diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
index 1acf7bdc60..e927dfee72 100644
--- a/.github/workflows/checks.yml
+++ b/.github/workflows/checks.yml
@@ -54,6 +54,12 @@ jobs:
         run: bun scripts/lint/no-unauth-routes.ts
       - name: Check unsafe type casts
         run: bun check:casts:strict
+      - name: Check for duplicate @packrat/utils implementations
+        run: bun check:utils
+      - name: Check @packrat/utils provenance manifest
+        run: bun check:provenance:strict
+      - name: Check code duplication (jscpd)
+        run: bun check:duplication
       - name: Check types
         run: bun check-types
       - name: Run Expo Doctor
diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
new file mode 100644
index 0000000000..bcd1b7a05a
--- /dev/null
+++ b/.github/workflows/coverage.yml
@@ -0,0 +1,289 @@
+name: Coverage
+
+on:
+  push:
+    branches: ["main", "development"]
+    paths:
+      - "package.json"
+      - "bun.lock"
+      - "apps/**"
+      - "packages/**"
+      - "scripts/lint/coverage-ratchet.ts"
+      - "scripts/lint/coverage-baseline-update.ts"
+      - "scripts/lint/no-weak-assertions.ts"
+      - "scripts/vitest.config.ts"
+      - "coverage-baselines.json"
+      - ".github/workflows/coverage.yml"
+  pull_request:
+    branches: ["**"]
+    paths:
+      - "package.json"
+      - "bun.lock"
+      - "apps/**"
+      - "packages/**"
+      - "scripts/lint/coverage-ratchet.ts"
+      - "scripts/lint/coverage-baseline-update.ts"
+      - "scripts/lint/no-weak-assertions.ts"
+      - "scripts/vitest.config.ts"
+      - "coverage-baselines.json"
+      - ".github/workflows/coverage.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write       # for baseline auto-commit on main
+  pull-requests: write  # for vitest-coverage-report-action comments
+
+jobs:
+  # One coverage run per tracked workspace. Uploads the coverage-summary.json
+  # as an artifact for the ratchet job to aggregate.
+  coverage:
+    name: Coverage (${{ matrix.name }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # `summary_path` / `final_path` are repo-relative (used by artifact
+          # upload + ratchet restore). `summary_relative` / `final_relative`
+          # are relative to `working_directory` (used by the coverage report
+          # action, which joins them with working_directory internally).
+          - name: packages/api
+            artifact_slug: packages-api
+            test_command: bun run --cwd packages/api test:unit:coverage
+            summary_path: packages/api/coverage/unit/coverage-summary.json
+            final_path: packages/api/coverage/unit/coverage-final.json
+            summary_relative: ./coverage/unit/coverage-summary.json
+            final_relative: ./coverage/unit/coverage-final.json
+            vite_config_path: ./vitest.unit.config.ts
+            working_directory: ./packages/api
+          - name: apps/expo
+            artifact_slug: apps-expo
+            test_command: bun run --cwd apps/expo test:coverage
+            summary_path: apps/expo/coverage/unit/coverage-summary.json
+            final_path: apps/expo/coverage/unit/coverage-final.json
+            summary_relative: ./coverage/unit/coverage-summary.json
+            final_relative: ./coverage/unit/coverage-final.json
+            vite_config_path: ./vitest.config.ts
+            working_directory: ./apps/expo
+          - name: packages/mcp
+            artifact_slug: packages-mcp
+            test_command: bun run --cwd packages/mcp test --coverage
+            summary_path: packages/mcp/coverage/coverage-summary.json
+            final_path: packages/mcp/coverage/coverage-final.json
+            summary_relative: ./coverage/coverage-summary.json
+            final_relative: ./coverage/coverage-final.json
+            vite_config_path: ./vitest.config.ts
+            working_directory: ./packages/mcp
+          - name: packages/analytics
+            artifact_slug: packages-analytics
+            test_command: bun run --cwd packages/analytics test --coverage
+            summary_path: packages/analytics/coverage/coverage-summary.json
+            final_path: packages/analytics/coverage/coverage-final.json
+            summary_relative: ./coverage/coverage-summary.json
+            final_relative: ./coverage/coverage-final.json
+            vite_config_path: ./vitest.config.ts
+            working_directory: ./packages/analytics
+          - name: packages/overpass
+            artifact_slug: packages-overpass
+            test_command: bun run --cwd packages/overpass test --coverage
+            summary_path: packages/overpass/coverage/coverage-summary.json
+            final_path: packages/overpass/coverage/coverage-final.json
+            summary_relative: ./coverage/coverage-summary.json
+            final_relative: ./coverage/coverage-final.json
+            vite_config_path: ./vitest.config.ts
+            working_directory: ./packages/overpass
+          - name: packages/units
+            artifact_slug: packages-units
+            test_command: bun run --cwd packages/units test --coverage
+            summary_path: packages/units/coverage/coverage-summary.json
+            final_path: packages/units/coverage/coverage-final.json
+            summary_relative: ./coverage/coverage-summary.json
+            final_relative: ./coverage/coverage-final.json
+            vite_config_path: ./vitest.config.ts
+            working_directory: ./packages/units
+          - name: packages/utils
+            artifact_slug: packages-utils
+            test_command: bun run --cwd packages/utils test --coverage
+            summary_path: packages/utils/coverage/coverage-summary.json
+            final_path: packages/utils/coverage/coverage-final.json
+            summary_relative: ./coverage/coverage-summary.json
+            final_relative: ./coverage/coverage-final.json
+            vite_config_path: ./vitest.config.ts
+            working_directory: ./packages/utils
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        env:
+          PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN: ${{ secrets.PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN }}
+        run: bun install --frozen-lockfile
+
+      - name: Run coverage for ${{ matrix.name }}
+        run: ${{ matrix.test_command }}
+
+      - name: Report coverage on PR
+        if: always() && github.event_name == 'pull_request'
+        uses: davelosert/vitest-coverage-report-action@v2
+        with:
+          name: ${{ matrix.name }}
+          json-summary-path: ${{ matrix.summary_relative }}
+          json-final-path: ${{ matrix.final_relative }}
+          vite-config-path: ${{ matrix.vite_config_path }}
+          working-directory: ${{ matrix.working_directory }}
+
+      - name: Upload coverage summary artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-summary-${{ matrix.artifact_slug }}
+          path: ${{ matrix.summary_path }}
+          if-no-files-found: error
+          retention-days: 7
+
+  # Aggregate every workspace's coverage-summary.json and run the ratchet.
+  # Fails the workflow if any workspace dropped below its baseline.
+  ratchet:
+    name: Coverage Ratchet
+    runs-on: ubuntu-latest
+    needs: coverage
+    if: always()
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        env:
+          PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN: ${{ secrets.PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN }}
+        run: bun install --frozen-lockfile
+
+      - name: Download all coverage summaries
+        uses: actions/download-artifact@v4
+        with:
+          pattern: coverage-summary-*
+          path: artifacts
+
+      - name: Restore summaries to their workspace paths
+        run: |
+          set -euo pipefail
+          # Each artifact arrives as artifacts/coverage-summary-<slug>/<path-without-leading-dir>
+          # actions/download-artifact@v4 unzips a single-file artifact into a directory
+          # named after the artifact, preserving the source file's basename.
+          # Copy each back to its expected location so coverage-baselines.json's
+          # summaryPath entries resolve.
+          declare -A targets=(
+            [packages-api]=packages/api/coverage/unit/coverage-summary.json
+            [apps-expo]=apps/expo/coverage/unit/coverage-summary.json
+            [packages-mcp]=packages/mcp/coverage/coverage-summary.json
+            [packages-analytics]=packages/analytics/coverage/coverage-summary.json
+            [packages-overpass]=packages/overpass/coverage/coverage-summary.json
+            [packages-units]=packages/units/coverage/coverage-summary.json
+          )
+          for slug in "${!targets[@]}"; do
+            target="${targets[$slug]}"
+            src_dir="artifacts/coverage-summary-${slug}"
+            if [ ! -d "$src_dir" ]; then
+              echo "::warning::missing artifact for $slug — coverage job may have failed"
+              continue
+            fi
+            mkdir -p "$(dirname "$target")"
+            # Find the single JSON file inside (path may be flat or preserved).
+            src_file=$(find "$src_dir" -name 'coverage-summary.json' | head -n1)
+            if [ -z "$src_file" ]; then
+              echo "::warning::no coverage-summary.json inside artifacts/coverage-summary-${slug}"
+              continue
+            fi
+            cp "$src_file" "$target"
+            echo "restored $slug → $target"
+          done
+
+      - name: Run coverage ratchet
+        run: bun check:coverage
+
+  # On a green push to main, auto-bump coverage-baselines.json upward.
+  # Never runs on PRs — PRs cannot edit the baseline file silently.
+  bump-baseline:
+    name: Bump Coverage Baselines
+    runs-on: ubuntu-latest
+    needs: ratchet
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # Need full token to push the auto-commit back to main.
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        env:
+          PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN: ${{ secrets.PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN }}
+        run: bun install --frozen-lockfile
+
+      - name: Download all coverage summaries
+        uses: actions/download-artifact@v4
+        with:
+          pattern: coverage-summary-*
+          path: artifacts
+
+      - name: Restore summaries to their workspace paths
+        run: |
+          set -euo pipefail
+          declare -A targets=(
+            [packages-api]=packages/api/coverage/unit/coverage-summary.json
+            [apps-expo]=apps/expo/coverage/unit/coverage-summary.json
+            [packages-mcp]=packages/mcp/coverage/coverage-summary.json
+            [packages-analytics]=packages/analytics/coverage/coverage-summary.json
+            [packages-overpass]=packages/overpass/coverage/coverage-summary.json
+            [packages-units]=packages/units/coverage/coverage-summary.json
+          )
+          for slug in "${!targets[@]}"; do
+            target="${targets[$slug]}"
+            src_dir="artifacts/coverage-summary-${slug}"
+            if [ ! -d "$src_dir" ]; then
+              continue
+            fi
+            mkdir -p "$(dirname "$target")"
+            src_file=$(find "$src_dir" -name 'coverage-summary.json' | head -n1)
+            if [ -n "$src_file" ]; then
+              cp "$src_file" "$target"
+            fi
+          done
+
+      - name: Compute baseline updates
+        run: bun check:coverage:update
+
+      - name: Commit baseline updates
+        uses: stefanzweifel/git-auto-commit-action@v6
+        with:
+          commit_message: "chore(coverage): bump baselines after green main"
+          file_pattern: coverage-baselines.json
+
+  # The scripts test suite — verifies the ratchet and assertion-lint analyzers
+  # themselves on every PR that touches them or their tests.
+  scripts-tests:
+    name: Scripts Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - name: Install dependencies
+        env:
+          PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN: ${{ secrets.PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN }}
+        run: bun install --frozen-lockfile
+      - name: Run scripts test suite
+        run: bun test:scripts
diff --git a/.github/workflows/eas-update.yml b/.github/workflows/eas-update.yml
index 5ccf9ed910..4a9c9c584b 100644
--- a/.github/workflows/eas-update.yml
+++ b/.github/workflows/eas-update.yml
@@ -8,6 +8,9 @@ on:
         required: false
         type: string
 
+permissions:
+  contents: read
+
 jobs:
   update:
     name: Publish EAS Update
diff --git a/.github/workflows/unit-tests.yml b/.github/workflows/unit-tests.yml
deleted file mode 100644
index 3faee06299..0000000000
--- a/.github/workflows/unit-tests.yml
+++ /dev/null
@@ -1,99 +0,0 @@
-name: Unit Tests
-
-on:
-  push:
-    branches: ["main", "development"]
-    paths:
-      - "package.json"
-      - "bun.lock"
-      - "packages/api/src/**"
-      - "packages/api/package.json"
-      - "packages/api/vitest.unit.config.ts"
-      - "apps/expo/package.json"
-      - "apps/expo/vitest.config.ts"
-      - "apps/expo/utils/**"
-      - "apps/expo/lib/utils/**"
-      - "apps/expo/features/**/utils/**"
-      - ".github/workflows/unit-tests.yml"
-  pull_request:
-    branches: ["**"]
-    paths:
-      - "package.json"
-      - "bun.lock"
-      - "packages/api/src/**"
-      - "packages/api/package.json"
-      - "packages/api/vitest.unit.config.ts"
-      - "apps/expo/package.json"
-      - "apps/expo/vitest.config.ts"
-      - "apps/expo/utils/**"
-      - "apps/expo/lib/utils/**"
-      - "apps/expo/features/**/utils/**"
-      - ".github/workflows/unit-tests.yml"
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-  pull-requests: write
-
-jobs:
-  api-unit-tests:
-    name: API Unit Tests
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v6
-
-      - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Install dependencies
-        env:
-          PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN: ${{ secrets.PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN }}
-        run: bun install --frozen-lockfile
-        
-      - name: Run API unit tests
-        run: bun run --cwd packages/api test:unit:coverage
-        
-      - name: Report API coverage
-        if: always()
-        uses: davelosert/vitest-coverage-report-action@v2
-        with:
-          name: API Unit Tests Coverage
-          json-summary-path: ./coverage/unit/coverage-summary.json
-          json-final-path: ./coverage/unit/coverage-final.json
-          vite-config-path: ./vitest.unit.config.ts
-          working-directory: ./packages/api
-
-  expo-unit-tests:
-    name: Expo Unit Tests
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v6
-
-      - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Install dependencies
-        env:
-          PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN: ${{ secrets.PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN }}
-        run: bun install --frozen-lockfile
-        
-      - name: Run Expo unit tests
-        run: bun run --cwd apps/expo test:coverage
-        
-      - name: Report Expo coverage
-        if: always()
-        uses: davelosert/vitest-coverage-report-action@v2
-        with:
-          name: Expo Unit Tests Coverage
-          json-summary-path: ./coverage/unit/coverage-summary.json
-          json-final-path: ./coverage/unit/coverage-final.json
-          vite-config-path: ./vitest.config.ts
-          working-directory: ./apps/expo
diff --git a/.jscpd.json b/.jscpd.json
new file mode 100644
index 0000000000..611a5051aa
--- /dev/null
+++ b/.jscpd.json
@@ -0,0 +1,26 @@
+{
+  "threshold": 7,
+  "minTokens": 50,
+  "absolute": false,
+  "gitignore": true,
+  "reporters": ["console"],
+  "format": ["typescript", "tsx"],
+  "ignore": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/.expo/**",
+    "**/.wrangler/**",
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.spec.ts",
+    "**/*.spec.tsx",
+    "**/*.gen.ts",
+    "**/src/codegen/**",
+    "**/drizzle/**",
+    "**/coverage/**",
+    "**/ios/**",
+    "**/android/**"
+  ]
+}
diff --git a/CLAUDE.md b/CLAUDE.md
index be81d88ee7..ea6e0fabaa 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -43,9 +43,13 @@ bun format            # Biome format --write
 bun check             # Biome check (no auto-fix, CI mode)
 bun check-types       # tsc --noEmit
 
-# Testing
-bun test:api:unit     # API unit tests (Vitest + Cloudflare pool)
-bun test:expo         # Expo tests (Vitest)
+# Testing — see docs/testing.md for the full policy
+bun test:api:unit       # API unit tests (Vitest, Node env, deps mocked)
+bun test:expo           # Expo pure-TS tests (Vitest)
+bun test:mcp            # MCP package tests
+bun test:scripts        # scripts/lint analyzer tests (ratchet + assertion lint)
+bun check:coverage      # Coverage ratchet — fails on regression vs coverage-baselines.json
+bun lint:weak-assertions # Catches assertion-free tests, bare .toBeDefined / .toHaveBeenCalled, oversized snapshots
 
 # Dependencies
 bun install           # Install all workspaces (takes 120s+, never cancel)
@@ -56,6 +60,10 @@ bun fix:deps          # manypkg auto-fix dependency issues
 bun bump              # Bump monorepo version
 ```
 
+## Testing Policy (summary)
+
+PackRat enforces coverage at two layers: each workspace's `vitest.config.ts` declares per-metric thresholds (mostly 95%+; `packages/units` 100%, `packages/{analytics,overpass}` 80%), and a **coverage ratchet** (`bun check:coverage` against `coverage-baselines.json`) blocks any PR that lowers a workspace's coverage. An **assertion-strength lint** (`bun lint:weak-assertions`) flags coverage-theater patterns (assertion-free tests, bare `.toBeDefined()`, bare `.toHaveBeenCalled()`, oversized snapshots). `packages/api` integration tests still run (`api-tests.yml`) but are not coverage-counted — V8 instrumentation is unsupported under the Cloudflare Workers pool. Full policy and patterns: **`docs/testing.md`**.
+
 ## Code Style
 
 Enforced by **Biome 2.0** via lefthook pre-commit hook:
@@ -244,6 +252,24 @@ Defined in root `tsconfig.json`:
 - Migrations: Drizzle Kit (`drizzle-kit`)
 - Embeddings: pgvector with 1536 dimensions
 
+### Migration discipline (read before touching `packages/api/drizzle/`)
+
+1. **Always generate via drizzle-kit.** Edit `packages/api/src/db/schema.ts` (or `packages/db/src/schema.ts` for the shared workspace), then run from the API package:
+
+   ```bash
+   cd packages/api && bun run db:generate
+   ```
+
+   Drizzle-kit emits a random-name file like `0048_loud_squirrel_girl.sql`. That random name is fine — keep it. The naming convention here is "whatever drizzle-kit gives you."
+
+2. **Do not rename a generated migration file.** The `meta/_journal.json` `tag` field, the migration SQL filename, and the snapshot filename all encode the migration identity together. Renaming any one of them (even with corresponding journal edits) makes the migration look hand-authored and creates drift that future drizzle-kit operations can mis-handle.
+
+3. **Do not hand-edit `meta/_journal.json`, `meta/*_snapshot.json`, or the generated SQL.** If the generated migration is wrong, fix the schema, delete the bad migration + snapshot + journal entry, and regenerate. Do not patch around it.
+
+4. **Collapse additive changes into one migration when they ship together** — fewer snapshot files in the diff, easier to revert as a unit. Splitting only makes sense when migrations need to land in separate releases.
+
+5. **Verify after generating.** Run `bunx drizzle-kit check` from `packages/api/` — it validates the snapshot chain is internally consistent. Run before pushing.
+
 ## EAS Build Profiles
 
 | Profile | Use | Distribution |
diff --git a/README.md b/README.md
index d076380f6f..256b317f8f 100644
--- a/README.md
+++ b/README.md
@@ -107,7 +107,7 @@ So pack your bags, grab your friends, and get ready for your next adventure with
 
 [![view - Documentation](https://img.shields.io/badge/view-Documentation-blue?style=for-the-badge)](/docs/ "Go to project documentation")
 
-[![view - Testing Guide](https://img.shields.io/badge/view-Testing_Guide-green?style=for-the-badge)](/TESTING.md "Go to testing documentation")
+[![view - Testing Guide](https://img.shields.io/badge/view-Testing_Guide-green?style=for-the-badge)](/docs/testing.md "Go to testing documentation")
 
 </div>
 
diff --git a/TESTING.md b/TESTING.md
deleted file mode 100644
index 74b5939779..0000000000
--- a/TESTING.md
+++ /dev/null
@@ -1,453 +0,0 @@
-# Unit Testing Guide for PackRat
-
-This document outlines testing standards and patterns used in the PackRat codebase.
-
-## Overview
-
-PackRat uses **Vitest** as its primary testing framework across both API and Expo layers. This guide demonstrates the patterns established in our unit test suite.
-
----
-
-## Testing Infrastructure
-
-### API Layer (packages/api)
-
-**Configuration Files:**
-- `vitest.config.ts` - Full integration tests with PostgreSQL + Cloudflare Workers
-- `vitest.unit.config.ts` - Pure unit tests with mocked dependencies (recommended for most unit tests)
-
-**Commands:**
-```bash
-# From packages/api
-bun test          # Full integration tests (requires Docker)
-bun test:unit     # Unit tests only (no database)
-bun test:unit:coverage  # Unit tests with coverage report
-
-# From monorepo root
-bun test:api:unit
-```
-
-**Coverage Configuration:**
-- **Provider:** v8
-- **Reports:** text, lcov, html
-- **Directory:** `packages/api/coverage/unit/`
-- **Target:** 80%+ coverage for critical paths
-
-### Expo Layer (apps/expo)
-
-**Configuration File:**
-- `vitest.config.ts` - Node environment for pure utility functions
-
-**Commands:**
-```bash
-# From apps/expo
-bun test              # Run utility tests
-bun test:coverage     # With coverage report
-
-# From monorepo root
-bun test:expo
-```
-
-**Coverage Configuration:**
-- **Provider:** v8
-- **Reports:** text, lcov, html
-- **Directory:** `apps/expo/coverage/unit/`
-- **Target:** 75%+ coverage for utility functions
-
-**Note:** Currently limited to pure utility functions. React Native hooks and components require additional setup (e.g., @testing-library/react-native).
-
----
-
-## Test Patterns
-
-### Pattern 1: Service Tests with Mocked Dependencies
-
-**Example:** `/packages/api/src/services/__tests__/catalogService.test.ts`
-
-```typescript
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { CatalogService } from '../catalogService';
-import * as embeddingService from '@packrat/api/services/embeddingService';
-
-// Module-level mocks (hoisted)
-vi.mock('@packrat/api/db', () => ({
-  createDb: vi.fn(),
-  createDbClient: vi.fn(),
-}));
-
-vi.mock('@packrat/api/services/embeddingService', () => ({
-  generateEmbedding: vi.fn(),
-  generateManyEmbeddings: vi.fn(),
-}));
-
-// Test suite
-describe('CatalogService', () => {
-  let service: CatalogService;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    service = new CatalogService(makeEnv(), false);
-  });
-
-  describe('vectorSearch', () => {
-    beforeEach(() => {
-      vi.mocked(embeddingService.generateEmbedding)
-        .mockResolvedValue(new Array(1536).fill(0.1));
-    });
-
-    it('returns empty result for empty query string', async () => {
-      const result = await service.vectorSearch('', 10, 0);
-
-      expect(result).toEqual({
-        items: [],
-        total: 0,
-        limit: 10,
-        offset: 0,
-        nextOffset: 10,
-      });
-      expect(embeddingService.generateEmbedding).not.toHaveBeenCalled();
-    });
-  });
-});
-```
-
-**Key Points:**
-- Use `vi.mock()` for module-level mocks (these are hoisted)
-- Import mocked modules for type-safe access (e.g., `import * as embeddingService`)
-- Use `vi.mocked()` for type-safe mock assertions
-- Clear mocks in `beforeEach()` for test isolation
-
-### Pattern 2: API Service Tests with Fetch Mocking
-
-**Example:** `/packages/api/src/services/__tests__/weatherService.test.ts`
-
-```typescript
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { WeatherService } from '../weatherService';
-
-describe('WeatherService', () => {
-  let service: WeatherService;
-  let fetchMock: ReturnType<typeof vi.fn>;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    mockContext = makeMockContext();
-    service = new WeatherService(mockContext);
-
-    // Mock global fetch
-    fetchMock = vi.fn();
-    global.fetch = fetchMock;
-  });
-
-  describe('getWeatherForLocation', () => {
-    it('returns formatted weather data for valid location', async () => {
-      const mockResponse = {
-        main: { temp: 72.5, humidity: 65 },
-        weather: [{ main: 'Clear' }],
-        wind: { speed: 8.3 },
-      };
-      
-      fetchMock.mockResolvedValue({
-        ok: true,
-        json: async () => mockResponse,
-      });
-
-      const result = await service.getWeatherForLocation('San Francisco');
-
-      expect(result.temperature).toBe(73); // Rounded
-      expect(result.conditions).toBe('Clear');
-    });
-  });
-});
-```
-
-**Key Points:**
-- Mock `global.fetch` in `beforeEach()` for fresh state
-- Use `mockResolvedValue` for successful responses
-- Test both success and error paths
-- Verify API was called with correct parameters
-
-### Pattern 3: Pure Utility Function Tests
-
-**Example:** `/apps/expo/features/packs/utils/__tests__/convertToGrams.test.ts`
-
-```typescript
-import { describe, expect, it } from 'vitest';
-import { convertToGrams } from '../convertToGrams';
-
-describe('convertToGrams', () => {
-  describe('metric conversions', () => {
-    it('returns same value for grams', () => {
-      expect(convertToGrams(100, 'g')).toBe(100);
-      expect(convertToGrams(0, 'g')).toBe(0);
-      expect(convertToGrams(1, 'g')).toBe(1);
-    });
-
-    it('converts kilograms to grams correctly', () => {
-      expect(convertToGrams(1, 'kg')).toBe(1000);
-      expect(convertToGrams(2.5, 'kg')).toBe(2500);
-    });
-  });
-
-  describe('edge cases', () => {
-    it('handles zero weight', () => {
-      expect(convertToGrams(0, 'kg')).toBe(0);
-    });
-
-    it('returns original value for unknown units', () => {
-      expect(convertToGrams(100, 'invalid')).toBe(100);
-    });
-  });
-});
-```
-
-**Key Points:**
-- No mocking needed for pure functions
-- Group related tests with nested `describe()` blocks
-- Test edge cases (zero, negative, invalid input)
-- Use `toBe()` for exact values, `toBeCloseTo()` for floating point
-- Test real-world scenarios to ensure practical correctness
-
----
-
-## Best Practices
-
-### 1. Test Organization
-
-```typescript
-describe('ServiceName', () => {
-  // Setup
-  let service: ServiceName;
-
-  beforeEach(() => {
-    // Reset mocks and create fresh instances
-  });
-
-  describe('methodName', () => {
-    // Group related tests
-
-    describe('when condition', () => {
-      // Nested context-specific tests
-    });
-  });
-});
-```
-
-### 2. Mock Isolation
-
-```typescript
-beforeEach(() => {
-  vi.clearAllMocks();  // Reset all mock state
-  // Re-create service instances
-  // Set default mock return values
-});
-```
-
-### 3. Input Validation Tests
-
-Always test:
-- ✅ Valid inputs (happy path)
-- ✅ Invalid inputs (error paths)
-- ✅ Edge cases (empty, null, undefined, zero, negative)
-- ✅ Boundary conditions (min/max values)
-
-### 4. Floating Point Comparisons
-
-```typescript
-// ❌ Don't use exact equality for floats
-expect(convertToGrams(1, 'oz')).toBe(28.3495);
-
-// ✅ Use toBeCloseTo() with appropriate precision
-expect(convertToGrams(1, 'oz')).toBeCloseTo(28.3495, 4);
-```
-
-### 5. Async Testing
-
-```typescript
-// Test async functions
-it('handles async operation', async () => {
-  const result = await service.fetchData();
-  expect(result).toBeDefined();
-});
-
-// Test error handling
-it('throws on invalid input', async () => {
-  await expect(service.process(null)).rejects.toThrow('Invalid input');
-});
-```
-
-### 6. Mock Configuration Patterns
-
-```typescript
-// Default behavior for all tests in describe block
-beforeEach(() => {
-  mockFunction.mockResolvedValue(defaultValue);
-});
-
-// Override for specific test
-it('handles special case', async () => {
-  mockFunction.mockResolvedValueOnce(specialValue);
-  // ...
-});
-```
-
----
-
-## Coverage Guidelines
-
-### What to Test (Priority Order)
-
-1. **Critical Business Logic**
-   - Payment processing
-   - User authentication
-   - Data validation
-   - Core algorithms
-
-2. **Public APIs**
-   - All exported functions
-   - All route handlers
-   - Service methods
-
-3. **Edge Cases**
-   - Null/undefined handling
-   - Empty collections
-   - Boundary values
-   - Invalid inputs
-
-4. **Error Paths**
-   - Exception handling
-   - Validation errors
-   - Network failures
-   - Database errors
-
-### What NOT to Test
-
-- Third-party library internals
-- Simple getters/setters with no logic
-- Generated code
-- Configuration files
-- Type definitions
-
----
-
-## Running Tests in CI
-
-### API Tests (GitHub Actions)
-
-```yaml
-- name: Run API Unit Tests
-  run: |
-    cd packages/api
-    bun test:unit --coverage
-```
-
-### Expo Tests (GitHub Actions)
-
-```yaml
-- name: Run Expo Tests
-  run: |
-    cd apps/expo
-    bun test --coverage
-```
-
-### Coverage Reports
-
-Coverage reports are generated in:
-- API: `packages/api/coverage/unit/`
-- Expo: `apps/expo/coverage/unit/`
-
-Open `index.html` to view detailed coverage reports locally.
-
----
-
-## Troubleshooting
-
-### "Cannot access before initialization" Error
-
-**Problem:** Trying to use a variable declared after `vi.mock()`
-
-**Solution:** Import the mocked module after the mock declaration
-
-```typescript
-// ❌ Won't work - hoisting issue
-const mockFn = vi.fn();
-vi.mock('./module', () => ({ fn: mockFn }));
-
-// ✅ Works - import after mock
-vi.mock('./module', () => ({ fn: vi.fn() }));
-import * as module from './module';
-// Use vi.mocked(module.fn) in tests
-```
-
-### Mock Not Resetting Between Tests
-
-**Problem:** Mock state persists across tests
-
-**Solution:** Always call `vi.clearAllMocks()` in `beforeEach()`
-
-```typescript
-beforeEach(() => {
-  vi.clearAllMocks();  // Resets all mock history and implementations
-});
-```
-
-### Floating Point Precision Errors
-
-**Problem:** `expect(0.1 + 0.2).toBe(0.3)` fails due to floating point arithmetic
-
-**Solution:** Use `toBeCloseTo()` with appropriate precision
-
-```typescript
-expect(0.1 + 0.2).toBeCloseTo(0.3, 10);  // 10 decimal places
-```
-
----
-
-## Resources
-
-- [Vitest Documentation](https://vitest.dev/)
-- [Testing Best Practices](https://testingjavascript.com/)
-- [Mocking in Vitest](https://vitest.dev/guide/mocking.html)
-- [Coverage Configuration](https://vitest.dev/guide/coverage.html)
-
----
-
-## Test Statistics (Current)
-
-### API Layer
-- **Test Files:** 8
-- **Tests:** 101 passing
-- **Coverage Target:** 80%+
-
-### Expo Layer
-- **Test Files:** 8  
-- **Tests:** 93 passing (excluding pre-existing failures)
-- **Coverage Target:** 75%+
-
-### Recent Additions
-- ✅ `CatalogService` - Vector search, batch operations, input validation
-- ✅ `WeatherService` - API calls, error handling, data transformations
-- ✅ `convertToGrams` - Unit conversions, edge cases, real-world scenarios
-- ✅ `convertFromGrams` - Reverse conversions, precision handling
-
----
-
-## Contributing
-
-When adding new features:
-
-1. **Write tests first** (TDD approach) or alongside implementation
-2. **Aim for 80%+ coverage** for new code
-3. **Test all code paths** including error cases
-4. **Use existing patterns** from this guide
-5. **Update this document** if introducing new patterns
-
-When fixing bugs:
-
-1. **Write a failing test** that reproduces the bug
-2. **Fix the bug** until the test passes
-3. **Verify** no regressions with full test suite
-
----
-
-*Last Updated: 2026-04-01*
diff --git a/apps/admin/components/analytics/catalog-analytics.tsx b/apps/admin/components/analytics/catalog-analytics.tsx
index 3ca0fa8461..f55c1599f0 100644
--- a/apps/admin/components/analytics/catalog-analytics.tsx
+++ b/apps/admin/components/analytics/catalog-analytics.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { safeJsonStringify } from '@packrat/utils';
 import { Badge } from '@packrat/web-ui/components/badge';
 import { Button } from '@packrat/web-ui/components/button';
 import {
@@ -146,7 +147,7 @@ function EtlJobFailuresDialog({ jobId, totalInvalid }: { jobId: string; totalInv
                             raw data
                           </summary>
                           <pre className="mt-1 text-xs whitespace-pre-wrap break-all">
-                            {JSON.stringify(s.rawData, null, 2)}
+                            {safeJsonStringify(s.rawData, null, 2)}
                           </pre>
                         </details>
                       )}
diff --git a/apps/admin/components/raw-object-dialog.tsx b/apps/admin/components/raw-object-dialog.tsx
index 023aa8922c..da6dece999 100644
--- a/apps/admin/components/raw-object-dialog.tsx
+++ b/apps/admin/components/raw-object-dialog.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { safeJsonStringify } from '@packrat/utils';
 import { Button } from '@packrat/web-ui/components/button';
 import {
   Dialog,
@@ -36,7 +37,7 @@ export function RawObjectDialog({ label, data }: RawObjectDialogProps) {
         </DialogHeader>
         <div className="max-h-[60vh] overflow-auto rounded-md bg-muted p-4">
           <pre className="text-xs leading-relaxed text-foreground whitespace-pre-wrap break-all">
-            {JSON.stringify(data, null, 2)}
+            {safeJsonStringify(data, null, 2)}
           </pre>
         </div>
       </DialogContent>
diff --git a/apps/admin/package.json b/apps/admin/package.json
index a1e728920c..f6b2d1c46f 100644
--- a/apps/admin/package.json
+++ b/apps/admin/package.json
@@ -1,6 +1,6 @@
 {
   "name": "packrat-admin-app",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "scripts": {
     "build": "next build",
@@ -17,6 +17,7 @@
     "@packrat/app": "workspace:*",
     "@packrat/guards": "workspace:*",
     "@packrat/schemas": "workspace:*",
+    "@packrat/utils": "workspace:*",
     "@packrat/web-ui": "workspace:*",
     "@radix-ui/react-alert-dialog": "catalog:",
     "@radix-ui/react-avatar": "catalog:",
diff --git a/apps/expo/app.config.ts b/apps/expo/app.config.ts
index 478019087e..daacf21f60 100644
--- a/apps/expo/app.config.ts
+++ b/apps/expo/app.config.ts
@@ -37,7 +37,7 @@ export default (): ExpoConfig =>
     {
       name: getAppName(),
       slug: 'packrat',
-      version: '2.0.26',
+      version: '2.0.27',
       scheme: 'packrat',
       web: {
         bundler: 'metro',
diff --git a/apps/expo/atoms/atomWithAsyncStorage.ts b/apps/expo/atoms/atomWithAsyncStorage.ts
index 49060418e7..aa9be68b42 100644
--- a/apps/expo/atoms/atomWithAsyncStorage.ts
+++ b/apps/expo/atoms/atomWithAsyncStorage.ts
@@ -1,4 +1,5 @@
 import { isFunction } from '@packrat/guards';
+import { safeJsonParse, safeJsonStringify } from '@packrat/utils';
 import AsyncStorage from '@react-native-async-storage/async-storage';
 import { atom } from 'jotai';
 
@@ -14,7 +15,7 @@ export const atomWithAsyncStorage = <T>({
   baseAtom.onMount = (setValue) => {
     (async () => {
       const item = await AsyncStorage.getItem(key);
-      setValue(item ? JSON.parse(item) : initialValue);
+      setValue(item ? safeJsonParse<T>(item) : initialValue);
     })();
   };
 
@@ -23,7 +24,7 @@ export const atomWithAsyncStorage = <T>({
     (get, set, update) => {
       const nextValue = isFunction(update) ? update(get(baseAtom)) : update;
       set(baseAtom, nextValue);
-      AsyncStorage.setItem(key, JSON.stringify(nextValue));
+      AsyncStorage.setItem(key, safeJsonStringify(nextValue));
     },
   );
 
diff --git a/apps/expo/atoms/atomWithKvStorage.ts b/apps/expo/atoms/atomWithKvStorage.ts
index 886827e7d7..7ffaafadb1 100644
--- a/apps/expo/atoms/atomWithKvStorage.ts
+++ b/apps/expo/atoms/atomWithKvStorage.ts
@@ -1,4 +1,5 @@
 import { isFunction } from '@packrat/guards';
+import { safeJsonParse, safeJsonStringify } from '@packrat/utils';
 import Storage from 'expo-sqlite/kv-store';
 import { atom } from 'jotai';
 
@@ -8,7 +9,7 @@ export const atomWithKvStorage = <T>({ key, initialValue }: { key: string; initi
   baseAtom.onMount = (setValue) => {
     (async () => {
       const item = await Storage.getItem(key);
-      setValue(item ? JSON.parse(item) : initialValue);
+      setValue(item ? safeJsonParse<T>(item) : initialValue);
     })();
   };
 
@@ -19,7 +20,7 @@ export const atomWithKvStorage = <T>({ key, initialValue }: { key: string; initi
 
       set(baseAtom, nextValue);
 
-      Storage.setItem(key, JSON.stringify(nextValue));
+      Storage.setItem(key, safeJsonStringify(nextValue));
     },
   );
 
diff --git a/apps/expo/atoms/atomWithSecureStorage.ts b/apps/expo/atoms/atomWithSecureStorage.ts
index da3c3ddcfe..043e9b24a4 100644
--- a/apps/expo/atoms/atomWithSecureStorage.ts
+++ b/apps/expo/atoms/atomWithSecureStorage.ts
@@ -1,4 +1,5 @@
 import { isFunction } from '@packrat/guards';
+import { safeJsonParse, safeJsonStringify } from '@packrat/utils';
 import * as SecureStore from 'expo-app/lib/secureStore';
 import { atom } from 'jotai';
 
@@ -14,7 +15,7 @@ export const atomWithSecureStorage = <T>({
   baseAtom.onMount = (setValue) => {
     (async () => {
       const item = await SecureStore.getItemAsync(key);
-      setValue(item ? JSON.parse(item) : initialValue);
+      setValue(item ? safeJsonParse<T>(item) : initialValue);
     })();
   };
 
@@ -23,7 +24,7 @@ export const atomWithSecureStorage = <T>({
     (get, set, update) => {
       const nextValue = isFunction(update) ? update(get(baseAtom)) : update;
       set(baseAtom, nextValue);
-      SecureStore.setItemAsync(key, JSON.stringify(nextValue));
+      SecureStore.setItemAsync(key, safeJsonStringify(nextValue));
     },
   );
 
diff --git a/apps/expo/atoms/atomWithSecureStorage.web.ts b/apps/expo/atoms/atomWithSecureStorage.web.ts
index f54b9176f3..d851a14ed3 100644
--- a/apps/expo/atoms/atomWithSecureStorage.web.ts
+++ b/apps/expo/atoms/atomWithSecureStorage.web.ts
@@ -1,4 +1,5 @@
 import { isFunction } from '@packrat/guards';
+import { safeJsonParse, safeJsonStringify } from '@packrat/utils';
 import { atom } from 'jotai';
 
 /**
@@ -19,7 +20,7 @@ export const atomWithSecureStorage = <T>({
   baseAtom.onMount = (setValue) => {
     try {
       const item = localStorage.getItem(key);
-      setValue(item !== null ? JSON.parse(item) : initialValue);
+      setValue(item !== null ? safeJsonParse<T>(item, { strict: true }) : initialValue);
     } catch {
       setValue(initialValue);
     }
@@ -31,7 +32,7 @@ export const atomWithSecureStorage = <T>({
       const nextValue = isFunction(update) ? (update as (prev: T) => T)(get(baseAtom)) : update;
       set(baseAtom, nextValue);
       try {
-        localStorage.setItem(key, JSON.stringify(nextValue));
+        localStorage.setItem(key, safeJsonStringify(nextValue));
       } catch {
         // Ignore storage errors
       }
diff --git a/apps/expo/features/ai/atoms/chatStorageAtoms.ts b/apps/expo/features/ai/atoms/chatStorageAtoms.ts
index 7c9a90a856..a6bbde5692 100644
--- a/apps/expo/features/ai/atoms/chatStorageAtoms.ts
+++ b/apps/expo/features/ai/atoms/chatStorageAtoms.ts
@@ -1,5 +1,6 @@
 import type { UIMessage } from '@ai-sdk/react';
 import { isObject, isString } from '@packrat/guards';
+import { safeJsonParse, safeJsonStringify } from '@packrat/utils';
 import AsyncStorage from '@react-native-async-storage/async-storage';
 
 export type ChatContext = {
@@ -64,7 +65,7 @@ export async function loadChatMessages(context: ChatContext): Promise<UIMessage[
     const stored = await AsyncStorage.getItem(key);
     if (!stored) return null;
 
-    const parsed = JSON.parse(stored);
+    const parsed = safeJsonParse(stored, { strict: true });
     if (!isValidMessageArray(parsed)) {
       console.warn('Invalid chat message format in storage, clearing');
       await AsyncStorage.removeItem(key);
@@ -91,7 +92,7 @@ export async function saveChatMessages({
 }): Promise<void> {
   try {
     const key = getChatStorageKey(context);
-    await AsyncStorage.setItem(key, JSON.stringify(messages));
+    await AsyncStorage.setItem(key, safeJsonStringify(messages));
   } catch (error) {
     console.error('Failed to save chat messages:', error);
   }
diff --git a/apps/expo/features/ai/components/ToolInvocationRenderer.tsx b/apps/expo/features/ai/components/ToolInvocationRenderer.tsx
index e3b8630816..e3135e0363 100644
--- a/apps/expo/features/ai/components/ToolInvocationRenderer.tsx
+++ b/apps/expo/features/ai/components/ToolInvocationRenderer.tsx
@@ -1,4 +1,5 @@
 import { isString } from '@packrat/guards';
+import { safeJsonParse } from '@packrat/utils';
 import type { ToolUIPart } from 'ai';
 import type { CatalogItemsTool } from './CatalogItemsGenerativeUI';
 import { CatalogItemsGenerativeUI } from './CatalogItemsGenerativeUI';
@@ -22,7 +23,7 @@ export function ToolInvocationRenderer({ toolInvocation }: ToolInvocationRendere
   // Normalize it here once so all GenUI components receive a plain object.
   const normalizedInvocation =
     toolInvocation.state === 'output-available' && isString(toolInvocation.output)
-      ? { ...toolInvocation, output: JSON.parse(toolInvocation.output) }
+      ? { ...toolInvocation, output: safeJsonParse(toolInvocation.output) }
       : toolInvocation;
 
   // safe-cast: each case branch narrows toolInvocation.type to the discriminant literal; the
diff --git a/apps/expo/features/ai/lib/CustomChatTransport.ts b/apps/expo/features/ai/lib/CustomChatTransport.ts
index de0392d0c1..25ed9af7db 100644
--- a/apps/expo/features/ai/lib/CustomChatTransport.ts
+++ b/apps/expo/features/ai/lib/CustomChatTransport.ts
@@ -1,5 +1,6 @@
 import type { UIMessage } from '@ai-sdk/react';
 import { isString } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import {
   type ChatRequestOptions,
   type ChatTransport,
@@ -64,7 +65,7 @@ export class CustomChatTransport implements ChatTransport<UIMessage> {
         if (error instanceof Error) {
           return error.message;
         }
-        return JSON.stringify(error);
+        return safeJsonStringify(error);
       },
     });
   }
diff --git a/apps/expo/features/ai/lib/appleModelWrapper.ts b/apps/expo/features/ai/lib/appleModelWrapper.ts
index 842cb1ddfd..b43c81b042 100644
--- a/apps/expo/features/ai/lib/appleModelWrapper.ts
+++ b/apps/expo/features/ai/lib/appleModelWrapper.ts
@@ -24,6 +24,7 @@
  */
 
 import { isString } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 
 // biome-ignore lint/suspicious/noExplicitAny: Apple model type is unknown at this layer
 type AnyModel = any;
@@ -96,7 +97,7 @@ export class AppleModelWrapper {
               toolCallId,
               toolName: part.toolName,
               // Apple may return input as an object; the spec requires a JSON string
-              input: isString(part.input) ? part.input : JSON.stringify(part.input),
+              input: isString(part.input) ? part.input : safeJsonStringify(part.input),
               providerExecuted: true,
             });
           } else if (part.type === 'tool-result') {
diff --git a/apps/expo/features/ai/lib/llamaToolsWrapper.ts b/apps/expo/features/ai/lib/llamaToolsWrapper.ts
index 28f9a8ca4a..efbc8de427 100644
--- a/apps/expo/features/ai/lib/llamaToolsWrapper.ts
+++ b/apps/expo/features/ai/lib/llamaToolsWrapper.ts
@@ -15,6 +15,7 @@
 
 import { generateId } from '@ai-sdk/provider-utils';
 import { isString } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import type { LlamaLanguageModel } from '@react-native-ai/llama';
 
 // Minimal structural slice of LanguageModelV2CallOptions we need
@@ -63,13 +64,13 @@ function toolResultOutputToString(output: any): string {
       return String(output.value ?? '');
     case 'json':
     case 'error-json':
-      return JSON.stringify(output.value);
+      return safeJsonStringify(output.value);
     case 'content':
       return (output.value ?? [])
         .map((p: { type: string; text?: string }) => (p.type === 'text' ? (p.text ?? '') : ''))
         .join('');
     default:
-      return JSON.stringify(output);
+      return safeJsonStringify(output);
   }
 }
 
@@ -114,7 +115,7 @@ function convertPromptToLlamaMessages(prompt: Prompt): LlamaMessage[] {
             id: p.toolCallId,
             function: {
               name: p.toolName,
-              arguments: isString(p.input) ? p.input : JSON.stringify(p.input),
+              arguments: isString(p.input) ? p.input : safeJsonStringify(p.input),
             },
           })),
         });
diff --git a/apps/expo/features/auth/hooks/useAuthActions.ts b/apps/expo/features/auth/hooks/useAuthActions.ts
index 6c95b74d2f..c4a1dd8653 100644
--- a/apps/expo/features/auth/hooks/useAuthActions.ts
+++ b/apps/expo/features/auth/hooks/useAuthActions.ts
@@ -1,4 +1,5 @@
 import { asBoolean, asString } from '@packrat/guards';
+import { safeJsonParse } from '@packrat/utils';
 import AsyncStorage from '@react-native-async-storage/async-storage';
 import {
   GoogleSignin,
@@ -27,7 +28,7 @@ import {
 
 function redirect(route: string) {
   try {
-    const parsedRoute: Href = JSON.parse(route);
+    const parsedRoute = safeJsonParse<Href>(route, { strict: true });
     return router.dismissTo(parsedRoute);
   } catch {
     router.dismissTo(route as Href); // safe-cast: Href = string | HrefObject; string literal branch failed JSON.parse so plain string is the correct type here
diff --git a/apps/expo/features/catalog/lib/normalizeDescription.ts b/apps/expo/features/catalog/lib/normalizeDescription.ts
index 9a6d68d035..8e939e3a51 100644
--- a/apps/expo/features/catalog/lib/normalizeDescription.ts
+++ b/apps/expo/features/catalog/lib/normalizeDescription.ts
@@ -1,3 +1,5 @@
+import { safeJsonParse } from '@packrat/utils';
+
 const DETAILS_ARRAY_RE = /^Details:\s*(\[[\s\S]*\])$/;
 
 export function normalizeDescription(description: string | null | undefined): string | null {
@@ -5,7 +7,7 @@ export function normalizeDescription(description: string | null | undefined): st
   const match = description.match(DETAILS_ARRAY_RE);
   if (match?.[1]) {
     try {
-      const items = JSON.parse(match[1]) as string[];
+      const items = safeJsonParse(match[1], { strict: true }) as string[];
       return items.join('. ');
     } catch {
       // fall through
diff --git a/apps/expo/features/catalog/types.ts b/apps/expo/features/catalog/types.ts
index 8b2e07e5a8..583f633c28 100644
--- a/apps/expo/features/catalog/types.ts
+++ b/apps/expo/features/catalog/types.ts
@@ -49,4 +49,5 @@ export interface CatalogItemInput {
   }>;
 }
 
-export type CatalogItemWithPackItemFields = CatalogItem & Partial<PackItemInput>;
+export type CatalogItemWithPackItemFields = CatalogItem &
+  Partial<Omit<PackItemInput, 'weight' | 'weightUnit'>>;
diff --git a/apps/expo/features/pack-templates/components/FeaturedPacksSection.tsx b/apps/expo/features/pack-templates/components/FeaturedPacksSection.tsx
index 71bce69524..420bb1d06c 100644
--- a/apps/expo/features/pack-templates/components/FeaturedPacksSection.tsx
+++ b/apps/expo/features/pack-templates/components/FeaturedPacksSection.tsx
@@ -1,8 +1,8 @@
+import { isArray } from '@packrat/guards';
 import { Text } from '@packrat/ui/nativewindui';
 import { WeightBadge } from 'expo-app/components/initial/WeightBadge';
 import { useTranslation } from 'expo-app/lib/hooks/useTranslation';
 import { useRouter } from 'expo-router';
-import { isArray } from 'radash';
 import { useMemo } from 'react';
 import { Image, Platform, Pressable, ScrollView, View } from 'react-native';
 import { usePackTemplates } from '../hooks';
diff --git a/apps/expo/features/trail-conditions/hooks/useTrailConditionReports.ts b/apps/expo/features/trail-conditions/hooks/useTrailConditionReports.ts
index 5ac2853fc0..3e80a03b66 100644
--- a/apps/expo/features/trail-conditions/hooks/useTrailConditionReports.ts
+++ b/apps/expo/features/trail-conditions/hooks/useTrailConditionReports.ts
@@ -1,4 +1,5 @@
 import { useSelector } from '@legendapp/state/react';
+import { safeJsonParse, safeJsonStringify } from '@packrat/utils';
 import AsyncStorage from '@react-native-async-storage/async-storage';
 import { useQuery } from '@tanstack/react-query';
 import { userStore } from 'expo-app/features/auth/store/user';
@@ -26,7 +27,7 @@ async function writeCachedReports({
   try {
     await AsyncStorage.setItem(
       cacheKey({ userId: opts.userId, trailName: opts.trailName }),
-      JSON.stringify(reports),
+      safeJsonStringify(reports),
     );
   } catch {
     // Best-effort — swallow write errors silently
@@ -43,7 +44,7 @@ async function readCachedReports(opts: {
       cacheKey({ userId: opts.userId, trailName: opts.trailName }),
     );
     // safe-cast: JSON.parse returns unknown; data was written as TrailConditionReport[] earlier
-    if (raw) return JSON.parse(raw) as TrailConditionReport[];
+    if (raw) return safeJsonParse(raw, { strict: true }) as TrailConditionReport[];
   } catch {
     // Corrupt or missing cache — ignore
   }
diff --git a/apps/expo/features/weather/screens/LocationSearchScreen.tsx b/apps/expo/features/weather/screens/LocationSearchScreen.tsx
index f0365f95a7..33ece35d33 100644
--- a/apps/expo/features/weather/screens/LocationSearchScreen.tsx
+++ b/apps/expo/features/weather/screens/LocationSearchScreen.tsx
@@ -1,4 +1,5 @@
 import { Text } from '@packrat/ui/nativewindui';
+import { safeJsonParse, safeJsonStringify } from '@packrat/utils';
 import AsyncStorage from '@react-native-async-storage/async-storage';
 import { Icon } from 'expo-app/components/Icon';
 import { SearchInput } from 'expo-app/components/SearchInput';
@@ -54,7 +55,7 @@ export default function LocationSearchScreen() {
       try {
         const storedSearches = await AsyncStorage.getItem(RECENT_SEARCHES_KEY);
         if (storedSearches) {
-          setRecentSearches(JSON.parse(storedSearches));
+          setRecentSearches(safeJsonParse<string[]>(storedSearches, { strict: true }));
         }
       } catch (err) {
         console.error('Error loading recent searches:', err);
@@ -76,14 +77,14 @@ export default function LocationSearchScreen() {
         ].slice(0, 5); // Keep only 5 most recent
 
         setRecentSearches(updatedSearches);
-        await AsyncStorage.setItem(RECENT_SEARCHES_KEY, JSON.stringify(updatedSearches));
+        await AsyncStorage.setItem(RECENT_SEARCHES_KEY, safeJsonStringify(updatedSearches));
         return;
       }
 
       // Add new search term to the beginning and limit to 5
       const updatedSearches = [searchTerm, ...recentSearches].slice(0, 5);
       setRecentSearches(updatedSearches);
-      await AsyncStorage.setItem(RECENT_SEARCHES_KEY, JSON.stringify(updatedSearches));
+      await AsyncStorage.setItem(RECENT_SEARCHES_KEY, safeJsonStringify(updatedSearches));
     } catch (err) {
       console.error('Error saving recent search:', err);
     }
diff --git a/apps/expo/lib/api/packrat.ts b/apps/expo/lib/api/packrat.ts
index 09d318ce2c..9f576e3ce5 100644
--- a/apps/expo/lib/api/packrat.ts
+++ b/apps/expo/lib/api/packrat.ts
@@ -1,5 +1,6 @@
 import { createApiClient } from '@packrat/api-client';
 import { fromZod } from '@packrat/guards';
+import { safeJsonParse } from '@packrat/utils';
 import { store } from 'expo-app/atoms/store';
 import { needsReauthAtom } from 'expo-app/features/auth/atoms/authAtoms';
 import { getApiBaseUrl } from 'expo-app/lib/api/getBaseUrl';
@@ -17,7 +18,7 @@ const CookieStoreSchema = z.record(z.object({ value: z.string() }));
 // HTTPS servers (remote dev/prod) prefix the cookie name with __Secure-; HTTP (local) does not.
 function parseSessionToken(cookieJson: string | null): string | null {
   if (!cookieJson) return null;
-  const cookies = fromZod(CookieStoreSchema)(JSON.parse(cookieJson));
+  const cookies = fromZod(CookieStoreSchema)(safeJsonParse(cookieJson));
   if (!cookies) return null;
   return (
     cookies['better-auth.session_token']?.value ??
diff --git a/apps/expo/package.json b/apps/expo/package.json
index bcf5e879e7..3804baa6d8 100644
--- a/apps/expo/package.json
+++ b/apps/expo/package.json
@@ -1,6 +1,6 @@
 {
   "name": "packrat-expo-app",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "main": "expo-router/entry",
   "scripts": {
@@ -65,6 +65,7 @@
     "@packrat/types": "workspace:*",
     "@packrat/ui": "workspace:*",
     "@packrat/units": "workspace:*",
+    "@packrat/utils": "workspace:*",
     "@react-native-ai/apple": "~0.10.0",
     "@react-native-ai/llama": "~0.10.0",
     "@react-native-async-storage/async-storage": "2.2.0",
@@ -135,7 +136,6 @@
     "llama.rn": "0.10.1",
     "nanoid": "^5.1.9",
     "nativewind": "^4.2.3",
-    "radash": "catalog:",
     "react": "catalog:",
     "react-dom": "catalog:",
     "react-i18next": "^17.0.4",
diff --git a/apps/expo/polyfills.ts b/apps/expo/polyfills.ts
index 0932b107d9..b66a0b968a 100644
--- a/apps/expo/polyfills.ts
+++ b/apps/expo/polyfills.ts
@@ -1,4 +1,5 @@
 import 'react-native-get-random-values';
+import { isString } from '@packrat/guards';
 import structuredClone from '@ungap/structured-clone';
 import { BackHandler, Platform } from 'react-native';
 
@@ -17,7 +18,7 @@ if (Platform.OS === 'web') {
   if (__DEV__) {
     const _origError = console.error.bind(console);
     console.error = (...args: unknown[]) => {
-      if (typeof args[0] === 'string' && args[0].includes('Unexpected text node')) return;
+      if (isString(args[0]) && args[0].includes('Unexpected text node')) return;
       _origError(...args);
     };
   }
diff --git a/apps/expo/utils/storage.ts b/apps/expo/utils/storage.ts
index abbab9a7da..bd94702fe8 100644
--- a/apps/expo/utils/storage.ts
+++ b/apps/expo/utils/storage.ts
@@ -2,16 +2,9 @@ import AsyncStorage from '@react-native-async-storage/async-storage';
 import type { WeatherLocation } from 'expo-app/features/weather/types';
 import { createJSONStorage } from 'jotai/utils';
 
-// Create a storage adapter for Jotai that uses AsyncStorage
-export const asyncStorage = createJSONStorage<WeatherLocation[]>(() => ({
-  getItem: async (key: string) => {
-    const value = await AsyncStorage.getItem(key);
-    return value ? JSON.parse(value) : null;
-  },
-  setItem: async (key: string, value: unknown) => {
-    await AsyncStorage.setItem(key, JSON.stringify(value));
-  },
-  removeItem: async (key: string) => {
-    await AsyncStorage.removeItem(key);
-  },
-}));
+// Jotai storage adapter backed by AsyncStorage. `createJSONStorage` owns the
+// JSON (de)serialization, so the backing storage must be a *string* storage —
+// AsyncStorage already is one. (The previous hand-rolled adapter parsed inside
+// the string-storage layer, which only type-checked because JSON.parse returns
+// `any`; it was the wrong shape for createJSONStorage.)
+export const asyncStorage = createJSONStorage<WeatherLocation[]>(() => AsyncStorage);
diff --git a/apps/guides/app/dev/generate/page.tsx b/apps/guides/app/dev/generate/page.tsx
index 120915e590..ebca110cc0 100644
--- a/apps/guides/app/dev/generate/page.tsx
+++ b/apps/guides/app/dev/generate/page.tsx
@@ -2,6 +2,7 @@
 
 import { guideEnv } from '@packrat/env/next';
 import { assertEnum } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import { Badge } from '@packrat/web-ui/components/badge';
 import { Button } from '@packrat/web-ui/components/button';
 import {
@@ -145,7 +146,7 @@ export default function GeneratePage() {
         headers: {
           'Content-Type': 'application/json',
         },
-        body: JSON.stringify({
+        body: safeJsonStringify({
           title,
           description,
           categories: selectedCategories,
@@ -198,7 +199,7 @@ export default function GeneratePage() {
         headers: {
           'Content-Type': 'application/json',
         },
-        body: JSON.stringify({
+        body: safeJsonStringify({
           count: batchCount,
           categories: batchCategories.length > 0 ? batchCategories : undefined,
         }),
diff --git a/apps/guides/package.json b/apps/guides/package.json
index a4497178e8..8ca6cc3f82 100644
--- a/apps/guides/package.json
+++ b/apps/guides/package.json
@@ -1,6 +1,6 @@
 {
   "name": "packrat-guides-app",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "scripts": {
     "build": "bun run build-content && bun run generate-og-images && next build",
@@ -31,6 +31,7 @@
     "@packrat/env": "workspace:*",
     "@packrat/guards": "workspace:*",
     "@packrat/schemas": "workspace:*",
+    "@packrat/utils": "workspace:*",
     "@packrat/web-ui": "workspace:*",
     "@radix-ui/react-accordion": "catalog:",
     "@radix-ui/react-alert-dialog": "catalog:",
diff --git a/apps/guides/scripts/build-content.ts b/apps/guides/scripts/build-content.ts
index ef2e267c6f..5c6c27d65d 100644
--- a/apps/guides/scripts/build-content.ts
+++ b/apps/guides/scripts/build-content.ts
@@ -2,6 +2,7 @@
 // It processes your MDX files and outputs JSON that can be imported
 // in your static site
 
+import { safeJsonStringify } from '@packrat/utils';
 import fs from 'fs';
 import matter from 'gray-matter';
 import type { Post } from 'guides-app/lib/types';
@@ -61,11 +62,11 @@ async function buildContent() {
   const contentFile = `// This file is auto-generated. Do not edit manually.
 import type { Post } from './types';
 
-export const posts: Post[] = ${JSON.stringify(posts, null, 2)};
+export const posts: Post[] = ${safeJsonStringify(posts, null, 2)};
 
-export const postContent: Record<string, string> = ${JSON.stringify(postContent, null, 2)};
+export const postContent: Record<string, string> = ${safeJsonStringify(postContent, null, 2)};
 
-export const categories: string[] = ${JSON.stringify(categories, null, 2)};
+export const categories: string[] = ${safeJsonStringify(categories, null, 2)};
 `;
 
   fs.writeFileSync(outputFile, contentFile);
diff --git a/apps/guides/scripts/generate-content.ts b/apps/guides/scripts/generate-content.ts
index f43a57b881..72590d9de7 100644
--- a/apps/guides/scripts/generate-content.ts
+++ b/apps/guides/scripts/generate-content.ts
@@ -1,5 +1,6 @@
 import { openai } from '@ai-sdk/openai';
 import { arrayIncludes, objectEntries } from '@packrat/guards';
+import { safeJsonParse } from '@packrat/utils';
 import { generateText } from 'ai';
 import chalk from 'chalk';
 import { format } from 'date-fns';
@@ -267,7 +268,9 @@ async function generateTopicIdeas({
   try {
     // Extract JSON from the text response which might contain markdown code blocks
     const jsonText = extractJsonFromText(text);
-    const ideas = JSON.parse(jsonText);
+    const ideas = safeJsonParse<
+      Array<{ title: string; description: string; categories: string[]; difficulty: string }>
+    >(jsonText, { strict: true });
 
     // Transform the data to match our internal format
     return ideas.map(
diff --git a/apps/landing/package.json b/apps/landing/package.json
index 11d718de32..4de0f59e23 100644
--- a/apps/landing/package.json
+++ b/apps/landing/package.json
@@ -1,6 +1,6 @@
 {
   "name": "packrat-landing-app",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "scripts": {
     "build": "bun run generate-og-images && next build",
diff --git a/apps/trails/lib/auth.ts b/apps/trails/lib/auth.ts
index 3d95a64e1b..1cb8889d00 100644
--- a/apps/trails/lib/auth.ts
+++ b/apps/trails/lib/auth.ts
@@ -4,6 +4,7 @@
 
 import { safeLocalStorage } from '@packrat/app/browser';
 import { fromZod, isString } from '@packrat/guards';
+import { safeJsonParse, safeJsonStringify } from '@packrat/utils';
 import z from 'zod';
 
 const ACCESS_KEY = 'access_token';
@@ -12,7 +13,7 @@ const REFRESH_KEY = 'refresh_token';
 function parseToken(raw: string | null): string | null {
   if (!raw) return null;
   try {
-    const parsed = JSON.parse(raw);
+    const parsed = safeJsonParse(raw, { strict: true });
     return isString(parsed) ? parsed : null;
   } catch {
     // Not JSON-encoded — return as-is (raw JWT)
@@ -54,13 +55,13 @@ export const UserInfoSchema = z.object({
 export type UserInfo = z.infer<typeof UserInfoSchema>;
 
 export function setUser(user: UserInfo): void {
-  safeLocalStorage.setItem({ key: 'user', value: JSON.stringify(user) });
+  safeLocalStorage.setItem({ key: 'user', value: safeJsonStringify(user) });
 }
 
 export function getUser(): UserInfo | null {
   try {
     const raw = safeLocalStorage.getItem('user');
-    return raw ? (fromZod(UserInfoSchema)(JSON.parse(raw)) ?? null) : null;
+    return raw ? (fromZod(UserInfoSchema)(safeJsonParse(raw, { strict: true })) ?? null) : null;
   } catch {
     return null;
   }
diff --git a/apps/trails/package.json b/apps/trails/package.json
index 39a5fb7bb1..b84b4dd185 100644
--- a/apps/trails/package.json
+++ b/apps/trails/package.json
@@ -1,6 +1,6 @@
 {
   "name": "packrat-trails-app",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "scripts": {
     "build": "bun run generate-og-images && next build",
@@ -19,6 +19,7 @@
     "@packrat/app": "workspace:*",
     "@packrat/guards": "workspace:*",
     "@packrat/overpass": "workspace:*",
+    "@packrat/utils": "workspace:*",
     "@packrat/web-ui": "workspace:*",
     "@radix-ui/react-dialog": "catalog:",
     "@radix-ui/react-label": "catalog:",
diff --git a/apps/web/app/auth/page.tsx b/apps/web/app/auth/page.tsx
index 6c989613c1..b41f613cbb 100644
--- a/apps/web/app/auth/page.tsx
+++ b/apps/web/app/auth/page.tsx
@@ -1,5 +1,6 @@
 'use client';
 import { webEnv } from '@packrat/env/web';
+import { safeJsonStringify } from '@packrat/utils';
 import { useMutation } from '@tanstack/react-query';
 import { useRouter } from 'next/navigation';
 import type React from 'react';
@@ -14,7 +15,7 @@ function useLoginMutation() {
       const res = await fetch(`${API_BASE}/api/auth/sign-in/email`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(body),
+        body: safeJsonStringify(body),
       });
       if (!res.ok) throw new Error('Login failed');
       return res.json() as Promise<{ token?: string; user?: unknown }>;
@@ -34,7 +35,7 @@ function useRegisterMutation() {
       const res = await fetch(`${API_BASE}/api/auth/sign-up/email`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ email: body.email, password: body.password, name }),
+        body: safeJsonStringify({ email: body.email, password: body.password, name }),
       });
       if (!res.ok) throw new Error('Registration failed');
       return res.json();
diff --git a/apps/web/components/screens/catalog-screen.tsx b/apps/web/components/screens/catalog-screen.tsx
index fc3624e485..916d9115ef 100644
--- a/apps/web/components/screens/catalog-screen.tsx
+++ b/apps/web/components/screens/catalog-screen.tsx
@@ -55,7 +55,9 @@ export function CatalogScreen() {
   // Client-side weight class filtering (since the API doesn't support it)
   const filteredItems = React.useMemo(() => {
     if (selectedWeightClass === 'all') return allItems;
-    return allItems.filter((item) => weightClass(item.weight) === selectedWeightClass);
+    return allItems.filter(
+      (item) => item.weight !== null && weightClass(item.weight) === selectedWeightClass,
+    );
   }, [allItems, selectedWeightClass]);
 
   const activeFilterCount = (selectedCategory ? 1 : 0) + (selectedWeightClass !== 'all' ? 1 : 0);
@@ -267,13 +269,15 @@ function CatalogCard({
   onAdd: () => void;
   onSave: () => void;
 }) {
-  const wc = weightClass(item.weight);
+  const wc = item.weight === null ? null : weightClass(item.weight);
   const wcStyles = {
     ultralight: 'bg-[#30d158]/15 text-[#30d158]',
     lightweight: 'bg-[#ff9f0a]/15 text-[#ff9f0a]',
     standard: 'bg-muted text-muted-foreground',
+    unknown: 'bg-muted text-muted-foreground',
   };
-  const wcLabels = { ultralight: 'UL', lightweight: 'LW', standard: 'STD' };
+  const wcLabels = { ultralight: 'UL', lightweight: 'LW', standard: 'STD', unknown: 'N/A' };
+  const weightClassKey = wc ?? 'unknown';
 
   return (
     <article className="rounded-2xl bg-card border border-border flex flex-col text-left hover:border-primary/30 transition-colors">
@@ -290,9 +294,12 @@ function CatalogCard({
             </span>
           )}
           <span
-            className={cn('rounded-full px-2 py-0.5 text-[10px] font-bold uppercase', wcStyles[wc])}
+            className={cn(
+              'rounded-full px-2 py-0.5 text-[10px] font-bold uppercase',
+              wcStyles[weightClassKey],
+            )}
           >
-            {wcLabels[wc]}
+            {wcLabels[weightClassKey]}
           </span>
         </div>
 
@@ -309,7 +316,9 @@ function CatalogCard({
         {/* Weight + Rating + Price */}
         <div className="flex items-center justify-between">
           <div className="flex items-center gap-2">
-            <span className="text-base font-bold">{fw(item.weight)}</span>
+            <span className="text-base font-bold">
+              {item.weight === null ? 'Unknown' : fw(item.weight)}
+            </span>
             {item.ratingValue && (
               <span className="flex items-center gap-0.5 text-xs text-muted-foreground">
                 <Star className="h-3 w-3 fill-[#ff9f0a] text-[#ff9f0a]" />
@@ -400,7 +409,9 @@ function GearDetailModal({
           <div className="flex items-center gap-3">
             <div className="flex-1 rounded-xl bg-card border border-border p-3 text-center">
               <p className="text-xs text-muted-foreground mb-0.5">Weight</p>
-              <p className="text-xl font-bold">{fw(item.weight)}</p>
+              <p className="text-xl font-bold">
+                {item.weight === null ? 'Unknown' : fw(item.weight)}
+              </p>
             </div>
             {item.price && (
               <div className="flex-1 rounded-xl bg-card border border-border p-3 text-center">
diff --git a/apps/web/components/screens/packs-screen.tsx b/apps/web/components/screens/packs-screen.tsx
index 8237ada2da..c0e4e8192b 100644
--- a/apps/web/components/screens/packs-screen.tsx
+++ b/apps/web/components/screens/packs-screen.tsx
@@ -632,7 +632,7 @@ function AddItemSlideOver({
                         packId,
                         body: {
                           name: item.name,
-                          weight: item.weight,
+                          weight: item.weight ?? 0,
                           weightUnit: 'g',
                           catalogItemId: item.id,
                         },
@@ -648,7 +648,9 @@ function AddItemSlideOver({
                       <p className="text-xs text-muted-foreground">{item.seller}</p>
                     </div>
                     <div className="text-right">
-                      <p className="text-sm font-semibold">{fw(item.weight)}</p>
+                      <p className="text-sm font-semibold">
+                        {item.weight === null ? 'Unknown' : fw(item.weight)}
+                      </p>
                       {item.price && <p className="text-xs text-muted-foreground">${item.price}</p>}
                     </div>
                   </div>
diff --git a/apps/web/lib/types.ts b/apps/web/lib/types.ts
index 5cc46ffdaa..42114e95fd 100644
--- a/apps/web/lib/types.ts
+++ b/apps/web/lib/types.ts
@@ -117,8 +117,8 @@ export type CatalogItem = {
   name: string;
   productUrl: string;
   sku: string;
-  weight: number;
-  weightUnit: string;
+  weight: number | null;
+  weightUnit: string | null;
   description: string | null;
   categories: string[] | null;
   images: string[] | null;
diff --git a/apps/web/package.json b/apps/web/package.json
index 631b065306..d2c6bc91ed 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -14,6 +14,7 @@
     "@packrat/app": "workspace:*",
     "@packrat/env": "workspace:*",
     "@packrat/guards": "workspace:*",
+    "@packrat/utils": "workspace:*",
     "@packrat/web-ui": "workspace:*",
     "@tanstack/react-query": "catalog:",
     "@tanstack/react-query-devtools": "catalog:",
diff --git a/ast-grep-rules/PARITY.md b/ast-grep-rules/PARITY.md
new file mode 100644
index 0000000000..6e61ca0f72
--- /dev/null
+++ b/ast-grep-rules/PARITY.md
@@ -0,0 +1,56 @@
+# ast-grep parity with retired regex lint scripts
+
+Maps each behavior of the old `scripts/lint/no-raw-typeof.ts` and
+`scripts/lint/no-raw-regex.ts` to the ast-grep rules that replace them. The old
+`.ts` scripts are left in place until the orchestrator confirms this proof.
+
+## no-raw-typeof.ts → `no-raw-typeof.yml` (+ `no-raw-typeof-tsx.yml`)
+
+| Old-script behavior | ast-grep coverage |
+|---|---|
+| Flags `typeof X === <primitive>` / `!==` | `rule.any` of `typeof $X === $T` / `typeof $X !== $T` |
+| Primitive set: string,number,boolean,object,function,undefined,symbol,bigint | `constraints.T.regex` exactly that set, quote-anchored |
+| Exempt globals window/document/globalThis/Bun/navigator/process | `constraints.X.not.regex` for those identifiers |
+| Scanned only `apps/` + `packages/`, skipped node_modules/dist/build/.wrangler | `ignores` for `scripts/**`, `.github/**`, mocks; ast-grep already skips ignored/build dirs via repo .gitignore |
+| Exempt `packages/guards/**` | `ignores: **/packages/guards/**` (plus `packages/utils/**`) |
+| Exempt `*.test`/`*.spec` files | `ignores` for `*.test.{ts,tsx}` / `*.spec.{ts,tsx}` |
+| Only matched `.ts/.tsx/.cts/.mts` | typescript-language rule + tsx-language twin for `.tsx` |
+
+**Stricter than the old script (real bugs the line-regex MISSED):** the old
+identifier regex `[A-Za-z_][A-Za-z0-9_.]*` did not match optional chaining or
+bracket access, so it silently skipped `typeof options?.md5 === 'string'`
+(packages/api/src/services/r2-bucket.ts) and `typeof entry[0] === 'string'`
+(packages/api-client/src/index.ts). ast-grep's `$X` metavar matches any
+expression, catching all of these. The `.tsx` twin also catches
+`packages/web-ui/src/components/chart.tsx`. All migrated (see report).
+
+## no-raw-regex.ts → `no-raw-regex.yml` (+ `no-raw-regex-tsx.yml`)
+
+| Old-script behavior | ast-grep coverage |
+|---|---|
+| Flags `new RegExp(...)` | `pattern: new RegExp($$$ARGS)` |
+| Flags `.replace/.replaceAll/.match/.matchAll/.test/.split/.search(/.../)` | method `any` + `has: {field: arguments, has: {kind: regex}}` (top-level regex literal arg only — mirrors the old `(/` heuristic, no over-match into nested calls) |
+| Scope apps/+packages/ non-test | same `ignores` set as typeof |
+| Allowlist enrichment.ts + alltrails.ts | `ignores` entries for both files |
+| Biome `performance/useTopLevelRegex` covers the strict AST case | noted in rule `message` |
+
+## no-raw-json (new) → `no-raw-json*.yml`
+
+Not part of parity (no old script). `severity: warning` so CI is not gated.
+`JSON.parse($X)`→`safeJsonParse($X)` and single-arg `JSON.stringify($X)`→
+`safeJsonStringify($X)` carry autofix `fix:`. Multi-arg stringify is flagged without
+autofix (no clean 1:1 rewrite). Import insertion is out of scope.
+
+## no-primitive-cast (new) → `no-primitive-cast*.yml` (+ `-tsx` twin)
+
+Not part of parity (no old script). Complements `packages/checks/check-type-casts.ts`,
+which deliberately exempts single-word lowercase types (`if (LOWERCASE_TYPE.test(castType)) continue;`)
+and so never flags `as string` / `as number` / `as boolean`. This rule fills that gap:
+it matches an as-expression to a primitive type (`$X as string|number|boolean`) and steers
+authors to a `@packrat/guards` narrow (`toString`/`toNumber`/`toBoolean`, `as*` aliases) or an
+explicit coercion (`String`/`Number`/`toFloat`/`toInt`). No double-reporting — the two checks
+cover disjoint cast shapes (named types vs. primitives). `as const` / `as unknown` / `as T[]`
+are not primitive single-type assertions and are naturally excluded by the pattern. Same
+`ignores` scope as the typeof rules (guards/utils/tooling/test files). `severity: warning`
+because ~63 primitive casts already exist (mostly `apps/expo`); burn the backlog down, then
+promote to `error`.
diff --git a/ast-grep-rules/no-primitive-cast-tsx.yml b/ast-grep-rules/no-primitive-cast-tsx.yml
new file mode 100644
index 0000000000..14df591109
--- /dev/null
+++ b/ast-grep-rules/no-primitive-cast-tsx.yml
@@ -0,0 +1,24 @@
+id: no-primitive-cast-tsx
+# TSX variant of no-primitive-cast. The `typescript` language parser does NOT
+# match .tsx files, so .tsx app code (apps/expo, apps/trails, apps/guides,
+# apps/landing) needs this `tsx`-language twin. Same rule/ignores as
+# no-primitive-cast.yml.
+language: tsx
+severity: warning
+message: "Don't assert with `as string` / `as number` / `as boolean` — assertions lie to the type-checker at boundaries. Use a `@packrat/guards` narrow (`toString`/`toNumber`/`toBoolean`, or the `asString`/`asNumber`/`asBoolean` aliases) and handle the `undefined` case, or coerce explicitly (e.g. `String(x)`, `Number(x)`, `toFloat`/`toInt` from @packrat/utils). `as const` / `as unknown` are fine and not flagged. Annotate a genuinely unavoidable cast with `// safe-cast:`."
+ignores:
+  - "**/packages/guards/**"
+  - "**/packages/utils/**"
+  - "scripts/**"
+  - ".github/**"
+  - "**/mocks/**"
+  - "**/__mocks__/**"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+rule:
+  any:
+    - pattern: $X as string
+    - pattern: $X as number
+    - pattern: $X as boolean
diff --git a/ast-grep-rules/no-primitive-cast.yml b/ast-grep-rules/no-primitive-cast.yml
new file mode 100644
index 0000000000..6592831e37
--- /dev/null
+++ b/ast-grep-rules/no-primitive-cast.yml
@@ -0,0 +1,24 @@
+id: no-primitive-cast
+language: typescript
+# warning, not error: the repo already has ~63 primitive casts (mostly apps/expo),
+# so gating CI would break the build. Burn the backlog down, then promote to error.
+severity: warning
+message: "Don't assert with `as string` / `as number` / `as boolean` — assertions lie to the type-checker at boundaries. Use a `@packrat/guards` narrow (`toString`/`toNumber`/`toBoolean`, or the `asString`/`asNumber`/`asBoolean` aliases) and handle the `undefined` case, or coerce explicitly (e.g. `String(x)`, `Number(x)`, `toFloat`/`toInt` from @packrat/utils). `as const` / `as unknown` are fine and not flagged. Annotate a genuinely unavoidable cast with `// safe-cast:`."
+ignores:
+  # Mirrors no-raw-typeof scope: guards/utils are the canonical narrow homes,
+  # tooling dirs and non-production files are out of scope.
+  - "**/packages/guards/**"
+  - "**/packages/utils/**"
+  - "scripts/**"
+  - ".github/**"
+  - "**/mocks/**"
+  - "**/__mocks__/**"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+rule:
+  any:
+    - pattern: $X as string
+    - pattern: $X as number
+    - pattern: $X as boolean
diff --git a/ast-grep-rules/no-raw-json-stringify-multi-tsx.yml b/ast-grep-rules/no-raw-json-stringify-multi-tsx.yml
new file mode 100644
index 0000000000..ad9e98d52e
--- /dev/null
+++ b/ast-grep-rules/no-raw-json-stringify-multi-tsx.yml
@@ -0,0 +1,23 @@
+id: no-raw-json-stringify-multi-tsx
+# TSX variant of no-raw-json-stringify-multi (multi-arg, no autofix).
+language: tsx
+severity: error
+message: "Prefer safeJsonStringify from @packrat/utils over raw JSON.stringify (multi-arg: replacer/space need manual migration)."
+ignores:
+  - "**/test/**"
+  - "**/playwright/**"
+  - "**/e2e/**"
+  - "scripts/**"
+  - ".github/**"
+  - "**/packages/utils/**"
+  - "**/mocks/**"
+  - "**/__mocks__/**"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+rule:
+  all:
+    - pattern: JSON.stringify($$$ARGS)
+    - not:
+        pattern: JSON.stringify($X)
diff --git a/ast-grep-rules/no-raw-json-stringify-multi.yml b/ast-grep-rules/no-raw-json-stringify-multi.yml
new file mode 100644
index 0000000000..9145bed7dc
--- /dev/null
+++ b/ast-grep-rules/no-raw-json-stringify-multi.yml
@@ -0,0 +1,27 @@
+id: no-raw-json-stringify-multi
+language: typescript
+# WARNING (not error): multi-argument JSON.stringify (replacer / space). Flagged
+# for the separate JSON-migration unit but intentionally NO autofix — there is
+# no clean 1:1 rewrite, so the orchestrator's codemod handles these by hand.
+# The single-arg form is covered (with autofix) by no-raw-json-stringify.yml;
+# the `not` constraint below keeps the two rules from double-reporting.
+severity: error
+message: "Prefer safeJsonStringify from @packrat/utils over raw JSON.stringify (multi-arg: replacer/space need manual migration)."
+ignores:
+  - "**/test/**"
+  - "**/playwright/**"
+  - "**/e2e/**"
+  - "scripts/**"
+  - ".github/**"
+  - "**/packages/utils/**"
+  - "**/mocks/**"
+  - "**/__mocks__/**"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+rule:
+  all:
+    - pattern: JSON.stringify($$$ARGS)
+    - not:
+        pattern: JSON.stringify($X)
diff --git a/ast-grep-rules/no-raw-json-stringify-tsx.yml b/ast-grep-rules/no-raw-json-stringify-tsx.yml
new file mode 100644
index 0000000000..5a5c669948
--- /dev/null
+++ b/ast-grep-rules/no-raw-json-stringify-tsx.yml
@@ -0,0 +1,21 @@
+id: no-raw-json-stringify-tsx
+# TSX variant of no-raw-json-stringify (single-arg, autofixable).
+language: tsx
+severity: error
+message: "Prefer safeJsonStringify from @packrat/utils over raw JSON.stringify."
+ignores:
+  - "**/test/**"
+  - "**/playwright/**"
+  - "**/e2e/**"
+  - "scripts/**"
+  - ".github/**"
+  - "**/packages/utils/**"
+  - "**/mocks/**"
+  - "**/__mocks__/**"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+rule:
+  pattern: JSON.stringify($X)
+fix: safeJsonStringify($X)
diff --git a/ast-grep-rules/no-raw-json-stringify.yml b/ast-grep-rules/no-raw-json-stringify.yml
new file mode 100644
index 0000000000..388d1f6bbf
--- /dev/null
+++ b/ast-grep-rules/no-raw-json-stringify.yml
@@ -0,0 +1,25 @@
+id: no-raw-json-stringify
+language: typescript
+# WARNING (not error): see no-raw-json.yml. Covers the single-argument form of
+# JSON.stringify, which has a clean 1:1 autofix (JSON.stringify($X) ->
+# safeJsonStringify($X)). Multi-arg calls (replacer / space) are handled by
+# no-raw-json-stringify-multi.yml, which has no autofix. Import insertion is out
+# of scope here (the orchestrator's codemod handles it).
+severity: error
+message: "Prefer safeJsonStringify from @packrat/utils over raw JSON.stringify."
+ignores:
+  - "**/test/**"
+  - "**/playwright/**"
+  - "**/e2e/**"
+  - "scripts/**"
+  - ".github/**"
+  - "**/packages/utils/**"
+  - "**/mocks/**"
+  - "**/__mocks__/**"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+rule:
+  pattern: JSON.stringify($X)
+fix: safeJsonStringify($X)
diff --git a/ast-grep-rules/no-raw-json-tsx.yml b/ast-grep-rules/no-raw-json-tsx.yml
new file mode 100644
index 0000000000..00ce0a60d9
--- /dev/null
+++ b/ast-grep-rules/no-raw-json-tsx.yml
@@ -0,0 +1,21 @@
+id: no-raw-json-tsx
+# TSX variant of no-raw-json (the `typescript` parser does not match .tsx).
+language: tsx
+severity: error
+message: "Prefer safeJsonParse from @packrat/utils over raw JSON.parse. Raw JSON.parse throws on malformed input and returns `any`; safeJsonParse returns a typed result."
+ignores:
+  - "**/test/**"
+  - "**/playwright/**"
+  - "**/e2e/**"
+  - "scripts/**"
+  - ".github/**"
+  - "**/packages/utils/**"
+  - "**/mocks/**"
+  - "**/__mocks__/**"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+rule:
+  pattern: JSON.parse($X)
+fix: safeJsonParse($X)
diff --git a/ast-grep-rules/no-raw-json.yml b/ast-grep-rules/no-raw-json.yml
new file mode 100644
index 0000000000..21fa34f5bc
--- /dev/null
+++ b/ast-grep-rules/no-raw-json.yml
@@ -0,0 +1,24 @@
+id: no-raw-json
+language: typescript
+# WARNING (not error): the repo-wide JSON migration (~156 sites) is a separate
+# unit handled by the orchestrator. This rule surfaces JSON.parse call sites
+# without failing CI yet. The `fix` rewrites JSON.parse($X) -> safeJsonParse($X);
+# import insertion is out of scope here (the orchestrator's codemod handles it).
+severity: error
+message: "Prefer safeJsonParse from @packrat/utils over raw JSON.parse. Raw JSON.parse throws on malformed input and returns `any`; safeJsonParse returns a typed result."
+ignores:
+  - "**/test/**"
+  - "**/playwright/**"
+  - "**/e2e/**"
+  - "scripts/**"
+  - ".github/**"
+  - "**/packages/utils/**"
+  - "**/mocks/**"
+  - "**/__mocks__/**"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+rule:
+  pattern: JSON.parse($X)
+fix: safeJsonParse($X)
diff --git a/ast-grep-rules/no-raw-regex-tsx.yml b/ast-grep-rules/no-raw-regex-tsx.yml
new file mode 100644
index 0000000000..0a7e0d7314
--- /dev/null
+++ b/ast-grep-rules/no-raw-regex-tsx.yml
@@ -0,0 +1,34 @@
+id: no-raw-regex-tsx
+# TSX variant of no-raw-regex (the `typescript` parser does not match .tsx).
+language: tsx
+severity: error
+message: "Prefer magic-regexp over a raw regex literal or `new RegExp(...)`. Raw regex is error-prone (missing escapes, unintended capture groups, poor readability); magic-regexp gives a typed, composable builder. See packages/analytics/src/core/enrichment.ts for a reference. Biome's performance/useTopLevelRegex covers the stricter top-level check."
+ignores:
+  - "scripts/**"
+  - ".github/**"
+  - "**/packages/guards/**"
+  - "**/packages/utils/**"
+  - "**/mocks/**"
+  - "**/__mocks__/**"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+  - "**/packages/analytics/src/core/enrichment.ts"
+  - "**/packages/api/src/routes/alltrails.ts"
+rule:
+  any:
+    - pattern: new RegExp($$$ARGS)
+    - all:
+        - any:
+            - { pattern: $OBJ.replace($$$) }
+            - { pattern: $OBJ.replaceAll($$$) }
+            - { pattern: $OBJ.match($$$) }
+            - { pattern: $OBJ.matchAll($$$) }
+            - { pattern: $OBJ.test($$$) }
+            - { pattern: $OBJ.split($$$) }
+            - { pattern: $OBJ.search($$$) }
+        - has:
+            field: arguments
+            has:
+              kind: regex
diff --git a/ast-grep-rules/no-raw-regex.yml b/ast-grep-rules/no-raw-regex.yml
new file mode 100644
index 0000000000..083a210424
--- /dev/null
+++ b/ast-grep-rules/no-raw-regex.yml
@@ -0,0 +1,38 @@
+id: no-raw-regex
+language: typescript
+severity: error
+message: "Prefer magic-regexp over a raw regex literal or `new RegExp(...)`. Raw regex is error-prone (missing escapes, unintended capture groups, poor readability); magic-regexp gives a typed, composable builder. See packages/analytics/src/core/enrichment.ts for a reference. Biome's performance/useTopLevelRegex covers the stricter top-level check."
+ignores:
+  # Mirror the old scripts/lint/no-raw-regex.ts scope: apps/ + packages/ only,
+  # non-test. Tooling dirs were never scanned; guards/utils are exempt homes.
+  - "scripts/**"
+  - ".github/**"
+  - "**/packages/guards/**"
+  - "**/packages/utils/**"
+  - "**/mocks/**"
+  - "**/__mocks__/**"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+  # File-level allowlist carried over from the old script:
+  # enrichment.ts is the magic-regexp reference; alltrails.ts builds a regex
+  # from a dynamic `property` arg and cannot be a static magic-regexp constant.
+  - "**/packages/analytics/src/core/enrichment.ts"
+  - "**/packages/api/src/routes/alltrails.ts"
+rule:
+  any:
+    - pattern: new RegExp($$$ARGS)
+    - all:
+        - any:
+            - { pattern: $OBJ.replace($$$) }
+            - { pattern: $OBJ.replaceAll($$$) }
+            - { pattern: $OBJ.match($$$) }
+            - { pattern: $OBJ.matchAll($$$) }
+            - { pattern: $OBJ.test($$$) }
+            - { pattern: $OBJ.split($$$) }
+            - { pattern: $OBJ.search($$$) }
+        - has:
+            field: arguments
+            has:
+              kind: regex
diff --git a/ast-grep-rules/no-raw-typeof-tsx.yml b/ast-grep-rules/no-raw-typeof-tsx.yml
new file mode 100644
index 0000000000..e789c0720c
--- /dev/null
+++ b/ast-grep-rules/no-raw-typeof-tsx.yml
@@ -0,0 +1,28 @@
+id: no-raw-typeof-tsx
+# TSX variant of no-raw-typeof. The `typescript` language parser does NOT match
+# .tsx files, so .tsx app code (apps/expo, apps/guides, apps/landing) needs this
+# `tsx`-language twin. Same rule/constraints/ignores as no-raw-typeof.yml.
+language: tsx
+severity: error
+message: "Use a guard from @packrat/guards (isString/isNumber/isBoolean/…) instead of a raw `typeof` primitive check. Raw typeof is allowed only inside packages/guards and packages/utils, and for global availability checks (window/document/globalThis/Bun/navigator/process)."
+ignores:
+  - "**/packages/guards/**"
+  - "**/packages/utils/**"
+  - "scripts/**"
+  - ".github/**"
+  - "**/mocks/**"
+  - "**/__mocks__/**"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+rule:
+  any:
+    - pattern: typeof $X === $T
+    - pattern: typeof $X !== $T
+constraints:
+  T:
+    regex: "^['\"](string|number|boolean|object|function|undefined|symbol|bigint)['\"]$"
+  X:
+    not:
+      regex: "^(window|document|globalThis|Bun|navigator|process)$"
diff --git a/ast-grep-rules/no-raw-typeof.yml b/ast-grep-rules/no-raw-typeof.yml
new file mode 100644
index 0000000000..a55006959b
--- /dev/null
+++ b/ast-grep-rules/no-raw-typeof.yml
@@ -0,0 +1,28 @@
+id: no-raw-typeof
+language: typescript
+severity: error
+message: "Use a guard from @packrat/guards (isString/isNumber/isBoolean/…) instead of a raw `typeof` primitive check. Raw typeof is allowed only inside packages/guards and packages/utils, and for global availability checks (window/document/globalThis/Bun/navigator/process)."
+ignores:
+  # The old scripts/lint/no-raw-typeof.ts only scanned apps/ + packages/.
+  # Everything below mirrors that scope: tooling dirs and non-production files
+  # the old script never walked, plus the canonical guard/util homes.
+  - "**/packages/guards/**"
+  - "**/packages/utils/**"
+  - "scripts/**"
+  - ".github/**"
+  - "**/mocks/**"
+  - "**/__mocks__/**"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+rule:
+  any:
+    - pattern: typeof $X === $T
+    - pattern: typeof $X !== $T
+constraints:
+  T:
+    regex: "^['\"](string|number|boolean|object|function|undefined|symbol|bigint)['\"]$"
+  X:
+    not:
+      regex: "^(window|document|globalThis|Bun|navigator|process)$"
diff --git a/ast-grep-tests/__snapshots__/no-primitive-cast-snapshot.yml b/ast-grep-tests/__snapshots__/no-primitive-cast-snapshot.yml
new file mode 100644
index 0000000000..d8cdc24625
--- /dev/null
+++ b/ast-grep-tests/__snapshots__/no-primitive-cast-snapshot.yml
@@ -0,0 +1,38 @@
+id: no-primitive-cast
+snapshots:
+  const a = x as string;:
+    labels:
+    - source: x as string
+      style: primary
+      start: 10
+      end: 21
+  const b = y as number;:
+    labels:
+    - source: y as number
+      style: primary
+      start: 10
+      end: 21
+  const c = z as boolean;:
+    labels:
+    - source: z as boolean
+      style: primary
+      start: 10
+      end: 22
+  const d = (s as unknown) as string;:
+    labels:
+    - source: (s as unknown) as string
+      style: primary
+      start: 10
+      end: 34
+  const e = params.lat as string;:
+    labels:
+    - source: params.lat as string
+      style: primary
+      start: 10
+      end: 30
+  const f = Number.parseFloat(params.lon as string);:
+    labels:
+    - source: params.lon as string
+      style: primary
+      start: 28
+      end: 48
diff --git a/ast-grep-tests/__snapshots__/no-primitive-cast-tsx-snapshot.yml b/ast-grep-tests/__snapshots__/no-primitive-cast-tsx-snapshot.yml
new file mode 100644
index 0000000000..87d4ef840f
--- /dev/null
+++ b/ast-grep-tests/__snapshots__/no-primitive-cast-tsx-snapshot.yml
@@ -0,0 +1,14 @@
+id: no-primitive-cast-tsx
+snapshots:
+  const C = () => <A id={id as string} />:
+    labels:
+    - source: id as string
+      style: primary
+      start: 23
+      end: 35
+  const D = () => <A n={count as number} />:
+    labels:
+    - source: count as number
+      style: primary
+      start: 22
+      end: 37
diff --git a/ast-grep-tests/__snapshots__/no-raw-regex-snapshot.yml b/ast-grep-tests/__snapshots__/no-raw-regex-snapshot.yml
new file mode 100644
index 0000000000..d06fb892ad
--- /dev/null
+++ b/ast-grep-tests/__snapshots__/no-raw-regex-snapshot.yml
@@ -0,0 +1,112 @@
+id: no-raw-regex
+snapshots:
+  const a = new RegExp('x'):
+    labels:
+    - source: new RegExp('x')
+      style: primary
+      start: 10
+      end: 25
+  const b = new RegExp(pattern, 'g'):
+    labels:
+    - source: new RegExp(pattern, 'g')
+      style: primary
+      start: 10
+      end: 34
+  const c = s.replace(/a/, 'b'):
+    labels:
+    - source: s.replace(/a/, 'b')
+      style: primary
+      start: 10
+      end: 29
+    - source: /a/
+      style: secondary
+      start: 20
+      end: 23
+    - source: /a/
+      style: secondary
+      start: 20
+      end: 23
+  const d = s.replaceAll(/a/g, 'b'):
+    labels:
+    - source: s.replaceAll(/a/g, 'b')
+      style: primary
+      start: 10
+      end: 33
+    - source: /a/g
+      style: secondary
+      start: 23
+      end: 27
+    - source: /a/g
+      style: secondary
+      start: 23
+      end: 27
+  const e = s.match(/x/):
+    labels:
+    - source: s.match(/x/)
+      style: primary
+      start: 10
+      end: 22
+    - source: /x/
+      style: secondary
+      start: 18
+      end: 21
+    - source: /x/
+      style: secondary
+      start: 18
+      end: 21
+  const f = s.matchAll(/x/g):
+    labels:
+    - source: s.matchAll(/x/g)
+      style: primary
+      start: 10
+      end: 26
+    - source: /x/g
+      style: secondary
+      start: 21
+      end: 25
+    - source: /x/g
+      style: secondary
+      start: 21
+      end: 25
+  const g = s.test(/y/):
+    labels:
+    - source: s.test(/y/)
+      style: primary
+      start: 10
+      end: 21
+    - source: /y/
+      style: secondary
+      start: 17
+      end: 20
+    - source: /y/
+      style: secondary
+      start: 17
+      end: 20
+  const h = s.split(/,/):
+    labels:
+    - source: s.split(/,/)
+      style: primary
+      start: 10
+      end: 22
+    - source: /,/
+      style: secondary
+      start: 18
+      end: 21
+    - source: /,/
+      style: secondary
+      start: 18
+      end: 21
+  const i = s.search(/z/):
+    labels:
+    - source: s.search(/z/)
+      style: primary
+      start: 10
+      end: 23
+    - source: /z/
+      style: secondary
+      start: 19
+      end: 22
+    - source: /z/
+      style: secondary
+      start: 19
+      end: 22
diff --git a/ast-grep-tests/__snapshots__/no-raw-typeof-snapshot.yml b/ast-grep-tests/__snapshots__/no-raw-typeof-snapshot.yml
new file mode 100644
index 0000000000..bbde6d22f5
--- /dev/null
+++ b/ast-grep-tests/__snapshots__/no-raw-typeof-snapshot.yml
@@ -0,0 +1,68 @@
+id: no-raw-typeof
+snapshots:
+  const n = typeof y === 'number':
+    labels:
+    - source: typeof y === 'number'
+      style: primary
+      start: 10
+      end: 31
+  if (typeof b === 'boolean') {}:
+    labels:
+    - source: typeof b === 'boolean'
+      style: primary
+      start: 4
+      end: 26
+  if (typeof big === 'bigint') {}:
+    labels:
+    - source: typeof big === 'bigint'
+      style: primary
+      start: 4
+      end: 27
+  if (typeof entry[0] === 'string') {}:
+    labels:
+    - source: typeof entry[0] === 'string'
+      style: primary
+      start: 4
+      end: 32
+  if (typeof f === 'function') {}:
+    labels:
+    - source: typeof f === 'function'
+      style: primary
+      start: 4
+      end: 27
+  if (typeof options?.md5 === 'string') {}:
+    labels:
+    - source: typeof options?.md5 === 'string'
+      style: primary
+      start: 4
+      end: 36
+  if (typeof s === 'symbol') {}:
+    labels:
+    - source: typeof s === 'symbol'
+      style: primary
+      start: 4
+      end: 25
+  if (typeof u === 'undefined') {}:
+    labels:
+    - source: typeof u === 'undefined'
+      style: primary
+      start: 4
+      end: 28
+  if (typeof x !== 'string') {}:
+    labels:
+    - source: typeof x !== 'string'
+      style: primary
+      start: 4
+      end: 25
+  if (typeof x === 'string') {}:
+    labels:
+    - source: typeof x === 'string'
+      style: primary
+      start: 4
+      end: 25
+  if (typeof z === 'object') {}:
+    labels:
+    - source: typeof z === 'object'
+      style: primary
+      start: 4
+      end: 25
diff --git a/ast-grep-tests/__snapshots__/no-raw-typeof-tsx-snapshot.yml b/ast-grep-tests/__snapshots__/no-raw-typeof-tsx-snapshot.yml
new file mode 100644
index 0000000000..0a89e4c99a
--- /dev/null
+++ b/ast-grep-tests/__snapshots__/no-raw-typeof-tsx-snapshot.yml
@@ -0,0 +1,14 @@
+id: no-raw-typeof-tsx
+snapshots:
+  'const C = () => (typeof x === ''string'' ? <A /> : <B />)':
+    labels:
+    - source: typeof x === 'string'
+      style: primary
+      start: 17
+      end: 38
+  'const D = () => (typeof n !== ''number'' ? <A /> : <B />)':
+    labels:
+    - source: typeof n !== 'number'
+      style: primary
+      start: 17
+      end: 38
diff --git a/ast-grep-tests/no-primitive-cast-test.yml b/ast-grep-tests/no-primitive-cast-test.yml
new file mode 100644
index 0000000000..111b28b16a
--- /dev/null
+++ b/ast-grep-tests/no-primitive-cast-test.yml
@@ -0,0 +1,20 @@
+id: no-primitive-cast
+valid:
+  # `as const` and `as unknown` are required, safe casts — not flagged.
+  - "const a = [1, 2, 3] as const;"
+  - "const b = x as unknown;"
+  # Array-type casts are not the primitive single-type assertion we target.
+  - "const c = x as string[];"
+  # Non-primitive named-type casts are check-type-casts.ts's job, not this rule's.
+  - "const d = x as MyType;"
+  # The narrowing API itself — the recommended replacement, never a cast.
+  - "const e = toString(x);"
+invalid:
+  - "const a = x as string;"
+  - "const b = y as number;"
+  - "const c = z as boolean;"
+  # Double-assertion to a primitive: the outer `as string` is still flagged.
+  - "const d = (s as unknown) as string;"
+  # Works on any expression, not just identifiers.
+  - "const e = params.lat as string;"
+  - "const f = Number.parseFloat(params.lon as string);"
diff --git a/ast-grep-tests/no-primitive-cast-tsx-test.yml b/ast-grep-tests/no-primitive-cast-tsx-test.yml
new file mode 100644
index 0000000000..c806199d3f
--- /dev/null
+++ b/ast-grep-tests/no-primitive-cast-tsx-test.yml
@@ -0,0 +1,8 @@
+id: no-primitive-cast-tsx
+valid:
+  - "const C = () => (cond ? <A /> : <B v={x as const} />)"
+  - "const D = () => <A id={toString(x)} />"
+invalid:
+  # Proves .tsx code (JSX present) is covered by the tsx-language twin.
+  - "const C = () => <A id={id as string} />"
+  - "const D = () => <A n={count as number} />"
diff --git a/ast-grep-tests/no-raw-regex-test.yml b/ast-grep-tests/no-raw-regex-test.yml
new file mode 100644
index 0000000000..29a9edf63d
--- /dev/null
+++ b/ast-grep-tests/no-raw-regex-test.yml
@@ -0,0 +1,23 @@
+id: no-raw-regex
+valid:
+  # String methods called with NON-regex args are fine.
+  - "const a = s.split(',')"
+  - "const b = s.replace('a', 'b')"
+  - "const c = s.split(sep)"
+  - "const d = s.match(myRegexVar)"
+  # Regex nested inside a non-first/non-top-level arg is not the `.method(/` shape.
+  - "const e = foo.bar(x, baz(/z/))"
+  # magic-regexp builder usage.
+  - "const r = createRegExp(word)"
+invalid:
+  # new RegExp(...) in any form.
+  - "const a = new RegExp('x')"
+  - "const b = new RegExp(pattern, 'g')"
+  # Raw regex literal passed to a string method (the old script's `.method(/` cases).
+  - "const c = s.replace(/a/, 'b')"
+  - "const d = s.replaceAll(/a/g, 'b')"
+  - "const e = s.match(/x/)"
+  - "const f = s.matchAll(/x/g)"
+  - "const g = s.test(/y/)"
+  - "const h = s.split(/,/)"
+  - "const i = s.search(/z/)"
diff --git a/ast-grep-tests/no-raw-typeof-test.yml b/ast-grep-tests/no-raw-typeof-test.yml
new file mode 100644
index 0000000000..2f4cc6b7a2
--- /dev/null
+++ b/ast-grep-tests/no-raw-typeof-test.yml
@@ -0,0 +1,27 @@
+id: no-raw-typeof
+valid:
+  # Global availability checks are exempt (accessing undeclared globals throws).
+  - "if (typeof window !== 'undefined') {}"
+  - "if (typeof document === 'undefined') {}"
+  - "const g = typeof globalThis === 'object'"
+  - "if (typeof Bun !== 'undefined') {}"
+  - "if (typeof navigator === 'object') {}"
+  - "if (typeof process !== 'undefined') {}"
+  # typeof against a non-primitive-literal RHS is not a primitive narrowing.
+  - "if (typeof a === b) {}"
+  - "if (typeof a === SOME_CONST) {}"
+  # Already migrated to a guard predicate.
+  - "if (isString(x)) {}"
+invalid:
+  - "if (typeof x === 'string') {}"
+  - "if (typeof x !== 'string') {}"
+  - "const n = typeof y === 'number'"
+  - "if (typeof z === 'object') {}"
+  - "if (typeof f === 'function') {}"
+  - "if (typeof b === 'boolean') {}"
+  - "if (typeof u === 'undefined') {}"
+  - "if (typeof s === 'symbol') {}"
+  - "if (typeof big === 'bigint') {}"
+  # Patterns the old line-regex MISSED but ast-grep catches:
+  - "if (typeof options?.md5 === 'string') {}"
+  - "if (typeof entry[0] === 'string') {}"
diff --git a/ast-grep-tests/no-raw-typeof-tsx-test.yml b/ast-grep-tests/no-raw-typeof-tsx-test.yml
new file mode 100644
index 0000000000..4b89f3aa06
--- /dev/null
+++ b/ast-grep-tests/no-raw-typeof-tsx-test.yml
@@ -0,0 +1,8 @@
+id: no-raw-typeof-tsx
+valid:
+  - "const C = () => (typeof window !== 'undefined' ? <A /> : <B />)"
+  - "const v = isString(x) ? <A /> : null"
+invalid:
+  # Proves .tsx code (JSX present) is covered by the tsx-language twin.
+  - "const C = () => (typeof x === 'string' ? <A /> : <B />)"
+  - "const D = () => (typeof n !== 'number' ? <A /> : <B />)"
diff --git a/biome.json b/biome.json
index 5715215a55..ca6e143008 100644
--- a/biome.json
+++ b/biome.json
@@ -53,7 +53,31 @@
         "useTopLevelRegex": "error"
       },
       "style": {
-        "noNonNullAssertion": "error"
+        "noNonNullAssertion": "error",
+        "noRestrictedImports": {
+          "level": "error",
+          "options": {
+            "patterns": [
+              {
+                "group": [
+                  "radashi",
+                  "radashi/**",
+                  "radash",
+                  "radash/**",
+                  "es-toolkit",
+                  "es-toolkit/**",
+                  "lodash",
+                  "lodash/**",
+                  "remeda",
+                  "remeda/**",
+                  "destr",
+                  "safe-stable-stringify"
+                ],
+                "message": "Import utilities from @packrat/utils (or narrowing from @packrat/guards). These libs may only be imported inside packages/utils — the single curated utility surface. See docs/utils-policy.md."
+              }
+            ]
+          }
+        }
       },
       "suspicious": {
         "noUnknownAtRules": "off"
@@ -61,6 +85,16 @@
     }
   },
   "overrides": [
+    {
+      "includes": ["packages/utils/**"],
+      "linter": {
+        "rules": {
+          "style": {
+            "noRestrictedImports": "off"
+          }
+        }
+      }
+    },
     {
       "includes": [
         "apps/expo/atoms/atomWith*.ts",
diff --git a/bun.lock b/bun.lock
index e13363a3da..9997add77a 100644
--- a/bun.lock
+++ b/bun.lock
@@ -5,6 +5,7 @@
     "": {
       "name": "packrat-monorepo",
       "devDependencies": {
+        "@ast-grep/cli": "^0.43.0",
         "@biomejs/biome": "2.4.6",
         "@manypkg/cli": "^0.24.0",
         "@playwright/test": "^1.59.1",
@@ -14,21 +15,24 @@
         "@typescript/native-preview": "7.0.0-dev.20260527.2",
         "fs-extra": "^11.3.0",
         "glob": "^11.0.3",
+        "jscpd": "^4.2.4",
         "lefthook": "^1.11.14",
         "semver": "catalog:",
         "sort-package-json": "^3.6.1",
+        "ts-morph": "^28.0.0",
         "turbo": "^2.5.0",
       },
     },
     "apps/admin": {
       "name": "packrat-admin-app",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@elysiajs/eden": "catalog:",
         "@packrat/api-client": "workspace:*",
         "@packrat/app": "workspace:*",
         "@packrat/guards": "workspace:*",
         "@packrat/schemas": "workspace:*",
+        "@packrat/utils": "workspace:*",
         "@packrat/web-ui": "workspace:*",
         "@radix-ui/react-alert-dialog": "catalog:",
         "@radix-ui/react-avatar": "catalog:",
@@ -71,7 +75,7 @@
     },
     "apps/expo": {
       "name": "packrat-expo-app",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@ai-sdk/react": "^3.0.170",
         "@better-auth/expo": "^1.6.9",
@@ -91,6 +95,7 @@
         "@packrat/types": "workspace:*",
         "@packrat/ui": "workspace:*",
         "@packrat/units": "workspace:*",
+        "@packrat/utils": "workspace:*",
         "@react-native-ai/apple": "~0.10.0",
         "@react-native-ai/llama": "~0.10.0",
         "@react-native-async-storage/async-storage": "2.2.0",
@@ -161,7 +166,6 @@
         "llama.rn": "0.10.1",
         "nanoid": "^5.1.9",
         "nativewind": "^4.2.3",
-        "radash": "catalog:",
         "react": "catalog:",
         "react-dom": "catalog:",
         "react-i18next": "^17.0.4",
@@ -210,7 +214,7 @@
     },
     "apps/guides": {
       "name": "packrat-guides-app",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@ai-sdk/openai": "catalog:",
         "@elysiajs/eden": "catalog:",
@@ -219,6 +223,7 @@
         "@packrat/env": "workspace:*",
         "@packrat/guards": "workspace:*",
         "@packrat/schemas": "workspace:*",
+        "@packrat/utils": "workspace:*",
         "@packrat/web-ui": "workspace:*",
         "@radix-ui/react-accordion": "catalog:",
         "@radix-ui/react-alert-dialog": "catalog:",
@@ -299,7 +304,7 @@
     },
     "apps/landing": {
       "name": "packrat-landing-app",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@emotion/is-prop-valid": "^1.3.1",
         "@hookform/resolvers": "catalog:",
@@ -369,12 +374,13 @@
     },
     "apps/trails": {
       "name": "packrat-trails-app",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@packrat/api-client": "workspace:*",
         "@packrat/app": "workspace:*",
         "@packrat/guards": "workspace:*",
         "@packrat/overpass": "workspace:*",
+        "@packrat/utils": "workspace:*",
         "@packrat/web-ui": "workspace:*",
         "@radix-ui/react-dialog": "catalog:",
         "@radix-ui/react-label": "catalog:",
@@ -415,6 +421,7 @@
         "@packrat/app": "workspace:*",
         "@packrat/env": "workspace:*",
         "@packrat/guards": "workspace:*",
+        "@packrat/utils": "workspace:*",
         "@packrat/web-ui": "workspace:*",
         "@tanstack/react-query": "catalog:",
         "@tanstack/react-query-devtools": "catalog:",
@@ -442,14 +449,14 @@
     },
     "packages/analytics": {
       "name": "@packrat/analytics",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@duckdb/node-api": "catalog:",
         "@packrat/env": "workspace:*",
         "@packrat/guards": "workspace:*",
+        "@packrat/utils": "workspace:*",
         "consola": "catalog:",
         "magic-regexp": "catalog:",
-        "radash": "catalog:",
         "zod": "catalog:",
       },
       "devDependencies": {
@@ -459,7 +466,7 @@
     },
     "packages/api": {
       "name": "@packrat/api",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@ai-sdk/google": "^3.0.64",
         "@ai-sdk/openai": "catalog:",
@@ -480,7 +487,8 @@
         "@packrat/schemas": "workspace:*",
         "@packrat/types": "workspace:*",
         "@packrat/units": "workspace:*",
-        "@sentry/cloudflare": "^10.0.0",
+        "@packrat/utils": "workspace:*",
+        "@sentry/cloudflare": "^10.37.0",
         "@sinclair/typebox": "^0.34.15",
         "@types/nodemailer": "^6.4.17",
         "ai": "catalog:",
@@ -496,7 +504,6 @@
         "linkedom": "^0.18.11",
         "nodemailer": "^6.10.0",
         "pg": "catalog:",
-        "radash": "catalog:",
         "resend": "^6.10.0",
         "workers-ai-provider": "^0.7.2",
         "ws": "catalog:",
@@ -523,10 +530,11 @@
     },
     "packages/api-client": {
       "name": "@packrat/api-client",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@elysiajs/eden": "catalog:",
         "@packrat/guards": "workspace:*",
+        "@packrat/utils": "workspace:*",
       },
       "devDependencies": {
         "@packrat/api": "workspace:*",
@@ -541,7 +549,7 @@
     },
     "packages/app": {
       "name": "@packrat/app",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@packrat/api-client": "workspace:*",
         "@packrat/schemas": "workspace:*",
@@ -562,11 +570,11 @@
     },
     "packages/checks": {
       "name": "@packrat/checks",
-      "version": "2.0.26",
+      "version": "2.0.27",
     },
     "packages/cli": {
       "name": "@packrat/cli",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "bin": {
         "packrat": "./src/index.ts",
       },
@@ -576,6 +584,7 @@
         "@packrat/api-client": "workspace:*",
         "@packrat/env": "workspace:*",
         "@packrat/guards": "workspace:*",
+        "@packrat/utils": "workspace:*",
         "chalk": "catalog:",
         "citty": "^0.2.1",
         "cli-table3": "^0.6.5",
@@ -590,21 +599,21 @@
     },
     "packages/config": {
       "name": "@packrat/config",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@packrat/guards": "workspace:*",
       },
     },
     "packages/constants": {
       "name": "@packrat/constants",
-      "version": "0.0.0",
+      "version": "2.0.27",
       "devDependencies": {
         "typescript": "catalog:",
       },
     },
     "packages/db": {
       "name": "@packrat/db",
-      "version": "0.0.0",
+      "version": "2.0.27",
       "dependencies": {
         "@packrat/constants": "workspace:*",
         "drizzle-orm": "catalog:",
@@ -616,27 +625,28 @@
     },
     "packages/env": {
       "name": "@packrat/env",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "zod": "catalog:",
       },
     },
     "packages/guards": {
       "name": "@packrat/guards",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
-        "radash": "catalog:",
+        "@packrat/utils": "workspace:*",
         "ts-extras": "catalog:",
         "zod": "catalog:",
       },
     },
     "packages/mcp": {
       "name": "@packrat/mcp",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@cloudflare/workers-oauth-provider": "^0.4.0",
         "@modelcontextprotocol/sdk": "^1.11.0",
         "@packrat/api-client": "workspace:*",
+        "@packrat/utils": "workspace:*",
         "agents": "^0.11.0",
         "magic-regexp": "catalog:",
         "zod": "catalog:",
@@ -652,7 +662,7 @@
     },
     "packages/osm-db": {
       "name": "@packrat/osm-db",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@neondatabase/serverless": "catalog:",
         "drizzle-orm": "catalog:",
@@ -666,7 +676,7 @@
     },
     "packages/osm-import": {
       "name": "@packrat/osm-import",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@packrat/env": "workspace:*",
         "pg": "catalog:",
@@ -674,7 +684,7 @@
     },
     "packages/overpass": {
       "name": "@packrat/overpass",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@packrat/guards": "workspace:*",
         "zod": "catalog:",
@@ -686,11 +696,12 @@
     },
     "packages/schemas": {
       "name": "@packrat/schemas",
-      "version": "0.0.0",
+      "version": "2.0.27",
       "dependencies": {
         "@packrat/constants": "workspace:*",
         "@packrat/db": "workspace:*",
         "@packrat/guards": "workspace:*",
+        "@packrat/utils": "workspace:*",
         "zod": "catalog:",
       },
       "devDependencies": {
@@ -699,7 +710,7 @@
     },
     "packages/types": {
       "name": "@packrat/types",
-      "version": "0.0.0",
+      "version": "2.0.27",
       "dependencies": {
         "@packrat/constants": "workspace:*",
         "@packrat/schemas": "workspace:*",
@@ -714,14 +725,14 @@
     },
     "packages/ui": {
       "name": "@packrat/ui",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@packrat-ai/nativewindui": "2.0.3-2",
       },
     },
     "packages/units": {
       "name": "@packrat/units",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@packrat/constants": "workspace:*",
         "@packrat/guards": "workspace:*",
@@ -731,9 +742,26 @@
         "vitest": "catalog:",
       },
     },
+    "packages/utils": {
+      "name": "@packrat/utils",
+      "version": "2.0.27",
+      "dependencies": {
+        "destr": "^2.0.5",
+        "es-toolkit": "^1.47.0",
+        "lodash": "^4.18.1",
+        "radash": "catalog:",
+        "radashi": "^12.9.1",
+        "remeda": "^2.37.0",
+        "safe-stable-stringify": "^2.5.0",
+      },
+      "devDependencies": {
+        "@types/lodash": "^4.17.24",
+        "vitest": "catalog:",
+      },
+    },
     "packages/web-ui": {
       "name": "@packrat/web-ui",
-      "version": "2.0.26",
+      "version": "2.0.27",
       "dependencies": {
         "@packrat/guards": "workspace:*",
         "@radix-ui/react-accordion": "catalog:",
@@ -934,6 +962,22 @@
 
     "@appium/types": ["@appium/types@1.4.0", "", { "dependencies": { "@appium/logger": "2.0.7", "@appium/schema": "1.1.1", "@appium/tsconfig": "1.1.2", "type-fest": "5.6.0" } }, "sha512-GeYnDMj1yOIFA8ujOHv0/ZKoZe42F9ldCVSlnEOheYnxqA5ueHGwRI11ifZoIfMBsq7hpU77MAzmu+v9NV1vig=="],
 
+    "@ast-grep/cli": ["@ast-grep/cli@0.43.0", "", { "dependencies": { "detect-libc": "2.1.2" }, "optionalDependencies": { "@ast-grep/cli-darwin-arm64": "0.43.0", "@ast-grep/cli-darwin-x64": "0.43.0", "@ast-grep/cli-linux-arm64-gnu": "0.43.0", "@ast-grep/cli-linux-x64-gnu": "0.43.0", "@ast-grep/cli-win32-arm64-msvc": "0.43.0", "@ast-grep/cli-win32-ia32-msvc": "0.43.0", "@ast-grep/cli-win32-x64-msvc": "0.43.0" }, "bin": { "sg": "sg", "ast-grep": "ast-grep" } }, "sha512-DGi6xXAOBJubGg9QWqTeW8PzKSGHWEOa3uxXspEfYf532yb3lHmNJAcKMl1d+O9Xs9bTcNeDLC8se+O+tirEFQ=="],
+
+    "@ast-grep/cli-darwin-arm64": ["@ast-grep/cli-darwin-arm64@0.43.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-0i63gSBbgriPaRpFsbP3yETxolHPK2JAZbpcGbFOytB7QTnKAguwhlKmIOkUGKfsCzYiEq1awY0EBmvjMONXOg=="],
+
+    "@ast-grep/cli-darwin-x64": ["@ast-grep/cli-darwin-x64@0.43.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-SPkj00HGKpYdqReUmso2ftG5Xgd+bWNFH4i9fubLxsWzn4ey2G6sotPruaOtcrzxb9xH+8kmhN7KJfm1k8Atzg=="],
+
+    "@ast-grep/cli-linux-arm64-gnu": ["@ast-grep/cli-linux-arm64-gnu@0.43.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-U8+2fkcY8sBxNHHBYZ33vTa7C97GFAB+Kj6gFzVMSqK8Ve1Aw+DxhVWD4i/PBryDdmWb4/erjGSkTQtdhVa2vg=="],
+
+    "@ast-grep/cli-linux-x64-gnu": ["@ast-grep/cli-linux-x64-gnu@0.43.0", "", { "os": "linux", "cpu": "x64" }, "sha512-r/o9Mag6OZmGevY9OJjatuUKDOX1rSvgo29qSfxpMbIciiH3hkzEW/2w1xTPZI8xnM7iC+k+CkGoknmoXVTYGg=="],
+
+    "@ast-grep/cli-win32-arm64-msvc": ["@ast-grep/cli-win32-arm64-msvc@0.43.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-oHa4ruD87xccnqFuR+Pmx6F/suHV0YtibuyZ6SxUqgpNJAFZiUNAiFblzhEgQ5gp03e8B012P/Yy/7GYOvxOLg=="],
+
+    "@ast-grep/cli-win32-ia32-msvc": ["@ast-grep/cli-win32-ia32-msvc@0.43.0", "", { "os": "win32", "cpu": "ia32" }, "sha512-RSzz9bKzSEutWgX7/g84guudEp75Q990CYpG/TBasdJP+U27zX8aA9d5p1+o/lF0hw3UoTYuFCGG8PU/QelfNQ=="],
+
+    "@ast-grep/cli-win32-x64-msvc": ["@ast-grep/cli-win32-x64-msvc@0.43.0", "", { "os": "win32", "cpu": "x64" }, "sha512-/5dDD9B65vVuHCdVHN5+tIDquhE5s43S5CgEn88w1BgQaoayf+nRnUO4ZFez6SqyCGqAfa/yZdoaOQ9N2ySa1w=="],
+
     "@aws-crypto/crc32": ["@aws-crypto/crc32@5.2.0", "", { "dependencies": { "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "tslib": "^2.6.2" } }, "sha512-nLbCWqQNgUiwwtFsen1AdzAtvuLRsQS8rYgMuxCrdKf9kOssamGLuPwyTY9wyYblNr9+1XM8v6zoDTPPSIeANg=="],
 
     "@aws-crypto/crc32c": ["@aws-crypto/crc32c@5.2.0", "", { "dependencies": { "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "tslib": "^2.6.2" } }, "sha512-+iWb8qaHLYKrNvGRbiYRHSdKRWhto5XlZUEBwDjYNf+ly5SVYG6zEoYIdxvf5R3zyeP16w4PLBn3rH1xc74Rag=="],
@@ -1564,6 +1608,16 @@
 
     "@jridgewell/trace-mapping": ["@jridgewell/trace-mapping@0.3.31", "", { "dependencies": { "@jridgewell/resolve-uri": "^3.1.0", "@jridgewell/sourcemap-codec": "^1.4.14" } }, "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw=="],
 
+    "@jscpd/badge-reporter": ["@jscpd/badge-reporter@4.2.4", "", { "dependencies": { "badgen": "^3.2.3", "colors": "^1.4.0", "fs-extra": "^11.2.0" } }, "sha512-g5vu05u0lX9rcHA0k3CptLfpOiuMzxh5+mUe2iYRAznTwH3ks6JAVAf9aPi5mBFttMCRiJh2zSt3xnSadHtMGg=="],
+
+    "@jscpd/core": ["@jscpd/core@4.2.4", "", { "dependencies": { "eventemitter3": "^5.0.1" } }, "sha512-9V9YzmmhYg9682kFqi+n0KGOhXNSoqxHbuIP3i/l/oSd6upBOnnSeBWDZMGOenQRQnyKEtCIbnS9YFz+3B+siQ=="],
+
+    "@jscpd/finder": ["@jscpd/finder@4.2.4", "", { "dependencies": { "@jscpd/core": "4.2.4", "@jscpd/tokenizer": "4.2.4", "blamer": "^1.0.6", "bytes": "^3.1.2", "cli-table3": "^0.6.5", "colors": "^1.4.0", "fast-glob": "^3.3.2", "fs-extra": "^11.2.0", "markdown-table": "^2.0.0", "pug": "^3.0.3" } }, "sha512-4LLEuAAmAraud/TAAlB5BByVdWfy7SYiPKacj5yEggpkNs0qsw2kiZ5EyU3LonB+/vntJJEDDpJMmvOeS58e0A=="],
+
+    "@jscpd/html-reporter": ["@jscpd/html-reporter@4.2.4", "", { "dependencies": { "colors": "1.4.0", "fs-extra": "^11.2.0", "pug": "^3.0.3" } }, "sha512-6UljCTVGf7O+o6D6fs1zNBG+vR1PTn47W2mSgb5hzSrvNw60rLrVoAMZMnr/TeIEdd/OEgAu+icbdvvVBfnvJw=="],
+
+    "@jscpd/tokenizer": ["@jscpd/tokenizer@4.2.4", "", { "dependencies": { "@jscpd/core": "4.2.4", "spark-md5": "^3.0.2" } }, "sha512-nM4kGyDvpcevt8t0zOsMQ82ShSc65c3LIQUHClTYwraiOGOmWgUQyen+JIiFCNF8eDCGR2Qa5iI5XBfGWYQzIg=="],
+
     "@legendapp/state": ["@legendapp/state@3.0.0-beta.47", "", { "dependencies": { "use-sync-external-store": "^1.2.2" }, "peerDependencies": { "expo-sqlite": "^15.0.0" }, "optionalPeers": ["expo-sqlite"] }, "sha512-MPgPacXXSoAazAv7ulW/o0ZAtK4YHk3twvXZ241l2HqAHciHozb7tg5SMbEAc2HKUUfC3JBh+9+DXfMsYokLpQ=="],
 
     "@lhci/cli": ["@lhci/cli@0.14.0", "", { "dependencies": { "@lhci/utils": "0.14.0", "chrome-launcher": "^0.13.4", "compression": "^1.7.4", "debug": "^4.3.1", "express": "^4.17.1", "inquirer": "^6.3.1", "isomorphic-fetch": "^3.0.0", "lighthouse": "12.1.0", "lighthouse-logger": "1.2.0", "open": "^7.1.0", "proxy-agent": "^6.4.0", "tmp": "^0.1.0", "uuid": "^8.3.1", "yargs": "^15.4.1", "yargs-parser": "^13.1.2" }, "bin": { "lhci": "./src/cli.js" } }, "sha512-TxOH9pFBnmmN7Jmo2Aimxx5UhE8veqXpHfFJDMWsCVxkwh7mGxcAWchGl84mK139SZbbRmerqZ72c+h2nG9/QQ=="],
@@ -1662,6 +1716,8 @@
 
     "@packrat/units": ["@packrat/units@workspace:packages/units"],
 
+    "@packrat/utils": ["@packrat/utils@workspace:packages/utils"],
+
     "@packrat/web-ui": ["@packrat/web-ui@workspace:packages/web-ui"],
 
     "@paulirish/trace_engine": ["@paulirish/trace_engine@0.0.23", "", {}, "sha512-2ym/q7HhC5K+akXkNV6Gip3oaHpbI6TsGjmcAsl7bcJ528MVbacPQeoauLFEeLXH4ulJvsxQwNDIg/kAEhFZxw=="],
@@ -2152,6 +2208,8 @@
 
     "@tootallnate/quickjs-emscripten": ["@tootallnate/quickjs-emscripten@0.23.0", "", {}, "sha512-C5Mc6rdnsaJDjO3UpGW/CQTHtCKaYlScZTly4JIu97Jxo/odCiH0ITnDXSJPTOrEKk/ycSZ0AOgTmkDtkOsvIA=="],
 
+    "@ts-morph/common": ["@ts-morph/common@0.29.0", "", { "dependencies": { "minimatch": "^10.0.1", "path-browserify": "^1.0.1", "tinyglobby": "^0.2.14" } }, "sha512-35oUmphHbJvQ/+UTwFNme/t2p3FoKiGJ5auTjjpNTop2dyREspirjMy82PLSC1pnDJ8ah1GU98hwpVt64YXQsg=="],
+
     "@tsconfig/node20": ["@tsconfig/node20@20.1.9", "", {}, "sha512-IjlTv1RsvnPtUcjTqtVsZExKVq+KQx4g5pCP5tI7rAs6Xesl2qFwSz/tPDBC4JajkL/MlezBu3gPUwqRHl+RIg=="],
 
     "@turbo/darwin-64": ["@turbo/darwin-64@2.9.16", "", { "os": "darwin", "cpu": "x64" }, "sha512-jLjApWTSNd7JZ5JaLYfelW1ytnGQOvB7ivl+2RD1xQvJTbi8I9gBjzcga7tDZVPyaxpl10YTfJt3BrYXR18KDw=="],
@@ -2230,6 +2288,8 @@
 
     "@types/leaflet": ["@types/leaflet@1.9.21", "", { "dependencies": { "@types/geojson": "*" } }, "sha512-TbAd9DaPGSnzp6QvtYngntMZgcRk+igFELwR2N99XZn7RXUdKgsXMR+28bUO0rPsWp8MIu/f47luLIQuSLYv/w=="],
 
+    "@types/lodash": ["@types/lodash@4.17.24", "", {}, "sha512-gIW7lQLZbue7lRSWEFql49QJJWThrTFFeIMJdp3eH4tKoxm1OvEPg02rm4wCCSHS0cL3/Fizimb35b7k8atwsQ=="],
+
     "@types/mdast": ["@types/mdast@4.0.4", "", { "dependencies": { "@types/unist": "*" } }, "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA=="],
 
     "@types/mdx": ["@types/mdx@2.0.13", "", {}, "sha512-+OWZQfAYyio6YkJb3HLxDrvnx6SWWDbC0zVPfBRzUk0/nqoDyf6dNxQi3eArPe8rJ473nobTMQ/8Zk+LxJ+Yuw=="],
@@ -2248,6 +2308,8 @@
 
     "@types/react-dom": ["@types/react-dom@19.2.3", "", { "peerDependencies": { "@types/react": "^19.2.0" } }, "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ=="],
 
+    "@types/sarif": ["@types/sarif@2.1.7", "", {}, "sha512-kRz0VEkJqWLf1LLVN4pT1cg1Z9wAuvI6L97V3m2f5B76Tg8d413ddvLBPTEHAZJlnn4XSvu0FkZtViCQGVyrXQ=="],
+
     "@types/stack-utils": ["@types/stack-utils@2.0.3", "", {}, "sha512-9aEbYZ3TbYMznPdcdr3SmIrLXwC/AKZXQeCf9Pgao5CKb8CyHuEX5jzWPTkvregvhRJHcpRO6BFoGW9ycaOkYw=="],
 
     "@types/triple-beam": ["@types/triple-beam@1.3.5", "", {}, "sha512-6WaYesThRMCl19iryMYP7/x2OVgCtbIVflDGFpWnb9irXI3UjYE4AzmYuiUKY1AJstGijoY+MgUszMgRxIYTYw=="],
@@ -2418,6 +2480,8 @@
 
     "asap": ["asap@2.0.6", "", {}, "sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA=="],
 
+    "assert-never": ["assert-never@1.4.0", "", {}, "sha512-5oJg84os6NMQNl27T9LnZkvvqzvAnHu03ShCnoj6bsJwS7L8AO4lf+C/XjK/nvzEqQB744moC6V128RucQd1jA=="],
+
     "assertion-error": ["assertion-error@2.0.1", "", {}, "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA=="],
 
     "ast-module-types": ["ast-module-types@6.0.2", "", {}, "sha512-6KuK/7nZ/2Qh7sGuVEiwxjCxzTY2Pdb5mTo5z1e6/J8BA0tvjR7G8vQJKrQMTqwmnA3UPEyKIFX4YUS1DO1Hvw=="],
@@ -2472,6 +2536,10 @@
 
     "babel-preset-jest": ["babel-preset-jest@29.6.3", "", { "dependencies": { "babel-plugin-jest-hoist": "^29.6.3", "babel-preset-current-node-syntax": "^1.0.0" }, "peerDependencies": { "@babel/core": "^7.0.0" } }, "sha512-0B3bhxR6snWXJZtR/RliHTDPRgn1sNHOR0yVtq/IiQFyuOVjFS+wuio/R4gSNkyYmKmJB4wGZv2NZanmKmTnNA=="],
 
+    "babel-walk": ["babel-walk@3.0.0-canary-5", "", { "dependencies": { "@babel/types": "^7.9.6" } }, "sha512-GAwkz0AihzY5bkwIY5QDR+LvsRQgB/B+1foMPvi0FZPMl5fjD7ICiznUiBdLYMH1QYe6vqu4gWYytZOccLouFw=="],
+
+    "badgen": ["badgen@3.3.2", "", {}, "sha512-fbQwK9norfdzbdsoPwbLIAmgBXDGEme3jeIyqPAH7o6vp9lmuLHS7uXULvOiQ6XnMLkYNG4gDjILf74hgtTAug=="],
+
     "bail": ["bail@2.0.2", "", {}, "sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw=="],
 
     "balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
@@ -2522,6 +2590,8 @@
 
     "blake3-wasm": ["blake3-wasm@2.1.5", "", {}, "sha512-F1+K8EbfOZE49dtoPtmxUQrpXaBIl3ICvasLh+nJta0xkz+9kF/7uet9fLnwKqhDrmj6g+6K3Tw9yQPUg2ka5g=="],
 
+    "blamer": ["blamer@1.0.7", "", { "dependencies": { "execa": "^4.0.0", "which": "^2.0.2" } }, "sha512-GbBStl/EVlSWkiJQBZps3H1iARBrC7vt++Jb/TTmCNu/jZ04VW7tSN1nScbFXBUy1AN+jzeL7Zep9sbQxLhXKA=="],
+
     "bluebird": ["bluebird@3.7.2", "", {}, "sha512-XpNj6GDQzdfW+r2Wnn7xiSAd7TM3jzkxGXBGTtWKuSXv1xUV+azxAm8jdWZN06QTQk+2N2XB9jRDkvbmQmcRtg=="],
 
     "body-parser": ["body-parser@2.2.2", "", { "dependencies": { "bytes": "^3.1.2", "content-type": "^1.0.5", "debug": "^4.4.3", "http-errors": "^2.0.0", "iconv-lite": "^0.7.0", "on-finished": "^2.4.1", "qs": "^6.14.1", "raw-body": "^3.0.1", "type-is": "^2.0.1" } }, "sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA=="],
@@ -2588,6 +2658,8 @@
 
     "character-entities-legacy": ["character-entities-legacy@3.0.0", "", {}, "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ=="],
 
+    "character-parser": ["character-parser@2.2.0", "", { "dependencies": { "is-regex": "^1.0.3" } }, "sha512-+UqJQjFEFaTAs3bNsF2j2kEN1baG/zghZbdqoYEDxGZtJo9LBzl1A+m0D4n3qKx8N2FNv8/Xp6yV9mQmBuptaw=="],
+
     "chardet": ["chardet@2.1.1", "", {}, "sha512-PsezH1rqdV9VvyNhxxOW32/d75r01NY7TQCmOqomRo15ZSOKbpTFVsfjghxo6JloQUCGnH4k1LGu0R4yCLlWQQ=="],
 
     "check-error": ["check-error@2.1.3", "", {}, "sha512-PAJdDJusoxnwm1VwW07VWwUN1sl7smmC3OKggvndJFadxxDRyFJBX/ggnu/KE4kQAB7a3Dp8f/YXC1FlUprWmA=="],
@@ -2630,6 +2702,8 @@
 
     "cmdk": ["cmdk@1.1.1", "", { "dependencies": { "@radix-ui/react-compose-refs": "^1.1.1", "@radix-ui/react-dialog": "^1.1.6", "@radix-ui/react-id": "^1.1.0", "@radix-ui/react-primitive": "^2.0.2" }, "peerDependencies": { "react": "^18 || ^19 || ^19.0.0-rc", "react-dom": "^18 || ^19 || ^19.0.0-rc" } }, "sha512-Vsv7kFaXm+ptHDMZ7izaRsP70GgrW9NBNGswt9OZaVBLlE0SNpDq8eu/VGXyF9r7M0azK3Wy7OlYXsuyYLFzHg=="],
 
+    "code-block-writer": ["code-block-writer@13.0.3", "", {}, "sha512-Oofo0pq3IKnsFtuHqSF7TqBfr71aeyZDVJ0HpmqB7FBM2qEigL0iPONSCZSO9pE9dZTAxANe5XHG9Uy0YMv8cg=="],
+
     "color": ["color@4.2.3", "", { "dependencies": { "color-convert": "^2.0.1", "color-string": "^1.9.0" } }, "sha512-1rXeuUUiGGrykh+CeBdu5Ie7OJwinCgQY0bc7GCRxy5xVHy+moaqkpL/jqQq0MtQOeYcrqEz4abc5f0KtU7W4A=="],
 
     "color-convert": ["color-convert@2.0.1", "", { "dependencies": { "color-name": "~1.1.4" } }, "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ=="],
@@ -2638,11 +2712,13 @@
 
     "color-string": ["color-string@1.9.1", "", { "dependencies": { "color-name": "^1.0.0", "simple-swizzle": "^0.2.2" } }, "sha512-shrVawQFojnZv6xM40anx4CkoDP+fZsw/ZerEMsW/pyzsRbElpsL/DBVW7q3ExxwusdNXI3lXpuhEZkzs8p5Eg=="],
 
+    "colors": ["colors@1.4.0", "", {}, "sha512-a+UqTh4kgZg/SlGvfbzDHpgRu7AAQOmmqRHJnxhRZICKFUT91brVhNNt58CMWU9PsBbv3PDCZUHbVxuDiH2mtA=="],
+
     "combined-stream": ["combined-stream@1.0.8", "", { "dependencies": { "delayed-stream": "~1.0.0" } }, "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg=="],
 
     "comma-separated-tokens": ["comma-separated-tokens@2.0.3", "", {}, "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg=="],
 
-    "commander": ["commander@12.1.0", "", {}, "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA=="],
+    "commander": ["commander@5.1.0", "", {}, "sha512-P0CysNDQ7rtVw4QIQtm+MRxV66vKFSvlsQvGYXZWR3qFU0jlMKHZZZgw8e+8DSah4UDKMqnknRDQz+xuQXQ/Zg=="],
 
     "comment-json": ["comment-json@4.6.2", "", { "dependencies": { "array-timsort": "^1.0.3", "esprima": "^4.0.1" } }, "sha512-R2rze/hDX30uul4NZoIZ76ImSJLFxn/1/ZxtKC1L77y2X1k+yYu1joKbAtMA2Fg3hZrTOiw0I5mwVMo0cf250w=="],
 
@@ -2668,6 +2744,8 @@
 
     "console-control-strings": ["console-control-strings@1.1.0", "", {}, "sha512-ty/fTekppD2fIwRvnZAVdeOiGd1c7YXEixbgJTNzqcxJWKQnjJ/V1bNEEE6hygpM3WjwHFUVK6HTjWSzV4a8sQ=="],
 
+    "constantinople": ["constantinople@4.0.1", "", { "dependencies": { "@babel/parser": "^7.6.0", "@babel/types": "^7.6.1" } }, "sha512-vCrqcSIq4//Gx74TXXCGnHpulY1dskqLTFGDmhrGxzeXL8lF8kvXv6mpNWlJj1uD4DW23D4ljAqbY4RRaaUZIw=="],
+
     "content-disposition": ["content-disposition@1.1.0", "", {}, "sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g=="],
 
     "content-type": ["content-type@1.0.5", "", {}, "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA=="],
@@ -2798,6 +2876,8 @@
 
     "dequal": ["dequal@2.0.3", "", {}, "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA=="],
 
+    "destr": ["destr@2.0.5", "", {}, "sha512-ugFTXCtDZunbzasqBxrK93Ik/DRYsO6S/fedkWEMKqt04xZ4csmnmwGDBAb07QWNaGMAmnTIemsYZCksjATwsA=="],
+
     "destroy": ["destroy@1.2.0", "", {}, "sha512-2sJGJTaXIIaR1w4iJSNoN0hnMY7Gpc/n8D4qSCJw8QqFWXf7cuAgnEHxBpweaVcPevC2l3KpjYCx3NypQQgaJg=="],
 
     "detect-indent": ["detect-indent@7.0.2", "", {}, "sha512-y+8xyqdGLL+6sh0tVeHcfP/QDd8gUgbasolJJpY7NgeQGSZ739bDtSiaiDgtoicy+mtYB81dKLxO9xRhCyIB3A=="],
@@ -2846,6 +2926,8 @@
 
     "doctrine": ["doctrine@3.0.0", "", { "dependencies": { "esutils": "^2.0.2" } }, "sha512-yS+Q5i3hBf7GBkd4KG8a7eBNNWNGLTaEwwYWUijIYM7zrlYDM0BFXHjjPWlWZ1Rg7UaddZeIDmi9jF3HmqiQ2w=="],
 
+    "doctypes": ["doctypes@1.1.0", "", {}, "sha512-LLBi6pEqS6Do3EKQ3J0NqHWV5hhb78Pi8vvESYwyOy2c31ZEZVdtitdzsQsKb7878PEERhzUk0ftqGhG6Mz+pQ=="],
+
     "dom-serializer": ["dom-serializer@2.0.0", "", { "dependencies": { "domelementtype": "^2.3.0", "domhandler": "^5.0.2", "entities": "^4.2.0" } }, "sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg=="],
 
     "domelementtype": ["domelementtype@2.3.0", "", {}, "sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw=="],
@@ -2928,7 +3010,7 @@
 
     "es-to-primitive": ["es-to-primitive@1.3.0", "", { "dependencies": { "is-callable": "^1.2.7", "is-date-object": "^1.0.5", "is-symbol": "^1.0.4" } }, "sha512-w+5mJ3GuFL+NjVtJlvydShqE1eN3h3PbI7/5LAsYJP/2qtuMXjfL2LpHSRqo4b4eSF5K/DH1JXKUAHSB2UW50g=="],
 
-    "es-toolkit": ["es-toolkit@1.46.1", "", {}, "sha512-5eNtXOs3tbfxXOj04tjjseeWkRWaoCjdEI+96DgwzZoe6c9juL49pXlzAFTI72aWC9Y8p7168g6XIKjh7k6pyQ=="],
+    "es-toolkit": ["es-toolkit@1.47.0", "", {}, "sha512-n1GuoD0WEQZMBk5tttoZSqwgyLx01oqa5XsBmCHwPyNe1S9jPBEmtR2pSgp2kJuWE3ciFZ6yRHmY4pM4C3OOkw=="],
 
     "esbuild": ["esbuild@0.27.3", "", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.27.3", "@esbuild/android-arm": "0.27.3", "@esbuild/android-arm64": "0.27.3", "@esbuild/android-x64": "0.27.3", "@esbuild/darwin-arm64": "0.27.3", "@esbuild/darwin-x64": "0.27.3", "@esbuild/freebsd-arm64": "0.27.3", "@esbuild/freebsd-x64": "0.27.3", "@esbuild/linux-arm": "0.27.3", "@esbuild/linux-arm64": "0.27.3", "@esbuild/linux-ia32": "0.27.3", "@esbuild/linux-loong64": "0.27.3", "@esbuild/linux-mips64el": "0.27.3", "@esbuild/linux-ppc64": "0.27.3", "@esbuild/linux-riscv64": "0.27.3", "@esbuild/linux-s390x": "0.27.3", "@esbuild/linux-x64": "0.27.3", "@esbuild/netbsd-arm64": "0.27.3", "@esbuild/netbsd-x64": "0.27.3", "@esbuild/openbsd-arm64": "0.27.3", "@esbuild/openbsd-x64": "0.27.3", "@esbuild/openharmony-arm64": "0.27.3", "@esbuild/sunos-x64": "0.27.3", "@esbuild/win32-arm64": "0.27.3", "@esbuild/win32-ia32": "0.27.3", "@esbuild/win32-x64": "0.27.3" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg=="],
 
@@ -3006,6 +3088,8 @@
 
     "exact-mirror": ["exact-mirror@0.2.7", "", { "peerDependencies": { "@sinclair/typebox": "^0.34.15" }, "optionalPeers": ["@sinclair/typebox"] }, "sha512-+MeEmDcLA4o/vjK2zujgk+1VTxPR4hdp23qLqkWfStbECtAq9gmsvQa3LW6z/0GXZyHJobrCnmy1cdeE7BjsYg=="],
 
+    "execa": ["execa@4.1.0", "", { "dependencies": { "cross-spawn": "^7.0.0", "get-stream": "^5.0.0", "human-signals": "^1.1.1", "is-stream": "^2.0.0", "merge-stream": "^2.0.0", "npm-run-path": "^4.0.0", "onetime": "^5.1.0", "signal-exit": "^3.0.2", "strip-final-newline": "^2.0.0" } }, "sha512-j5W0//W7f8UxAn8hXVnwG8tLwdiUy4FJLcSupCg6maBYZDpyBvTApK7KyuI4bKj8KOh1r2YH+6ucuYtJv1bTZA=="],
+
     "exit-hook": ["exit-hook@2.2.1", "", {}, "sha512-eNTPlAD67BmP31LDINZ3U7HSF8l57TxOY2PmBJ1shpCvpnxBF93mWCE8YHBnXs8qiUZJc9WDcWIeC3a2HIAMfw=="],
 
     "expect-type": ["expect-type@1.3.0", "", {}, "sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA=="],
@@ -3238,7 +3322,7 @@
 
     "get-stdin": ["get-stdin@4.0.1", "", {}, "sha512-F5aQMywwJ2n85s4hJPTT9RPxGmubonuB10MNYo17/xph174n2MIR33HRguhzVag10O/npM7SPk73LMZNP+FaWw=="],
 
-    "get-stream": ["get-stream@9.0.1", "", { "dependencies": { "@sec-ant/readable-stream": "^0.4.1", "is-stream": "^4.0.1" } }, "sha512-kVCxPF3vQM/N0B1PmoqVUqgHP+EeVjmZSQn+1oCRPxd2P21P2F19lIgbR3HBosbB1PUhOAoctJnfEn2GbN2eZA=="],
+    "get-stream": ["get-stream@5.2.0", "", { "dependencies": { "pump": "^3.0.0" } }, "sha512-nBF+F1rAZVCu/p7rjzgA+Yb4lfYXrpl7a6VmJrU8wF9I1CKvP/QwPNZHnOlwbTkY6dvtFIzFMSyQXbLoTQPRpA=="],
 
     "get-symbol-description": ["get-symbol-description@1.1.0", "", { "dependencies": { "call-bound": "^1.0.3", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.6" } }, "sha512-w9UMqWwJxHNOvoNzSJ2oPF5wvYcvP7jUvYzhp67yEhTi17ZDBBC1z9pTdGuzjD+EFIqLSYRweZjqfiPzQ06Ebg=="],
 
@@ -3336,6 +3420,8 @@
 
     "https-proxy-agent": ["https-proxy-agent@7.0.6", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "4" } }, "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw=="],
 
+    "human-signals": ["human-signals@1.1.1", "", {}, "sha512-SEQu7vl8KjNL2eoGBLF3+wAjpsNfA9XMlXAYj/3EdaNfAlxKthD1xjEQfGOUhllCGGJVNY34bRr6lPINhNjyZw=="],
+
     "hyphenate-style-name": ["hyphenate-style-name@1.1.0", "", {}, "sha512-WDC/ui2VVRrz3jOVi+XtjqkDjiVjTtFaAGiW37k6b+ohyQ5wYDOGkvCZa8+H0nx3gyvv0+BST9xuOgIyGQ00gw=="],
 
     "i": ["i@0.3.7", "", {}, "sha512-FYz4wlXgkQwIPqhzC5TdNMLSE5+GS1IIDJZY/1ZiEPCT2S3COUVZeT5OW4BmW4r5LHLQuOosSwsvnroG9GR59Q=="],
@@ -3410,6 +3496,8 @@
 
     "is-docker": ["is-docker@2.2.1", "", { "bin": { "is-docker": "cli.js" } }, "sha512-F+i2BKsFrH66iaUFc0woD8sLy8getkwTwtOBjvs56Cx4CgJDeKQeqfz8wAYiSb8JOprWhHH5p77PbmYCvvUuXQ=="],
 
+    "is-expression": ["is-expression@4.0.0", "", { "dependencies": { "acorn": "^7.1.1", "object-assign": "^4.1.1" } }, "sha512-zMIXX63sxzG3XrkHkrAPvm/OVZVSCPNkwMHU8oTX7/U3AL78I0QXCEICXUM13BIa8TYGZ68PiTKfQz3yaTNr4A=="],
+
     "is-extendable": ["is-extendable@0.1.1", "", {}, "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw=="],
 
     "is-extglob": ["is-extglob@2.1.1", "", {}, "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ=="],
@@ -3530,12 +3618,18 @@
 
     "js-library-detector": ["js-library-detector@6.7.0", "", {}, "sha512-c80Qupofp43y4cJ7+8TTDN/AsDwLi5oOm/plBrWI+iQt485vKXCco+yVmOwEgdo9VOdsYTuV0UlTeetVPTriXA=="],
 
+    "js-stringify": ["js-stringify@1.0.2", "", {}, "sha512-rtS5ATOo2Q5k1G+DADISilDA6lv79zIiwFd6CcjuIxGKLFm5C+RLImRscVap9k55i+MOZwgliw+NejvkLuGD5g=="],
+
     "js-tokens": ["js-tokens@4.0.0", "", {}, "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ=="],
 
     "js-yaml": ["js-yaml@3.14.2", "", { "dependencies": { "argparse": "^1.0.7", "esprima": "^4.0.0" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg=="],
 
     "jsc-safe-url": ["jsc-safe-url@0.2.4", "", {}, "sha512-0wM3YBWtYePOjfyXQH5MWQ8H7sdk5EXSwZvmSLKk2RboVQ2Bu239jycHDz5J/8Blf3K0Qnoy2b6xD+z10MFB+Q=="],
 
+    "jscpd": ["jscpd@4.2.4", "", { "dependencies": { "@jscpd/badge-reporter": "4.2.4", "@jscpd/core": "4.2.4", "@jscpd/finder": "4.2.4", "@jscpd/html-reporter": "4.2.4", "@jscpd/tokenizer": "4.2.4", "colors": "^1.4.0", "commander": "^5.0.0", "fs-extra": "^11.2.0", "jscpd-sarif-reporter": "4.2.4" }, "bin": { "jscpd": "bin/jscpd" } }, "sha512-PSo2U0G8OxULayGyQMv7T/0ZQ+c3PPltdMOz/57v9Xnmq5xSIhh4cnZ0oYZPKqejy10aFwAbMVxqAlo24+PQ3g=="],
+
+    "jscpd-sarif-reporter": ["jscpd-sarif-reporter@4.2.4", "", { "dependencies": { "colors": "^1.4.0", "fs-extra": "^11.2.0", "node-sarif-builder": "^3.4.0" } }, "sha512-JtX79kFSyAhqJh5TdLUcvtYJtJd1F8UW8b4Miaga+EIgUn2/nR0N2zWL9mH5cRXgbzLuQbbsw9kReUVIECApwQ=="],
+
     "jsesc": ["jsesc@3.1.0", "", { "bin": { "jsesc": "bin/jsesc" } }, "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA=="],
 
     "jsftp": ["jsftp@2.1.3", "", { "dependencies": { "debug": "^3.1.0", "ftp-response-parser": "^1.0.1", "once": "^1.4.0", "parse-listing": "^1.1.3", "stream-combiner": "^0.2.2", "unorm": "^1.4.1" } }, "sha512-r79EVB8jaNAZbq8hvanL8e8JGu2ZNr2bXdHC4ZdQhRImpSPpnWwm5DYVzQ5QxJmtGtKhNNuvqGgbNaFl604fEQ=="],
@@ -3558,6 +3652,8 @@
 
     "jsonfile": ["jsonfile@6.2.1", "", { "dependencies": { "universalify": "^2.0.0" }, "optionalDependencies": { "graceful-fs": "^4.1.6" } }, "sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q=="],
 
+    "jstransformer": ["jstransformer@1.0.0", "", { "dependencies": { "is-promise": "^2.0.0", "promise": "^7.0.1" } }, "sha512-C9YK3Rf8q6VAPDCCU9fnqo3mAfOH6vUGnMcP4AQAYIEpWtfGLpwOTmZ+igtdK5y+VvI2n3CyYSzy4Qh34eq24A=="],
+
     "jsx-ast-utils": ["jsx-ast-utils@3.3.5", "", { "dependencies": { "array-includes": "^3.1.6", "array.prototype.flat": "^1.3.1", "object.assign": "^4.1.4", "object.values": "^1.1.6" } }, "sha512-ZZow9HBI5O6EPgSJLUb8n2NKgmVWTwCvHGwFuJlMjvLFqlGG6pjirPhtdsseaLZjSibD8eegzmYpUZwoIlj2cQ=="],
 
     "jwa": ["jwa@2.0.1", "", { "dependencies": { "buffer-equal-constant-time": "^1.0.1", "ecdsa-sig-formatter": "1.0.11", "safe-buffer": "^5.0.1" } }, "sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg=="],
@@ -3702,7 +3798,7 @@
 
     "markdown-it": ["markdown-it@13.0.2", "", { "dependencies": { "argparse": "^2.0.1", "entities": "~3.0.1", "linkify-it": "^4.0.1", "mdurl": "^1.0.1", "uc.micro": "^1.0.5" }, "bin": { "markdown-it": "bin/markdown-it.js" } }, "sha512-FtwnEuuK+2yVU7goGn/MJ0WBZMM9ZPgU9spqlFs7/A/pDIUNSOQZhUgOqYCficIuR2QaFnrt8LHqBWsbTAoI5w=="],
 
-    "markdown-table": ["markdown-table@3.0.4", "", {}, "sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw=="],
+    "markdown-table": ["markdown-table@2.0.0", "", { "dependencies": { "repeat-string": "^1.0.0" } }, "sha512-Ezda85ToJUBhM6WGaG6veasyym+Tbs3cMAw/ZhOPqXiYsr0jgocBV3j3nx+4lk47plLlIqjwuTm/ywVI+zjJ/A=="],
 
     "marky": ["marky@1.3.0", "", {}, "sha512-ocnPZQLNpvbedwTy9kNrQEsknEfgvcLMvOtz3sFeWApDq1MXH1TqkCIx58xlpESsfwQOnuBO9beyQuNGzVvuhQ=="],
 
@@ -3852,7 +3948,7 @@
 
     "mimetext": ["mimetext@3.0.28", "", { "dependencies": { "@babel/runtime": "^7.26.0", "@babel/runtime-corejs3": "^7.26.0", "js-base64": "^3.7.7", "mime-types": "^2.1.35" } }, "sha512-eQXpbNrtxLCjUtiVbR/qR09dbPgZ2o+KR1uA7QKqGhbn8QV7HIL16mXXsobBL4/8TqoYh1us31kfz+dNfCev9g=="],
 
-    "mimic-fn": ["mimic-fn@1.2.0", "", {}, "sha512-jf84uxzwiuiIVKiOLpfYk7N46TSy8ubTonmneY9vrpHNAnp0QBt2BxWV9dO3/j+BoVAb+a5G6YDPW3M5HOdMWQ=="],
+    "mimic-fn": ["mimic-fn@2.1.0", "", {}, "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg=="],
 
     "miniflare": ["miniflare@4.20250906.0", "", { "dependencies": { "@cspotcode/source-map-support": "0.8.1", "acorn": "8.14.0", "acorn-walk": "8.3.2", "exit-hook": "2.2.1", "glob-to-regexp": "0.4.1", "sharp": "^0.33.5", "stoppable": "1.1.0", "undici": "^7.10.0", "workerd": "1.20250906.0", "ws": "8.18.0", "youch": "4.1.0-beta.10", "zod": "3.22.3" }, "bin": { "miniflare": "bootstrap.js" } }, "sha512-T/RWn1sa0ien80s6NjU+Un/tj12gR6wqScZoiLeMJDD4/fK0UXfnbWXJDubnUED8Xjm7RPQ5ESYdE+mhPmMtuQ=="],
 
@@ -3920,6 +4016,8 @@
 
     "node-releases": ["node-releases@2.0.44", "", {}, "sha512-5WUyunoPMsvvEhS8AxHtRzP+oA8UCkJ7YRxatWKjngndhDGLiqEVAQKWjFAiAiuL8zMRGzGSJxFnLetoa43qGQ=="],
 
+    "node-sarif-builder": ["node-sarif-builder@3.4.0", "", { "dependencies": { "@types/sarif": "^2.1.7", "fs-extra": "^11.1.1" } }, "sha512-tGnJW6OKRii9u/b2WiUViTJS+h7Apxx17qsMUjsUeNDiMMX5ZFf8F8Fcz7PAQ6omvOxHZtvDTmOYKJQwmfpjeg=="],
+
     "node-source-walk": ["node-source-walk@7.0.2", "", { "dependencies": { "@babel/parser": "^7.29.0" } }, "sha512-71kFFjYaSshDTA8/a2HiTYPLdASWjLJxUyJxGE+ffxU+KhxSBtM9kiLUX+R2yooFdSFKMFpi4n3PFtDy6qXv8A=="],
 
     "nodemailer": ["nodemailer@6.10.1", "", {}, "sha512-Z+iLaBGVaSjbIzQ4pX6XV41HrooLsQ10ZWPUehGmuantvzWoDVBnmsdUcOIDM1t+yPor5pDhVlDESgOMEGxhHA=="],
@@ -3930,6 +4028,8 @@
 
     "npm-package-arg": ["npm-package-arg@11.0.3", "", { "dependencies": { "hosted-git-info": "^7.0.0", "proc-log": "^4.0.0", "semver": "^7.3.5", "validate-npm-package-name": "^5.0.0" } }, "sha512-sHGJy8sOC1YraBywpzQlIKBE4pBbGbiF95U6Auspzyem956E0+FtDtsx1ZxlOJkQCZ1AFXAY/yuvtFYrOxF+Bw=="],
 
+    "npm-run-path": ["npm-run-path@4.0.1", "", { "dependencies": { "path-key": "^3.0.0" } }, "sha512-S48WzZW777zhNIrn7gxOlISNAqi9ZC/uQFnRdbeIHhZhCA6UqpkOT8T1G7BvfdgP4Er8gF4sUbaS0i7QvIfCWw=="],
+
     "nth-check": ["nth-check@2.1.1", "", { "dependencies": { "boolbase": "^1.0.0" } }, "sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w=="],
 
     "nullthrows": ["nullthrows@1.1.1", "", {}, "sha512-2vPPEi+Z7WqML2jZYddDIfy5Dqb0r2fze2zTxNNknZaFpVHU3mFB3R+DWeJWGVx0ecvttSGlJTI+WG+8Z4cDWw=="],
@@ -3968,7 +4068,7 @@
 
     "one-time": ["one-time@1.0.0", "", { "dependencies": { "fn.name": "1.x.x" } }, "sha512-5DXOiRKwuSEcQ/l0kGCF6Q3jcADFv5tSmRaJck/OqkVFcOzutB134KRSfF0xDrL39MNnqxbHBbUUcjZIhTgb2g=="],
 
-    "onetime": ["onetime@2.0.1", "", { "dependencies": { "mimic-fn": "^1.0.0" } }, "sha512-oyyPpiMaKARvvcgip+JV+7zci5L8D1W9RZIz2l1o08AM3pfspitVWnPt3mzHcBPp12oYMTy0pqrFs/C+m3EwsQ=="],
+    "onetime": ["onetime@5.1.2", "", { "dependencies": { "mimic-fn": "^2.1.0" } }, "sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg=="],
 
     "open": ["open@7.4.2", "", { "dependencies": { "is-docker": "^2.0.0", "is-wsl": "^2.1.1" } }, "sha512-MVHddDVweXZF3awtlAS+6pgKLlm/JgxZ90+/NBurBoQctVOOB/zDdVjcyPzQ+0laDGbsWgrRkflI65sQeOgT9Q=="],
 
@@ -4040,6 +4140,8 @@
 
     "path": ["path@0.12.7", "", { "dependencies": { "process": "^0.11.1", "util": "^0.10.3" } }, "sha512-aXXC6s+1w7otVF9UletFkFcDsJeO7lSZBPUQhtb5O0xJe8LtYhj/GxldoL09bBj9+ZmE2hNoHqQSFMN5fikh4Q=="],
 
+    "path-browserify": ["path-browserify@1.0.1", "", {}, "sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g=="],
+
     "path-exists": ["path-exists@4.0.0", "", {}, "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w=="],
 
     "path-is-absolute": ["path-is-absolute@1.0.1", "", {}, "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg=="],
@@ -4170,6 +4272,30 @@
 
     "proxy-from-env": ["proxy-from-env@1.1.0", "", {}, "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg=="],
 
+    "pug": ["pug@3.0.4", "", { "dependencies": { "pug-code-gen": "^3.0.4", "pug-filters": "^4.0.0", "pug-lexer": "^5.0.1", "pug-linker": "^4.0.0", "pug-load": "^3.0.0", "pug-parser": "^6.0.0", "pug-runtime": "^3.0.1", "pug-strip-comments": "^2.0.0" } }, "sha512-kFfq5mMzrS7+wrl5pLJzZEzemx34OQ0w4SARfhy/3yxTlhbstsudDwJzhf1hP02yHzbjoVMSXUj/Sz6RNfMyXg=="],
+
+    "pug-attrs": ["pug-attrs@3.0.0", "", { "dependencies": { "constantinople": "^4.0.1", "js-stringify": "^1.0.2", "pug-runtime": "^3.0.0" } }, "sha512-azINV9dUtzPMFQktvTXciNAfAuVh/L/JCl0vtPCwvOA21uZrC08K/UnmrL+SXGEVc1FwzjW62+xw5S/uaLj6cA=="],
+
+    "pug-code-gen": ["pug-code-gen@3.0.4", "", { "dependencies": { "constantinople": "^4.0.1", "doctypes": "^1.1.0", "js-stringify": "^1.0.2", "pug-attrs": "^3.0.0", "pug-error": "^2.1.0", "pug-runtime": "^3.0.1", "void-elements": "^3.1.0", "with": "^7.0.0" } }, "sha512-6okWYIKdasTyXICyEtvobmTZAVX57JkzgzIi4iRJlin8kmhG+Xry2dsus+Mun/nGCn6F2U49haHI5mkELXB14g=="],
+
+    "pug-error": ["pug-error@2.1.0", "", {}, "sha512-lv7sU9e5Jk8IeUheHata6/UThZ7RK2jnaaNztxfPYUY+VxZyk/ePVaNZ/vwmH8WqGvDz3LrNYt/+gA55NDg6Pg=="],
+
+    "pug-filters": ["pug-filters@4.0.0", "", { "dependencies": { "constantinople": "^4.0.1", "jstransformer": "1.0.0", "pug-error": "^2.0.0", "pug-walk": "^2.0.0", "resolve": "^1.15.1" } }, "sha512-yeNFtq5Yxmfz0f9z2rMXGw/8/4i1cCFecw/Q7+D0V2DdtII5UvqE12VaZ2AY7ri6o5RNXiweGH79OCq+2RQU4A=="],
+
+    "pug-lexer": ["pug-lexer@5.0.1", "", { "dependencies": { "character-parser": "^2.2.0", "is-expression": "^4.0.0", "pug-error": "^2.0.0" } }, "sha512-0I6C62+keXlZPZkOJeVam9aBLVP2EnbeDw3An+k0/QlqdwH6rv8284nko14Na7c0TtqtogfWXcRoFE4O4Ff20w=="],
+
+    "pug-linker": ["pug-linker@4.0.0", "", { "dependencies": { "pug-error": "^2.0.0", "pug-walk": "^2.0.0" } }, "sha512-gjD1yzp0yxbQqnzBAdlhbgoJL5qIFJw78juN1NpTLt/mfPJ5VgC4BvkoD3G23qKzJtIIXBbcCt6FioLSFLOHdw=="],
+
+    "pug-load": ["pug-load@3.0.0", "", { "dependencies": { "object-assign": "^4.1.1", "pug-walk": "^2.0.0" } }, "sha512-OCjTEnhLWZBvS4zni/WUMjH2YSUosnsmjGBB1An7CsKQarYSWQ0GCVyd4eQPMFJqZ8w9xgs01QdiZXKVjk92EQ=="],
+
+    "pug-parser": ["pug-parser@6.0.0", "", { "dependencies": { "pug-error": "^2.0.0", "token-stream": "1.0.0" } }, "sha512-ukiYM/9cH6Cml+AOl5kETtM9NR3WulyVP2y4HOU45DyMim1IeP/OOiyEWRr6qk5I5klpsBnbuHpwKmTx6WURnw=="],
+
+    "pug-runtime": ["pug-runtime@3.0.1", "", {}, "sha512-L50zbvrQ35TkpHwv0G6aLSuueDRwc/97XdY8kL3tOT0FmhgG7UypU3VztfV/LATAvmUfYi4wNxSajhSAeNN+Kg=="],
+
+    "pug-strip-comments": ["pug-strip-comments@2.0.0", "", { "dependencies": { "pug-error": "^2.0.0" } }, "sha512-zo8DsDpH7eTkPHCXFeAk1xZXJbyoTfdPlNR0bK7rpOMuhBYb0f5qUVCO1xlsitYd3w5FQTK7zpNVKb3rZoUrrQ=="],
+
+    "pug-walk": ["pug-walk@2.0.0", "", {}, "sha512-yYELe9Q5q9IQhuvqsZNwA5hfPkMJ8u92bQLIMcsMxf/VADjNtEYptU+inlufAFYcWdHlwNfZOEnOOQrZrcyJCQ=="],
+
     "pump": ["pump@3.0.4", "", { "dependencies": { "end-of-stream": "^1.1.0", "once": "^1.3.1" } }, "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA=="],
 
     "punycode": ["punycode@2.3.1", "", {}, "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg=="],
@@ -4188,6 +4314,8 @@
 
     "radash": ["radash@12.1.1", "", {}, "sha512-h36JMxKRqrAxVD8201FrCpyeNuUY9Y5zZwujr20fFO77tpUtGa6EZzfKw/3WaiBX95fq7+MpsuMLNdSnORAwSA=="],
 
+    "radashi": ["radashi@12.9.1", "", {}, "sha512-HCvrL1Ag7qnyH11UiSWQaEIiizJ7kldHjBw63aELoum7C8nQrSLqotLDuKKvoRPtO0w8azCzUQcL3yrU3lBksw=="],
+
     "range-parser": ["range-parser@1.2.1", "", {}, "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg=="],
 
     "raw-body": ["raw-body@3.0.2", "", { "dependencies": { "bytes": "~3.1.2", "http-errors": "~2.0.1", "iconv-lite": "~0.7.0", "unpipe": "~1.0.0" } }, "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA=="],
@@ -4322,6 +4450,10 @@
 
     "remark-stringify": ["remark-stringify@11.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-to-markdown": "^2.0.0", "unified": "^11.0.0" } }, "sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw=="],
 
+    "remeda": ["remeda@2.37.0", "", {}, "sha512-wN6BXWua0t4o7vDamqc27J3VRxnokG9cDezsFN2nOnt2JD/IkJQHTYqM6UvmEctAZETAoviwEFQZJO3kZ4Ohew=="],
+
+    "repeat-string": ["repeat-string@1.6.1", "", {}, "sha512-PV0dzCYDNfRi1jCDbJzpW7jNNDRuCOG/jI5ctQcGKt/clZD+YcPS3yIlWuTJMmESC8aevCFmWJy5wjAFgNqN6w=="],
+
     "repeating": ["repeating@2.0.1", "", { "dependencies": { "is-finite": "^1.0.0" } }, "sha512-ZqtSMuVybkISo2OWvqvm7iHSWngvdaW3IpsT9/uP8v4gMi591LY6h35wdOfvQdWCKFWZWm2Y1Opp4kV7vQKT6A=="],
 
     "require-directory": ["require-directory@2.1.1", "", {}, "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q=="],
@@ -4474,6 +4606,8 @@
 
     "space-separated-tokens": ["space-separated-tokens@2.0.2", "", {}, "sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q=="],
 
+    "spark-md5": ["spark-md5@3.0.2", "", {}, "sha512-wcFzz9cDfbuqe0FZzfi2or1sgyIrsDwmPwfZC4hiNidPdPINjeUwNfv5kldczoEAcjl9Y1L3SM7Uz2PUEQzxQw=="],
+
     "spawn-command": ["spawn-command@0.0.2", "", {}, "sha512-zC8zGoGkmc8J9ndvml8Xksr1Amk9qBujgbF0JAIWO7kXr43w0h/0GJNM/Vustixu+YE8N/MTrQ7N31FvHUACxQ=="],
 
     "spdx-correct": ["spdx-correct@3.2.0", "", { "dependencies": { "spdx-expression-parse": "^3.0.0", "spdx-license-ids": "^3.0.0" } }, "sha512-kN9dJbvnySHULIluDHy32WHRUu3Og7B9sbY7tsFLctQkIqnMh3hErYgdMjTYuqmcXX+lK5T1lnUt3G7zNswmZA=="],
@@ -4552,6 +4686,8 @@
 
     "strip-bom-string": ["strip-bom-string@1.0.0", "", {}, "sha512-uCC2VHvQRYu+lMh4My/sFNmF2klFymLX1wHJeXnbEJERpV/ZsVuonzerjfrGpIGF7LBVa1O7i9kjiWvJiFck8g=="],
 
+    "strip-final-newline": ["strip-final-newline@2.0.0", "", {}, "sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA=="],
+
     "strip-indent": ["strip-indent@1.0.1", "", { "dependencies": { "get-stdin": "^4.0.1" }, "bin": { "strip-indent": "cli.js" } }, "sha512-I5iQq6aFMM62fBEAIB/hXzwJD6EEZ0xEGCX2t7oXqaKPIRgt4WruAQ285BISgdkP+HLGWyeGmNJcpIwFeRYRUA=="],
 
     "strip-json-comments": ["strip-json-comments@3.1.1", "", {}, "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig=="],
@@ -4648,6 +4784,8 @@
 
     "toidentifier": ["toidentifier@1.0.1", "", {}, "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA=="],
 
+    "token-stream": ["token-stream@1.0.0", "", {}, "sha512-VSsyNPPW74RpHwR8Fc21uubwHY7wMDeJLys2IX5zJNih+OnAnaifKHo+1LHT7DAdloQ7apeaaWg8l7qnf/TnEg=="],
+
     "token-types": ["token-types@6.1.2", "", { "dependencies": { "@borewit/text-codec": "^0.2.1", "@tokenizer/token": "^0.3.0", "ieee754": "^1.2.1" } }, "sha512-dRXchy+C0IgK8WPC6xvCHFRIWYUbqqdEIKPaKo/AcTUNzwLTK6AH7RjdLWsEZcAN/TBdtfUw3PYEgPr5VPr6ww=="],
 
     "toqr": ["toqr@0.1.1", "", {}, "sha512-FWAPzCIHZHnrE/5/w9MPk0kK25hSQSH2IKhYh9PyjS3SG/+IEMvlwIHbhz+oF7xl54I+ueZlVnMjyzdSwLmAwA=="],
@@ -4674,6 +4812,8 @@
 
     "ts-interface-checker": ["ts-interface-checker@0.1.13", "", {}, "sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA=="],
 
+    "ts-morph": ["ts-morph@28.0.0", "", { "dependencies": { "@ts-morph/common": "~0.29.0", "code-block-writer": "^13.0.3" } }, "sha512-Wp3tnZ2bzwxyTZMtgWVzXDfm7lB1Drz+y9DmmYH/L702PQhPyVrp3pkou3yIz4qjS14GY9kcpmLiOOMvl8oG1g=="],
+
     "tsconfck": ["tsconfck@3.1.6", "", { "peerDependencies": { "typescript": "^5.0.0" }, "optionalPeers": ["typescript"], "bin": { "tsconfck": "bin/tsconfck.js" } }, "sha512-ks6Vjr/jEw0P1gmOVwutM3B7fWxoWBL2KRDb1JfqGVawBmO5UsvmWOQFGHBPl5yxYz4eERr19E6L7NMv+Fej4w=="],
 
     "tsconfig-paths": ["tsconfig-paths@3.15.0", "", { "dependencies": { "@types/json5": "^0.0.29", "json5": "^1.0.2", "minimist": "^1.2.6", "strip-bom": "^3.0.0" } }, "sha512-2Ac2RgzDe/cn48GvOe3M+o82pEFewD3UPbyoUHHdKasHwJKjds4fLXWf/Ux5kATBKN20oaFGu+jbElp1pos0mg=="],
@@ -4854,6 +4994,8 @@
 
     "winston-transport": ["winston-transport@4.9.0", "", { "dependencies": { "logform": "^2.7.0", "readable-stream": "^3.6.2", "triple-beam": "^1.3.0" } }, "sha512-8drMJ4rkgaPo1Me4zD/3WLfI/zPdA9o2IipKODunnGDcuqbHwjsbB79ylv04LCGGzU0xQ6vTznOMpQGaLhhm6A=="],
 
+    "with": ["with@7.0.2", "", { "dependencies": { "@babel/parser": "^7.9.6", "@babel/types": "^7.9.6", "assert-never": "^1.2.1", "babel-walk": "3.0.0-canary-5" } }, "sha512-RNGKj82nUPg3g5ygxkQl0R937xLyho1J24ItRCBTr/m1YnZkzJy1hUiHUJrc/VlsDQzsCnInEGSg3bci0Lmd4w=="],
+
     "word-wrap": ["word-wrap@1.2.5", "", {}, "sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA=="],
 
     "workerd": ["workerd@1.20260515.1", "", { "optionalDependencies": { "@cloudflare/workerd-darwin-64": "1.20260515.1", "@cloudflare/workerd-darwin-arm64": "1.20260515.1", "@cloudflare/workerd-linux-64": "1.20260515.1", "@cloudflare/workerd-linux-arm64": "1.20260515.1", "@cloudflare/workerd-windows-64": "1.20260515.1" }, "bin": { "workerd": "bin/workerd" } }, "sha512-MjKOJLcvU45xXedQowvuiHtJTxu4WTHYQeIlF7YmjuqhiI6dImTFxWCEoRQHiskztxuVSNEmdO7/0UfDu6OMnQ=="],
@@ -4950,6 +5092,8 @@
 
     "@appium/support/bplist-creator": ["bplist-creator@0.1.1", "", { "dependencies": { "stream-buffers": "2.2.x" } }, "sha512-Ese7052fdWrxp/vqSJkydgx/1MdBnNOCV2XVfbmdGWD2H6EYza+Q4pyYSuVSnCUD22hfI/BFI4jHaC3NLXLlJQ=="],
 
+    "@appium/support/get-stream": ["get-stream@9.0.1", "", { "dependencies": { "@sec-ant/readable-stream": "^0.4.1", "is-stream": "^4.0.1" } }, "sha512-kVCxPF3vQM/N0B1PmoqVUqgHP+EeVjmZSQn+1oCRPxd2P21P2F19lIgbR3HBosbB1PUhOAoctJnfEn2GbN2eZA=="],
+
     "@appium/support/glob": ["glob@13.0.5", "", { "dependencies": { "minimatch": "^10.2.1", "minipass": "^7.1.2", "path-scurry": "^2.0.0" } }, "sha512-BzXxZg24Ibra1pbQ/zE7Kys4Ua1ks7Bn6pKLkVPZ9FZe4JQS6/Q7ef3LG1H+k7lUf5l4T3PLSyYyYJVYUvfgTw=="],
 
     "@appium/support/log-symbols": ["log-symbols@7.0.1", "", { "dependencies": { "is-unicode-supported": "^2.0.0", "yoctocolors": "^2.1.1" } }, "sha512-ja1E3yCr9i/0hmBVaM0bfwDjnGy8I/s6PP4DFp+yP+a+mrHO4Rm7DtmnqROTUkHIkqffC84YY7AeqX6oFk0WFg=="],
@@ -5356,6 +5500,8 @@
 
     "eslint-utils/eslint-visitor-keys": ["eslint-visitor-keys@1.3.0", "", {}, "sha512-6J72N8UNa462wa/KFODt/PJ3IU60SDpC3QXC1Hjc1BXXpfL2C9R5+AU7jhe0F6GREqVMh4Juu+NY7xn+6dipUQ=="],
 
+    "execa/signal-exit": ["signal-exit@3.0.7", "", {}, "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ=="],
+
     "expo-modules-autolinking/chalk": ["chalk@4.1.2", "", { "dependencies": { "ansi-styles": "^4.1.0", "supports-color": "^7.1.0" } }, "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA=="],
 
     "expo-modules-autolinking/commander": ["commander@7.2.0", "", {}, "sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw=="],
@@ -5378,8 +5524,6 @@
 
     "external-editor/tmp": ["tmp@0.0.33", "", { "dependencies": { "os-tmpdir": "~1.0.2" } }, "sha512-jRCJlojKnZ3addtTOjdIqoRuPEKBvNXcGYqzO6zWZX8KfKEpnGY5jfggJQ3EjKuu8D4bJRr0y+cYJFmYbImXGw=="],
 
-    "extract-zip/get-stream": ["get-stream@5.2.0", "", { "dependencies": { "pump": "^3.0.0" } }, "sha512-nBF+F1rAZVCu/p7rjzgA+Yb4lfYXrpl7a6VmJrU8wF9I1CKvP/QwPNZHnOlwbTkY6dvtFIzFMSyQXbLoTQPRpA=="],
-
     "extract-zip/yauzl": ["yauzl@2.10.0", "", { "dependencies": { "buffer-crc32": "~0.2.3", "fd-slicer": "~1.1.0" } }, "sha512-p4a9I6X6nu6IhoGmBqAcbJy1mlC4j27vEPZX9F4L4/vZT3Lyq1VkFHw/V/PUcB9Buo+DG3iHkT0x3Qya58zc3g=="],
 
     "fast-glob/glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
@@ -5398,8 +5542,6 @@
 
     "ftp-response-parser/readable-stream": ["readable-stream@1.1.14", "", { "dependencies": { "core-util-is": "~1.0.0", "inherits": "~2.0.1", "isarray": "0.0.1", "string_decoder": "~0.10.x" } }, "sha512-+MeVjFf4L44XUkhM1eYbD8fyEsxcV81pqMSR5gblfcLCHfZvbrqy4/qYHE+/R5HoBUT11WV5O08Cr1n3YXkWVQ=="],
 
-    "get-stream/is-stream": ["is-stream@4.0.1", "", {}, "sha512-Dnz92NInDqYckGEUJv689RbRiTSEHCQ7wOVeALbkOz999YpqT46yMRIGtSNl2iCL1waAZSx40+h59NV/EwzV/A=="],
-
     "get-uri/data-uri-to-buffer": ["data-uri-to-buffer@6.0.2", "", {}, "sha512-7hvf7/GW8e86rW0ptuwS3OcBGDjIi6SZva7hCyWC0yYry2cOPmLIjXAUHI6DK2HsnwJd9ifmt57i8eV2n4YNpw=="],
 
     "globals/type-fest": ["type-fest@0.20.2", "", {}, "sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ=="],
@@ -5422,6 +5564,10 @@
 
     "inquirer/strip-ansi": ["strip-ansi@5.2.0", "", { "dependencies": { "ansi-regex": "^4.1.0" } }, "sha512-DuRs1gKbBqsMKIZlrffwlug8MHkcnpjs5VPmL1PAh+mA30U0DTotfDZ0d2UUsXpPmPmMMJ6W773MaA3J+lbiWA=="],
 
+    "is-expression/acorn": ["acorn@7.4.1", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-nQyp0o1/mNdbTO1PO6kHkwSrmgZ0MT/jCCpNiwbUjGoRN4dlBhqJtoQuCnEOKzgTVwg0ZWiCoQy6SxMebQVh8A=="],
+
+    "is-expression/object-assign": ["object-assign@4.1.1", "", {}, "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg=="],
+
     "isomorphic-fetch/node-fetch": ["node-fetch@2.7.0", "", { "dependencies": { "whatwg-url": "^5.0.0" }, "peerDependencies": { "encoding": "^0.1.0" }, "optionalPeers": ["encoding"] }, "sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A=="],
 
     "istanbul-lib-instrument/semver": ["semver@6.3.1", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="],
@@ -5444,6 +5590,10 @@
 
     "jsftp/debug": ["debug@3.2.7", "", { "dependencies": { "ms": "^2.1.1" } }, "sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ=="],
 
+    "jstransformer/is-promise": ["is-promise@2.2.2", "", {}, "sha512-+lP4/6lKUBfQjZ2pdxThZvLUAafmZb8OAxFb8XXtiQmS35INgr85hdOGoEs124ez1FCnZJt6jau/T+alh58QFQ=="],
+
+    "jstransformer/promise": ["promise@7.3.1", "", { "dependencies": { "asap": "~2.0.3" } }, "sha512-nolQXZ/4L+bP/UGlkfaIujX9BKxGwmQ9OT4mOt5yvy8iK1h3wqTEJCijzGANTCCl9nWjY41juyAn2K3Q1hLLTg=="],
+
     "lazystream/readable-stream": ["readable-stream@2.3.8", "", { "dependencies": { "core-util-is": "~1.0.0", "inherits": "~2.0.3", "isarray": "~1.0.0", "process-nextick-args": "~2.0.0", "safe-buffer": "~5.1.1", "string_decoder": "~1.1.1", "util-deprecate": "~1.0.1" } }, "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA=="],
 
     "lighthouse/chrome-launcher": ["chrome-launcher@1.2.1", "", { "dependencies": { "@types/node": "*", "escape-string-regexp": "^4.0.0", "is-wsl": "^2.2.0", "lighthouse-logger": "^2.0.1" }, "bin": { "print-chrome-path": "bin/print-chrome-path.cjs" } }, "sha512-qmFR5PLMzHyuNJHwOloHPAHhbaNglkfeV/xDtt5b7xiFFyU1I+AZZX0PYseMuhenJSSirgxELYIbswcoc+5H4A=="],
@@ -5480,6 +5630,8 @@
 
     "mdast-util-find-and-replace/escape-string-regexp": ["escape-string-regexp@5.0.0", "", {}, "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw=="],
 
+    "mdast-util-gfm-table/markdown-table": ["markdown-table@3.0.4", "", {}, "sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw=="],
+
     "merge-options/is-plain-obj": ["is-plain-obj@2.1.0", "", {}, "sha512-YWnfyRwxL/+SsrWYfOpUtz5b3YD+nyfkHvjbcanzk8zgyO4ASD67uVMRt8k5bM4lLMDnXfriRhOpemw+NfT1eA=="],
 
     "method-override/debug": ["debug@3.1.0", "", { "dependencies": { "ms": "2.0.0" } }, "sha512-OX8XqP7/1a9cqkxYw2yXss15f26NKWBpDXQd0/uK/KPqdQhxbPa994hnzjcE2VqQpDslf55723cKPUOGSmMY3g=="],
@@ -5536,6 +5688,8 @@
 
     "postcss/nanoid": ["nanoid@3.3.12", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ=="],
 
+    "precinct/commander": ["commander@12.1.0", "", {}, "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA=="],
+
     "pretty-format/ansi-styles": ["ansi-styles@5.2.0", "", {}, "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA=="],
 
     "pretty-format/react-is": ["react-is@18.3.1", "", {}, "sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg=="],
@@ -5546,12 +5700,16 @@
 
     "proxy-agent/lru-cache": ["lru-cache@7.18.3", "", {}, "sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA=="],
 
+    "pug-load/object-assign": ["object-assign@4.1.1", "", {}, "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg=="],
+
     "rc/ini": ["ini@1.3.8", "", {}, "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew=="],
 
     "rc/strip-json-comments": ["strip-json-comments@2.0.1", "", {}, "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ=="],
 
     "react-devtools-core/ws": ["ws@7.5.10", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": "^5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-+dbF1tHwZpXcbOJdVOkzLDxZP1ailvSxM6ZweXTegylPny803bFhA+vqBYw4s31NSAk4S2Qz+AKXK9a4wkdjcQ=="],
 
+    "react-native/commander": ["commander@12.1.0", "", {}, "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA=="],
+
     "react-native/glob": ["glob@7.2.3", "", { "dependencies": { "fs.realpath": "^1.0.0", "inflight": "^1.0.4", "inherits": "2", "minimatch": "^3.1.1", "once": "^1.3.0", "path-is-absolute": "^1.0.0" } }, "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q=="],
 
     "react-native/ws": ["ws@7.5.10", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": "^5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-+dbF1tHwZpXcbOJdVOkzLDxZP1ailvSxM6ZweXTegylPny803bFhA+vqBYw4s31NSAk4S2Qz+AKXK9a4wkdjcQ=="],
@@ -5576,6 +5734,10 @@
 
     "readdir-glob/minimatch": ["minimatch@5.1.9", "", { "dependencies": { "brace-expansion": "^2.0.1" } }, "sha512-7o1wEA2RyMP7Iu7GNba9vc0RWWGACJOCZBJX2GJWip0ikV+wcOsgVuY9uE8CPiyQhkGFSlhuSkZPavN7u1c2Fw=="],
 
+    "recharts/es-toolkit": ["es-toolkit@1.46.1", "", {}, "sha512-5eNtXOs3tbfxXOj04tjjseeWkRWaoCjdEI+96DgwzZoe6c9juL49pXlzAFTI72aWC9Y8p7168g6XIKjh7k6pyQ=="],
+
+    "restore-cursor/onetime": ["onetime@2.0.1", "", { "dependencies": { "mimic-fn": "^1.0.0" } }, "sha512-oyyPpiMaKARvvcgip+JV+7zci5L8D1W9RZIz2l1o08AM3pfspitVWnPt3mzHcBPp12oYMTy0pqrFs/C+m3EwsQ=="],
+
     "restore-cursor/signal-exit": ["signal-exit@3.0.7", "", {}, "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ=="],
 
     "rimraf/glob": ["glob@13.0.6", "", { "dependencies": { "minimatch": "^10.2.2", "minipass": "^7.1.3", "path-scurry": "^2.0.2" } }, "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw=="],
@@ -5668,6 +5830,8 @@
 
     "@appium/support/axios/proxy-from-env": ["proxy-from-env@2.1.0", "", {}, "sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA=="],
 
+    "@appium/support/get-stream/is-stream": ["is-stream@4.0.1", "", {}, "sha512-Dnz92NInDqYckGEUJv689RbRiTSEHCQ7wOVeALbkOz999YpqT46yMRIGtSNl2iCL1waAZSx40+h59NV/EwzV/A=="],
+
     "@appium/support/log-symbols/is-unicode-supported": ["is-unicode-supported@2.1.0", "", {}, "sha512-mE00Gnza5EEB3Ds0HfMyllZzbBrmLOX3vfWoj9A9PEnTfratQ/BcaJOuMhnkhjXvb2+FkY3VuHqtAGpTPmglFQ=="],
 
     "@appium/support/plist/@xmldom/xmldom": ["@xmldom/xmldom@0.9.10", "", {}, "sha512-A9gOqLdi6cV4ibazAjcQufGj0B1y/vDqYrcuP6d/6x8P27gRS8643Dj9o1dEKtB6O7fwxb2FgBmJS2mX7gpvdw=="],
@@ -6138,6 +6302,8 @@
 
     "readdir-glob/minimatch/brace-expansion": ["brace-expansion@2.1.0", "", { "dependencies": { "balanced-match": "^1.0.0" } }, "sha512-TN1kCZAgdgweJhWWpgKYrQaMNHcDULHkWwQIspdtjV4Y5aurRdZpjAqn6yX3FPqTA9ngHCc4hJxMAMgGfve85w=="],
 
+    "restore-cursor/onetime/mimic-fn": ["mimic-fn@1.2.0", "", {}, "sha512-jf84uxzwiuiIVKiOLpfYk7N46TSy8ubTonmneY9vrpHNAnp0QBt2BxWV9dO3/j+BoVAb+a5G6YDPW3M5HOdMWQ=="],
+
     "tailwindcss/chokidar/glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
 
     "tailwindcss/chokidar/readdirp": ["readdirp@3.6.0", "", { "dependencies": { "picomatch": "^2.2.1" } }, "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA=="],
@@ -6494,8 +6660,6 @@
 
     "agents/yargs/string-width/strip-ansi/ansi-regex": ["ansi-regex@6.2.2", "", {}, "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg=="],
 
-    "appium/ora/cli-cursor/restore-cursor/onetime": ["onetime@5.1.2", "", { "dependencies": { "mimic-fn": "^2.1.0" } }, "sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg=="],
-
     "appium/ora/cli-cursor/restore-cursor/signal-exit": ["signal-exit@3.0.7", "", {}, "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ=="],
 
     "archiver-utils/glob/jackspeak/@isaacs/cliui/string-width": ["string-width@5.1.2", "", { "dependencies": { "eastasianwidth": "^0.2.0", "emoji-regex": "^9.2.2", "strip-ansi": "^7.0.1" } }, "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA=="],
@@ -6534,8 +6698,6 @@
 
     "@lhci/cli/yargs/find-up/locate-path/p-locate/p-limit": ["p-limit@2.3.0", "", { "dependencies": { "p-try": "^2.0.0" } }, "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w=="],
 
-    "appium/ora/cli-cursor/restore-cursor/onetime/mimic-fn": ["mimic-fn@2.1.0", "", {}, "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg=="],
-
     "archiver-utils/glob/jackspeak/@isaacs/cliui/string-width/emoji-regex": ["emoji-regex@9.2.2", "", {}, "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg=="],
 
     "archiver-utils/glob/jackspeak/@isaacs/cliui/strip-ansi/ansi-regex": ["ansi-regex@6.2.2", "", {}, "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg=="],
diff --git a/copilot-instructions.md b/copilot-instructions.md
index 83baf28438..041d20b18e 100644
--- a/copilot-instructions.md
+++ b/copilot-instructions.md
@@ -88,10 +88,14 @@ cd apps/guides && bun dev
 - NEVER CANCEL: Takes ~1.4 seconds to start, set timeout to 30+ seconds
 - Runs on `http://localhost:3001` (if 3000 is taken)
 
-#### **Testing**
-- **API Unit Tests**: `bun test:api:unit` -- NEVER CANCEL: Takes ~5 seconds
-- **Expo Tests**: `bun test:expo` -- runs Expo/React Native unit tests
-- Tests run sequentially (`fileParallelism: false` in `packages/api/vitest.unit.config.ts`) to avoid database deadlocks
+#### **Testing** — see `docs/testing.md` for the full policy
+- **API Unit Tests**: `bun test:api:unit` -- Node env, deps mocked. Runtime varies with suite size
+- **Expo Tests**: `bun test:expo` -- Vitest, pure-TS modules only (no native imports)
+- **MCP Tests**: `bun test:mcp`
+- **Scripts Tests**: `bun test:scripts` -- analyzer tests for the coverage ratchet and assertion lint
+- **Coverage ratchet**: `bun check:coverage` -- compares each tracked workspace's `coverage/[unit/]coverage-summary.json` against `coverage-baselines.json` at the repo root. Fails CI on regression
+- **Assertion-strength lint**: `bun lint:weak-assertions` -- catches assertion-free tests, bare `.toBeDefined()`, bare `.toHaveBeenCalled()`, oversized inline snapshots
+- **Integration tests** (`bun run --cwd packages/api test`): require Docker (Postgres + neon-wsproxy), run sequentially (`fileParallelism: false`) to avoid database deadlocks. NOT coverage-counted (V8 unsupported under Cloudflare Workers pool)
 - Tests expect environment variables to be configured (see `.env.example`)
 
 #### **Build Commands**
diff --git a/coverage-baselines.json b/coverage-baselines.json
new file mode 100644
index 0000000000..2661502a58
--- /dev/null
+++ b/coverage-baselines.json
@@ -0,0 +1,67 @@
+{
+  "_comment": "Coverage ratchet baselines — see docs/testing.md and scripts/lint/coverage-ratchet.ts. Each entry is a workspace's floor: a PR that drops any metric below the baseline (modulo epsilon) fails CI. CI on main auto-bumps these numbers upward via scripts/lint/coverage-baseline-update.ts after a green run.",
+  "_epsilon": 0.5,
+  "packages/api": {
+    "summaryPath": "packages/api/coverage/unit/coverage-summary.json",
+    "tier": "B",
+    "lines": 98.31,
+    "branches": 95.43,
+    "functions": 100,
+    "statements": 98.31,
+    "recordedAt": "2026-05-19"
+  },
+  "apps/expo": {
+    "summaryPath": "apps/expo/coverage/unit/coverage-summary.json",
+    "tier": "C",
+    "lines": 97.36,
+    "branches": 95,
+    "functions": 100,
+    "statements": 97.36,
+    "recordedAt": "2026-05-19"
+  },
+  "packages/mcp": {
+    "summaryPath": "packages/mcp/coverage/coverage-summary.json",
+    "tier": "B",
+    "lines": 98.87,
+    "branches": 98.38,
+    "functions": 100,
+    "statements": 98.87,
+    "recordedAt": "2026-05-19"
+  },
+  "packages/analytics": {
+    "summaryPath": "packages/analytics/coverage/coverage-summary.json",
+    "tier": "B",
+    "lines": 84.48,
+    "branches": 83.33,
+    "functions": 89.13,
+    "statements": 84.48,
+    "recordedAt": "2026-05-19"
+  },
+  "packages/overpass": {
+    "summaryPath": "packages/overpass/coverage/coverage-summary.json",
+    "tier": "A",
+    "lines": 100,
+    "branches": 95.65,
+    "functions": 100,
+    "statements": 100,
+    "recordedAt": "2026-05-19"
+  },
+  "packages/units": {
+    "summaryPath": "packages/units/coverage/coverage-summary.json",
+    "tier": "A",
+    "lines": 100,
+    "branches": 100,
+    "functions": 100,
+    "statements": 100,
+    "recordedAt": "2026-05-19"
+  },
+  "packages/utils": {
+    "summaryPath": "packages/utils/coverage/coverage-summary.json",
+    "tier": "A",
+    "lines": 100,
+    "branches": 100,
+    "functions": 100,
+    "statements": 100,
+    "recordedAt": "2026-05-31"
+  }
+}
diff --git a/docs/audits/2026-05-16-etl-audit.md b/docs/audits/2026-05-16-etl-audit.md
new file mode 100644
index 0000000000..84f1d69449
--- /dev/null
+++ b/docs/audits/2026-05-16-etl-audit.md
@@ -0,0 +1,183 @@
+# ETL Pipeline Audit — 2026-05-16
+
+## Summary
+
+The catalog ETL pipeline works end-to-end and has been hardened through a recent series of fixes (OOM, CPU-time budget, atomic counters, byte-range chunking), but it is not production-ready: chunking + a single shared `jobId` produces double-counted `totalProcessed`, mis-marks jobs `completed` after the first chunk finishes, and lacks any dead-letter / retry policy at the queue layer. Catastrophic per-message failures silently swallow errors in `processQueueBatch` (`try/catch` with `console.error` only), so the queue happily acks bad chunks. The retry endpoint also re-queues only the original object key, ignoring multi-chunk jobs entirely.
+
+**Top 3 risks**: (1) cross-chunk job-status race (any one chunk's completion marks the entire job `completed`), (2) consumer swallows errors so failed messages never retry/DLQ, (3) retry endpoint and stuck-job sweep are incompatible with byte-range chunking.
+
+## Architecture
+
+```
+POST /api/catalog/etl            ── api-key auth
+   │  body: { filename, chunks[], source, scraperRevision }
+   ▼
+1. INSERT etl_jobs (status='running')
+2. For each objectKey: R2.head() → split into 20 MB byte-range chunks
+3. queueCatalogETL → ETL_QUEUE.sendBatch (one message per chunk, same jobId)
+
+ETL_QUEUE (max_batch_size=1, max_concurrency=1)
+   ▼
+processQueueBatch
+   ▼
+processCatalogETL                ── per chunk
+   ├── R2.get(key, {range})      ── stream body
+   ├── if non-first chunk: GET first 4 KB → extract header → inject; skip partial row
+   ├── csv-parse stream w/ backpressure (parser.write returns false → wait 'drain')
+   ├── yield every 100 rows (setTimeout(1))
+   ├── flush at BATCH_SIZE=100 rows:
+   │     valid   → processValidItemsBatch → mergeBySku → embeddings → catalogService.upsert → updateEtlJobProgress
+   │     invalid → processLogsBatch       → invalid_item_logs        → updateEtlJobProgress
+   └── on success: UPDATE etl_jobs SET status='completed'   ◀── PROBLEM with multi-chunk jobs
+       on throw:    UPDATE etl_jobs SET status='failed' + rethrow
+```
+
+Counters are atomic per call (`COALESCE(col, 0) + n` in SQL). Job rows are not.
+
+## Findings
+
+### [P0] Multi-chunk jobs are marked `completed` after the first chunk finishes
+- **What**: All chunks for a single source file share one `jobId`; each chunk independently sets `status='completed'` on success.
+- **Where**: `packages/api/src/services/etl/processCatalogEtl.ts:188-191`; chunks created in `packages/api/src/routes/catalog/index.ts:182-200`.
+- **Why it matters**: A 100 MB file becomes 5 chunks → 5 messages → the first message to finish flips the job to `completed`, even though 80% of rows haven't been processed yet. The dashboard, `success_rate`, and any downstream check ("is the catalog refresh done?") fire prematurely. Subsequent chunks continue to mutate `totalProcessed/totalValid/totalInvalid`, so the row reads as `completed` with rising counters.
+- **Recommendation**: Track per-chunk completion. Two options: (a) add a `chunks_total` and `chunks_completed` column; only set `completed` when `chunks_completed = chunks_total`. (b) give each chunk its own jobId and group by a parent `batch_id`. Option (a) is the smaller change.
+
+### [P0] `processQueueBatch` swallows errors — failed chunks never retry or DLQ
+- **What**: Per-message exceptions are caught and logged but never rethrown; CF Queues auto-acks every message in the batch.
+- **Where**: `packages/api/src/services/etl/queue.ts:50-60`.
+- **Why it matters**: A transient DB error, OpenAI 429, or R2 read failure permanently loses the chunk. The job is marked `failed` (good) but the message is acked (bad) — there is no retry, no dead-letter queue, and `wrangler.jsonc` does not declare a `dead_letter_queue` or `max_retries`. Combined with the multi-chunk issue above, a single failure can corrupt the job state while other chunks succeed and mark it `completed`.
+- **Recommendation**: Rethrow in the catch (or call `message.retry()` explicitly on the specific message). Add `dead_letter_queue` and `max_retries: 3` to the ETL queue consumer in `wrangler.jsonc:76-82`. Process messages with `for...of` calling `message.ack()` / `message.retry()` explicitly so partial-batch semantics are correct even though `max_batch_size=1` today.
+
+### [P1] Retry endpoint discards multi-chunk structure
+- **What**: `POST /admin/etl/:jobId/retry` re-queues exactly one chunk built from `v2/${source}/${filename}` with no chunking.
+- **Where**: `packages/api/src/routes/admin/analytics/catalog.ts:434-450`.
+- **Why it matters**: If the original job was chunked (20 MB+ files), retry blasts the entire file at one Worker invocation, blowing past the 300s CPU-time limit that prompted the chunking work in the first place. Result: retries of any large failed job silently re-fail.
+- **Recommendation**: Re-run the same R2.head + chunk-split logic the producer endpoint uses (lines 182-200). Extract that to a shared helper so both call sites stay in sync.
+
+### [P1] Stuck-job sweep is wall-clock based and incompatible with serial chunked jobs
+- **What**: `POST /admin/etl/reset-stuck` flips any job in `running` for >30 min to `failed`.
+- **Where**: `packages/api/src/routes/admin/analytics/catalog.ts:384-403`.
+- **Why it matters**: With `max_concurrency=1` and 20 MB chunks each consuming most of a 300s CPU budget, a 500 MB file produces 25 chunks at up to ~5 minutes each → comfortably past 30 minutes. Healthy long jobs will be marked `failed`. The trigger should be "no progress for N minutes" (e.g., `totalProcessed` unchanged), not "started >30 min ago".
+- **Recommendation**: Add `lastProgressAt` updated on each `updateEtlJobProgress` call; sweep on `lastProgressAt < now - 15min`. Or check `completedAt IS NULL AND startedAt < now - 2h` for the absolute floor.
+
+### [P1] First-chunk header injection assumes the first 4 KB contains a complete header
+- **What**: For non-first chunks, the parser fetches `bytes 0-4095` and uses `headerText.split('\n')[0]` as the header row.
+- **Where**: `packages/api/src/services/etl/processCatalogEtl.ts:53-58`.
+- **Why it matters**: If the header row exceeds 4 KB (wide CSVs with 30+ columns and long names — possible here given the catalog schema has 25+ fields), `split('\n')[0]` returns a *truncated* header, so `fieldMap` silently maps the last column wrong. There is also no validation that the slice actually contained a newline before `byteEnd=4095`.
+- **Recommendation**: Loop the range request (or use a streaming `until newline` reader). At minimum, throw if no `\n` appears in the first 4 KB so the failure is loud, not silent.
+
+### [P1] Partial-row skip can drop a valid full row when chunk boundary lands on a newline
+- **What**: `skipPartialRow` discards everything up to and including the first `\n` after `byteStart`. If `byteStart` happens to be the first byte *after* a newline (i.e., the previous chunk's last byte is `\n`), the producing chunk processed the full row, and this chunk correctly starts on a row boundary — but the skip logic still throws away the first whole row.
+- **Where**: `packages/api/src/services/etl/processCatalogEtl.ts:95-108`.
+- **Why it matters**: Off-by-one row drop at every chunk boundary in worst case (data loss, not just dup). For 25-chunk file → potentially 24 lost catalog items. No test covers the boundary-aligned case.
+- **Recommendation**: When splitting chunks at line 195-196 of `routes/catalog/index.ts`, do not split on arbitrary 20 MB offsets — peek at R2 with a short range request and align `byteEnd` to a newline so the skip logic is unnecessary, *or* skip only when the previous byte (range `byteStart-1`) was non-newline.
+
+### [P1] CSV row spanning chunk boundary is never reassembled
+- **What**: A row beginning before `byteEnd` and ending after will be cut in half. The producing chunk parses a truncated row (likely fails validation); the next chunk discards the tail.
+- **Where**: `packages/api/src/services/etl/processCatalogEtl.ts:95-108` (skip logic), `routes/catalog/index.ts:182-200` (chunk creation).
+- **Why it matters**: Every chunk boundary loses (or invalidates) one row. Symptom would be `totalInvalid` rising by ~N per N-chunk job, with field-shaped errors. Severity depends on row width vs 20 MB.
+- **Recommendation**: Same as above — align chunk boundaries to row boundaries in the producer. Alternatively, the producing chunk should fetch ~64 KB beyond `byteEnd` to complete its final row, and the next chunk skip logic stays.
+
+### [P2] `console.log`/`console.error` only — no structured logging, no Sentry
+- **What**: Every log uses `console.log` with emoji prefixes; no Sentry integration in ETL paths despite Sentry being a documented monitoring tool.
+- **Where**: All ETL files; verified by `grep -rn "Sentry|captureException" packages/api/src/services/etl/` → no results. Same applies to `packages/api/src/`.
+- **Why it matters**: A stuck job cannot be debugged without paging through CF Workers logs by hand. No correlation IDs (other than jobId), no per-chunk structured fields (`byteStart`, `rowsProcessed`, `elapsed_ms`), no error categorization. Failures in `processLogsBatch` are caught and `console.error`-ed without rethrow (`packages/api/src/services/etl/processLogsBatch.ts:25-27`) — invalid logs can fail to write and nobody knows.
+- **Recommendation**: Add a thin logger (`logger.info({ jobId, chunk: { byteStart, byteEnd }, event: 'chunk_start' })`). Call `Sentry.captureException(err, { tags: { jobId, objectKey } })` in the `processCatalogETL` catch block.
+
+### [P2] `processLogsBatch` swallows DB errors silently
+- **What**: Catch logs to console and returns normally — caller has no idea logs were dropped.
+- **Where**: `packages/api/src/services/etl/processLogsBatch.ts:25-27`.
+- **Why it matters**: Invalid-item logs are the *only* forensic record of what failed validation. If the INSERT fails (Neon hiccup, payload size, FK violation), we lose visibility forever. The `updateEtlJobProgress` call is also inside the try, so `totalInvalid`/`totalProcessed` will be undercounted.
+- **Recommendation**: Rethrow. Let the outer ETL catch flip the job to `failed` — the alternative is silent data quality erosion.
+
+### [P2] Embedding failure path silently drops embeddings without marking it
+- **What**: When `generateManyEmbeddings` throws, items are upserted with `embedding=undefined` (i.e., NULL) but the job still reports as fully successful.
+- **Where**: `packages/api/src/services/etl/processValidItemsBatch.ts:52-63`.
+- **Why it matters**: No metric distinguishes "successful with embeddings" from "successful but degraded". The `/admin/embeddings` route reports coverage but cannot attribute the drop to a specific job. A backfill is required to recover, and there is no automatic re-queue.
+- **Recommendation**: Add a `totalEmbeddingFailures` column on `etl_jobs`, increment it in the fallback path, and surface in the admin dashboard. Optionally enqueue the affected SKUs into `EMBEDDINGS_QUEUE` from the fallback for automatic backfill.
+
+### [P2] `parser.end()` is called inside a fire-and-forget IIFE — errors are unhandled
+- **What**: The async writer is invoked as `(async () => { ... })()` with no `.catch()`. Any stream read error or `parser.write` throw becomes an unhandled rejection.
+- **Where**: `packages/api/src/services/etl/processCatalogEtl.ts:89-117`.
+- **Why it matters**: In CF Workers, unhandled rejections can terminate the isolate. More commonly the outer `for await (const record of parser)` loop will just hang on a stalled parser if the writer rejected. The job will sit in `running` until the stuck-job sweep notices.
+- **Recommendation**: Wrap in an explicit promise: `const writerPromise = (async () => { ... })().catch(err => parser.destroy(err));` and `await writerPromise` after the `for await` loop. Surface the error to the outer catch.
+
+### [P2] `setTimeout(resolve, 1)` every 100 rows is a fragile yield mechanism
+- **What**: Used to yield to event loop / give GC a chance.
+- **Where**: `packages/api/src/services/etl/processCatalogEtl.ts:120`.
+- **Why it matters**: `setTimeout` consumes wall-clock budget. Workers have a 30s wall-clock per invocation (separate from `cpu_ms`). At 1ms × 600 yields per 60k-row chunk = 0.6s — fine today, but the comment mentions a previous "per-row yield hits the CF Worker wall-clock limit". The thresholds are tightly coupled and undocumented.
+- **Recommendation**: Replace with `await scheduler.yield()` (CF supports it) or `await new Promise(setImmediate)`-equivalent. Add a unit test that verifies a 100k-row CSV completes within wall-clock.
+
+### [P2] `BATCH_SIZE = 100` is exported but reads inconsistent with comment/runtime
+- **What**: `processCatalogEtl.ts:13` exports `BATCH_SIZE = 100`. The catalog OpenAI embedding API supports 1000+ per call, so this is conservative; meanwhile the queue's `batchSize` for `sendBatch` is hard-coded at 100 (`queue.ts:17`) for an unrelated reason (max batch size from CF). Reusing the symbol `100` for two different concepts is fragile.
+- **Where**: `processCatalogEtl.ts:13`, `queue.ts:17`.
+- **Recommendation**: Rename to `ITEM_FLUSH_BATCH_SIZE` and `CF_QUEUE_BATCH_SIZE`, hoist both to a shared constants file.
+
+### [P3] `mergeItemsBySku` logs change diff on every merge — unbounded console output
+- **What**: Logs a `🔄 Merged SKU` line for every SKU collision with every changed field.
+- **Where**: `packages/api/src/services/etl/mergeItemsBySku.ts:34-48`.
+- **Why it matters**: On a 500 MB CSV with many duplicate SKUs across chunks, this can produce millions of log lines, polluting CF logs and possibly hitting `logpush` quotas.
+- **Recommendation**: Aggregate into a single per-batch summary or gate behind a debug flag.
+
+### [P3] Validator: no URL scheme check, no length limits, no SKU charset rules
+- **What**: `isValidUrl` allows any `new URL()`-parseable input (e.g., `mailto:`, `javascript:`, `file:`).
+- **Where**: `packages/api/src/services/etl/CatalogItemValidator.ts:60-67`.
+- **Why it matters**: `productUrl` is rendered in the mobile app and on the guides site. A scraper bug could inject `javascript:` URLs that survive to the UI.
+- **Recommendation**: Restrict to `http:`/`https:`. Add length caps (`name` ≤ 500, `description` ≤ 50k, `sku` matches `[A-Za-z0-9_.\-/]+`).
+
+### [P3] Soft-delete is not handled by the upsert
+- **What**: `catalogItems` has no `deletedAt` column (verified — grep returns nothing). CLAUDE.md notes "Soft deletes for all user content" but catalog items are scraper-controlled, so this may be intentional. However, an item that disappears from the source CSV is never marked unavailable.
+- **Where**: `packages/api/src/db/schema.ts:132-215`; `packages/api/src/services/catalogService.ts:337-407`.
+- **Why it matters**: The catalog grows monotonically. Discontinued products keep their `availability` from the last successful upsert. There is no "items present in last job but not in this one → mark out-of-stock" reconciliation.
+- **Recommendation**: After a successful ETL, run `UPDATE catalog_items SET availability='OutOfStock' WHERE NOT EXISTS (SELECT 1 FROM catalog_item_etl_jobs WHERE catalog_item_id = id AND etl_job_id IN (last N jobs for this source))`. Or accept the limitation and document it.
+
+### [P3] No invalid-items retention policy
+- **What**: `invalid_item_logs` grows forever; no TTL/sweep.
+- **Where**: `packages/api/src/db/schema.ts:481-490`.
+- **Why it matters**: Each bad row stores `raw_data` as JSONB plus an `errors` array — a single bad upload can write hundreds of MB to Neon.
+- **Recommendation**: Add a scheduled task (or CF Cron Trigger) to drop logs >90 days.
+
+### [P3] No runbook / deploy docs
+- **What**: No `docs/runbooks/etl.md`. `grep "etl|ETL"` in `README.md`/`docs/` returns only stale plan files.
+- **Where**: N/A (missing).
+- **Recommendation**: Write a 1-page runbook: how to trigger an ETL, how to inspect queue depth (`wrangler queues list/info packrat-etl-queue`), how to retry a failed job, how to drain the queue (`wrangler queues consumer remove`), how to interpret `success_rate`. Reference admin endpoints `/admin/etl/*`.
+
+## Test Coverage Gaps
+
+Tests cover the happy path with mocked R2 and globally-mocked DB. The following are **not** tested:
+
+- **Byte-range chunk processing** — no test sets `byteStart`/`byteEnd` in the message. The injected-header fetch, partial-row skip, and boundary off-by-ones (P1 above) are entirely uncovered.
+- **Multi-message job (same jobId, multiple chunks)** — no integration test exercises the "two chunks complete sequentially" path, so the P0 premature-completion bug is invisible to CI.
+- **Header > 4 KB** — see P1 finding.
+- **Row spanning chunk boundary** — see P1 finding.
+- **Embedding service failure path** — `processValidItemsBatch.test` mocks the rejection but does not assert that items were upserted without embeddings (the actual fallback behavior).
+- **`processLogsBatch` DB failure** — no test for the swallowed-error case.
+- **Backpressure** — `parser.write` returning `false` and waiting on `'drain'` is not unit-testable with the current mock (whole CSV emitted in one chunk).
+- **Yield/wall-clock budget** — no test asserts a 100k-row CSV completes under wall-clock.
+- **`processQueueBatch`** — no direct test; the per-message catch-and-swallow (P0) is untested.
+- **Retry endpoint** — no integration test verifies the retry produces a new running job and a queue send.
+- **Stuck-job sweep** — no test for the 30-minute cutoff.
+- **Concurrent updates to same job row** — no race-condition test (e.g., two batches calling `updateEtlJobProgress` interleaved). Atomicity at the SQL level is good but a parallel-batch test would lock it in.
+- **`mergeItemsBySku` cross-chunk SKU collisions** — merging happens within a single batch; SKUs duplicated across batches (or across chunks) hit the DB upsert path, not the merge path. No test for that.
+- **Header injection — wrong column ordering** — what if the source CSV has a BOM, or quoted headers with commas inside?
+
+## Production Readiness Checklist
+
+- [ ] Multi-chunk job completion tracked correctly (chunks_total / chunks_completed columns) — addresses P0 #1
+- [ ] Queue consumer rethrows on per-message failure; DLQ + max_retries configured in `wrangler.jsonc` — addresses P0 #2
+- [ ] Retry endpoint chunks large files the same way the producer does — addresses P1 #1
+- [ ] Stuck-job sweep keyed on `lastProgressAt`, not `startedAt` — addresses P1 #2
+- [ ] Chunk boundaries aligned to row boundaries in the producer (or reassembly in the consumer) — addresses P1 #3 and P1 #4
+- [ ] Header injection validates first 4 KB contains a `\n`; tested with wide CSV — addresses P1 #5
+- [ ] Sentry integration in ETL paths with `jobId`/`objectKey` tags — addresses P2 #1
+- [ ] `processLogsBatch` rethrows on DB failure — addresses P2 #2
+- [ ] Embedding fallback tracked via counter and visible in admin dashboard — addresses P2 #3
+- [ ] Writer IIFE error attached to outer flow — addresses P2 #4
+- [ ] Yield mechanism uses `scheduler.yield()` and has a wall-clock test — addresses P2 #5
+- [ ] Rename ambiguous `BATCH_SIZE` constants — addresses P2 #6
+- [ ] `mergeItemsBySku` summary log instead of per-SKU — addresses P3 #1
+- [ ] Validator enforces `http(s):` scheme and length caps — addresses P3 #2
+- [ ] Discontinued-item reconciliation strategy chosen and documented — addresses P3 #3
+- [ ] `invalid_item_logs` retention policy — addresses P3 #4
+- [ ] Runbook checked in at `docs/runbooks/etl.md` — addresses P3 #5
+- [ ] Test coverage added for all gaps listed above
diff --git a/docs/plans/2026-05-19-001-chore-coverage-ratchet-and-quality-gates-plan.md b/docs/plans/2026-05-19-001-chore-coverage-ratchet-and-quality-gates-plan.md
new file mode 100644
index 0000000000..1c7a0b4af3
--- /dev/null
+++ b/docs/plans/2026-05-19-001-chore-coverage-ratchet-and-quality-gates-plan.md
@@ -0,0 +1,184 @@
+---
+type: plan
+status: active
+plan_type: chore
+title: Coverage ratchet and assertion-strength gates
+created: 2026-05-19
+worktree: .worktrees/chore/ramp-test-coverage
+branch: chore/ramp-test-coverage
+supersedes: docs/plans/2026-05-17-001-chore-test-coverage-ramp-and-ci-gate-plan.md
+---
+
+# chore: Coverage ratchet and assertion-strength gates
+
+## Summary
+
+A 2026-05-17 plan proposed a 9-unit, 4-phase ramp toward 95%+ coverage across the monorepo with a CI gate that blocks regressions. While that plan was being written, upstream `main` independently landed the threshold ramp itself — Vitest configs across `packages/api`, `apps/expo`, `packages/analytics`, `packages/mcp`, and `packages/overpass` now sit at 95/92/97/95 (or close), with refined exclude lists and added unit tests for middleware, image utils, and storage. **U2 of the original plan is therefore obsoleted by upstream.**
+
+What remains novel and ship-ready is the *enforcement* layer the original plan introduced:
+
+- **U6** — a coverage **ratchet** (`scripts/lint/coverage-ratchet.ts` + committed `coverage-baselines.json`) that fails CI if any tracked workspace drops below its baseline. Complements Vitest's per-config thresholds: thresholds enforce the floor, the ratchet enforces no-regression toward the tier target.
+- **U9** — an **assertion-strength lint** (`scripts/lint/no-weak-assertions.ts`) that catches coverage theater patterns (assertion-free tests, bare `.toBeDefined()`, bare `.toHaveBeenCalled()`, oversized snapshots).
+- **U1** — migrate the testing guide off the repo root (`TESTING.md` → `docs/testing.md`, per the "no random md in root" convention) and rewrite around the ratchet + lint, not the obsolete tier ramp.
+
+Future phases (consolidated coverage workflow / Stryker mutation testing / per-workspace backfills for the still-untested packages) are deferred to follow-up plans.
+
+---
+
+## Problem Frame
+
+PackRat's Vitest configs now declare strict per-package coverage thresholds (largely 95%+), but the surrounding enforcement is thin:
+
+1. **No regression gate.** Vitest's `thresholds` block fails the build when a single config's run drops below its declared floor. There is nothing that fails CI when an existing workspace silently slides from 95% to 89% if the threshold is lowered as a "temporary unblock" — exactly the pattern the Elysia migration's PR-2083 history shows (`4c2c00d19 fix(ci): separate API type-check, lower coverage threshold`). A floor that can be edited by the same PR that drops below it is not a gate.
+2. **No quality gate beyond line counts.** Coverage rewards *executing* code, not *asserting* on it. The standing failure mode is `expect(x).toBeDefined()` after a parse, or `expect(spy).toHaveBeenCalled()` without arg matching — both fully covered, both regression-blind.
+3. **Doc hygiene.** `TESTING.md` lives at the repo root alongside `CLAUDE.md` and `README.md`. The repo convention is that only those last two belong at root; everything else goes under `docs/`. The testing guide itself was already out of date relative to upstream's threshold ramp.
+
+This plan adds the missing gates and the missing doc move. It does **not** lower or rewrite any existing Vitest threshold.
+
+---
+
+## Scope Boundaries
+
+### In scope
+
+- A `scripts/lint/coverage-ratchet.ts` enforcement script + `scripts/lint/coverage-baseline-update.ts` (CI-only baseline bump) + committed `coverage-baselines.json` at the repo root.
+- `bun check:coverage` / `bun check:coverage:update` package.json scripts.
+- A unit test suite for the ratchet at `scripts/lint/__tests__/coverage-ratchet.test.ts`.
+- `scripts/lint/no-weak-assertions.ts` and its unit test suite at `scripts/lint/__tests__/no-weak-assertions.test.ts`.
+- `bun lint:weak-assertions` script and a `scripts/vitest.config.ts` for the scripts test suite.
+- Migrating `TESTING.md` to `docs/testing.md` with content rewritten around current reality (upstream's 95%+ thresholds plus the new ratchet + lint).
+
+### Deferred to follow-up work
+
+- **Consolidated `.github/workflows/coverage.yml` matrix workflow** that runs every Tier A/B/C workspace, posts per-workspace PR comments, and invokes the ratchet. Out of scope for this PR — easier to land on top of the ratchet once the gate is in place. Tracked separately.
+- **Stryker mutation testing** on `packages/api/src/{services,middleware,utils}/**` and the nightly workflow. Follow-up.
+- **Backfilling tests in currently-untested workspaces** (`apps/{admin,trails,web}`, `packages/{guards,env,app,cli,checks,config,osm-db,osm-import,web-ui,api-client,ui}`). Some of these gained tests via upstream's work; the rest are a separate effort.
+- **Wiring `bun lint:weak-assertions` into `scripts/check-all.ts`** as a blocking check. The lint currently surfaces a handful of real findings against the upstream codebase (mostly in `packages/analytics`); wiring into the gate requires a small cleanup PR first.
+
+### Out of scope
+
+- Lowering or rewriting any Vitest threshold upstream put in place.
+- Adding Codecov / Coveralls integration.
+- E2E / visual-regression / mutation testing.
+
+---
+
+## Requirements
+
+| ID | Requirement |
+|---|---|
+| R1 | `coverage-baselines.json` lives at the repo root and records, per tracked workspace: `summaryPath`, four-metric baseline, and `recordedAt`. Updates happen via the baseline-update script on green merges to `main` — never manually edited in feature PRs. |
+| R2 | `scripts/lint/coverage-ratchet.ts` exits non-zero on any metric dropping below the baseline (modulo `_epsilon` to absorb v8 jitter), on a missing summary file, or on a malformed summary. |
+| R3 | The ratchet's analysis logic is testable in isolation. `scripts/lint/__tests__/coverage-ratchet.test.ts` covers happy path, regressions, missing summaries, malformed summaries, multi-metric regressions, and baseline parsing. |
+| R4 | `scripts/lint/no-weak-assertions.ts` flags the four documented coverage-theater patterns (assertion-free tests, `only-tobedefined`, `bare-tohavebeencalled`, `large-snapshot`) and respects a file-level `// no-weak-assertions: disable` escape hatch. |
+| R5 | The lint's analysis logic is testable. `scripts/lint/__tests__/no-weak-assertions.test.ts` covers each rule's positive/negative cases, the disable comment, expect-helper detection, and multi-violation files. |
+| R6 | `bun check:coverage` runs the ratchet. `bun check:coverage:update` runs the baseline-update script. `bun lint:weak-assertions` runs the assertion lint. `bun test:scripts` runs both unit suites. |
+| R7 | `TESTING.md` no longer exists at the repo root. `docs/testing.md` is the single canonical testing guide. `CLAUDE.md`, `README.md`, `copilot-instructions.md`, and any solutions doc that linked to the old path point to the new one. |
+| R8 | Baselines for U6 are captured from real coverage runs against current upstream configs (not from the obsolete numbers in the superseded plan). |
+
+---
+
+## Key Technical Decisions
+
+| Decision | Choice | Why |
+|---|---|---|
+| Threshold authority | **Keep upstream's existing Vitest thresholds; do not touch them.** The ratchet adds a second layer of enforcement on top. | Upstream already ramped to 95%+. Touching their numbers reopens decisions that were settled in PRs the merged into `main` between 2026-05-17 and 2026-05-19. |
+| Ratchet implementation | **In-repo Bun script + committed `coverage-baselines.json`** | No external service, no new secrets, zero dependencies beyond the test runs that already happen. Mirrors `scripts/lint/no-duplicate-deps.ts` shape. |
+| Baseline update flow | **CI-only on `main` post-merge** | Auto-commit baseline bumps after green runs so the floor only moves up. PRs cannot edit `coverage-baselines.json` to silently lower the gate. |
+| Epsilon | **0.5 percentage points** | V8 coverage instrumentation has small run-to-run variance on identical code (observed ~0.16% on `packages/analytics` functions metric). Epsilon absorbs this without making the gate meaningless. |
+| Assertion-strength rule strictness | **Flag only genuinely weak matchers** (`toBeDefined`, `toBeTruthy`, `toBeFalsy`, `.not.toBe{Undefined,Null}`). `toBeUndefined()` and `toBeNull()` alone are NOT flagged — they assert specific return values. | Avoids false positives on tests that legitimately assert "this returns null". |
+| Helper-assertion detection | **Any call to `expect[A-Z][A-Za-z0-9]*(` counts as an assertion** (e.g., `expectUnauthorized(res)`, `expectJsonResponse(res)`). | `packages/api/test/` uses this convention extensively. Treating helpers as black-box assertions avoids flagging them as `assertion-free-test`. |
+| Lint gate enable | **Add the command, defer wiring into `check-all.ts`** | Surfaces ~handful of real findings in current upstream code. Wiring into the blocking check requires a cleanup PR first; the script ships so contributors can run it manually until then. |
+| Docs location | **`docs/testing.md`** | Per the "no random md in root" convention — `CLAUDE.md` and `README.md` are the only root markdown files. |
+
+---
+
+## Implementation Units
+
+### U1. Migrate `TESTING.md` → `docs/testing.md`
+
+- **Goal:** Honor the "no random md in root" convention. Rewrite the testing guide around current reality (upstream's 95%+ thresholds + the ratchet + the lint).
+- **Requirements:** R7
+- **Dependencies:** none
+- **Files:**
+  - `TESTING.md` (delete)
+  - `docs/testing.md` (new — moved + rewritten)
+  - `CLAUDE.md` (update Testing section: link to new path, summarize ratchet + lint)
+  - `README.md` (badge link → `/docs/testing.md`)
+  - `copilot-instructions.md` (testing section: point at `docs/testing.md`, mention new scripts)
+  - `docs/solutions/ui-bugs/android-textinput-keyboard-focus-loss.md` (cross-ref link)
+- **Approach:** The original `TESTING.md` content remains useful for patterns. The "Test Statistics" block at the bottom is out of date; replace it with a "Coverage Tier Model" matrix reflecting upstream's actual thresholds (api/expo/analytics/mcp at ~95/92/97/95). Add new sections for the ratchet and the assertion-strength lint.
+- **Test scenarios:** Test expectation: none — documentation move with no behaviour change. Verify by grep: `rg -n 'TESTING\.md' .` returns no matches outside of `docs/plans/`.
+- **Verification:** `TESTING.md` does not exist at root; `docs/testing.md` opens and renders; every `TESTING.md` reference in code, docs, and configs is updated.
+
+---
+
+### U6. Coverage ratchet + baseline file
+
+- **Goal:** Add the regression-blocking gate. Vitest thresholds enforce the floor in each workspace; the ratchet ensures the floor cannot quietly slide down across PRs.
+- **Requirements:** R1, R2, R3, R6, R8
+- **Dependencies:** none structurally; baselines must be captured from current upstream configs before commit
+- **Files:**
+  - `coverage-baselines.json` (new — repo root)
+  - `scripts/lint/coverage-ratchet.ts` (new)
+  - `scripts/lint/coverage-baseline-update.ts` (new — CI-only)
+  - `scripts/lint/__tests__/coverage-ratchet.test.ts` (new — 13 scenarios)
+  - `package.json` (add `check:coverage` and `check:coverage:update`)
+- **Approach:**
+  - Each workspace baseline carries: `summaryPath`, `tier`, four metric percentages, `recordedAt`.
+  - The ratchet reads `coverage-baselines.json` and each workspace's `coverage-summary.json`, compares per-metric with epsilon 0.5, and exits 0/1.
+  - Missing summary file → exit 1 ("silent skipping is exactly the regression mode this script exists to prevent").
+  - Malformed summary (missing required `total` fields) → exit 1.
+  - The baseline-update script bumps numbers upward when current > baseline + epsilon; never lowers. Designed for `main`-only auto-commit, not for PR-time manual updates.
+  - Initial baselines captured fresh from `bun run --cwd <workspace> test:coverage` against upstream's configs.
+- **Patterns to follow:** `scripts/lint/no-duplicate-deps.ts` for CLI shape; existing `scripts/lint/__tests__/` once U9 lands for the test layout.
+- **Test scenarios:** Per the ratchet test file:
+  - `compareWorkspace` returns `ok` / `improvement` / `regression` based on metric deltas.
+  - Tolerates noise below epsilon (default 0.5).
+  - Rejects drops just above epsilon.
+  - Reports multiple regressions in one workspace.
+  - `runRatchet` fails on missing or invalid summaries.
+  - `loadBaseline` parses workspace entries, honors `_epsilon`, falls back to default, and skips malformed entries.
+- **Verification:** `bun check:coverage` runs cleanly on the captured baselines; `bun test:scripts` includes the 13 ratchet tests.
+
+---
+
+### U9. Assertion-strength lint
+
+- **Goal:** Catch coverage theater (assertion-free tests, weak matchers, oversized snapshots, untyped mock calls) at lint time.
+- **Requirements:** R4, R5, R6
+- **Dependencies:** none — cherry-picked from prior Phase 1 work
+- **Files:**
+  - `scripts/lint/no-weak-assertions.ts`
+  - `scripts/lint/__tests__/no-weak-assertions.test.ts` (16 scenarios)
+  - `scripts/vitest.config.ts` (for `bun test:scripts`)
+  - `package.json` (add `lint:weak-assertions`, `test:scripts`)
+- **Approach:** See Key Technical Decisions for the matcher-strictness and helper-detection rules.
+- **Patterns to follow:** `scripts/lint/no-raw-typeof.ts` for shape.
+- **Test scenarios:** Each of the four rules: positive case (flags), negative case (does not flag), edge cases (`it.todo`, helper assertions, disable comment, multi-violation file).
+- **Verification:** `bun test:scripts` passes; `bun lint:weak-assertions` runs in under 5 seconds across the repo and surfaces only the small set of known-current findings.
+
+---
+
+## Risk Analysis & Mitigation
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| Captured baselines too aggressive → first PR red | Medium | Medium | Epsilon 0.5 absorbs v8 jitter. Baselines captured from clean coverage runs, not from older numbers. |
+| Lint flags too many existing tests | Confirmed (handful) | Low | Lint command exists but is NOT wired into the blocking `check-all.ts` until a separate cleanup PR. File-level `// no-weak-assertions: disable` escape hatch is available for grandfathered tests if needed. |
+| Baseline file becomes a merge-conflict magnet | Low | Low | Updates happen only on `main` via the post-merge auto-commit. PR-level edits to `coverage-baselines.json` are not the workflow. |
+| Future Vitest threshold change diverges from baseline | Low | Medium | Both layers gate independently. Vitest threshold is per-config; ratchet is per-baseline. A drop will trip whichever has a stricter floor — that's the right behaviour. Document the dual-layer model in `docs/testing.md`. |
+
+---
+
+## Verification Strategy
+
+- **U1**: `rg -n 'TESTING\.md' .` returns no matches outside `docs/plans/`. `docs/testing.md` exists and renders. `bun check` passes.
+- **U6**: `bun check:coverage` exits 0 on committed baselines; intentionally tweaking a baseline number downward makes a fresh coverage run trip the ratchet. `bun test:scripts` includes 13 ratchet tests, all passing.
+- **U9**: `bun test:scripts` includes 16 assertion-lint tests, all passing. `bun lint:weak-assertions` runs in under 5 seconds and produces a stable list of findings.
+
+---
+
+## Origin
+
+This plan supersedes `docs/plans/2026-05-17-001-chore-test-coverage-ramp-and-ci-gate-plan.md`. That document remains in place as historical context — its U2 (threshold ramp) was made obsolete by upstream work between 2026-05-17 and 2026-05-19, while its U1/U6/U9 carry forward unchanged in intent (only the baseline numbers were re-captured against the updated configs).
diff --git a/docs/plans/2026-05-19-001-fix-etl-pipeline-audit-remediation-plan.md b/docs/plans/2026-05-19-001-fix-etl-pipeline-audit-remediation-plan.md
new file mode 100644
index 0000000000..6df4f8b89c
--- /dev/null
+++ b/docs/plans/2026-05-19-001-fix-etl-pipeline-audit-remediation-plan.md
@@ -0,0 +1,1063 @@
+---
+title: "fix: ETL pipeline audit remediation"
+type: fix
+status: superseded
+supersededBy: docs/plans/2026-05-20-001-fix-etl-pipeline-workflows-migration-plan.md
+supersededReason: "Pivoted execution engine from Cloudflare Queues + outbox to Cloudflare Workflows on 2026-05-20. Workflows natively provides the durable-step + idempotency + retry + state semantics that ~8 of the 15 units in this plan were manually reconstructing. The audit findings about CSV correctness, validator hardening, observability, retention, and runbook remain real and carry into the successor plan; the queue-as-state-machine subplot is dropped."
+date: 2026-05-19
+deepened: 2026-05-19
+origin: docs/audits/2026-05-16-etl-audit.md
+---
+
+# fix: ETL pipeline audit remediation
+
+## Summary
+
+Remediate the catalog ETL pipeline against every finding in the 2026-05-16 audit (2 P0, 5 P1, 6 P2, 3 P3), correct two stale assumptions the audit made about Cloudflare runtime APIs, add bucket-vs-job reconciliation (both an admin-triggered tool and automatic post-job verification), and add a "re-ingest from the top" recovery path for jobs the buggy stuck-job sweep has already corrupted. Delivered as one master plan in four sequenced phases — schema + P0 blockers first, then chunking correctness, then observability + reconciliation, then hardening + runbook.
+
+---
+
+## Problem Frame
+
+The pipeline ingests scraper CSVs from R2 (`packrat-scrapy-bucket`) into Neon Postgres via a Cloudflare Queue consumer. It is currently silently incorrect: live prod admin data (192 runs / 74 failed = 38% failure rate) shows seven large jobs from 2026-05-14 marked `failed` with identical `completedAt` timestamps — the wall-clock-based stuck-job sweep firing on healthy long jobs — while the dashboard reports `successRate: 100%` on those same failed jobs. Audit `docs/audits/2026-05-16-etl-audit.md` enumerates the structural causes: a single shared `jobId` across byte-range chunks lets the first finishing chunk flip the parent job to `completed`, per-message exceptions are swallowed (no DLQ, no retry), byte-range chunk boundaries silently drop or invalidate rows that span them, retries discard chunking entirely, and there is no Sentry / structured logging anywhere in the ETL path.
+
+The user's stated concern — *"some [data] is missing or falsely labeling as success"* — is corroborated on both ends: `completed` jobs can be premature (P0 #1), and `failed` jobs can be false failures (P1 #2). Either way the catalog count `totalItemsIngested: 304,431` cannot currently be trusted.
+
+---
+
+## Requirements
+
+- R1. **No chunk causes premature job completion.** A multi-chunk job transitions to `completed` only when every chunk has succeeded.
+- R2. **Per-message queue failures retry and ultimately DLQ.** No exception thrown by chunk processing is silently swallowed.
+- R3. **Stuck-job sweep is progress-based, not wall-clock-based.** Healthy long-running jobs are not falsely marked `failed`.
+- R4. **Chunk boundaries do not drop or invalidate rows.** Every row in the source CSV is processed exactly once.
+- R5. **Retry / repair endpoints chunk the same way the producer does.** Retrying a large file does not single-shot it.
+- R6. **CSV header injection for non-first chunks is correct or fails loudly.** No silent column misalignment.
+- R7. **Every ETL job has post-ingestion verification.** R2 row count is compared to `totalProcessed` and the result is observable; significant deltas are surfaced.
+- R8. **Operators can trigger a "from scratch" repair of any historical job** without invoking the original producer endpoint.
+- R9. **Failures emit Sentry events with structured context.** Operators can debug a stuck job without paging through raw Worker logs.
+- R10. **Embedding-fallback degradation is observable.** A job that completed without embeddings is distinguishable from a fully-successful one.
+- R11. **Validator rejects unsafe URLs and oversize fields.** Mobile/web cannot be tricked into rendering `javascript:` URLs from the catalog.
+- R12. **`invalid_item_logs` retention is bounded.** A bad upload cannot fill Neon storage indefinitely.
+- R13. **A documented runbook exists for ETL operations.** A new on-caller can trigger / inspect / retry / drain without reading source.
+- R14. **Test coverage exists for every behavior in R1–R12.** Specifically including the cases the global queue-mock in `packages/api/test/setup.ts` currently hides.
+
+---
+
+## Scope Boundaries
+
+- The plan does not raise `max_concurrency` above 1 for the ETL queue. Concurrency bump is blocked on per-chunk idempotency keys that this plan introduces; the actual bump is a follow-up after this lands and bakes.
+- The plan does not add a DLQ to the embeddings queue. ETL queue DLQ only.
+- The plan does not migrate or rewrite the existing `etl_jobs` row data for the 7 historical jobs falsely marked `failed`. The repair-from-scratch endpoint introduced in U6 is the mechanism operators will use; the actual recovery run is operational, not a code unit.
+- The plan does not change the producer endpoint's authentication, the source CSV schema, or the scraper revision pinning.
+- The plan does not introduce a new ETL Worker — the current `packages/api` Elysia Worker continues to host both the HTTP routes and the queue consumer.
+- The plan does not address `apps/landing` / `apps/guides` / `apps/expo` consumers of catalog data even when bucket-vs-job reconciliation finds drift. Surfacing inconsistencies is in scope; downstream cache invalidation is not.
+
+### Deferred to Follow-Up Work
+
+- **Concurrency bump on `packrat-etl-queue` consumer**: separate PR after this plan ships and per-chunk idempotency is verified in production for ≥2 weeks.
+- **Embeddings-queue DLQ + retry policy**: separate plan; same shape as ETL DLQ work in U3, but a distinct surface.
+- **Catalog reconciliation across multiple historical jobs**: only per-job reconciliation is in scope. Historical cross-source rollup ("did we lose 5% of the catalog last quarter?") is a separate analytics workstream.
+- **Soft-delete / discontinued-item reconciliation** (audit P3 #3): documented as accepted limitation in the runbook (catalog is scraper-controlled, not user content). A future plan can add `availability='OutOfStock'` reconciliation if business requirements emerge.
+- **CLI subcommand surface in `packages/cli/src/commands/admin/etl.ts`**: U12 wires the new admin endpoints into the existing CLI command file. Broader CLI ergonomics work is out of scope.
+
+---
+
+## Context & Research
+
+### Relevant Code and Patterns
+
+- **Producer endpoint:** `packages/api/src/routes/catalog/index.ts:229-293` — `POST /catalog/etl`, R2 head + 20 MB chunking at `:253-271`. Chunk creation logic to extract into a shared helper used by U6.
+- **Queue producer:** `packages/api/src/services/etl/queue.ts:6-41` — `queueCatalogETL`; uses `sendBatch` with `batchSize: 100` (CF queue per-call cap).
+- **Queue consumer dispatch:** `packages/api/src/services/etl/queue.ts:43-61` — `processQueueBatch` with the swallowed catch at `:50-60`. **This is the core P0 #2 surface.**
+- **Per-chunk processor:** `packages/api/src/services/etl/processCatalogEtl.ts` — header injection (`:50-58`), partial-row skip (`:95-108`), batch flush (`:120-187`), per-chunk completion (`:188-191`), per-chunk failure (`:201-204`).
+- **Atomic counter pattern (mirror this):** `packages/api/src/services/etl/updateEtlJobProgress.ts:16-23` — `sql\`COALESCE(${col}, 0) + ${n}\``. New `chunks_completed` / `total_embedding_failures` increments use the same idiom; the "set status=completed when chunks_completed+1 == chunks_total" branch uses a single `UPDATE ... SET ... WHERE` with a `CASE` expression in the same transaction.
+- **Embeddings queue pattern (mirror this):** `packages/api/src/services/catalogService.ts:461-507` — consumer rethrows on failure so CF Queue retries fire. ETL consumer must adopt the same shape.
+- **Admin routing pattern:** `packages/api/src/routes/admin/index.ts:117-237` mounts the admin prefix; `:230-237` enforces `adminAuthGuard` on every sub-route. New endpoints in `packages/api/src/routes/admin/analytics/catalog.ts` inherit the guard.
+- **R2 access (S3-API not Workers binding):** `packages/api/src/services/r2-bucket.ts:193-360` — `R2BucketService({ env, bucketType: 'catalog' })` wraps `@aws-sdk/client-s3` against the R2 S3 endpoint. `r2.head(key)` and `r2.get(key, { range: { offset, length } })` are the surface. Range format `bytes=offset-(offset+length-1)` at `:675-691`.
+- **Schema location:** `packages/db/src/schema.ts:446-510` — `etlJobs`, `invalidItemLogs`, `catalogItemEtlJobs`, status enum at `:460`. **Audit cites a stale path (`packages/api/src/db/schema.ts`); the file was extracted into the `packages/db` package — see merge `b14f4dbd5`.**
+- **Drizzle migration location:** `packages/api/drizzle/NNNN_<name>.sql` + `meta/NNNN_snapshot.json` + `_journal.json`. Latest is `0047_cute_bloodscream.sql`; new migrations land at `0048` and `0049` (split per Drizzle Kit's enum-add constraint). Generated via `bun run --cwd packages/api db:generate`. Custom linter at `scripts/lint/check-drizzle-migrations.ts` runs in `lint:custom`.
+- **Existing ETL integration test:** `packages/api/test/etl.test.ts` — mocks `R2BucketService` per-test, uses real Postgres via wsproxy at `localhost:5434`. Setup at `packages/api/test/setup.ts:535-572` globally mocks both `queueCatalogETL` and `processQueueBatch` (lines `:544-551`) — this is precisely *why* the per-message swallow in P0 #2 is invisible to CI today, and U14 must un-mock to cover it.
+- **Wrangler config:** `packages/api/wrangler.jsonc:65-89` (prod queues) and `:161-194` (dev). Currently `max_batch_size: 1, max_concurrency: 1`, **no `dead_letter_queue`, no `max_retries`** on either consumer. Queue routing handler at `packages/api/src/index.ts:109-124`.
+- **Admin CLI surface:** `packages/cli/src/commands/admin/etl.ts` already exists. New endpoints in U6 and U12 add corresponding subcommands.
+
+### Institutional Learnings
+
+- `docs/solutions/` has no prior ETL, Cloudflare Queues, R2 byte-range, or Sentry-in-Workers learnings — only an unrelated Better Auth CLI note and an Android UI bug. This remediation is greenfield from an institutional-knowledge standpoint, which makes it a strong `/ce-compound` target after each phase ships.
+
+### External References
+
+- **Cloudflare Queues — ack/retry semantics:** `message.ack()` / `message.retry({ delaySeconds })` / `ackAll()` / `retryAll()` documented at <https://developers.cloudflare.com/queues/configuration/javascript-apis/>. Throwing fails the un-acked remainder of the batch. `retryDelaySeconds` max is 24h per <https://developers.cloudflare.com/queues/platform/limits/>.
+- **Cloudflare Queues — DLQ:** `dead_letter_queue` (string name) + `max_retries` (default 3, max 100) in the consumer block per <https://developers.cloudflare.com/queues/configuration/dead-letter-queues/>.
+- **Cloudflare Workers Scheduler:** Only `scheduler.wait(ms)` is documented at <https://developers.cloudflare.com/workers/runtime-apis/scheduler/>. **`scheduler.yield()` does not exist** — the audit P2 #5 recommendation is wrong on this. Use `await scheduler.wait(0)` instead.
+- **Wall-clock limit:** Queue consumer wall-clock cap is **15 minutes**, not 30 seconds, per <https://developers.cloudflare.com/queues/platform/limits/>. The audit's "30 s wall-clock" framing under P2 #5 is stale.
+- **Sentry on Cloudflare:** Prefer the first-party `@sentry/cloudflare` over toucan-js. Wrap via `Sentry.withSentry(optsFn, { fetch, queue })` per <https://docs.sentry.io/platforms/javascript/guides/cloudflare/>. Queue instrumentation guidance at <https://docs.sentry.io/platforms/javascript/guides/cloudflare/tracing/instrumentation/queues-module/>.
+- **Drizzle enum-add limitation:** `ALTER TYPE … ADD VALUE` inside the same transaction as code that uses the new value fails. Split migrations. Tracked at <https://github.com/drizzle-team/drizzle-orm/issues/3249>.
+- **R2 range reads with AWS SDK:** R2's S3 API fully supports the `Range` header — `GetObjectCommand({ Range: 'bytes=0-1023' })` behaves identically to S3 per <https://developers.cloudflare.com/r2/api/s3/api/>.
+
+---
+
+## Key Technical Decisions
+
+- **Track chunk completion via two new columns (`chunks_total`, `chunks_completed`) on the existing `etl_jobs` row, gated by a per-chunk idempotency table `etl_job_chunks(job_id, chunk_index, completed_at)` with PK on `(job_id, chunk_index)`.** Rationale: even at `max_concurrency: 1` today, Cloudflare Queues are *at-least-once* — a chunk whose DB writes succeed but whose ack is lost will be redelivered, which would double-increment a naive `chunks_completed = chunks_completed + 1` and either crash through `chunks_total` or transition the job to `completed` while a sibling chunk is still pending. The idempotency table makes the increment a deterministic side-effect of `INSERT … ON CONFLICT (job_id, chunk_index) DO NOTHING RETURNING 1`; the counter only bumps when the insert created a new row. This was originally scoped as a follow-up under "Deferred" but the deepening pass surfaced it as a correctness prerequisite — pulled forward into U1/U2.
+- **No new `partial` enum value on `etl_job_status`.** Embedding-fallback degradation is observable via `total_embedding_failures > 0` on a `completed` row. Adding an enum value would force the audit P2 #3 split into two migrations (Drizzle Kit limitation) and complicate every admin filter without observable benefit.
+- **Use `@sentry/cloudflare` (first-party), not toucan-js as the audit suggested.** Toucan still works but is no longer the recommended Sentry path on Workers as of 2026. `withSentry({ fetch, queue })` wraps both entry points in one call; no manual `waitUntil` plumbing needed.
+- **Use `await scheduler.wait(0)` for yielding, not the non-existent `scheduler.yield()`.** Audit P2 #5 is corrected here.
+- **Stuck-job sweep keyed on `last_progress_at < now() - interval '15 minutes'` AND `status = 'running'`,** not on `started_at`. The 15-min figure derives from the actual CF Queue consumer wall-clock cap (15 min), not the audit's stale 30 s/30 min framing. With per-chunk progress updates writing `last_progress_at`, any chunk making real progress is safe; only truly stalled jobs flip to `failed`.
+- **Row-boundary alignment happens in the producer**, not the consumer. The producer's `r2.head(key)` flow does an extra small range read on each chunk-end region (e.g., 64 KB) to find the last `\n` and emits chunks with newline-aligned `byteEnd`. This eliminates both the partial-row skip bug (P1 #4) and the row-spanning-chunk bug (P1 #5) in one place. Consumer's `skipPartialRow` logic is removed.
+- **CSV header re-read with bounded loop, not a fixed 4 KB slice.** For non-first chunks, the consumer fetches `[0, 4096)`, and if no `\n` appears, expands to `[0, 16384)`, then `[0, 65536)`. If still no newline, throw — header is malformed. Eliminates P1 #3 silent column misalignment.
+- **Per-chunk idempotency key is `(jobId, chunkIndex)`** — added to `CatalogETLMessage`. Even though `max_concurrency: 1` means de-facto serialization today, threading the key now unblocks the future concurrency bump without another migration.
+- **DLQ is a dedicated new queue `packrat-etl-dlq`** with a minimal consumer that captures the failure to Sentry, persists a row to a new `etl_dlq_events` table for forensics, and acks. The DLQ does *not* attempt to re-process — it's an event sink + visibility tool.
+- **Reconciliation runs as both a manual admin endpoint and an automatic post-job step, with the automatic step on its own queue.** Manual endpoint stays synchronous (operator-explicit, scoped to one job). Automatic step is dispatched as a queue message to a new `packrat-etl-reconcile-queue` on the final-chunk completion transition, *not* via `ctx.waitUntil` — `waitUntil` shares the queue invocation's wall-clock budget, which for a multi-GB CSV exceeds the 15-min cap when added on top of the chunk's own processing time. The reconcile consumer streams the file in 100 MB byte-range windows with progress checkpointed to a transient column so retries resume. The consumer's `INSERT … RETURNING` includes `verified_at IS NULL` as an idempotency gate so a redelivered reconcile message is a no-op. Warning threshold remains `> max(10, ceil(0.01 * total_processed))`.
+- **Repair-from-scratch endpoint creates a NEW `etl_jobs` row and links it to the old via a new nullable `superseded_by_job_id` column with `ON DELETE SET NULL` and a paired `superseded_at timestamp`.** No mutation of the old row's counters — preserves audit trail and lets the dashboard show "originally failed, repaired by job X". `ON DELETE SET NULL` (not `CASCADE`) so deleting one row never silently nukes a chain of repair attempts. A CHECK constraint prevents self-reference (`superseded_by_job_id != id`). The runbook procedure (U15) requires verifying R2 source presence + ETag match before invoking repair, so an overwritten source cannot silently re-ingest the wrong file.
+- **Structured logger lives at `packages/api/src/utils/logger.ts`** as a thin wrapper around `console.*` for now, accepting a `LogContext` (jobId, chunkIndex, r2Key, etc.) and emitting JSON-prefixed lines. Sentry breadcrumbs piggyback on the same call surface. Not a full logger framework — that's a separate decision.
+
+---
+
+## Open Questions
+
+### Resolved During Planning
+
+- **Should the chunk completion track go on `etl_jobs` columns alone, or be paired with a per-chunk idempotency table?** Resolved during deepening: both. `etl_jobs.{chunks_total, chunks_completed}` are the counters; `etl_job_chunks(job_id, chunk_index)` is the idempotency gate that makes the increment safe under at-least-once delivery. See Key Technical Decisions.
+- **Should embedding-fallback get a new enum value `partial`?** Resolved: no — use `total_embedding_failures` counter on a `completed` row.
+- **Toucan-js or `@sentry/cloudflare`?** Resolved: `@sentry/cloudflare`. See External References.
+- **Wall-clock budget for the stuck-job sweep cutoff?** Resolved: `last_progress_at < now() - interval '15 minutes'`, matching the actual queue-consumer wall-clock cap.
+- **Should the row-boundary alignment happen in producer or consumer?** Resolved: producer. Single source of truth for chunk boundaries.
+- **Should auto-reconcile use `ctx.waitUntil` or its own queue?** Resolved during deepening: dedicated queue (`packrat-etl-reconcile-queue`) with resumable byte-range streaming. `waitUntil` shares the chunk consumer's wall-clock budget, which fails at multi-GB files.
+- **Should the DLQ consumer's INSERT + status UPDATE be transactional?** Resolved during deepening: yes, single `db.transaction()`. Same for the sweep's UPDATE + sentinel-event INSERT.
+- **Should the migration split into 0048a/0048b/0048c?** Resolved during deepening: no — at ~200 rows, the single-migration approach is fine. Splitting becomes correct when `etl_jobs` exceeds ~100k rows, and the migration header carries a comment to revisit at that scale.
+
+### Deferred to Implementation
+
+- **Exact Drizzle migration sequencing within Phase 1.** All six columns + the partial index + the new `etl_dlq_events` table can land in a single migration `0048` since none touch the enum. Whether to split `superseded_by_job_id` (added later in U6) into its own migration `0049` or include it in `0048` is decided at U1 implementation. Either way the enum stays untouched in this plan.
+- **`@sentry/cloudflare` instrumentation depth for the queue consumer.** The exact `Sentry.startSpan` attributes per queue message (some attributes are conventional, some are CF-specific) get finalized when U8 lands.
+- **Sentry sampling rate** for the queue consumer. Default to `tracesSampleRate: 0.1` and tune in production; not a plan-time decision.
+- **Exact threshold for "significant" reconciliation delta** that triggers a Sentry warning vs informational event. Default: `> max(10, ceil(0.01 * total_processed))` rows of delta. Tunable in production.
+- **Cron schedule for `invalid_item_logs` retention sweep.** Daily at 09:00 UTC unless ops has a quieter window.
+
+---
+
+## High-Level Technical Design
+
+> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
+
+```text
+Producer  ─── POST /catalog/etl ──┐
+                                  │
+                                  ▼
+        ┌─────────────────────────────────────────────┐
+        │ chunkCsvForR2(key)  (NEW shared helper)     │
+        │   1. r2.head(key) -> size                   │
+        │   2. for each 20 MB window:                 │
+        │        peek (next 64 KB) to find last '\n'  │
+        │        emit chunk with byteEnd = newline-1  │
+        │   3. tag each chunk: { jobId, chunkIndex,   │
+        │                        chunksTotal, byteRange }
+        └─────────────────────────────────────────────┘
+                                  │
+                          INSERT etl_jobs
+                          (status='running',
+                           chunks_total=N,
+                           chunks_completed=0)
+                                  │
+                          ETL_QUEUE.sendBatch(chunks)
+                                  │
+                                  ▼
+        ┌─────────────────────────────────────────────┐
+        │ processQueueBatch (REWRITE)                 │
+        │   for message of batch:                     │
+        │     try {                                   │
+        │       processCatalogETL(msg)                │
+        │       message.ack()                         │
+        │     } catch (err) {                         │
+        │       Sentry.captureException(err, {...})   │
+        │       message.retry({ delaySeconds: 30 })   │
+        │     }                                       │
+        └─────────────────────────────────────────────┘
+                                  │
+                                  ▼
+        ┌─────────────────────────────────────────────┐
+        │ processCatalogETL (per chunk)               │
+        │   r2.get(key, range) -> stream              │
+        │   if chunkIndex > 0: re-fetch header        │
+        │     (expand 4K→16K→64K, throw if no '\n')   │
+        │   parse rows (csv-parse, backpressure)      │
+        │   per 100 rows: scheduler.wait(0)           │
+        │   flush valid -> processValidItemsBatch     │
+        │     (embedding fallback increments          │
+        │      total_embedding_failures atomically)   │
+        │   flush invalid -> processLogsBatch         │
+        │     (now RETHROWS on DB failure)            │
+        │   on success:                               │
+        │     UPDATE etl_jobs                         │
+        │       SET chunks_completed = chunks_completed+1,
+        │           last_progress_at = now(),         │
+        │           status = CASE                     │
+        │             WHEN chunks_completed+1         │
+        │                  = chunks_total             │
+        │             THEN 'completed'                │
+        │             ELSE status                     │
+        │           END                               │
+        │     if completed (in same txn):             │
+        │       enqueue ReconcileMessage to           │
+        │       packrat-etl-reconcile-queue           │
+        └─────────────────────────────────────────────┘
+                                  │
+                  (on completion transition)
+                                  ▼
+        ┌─────────────────────────────────────────────┐
+        │ processReconcileBatch                       │
+        │   reconcileJob(jobId, resumeFromByte=0):    │
+        │     if verified_at IS NOT NULL: ack         │
+        │     stream 100 MB byte-range windows        │
+        │       checkpoint to                         │
+        │         verified_row_count_partial          │
+        │       if budget low: throw ResumeError      │
+        │         (consumer re-enqueues)              │
+        │     on EOF: UPDATE verified_at, count       │
+        │     if delta > threshold: Sentry warning    │
+        └─────────────────────────────────────────────┘
+                                  │
+                  (on any thrown error after retries)
+                                  ▼
+                          packrat-etl-dlq
+                                  │
+                                  ▼
+        ┌─────────────────────────────────────────────┐
+        │ dlqConsumer                                 │
+        │   Sentry.captureException                   │
+        │   INSERT etl_dlq_events                     │
+        │   ack                                       │
+        └─────────────────────────────────────────────┘
+
+Background (CF Cron):
+  stuck-job sweep: status='running' AND last_progress_at < now()-15min
+                   -> status='failed', emit Sentry warning
+  invalid-log retention: DELETE FROM invalid_item_logs WHERE created_at < now()-90d
+```
+
+---
+
+## Implementation Units
+
+### U1. Schema migration: chunk tracking, idempotency table, progress timestamp, embedding failures, reconciliation columns, DLQ events table, constraint hardening
+
+**Goal:** Add the columns, tables, indexes, and constraints that the rest of the plan reads and writes. Lands first so every subsequent unit can compile and migrate against a known schema. Single migration `0048` is acceptable at the current ~200-row scale of `etl_jobs`; splitting into multiple migrations is unnecessary engineering at this size (revisit if `etl_jobs` exceeds ~100k rows).
+
+**Requirements:** R1, R3, R7, R8, R10
+
+**Dependencies:** None
+
+**Files:**
+- Modify: `packages/db/src/schema.ts` (add columns to `etlJobs`; add new `etlJobChunks` table; add new `etlDlqEvents` table; add UNIQUE constraint to `catalogItemEtlJobs`; export all)
+- Create: `packages/api/drizzle/0048_etl_chunking_and_observability.sql`
+- Create: `packages/api/drizzle/meta/0048_snapshot.json` (generated)
+- Modify: `packages/api/drizzle/meta/_journal.json` (generated)
+- Test: `packages/api/test/db-schema-etl.test.ts` (new — schema smoke test asserting columns exist with expected defaults; uses the existing Docker Postgres wsproxy setup at `localhost:5434`)
+
+**Approach:**
+- Columns added to `etl_jobs`:
+  - `chunks_total integer` (nullable — single-chunk legacy jobs leave it null)
+  - `chunks_completed integer DEFAULT 0 NOT NULL`
+  - `last_progress_at timestamp` (nullable initially; backfilled to `started_at` for legacy rows in the same migration)
+  - `total_embedding_failures integer DEFAULT 0 NOT NULL`
+  - `verified_at timestamp` (nullable)
+  - `verified_row_count integer` (nullable)
+  - `verified_row_count_partial integer` (nullable — checkpoint for resumable reconcile in U10)
+  - `superseded_by_job_id text` (nullable, FK to `etl_jobs.id` `ON DELETE SET NULL`)
+  - `superseded_at timestamp` (nullable — paired with `superseded_by_job_id` so the timeline survives even after FK cleanup)
+  - `source_etag text` (nullable — captured on producer insert from `r2.head(objectKey).etag`; U6's repair endpoint uses this for failure-closed source verification)
+  - `source_last_modified timestamp` (nullable — same capture; redundant with etag but cheap)
+- CHECK constraints on `etl_jobs`:
+  - `etl_jobs_chunks_completed_lte_total CHECK (chunks_total IS NULL OR chunks_completed <= chunks_total)` — fail loudly on over-count.
+  - `etl_jobs_no_self_supersede CHECK (superseded_by_job_id IS NULL OR superseded_by_job_id <> id)` — prevent self-referential repair loop.
+- New indexes on `etl_jobs`:
+  - Partial: `etl_jobs_running_progress_idx` on `(status, last_progress_at)` `WHERE status = 'running'` — for the U5 stuck-job sweep.
+  - Partial: `etl_jobs_unverified_idx` on `(verified_at)` `WHERE status = 'completed' AND verified_at IS NULL` — for the U10 watchdog scan.
+  - `etl_jobs_superseded_by_idx` on `(superseded_by_job_id)` — for the admin dashboard's "is this job superseded?" lookup.
+- New table `etl_job_chunks` (per-chunk idempotency, see Key Technical Decisions):
+  - `job_id text NOT NULL` (FK to `etl_jobs.id` `ON DELETE CASCADE`)
+  - `chunk_index integer NOT NULL`
+  - `completed_at timestamp DEFAULT now() NOT NULL`
+  - `PRIMARY KEY (job_id, chunk_index)`
+- New table `etl_dlq_events`: `id text PK`, `job_id text` (FK, nullable, `ON DELETE SET NULL`), `chunk_index integer`, `message_body jsonb`, `error_message text`, `error_stack text`, `attempts integer`, `source text` (one of `consumer`, `sweep`; defaults to `consumer`), `created_at timestamp DEFAULT now() NOT NULL`. Index on `created_at`.
+- Modification to `catalog_item_etl_jobs`: add `UNIQUE (catalog_item_id, etl_job_id)` so a redelivered chunk's upsert can use `ON CONFLICT DO NOTHING` and not produce duplicate provenance rows.
+- Backfill: `UPDATE etl_jobs SET last_progress_at = started_at WHERE last_progress_at IS NULL`. Safe — `etl_jobs` is ~200 rows; sub-100ms on Neon.
+- Drizzle generator: `bun run --cwd packages/api db:generate` then verify the SQL file matches the design. **Verify Drizzle Kit emits `DEFAULT 0 NOT NULL` literally in the SQL** — Drizzle sometimes drops the SQL-side default and keeps only the JS-side, which would break inserts from in-flight old workers during a rolling deploy. **Do NOT touch the `etl_job_status` enum in this migration** — no new enum value is needed (see Key Technical Decisions).
+- Drizzle Kit does not auto-emit `CONCURRENTLY` for indexes. At 200 rows the index build is instant so `CONCURRENTLY` is nice-to-have, not blocking. If the table grows >100k rows before this lands, hand-edit the generated SQL to use `CREATE INDEX CONCURRENTLY IF NOT EXISTS` and split each index into its own statement-breakpoint block.
+
+**Patterns to follow:**
+- Existing `etl_jobs` definition at `packages/db/src/schema.ts:460-479` for column shape and import style.
+- Migration `0027_past_madrox.sql` (added `scraper_revision` + index) for the "add column + partial index" pattern.
+- `scripts/lint/check-drizzle-migrations.ts` runs in `lint:custom`; the new migration must pass it.
+
+**Test scenarios:**
+- Happy path: After migration runs against a populated test DB, all 8 new `etl_jobs` columns are present with the documented defaults; `etl_job_chunks` and `etl_dlq_events` exist; the three new partial/normal indexes are queryable (`EXPLAIN SELECT ... WHERE status='running' ...` uses the running-progress index; the unverified index serves the watchdog).
+- Happy path: `INSERT INTO etl_job_chunks (job_id, chunk_index) VALUES ('j1', 0)` succeeds; a duplicate insert returns no row via `ON CONFLICT DO NOTHING RETURNING 1` and the table still contains exactly one row.
+- Edge case: Legacy rows have `chunks_total = NULL` and `last_progress_at` backfilled to `started_at`.
+- Edge case: `chunks_completed DEFAULT 0` is correctly applied to existing rows (verify with a row that has `chunks_completed = 0` post-migration). The generated SQL must literally include `DEFAULT 0 NOT NULL` — assert via SQL `information_schema.columns`.
+- Edge case: `UNIQUE (catalog_item_id, etl_job_id)` on `catalog_item_etl_jobs` prevents a duplicate-insert (returns conflict).
+- Error path: Attempting to insert a row with `chunks_completed > chunks_total` violates the CHECK constraint and errors clearly.
+- Error path: Attempting to set `superseded_by_job_id = id` violates the no-self-supersede CHECK.
+- Error path: Re-running the migration on an already-migrated DB is a no-op (Drizzle's migration log handles this; smoke-test the up/down via `bun run --cwd packages/api db:migrate`).
+- Edge case: Down-migration cleanly drops the new columns/tables on a DB with no Phase 2+ data. **Once Phase 2 ships and writes start landing in the new columns, the migration is forward-only** — document in the migration header comment.
+
+**Verification:**
+- `bun run --cwd packages/api db:migrate` applies cleanly against a fresh Docker Postgres + against a Postgres seeded with current-prod-shape `etl_jobs` rows.
+- `bunx drizzle-kit check` (run from `packages/api/`) validates the snapshot chain is internally consistent — run this before pushing any migration change.
+- `bun lint:custom` passes on the new migration.
+- `bun test:api:unit` includes the new schema test and it passes.
+
+---
+
+### U2. P0 #1 fix: chunk-completion lifecycle in producer + consumer
+
+**Goal:** A multi-chunk job's `status` transitions to `completed` only after every chunk has finished. Premature completion eliminated.
+
+**Requirements:** R1
+
+**Dependencies:** U1
+
+**Files:**
+- Modify: `packages/api/src/routes/catalog/index.ts` (producer endpoint sets `chunks_total` on `etl_jobs` insert and tags each `CatalogETLMessage` with `chunkIndex` and `chunksTotal`)
+- Modify: `packages/api/src/services/etl/types.ts` (extend `CatalogETLMessage.data` with `chunkIndex: number` and `chunksTotal: number`; `byteStart`/`byteEnd` remain)
+- Modify: `packages/api/src/services/etl/processCatalogEtl.ts` (rewrite the `:188-191` success-path UPDATE to use the `CASE` expression that flips status only when `chunks_completed + 1 = chunks_total`; also update `last_progress_at` on every counter write)
+- Modify: `packages/api/src/services/etl/updateEtlJobProgress.ts` (include `last_progress_at: sql\`now()\`` in the update set so every progress write refreshes the sweep timestamp)
+- Test: `packages/api/test/etl-chunk-completion.test.ts` (new)
+
+**Approach:**
+- Producer: compute `chunks` first, then `INSERT etl_jobs (..., chunks_total) VALUES (..., ${chunks.length})` — a single round-trip including `chunks_total`. Then `sendBatch` with each message carrying `chunkIndex` 0..N-1 and `chunksTotal: N`. Setting `chunks_total` in the initial INSERT (rather than a separate follow-up UPDATE) eliminates a window where a chunk consumer could observe `chunks_total IS NULL` and silently fail the `chunks_completed + 1 = chunks_total` CASE comparison.
+- Consumer success path runs inside a single Drizzle `db.transaction()`:
+  1. `INSERT INTO etl_job_chunks (job_id, chunk_index) VALUES ($1, $2) ON CONFLICT (job_id, chunk_index) DO NOTHING RETURNING 1` — the idempotency gate. If no row returned, this is a redelivery; skip the increment, ack the message, return.
+  2. If the insert created a row, run the atomic UPDATE: `UPDATE etl_jobs SET chunks_completed = chunks_completed + 1, last_progress_at = now(), status = CASE WHEN chunks_completed + 1 = chunks_total THEN 'completed' ELSE status END, completed_at = CASE WHEN chunks_completed + 1 = chunks_total THEN now() ELSE completed_at END WHERE id = $1 AND status = 'running' RETURNING status, chunks_completed, chunks_total`.
+  3. The `WHERE status = 'running'` gate prevents clobbering a row the U5 sweep has already flipped to `failed` (status-flip-flop hazard).
+  4. If the returned row shows the transition to `completed`, *and* this transaction was the one that created the chunk-row in step 1, send a message to `packrat-etl-reconcile-queue` (see U10) for the auto-reconcile.
+- On per-chunk failure: the consumer no longer flips the parent job to `failed` immediately. Instead it lets the message throw / retry. The parent job only flips to `failed` via (a) DLQ consumer when retries are exhausted, or (b) the stuck-job sweep (U5).
+- Single-chunk legacy jobs: when `chunks_total IS NULL`, the `etl_job_chunks` insert still gates the increment; legacy rows backfilled to `chunks_total = 1` migrate cleanly. Backwards-compatible with any in-flight legacy messages.
+- The CHECK constraint `chunks_completed <= chunks_total` from U1 is the loud-failure safety net — if the idempotency gate ever leaks (e.g., a code bug bypasses the chunk-table insert), the next `UPDATE` errors with a constraint violation rather than silently corrupting the counter.
+
+**Patterns to follow:**
+- Atomic SQL update idiom at `packages/api/src/services/etl/updateEtlJobProgress.ts:16-23`.
+- Drizzle transaction shape: `await db.transaction(async (tx) => { ... })`.
+
+**Test scenarios:**
+- Happy path: 5-chunk job; chunks 0..3 complete successfully → status remains `running` with `chunks_completed = 4`; chunk 4 completes → status flips to `completed`, `completed_at` set, `etl_job_chunks` has 5 rows.
+- Happy path (idempotency): Chunk 2 succeeds, ack lost, CF redelivers → second attempt's `INSERT … ON CONFLICT DO NOTHING RETURNING` returns no row → increment is skipped → `chunks_completed` increments exactly once over the two deliveries.
+- Edge case: Chunks complete out of order (chunk 3 finishes before chunk 1) → status flips only when all five have incremented; the `etl_job_chunks` rows record actual completion order.
+- Edge case: Single-chunk legacy job (`chunks_total = 1`) → flips to `completed` on its one success; `etl_job_chunks` has 1 row.
+- Edge case: Sweep flips job to `failed` mid-flight; the next chunk's UPDATE `WHERE … AND status = 'running'` returns zero rows → transaction sees the conflict, logs warning, lets the operator route to repair-from-scratch.
+- Error path: One chunk throws; other chunks succeed → parent job stays `running` while CF Queue retries the failed chunk; if retries exhaust, DLQ consumer (U3) handles state transition.
+- Error path: CHECK constraint trips (hypothetical leaked-idempotency bug) → UPDATE errors loudly, chunk retries, no silent corruption.
+- Integration: With `R2BucketService` mocked to return a small CSV split into 3 chunks via `byteRange`, the full producer→queue→consumer cycle ends in exactly one `status=completed` transition for the parent job AND exactly one reconcile message enqueued.
+- Integration (idempotency at scale): Replay every chunk message twice → `etl_job_chunks` has exactly `chunks_total` rows, counters match, status = `completed`.
+
+**Verification:**
+- Re-running `etl.test.ts` plus the new test under `bun test:api` shows no `status='completed'` write until `chunks_completed = chunks_total`.
+- A manual prod-shape replay (`POST /catalog/etl` against the dev Worker with a CSV that produces ≥3 chunks) shows the dashboard's `successRate` remain at the running state until all chunks finish.
+
+---
+
+### U3. P0 #2 fix: explicit ack/retry + DLQ wiring
+
+**Goal:** No per-message exception is silently swallowed. Failures retry; exhausted retries land in a dedicated DLQ that emits Sentry events and persists for forensics.
+
+**Requirements:** R2, R9
+
+**Dependencies:** U1 (for `etl_dlq_events` table)
+
+**Files:**
+- Modify: `packages/api/src/services/etl/queue.ts` (rewrite `processQueueBatch` for explicit per-message ack/retry; remove the swallow at `:50-60`)
+- Create: `packages/api/src/services/etl/processDlqEvent.ts` (DLQ consumer; INSERT into `etl_dlq_events`, capture Sentry exception, ack)
+- Modify: `packages/api/src/index.ts` (extend the `queue()` switch at `:109-124` with arms for `packrat-etl-dlq` and `packrat-etl-dlq-dev`)
+- Modify: `packages/api/wrangler.jsonc` (declare `packrat-etl-dlq` and `packrat-etl-dlq-dev` as producer + consumer; add `dead_letter_queue: "packrat-etl-dlq"` and `max_retries: 3` to the ETL consumer block at `:78-82` and dev equivalent at `:178-182`)
+- Modify: `packages/api/src/services/etl/processCatalogEtl.ts` (when a chunk's processing throws, also UPDATE `last_progress_at` and increment a transient `last_error_at` if useful — see Approach for trade-off; primary work is removing the per-chunk `status='failed'` write at `:201-204` since the DLQ consumer is now responsible for state transition)
+- Test: `packages/api/test/etl-queue-retry.test.ts` (new — covers the global-mock blind spot in `setup.ts:544-551`)
+
+**Approach:**
+- Rewrite `processQueueBatch`:
+  ```text
+  for (const message of batch.messages) {
+    try {
+      await processCatalogETL({ message: message.body, env });
+      message.ack();
+    } catch (err) {
+      logger.error('etl.chunk.failed', { jobId, chunkIndex, err });
+      Sentry.captureException(err, { tags: { jobId, chunkIndex, r2Key }, contexts: { queue: { messageId: message.id, attempts: message.attempts } } });
+      message.retry({ delaySeconds: 30 });
+    }
+  }
+  ```
+  (Sentry wiring lives in U8; in U3 the call sites are added as no-ops that U8 fills in.)
+- DLQ consumer reads from `packrat-etl-dlq` and, inside a single `db.transaction()`, performs: (1) `INSERT INTO etl_dlq_events (… source = 'consumer')` capturing `{ jobId, chunkIndex, message_body, error_message, error_stack, attempts }`, (2) `UPDATE etl_jobs SET status = 'failed', completed_at = now() WHERE id = $1 AND status = 'running'` — the `WHERE status = 'running'` clause is the no-op gate that prevents racing the U5 sweep. `Sentry.captureException` fires *before* the transaction (so the event survives even if the DB transaction rolls back) with tags `{ jobId, chunkIndex, r2Key }`. The `error_stack` field is contractually free of raw CSV row data — only structural error messages — to avoid accidental PII capture (documented at the call site).
+- Wrangler config additions:
+  ```text
+  // producer
+  { "queue": "packrat-etl-dlq", "binding": "ETL_DLQ" }
+  // consumer
+  { "queue": "packrat-etl-dlq", "max_batch_size": 10, "max_batch_timeout": 30 }
+  // on the existing ETL consumer:
+  "dead_letter_queue": "packrat-etl-dlq",
+  "max_retries": 3
+  ```
+  Same shape applied to `*-dev` queues.
+- The removal of the per-chunk `status='failed'` write at `processCatalogEtl.ts:201-204` is critical — leaving it would race with the DLQ consumer's state transition.
+- `processCatalogETL` rethrows on any internal failure (it already does); no behavioral change other than the consumer's catch now retries instead of swallowing.
+
+**Patterns to follow:**
+- Embeddings consumer pattern at `packages/api/src/services/catalogService.ts:461-507` for the rethrow shape.
+- Existing `queue()` dispatch at `packages/api/src/index.ts:109-124` for the new DLQ arm.
+
+**Test scenarios:**
+- Happy path: Single message processes successfully → `message.ack()` called exactly once; no retry; no DLQ row.
+- Error path: Transient throw (simulated R2 5xx) → first call: `message.retry({ delaySeconds: 30 })` and no DLQ; second call succeeds → ack. Total DLQ rows = 0.
+- Error path: Permanent throw (4 attempts all fail) → exhausts `max_retries: 3` → message routed to `packrat-etl-dlq` → DLQ consumer inserts row in `etl_dlq_events` with `attempts = 4`, captures Sentry, flips `etl_jobs.status = 'failed'`.
+- Integration: Un-mock `processQueueBatch` (override `setup.ts:544-551` per-file with `vi.doUnmock`) and exercise the real consumer against an in-memory queue stub.
+- Edge case: Two messages in a batch, first throws and second succeeds (this should not happen at `max_batch_size: 1` but the code path supports it) → first retries, second acks; no cross-contamination of state.
+
+**Verification:**
+- New test passes with the per-message catch removed; passes with the catch present too (so the test actually proves the new behavior).
+- `bun test:api` overall still green.
+- Inspecting `packrat-etl-dlq` queue depth in `wrangler queues info packrat-etl-dlq-dev` after a forced failure shows zero (because the DLQ consumer drains immediately).
+
+---
+
+### U4. Sweep cleanup: remove the broken wall-clock stuck-job sweep before U5 replaces it
+
+**Goal:** Take the existing `POST /admin/etl/reset-stuck` endpoint out of production rotation before U5's progress-based replacement lands, to stop new false-failures while the rest of Phase 2 ships.
+
+**Requirements:** R3
+
+**Dependencies:** None (independent of U1; this is a code removal)
+
+**Files:**
+- Modify: `packages/api/src/routes/admin/analytics/catalog.ts` (remove or guard the `POST /admin/etl/reset-stuck` route at `:384-409`; if removed, also remove from the OpenAPI spec)
+- Modify: `packages/cli/src/commands/admin/etl.ts` (drop any subcommand wired to the removed endpoint)
+- Test: `packages/api/test/admin-etl-routes.test.ts` (new or extend existing — assert the route returns 410 Gone or is absent)
+
+**Approach:**
+- Two options, both acceptable:
+  - **Remove the route entirely.** Anyone calling it gets a 404. Cleanest. Recommended if no automation depends on it.
+  - **Replace the route body with a 410 Gone response** that links to the runbook (added in U15) and the new sweep design from U5. Use if there's any concern about external automation calling it.
+- Existing endpoint logic at `:384-409` does `UPDATE etl_jobs SET status='failed' WHERE status='running' AND started_at < now() - interval '30 minutes'`. This is the SQL that wrongly failed the 7 jobs on 2026-05-14.
+- This unit ships before U5 lands the replacement, so for a short window there is no automated sweep at all. Acceptable because stuck-job recovery in that window is operational (U15 runbook documents the manual SQL).
+
+**Patterns to follow:**
+- Existing admin route removal pattern (none in repo as of this writing); fall back to standard Elysia route definition omission.
+
+**Test scenarios:**
+- Happy path: `POST /admin/etl/reset-stuck` returns 410 (or 404 if removed) — test asserts on the chosen behavior.
+- Edge case: Admin CLI subcommand for the old endpoint no longer exists (or returns a clear "removed, see runbook" message).
+
+**Verification:**
+- `bun test:api` passes with the new assertion.
+- Manual `curl` against dev Worker returns the chosen status code.
+
+---
+
+### U5. P1 #2 fix: progress-based stuck-job sweep
+
+**Goal:** Replace the wall-clock-based sweep with one that uses `last_progress_at` so healthy long jobs (e.g., 50,100-row `evo` file) are not falsely failed.
+
+**Requirements:** R3
+
+**Dependencies:** U1 (for `last_progress_at`), U2 (for the `last_progress_at` write-on-progress), U4 (so the old sweep is gone first)
+
+**Files:**
+- Create: `packages/api/src/services/etl/sweepStuckJobs.ts` (the sweep function — pure DB logic, no HTTP)
+- Modify: `packages/api/src/routes/admin/analytics/catalog.ts` (new `POST /admin/etl/sweep-stuck` endpoint that calls `sweepStuckJobs` and returns the affected rows; for manual triggering)
+- Modify: `packages/api/wrangler.jsonc` (declare a CF Cron Trigger for the sweep, e.g., `*/5 * * * *`)
+- Modify: `packages/api/src/index.ts` (add `scheduled()` handler that invokes `sweepStuckJobs` on the cron event; if a `scheduled` handler doesn't yet exist, add one)
+- Test: `packages/api/test/etl-stuck-job-sweep.test.ts` (new)
+
+**Approach:**
+- Sweep runs inside a single `db.transaction()`:
+  1. `UPDATE etl_jobs SET status='failed', completed_at = now() WHERE status='running' AND COALESCE(last_progress_at, started_at) < now() - interval '15 minutes' RETURNING id, source, filename, started_at, last_progress_at, chunks_total, chunks_completed`. (The `COALESCE` defends against any legacy row that somehow escaped the U1 backfill.)
+  2. For each returned row, `INSERT INTO etl_dlq_events (job_id, error_message, source) VALUES ($1, 'sweep:no_progress', 'sweep')` so the forensic table is the single source of truth for *every* failed transition — whether triggered by the consumer DLQ or by the sweep. `chunk_index = NULL` in sweep-sourced events.
+- Returned rows also feed a Sentry warning event per affected job (`level: warning`, tags `{ jobId, source: 'sweep' }`, extra includes `chunks_completed/chunks_total` so the operator immediately sees how far the job got).
+- 15-minute interval matches the CF Queue consumer wall-clock cap. Any chunk making real progress writes `last_progress_at = now()` (via U2's modification to `updateEtlJobProgress`), so this only catches truly stalled jobs.
+- CF Cron Trigger every 5 minutes (configurable via env if needed). The cron handler is idempotent — the partial index from U1 keeps the query cheap even at thousands of jobs. Wrangler config shape: `"triggers": { "crons": ["*/5 * * * *"] }` — top-level `triggers` object wrapping a `crons` array, not a bare top-level `crons` key.
+- Manual admin endpoint exists for on-demand sweep — useful during incident response.
+
+**Patterns to follow:**
+- Admin route structure at `packages/api/src/routes/admin/analytics/catalog.ts` for the new endpoint.
+- CF Cron Triggers config in `wrangler.jsonc` (the repo has none today — this is the first; reference <https://developers.cloudflare.com/workers/configuration/cron-triggers/>).
+
+**Test scenarios:**
+- Happy path: Insert a job with `status='running'`, `last_progress_at = now() - 30min` → sweep flips it to `failed`.
+- Edge case: Insert a job with `status='running'`, `last_progress_at = now() - 5min` → sweep leaves it alone (within budget).
+- Edge case: Insert a job with `last_progress_at = NULL` (somehow — legacy row that escaped backfill) → COALESCE the column with `started_at` in the WHERE clause so it still gets evaluated.
+- Edge case: 50,100-row job in progress — chunks write `last_progress_at = now()` every 100 rows → sweep never fires on it.
+- Integration: Cron-event simulation calls the same code path as the admin endpoint; both return identical results for the same DB state.
+- Error path: Sweep query fails (DB down) → caller observes the error; Sentry captures; cron does not silently mask.
+
+**Verification:**
+- After running the sweep against a DB with the seeded test cases, exactly the long-stalled rows are affected.
+- `bun test:api` includes the new test and passes.
+- Dev cron schedule fires (`wrangler dev --test-scheduled`) and exercises the handler.
+
+---
+
+### U6. P1 #1 fix: shared chunking helper + retry endpoint + repair-from-scratch endpoint
+
+**Goal:** Both retry and repair use the same producer chunking logic. The repair endpoint creates a brand-new `etl_jobs` row linked to the broken historical one — directly enabling the operational recovery of the 7 wrongly-`failed` jobs from 2026-05-14.
+
+**Requirements:** R5, R8
+
+**Dependencies:** U1 (for `superseded_by_job_id`), U2 (for `chunks_total` write semantics)
+
+**Files:**
+- Create: `packages/api/src/services/etl/chunkCsvForR2.ts` (extracted shared helper: takes `objectKey`, returns an array of `{ chunkIndex, chunksTotal, byteStart, byteEnd }` with newline-aligned boundaries — newline alignment itself ships in U7)
+- Modify: `packages/api/src/routes/catalog/index.ts` (replace inline chunking at `:253-271` with a call to `chunkCsvForR2`)
+- Modify: `packages/api/src/routes/admin/analytics/catalog.ts` (rewrite `POST /admin/etl/:jobId/retry` at `:413-470` to use `chunkCsvForR2`; add new `POST /admin/etl/:jobId/repair-from-scratch`)
+- Modify: `packages/api/src/services/etl/queue.ts` (extend `queueCatalogETL` to accept pre-computed chunks rather than constructing them — or accept either, with the chunk-construction path migrating to the shared helper)
+- Modify: `packages/cli/src/commands/admin/etl.ts` (add `retry <jobId>` subcommand if not present, plus new `repair-from-scratch <jobId>` subcommand)
+- Test: `packages/api/test/etl-retry-repair.test.ts` (new)
+
+**Approach:**
+- `chunkCsvForR2(objectKey, r2, options?)`: signature returns `Promise<ChunkSpec[]>`. Calls `r2.head(objectKey)`, splits into 20 MB windows. Newline-alignment lives in U7 but the shape lands here so U7 is a fill-in.
+- Retry endpoint (`POST /admin/etl/:jobId/retry`): looks up `(source, filename, scraperRevision)` from the existing job, generates a fresh `jobId`, INSERTs a new `etl_jobs` row with `chunks_total = chunkCsvForR2(...).length`, sets `superseded_by_job_id = <original jobId>` on the new row only if the original is `failed`, sends batch.
+- Repair-from-scratch (`POST /admin/etl/:jobId/repair-from-scratch`): same behavior as retry but always sets `superseded_by_job_id` and `superseded_at = now()` on the new row, and always re-reads the full file (even if the original was `completed`). Use case: an operator suspects a `completed` job is undercount; repair recreates from scratch.
+- **R2 ETag verification (failure-closed)**: before creating the new job row, both endpoints call `r2.head(objectKey)` and compare the returned `etag` (and `lastModified`) against the original job's recorded values. If the original job has no `etag` stored (legacy rows), require an explicit `?force=true` query flag. If the `etag` differs (source was overwritten by a later scrape), return 409 Conflict with a clear message naming both etags — never silently re-ingest a different file under the same path. (This implies adding `source_etag text` and `source_last_modified timestamp` to `etl_jobs` — fold into U1's column list if not already, or capture as a follow-up here.)
+- Both endpoints accept an optional `?dryRun=true` query that returns the planned chunk spec without enqueuing anything — operator preview.
+- The 7 historical jobs from 2026-05-14 will be recovered by calling repair-from-scratch on each of them once Phase 1+2 ships. U15 runbook documents the operator procedure including the ETag verification step.
+
+**Patterns to follow:**
+- Admin route structure at `packages/api/src/routes/admin/analytics/catalog.ts:178-235` for response shape.
+- Existing retry endpoint at `:413-470` for the basic flow (just don't replicate the broken single-chunk behavior).
+
+**Test scenarios:**
+- Happy path: Retry a failed job with a 50 MB source file → 3 chunks created via `chunkCsvForR2`, 3 messages sent, new `etl_jobs` row has `chunks_total = 3`, `superseded_by_job_id` matches original.
+- Happy path: Repair-from-scratch a `completed` job with apparent undercount → new job created with `superseded_by_job_id` set; original row untouched.
+- Edge case: Retry a single-chunk legacy job (file size < 20 MB) → 1 chunk, `chunks_total = 1`, behaves identically to the producer endpoint.
+- Edge case: Retry on a job whose `filename` no longer exists in R2 → endpoint returns 404 with a clear message; no new `etl_jobs` row.
+- Edge case: `?dryRun=true` returns the planned chunk spec; no DB writes, no queue sends.
+- Integration: Repair-from-scratch on a 50,100-row file (the `evo` case) produces the expected ~3 chunks, all enqueued, and after the full pipeline completes the new job's `total_processed` matches the file's actual row count.
+- Covers AE: the 7 jobs from 2026-05-14 can each be repaired by calling repair-from-scratch — verified manually post-deploy.
+
+**Verification:**
+- Both endpoints documented in the OpenAPI spec emitted by `@elysiajs/openapi`.
+- CLI subcommands invoke the endpoints with proper auth.
+- `bun test:api` passes the new integration test.
+
+---
+
+### U7. P1 #3 + P1 #4 + P1 #5 fix: row-boundary-aligned chunks + robust header injection
+
+**Goal:** No row is silently dropped, invalidated, or split across chunks. Wide-CSV headers (>4 KB) fail loudly instead of silently misaligning columns.
+
+**Requirements:** R4, R6
+
+**Dependencies:** U6 (for `chunkCsvForR2`)
+
+**Files:**
+- Modify: `packages/api/src/services/etl/chunkCsvForR2.ts` (implement newline alignment — for each 20 MB window, read the next 64 KB tail, find the last `\n`, snap `byteEnd` to the byte before that newline)
+- Modify: `packages/api/src/services/etl/processCatalogEtl.ts` (remove `skipPartialRow` at `:95-108`; rewrite header injection at `:50-58` with a bounded expand loop 4K→16K→64K; throw a typed error if no newline in 64 KB)
+- Test: `packages/api/test/etl-chunk-boundaries.test.ts` (new)
+
+**Approach:**
+- Newline alignment in producer:
+  - For each chunk window `[start, start + 20MB)`:
+    - Read `[start + 20MB - 64KB, start + 20MB)`.
+    - Find the index of the last `\n` in that slice.
+    - If found: `byteEnd = (start + 20MB - 64KB) + lastNewlineIndex`. The next chunk's `byteStart = byteEnd + 1`.
+    - If not found in 64 KB (extremely unlikely with normal CSV row sizes): throw `ChunkBoundaryError` immediately, surfacing to Sentry and aborting the job creation. Caller is told the file has a row larger than 64 KB.
+  - Last chunk: `byteEnd = file.size - 1`.
+- Header re-fetch in consumer (for `chunkIndex > 0`):
+  ```text
+  let headerSlice = await r2.get(key, { range: { offset: 0, length: 4096 }}).then(b => b.text());
+  let nlIdx = headerSlice.indexOf('\n');
+  if (nlIdx === -1) {
+    headerSlice = await r2.get(key, { range: { offset: 0, length: 16384 }}).then(b => b.text());
+    nlIdx = headerSlice.indexOf('\n');
+  }
+  if (nlIdx === -1) {
+    headerSlice = await r2.get(key, { range: { offset: 0, length: 65536 }}).then(b => b.text());
+    nlIdx = headerSlice.indexOf('\n');
+  }
+  if (nlIdx === -1) throw new EtlHeaderError(`No newline in first 64 KB of ${key} — malformed header`);
+  const headerRow = headerSlice.slice(0, nlIdx);
+  ```
+- Since chunks are now newline-aligned, `skipPartialRow` is no longer needed — the consumer can stream the chunk body directly into the parser after prepending the header.
+- BOM handling: if the first byte of the header slice is `0xEF 0xBB 0xBF`, strip it before extracting the header row. Same treatment for the first chunk.
+
+**Patterns to follow:**
+- R2 byte-range read pattern at `packages/api/src/services/etl/processCatalogEtl.ts:54, 71`.
+- Typed-error pattern: extend whatever the repo uses for domain errors (typically `Error` subclasses in `packages/api/src/utils/errors.ts`).
+
+**Test scenarios:**
+- Happy path: 5 MB file, 1 chunk → no boundary logic exercised; row count matches actual.
+- Happy path: 60 MB file, 3 chunks; rows of varying width; all `byteEnd` values land immediately before a `\n`; total row count across chunks = file row count.
+- Edge case: Chunk boundary lands exactly on a newline character (`source[byteEnd] === '\n'`) → still aligned; next chunk starts on next row; no dropped row.
+- Edge case: Header row of 4500 bytes (just over 4 KB) → re-fetch expands to 16 KB, succeeds; columns mapped correctly.
+- Edge case: Header row of 50 KB (one absurdly wide CSV) → re-fetch expands to 64 KB, succeeds.
+- Edge case: BOM at start of file → stripped from header extraction in both chunk-0 and re-fetch paths.
+- Error path: File with no newline in first 64 KB → throws `EtlHeaderError`; job marked `failed` via DLQ (U3).
+- Error path: Row larger than 64 KB encountered at a chunk boundary → producer throws `ChunkBoundaryError`; no job created.
+- Integration: A real CSV from prod (anonymized fixture in `packages/api/test/fixtures/`) splits into multiple chunks; sum of consumer-reported `totalProcessed` across all chunks equals `wc -l fixture.csv - 1` (subtract header).
+- Covers AE: A 50,100-row file (the `evo` shape) ingested via the new chunking logic shows `total_processed = 50100`, `total_valid + total_invalid = 50100`, no missing rows.
+
+**Verification:**
+- Manual run on a real prod fixture file with `wc -l` cross-check matches the job's `total_processed`.
+- `bun test:api` passes the new fixture-driven test.
+- Sentry catches the malformed-header case during the next dev exercise.
+
+---
+
+### U8. Sentry wiring via `@sentry/cloudflare`
+
+**Goal:** Every uncaught exception in the API Worker — including queue-consumer paths — emits a Sentry event with structured tags. Operators can debug a stuck job without paging through raw Worker logs.
+
+**Requirements:** R9
+
+**Dependencies:** None (independent; can start in parallel with Phase 1 but lands in Phase 3)
+
+**Files:**
+- Modify: `packages/api/package.json` (add `@sentry/cloudflare` dependency; pin to a specific version)
+- Modify: `packages/api/src/index.ts` (wrap the Worker default export with `Sentry.withSentry({...}, { fetch, queue })`; pass the Sentry options factory that reads `env.SENTRY_DSN`)
+- Modify: `packages/api/src/utils/env-validation.ts` (no schema change — `SENTRY_DSN` is already declared at `:9, 94`; verify it's required vs optional and adjust accordingly so dev doesn't break without a DSN)
+- Modify: `packages/api/wrangler.jsonc` (add `upload_source_maps: true` at the top level)
+- Modify: `packages/api/src/services/etl/queue.ts` (fill in the `Sentry.captureException(...)` call site that U3 stubbed)
+- Modify: `packages/api/src/services/etl/processCatalogEtl.ts` (Sentry breadcrumbs at chunk-start, batch-flush, and chunk-end; `Sentry.startSpan` around the chunk lifecycle)
+- Create: `packages/api/src/utils/logger.ts` (the thin structured logger — accepts `LogContext`, emits JSON-prefixed `console.log` lines, also calls `Sentry.addBreadcrumb` when Sentry is initialized)
+- Modify: All `packages/api/src/services/etl/*.ts` console calls migrated to `logger.{info,warn,error}` (mechanical change — sweeps across the ETL files)
+- Test: `packages/api/test/sentry-instrumentation.test.ts` (new — mocks `@sentry/cloudflare` and asserts captureException/breadcrumb call shape)
+
+**Approach:**
+- `withSentry({ fetch, queue })` wraps the existing default export at `packages/api/src/index.ts`. The Sentry options factory reads `env.SENTRY_DSN`, `env.ENVIRONMENT`, sets `tracesSampleRate: 0.1`.
+- Queue consumer instrumentation per <https://docs.sentry.io/platforms/javascript/guides/cloudflare/tracing/instrumentation/queues-module/>:
+  - `Sentry.startSpan({ op: 'queue.process', name: 'etl-chunk', attributes: { 'messaging.message.id': msg.id, 'messaging.message.retry.count': msg.attempts, 'jobId': msg.body.id, 'chunkIndex': msg.body.data.chunkIndex } }, async () => { ... })`.
+  - `Sentry.captureException(err, { tags: { jobId, chunkIndex, r2Key }, contexts: { queue: { messageId, attempts } } })` inside the catch.
+- DLQ consumer (from U3) gets the same treatment.
+- `logger.ts`: ~30 lines. Functions: `info(event, ctx)`, `warn(event, ctx)`, `error(event, ctx, err?)`. Emits a JSON line; if Sentry is initialized, also calls `Sentry.addBreadcrumb({ category: event, data: ctx, level })`.
+- Source maps: `upload_source_maps: true` works with Wrangler 4.x and `compatibility_date: 2025-06-01`.
+
+**Patterns to follow:**
+- No existing Sentry initialization in `packages/api` — this is the first.
+- Reference Sentry-in-CF guidance: <https://docs.sentry.io/platforms/javascript/guides/cloudflare/>.
+
+**Test scenarios:**
+- Happy path: Successful chunk → one `startSpan` invocation, breadcrumbs at chunk-start/flush/end, no `captureException`.
+- Error path: Chunk throws → `captureException` called once with expected tags; span marks status `internal_error`.
+- Edge case: `SENTRY_DSN` empty (dev without secret) → no Sentry calls fire; logger still emits lines; no crash.
+- Edge case: Logger called before Sentry initialized (cold-start race) → graceful no-op on breadcrumb path; logger.info still emits the line.
+- Integration: A real Sentry test project receives events from `bun api` dev-server when forced failures are triggered.
+
+**Verification:**
+- Dev `bun api` cold start logs the Sentry init line.
+- A forced chunk failure produces a Sentry event visible in the project.
+- All `packages/api/src/services/etl/*.ts` files have zero `console.*` references (`grep -rn 'console\.' packages/api/src/services/etl/` returns nothing).
+
+---
+
+### U9. P2 #2 + P2 #3 + P2 #4 fix: error propagation + embedding-failure observability + IIFE error handling
+
+**Goal:** Three related but smaller correctness issues that all share the theme "errors should not vanish silently."
+
+**Requirements:** R2, R10
+
+**Dependencies:** U1 (for `total_embedding_failures`), U8 (so the new error sites can `Sentry.captureException`)
+
+**Files:**
+- Modify: `packages/api/src/services/etl/processLogsBatch.ts` (rethrow on DB failure at `:25-27`; remove the swallow)
+- Modify: `packages/api/src/services/etl/processValidItemsBatch.ts` (in the embedding-fallback path at `:52-63`, atomically increment `etl_jobs.total_embedding_failures` before upserting; surface a Sentry warning event with `jobId` and the affected SKU count; do not throw)
+- Modify: `packages/api/src/services/etl/processCatalogEtl.ts` (wrap the writer IIFE at `:89-117` in an explicit promise: `const writerPromise = (async () => { ... })().catch(err => parser.destroy(err)); ...; await writerPromise.catch(err => { throw err })` so unhandled rejections become outer-flow throws)
+- Modify: `packages/api/src/routes/admin/analytics/catalog.ts` (extend the admin job-list response to include `totalEmbeddingFailures` so dashboards can surface degradation)
+- Test: `packages/api/test/etl-error-propagation.test.ts` (new)
+
+**Approach:**
+- `processLogsBatch`: catch block currently logs and returns. Replace with `throw err`. The outer `processCatalogETL` catch already exists and the chunk will retry/DLQ correctly via U3.
+- Embedding fallback: at `processValidItemsBatch.ts:52-63`, on `generateManyEmbeddings` throw:
+  ```text
+  await db.update(etlJobs).set({ totalEmbeddingFailures: sql`COALESCE(${etlJobs.totalEmbeddingFailures}, 0) + ${items.length}` }).where(eq(etlJobs.id, jobId));
+  logger.warn('etl.embedding.fallback', { jobId, skuCount: items.length });
+  Sentry.captureMessage('etl.embedding.fallback', { level: 'warning', tags: { jobId }, extra: { skuCount: items.length } });
+  // continue with upsert; embedding stays NULL
+  ```
+- IIFE wrap pattern:
+  ```text
+  const writerPromise = (async () => { ... })()
+    .catch(err => { parser.destroy(err); throw err; });
+  // ... for await loop ...
+  await writerPromise;
+  ```
+  Any rejection in the writer now propagates to the outer try/catch in `processCatalogETL` and triggers retry/DLQ via U3.
+- Admin response extension: extend the existing `GET /admin/analytics/catalog/etl` route's select shape to include `totalEmbeddingFailures` and update the response Zod schema if one is declared.
+
+**Patterns to follow:**
+- Atomic update idiom at `packages/api/src/services/etl/updateEtlJobProgress.ts:16-23`.
+- Admin route response shape at `packages/api/src/routes/admin/analytics/catalog.ts:178-235`.
+
+**Test scenarios:**
+- Happy path (embedding fallback): Embedding service throws → SKUs upserted with `embedding=NULL`; `total_embedding_failures` increments by exactly `items.length`; Sentry warning event fires once per batch (not per SKU).
+- Happy path (logs rethrow): `processLogsBatch` DB INSERT fails → exception propagates to outer catch → chunk retried by CF Queue.
+- Happy path (IIFE wrap): Writer throws inside the async IIFE → parser destroyed; outer `for await` loop terminates; outer catch fires; chunk retried.
+- Edge case: Multiple consecutive embedding batches in one chunk all fall back → counter increments cumulatively; Sentry warnings fire once per batch, not once per chunk.
+- Edge case: Mixed batch — some SKUs embed, then fallback kicks in for the rest → counter increments only for the failed batch's SKU count.
+- Integration: Admin endpoint response includes `totalEmbeddingFailures` field for every job; the prod-shape dashboard query still parses cleanly.
+
+**Verification:**
+- New test passes with the rethrow / wrap / counter increments in place.
+- `bun test:api` overall green.
+- Dev admin endpoint `GET /admin/analytics/catalog/etl?limit=5` returns the new field.
+
+---
+
+### U10. Reconciliation: admin endpoint + automatic post-job verification (via dedicated queue) + CLI subcommand
+
+**Goal:** Every ETL completion writes a verification row count; operators can also trigger reconciliation on any job on demand. Surfaces the user's "missing or falsely labeling" concern as a first-class observable signal. Auto-reconciliation runs on its own queue, not via `ctx.waitUntil`, so multi-GB files do not exceed the queue invocation's 15-min wall-clock.
+
+**Requirements:** R7
+
+**Dependencies:** U1 (for `verified_at`, `verified_row_count`, `verified_row_count_partial`), U2 (for the completion transition that enqueues the reconcile message), U8 (for Sentry warnings on delta)
+
+**Files:**
+- Create: `packages/api/src/services/etl/reconcileJob.ts` (pure function: given a `jobId` and optional `resumeFromByte`, stream the R2 source in 100 MB byte-range windows, count newlines, checkpoint progress, finalize verification on EOF, return delta)
+- Create: `packages/api/src/services/etl/processReconcileBatch.ts` (queue consumer for `packrat-etl-reconcile-queue`; calls `reconcileJob`; handles retry/resume)
+- Modify: `packages/api/src/services/etl/queue.ts` (extend producer to enqueue reconcile messages; type `ReconcileMessage { jobId: string; resumeFromByte?: number }`)
+- Modify: `packages/api/src/services/etl/processCatalogEtl.ts` (on the final-chunk completion transition from U2, enqueue a `ReconcileMessage` to `packrat-etl-reconcile-queue` *inside the same transaction* as the status flip so a row can never transition to `completed` without an enqueued reconcile)
+- Modify: `packages/api/src/index.ts` (extend the `queue()` switch with an arm for `packrat-etl-reconcile-queue` and `packrat-etl-reconcile-queue-dev`)
+- Modify: `packages/api/wrangler.jsonc` (declare `packrat-etl-reconcile-queue` and `packrat-etl-reconcile-queue-dev` as producer + consumer with its own `dead_letter_queue: 'packrat-etl-dlq'` and `max_retries: 3`)
+- Modify: `packages/api/src/routes/admin/analytics/catalog.ts` (add `POST /admin/etl/:jobId/reconcile` — calls `reconcileJob` synchronously; for small/medium files returns inline; for large files returns 202 Accepted and enqueues to the reconcile queue with the existing job id)
+- Modify: `packages/cli/src/commands/admin/etl.ts` (add `reconcile <jobId>` subcommand)
+- Modify: admin list endpoint response shape (include `verifiedAt`, `verifiedRowCount`, and `verifiedRowCountPartial` so the dashboard surfaces it)
+- Test: `packages/api/test/etl-reconciliation.test.ts` (new)
+
+**Approach:**
+- `reconcileJob(jobId, resumeFromByte = 0)`:
+  1. Read `(filename, total_processed, verified_at, verified_row_count_partial)` from `etl_jobs`. If `verified_at IS NOT NULL`, return early — idempotent no-op for redelivered messages.
+  2. `r2.head(key)` → `fileSize`.
+  3. From `resumeFromByte` (or `verified_row_count_partial`'s checkpoint byte position if set), read 100 MB byte-range windows. For each window:
+     - Count `\n` bytes in the window.
+     - Add to running `lineCount`.
+     - On the last window, subtract 1 for the header row.
+     - Every 5 windows (500 MB processed) or when elapsed time > 10 min: `UPDATE etl_jobs SET verified_row_count_partial = $lineCount` (checkpoint), then throw a typed `ReconcileResumeError` carrying the current byte offset so the queue retry re-enqueues with `resumeFromByte` advanced. Wall-clock budget reset.
+  4. On EOF: `UPDATE etl_jobs SET verified_at = now(), verified_row_count = $lineCount, verified_row_count_partial = NULL WHERE id = $1 AND verified_at IS NULL` (idempotency gate).
+  5. Compute `delta = lineCount - total_processed`. If `abs(delta) > max(10, ceil(0.01 * lineCount))`: `Sentry.captureMessage('etl.reconciliation.delta', { level: 'warning', tags: { jobId }, extra: { delta, expected: lineCount, actual: total_processed } })`.
+  6. Return `{ jobId, expectedRowCount: lineCount, actualRowCount: total_processed, delta, withinThreshold }`.
+- `processReconcileBatch` (queue consumer):
+  - For each message: try `reconcileJob(msg.jobId, msg.resumeFromByte)` → on success `ack()`. On `ReconcileResumeError`: enqueue a new message with the advanced offset and `ack()` the current one. On any other error: `retry({ delaySeconds: 60 })`.
+- Auto-trigger: in U2's completion transaction, after the status flip to `completed`, enqueue `{ jobId, resumeFromByte: 0 }` to `packrat-etl-reconcile-queue`. Because both writes are in the same transaction, a row can never be `completed` without an enqueued reconcile.
+- Manual endpoint (`POST /admin/etl/:jobId/reconcile`):
+  - For files where `fileSize < 200 MB`: call `reconcileJob` synchronously and return the result inline.
+  - For files ≥ 200 MB: enqueue to `packrat-etl-reconcile-queue` and return 202 with a "poll the job for `verified_at`" message.
+  - Optional `?force=true` query: clear `verified_at` first and re-enqueue (operator override for a re-verify).
+- CLI subcommand: `packrat-admin etl reconcile <jobId>` → wraps the endpoint, polls until `verifiedAt` is set or timeout.
+- The 7 historical jobs from 2026-05-14 can each be reconciled retroactively via this endpoint *before* deciding to repair (U6). Confirms the suspicion that they processed partial data before being swept.
+
+**Patterns to follow:**
+- Queue consumer pattern from U3 (per-message ack/retry, DLQ wired).
+- Streaming-count pattern: `for await (const chunk of body)` and accumulate `chunk.filter(byte => byte === 0x0A).length`.
+
+**Test scenarios:**
+- Happy path: Job with `total_processed = 100`, R2 file has 101 lines (100 rows + header) → delta = 0; `verified_at` set; no Sentry warning.
+- Happy path: Job with `total_processed = 1000`, R2 file has 1006 lines (1005 rows + header) → delta = 5; within threshold; no warning.
+- Edge case: Job with `total_processed = 50000`, R2 file has 50100 lines + header → delta = 100; threshold = `max(10, 500)` = 500; within threshold; no warning. (The 50,100 case stays informational.)
+- Edge case (the real case): Job with `total_processed = 400`, R2 file has 50101 lines (50100 rows + header) — what the `campmor`-shape failures looked like → delta = 49700; way over threshold; Sentry warning fires.
+- Edge case (resume): A 1.5 GB file forces three resume-error checkpoints; each resume picks up at the right byte offset; final `verified_row_count` matches the true row count.
+- Edge case (idempotency): A redelivered reconcile message with `resumeFromByte = 0` against a job that already has `verified_at` set — `reconcileJob` returns early without re-reading the file.
+- Error path: R2 object missing → `reconcileJob` throws a typed error; queue consumer retries with backoff; after exhausting `max_retries: 3`, the DLQ captures it.
+- Edge case: Job with `total_processed = NULL` (legacy stuck-job-sweep casualty) → reconcileJob computes delta as `expected - 0 = expected`; the warning carries useful context for diagnosing the historical job.
+- Integration: Auto-verify fires exactly once per job, enqueued atomically with the completion transition; it does not fire for intermediate chunk completions; it does not fire twice on a redelivered final chunk (idempotency comes from the `etl_job_chunks` gate in U2).
+
+**Verification:**
+- New test passes.
+- Calling the endpoint on a real dev-seeded job returns the documented shape (inline for small files, 202 + queued for large).
+- The chunk-completion transaction either commits both the status flip and the reconcile enqueue, or neither (verify with a forced enqueue failure mid-transaction).
+
+---
+
+### U11. Quality-of-life: scheduler.wait, BATCH_SIZE rename, mergeBySku log aggregation
+
+**Goal:** Three tiny correctness/cleanliness wins that share a maintenance flavor and ship together.
+
+**Requirements:** R9 (log volume), and audit P2 #5, P2 #6, P3 #1
+
+**Dependencies:** U8 (for the logger surface used by the aggregated merge summary)
+
+**Files:**
+- Modify: `packages/api/src/services/etl/processCatalogEtl.ts:120` (replace `setTimeout(resolve, 1)` with `await scheduler.wait(0)`)
+- Create: `packages/api/src/services/etl/constants.ts` (new — exports `ITEM_FLUSH_BATCH_SIZE = 100` and `CF_QUEUE_BATCH_SIZE = 100`)
+- Modify: `packages/api/src/services/etl/processCatalogEtl.ts:13` and `packages/api/src/services/etl/queue.ts:17` (import from the new constants module instead of declaring inline)
+- Modify: `packages/api/src/services/etl/mergeItemsBySku.ts:34-48` (replace per-SKU `console.log` with a per-batch summary `logger.info('etl.merge.summary', { jobId, mergedSkuCount, totalChangedFields })`)
+- Test: `packages/api/test/etl-yield-and-constants.test.ts` (new — minimal; mostly behavior-preservation)
+
+**Approach:**
+- `await scheduler.wait(0)` is the documented Workers Scheduler API. `scheduler.yield()` does not exist (corrected from audit P2 #5).
+- The constants module is dead-simple — two exports — but the rename surfaces intent at the call site and ends the ambiguity the audit flagged at P2 #6.
+- The mergeBySku aggregation accumulates change counts across one batch (already a natural unit) and logs once at the end. No per-SKU lines.
+
+**Patterns to follow:**
+- Module organization mirrors `packages/api/src/services/etl/types.ts` for a constants file.
+
+**Test scenarios:**
+- Behavior preservation: A 10,000-row chunk completes at least as fast as before with `scheduler.wait(0)` (regression check, not a strict assertion).
+- Happy path (merge log): A batch with 50 SKU merges → exactly one log line emitted, summarizing the batch.
+- Edge case: A batch with 0 merges → no log line.
+
+**Verification:**
+- `grep -rn "setTimeout\(.*1.*\)" packages/api/src/services/etl/` returns nothing.
+- `grep -rn "BATCH_SIZE\s*=" packages/api/src/services/etl/` returns only the new constants.
+- A real ETL run on dev with 1k duplicate SKUs produces 1 merge summary line, not 1000.
+
+---
+
+### U12. Validator hardening: URL scheme + length caps + SKU charset
+
+**Goal:** Eliminate the audit P3 #2 attack surface — `javascript:` URLs and oversize fields cannot enter the catalog.
+
+**Requirements:** R11
+
+**Dependencies:** None (independent; can land any time after Phase 1)
+
+**Files:**
+- Modify: `packages/api/src/services/etl/CatalogItemValidator.ts` (rewrite `isValidUrl` at `:60-67`; add length caps and SKU regex)
+- Test: `packages/api/test/etl-validator.test.ts` (new or extend existing)
+
+**Approach:**
+- `isValidUrl`: parse with `new URL()`; reject any scheme other than `http:` and `https:`. Reject URLs longer than 2048 chars.
+- Length caps (rejects, not truncates): `name ≤ 500`, `description ≤ 50000`, `brand ≤ 200`, `category ≤ 200`.
+- SKU regex: `/^[A-Za-z0-9_.\-\/]+$/`; max length 200.
+- Each rejection produces a structured invalid-item log entry with the specific reason — surfaces in the existing `/admin/etl/:jobId/failures` endpoint.
+
+**Patterns to follow:**
+- Existing validator structure at `packages/api/src/services/etl/CatalogItemValidator.ts`.
+- Invalid-log shape at `packages/api/src/services/etl/processLogsBatch.ts`.
+
+**Test scenarios:**
+- Happy path: Valid `https://example.com/product/123` URL accepted.
+- Error path: `javascript:alert(1)` URL rejected with reason `INVALID_URL_SCHEME`.
+- Error path: `mailto:foo@bar` rejected with `INVALID_URL_SCHEME`.
+- Error path: URL of 3000 chars rejected with `URL_TOO_LONG`.
+- Edge case: Name of exactly 500 chars accepted; 501 chars rejected.
+- Edge case: SKU `ABC-123_/test.sku` accepted; SKU `<script>` rejected with `INVALID_SKU_CHARS`.
+- Integration: Run the existing `etl.test.ts` fixture with a row containing a `javascript:` URL → row routed to invalid logs, no DB insert into `catalog_items`.
+
+**Verification:**
+- New test passes.
+- A real prod-shape CSV with an injected `javascript:` URL run through `bun test:api` shows the row rejected.
+
+---
+
+### U13. Retention policy: `invalid_item_logs` cron sweep
+
+**Goal:** Bounded growth of the `invalid_item_logs` table. Bad uploads cannot fill Neon storage indefinitely.
+
+**Requirements:** R12
+
+**Dependencies:** U5 (for the existing `scheduled()` handler; the retention sweep adds a second cron arm)
+
+**Files:**
+- Create: `packages/api/src/services/etl/invalidLogRetention.ts` (the sweep function)
+- Modify: `packages/api/src/index.ts` (extend the `scheduled()` handler to dispatch on cron name; add the retention sweep arm)
+- Modify: `packages/api/wrangler.jsonc` (add a daily cron trigger, e.g., `0 9 * * *` UTC)
+- Test: `packages/api/test/etl-log-retention.test.ts` (new)
+
+**Approach:**
+- Sweep: `DELETE FROM invalid_item_logs WHERE created_at < now() - interval '90 days'`. Returns the deleted count; emits a Sentry breadcrumb.
+- Cron config in `wrangler.jsonc`: `"triggers": { "crons": ["*/5 * * * *", "0 9 * * *"] }` (sweep + retention). The top-level `triggers` wrapper is required by the Wrangler schema — a bare top-level `crons` key is silently ignored. The `scheduled` handler in `packages/api/src/index.ts` dispatches on the `event.cron` string.
+- 90-day window is a default; configurable via `env.INVALID_LOG_RETENTION_DAYS` if needed.
+
+**Patterns to follow:**
+- The stuck-job sweep cron from U5 establishes the `scheduled()` handler pattern.
+
+**Test scenarios:**
+- Happy path: Insert logs at `now() - 100d` and `now() - 30d`; sweep deletes only the 100d one.
+- Edge case: Empty table → sweep deletes 0 rows; no error.
+- Edge case: `INVALID_LOG_RETENTION_DAYS=30` env override → 30d-old logs swept.
+
+**Verification:**
+- New test passes.
+- `wrangler dev --test-scheduled` exercises both cron arms.
+
+---
+
+### U14. Test gap backfill: cross-cutting tests the global mock currently hides
+
+**Goal:** Add the specific tests that the per-unit tests above couldn't cover because of `packages/api/test/setup.ts:544-551`'s global queue mock — plus a few cross-cutting integration scenarios.
+
+**Requirements:** R14
+
+**Dependencies:** U2, U3, U6, U7 (all of which introduce behavior that should be covered end-to-end)
+
+**Files:**
+- Create: `packages/api/test/etl-queue-direct.test.ts` (per-file unmock of `queueCatalogETL` and `processQueueBatch`; exercise the real consumer)
+- Create: `packages/api/test/etl-multi-chunk-integration.test.ts` (full producer→queue→consumer→DB flow for a 3-chunk job)
+- Create: `packages/api/test/etl-csv-edge-cases.test.ts` (BOM at start, quoted header with embedded commas, header with 30+ columns straddling the 4KB initial slice, row-spanning-chunk fixture)
+- Modify: `packages/api/test/setup.ts` (if needed, document the `vi.doUnmock` escape hatch in a comment so future tests don't fight the global mock blindly)
+
+**Approach:**
+- Each new test file declares `vi.doUnmock('@packrat/api/services/etl/queue')` in `beforeAll` so the real implementation is exercised.
+- Fixtures live in `packages/api/test/fixtures/etl/`:
+  - `small-1chunk.csv` — 100 rows, ~10 KB
+  - `medium-3chunk.csv` — ~50 MB synthetic, designed to split into 3 byte-range chunks with row-boundary alignment work
+  - `wide-header.csv` — header row of 6 KB (forces the 4K→16K expansion path)
+  - `bom-prefixed.csv` — starts with `0xEF 0xBB 0xBF`
+  - `quoted-header.csv` — header has `"Item,Name","Description"` quoting
+- Tests assert behaviors that map directly to audit findings:
+  - Multi-chunk completion (P0 #1): full producer→consumer for a 3-chunk file ends with one `completed` transition.
+  - Queue retry (P0 #2): forced R2 5xx on first attempt → retry → success on second.
+  - Header > 4KB (P1 #3): consumer succeeds; columns mapped correctly.
+  - Row-spanning (P1 #4 / P1 #5): no rows dropped, no rows duplicated, no rows invalidated.
+  - BOM and quoted headers: parsed correctly.
+- Concurrent updates (audit also flagged this): a test that fires two simultaneous `updateEtlJobProgress` calls for the same `jobId` from different mocked workers; asserts atomic counter increment via the existing `COALESCE` idiom.
+
+**Patterns to follow:**
+- Existing `packages/api/test/etl.test.ts` for mocking + Postgres setup.
+- Per-test mock control via `vi.mocked(...).mockImplementationOnce(...)`.
+
+**Test scenarios:**
+- (Each described above as a fixture-driven scenario.)
+
+**Verification:**
+- `bun test:api` passes.
+- `grep -rn "vi.doUnmock" packages/api/test/etl-*.test.ts` shows the un-mock is applied where needed.
+- Coverage delta is positive on `packages/api/src/services/etl/queue.ts` and `packages/api/src/services/etl/processCatalogEtl.ts`.
+
+---
+
+### U15. Runbook at `docs/runbooks/etl-pipeline.md`
+
+**Goal:** A new on-caller can trigger / inspect / retry / drain / reconcile / recover without reading source.
+
+**Requirements:** R13
+
+**Dependencies:** U3, U5, U6, U10 (all of which create the operator-facing endpoints the runbook documents)
+
+**Files:**
+- Create: `docs/runbooks/etl-pipeline.md`
+
+**Approach:**
+- Sections in the runbook:
+  1. **Architecture** — one diagram showing producer → queue → consumer → DLQ, plus the cron jobs (sweep + retention).
+  2. **How to trigger an ETL** — `curl POST /catalog/etl` with payload schema; CLI command equivalent.
+  3. **How to inspect queue depth** — `wrangler queues list` and `wrangler queues info packrat-etl-queue`; same for `packrat-etl-dlq`.
+  4. **How to retry a failed job** — `curl POST /admin/etl/:jobId/retry`; CLI `packrat-admin etl retry <jobId>`.
+  5. **How to repair a corrupted job** (the 7-job case) — `POST /admin/etl/:jobId/repair-from-scratch`; CLI `packrat-admin etl repair-from-scratch <jobId>`. Includes the explicit one-time procedure for the seven 2026-05-14 jobs (list the jobIds).
+  6. **How to reconcile** — manual endpoint + automatic behavior; how to interpret the delta.
+  7. **How to drain the queue** — `wrangler queues consumer remove`.
+  8. **How to interpret `success_rate` and `verified_row_count`** — what 100%-failed means, what missing-but-present-in-source means.
+  9. **DLQ forensics** — querying `etl_dlq_events`; replay procedure (re-enqueue via `repair-from-scratch`).
+  10. **Accepted limitations** — soft-delete / discontinued-item reconciliation is not in scope; catalog grows monotonically; document the trade-off.
+  11. **References** — link to the audit, this plan, the Cloudflare Queues docs, the Sentry project.
+
+**Patterns to follow:**
+- No existing runbook in `docs/runbooks/` (verified absent). This is the first; establishes the convention.
+
+**Test scenarios:**
+- *Test expectation: none — documentation only, no behavioral change.*
+
+**Verification:**
+- The runbook is comprehensive enough that a new on-caller can complete each documented procedure without reading source.
+- Reviewer walks through every command in dev and confirms expected output.
+
+---
+
+## System-Wide Impact
+
+- **Interaction graph:** Producer endpoint → `chunkCsvForR2` (U6/U7) → ETL queue → consumer (idempotency gate via `etl_job_chunks` then atomic completion UPDATE → enqueue reconcile message inside the same transaction) → DLQ on exhaust → DLQ consumer → `etl_dlq_events`. Reconcile queue (`packrat-etl-reconcile-queue`) → reconcile consumer (resumable byte-range streaming, checkpointed via `verified_row_count_partial`). Two new cron jobs (sweep + retention). Sweep also inserts sentinel `etl_dlq_events` so the forensic table is single-source-of-truth for every `failed` transition. Sentry now intercepts every entry point via `withSentry({ fetch, queue })`.
+- **Error propagation:** Chunk-level exceptions now propagate from inner code → `processCatalogETL` outer catch → `processQueueBatch` per-message catch → `message.retry()` → exhaustion → DLQ → `etl_dlq_events` + Sentry. The `etl_jobs.status='failed'` transition happens only at the DLQ consumer or via the progress-based sweep. Nothing else writes `failed`.
+- **State lifecycle risks:** The chunk-completion path is correct under at-least-once delivery because every increment is gated by `INSERT INTO etl_job_chunks … ON CONFLICT DO NOTHING RETURNING 1` — a redelivered chunk produces no row and skips the increment. The combined transaction (chunk-table INSERT + counter UPDATE + reconcile-message enqueue) ensures atomicity: a row can never transition to `completed` without an enqueued reconcile, and a chunk increment can never be applied without the corresponding chunk-table row. The CHECK constraint `chunks_completed <= chunks_total` is the loud-failure safety net if any code path ever bypasses the gate. Status flip-flop (sweep flips to `failed` while a chunk completes) is prevented by the `WHERE status = 'running'` clause on every status-mutating UPDATE. The U10 reconcile checkpoint via `verified_row_count_partial` enables resumable verification of files that exceed a single queue invocation.
+- **API surface parity:** Three new admin endpoints (`/admin/etl/sweep-stuck`, `/admin/etl/:jobId/repair-from-scratch`, `/admin/etl/:jobId/reconcile`), one removed (`/admin/etl/reset-stuck`), one rewritten (`/admin/etl/:jobId/retry`). All three new endpoints get CLI subcommands in `packages/cli/src/commands/admin/etl.ts`. The producer endpoint at `POST /catalog/etl` is unchanged in shape (only the chunking internals change).
+- **Integration coverage:** U14's `etl-multi-chunk-integration.test.ts` exercises the full pipeline end-to-end against the test Postgres. The global queue mock in `setup.ts:544-551` is explicitly un-mocked per-test where the real consumer matters.
+- **Unchanged invariants:** The producer `POST /catalog/etl` request body shape; the `catalog_items` upsert behavior (still SKU-keyed); the OpenAPI client generated by `@elysiajs/openapi` for non-ETL routes; the admin auth surface (`adminAuthGuard` continues to gate every new admin route); the scraper-revision pinning. No mobile or web app code is touched.
+
+---
+
+## Risks & Dependencies
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| **At-least-once chunk redelivery double-increments `chunks_completed`** before the per-chunk idempotency table exists | High (without mitigation) | High | U1 adds `etl_job_chunks(job_id, chunk_index)` PK table; U2 gates the increment on `INSERT … ON CONFLICT DO NOTHING RETURNING 1`. CHECK constraint `chunks_completed <= chunks_total` is the loud safety net |
+| **Chunk-completion UPDATE clobbers a row the sweep already failed** (status flip-flop) | Med | High | All status-mutating UPDATEs gate on `WHERE status = 'running'`. The chunk consumer also runs the completion UPDATE inside a transaction with the idempotency INSERT |
+| **U10 auto-reconcile via `ctx.waitUntil` exceeds 15-min wall-clock for multi-GB files** | High at >1 GB | High | Reconcile runs on its own `packrat-etl-reconcile-queue` with byte-range streaming + checkpointed resume via `verified_row_count_partial`. `waitUntil` is no longer used |
+| **DLQ event INSERT succeeds, status UPDATE fails — two-phase ordering bug** | Low | Med | Both writes inside one `db.transaction()` in U3. Post-deploy verification query in the runbook (`SELECT job_id FROM etl_dlq_events WHERE job_id IN (SELECT id FROM etl_jobs WHERE status != 'failed')`) alerts on inconsistency |
+| **`catalog_item_etl_jobs` accumulates duplicate provenance rows on chunk redelivery** | Med | Low | U1 adds `UNIQUE (catalog_item_id, etl_job_id)`; upserts use `ON CONFLICT DO NOTHING` |
+| **`error_stack` in `etl_dlq_events` accidentally captures CSV row data** (PII risk if scrapers ever ingest user-generated text) | Low today | Med | Documented contract at the call site: error messages MUST NOT include raw row data. U14 test asserts this property |
+| **Migration 0048 backfill blocks in-flight ETL writers during deploy** | Low (~200 rows) | Low | Single-migration approach is fine at current scale; UPDATE is sub-100ms on Neon. Comment in migration: "revisit if row count >100k" |
+| **`repair-from-scratch` re-ingests a different file than the original** because R2 source was overwritten | Low | High | U6 endpoint compares stored `source_etag` against fresh `r2.head(key).etag`; returns 409 on mismatch unless `?force=true` |
+| Drizzle Kit emits SQL without literal `DEFAULT 0 NOT NULL` (only JS-side default) breaking inserts from old workers mid-rolling-deploy | Med | High | U1 implementer hand-inspects the generated `.sql` before applying; assert via `information_schema.columns` in the schema smoke test |
+| `@sentry/cloudflare` adds bundle size that pushes the API Worker over a CF size limit | Low | Med | Sentry SDK is ~30 KB gzipped per their docs; current Worker bundle is well under the 10 MB limit; verify with `wrangler deploy --dry-run` after U8 |
+| The 7 historical jobs from 2026-05-14 cannot be repaired because their R2 source has been deleted by a separate retention policy | Low | Low | Verify R2 source presence as part of the U15 runbook procedure before invoking `repair-from-scratch`; if missing, document as accepted loss |
+| `@sentry/cloudflare` + `nodejs_compat` interaction introduces a cold-start regression | Low | Med | Measure cold-start delta against a control deploy; if regression > 50 ms, evaluate toucan-js fallback |
+| DLQ consumer fails (e.g., DB down when DLQ event arrives) | Low | Med | DLQ consumer is itself a queue consumer with `max_retries: 3` and its own DLQ semantics. Sentry capture happens before the DB write, so the event is preserved even if persistence fails. The U5 sweep is the bottom-floor safety net for any row that DLQ couldn't transition |
+| Down-migration loses Phase-2+ data after this plan ships | Cert if attempted | High | Migration is **forward-only after U2 ships** (documented in U1's test scenarios and in the migration header comment). Rollback strategy is a forward-fix migration, not a structural revert |
+| Wide-CSV fixture in U14 introduces a long-running test that destabilizes CI | Low | Low | Synthesize the fixture once at test-run startup with a deterministic seed instead of checking in a 50 MB file; cap fixture size at 5 MB in test mode via env |
+
+---
+
+## Documentation / Operational Notes
+
+- The new runbook at `docs/runbooks/etl-pipeline.md` (U15) is the operator entry point; link from the README and the CLAUDE.md ETL section in a follow-up doc PR.
+- Sentry project must be provisioned (or confirmed existing) before U8 lands. `env.SENTRY_DSN` is already validated in `packages/api/src/utils/env-validation.ts:9, 94` — verify the prod and dev env have it set via `wrangler secret list`.
+- Rollout sequencing across phases is incremental: each phase's PR is independently deployable. After Phase 1 ships, observe one week of prod data to confirm no regression before merging Phase 2. After Phase 2 ships, exercise `repair-from-scratch` against the 7 historical jobs as the explicit operational validation.
+- Source maps require `upload_source_maps: true` in `wrangler.jsonc` (U8). Pair with Sentry's CLI in CI for full symbolication; otherwise stack traces in Sentry will show minified line numbers.
+- The CF Cron Trigger added in U5 is the first in this Worker. Verify it appears in `wrangler triggers` after deploy and fires on schedule (`wrangler tail --format=pretty` during the 5-minute window).
+- The 7 historical-job recovery procedure (U15 §5) is a one-time operational task; record the run in the runbook's `## Historical Recoveries` appendix.
+
+---
+
+## Phased Delivery
+
+### Phase 1 — Foundation + P0 Blockers (U1, U2, U3, U4)
+
+Lands the schema migration plus the two production blockers and removes the broken wall-clock sweep. After this phase, multi-chunk jobs cannot prematurely complete, queue failures no longer silently swallow, and the wrongly-triggering sweep is gone. Independently deployable; no operational dependency on later phases. Ship as 1–2 PRs (migration + code, or both in one).
+
+### Phase 2 — Chunking Correctness + Recovery (U5, U6, U7)
+
+Replaces the sweep with a progress-based one; introduces the shared chunking helper with newline alignment; lands the retry + repair-from-scratch endpoints. After this phase, the 7 historical jobs from 2026-05-14 can be operationally recovered (run via the U15 runbook once Phase 4 ships, or earlier with a quick text note). Independently deployable. 2–3 PRs.
+
+### Phase 3 — Observability + Reconciliation (U8, U9, U10, U11)
+
+Wires Sentry, fixes the silent-error paths, adds reconciliation. After this phase, every job has a verified row count, every error reaches Sentry, and the smaller correctness issues (embedding fallback, IIFE error, scheduler.wait) are resolved. 2 PRs (Sentry + the rest).
+
+### Phase 4 — Hardening + Documentation (U12, U13, U14, U15)
+
+Validator hardening, log retention, the test gap backfill, and the runbook. After this phase, the test suite covers the previously-hidden surfaces and the on-call procedure is documented. 1–2 PRs.
+
+---
+
+## Documentation Plan
+
+- `docs/runbooks/etl-pipeline.md` — created in U15.
+- `CLAUDE.md` ETL section — minor update in a Phase 4 PR to link the runbook.
+- Update the existing `docs/audits/2026-05-16-etl-audit.md` with a footer linking to this plan (so future readers know remediation is in progress / done).
+- `/ce-compound` candidates after each phase:
+  - Phase 1: "Cloudflare Queue DLQ + explicit ack/retry pattern in a CF Worker"
+  - Phase 2: "Byte-range R2 chunking with newline alignment"
+  - Phase 3: "Sentry on Cloudflare Workers via `@sentry/cloudflare` (queue + fetch)"
+  - Phase 4: "ETL operational runbook structure"
+
+---
+
+## Operational / Rollout Notes
+
+- Each phase's PR is gated on the previous phase having shipped to prod and observed for at least 24h. No monitoring regression → promote to next phase.
+- The 7-job recovery (operational) happens after Phase 2 lands; document the jobIds and the run in the runbook's recoveries appendix.
+- New env vars: `INVALID_LOG_RETENTION_DAYS` (optional, default 90). Add to `.env.example` in Phase 4.
+- Wrangler secrets to verify: `SENTRY_DSN`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `PACKRAT_SCRAPY_BUCKET_R2_BUCKET_NAME`. None new, but confirm presence before Phase 3 deploy.
+- Rollback: each PR is independently revertable. The migration in U1 has a generated down-migration; verify it cleanly drops the new columns + table without affecting existing data.
+
+---
+
+## Sources & References
+
+- **Origin document:** `docs/audits/2026-05-16-etl-audit.md` (the ETL pipeline audit)
+- Related code:
+  - `packages/api/src/services/etl/`
+  - `packages/api/src/routes/catalog/index.ts`
+  - `packages/api/src/routes/admin/analytics/catalog.ts`
+  - `packages/api/wrangler.jsonc`
+  - `packages/db/src/schema.ts`
+  - `packages/api/test/etl.test.ts`
+  - `packages/cli/src/commands/admin/etl.ts`
+- Live prod evidence: `GET https://packrat-api.orange-frost-d665.workers.dev/api/admin/analytics/catalog/etl?limit=25` (2026-05-19; surfaced 7 wrongly-`failed` jobs at `completedAt = 2026-05-14T16:24:04.470Z`; 192 runs / 74 failed = 38% failure rate; `totalItemsIngested: 304,431`)
+- External docs:
+  - <https://developers.cloudflare.com/queues/configuration/javascript-apis/>
+  - <https://developers.cloudflare.com/queues/configuration/dead-letter-queues/>
+  - <https://developers.cloudflare.com/queues/platform/limits/>
+  - <https://developers.cloudflare.com/workers/runtime-apis/scheduler/>
+  - <https://developers.cloudflare.com/workers/configuration/cron-triggers/>
+  - <https://developers.cloudflare.com/r2/api/s3/api/>
+  - <https://docs.sentry.io/platforms/javascript/guides/cloudflare/>
+  - <https://docs.sentry.io/platforms/javascript/guides/cloudflare/tracing/instrumentation/queues-module/>
+  - <https://github.com/drizzle-team/drizzle-orm/issues/3249>
diff --git a/docs/plans/2026-05-20-001-fix-etl-pipeline-workflows-migration-plan.md b/docs/plans/2026-05-20-001-fix-etl-pipeline-workflows-migration-plan.md
new file mode 100644
index 0000000000..62ed13acf1
--- /dev/null
+++ b/docs/plans/2026-05-20-001-fix-etl-pipeline-workflows-migration-plan.md
@@ -0,0 +1,771 @@
+---
+title: "refactor: Migrate catalog ETL to Cloudflare Workflows"
+type: refactor
+status: active
+date: 2026-05-20
+origin: docs/audits/2026-05-16-etl-audit.md
+supersedes: docs/plans/2026-05-19-001-fix-etl-pipeline-audit-remediation-plan.md
+---
+
+# refactor: Migrate catalog ETL to Cloudflare Workflows
+
+## Summary
+
+Replace the Cloudflare-Queues-based catalog ETL pipeline with a Cloudflare Workflows-based pipeline. Workflows natively provides durable step execution, automatic memoized retries, durable state between steps, and built-in instance status — eliminating roughly half the original audit-remediation plan, which was manually reconstructing those primitives on top of Queues + Postgres. The audit's findings about CSV correctness (chunk-boundary row alignment, header injection), observability, validator hardening, log retention, and the operational runbook remain real and are addressed here. Delivered in three phases: spike + producer-side rewiring; correctness + observability; hardening + tests + docs.
+
+---
+
+## Problem Frame
+
+The catalog ETL audit at `docs/audits/2026-05-16-etl-audit.md` enumerated 16 findings (2 P0, 5 P1, 6 P2, 5 P3) and live prod data (192 runs / 74 failed = 38% failure rate; 7 large jobs falsely marked `failed` by a wall-clock-based sweep on 2026-05-14) confirmed the pipeline is silently incorrect. The first attempted remediation (the now-superseded `2026-05-19-001` plan) tried to fix the Queues-based design in place. Doc review on that plan surfaced a load-bearing P0: the design relied on atomicity between Postgres transactions and Cloudflare Queue `sendBatch` calls that the runtime cannot provide, plus the `drizzle-orm/neon-http` driver doesn't support session-bound transactions with external awaits. Resolving that fork added an outbox table, a cron dispatcher, a watchdog sweep, and a driver switch — making it ~8 units of plumbing to manually rebuild durable execution.
+
+Cloudflare Workflows ships durable execution natively: `step.do(name, fn)` is automatically memoized and retried, step results are persisted between steps (≤1 MiB each), step.sleep survives Worker restarts, instance state IS the job state, and the dashboard surfaces stuck/errored/complete instances without a custom sweep. The producer becomes a one-line `env.ETL_WORKFLOW.create({ params })` call; the entire chunk-completion state machine, DLQ wiring, sweep cron, and outbox plumbing collapse into Workflows-managed state.
+
+---
+
+## Requirements
+
+- R1. **Every catalog source CSV is fully ingested or fully failed-and-recoverable.** No partial completion, no premature "completed" status, no orphan rows.
+- R2. **Chunk-boundary correctness.** No row is dropped, invalidated, or duplicated at byte-range chunk boundaries. CSV headers wider than 4 KB do not silently misalign columns.
+- R3. **Operators can re-ingest any historical job from scratch** without invoking the original producer endpoint. The 7 historical jobs from 2026-05-14 are recoverable via this path.
+- R4. **Every completed ingest has post-ingestion row-count verification.** R2 source row count is compared to the ingested count and surfaced as observable signal; significant deltas emit Sentry warnings.
+- R5. **Failures are visible.** Every workflow error reaches Sentry with `jobId`, `chunkIndex`, source key, and step name. Operators can debug without reading raw Worker logs.
+- R6. **Embedding-fallback degradation is observable.** A workflow that completed without embeddings is distinguishable from a fully-successful one.
+- R7. **Validator rejects unsafe URLs and oversize fields.** Mobile/web cannot be tricked into rendering `javascript:`, IDN homograph, or RFC-1918 URLs from the catalog.
+- R8. **`invalid_item_logs` retention is bounded.** A bad upload cannot fill Neon storage indefinitely.
+- R9. **A documented runbook exists** covering trigger / inspect / retry / repair / reconcile / drain operations against Workflows.
+- R10. **Test coverage exists for every behavior above**, including the cases the legacy global queue-mock currently hides.
+
+---
+
+## Scope Boundaries
+
+- The plan does not migrate the embeddings pipeline. `EMBEDDINGS_QUEUE` continues to operate as a Cloudflare Queue with the existing producer/consumer pattern. Only the catalog ETL pipeline moves to Workflows.
+- The plan does not rewrite the existing `etl_jobs` data for the 7 historical jobs falsely marked `failed`. The re-ingest workflow is the recovery mechanism; the actual recovery run is operational, not a code unit.
+- The plan does not raise queue concurrency on `EMBEDDINGS_QUEUE` or alter its configuration.
+- The plan does not change the catalog data model, `catalogItems`, or downstream consumers (`apps/expo`, `apps/guides`, `apps/landing`).
+- The plan does not introduce a separate ETL Worker; the existing `packages/api` Worker hosts both the HTTP routes and the new Workflow binding.
+
+### Deferred to Follow-Up Work
+
+- **Soft-delete / discontinued-item reconciliation** (audit P3 #3): documented as accepted limitation in the runbook (catalog is scraper-controlled, not user content).
+- **Embeddings-queue DLQ + retry policy**: separate plan once the catalog ETL pivot is proven in production.
+- **Workflows-based scraper orchestration**: out of scope. Scrapers continue to write CSVs to `packrat-scrapy-bucket`; this plan only touches what happens after the file lands.
+- **`@sentry/cloudflare` cold-start performance regression**: measured if observed, addressed in a follow-up. Not blocking this plan.
+
+---
+
+## Context & Research
+
+### Relevant Code and Patterns
+
+- **Producer endpoint** (current): `packages/api/src/routes/catalog/index.ts:229-293` — `POST /catalog/etl`. Will be reduced to a Workflow trigger.
+- **Per-chunk processor** (current, to be replaced): `packages/api/src/services/etl/processCatalogEtl.ts` (208 lines). Its inner logic (R2 byte-range read, CSV parse, batch flush, embeddings + upsert + invalid-log handoff) becomes the body of `step.do()` calls inside the new workflow.
+- **Queue producer/consumer** (current, to be removed): `packages/api/src/services/etl/queue.ts` — `queueCatalogETL` and `processQueueBatch`. Deleted at end of Phase 1.
+- **R2 access**: `packages/api/src/services/r2-bucket.ts:193-360` — `R2BucketService` wrapping AWS S3 client. Works inside Workflows the same as inside a Worker handler. Will be spike-tested in U1.
+- **Drizzle Neon access**: `packages/api/src/db/index.ts:82-84` — `createDbClient(env)` returns the neon-http driver. Inside a `step.do()` callback, single-statement DB calls and multi-statement batched transactions both work; the issue with the Queues-based plan was awaiting *external* RPCs inside `db.transaction()`. In Workflows, each `step.do()` is its own unit of atomicity, so the driver's HTTP-batch limitation is no longer a blocker.
+- **Embeddings**: `packages/api/src/services/catalogService.ts` — `generateManyEmbeddings` + the existing `EMBEDDINGS_QUEUE` pattern. Unchanged. The ETL workflow calls this inside a `step.do()`; embedding failures increment a counter (R6) without re-firing on retry (memoization).
+- **Existing ETL test**: `packages/api/test/etl.test.ts` — integration test against real Postgres via Docker wsproxy at `localhost:5434`. New workflow-based tests follow the same fixture/mock pattern. `packages/api/test/setup.ts:544-551`'s global queue mock is removed since the queue no longer participates.
+- **Schema location**: `packages/db/src/schema.ts:446-510`. Smaller migration than the superseded plan needed — most chunk-tracking columns are absorbed into Workflows instance state.
+- **Wrangler config**: `packages/api/wrangler.jsonc` — new `workflows` binding added; the `packrat-etl-queue` producer + consumer entries removed at the end of Phase 1 once the producer cuts over.
+- **Admin routes**: `packages/api/src/routes/admin/analytics/catalog.ts` — `GET /admin/analytics/catalog/etl` continues to read from `etl_jobs`; admin retry/repair endpoints now trigger workflow instances rather than enqueue messages.
+- **Admin CLI**: `packages/cli/src/commands/admin/etl.ts` — subcommands re-target the new admin endpoints.
+
+### Institutional Learnings
+
+- `docs/solutions/` carries no prior Workflows or queue-based-ETL learnings — this is the first project Workflows footprint. After Phase 2 ships, `/ce-compound` candidates: (a) "Cloudflare Workflows step.do idempotency for batch ETL", (b) "Migration from Queues-based state machine to Workflows".
+
+### External References
+
+- **Cloudflare Workflows API** (verified 2026-05-20): <https://developers.cloudflare.com/workflows/>. `step.do(name, fn)` is idempotent + memoized by step name within an instance. Built-in retries with configurable backoff; `step.sleep` / `step.sleepUntil` for durable waits.
+- **Workflows limits** (verified 2026-05-20): <https://developers.cloudflare.com/workflows/reference/limits/>. 10,000 steps per instance (configurable to 25,000); 30s CPU per step (configurable to 5 min); wall-clock unlimited per step; step output max 1 MiB; 50,000 concurrent running instances on Paid; 1 GB state per instance.
+- **Workflows pricing**: documented but ambiguous in the public docs as of plan-write — verified in U1 spike with `wrangler workflows`/dashboard inspection at PackRat's scale (~250 jobs/day × ~3 steps/job).
+- **Cloudflare Queues** (existing, retained for `EMBEDDINGS_QUEUE` only): <https://developers.cloudflare.com/queues/configuration/javascript-apis/>.
+- **R2 S3 API compatibility**: <https://developers.cloudflare.com/r2/api/s3/api/> — range reads via AWS SDK work identically inside Workflows.
+- **Sentry on Cloudflare**: <https://docs.sentry.io/platforms/javascript/guides/cloudflare/> — first-party `@sentry/cloudflare` with `Sentry.withSentry({ fetch, queue, workflow })` wrapping pattern.
+
+---
+
+## Key Technical Decisions
+
+- **One workflow per source CSV.** `CatalogEtlWorkflow` takes `{ objectKey, source, scraperRevision }` as params; the instance ID derives from `(source, filename)` so duplicate triggers for the same file (e.g., from a producer-side retry) are no-ops via Workflows' instance-id idempotency. This subsumes the deepening pass's per-chunk idempotency table entirely.
+- **Chunks become workflow steps, not queue messages.** For each chunk index, the workflow runs `step.do(\`chunk-${i}\`, async () => processChunk(...))`. Workflows memoizes the step result, so a retry of a partially-completed workflow resumes from the last unfinished step. The audit's P0 #1 (premature completion) and P0 #2 (swallowed errors) are non-findings.
+- **No `etl_job_chunks`, `etl_outbox_messages`, `etl_dlq_events`, `chunks_total/chunks_completed/last_progress_at` columns.** Workflows instance state IS the job state. The `etl_jobs` table retains its existing shape (id, status, source, filename, started_at, completed_at, total_processed, total_valid, total_invalid, scraper_revision) plus new columns for DB-side denormalization that admin queries need: `workflow_instance_id text` (the Workflows instance id), `verified_at timestamp`, `verified_row_count integer`, `total_embedding_failures integer DEFAULT 0 NOT NULL` (R6), `superseded_by_job_id text`, `superseded_at timestamp`, `source_etag text`, and `source_last_modified timestamp`. See U2 for the full column list and migration SQL.
+- **Repair-from-scratch creates a new workflow instance with a new `(source, filename, scraperRevision)` triple keyed by a fresh nonce in the instance id**, so the original instance and the repair instance are both queryable in the Workflows dashboard and both have rows in `etl_jobs`. The `superseded_by_job_id text` column on `etl_jobs` (FK to `etl_jobs.id`, `ON DELETE SET NULL`) links them; `superseded_at timestamp` preserves the timeline even after FK cleanup. A CHECK constraint prevents self-reference.
+- **R2 source ETag captured at workflow start.** New `source_etag text` and `source_last_modified timestamp` columns on `etl_jobs`. Repair-from-scratch compares the stored ETag against fresh `r2.head().etag` and returns 409 on mismatch unless `?force=true` is supplied. For legacy rows (the 7 historical jobs), the migration SQL sets `source_etag = NULL` (the ETag is genuinely unknown at migration time and cannot be resolved inside a SQL migration). As a post-migration operational step, an operator calls `r2.head()` for each of the 7 job IDs and issues a targeted `UPDATE etl_jobs SET source_etag = $1, source_last_modified = $2 WHERE id = $3` only if the file still exists — closing the audit's source-verification gap. This procedure is documented in the U5 runbook and U8 historical-recovery appendix.
+- **Reconciliation is the final step of every workflow.** No separate queue; no `verified_row_count_partial` checkpoint column needed (a single step can run for 5 min CPU + unlimited wall-clock, which covers all realistic source sizes; if a workflow ever hits the 5-min step CPU limit, it's split into N counting steps by chunk range). Reconciliation reads the source via `r2.get(key)` and counts logical rows using `csv-parse` (not raw newline counting — this closes the audit-corrected finding about quoted multi-line CSV fields).
+- **Row-boundary alignment lives in the producer (`chunkCsvForR2` helper).** Each chunk window's `byteEnd` is snapped to the last `\n` in a small (64 KB) tail-read; chunks emit on row boundaries; the consumer no longer needs `skipPartialRow` logic. The 64 KB peek reads are parallelized with `Promise.all` so the producer-side CPU budget is not strained for multi-GB files. Resolves audit P1 #3/#4/#5.
+- **Header injection for non-first chunks uses a bounded-expand re-fetch loop** (4 KB → 16 KB → 64 KB), throwing a typed `EtlHeaderError` if no newline appears in 64 KB. Resolves audit P1 #3 silent column misalignment.
+- **Workflow retry policy** is per-step: `{ limit: 3, delay: '30s', backoff: 'exponential' }` for chunk-processing steps; `{ limit: 0 }` for reconciliation (a delta is data, not a failure — surface to Sentry and continue). On total workflow failure (all retries exhausted), Workflows marks the instance `errored`, the workflow's final cleanup step runs (set `etl_jobs.status='failed'`, capture Sentry event with all chunk failure history). No DLQ table needed; the Workflows dashboard is the forensic surface.
+- **`@sentry/cloudflare` wraps `{ fetch, queue, workflow }`** in `packages/api/src/index.ts`. Per-step `Sentry.startSpan` for chunk processing; `Sentry.captureException` on step failure; tags include `jobId`, `workflowInstanceId`, `chunkIndex`, `r2Key`. `error_stack` is contractually free of raw CSV row data (documented at call sites; the U10 test asserts it). Sentry source-map upload via `@sentry/cli sourcemaps upload` is wired into CI as part of U6 — not just `upload_source_maps: true` in wrangler.jsonc.
+- **URL validator** (U7) restricts to `http(s):`, rejects IDN homograph (deny non-ASCII hostnames or normalize via punycode and compare), rejects RFC-1918 / loopback / link-local hostnames after DNS resolution-pattern check (string-level, not network). Length cap 2048. SKU charset `/^[A-Za-z0-9_.\-\/]+$/` max 200 chars.
+- **`invalid_item_logs` retention runs as a scheduled Workflow** (or a CF Cron Trigger calling a deletion step). Batched DELETE: loop `DELETE FROM invalid_item_logs WHERE id IN (SELECT id FROM invalid_item_logs WHERE created_at < now() - interval '90 days' LIMIT 10000)` until 0 rows; surface Sentry warning if a single run hits a max-iteration cap.
+
+---
+
+## Open Questions
+
+### Resolved During Planning
+
+- **Queues vs Workflows for execution.** Resolved: Workflows. Eliminates ~8 units of plumbing that the prior plan needed.
+- **Per-chunk idempotency.** Resolved: free via `step.do(name, fn)` memoization. No `etl_job_chunks` table.
+- **DB+Queue atomicity.** Resolved: no longer applicable. Each `step.do()` is its own unit of durability; Workflows persists step results between steps.
+- **Drizzle driver choice.** Resolved: stay on `neon-http`. The audit-plan blocker (transactions with external awaits) doesn't apply because each step is atomic.
+- **Stuck-job sweep design.** Resolved: not needed. Workflows surfaces stuck/errored instances natively in the dashboard.
+- **DLQ design.** Resolved: not needed. Failed workflow instances are the forensic record.
+- **CSV parser for reconciliation.** Resolved: use `csv-parse` (not raw newline counting). Closes the quoted-multiline-field correctness gap.
+- **Workflow instance ID strategy.** Resolved: deterministic ID `${source}-${filename}` for first ingest (prevents duplicate triggers); repair-from-scratch uses `${source}-${filename}-repair-${nonce}`.
+- **Producer cutover strategy.** Resolved: coexist both paths during transition. The producer endpoint accepts a `?engine=workflow|queue` query parameter (default `workflow`); operators can fall back to the queue path during a rollback window. After Phase 1 bakes for a week with no fallback usage, the queue path is removed in a Phase 2 cleanup PR.
+
+### Deferred to Implementation
+
+- **Workflows pricing at PackRat's scale.** ~250 jobs/day × ~3 chunks/job = ~750 step executions/day. U1's spike confirms cost is comfortably within Workers Paid; if not, escalate before Phase 2.
+- **Exact step CPU budget per chunk.** The 30s default is likely sufficient; if R2 + Drizzle + embeddings + upsert overruns, bump to `cpu_ms: 60000` or split chunk processing into sub-steps (parse → embed → upsert).
+- **Reconciliation step CPU budget for the largest historical files (50,100 rows / ~30 MB).** Likely <10s in CPU; verified in U1 spike.
+- **Cron trigger for retention sweep — separate Workflow vs traditional cron-handler.** Both work; choose based on Phase 3 ergonomics.
+- **Sentry sampling rate** for Workflows spans. Default `tracesSampleRate: 0.1`; tune in production.
+
+---
+
+## Output Structure
+
+    packages/api/src/
+    ├── workflows/
+    │   ├── catalog-etl-workflow.ts          (NEW — the main ETL workflow)
+    │   ├── retention-workflow.ts            (NEW — invalid_item_logs sweep)
+    │   └── shared/
+    │       ├── chunkCsvForR2.ts             (NEW — row-boundary-aligned chunking)
+    │       └── reconcileJob.ts              (NEW — final-step row count comparison)
+    ├── services/etl/
+    │   ├── CatalogItemValidator.ts          (MODIFIED — U7 hardening)
+    │   ├── mergeItemsBySku.ts               (MODIFIED — aggregate log per batch)
+    │   ├── processValidItemsBatch.ts        (MODIFIED — embedding-fallback counter)
+    │   ├── processLogsBatch.ts              (MODIFIED — rethrow on DB failure)
+    │   ├── constants.ts                     (NEW — ITEM_FLUSH_BATCH_SIZE etc.)
+    │   ├── processCatalogEtl.ts             (DELETED — superseded by workflow)
+    │   └── queue.ts                         (DELETED at end of Phase 1)
+    ├── routes/catalog/index.ts              (MODIFIED — producer triggers workflow)
+    ├── routes/admin/analytics/catalog.ts    (MODIFIED — retry/repair/reconcile route workflows)
+    ├── utils/logger.ts                      (NEW — small; structured-field wrapper)
+    └── index.ts                             (MODIFIED — withSentry + workflow export)
+
+    packages/db/src/schema.ts                (MODIFIED — 5 new columns on etl_jobs)
+    packages/api/drizzle/0048_etl_workflow_columns.sql   (NEW)
+    packages/api/wrangler.jsonc              (MODIFIED — workflows binding; retire ETL_QUEUE end of Phase 1)
+    packages/cli/src/commands/admin/etl.ts   (MODIFIED — subcommands target workflow endpoints)
+    packages/api/test/                       (NEW workflow tests)
+    docs/runbooks/etl-pipeline.md            (NEW)
+
+---
+
+## High-Level Technical Design
+
+> *This illustrates the intended approach and is directional guidance for review, not implementation specification.*
+
+```text
+Producer  ─── POST /catalog/etl ──┐
+                                  │
+                                  ▼
+        ┌─────────────────────────────────────────────┐
+        │ chunkCsvForR2(key)                          │
+        │   r2.head → chunks[]                        │
+        │   parallel(Promise.all):                    │
+        │     for each window: peek tail, align       │
+        │       byteEnd to last '\n'                  │
+        └─────────────────────────────────────────────┘
+                                  │
+                          INSERT etl_jobs
+                          (status='running',
+                           source_etag, source_last_modified)
+                                  │
+                          env.ETL_WORKFLOW.create({
+                            id: `${source}-${filename}`,
+                            params: { objectKey, source,
+                                      scraperRevision, chunks,
+                                      jobId }
+                          })
+                                  │
+                                  ▼
+        ┌─────────────────────────────────────────────┐
+        │ CatalogEtlWorkflow.run({ event, step }):    │
+        │                                             │
+        │   for each chunk in params.chunks:          │
+        │     await step.do(`chunk-${i}`, {           │
+        │       retries: { limit: 3, delay: '30s',    │
+        │                  backoff: 'exponential' },  │
+        │       timeout: '5 minutes',                 │
+        │     }, async () => {                        │
+        │       // - r2.get(key, range)               │
+        │       // - csv-parse with backpressure      │
+        │       // - flush valid → embeddings → upsert│
+        │       // - flush invalid → logs             │
+        │       // - return { rowsProcessed,          │
+        │       //            rowsValid, rowsInvalid }│
+        │     })                                      │
+        │                                             │
+        │   await step.do('aggregate', async () => {  │
+        │     // sum chunk results, UPDATE etl_jobs   │
+        │     // SET total_processed, total_valid,    │
+        │     //     total_invalid                    │
+        │   })                                        │
+        │                                             │
+        │   await step.do('reconcile', async () => {  │
+        │     // csv-parse R2 source, count rows,     │
+        │     // UPDATE verified_at,                  │
+        │     //         verified_row_count           │
+        │     // Sentry.captureMessage on delta       │
+        │   })                                        │
+        │                                             │
+        │   await step.do('finalize', async () => {   │
+        │     // UPDATE status='completed',           │
+        │     //         completed_at=now()           │
+        │   })                                        │
+        └─────────────────────────────────────────────┘
+
+On step failure exhausting retries:
+  → Workflow instance → 'errored' state
+  → Workflows dashboard surfaces with full step history
+  → Sentry capture from a Sentry.withSentry workflow wrapper
+  → A final 'errored' lifecycle hook runs:
+    UPDATE etl_jobs SET status='failed', completed_at=now()
+
+Scheduled (CF Cron Trigger or scheduled workflow):
+  retention-workflow:
+    loop: DELETE FROM invalid_item_logs WHERE id IN (
+            SELECT id FROM invalid_item_logs
+            WHERE created_at < now() - interval '90 days'
+            LIMIT 10000
+          )
+    until 0 rows affected
+    or max iterations (Sentry warning if hit)
+```
+
+---
+
+## Implementation Units
+
+### U1. Workflows spike: R2 + Drizzle Neon + csv-parse inside step.do
+
+**Goal:** Prove the integration works at PackRat's actual scale before committing to the migration. 30-60 minutes of focused work; output is a GO/NO-GO with concrete observations.
+
+**Requirements:** Gates R1-R10 (if Workflows can't host the workload, the entire plan blocks).
+
+**Dependencies:** None
+
+**Files:**
+- Create: `packages/api/src/workflows/spike-etl-workflow.ts` (throwaway; deleted after the spike or kept as a reference fixture)
+- Modify: `packages/api/wrangler.jsonc` (add workflows binding for the spike)
+- No tests — this is a manual spike.
+
+**Approach:**
+- Build a minimal workflow with three steps:
+  1. `step.do('head', () => r2.head('v2/cotopaxi/cotopaxi_2026-05-14T16-54-05.csv'))` — verify R2 binding works inside step.do.
+  2. `step.do('chunk', () => r2.get(key, { range: { offset: 0, length: 1024*1024 } }).then(b => b.text()))` — verify byte-range read returns useable string.
+  3. `step.do('parse-and-write', async () => { /* csv-parse 100 rows, INSERT into a scratch test table via Drizzle Neon, return { rowsWritten } */ })` — verify csv-parse + Drizzle work inside step.do.
+  4. `step.sleep('rest', '5 seconds')` — verify durable sleep works.
+  5. `step.do('verify-memoization', async () => { console.log('this should fire exactly once even across retries'); return Date.now(); })` — trigger an artificial retry (throw on first call via a counter file) and verify the second attempt sees the memoized result.
+- Run via `wrangler dev --remote` (Workflows requires remote bindings) or `wrangler workflows trigger` against deployed dev environment.
+- Observe in Workflows dashboard: step durations, retry behavior, total instance latency, billing meter delta.
+- Document: pricing observed for this run, any unexpected friction, blocker confirmation/clearance.
+
+**Patterns to follow:**
+- The Workflows quickstart example pattern from <https://developers.cloudflare.com/workflows/get-started/guide/>.
+- Existing `R2BucketService` instantiation pattern at `packages/api/src/services/r2-bucket.ts:193-210`.
+- Existing `createDbClient(env)` pattern from `packages/api/src/db/index.ts:82-84`.
+
+**Test scenarios:**
+- *Test expectation: none — this is a manual spike. The workflow itself is throwaway.*
+
+**Verification:**
+- Spike workflow completes successfully end-to-end in the Workflows dashboard.
+- Memoization confirmed: the artificially-retried step shows the same return value on the second attempt.
+- Pricing observed at the dashboard's billing meter is within an order of magnitude of "negligible" for one run. (Extrapolated to 250 jobs/day, must stay clearly under any concerning threshold.)
+- Document one of: GO (proceed to U2), GO-WITH-CAVEATS (proceed but note the friction), NO-GO (fall back to the superseded plan's outbox design).
+
+---
+
+### U2. Drizzle migration 0048: workflow_instance_id + embedding-failure counter (slimmed during implementation)
+
+> **Scope adjustment (2026-05-20):** During PR review the schema additions were narrowed from 8 columns to 2. Rationale: most of the originally-scoped columns (`verified_at`, `verified_row_count`, `superseded_by_job_id`, `superseded_at`, `source_etag`, `source_last_modified`) exist to support audit findings whose consumers (U5 repair endpoint, U6 Sentry observability, the reconcile UI) ship in later PRs. Adding them now creates dead schema. Each follow-up unit adds the column it needs when it lands. The two columns kept are the ones with value from day one: `workflow_instance_id` links every new `etl_jobs` row to its CF Workflows instance for admin debugging, and `total_embedding_failures` makes embedding-fallback degradation observable in admin queries without code changes elsewhere. The text below describes the originally-scoped 8 columns for context; what actually ships is the slim version.
+
+**Goal:** Add the minimal schema columns Workflows-based execution needs for DB-side denormalization (admin queries continue to work without hitting the Workflows API for every list).
+
+**Requirements:** R1, R3, R4, R6
+
+**Dependencies:** U1 (spike must pass before committing migration to the new architecture)
+
+**Files:**
+- Modify: `packages/db/src/schema.ts` (add columns to `etlJobs`; UNIQUE constraint on `catalogItemEtlJobs`)
+- Create: `packages/api/drizzle/0048_etl_workflow_columns.sql`
+- Create: `packages/api/drizzle/meta/0048_snapshot.json` (generated)
+- Modify: `packages/api/drizzle/meta/_journal.json` (generated)
+- Test: `packages/api/test/db-schema-etl.test.ts` (new — assert columns exist with expected defaults)
+
+**Approach:**
+- Columns added to `etl_jobs`:
+  - `workflow_instance_id text` (nullable — legacy queue-based rows leave NULL until repair)
+  - `verified_at timestamp` (nullable)
+  - `verified_row_count integer` (nullable)
+  - `total_embedding_failures integer DEFAULT 0 NOT NULL`
+  - `superseded_by_job_id text` (nullable, FK to `etl_jobs.id` `ON DELETE SET NULL`)
+  - `superseded_at timestamp` (nullable)
+  - `source_etag text` (nullable)
+  - `source_last_modified timestamp` (nullable)
+- CHECK constraints on `etl_jobs`:
+  - `etl_jobs_no_self_supersede CHECK (superseded_by_job_id IS NULL OR superseded_by_job_id <> id)`
+- Indexes:
+  - `etl_jobs_workflow_instance_id_idx` on `(workflow_instance_id)` — for the admin "find by workflow" lookup
+  - `etl_jobs_superseded_by_idx` on `(superseded_by_job_id)`
+- Modification to `catalog_item_etl_jobs`: add `UNIQUE (catalog_item_id, etl_job_id)` so retried upserts use `ON CONFLICT DO NOTHING`.
+- **Source-ETag backfill (one-shot, in the migration itself)**: a `DO $$ BEGIN UPDATE etl_jobs SET source_etag = NULL, source_last_modified = NULL WHERE status IN ('completed', 'failed'); END $$;` is a no-op for the 7 historical jobs in the sense that the ETag is genuinely unknown — but a companion *operational* step (in U10 runbook) calls `r2.head()` for each of the 7 jobids and `UPDATE etl_jobs SET source_etag = $1, source_last_modified = $2 WHERE id = $3` ONLY IF the file still exists. This is the documented forensic recovery procedure; it does not run inside the SQL migration.
+- Drizzle generator: `bun run --cwd packages/api db:generate`. Hand-verify the generated SQL emits literal `DEFAULT 0 NOT NULL` for `total_embedding_failures` (Drizzle Kit sometimes drops SQL-side defaults).
+
+**Patterns to follow:**
+- Existing `etl_jobs` definition at `packages/db/src/schema.ts:460-479`.
+- Migration `0027_past_madrox.sql` (added `scraper_revision` + index) for the "add column + index" pattern.
+
+**Test scenarios:**
+- Happy path: After migration, all 8 new columns present with documented defaults; both indexes queryable; UNIQUE constraint on `catalog_item_etl_jobs` prevents duplicate inserts.
+- Edge case: Existing rows have `workflow_instance_id = NULL`, `total_embedding_failures = 0`, `source_etag = NULL`.
+- Error path: `INSERT etl_jobs SET superseded_by_job_id = id` violates the no-self-supersede CHECK.
+- Error path: Re-running the migration is a no-op (Drizzle's migration log handles this).
+
+**Verification:**
+- `bun run --cwd packages/api db:migrate` applies cleanly against a fresh Docker Postgres + against a Postgres seeded with current-prod-shape `etl_jobs` rows.
+- `bun lint:custom` passes.
+- `bun test:api:unit` includes the new schema test and it passes.
+
+---
+
+### U3. Define CatalogEtlWorkflow + producer cutover
+
+**Goal:** Replace `processCatalogEtl.ts` + `queue.ts` + `processQueueBatch` with a single `CatalogEtlWorkflow` class. Producer endpoint switches from `sendBatch` to `env.ETL_WORKFLOW.create()`. Old queue path coexists during transition (via `?engine=workflow|queue`).
+
+**Requirements:** R1, R3, R5
+
+**Dependencies:** U2 (schema columns must exist for workflow to write them)
+
+**Execution note:** Test-first for the workflow class itself. Write the integration test (small CSV, 3 chunks, full ingest path) before implementing the workflow body — the test acts as the executable specification of the desired behavior.
+
+**Files:**
+- Create: `packages/api/src/workflows/catalog-etl-workflow.ts` (the main workflow class)
+- Create: `packages/api/src/workflows/shared/chunkCsvForR2.ts` (row-boundary-aligned chunking; parallel peek reads via `Promise.all`; pulled forward from old plan's U6/U7)
+- Modify: `packages/api/src/index.ts` (export `CatalogEtlWorkflow`; extend the Worker module type)
+- Modify: `packages/api/wrangler.jsonc` (add `workflows` binding `ETL_WORKFLOW`; keep `packrat-etl-queue` for the coexistence window)
+- Modify: `packages/api/src/routes/catalog/index.ts` (producer accepts `?engine=workflow|queue`; default `workflow`; both paths INSERT into `etl_jobs` with `source_etag` capture)
+- Modify: `packages/api/src/services/etl/types.ts` (`CatalogEtlWorkflowParams` type)
+- Delete (Phase 1 cleanup PR, *after* coexistence window): `packages/api/src/services/etl/processCatalogEtl.ts`, `packages/api/src/services/etl/queue.ts`
+- Test: `packages/api/test/etl-workflow-integration.test.ts` (new — end-to-end test using a mocked `step` runtime)
+
+**Approach:**
+- `CatalogEtlWorkflow extends WorkflowEntrypoint<Env, CatalogEtlWorkflowParams>`:
+  ```text
+  async run(event, step) {
+    const { jobId, objectKey, chunks } = event.payload;
+
+    const chunkResults = [];
+    for (const [i, chunk] of chunks.entries()) {
+      const result = await step.do(
+        `chunk-${i}`,
+        {
+          retries: { limit: 3, delay: '30s', backoff: 'exponential' },
+          timeout: '5 minutes',
+        },
+        async () => this.processChunk(jobId, objectKey, chunk, i),
+      );
+      chunkResults.push(result);
+    }
+
+    await step.do('aggregate', async () => this.aggregateCounters(jobId, chunkResults));
+    await step.do('reconcile', async () => this.reconcile(jobId, objectKey));
+    await step.do('finalize', async () => this.finalizeJob(jobId));
+  }
+  ```
+- `processChunk` body absorbs the existing `processCatalogETL` logic: R2 byte-range read, csv-parse with backpressure, batch flush, embedding fallback path (increments `total_embedding_failures`), invalid-log handoff. Returns `{ rowsProcessed, rowsValid, rowsInvalid }` — small enough to fit in the 1 MiB step output cap.
+- Header injection for non-first chunks uses the bounded-expand re-fetch loop (4K → 16K → 64K → throw `EtlHeaderError`).
+- `chunkCsvForR2`: producer-side row-boundary alignment with parallel 64KB peek reads (closes audit P1 #3/#4/#5 + the previously-flagged producer CPU budget concern). Returns `Array<{ chunkIndex, chunksTotal, byteStart, byteEnd }>` plus the captured `etag` + `lastModified`.
+- Producer endpoint writes `etl_jobs` row with `source_etag`, `source_last_modified`, `workflow_instance_id`; then `env.ETL_WORKFLOW.create({ id: \`${source}-${filename}\`, params: { jobId, objectKey, source, scraperRevision, chunks } })`. The deterministic instance ID prevents duplicate triggers for the same file (Workflows rejects duplicate IDs).
+- Producer's `?engine=queue` branch keeps the old `queueCatalogETL` flow for rollback. Removed in the Phase 1 cleanup PR after one week of bake.
+- Test uses Workflows' test harness (`@cloudflare/vitest-pool-workers`) or mocks the `step` object directly with an in-memory implementation that exercises memoization.
+
+**Patterns to follow:**
+- Workflows quickstart: <https://developers.cloudflare.com/workflows/get-started/guide/>.
+- Existing `R2BucketService` and `createDbClient` instantiation patterns.
+- Existing CSV parse + backpressure handling in `processCatalogEtl.ts:80-130` (lifted into `processChunk`).
+
+**Test scenarios:**
+- Happy path: 3-chunk CSV (small fixture), workflow runs end-to-end, final `etl_jobs.status = 'completed'`, `total_processed = 100` (or fixture row count), `verified_at` set, `total_embedding_failures = 0`.
+- Edge case: One chunk throws a transient error; Workflows retries once and succeeds; final state correct; `aggregate` step's input includes the retried chunk's eventual success result (memoization).
+- Edge case: Embedding service throws on chunk 1's flush; `total_embedding_failures` increments by the flush size; chunk still completes (embedding fallback); workflow continues; `verified_at` set.
+- Edge case: Chunk boundary lands on a row boundary; total row count matches `wc -l` minus header.
+- Edge case: Header row >4 KB (synthetic fixture with 60 columns of long names); re-fetch expands to 16 KB; columns mapped correctly.
+- Error path: All retries on chunk 0 exhaust; workflow instance enters `errored`; lifecycle hook flips `etl_jobs.status = 'failed'`; Sentry captures with full step history.
+- Error path: Duplicate trigger for the same `(source, filename)` returns the existing instance ID; no duplicate row inserted.
+- Integration: Producer endpoint with `?engine=workflow` triggers a workflow; with `?engine=queue` triggers the legacy path. Both produce a working ingest. Compared row counts match.
+
+**Verification:**
+- Integration test passes against the test Postgres.
+- `bun api` dev server: hitting `POST /catalog/etl?engine=workflow` with a real R2 fixture triggers a visible workflow instance in `wrangler workflows list catalog-etl-workflow`.
+- Workflow instance completes; `etl_jobs` row reflects expected counters; Sentry event present on simulated chunk failure.
+
+---
+
+### U4. Validator hardening: scheme, IDN, SSRF, length caps, SKU charset
+
+**Goal:** Eliminate audit P3 #2 attack surface — `javascript:`, IDN homograph, RFC-1918, oversize fields cannot enter the catalog.
+
+**Requirements:** R7
+
+**Dependencies:** None (independent; can land any time)
+
+**Files:**
+- Modify: `packages/api/src/services/etl/CatalogItemValidator.ts`
+- Test: `packages/api/test/etl-validator.test.ts` (new or extend existing)
+
+**Approach:**
+- `isValidUrl`:
+  - Parse with `new URL()`.
+  - Reject scheme other than `http:` / `https:` → reason `INVALID_URL_SCHEME`.
+  - Reject length > 2048 → `URL_TOO_LONG`.
+  - Reject IDN homograph: if `url.hostname` contains any non-ASCII character, run through `punycode.toUnicode` and compare to original; reject mixed-script labels via the Unicode IDNA `getStringPrepProfile` heuristic (or a small allow-list of Latin-only scripts). Reason `INVALID_URL_HOMOGRAPH`.
+  - Reject private/loopback/link-local hostnames via string-level pattern check (no DNS resolution — that adds an unbounded fetch surface and is itself an SSRF risk): block hostname literals matching `/^(?:127\.|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|169\.254\.|fc00:|fd00:|fe80:|localhost$|::1$)/i`. Reason `INVALID_URL_PRIVATE`.
+- Length caps: `name ≤ 500`, `description ≤ 50000`, `brand ≤ 200`, `category ≤ 200`.
+- SKU regex: `/^[A-Za-z0-9_.\-\/]+$/` max 200.
+
+**Patterns to follow:**
+- Existing validator at `packages/api/src/services/etl/CatalogItemValidator.ts`.
+- Invalid-log shape at `packages/api/src/services/etl/processLogsBatch.ts`.
+
+**Test scenarios:**
+- Happy path: `https://example.com/product/123` accepted.
+- Error path: `javascript:alert(1)` rejected (`INVALID_URL_SCHEME`).
+- Error path: `https://192.168.1.1/admin` rejected (`INVALID_URL_PRIVATE`).
+- Error path: `https://xn--pypal-4ve.com/` rejected (`INVALID_URL_HOMOGRAPH`).
+- Error path: `https://localhost/` rejected (`INVALID_URL_PRIVATE`).
+- Edge case: URL of exactly 2048 chars accepted; 2049 rejected.
+- Edge case: SKU `ABC-123_/test.sku` accepted; SKU `<script>` rejected.
+- Integration: A real prod-shape CSV with an injected `javascript:` URL run through the workflow → row in `invalid_item_logs`, no `catalog_items` insert.
+
+**Verification:**
+- New tests pass.
+- `bun test:api` overall green.
+
+---
+
+### U5. Retry, repair-from-scratch, reconcile admin endpoints (workflow-aware)
+
+**Goal:** Operators can trigger a new workflow instance from a historical `jobId` (retry), force a re-ingest with verification (repair-from-scratch), or trigger reconciliation against any job.
+
+**Requirements:** R3, R4
+
+**Dependencies:** U3 (workflow class must exist)
+
+**Files:**
+- Modify: `packages/api/src/routes/admin/analytics/catalog.ts` (rewrite `POST /admin/etl/:jobId/retry`; add `POST /admin/etl/:jobId/repair-from-scratch`; add `POST /admin/etl/:jobId/reconcile`)
+- Modify: `packages/cli/src/commands/admin/etl.ts` (add/refresh subcommands)
+- Modify: admin list endpoint response shape (include `workflowInstanceId`, `verifiedAt`, `verifiedRowCount`, `totalEmbeddingFailures`)
+- Test: `packages/api/test/etl-admin-retry-repair-reconcile.test.ts` (new)
+
+**Approach:**
+- `POST /admin/etl/:jobId/retry`: look up original `(source, filename, scraperRevision)`; verify `r2.head` of the original `filename` matches stored `source_etag` (409 on mismatch unless `?force=true`); INSERT a new `etl_jobs` row with `superseded_by_job_id = :jobId`, `superseded_at = now()`; trigger workflow with a fresh instance ID `${source}-${filename}-retry-${nonce}`.
+- `POST /admin/etl/:jobId/repair-from-scratch`: same shape as retry but always sets supersession even for `completed` jobs. Use case: an operator suspects a `completed` job is undercount.
+- `POST /admin/etl/:jobId/reconcile`: synchronously reads the source via `r2.get(key)`, csv-parses + counts logical rows, updates `verified_at` + `verified_row_count` on the target job. For very large files the operator can pass `?async=true` to trigger a workflow whose only step is reconcile.
+- Both endpoints accept `?dryRun=true` returning the planned action without side effects.
+- 7-job historical recovery procedure documented in U8 runbook: for each of the 7 jobIds, operator (a) verifies R2 source still exists, (b) backfills `source_etag` via a one-time SQL UPDATE using the current `r2.head().etag`, (c) calls `POST /admin/etl/:jobId/repair-from-scratch` (no `force` needed once etag is backfilled).
+
+**Patterns to follow:**
+- Admin route structure at `packages/api/src/routes/admin/analytics/catalog.ts:178-235`.
+- Workflow trigger pattern from U3.
+
+**Test scenarios:**
+- Happy path: Retry of a `failed` job whose source still exists → 409? No, 200 (ETag matches), new workflow instance triggered, new `etl_jobs` row with `superseded_by_job_id` set.
+- Happy path: Repair-from-scratch on a `completed` job → new workflow instance, supersession recorded.
+- Edge case: Retry when source has been overwritten (ETag mismatch) → 409; operator must use `?force=true`.
+- Edge case: `?dryRun=true` returns planned action; no side effects.
+- Edge case: Reconcile on a tiny job returns inline; on a synthetic 1 GB fixture with `?async=true` triggers a reconcile-only workflow.
+- Integration: Repair-from-scratch on a 50,100-row file produces a new job whose `total_processed = 50100`, `verified_row_count = 50100`.
+- Covers AE: The 7 historical jobs from 2026-05-14 are recoverable via this endpoint after the manual ETag backfill step.
+
+**Verification:**
+- Endpoints documented in OpenAPI spec via `@elysiajs/openapi`.
+- CLI subcommands invoke endpoints with proper auth.
+- `bun test:api` passes.
+
+---
+
+### U6. Observability: Sentry wiring, structured logger, error propagation fixes
+
+**Goal:** Every workflow error reaches Sentry with structured context. Embedding fallback observable via counter + Sentry breadcrumb. Internal error-propagation fixes from audit P2 #2/#3/#4.
+
+**Requirements:** R5, R6
+
+**Dependencies:** U3 (workflow class to instrument)
+
+**Files:**
+- Modify: `packages/api/package.json` (add `@sentry/cloudflare`, pin version)
+- Modify: `packages/api/src/index.ts` (wrap with `Sentry.withSentry({ ...opts, fetch, workflow, queue })`)
+- Modify: `packages/api/wrangler.jsonc` (`upload_source_maps: true`)
+- Modify: `.github/workflows/api-deploy.yml` (or equivalent) (add `@sentry/cli sourcemaps upload` step after deploy)
+- Create: `packages/api/src/utils/logger.ts` (thin wrapper: `info/warn/error(event, ctx)`; emits JSON line + Sentry breadcrumb when initialized)
+- Modify: `packages/api/src/workflows/catalog-etl-workflow.ts` (instrument each step with `Sentry.startSpan`; capture exceptions in step bodies)
+- Modify: `packages/api/src/services/etl/processLogsBatch.ts` (rethrow on DB failure — audit P2 #2)
+- Modify: `packages/api/src/services/etl/processValidItemsBatch.ts` (embedding-fallback path atomically increments `etl_jobs.total_embedding_failures`, emits Sentry warning — audit P2 #3)
+- Modify: `packages/api/src/services/etl/mergeItemsBySku.ts` (per-batch summary log instead of per-SKU — audit P3 #1)
+- Modify: All ETL files' `console.*` → `logger.*` (mechanical)
+- Modify: `packages/api/src/services/etl/processCatalogEtl.ts` *if it still exists* (writer IIFE wrap — audit P2 #4); deletion in Phase 1 cleanup makes this moot
+- Create: `packages/api/src/services/etl/constants.ts` (`ITEM_FLUSH_BATCH_SIZE = 100`, `CF_QUEUE_BATCH_SIZE = 100` — audit P2 #6)
+- Test: `packages/api/test/sentry-instrumentation.test.ts` (mock `@sentry/cloudflare`; assert capture shape)
+- Test: `packages/api/test/etl-error-propagation.test.ts` (rethrows, fallback counter increments)
+
+**Approach:**
+- Wrap the default export at `packages/api/src/index.ts` with `Sentry.withSentry(getOptions, { fetch, workflow, queue })`. Options factory reads `env.SENTRY_DSN`, `env.ENVIRONMENT`, sets `tracesSampleRate: 0.1`.
+- Workflow instrumentation: each `step.do(name, fn)` callback wraps the body in `Sentry.startSpan({ op: 'workflow.step', name, attributes: { jobId, workflowInstanceId, chunkIndex } }, ...)`. Capture errors before rethrowing.
+- Source-map upload: `@sentry/cli sourcemaps upload --release=$SENTRY_RELEASE ./dist` in CI after `wrangler deploy` — symbolicated stack traces in Sentry. Just `upload_source_maps: true` in wrangler.jsonc only ships maps to Cloudflare, not Sentry.
+- `error_stack` contract: the Sentry capture call sites use `Sentry.captureException(err, { tags: { jobId, workflowInstanceId, chunkIndex }, contexts: { ... } })` and pass error-message-only payloads — never include raw CSV row data. U10 test asserts no row-data substrings leak into the captured payload across all error paths.
+- Compatibility flags: verify `@sentry/cloudflare`'s required flags for the chosen version against the current `wrangler.jsonc` flags. `nodejs_compat` is already set; if the chosen version requires `nodejs_compat_v2` or `nodejs_als`, add them.
+
+**Patterns to follow:**
+- Reference: <https://docs.sentry.io/platforms/javascript/guides/cloudflare/>.
+- Workflows-specific tracing: workflow-aware spans via `withSentry`'s `workflow` wrapper.
+
+**Test scenarios:**
+- Happy path: Successful workflow → one `startSpan` per step, no `captureException`.
+- Error path: A `step.do` throws → `captureException` called with `{ jobId, workflowInstanceId, chunkIndex }` tags; span marks status error; workflow retries per step retry policy.
+- Edge case: `SENTRY_DSN` empty (dev without secret) → no Sentry calls; logger still emits lines; no crash.
+- Edge case: `processLogsBatch` DB INSERT fails → exception propagates → step retried by Workflows.
+- Edge case: Embedding service throws → `total_embedding_failures` increments atomically by the batch size; `etl.embedding.fallback` Sentry warning fires once per batch.
+- Integration: A forced chunk failure in dev produces a Sentry event visible in the project with the expected tags.
+
+**Verification:**
+- `grep -rn 'console\.' packages/api/src/services/etl/ packages/api/src/workflows/` returns nothing.
+- A real `bun api` cold-start log contains the Sentry init line.
+- Sentry test project receives an event from a forced workflow failure.
+- CI sourcemaps upload step succeeds; minified frames in Sentry show original filenames.
+
+---
+
+### U7. Retention sweep: scheduled handler with batched DELETE
+
+**Goal:** Bounded growth of `invalid_item_logs`. Naive single-statement DELETE is replaced with a batched loop to survive multi-million-row pruning.
+
+**Requirements:** R8
+
+**Dependencies:** None
+
+**Files:**
+- Create: `packages/api/src/workflows/retention-workflow.ts` *(or)* `packages/api/src/services/retention/invalidLogRetention.ts` + a `scheduled()` handler arm — pick one based on Phase 3 ergonomics
+- Modify: `packages/api/src/index.ts` (`scheduled` handler dispatches on `event.cron`, or workflow trigger registered)
+- Modify: `packages/api/wrangler.jsonc` (add `"triggers": { "crons": ["0 9 * * *"] }` — top-level `triggers` wrapper, not bare `crons`)
+- Test: `packages/api/test/etl-log-retention.test.ts` (new)
+
+**Approach:**
+- Sweep: loop
+  ```text
+  DELETE FROM invalid_item_logs
+  WHERE id IN (
+    SELECT id FROM invalid_item_logs
+    WHERE created_at < now() - interval '90 days'
+    LIMIT 10000
+  );
+  ```
+  until `0 rows affected` OR `iterations >= 100`. Pause briefly between iterations (`await scheduler.wait(100)`). If max iterations hit, Sentry warning with the deleted-row count so operators know more remains.
+- 90-day window default; configurable via `env.INVALID_LOG_RETENTION_DAYS`.
+- Daily cron at 09:00 UTC.
+
+**Patterns to follow:**
+- CF Cron Triggers config: <https://developers.cloudflare.com/workers/configuration/cron-triggers/>.
+
+**Test scenarios:**
+- Happy path: Seed table with 30k rows older than 90 days and 100 rows younger → sweep deletes exactly 30k in 3 iterations, leaves 100 rows.
+- Edge case: Empty table → sweep deletes 0 rows; no error; no Sentry warning.
+- Edge case: 1.5M rows older than 90 days → sweep hits max iterations cap at 1M deleted, emits Sentry warning, leaves remaining for next run.
+- Edge case: `INVALID_LOG_RETENTION_DAYS=30` env override → 30d-old logs swept.
+
+**Verification:**
+- New test passes.
+- `wrangler dev --test-scheduled` exercises the handler; assertion via DB row count delta.
+
+---
+
+### U8. Runbook at `docs/runbooks/etl-pipeline.md`
+
+**Goal:** A new on-caller can trigger / inspect / retry / repair / reconcile / drain operations against Workflows without reading source.
+
+**Requirements:** R9
+
+**Dependencies:** U3, U5 (operator-facing endpoints must exist)
+
+**Files:**
+- Create: `docs/runbooks/etl-pipeline.md`
+
+**Approach:**
+Sections:
+1. **Architecture overview** — producer → workflow instance → step.do chunks → aggregate → reconcile → finalize, with a small Mermaid diagram.
+2. **Triggering an ETL** — `curl POST /catalog/etl` (params, auth); CLI equivalent.
+3. **Inspecting workflow status** — `wrangler workflows instances list catalog-etl-workflow`; `wrangler workflows instances describe <id>`; admin dashboard query.
+4. **Retrying a failed workflow** — `curl POST /admin/etl/:jobId/retry`; CLI `packrat-admin etl retry <jobId>`.
+5. **Repair-from-scratch** — including the explicit one-time procedure for the seven 2026-05-14 jobs (list jobIds; describe ETag backfill step; describe expected output).
+6. **Reconciliation** — manual sync endpoint vs async-workflow trigger; interpreting delta.
+7. **Draining the queue (legacy path)** — only relevant during the coexistence window; how to verify drain before removing the queue config.
+8. **DLQ alternative** — since Workflows is the forensic record, the runbook explains: "Failed workflow instances are queryable for 90 days via dashboard; `wrangler workflows instances describe <id>` shows full step history with errors."
+9. **Accepted limitations** — soft-delete/discontinued-item reconciliation is not in scope; catalog grows monotonically.
+10. **References** — link to the audit, this plan, Workflows docs, Sentry project.
+
+**Patterns to follow:**
+- First runbook in `docs/runbooks/`; establishes the convention.
+
+**Test scenarios:**
+- *Test expectation: none — documentation only.*
+
+**Verification:**
+- Reviewer walks through each documented procedure in dev and confirms expected output.
+
+---
+
+### U9. Test gap backfill
+
+**Goal:** Cover the behaviors the legacy global queue-mock hid; add fixtures for byte-range edge cases.
+
+**Requirements:** R10
+
+**Dependencies:** U3, U4, U6 (units under test must exist)
+
+**Files:**
+- Modify: `packages/api/test/setup.ts` (remove the global queue mock — `processQueueBatch` no longer exists)
+- Create: `packages/api/test/etl-workflow-multi-chunk.test.ts`
+- Create: `packages/api/test/etl-csv-edge-cases.test.ts`
+- Create: `packages/api/test/fixtures/etl/` (synthesized at test startup with deterministic seed):
+  - `small-1chunk.csv` (~10 KB)
+  - `medium-3chunk.csv` (~50 MB synthetic, splits into 3 chunks)
+  - `wide-header.csv` (6 KB header)
+  - `bom-prefixed.csv` (starts with BOM)
+  - `quoted-header.csv` (CSV-quoted commas in header)
+  - `quoted-multiline.csv` (newlines inside quoted fields — gated by U3 csv-parse reconciliation, not raw byte counting)
+
+**Approach:**
+- Each new test exercises the real workflow integration against the test Postgres + mocked `step` runtime.
+- Specific assertions:
+  - Multi-chunk workflow completes with one `status='completed'` transition.
+  - Header > 4 KB: re-fetch expands to 16 KB, columns mapped correctly.
+  - Row-spanning chunk: no rows dropped or duplicated; total row count matches `wc -l - 1`.
+  - BOM-prefixed file: stripped before header extraction.
+  - Quoted-multiline file: csv-parse counts logical rows correctly; reconcile delta = 0.
+  - Embedding fallback: `total_embedding_failures` increments; chunk completes; Sentry warning fires once per batch.
+  - Step memoization: forced retry of one chunk produces the same return value on the second attempt (mocked step runtime asserts this).
+
+**Patterns to follow:**
+- Existing `packages/api/test/etl.test.ts` for fixture setup + Docker Postgres pattern.
+- Vitest mocking conventions from `packages/api/test/setup.ts`.
+
+**Test scenarios:**
+- (Each described above.)
+
+**Verification:**
+- `bun test:api` passes.
+- Coverage delta is positive on `packages/api/src/workflows/` and the modified ETL service files.
+
+---
+
+## System-Wide Impact
+
+- **Interaction graph:** Producer endpoint → `chunkCsvForR2` (parallel peek reads) → INSERT etl_jobs with source_etag → `env.ETL_WORKFLOW.create(...)` → workflow instance runs `chunk-*` steps in order → `aggregate` → `reconcile` → `finalize`. Failed instances surface in Workflows dashboard. Sentry wraps every entry point (`fetch`, `workflow`, `queue` — the last for the unchanged embeddings queue). One scheduled cron arm for retention sweep.
+- **Error propagation:** Errors thrown inside `step.do` callbacks are captured by `Sentry.captureException`, rethrown to Workflows runtime, retried per step config; exhaustion routes the instance to `errored`; the workflow's terminal `errored` lifecycle hook flips `etl_jobs.status='failed'` and captures a final Sentry event with step history. Inner code (`processLogsBatch`, `processValidItemsBatch` embedding fallback) rethrows on DB failure so the step retries with the right backoff.
+- **State lifecycle:** Workflows step results are durably persisted and memoized by step name; retries are exactly-once-on-success. No `chunks_total/chunks_completed/last_progress_at` columns are needed because instance state is the source of truth. `etl_jobs` carries only the denormalized counters needed by admin queries.
+- **API surface parity:** Producer `POST /catalog/etl` keeps the same request body shape; accepts an additional optional `?engine=workflow|queue` parameter (default `workflow`) during the coexistence window. Admin endpoints: rewritten retry, new repair-from-scratch, new reconcile. Old endpoints (`/admin/etl/reset-stuck`) are removed in U3's PR (no replacement needed — Workflows surfaces stuck instances natively).
+- **Integration coverage:** U9 exercises the full pipeline end-to-end. The legacy global queue mock at `packages/api/test/setup.ts:544-551` is removed since the queue no longer participates in catalog ETL.
+- **Unchanged invariants:** `EMBEDDINGS_QUEUE` and `LOGS_QUEUE` configuration; `catalog_items` upsert behavior (still SKU-keyed); OpenAPI client generated by `@elysiajs/openapi` for non-ETL routes; admin auth surface (`adminAuthGuard`); scraper-revision pinning; mobile and web apps untouched.
+
+---
+
+## Risks & Dependencies
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| **Workflows pricing surprises at PackRat's scale** | Med (unknown until measured) | Med | U1 spike captures dashboard billing meter for one run; extrapolate to ~750 step-executions/day. Escalate before Phase 2 if cost trajectory exceeds Workers Paid base. |
+| **`step.do` output exceeds 1 MiB cap** for very wide chunks | Low | Med | Chunk-step returns aggregated counters only (`{ rowsProcessed, rowsValid, rowsInvalid }`), not row data. Detail rows go to `catalog_items` / `invalid_item_logs` via DB writes inside the step. |
+| **Producer's parallel newline-peek reads collide with R2 rate limits** for multi-GB files | Low | Med | `Promise.all` over ≤50 chunks × one 64KB read each = ≤50 concurrent R2 GETs; well within R2's documented per-bucket throughput. If issue surfaces, bound concurrency with a small p-limit. |
+| **`@sentry/cloudflare` requires compatibility_flags beyond `nodejs_compat`** | Low | Med | Verify against the pinned Sentry version at U6 start; add any missing flags as part of U6. |
+| **Coexistence window misuse** (operators flip `?engine=queue` after cutover) | Low | Low | Producer logs a Sentry breadcrumb on `?engine=queue` usage; runbook documents the deprecation. Cleanup PR removes the option entirely a week after cutover. |
+| **The 7 historical jobs' R2 sources have been deleted** by a separate retention policy | Low | Low | U8 runbook procedure verifies `r2.head` before invoking repair; if missing, accept as documented data loss. |
+| **Workflow instance ID collision** if the same `(source, filename)` is triggered twice (deterministic ID) | Low | Low | Workflows returns the existing instance on duplicate; producer endpoint treats this as success and returns the existing `jobId`. Documented behavior. |
+| **`csv-parse` reconciliation is slower than naive byte counting** for very large files | Low | Low | At ~10MB/s parse rate, a 100MB file takes ~10s — well within step CPU. If a 1 GB+ file appears, the reconcile step is split by byte range (each sub-step parses 200 MB). |
+| **Drizzle Kit emits SQL without literal `DEFAULT 0 NOT NULL`** | Med | High | U2 implementer hand-verifies generated `.sql`; schema smoke test asserts via `information_schema.columns`. |
+| **Down-migration loses Phase-2+ data** once writes start landing | Cert if attempted | High | Migration is **forward-only after U3 ships**; documented in U2's test scenarios and migration header. Rollback strategy is a forward-fix migration. |
+| **Wide-CSV fixture in U9 destabilizes CI** | Low | Low | Synthesize at test startup with deterministic seed (no checked-in large file); cap size in test mode via env. |
+
+---
+
+## Documentation / Operational Notes
+
+- The new runbook at `docs/runbooks/etl-pipeline.md` (U8) is the operator entry point.
+- Sentry project must be provisioned (or confirmed existing) before U6 lands. `env.SENTRY_DSN` is already validated in `packages/api/src/utils/env-validation.ts:9, 94` — verify the prod and dev env have it set via `wrangler secret list`.
+- Rollout sequencing:
+  - **Phase 1** ships U1 + U2 + U3. Producer accepts `?engine=workflow|queue`; default `workflow`. Coexistence window of one week. Daily `wrangler workflows instances list` check during the window.
+  - **Phase 1 cleanup PR** (one week after Phase 1): delete `processCatalogEtl.ts`, `queue.ts`, the `?engine=queue` branch, the `packrat-etl-queue` config. `setup.ts:544-551` global queue mock removed.
+  - **Phase 2** ships U4 + U5 + U6 + U7. Validator hardening, admin endpoints, observability, retention.
+  - **Phase 3** ships U8 + U9. Runbook + test backfill.
+- The 7 historical-job recovery is a one-time operational task after Phase 2; record the run in the runbook's `## Historical Recoveries` appendix.
+- New env vars: `INVALID_LOG_RETENTION_DAYS` (optional, default 90). Add to `.env.example` in Phase 3.
+
+---
+
+## Phased Delivery
+
+### Phase 1 — Workflows foundation + producer cutover (U1, U2, U3)
+
+Spike → migration → workflow class → producer accepts both engines. Independently shippable in 2-3 PRs (spike result attached to U2's PR; U2 + U3 in one PR or split). After Phase 1 bakes for one week, Phase 1 cleanup PR removes the legacy queue path entirely.
+
+### Phase 2 — Validator + admin endpoints + observability + retention (U4, U5, U6, U7)
+
+Hardening + the operator surface that lets the 7-job recovery happen. 2-3 PRs.
+
+### Phase 3 — Runbook + test backfill (U8, U9)
+
+Documentation + test coverage. 1-2 PRs.
+
+---
+
+## Documentation Plan
+
+- `docs/runbooks/etl-pipeline.md` — created in U8.
+- `CLAUDE.md` ETL section — minor update in a Phase 3 PR to link the runbook and note the Workflows architecture.
+- Update `docs/audits/2026-05-16-etl-audit.md` footer linking to this plan (so future readers know remediation went through Workflows).
+- `/ce-compound` candidates after each phase:
+  - Phase 1: "Cloudflare Workflows step.do idempotency for batch ETL"
+  - Phase 1: "Migrating a Cloudflare Queues state machine to Workflows"
+  - Phase 2: "Sentry on Cloudflare Workers via `@sentry/cloudflare` (fetch + workflow + queue)"
+  - Phase 3: "ETL operational runbook structure (Workflows edition)"
+
+---
+
+## Operational / Rollout Notes
+
+- Each phase's PR is gated on the previous phase having shipped to prod and observed for at least 24h. Particular care during Phase 1's coexistence window — monitor `wrangler workflows instances list` daily and confirm the workflow path is the one being exercised.
+- The 7-job recovery happens after Phase 2 lands; document the jobIds and the run in the runbook recoveries appendix.
+- New env vars: `INVALID_LOG_RETENTION_DAYS` (optional, default 90). Add to `.env.example` in Phase 3.
+- Wrangler secrets to verify: `SENTRY_DSN`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `PACKRAT_SCRAPY_BUCKET_R2_BUCKET_NAME`. None new; confirm presence before Phase 2 deploy via `wrangler secret list`.
+- Rollback: each PR is independently revertable until U3's cleanup. Once the legacy queue path is removed, rollback requires a forward-fix.
+
+---
+
+## Sources & References
+
+- **Origin audit:** `docs/audits/2026-05-16-etl-audit.md`
+- **Superseded plan:** `docs/plans/2026-05-19-001-fix-etl-pipeline-audit-remediation-plan.md` (Queues + outbox design; pivoted to Workflows on 2026-05-20)
+- Related code:
+  - `packages/api/src/services/etl/`
+  - `packages/api/src/routes/catalog/index.ts`
+  - `packages/api/src/routes/admin/analytics/catalog.ts`
+  - `packages/api/wrangler.jsonc`
+  - `packages/db/src/schema.ts`
+  - `packages/api/test/etl.test.ts`
+  - `packages/cli/src/commands/admin/etl.ts`
+- Live prod evidence (pulled 2026-05-19 + 2026-05-20): `GET https://packrat-api.orange-frost-d665.workers.dev/api/admin/analytics/catalog/etl?limit=25` showed 192 runs / 74 failed, 7 jobs falsely-failed at 2026-05-14T16:24:04.470Z. Counters unchanged across the two pulls — pipeline is currently dormant.
+- External docs:
+  - <https://developers.cloudflare.com/workflows/>
+  - <https://developers.cloudflare.com/workflows/get-started/guide/>
+  - <https://developers.cloudflare.com/workflows/reference/limits/>
+  - <https://developers.cloudflare.com/queues/configuration/javascript-apis/> (for the embeddings queue, retained)
+  - <https://developers.cloudflare.com/r2/api/s3/api/>
+  - <https://docs.sentry.io/platforms/javascript/guides/cloudflare/>
+  - <https://developers.cloudflare.com/workers/configuration/cron-triggers/>
diff --git a/docs/plans/2026-05-31-002-refactor-utils-guards-hardening-plan.md b/docs/plans/2026-05-31-002-refactor-utils-guards-hardening-plan.md
new file mode 100644
index 0000000000..6e34592877
--- /dev/null
+++ b/docs/plans/2026-05-31-002-refactor-utils-guards-hardening-plan.md
@@ -0,0 +1,429 @@
+---
+title: "refactor: @packrat/utils facade + two-tier guards + layered duplication enforcement"
+type: refactor
+status: completed
+created: 2026-05-31
+origin: in-session brainstorm (not persisted to docs/brainstorms/) — decisions carried forward in Problem Frame + Key Technical Decisions
+depth: deep
+---
+
+# refactor: @packrat/utils Facade + Two-Tier Guards + Layered Duplication Enforcement
+
+## Problem Frame
+
+Utility logic is duplicated across the monorepo — hand-rolled array/object/string/async helpers and raw primitive checks (`typeof x === 'string'`, manual dedupe, hand-written debounce) that could be abstracted behind one curated, type-safe surface. `@packrat/guards` already proves the pattern works for type narrowing (one barrel re-exporting `radash` + `ts-extras` + custom helpers, with a "never use `as` casts" policy and a `no-duplicate-guards` lint). There is **no equivalent home for general utilities**, and nothing enforces "go through the blessed surface" for them.
+
+This plan builds that surface and hardens its enforcement:
+
+1. **`@packrat/utils`** — a new single-barrel package (with subpath exports) that curates the best-typed implementation of each utility across five libraries — **radashi → radash → es-toolkit → lodash → remeda** (soft priority; real tiebreaker is best types + has-the-function). Re-export by default; wrap only when normalization (single-object args, consistent naming) or composition earns it. lodash is retained specifically for old-school primitives (`toString`, `toFloat`, etc.) the modern libs dropped.
+2. **`@packrat/utils` is the sole package allowed to import the five raw libs.** Everything else imports from `@packrat/utils` or `@packrat/guards`.
+3. **`@packrat/guards` becomes a two-tier specialization on top of `@packrat/utils`** — it re-exports generic predicates (`isString`, `isArray`, `isEmpty`, …) sourced through utils, and keeps/grows its custom narrowing, assertion, enum, and zod-parse layer.
+4. **A five-layer enforcement pipeline**, all CI-blocking after migration: `noRestrictedImports` (no reach-around) → `ast-grep` (structural raw-primitive patterns, replacing the brittle regex scripts) → `jscpd` (copy-paste / repeated-logic) → `no-duplicate-utils` (name-based re-implementation) → a **provenance check** (manifest sync + priority order).
+5. **A one-shot agent comb-through** seeds the facade and drives the migration by surfacing duplication and abstraction candidates that static tools miss.
+
+**Migration surface is small and verified (2026-05-31):** only **3 real `from 'radash'` import sites** exist (`packages/analytics/src/core/local-cache.ts` → `tryit`; `packages/guards/src/index.ts` → barrel re-export; `apps/expo/features/pack-templates/components/FeaturedPacksSection.tsx`). `packages/api` *declares* `radash` but never imports it (dead dep). `radashi`, `es-toolkit`, and `remeda` are net-new to the repo.
+
+**Target repo:** PackRat. Intended to land in a **new worktree**. All paths below are repo-relative.
+
+---
+
+## Verified Findings (this session, 2026-05-31)
+
+Load-bearing facts gathered from the repo; the units below depend on them:
+
+- **Internal packages are unbundled source.** `@packrat/guards` is `private: true` with `exports → ./src/index.ts` and **no tsup/build step**. tsup is only for *distributed* libs. `@packrat/utils` follows the same shape — no build.
+- **Subpath exports have direct precedent.** `packages/env` uses explicit subpaths (`"./node"`, `"./next"`, …); `packages/api` and `packages/schemas` use the wildcard `"./*": "./src/*.ts"`. Either works for utils' category subpaths.
+- **`biome noRestrictedImports` is supported** (present in `node_modules/@biomejs/biome/configuration_schema.json`; biome 2.4.6). Per-path scoping uses the existing `overrides[].includes` mechanism already in `biome.json`.
+- **The check-wiring triad is fixed convention.** A new check is wired into `lefthook.yml` (pre-push `clean-checks`), `scripts/check-all.ts` (master orchestrator), and `.github/workflows/checks.yml`, plus the `lint:custom` / `lint:strict` aggregate scripts in root `package.json`. The pre-push header states *"All custom checks are now clean — no continue-on-error backlog remaining"* — so new checks must be green (full migration) before they're added to the blocking set.
+- **`packages/checks` is the home for richer checks** (`check-magic-strings.ts`, `check-route-schemas.ts`, `check-type-casts.ts`), invoked via `bun run --cwd packages/checks ...`. The provenance check belongs here. The coarser nudge-style checks live in `scripts/lint/`.
+- **Existing enforcement philosophy already prefers builders over raw primitives.** `no-raw-regex.ts` enforces `magic-regexp` over raw regex and explicitly notes *"Biome's `performance/useTopLevelRegex` covers the stricter AST check"* — the team already understands the regex-vs-AST tradeoff, making ast-grep a natural upgrade.
+- **Library type-nativeness:** radashi, es-toolkit, remeda, and radash are all TS-native and ship their own types; only lodash needs `@types/lodash`.
+- **Adjacency (coordination, not conflict):** `docs/plans/2026-05-31-001-refactor-monorepo-dependency-policy-plan.md` (authored today) edits root `package.json` catalog/overrides **and the same check-wiring triad**, and establishes a **fenced-JSON-registry-parsed-by-a-lint** pattern (because `package.json` is strict JSON — no inline comments). This plan reuses that registry pattern for provenance and should expect to rebase its triad edits onto that plan's.
+- **`bun.lock` regenerates on install;** review its diff whenever deps change.
+
+---
+
+## Key Technical Decisions
+
+**D1 — `@packrat/utils` is the single import boundary for the five libs.**
+Only `packages/utils/**` may import `radashi`/`radash`/`es-toolkit`/`lodash`/`remeda`. Enforced via biome `noRestrictedImports` (global ban) + a `biome.json` override scoping the rule off for `packages/utils/**`. `@packrat/guards` is **not** exempt from the five-lib ban — it obtains generic predicates *through* utils. (Guards keeps its existing `ts-extras` + `zod` direct imports; those are outside the banned set.)
+
+**D2 — Two-tier dependency direction: `guards → utils`, one-directional.**
+`@packrat/guards` depends on `@packrat/utils` (workspace dep). Guards re-exports generic predicates from utils and layers its custom narrowing/assertions/enum/zod-parse on top. No cycle (utils never imports guards); enforced by the existing `no-circular-deps.ts`.
+
+**D3 — Two distinct enforcement exemption sets.**
+The "no raw library imports" exemption is **utils-only**. The "no raw `typeof`" exemption is **utils + guards** (guards is the legitimate home for custom `typeof` narrowing). These are deliberately different sets; the ast-grep rules and biome config encode them separately so they don't get conflated.
+
+**D4 — Curate by re-export; wrap only when it earns it.**
+Default is a thin re-export sourcing the best-typed implementation. Wrap when (a) normalizing to repo conventions (single-object args for `useMaxParams: 2`, consistent naming) or (b) composing a primitive the libs lack. No speculative wrappers — the facade grows from real usage + duplication the sweep surfaces.
+
+**D5 — Provenance is a fenced-JSON manifest enforced by a check in `packages/checks`.**
+A manifest records, per facade export: `source` (which lib), and `alsoIn` (higher-priority libs known to provide it, if any). The check asserts (a) every facade export appears with a valid `source`; (b) `source` is an allowed lib; (c) no export sources from a lower-priority lib when `alsoIn` lists a higher-priority one — i.e. priority is enforced against the curator's *own declared* alternatives, not by dynamically probing every lib's API (which would be brittle across versions). This keeps the priority rule real and CI-blocking without an unmaintainable cross-lib API index.
+
+**D6 — The five libs are direct deps of `@packrat/utils`, not catalog entries** *(diverges from the brainstorm assumption; follows the newer dependency policy)*.
+Per `docs/plans/2026-05-31-001-...-dependency-policy-plan.md`, catalog is for deps **multiple workspaces declare directly and must agree on**. Post-migration only `@packrat/utils` imports these libs, so they are single-consumer direct deps → declared directly in `packages/utils/package.json`, **not** catalog. This means `radash` moves **out** of root catalog as part of migration. `check:catalog` (`no-duplicate-deps.ts`) stays green because no other workspace declares them. *(Reversible on review if the team prefers cataloging the blessed libs regardless.)*
+
+**D7 — ast-grep and jscpd are root dev dependencies, not catalog.**
+Single-consumer tooling (root scripts) → plain `devDependencies` in root `package.json`, consistent with D6 and the dependency policy. `@ast-grep/cli` and `jscpd`.
+
+---
+
+## Output Structure
+
+```text
+packages/utils/                      # new — the curated facade (private, unbundled source)
+  package.json                       # private; subpath exports; direct deps on the five libs
+  src/
+    index.ts                         # root barrel (re-exports all categories)
+    array.ts
+    object.ts
+    string.ts
+    async.ts
+    fn.ts
+    math.ts
+    provenance.ts                    # the fenced-JSON manifest source-of-truth (or .json — see U9)
+  test/
+    array.test.ts
+    string.test.ts
+    wrappers.test.ts                 # custom/wrapped helpers only
+    provenance.test.ts
+
+packages/checks/src/
+  check-utils-provenance.ts          # new — manifest sync + priority enforcement (U9)
+
+scripts/lint/
+  no-duplicate-utils.ts              # new — name-based re-implementation check (U8)
+  no-raw-typeof.ts                   # DELETED — ported to ast-grep (U6)
+  no-raw-regex.ts                    # DELETED — ported to ast-grep (U6)
+
+sgconfig.yml                         # new — ast-grep project config (U6)
+ast-grep-rules/
+  no-raw-typeof.yml                  # ported rule, with autofix
+  no-raw-regex.yml                   # ported rule
+  no-handrolled-util.yml             # new structural rules for facade equivalents
+
+.jscpd.json                         # new — copy-paste detector config (U7)
+
+docs/utils-policy.md                 # new — the facade curation policy + provenance contract
+```
+
+The tree is a scope declaration, not a constraint; per-unit **Files** lists are authoritative.
+
+---
+
+## High-Level Technical Design
+
+The two-tier surface and the enforcement boundary:
+
+```text
+        radashi  radash  es-toolkit  lodash  remeda      (raw libs — direct deps of utils only)
+            \       \        |         /       /
+             \       \       |        /       /
+              ▼       ▼      ▼       ▼       ▼
+          ┌─────────────────────────────────────────┐
+          │   @packrat/utils   (SOLE lib importer)   │   re-export + wrap; provenance manifest
+          │   barrel + subpaths: array/object/...    │
+          └─────────────────────────────────────────┘
+                 ▲                         ▲
+                 │ (predicates)            │ (utilities)
+          ┌──────────────────┐      ┌──────────────────────────────┐
+          │  @packrat/guards │      │  all other packages + apps    │
+          │  custom narrow / │      │  import ONLY from the facade   │
+          │  assert / zod    │      └──────────────────────────────┘
+          └──────────────────┘
+
+  Enforcement (CI-blocking after migration):
+   1. biome noRestrictedImports  → ban the five libs outside packages/utils
+   2. ast-grep                   → structural raw-primitive patterns (replaces regex scripts)
+   3. jscpd                      → copy-paste / repeated-logic detection
+   4. no-duplicate-utils         → name-based re-implementation of facade exports
+   5. check-utils-provenance     → manifest sync + priority order
+```
+
+*This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
+
+---
+
+## Implementation Units
+
+Grouped into four phases. U-IDs are stable and never renumbered.
+
+### Phase 1 — Facade foundation
+
+### U1. Enroll libs + scaffold `@packrat/utils`
+
+**Goal:** Stand up the empty `@packrat/utils` package with subpath exports and the five libs as direct deps; add `@types/lodash`.
+**Requirements:** Single curated utility surface (Problem Frame #1); single import boundary (D1, D6).
+**Dependencies:** none.
+**Files:**
+- `packages/utils/package.json` (create — `private: true`, `type: module`, root + category subpath exports mirroring `packages/env`; deps: `radashi`, `radash`, `es-toolkit`, `lodash`, `remeda`, `@types/lodash`)
+- `packages/utils/src/index.ts` (create — empty barrel re-exporting category files)
+- `packages/utils/src/{array,object,string,async,fn,math}.ts` (create — empty stubs)
+- `package.json` (modify — remove `radash` from `catalog` per D6; confirm no other catalog churn)
+- `bun.lock` (regenerated; review diff)
+
+**Approach:** Mirror `packages/guards/package.json` shape plus subpath exports. Pick the explicit-subpath style (`"./array": "./src/array.ts"`, …) like `packages/env` for discoverability, plus the `"."` root barrel. No build step (D-Verified: unbundled source).
+
+**Patterns to follow:** `packages/env/package.json` (subpath exports), `packages/guards/package.json` (private unbundled shape).
+
+**Test scenarios:**
+- `Test expectation: none -- scaffolding/package manifest; behavior arrives in U3. Verified by typecheck + install resolving the new workspace.`
+
+**Verification:** `bun install` resolves the new workspace; `@packrat/utils` and each subpath import-resolve from a scratch file; `radash` no longer in root catalog; `check:catalog` and `bun check-types` pass.
+
+---
+
+### U2. One-shot agent comb-through → duplication & abstraction findings
+
+**Goal:** Produce a findings document enumerating (a) duplicated/hand-rolled utility logic across `packages/` + `apps/`, (b) raw primitives with a facade equivalent, and (c) the prioritized list of functions the facade should expose first — each mapped to its best-typed source lib.
+**Requirements:** "Tired of duplicated code we could abstract" (Problem Frame); seeds U3 curation and U10 migration.
+**Dependencies:** none (can run parallel to U1).
+**Files:**
+- `docs/utils-sweep-findings.md` (create — the agent's report: candidate exports, source lib per candidate, duplication clusters with file references, suggested wrappers)
+
+**Approach:** Dispatch a sweep agent (or `jscpd`-assisted scan as input) over `packages/` and `apps/` to surface repeated logic and hand-rolled helpers. Output is a decision-support artifact, not code. The curator (U3) treats it as the candidate backlog. Cross-check against the 3 known `radash` sites and any `lodash`-shaped hand-rolls.
+
+**Patterns to follow:** none (research artifact).
+
+**Test scenarios:**
+- `Test expectation: none -- findings document; correctness is validated by U3 consuming it and U7/U8 later catching anything missed.`
+
+**Verification:** `docs/utils-sweep-findings.md` exists with a concrete candidate list (function → source lib → call sites) sufficient to drive U3 without re-deriving it.
+
+---
+
+### U3. Curate & implement the `@packrat/utils` surface
+
+**Goal:** Populate the facade — re-export the best-typed implementation per function across the five libs, wrapping only where D4 justifies; author the provenance manifest alongside each export.
+**Requirements:** Single curated, type-safe surface; composability (Problem Frame #1, D4); provenance source-of-truth (D5).
+**Dependencies:** U1, U2.
+**Files:**
+- `packages/utils/src/{array,object,string,async,fn,math}.ts` (implement)
+- `packages/utils/src/index.ts` (wire re-exports)
+- `packages/utils/src/provenance.ts` or `provenance.json` (create — the manifest U9 enforces; see U9 for shape decision)
+- `packages/utils/test/array.test.ts`, `string.test.ts`, `wrappers.test.ts` (create)
+- `docs/utils-policy.md` (create — curation policy: priority order, wrap-vs-reexport rule, provenance contract)
+
+**Approach:** For each candidate from U2: choose the source lib by best types + availability (priority order as tiebreaker), re-export directly, and record `{ source, alsoIn }` in the manifest. Wrap (D4) only for arg-shape normalization (`useMaxParams: 2`) or composition. Keep categories cohesive; the root barrel re-exports all. Mirror `@packrat/guards/src/index.ts`'s sectioned-comment style documenting where each group comes from.
+
+**Patterns to follow:** `packages/guards/src/index.ts` (sectioned re-export barrel with provenance comments), `packages/guards/src/narrow.ts` (wrapper + alias style).
+
+**Test scenarios:**
+- Happy path: each **wrapped** helper returns expected output for representative inputs (e.g. a normalized single-object-arg wrapper maps to the underlying lib call correctly).
+- Edge cases: wrapped helpers handle empty/nullish/boundary inputs per their documented contract (empty array, `undefined`, zero).
+- Type-level: a `tsd`-style or `expectTypeOf` assertion that key exports carry the expected types (esp. lodash-sourced ones via `@types/lodash`) and that subpath imports (`@packrat/utils/array`) resolve.
+- Smoke: every name listed in the provenance manifest is actually exported from the barrel (guards against manifest/code drift from the code side; U9 guards the manifest side).
+- `Pure re-exports (no wrapper) are NOT re-tested` — the upstream lib owns that behavior; only wrappers and the barrel/manifest contract are tested here.
+
+**Verification:** `@packrat/utils` exports the curated surface; wrappers covered by tests with coverage meeting repo gates; `bun check-types` passes; manifest lists every export.
+
+---
+
+### Phase 2 — Guards two-tier refactor
+
+### U4. Refactor `@packrat/guards` onto `@packrat/utils`
+
+**Goal:** Make guards depend on utils, re-export generic predicates from utils (not directly from `radash`), and keep/grow the custom narrowing/assertion/enum/parse layer.
+**Requirements:** Two-tier architecture (Problem Frame #3, D2); removes guards' direct `radash` import (one of the 3 migration sites).
+**Dependencies:** U3.
+**Files:**
+- `packages/guards/package.json` (modify — add `@packrat/utils: workspace:*`; remove `radash` direct dep)
+- `packages/guards/src/index.ts` (modify — source `isString`/`isArray`/`isObject`/`isEmpty`/`isEqual`/… from `@packrat/utils` instead of `radash`; keep `ts-extras` + custom re-exports)
+- `packages/guards/test/*` (add/extend — assert the re-exported predicate surface is unchanged for consumers)
+
+**Approach:** Swap the `from 'radash'` predicate block to `from '@packrat/utils'`. Public surface of `@packrat/guards` stays byte-for-byte identical to consumers (same names exported) — this is an internal sourcing change. Custom files (`narrow.ts`, `assertions.ts`, `enum.ts`, `parse.ts`) are untouched except where a predicate they use now comes from utils.
+
+**Execution note:** Characterization-first — snapshot the current `@packrat/guards` public export list before the change; assert it's identical after (no consumer-visible drift).
+
+**Patterns to follow:** the existing `packages/guards/src/index.ts` re-export structure.
+
+**Test scenarios:**
+- Covers the no-regression contract: the set of names exported from `@packrat/guards` is identical before and after (snapshot/enumeration test).
+- Happy path: representative predicates (`isString`, `isArray`, `isEmpty`) behave identically when imported from `@packrat/guards` post-refactor.
+- Integration: a downstream consumer (`packages/config`, which depends on `@packrat/guards`) type-checks and runs unchanged.
+- Edge: no circular dependency introduced — `no-circular-deps.ts` passes with the new `guards → utils` edge.
+
+**Verification:** guards imports predicates from utils; `radash` gone from `packages/guards/package.json`; public export surface unchanged; `no-circular-deps` + `bun check-types` pass.
+
+---
+
+### Phase 3 — Enforcement pipeline (built green, flipped to blocking in U10)
+
+### U5. `noRestrictedImports` — ban reach-around imports
+
+**Goal:** Forbid direct imports of the five libs everywhere except `packages/utils/**`.
+**Requirements:** Single import boundary (D1).
+**Dependencies:** U3 (facade must exist so there's a legal alternative), U4 (guards already migrated so the rule lands green).
+**Files:**
+- `biome.json` (modify — add `noRestrictedImports` to `linter.rules` banning `radashi`/`radash`/`es-toolkit`/`lodash`/`remeda`; add an `overrides` entry scoping the rule `off` for `packages/utils/**`)
+
+**Approach:** Use biome's native `noRestrictedImports`. Global ban with a per-path override (the same mechanism `biome.json` already uses for `useMaxParams`/`useTopLevelRegex` exemptions). No custom script needed.
+
+**Patterns to follow:** existing `biome.json` `overrides[].includes` exemption blocks.
+
+**Test scenarios:**
+- Happy path: a file outside utils importing `from 'lodash'` is flagged by `bun biome check`; the same import inside `packages/utils/**` is not.
+- Edge: subpath/`/fp` style imports (`lodash/merge`, `es-toolkit/compat`) are also caught (pattern covers submodules), or explicitly documented if biome's matcher can't and a fallback ast-grep rule covers it.
+
+**Verification:** `bun biome check` flags reach-around imports outside utils and stays silent inside utils; repo is clean post-U10 migration.
+
+---
+
+### U6. Introduce ast-grep; port and retire the regex scripts
+
+**Goal:** Add ast-grep with AST-accurate, autofixable rules for raw `typeof` and raw regex; delete `no-raw-typeof.ts` and `no-raw-regex.ts`.
+**Requirements:** Structural (not name/text) enforcement of raw primitives (Problem Frame #4; user: "not just about name … repeated logic"); D3 exemption sets.
+**Dependencies:** U3.
+**Files:**
+- `package.json` (modify — add `@ast-grep/cli` devDep; add `check:ast-grep` script)
+- `sgconfig.yml` (create — ast-grep project config pointing at `ast-grep-rules/`)
+- `ast-grep-rules/no-raw-typeof.yml` (create — match `typeof $X === '<primitive>'`, autofix to facade/guards predicate; preserve the `GLOBAL_IDENTIFIERS` exemption — `window`/`document`/`globalThis`/`Bun`/`navigator`/`process`; exempt `packages/utils/**` + `packages/guards/**` per D3)
+- `ast-grep-rules/no-raw-regex.yml` (create — match raw regex literals / `new RegExp`, point to `magic-regexp`; exempt utils)
+- `scripts/lint/no-raw-typeof.ts` (delete)
+- `scripts/lint/no-raw-regex.ts` (delete)
+- `scripts/check-all.ts`, `lefthook.yml`, `.github/workflows/checks.yml`, root `lint:custom`/`lint:strict` (modify — replace the two deleted script references with `check:ast-grep`)
+
+**Approach:** Encode the rules in ast-grep YAML with `language: typescript`. Carry over the exact exemptions the regex scripts had (global identifiers; the `packages/guards` carve-out for `typeof`). ast-grep's `fix:` field provides autofix where a 1:1 predicate substitution is safe.
+
+**Test scenarios:**
+- Happy path: a fixture file with `typeof v === 'string'` outside utils/guards is flagged; the autofix rewrites it to the facade/guards predicate.
+- Exemption: `typeof window !== 'undefined'` and custom `typeof` narrowing inside `packages/guards/**` are NOT flagged (D3).
+- Happy path: a raw `/foo/.test(x)` is flagged with a `magic-regexp` suggestion; same construct inside utils is exempt.
+- Regression-parity: every case the old `no-raw-typeof.ts`/`no-raw-regex.ts` caught is still caught (port a sample of their known-flag cases as fixtures), and known false positives they over-flagged are now clean.
+
+**Verification:** `check:ast-grep` runs in all four wiring surfaces; the two regex scripts are gone; parity fixtures pass; repo is clean post-migration.
+
+---
+
+### U7. Introduce `jscpd` — copy-paste / repeated-logic detection
+
+**Goal:** Add token-based duplication detection across `packages/` + `apps/` with a tuned threshold.
+**Requirements:** Catch duplicated logic regardless of naming (Problem Frame #4; user: "repeated logic").
+**Dependencies:** none structural (can build anytime); tuned against the post-U3/U10 tree.
+**Files:**
+- `package.json` (modify — add `jscpd` devDep; add `check:duplication` script)
+- `.jscpd.json` (create — config: globs over `packages/`/`apps/` src, ignore tests/generated/`dist`, set `threshold`, `minTokens`, reporters)
+- `scripts/check-all.ts`, `lefthook.yml`, `.github/workflows/checks.yml` (modify — wire `check:duplication`)
+
+**Approach:** Configure jscpd with a threshold that passes on the post-migration tree (calibrate empirically so it's green at flip time, then ratchet down in follow-ups). Exclude tests, codegen (`**/*.gen.ts`, `src/codegen`), and the ignore set already in `biome.json`.
+
+**Test scenarios:**
+- Happy path: a fixture with two near-identical ~`minTokens` blocks is reported as a clone.
+- Edge: test files and generated files are excluded (a deliberate dup in a `*.test.ts` is not reported).
+- Calibration: `check:duplication` exits 0 on the migrated tree at the chosen threshold (records the baseline so the gate is meaningful, not vacuous).
+
+**Verification:** `check:duplication` runs in the wiring surfaces and is green at the calibrated threshold post-migration; the baseline threshold is recorded in `.jscpd.json` with a comment/doc note.
+
+---
+
+### U8. `no-duplicate-utils` — name-based re-implementation check
+
+**Goal:** Flag home-grown functions whose name matches a `@packrat/utils` export, mirroring `no-duplicate-guards.ts`.
+**Requirements:** Catch copy-paste re-implementation of facade utilities (Problem Frame #4).
+**Dependencies:** U3 (needs the canonical export list).
+**Files:**
+- `scripts/lint/no-duplicate-utils.ts` (create — adapt `no-duplicate-guards.ts`; derive the banned-name set from the `@packrat/utils` manifest/exports rather than a hardcoded list, so it stays in sync)
+- `scripts/check-all.ts`, `lefthook.yml`, `.github/workflows/checks.yml`, `lint:custom` (modify — wire it)
+
+**Approach:** Clone the `no-duplicate-guards.ts` structure (walk `apps/` + `packages/`, skip comment/import lines, regex for declarations). Source the name set from `@packrat/utils`'s exports (or the provenance manifest) so adding a facade export automatically extends the check. Exclude `packages/utils/**` and `packages/checks/**`.
+
+**Patterns to follow:** `scripts/lint/no-duplicate-guards.ts` (near-identical shape).
+
+**Test scenarios:**
+- Happy path: a fixture declaring `const chunk = (...)` outside utils is flagged with a "import from @packrat/utils" message.
+- Edge: a re-export line (`export { chunk } from '@packrat/utils'`) and the definition inside `packages/utils/**` are NOT flagged.
+- Sync: adding a new export to the facade manifest extends the banned set without editing the check (assert via fixture that a newly-listed name is now caught).
+
+**Verification:** `no-duplicate-utils` runs in the wiring surfaces, flags re-implementations, exempts utils/checks, and derives its name set from the facade.
+
+---
+
+### U9. `check-utils-provenance` — manifest sync + priority
+
+**Goal:** A `packages/checks` check that validates the provenance manifest against the facade and enforces the priority order against declared alternatives (D5).
+**Requirements:** Provenance as a real CI check (user decision); priority order enforcement.
+**Dependencies:** U3 (manifest + exports exist).
+**Files:**
+- `packages/checks/src/check-utils-provenance.ts` (create)
+- `packages/checks/package.json` (modify — add `check:provenance` script)
+- `packages/utils/src/provenance.{ts|json}` (manifest; shape decided here)
+- `packages/checks/test/check-utils-provenance.test.ts` (create)
+- `scripts/check-all.ts`, `lefthook.yml`, `.github/workflows/checks.yml` (modify — wire `check:provenance:strict` alongside the existing `check:route-schemas:strict` / `check:casts:strict`)
+
+**Approach (manifest shape decision):** Use a typed TS module (`provenance.ts`) exporting a `Record<string, { source: Lib; alsoIn?: Lib[] }>` rather than a free-form fenced markdown block — utils is a TS package, so a typed object is parse-stable, type-checked, and avoids the markdown-table fragility the dependency-policy plan called out. (The dependency-policy lint parses a fenced JSON block because its data lives in a `.md` doc; here the data lives in code, so a typed module is the lower-friction equivalent.) The check asserts: every facade export has a manifest entry; every manifest entry maps to a real export (no stale rows); `source` is an allowed lib; and `source` is not lower-priority than any lib listed in `alsoIn`.
+
+**Patterns to follow:** `packages/checks/src/check-route-schemas.ts` (strict-mode check shape, `--strict` flag, `bun run --cwd packages/checks` invocation).
+
+**Test scenarios:**
+- Happy path: a manifest in sync with exports, all sources valid and priority-respecting, exits 0.
+- Failure: an export missing from the manifest → exit 1 with the export name.
+- Failure: a stale manifest row referencing a non-existent export → exit 1.
+- Failure: `source: 'lodash'` with `alsoIn: ['radashi']` → exit 1 (lower-priority source despite a higher-priority alternative).
+- Edge: an export legitimately only in lodash (`alsoIn` empty/absent) sourced from lodash → exits 0 (lodash retained for old-school primitives is allowed).
+
+**Verification:** `check:provenance:strict` runs in the wiring surfaces; the four failure modes above are covered by tests; green on the real manifest.
+
+---
+
+### Phase 4 — Migration & activation
+
+### U10. Migrate call sites, remove dead deps, flip checks to blocking
+
+**Goal:** Migrate the remaining raw call sites, remove dead/relocated deps, resolve everything the new checks flag, and add all five layers to the CI-blocking set.
+**Requirements:** "Full migration in this worktree" (user decision); pre-push invariant ("all checks clean, no backlog").
+**Dependencies:** U4, U5, U6, U7, U8, U9.
+**Files:**
+- `packages/analytics/src/core/local-cache.ts` (modify — `tryit` from `@packrat/utils`)
+- `apps/expo/features/pack-templates/components/FeaturedPacksSection.tsx` (modify — radash import → facade)
+- `packages/analytics/package.json`, `apps/expo/package.json`, `packages/api/package.json` (modify — remove now-unused direct `radash` deps; `api`'s is already dead)
+- any sites flagged by ast-grep `no-raw-typeof`/`no-raw-regex`, `no-duplicate-utils`, or `jscpd` above threshold (modify — replace with facade/guards calls)
+- `lefthook.yml`, `scripts/check-all.ts`, `.github/workflows/checks.yml`, root `lint:custom`/`lint:strict` (modify — promote `check:ast-grep`, `check:duplication`, `no-duplicate-utils`, `check:provenance:strict` into the blocking sets; remove the deleted regex-script references)
+- `bun.lock` (regenerated; review diff)
+
+**Approach:** Sequence migration before flip: run each new check, fix what it surfaces (using the U2 findings as the map), confirm green, then add it to `clean-checks` (pre-push), `check-all.ts`, and `checks.yml`. **Coordinate with `2026-05-31-001` dependency-policy plan** — both edit the triad + root `package.json`; rebase triad edits onto whichever lands first to avoid clobbering.
+
+**Execution note:** Migrate-then-gate per check — never add a check to the blocking set while it's red. The pre-push header's "no continue-on-error backlog" invariant must hold at the end.
+
+**Test scenarios:**
+- Integration: full `bun check:all` is green with all five new layers active.
+- Integration: `bun check-types` passes after every call-site migration (no type drift from swapping `radash` → facade).
+- Happy path: the 3 known radash sites import from `@packrat/utils` and behave identically (analytics `tryit` error-tuple behavior unchanged; expo component renders unchanged).
+- Edge: no `radash`/`radashi`/`es-toolkit`/`lodash`/`remeda` direct import remains outside `packages/utils/**` (biome clean); no orphaned dep declarations remain.
+- Regression: existing test suites for `analytics`, `api`, `expo`, `guards`, `config` pass unchanged.
+
+**Verification:** all five enforcement layers are CI-blocking and green; no reach-around imports or dead util-lib deps remain; `bun check:all` and the full test suite pass; the migrated worktree is ready to merge.
+
+---
+
+## Scope Boundaries
+
+**In scope:** `@packrat/utils` facade + subpaths; two-tier guards refactor; five-layer enforcement; one-shot seeding sweep; migration of the 3 radash sites + raw-primitive sites flagged by the new checks; wiring all checks to CI-blocking.
+
+### Deferred to Follow-Up Work
+- **Ratcheting `jscpd` threshold down** over successive PRs after the initial calibrated baseline.
+- **Recurring/scheduled duplication sweep** (user chose one-shot; a committed recurring command was the rejected alternative).
+- **Migrating non-radash hand-rolled utilities** beyond what the sweep + checks surface this round — the facade grows from real usage, not speculation (D4).
+- **`ast-grep` rules for hand-rolled facade equivalents** (`no-handrolled-util.yml` beyond `typeof`/regex) — add as duplication patterns prove worth encoding.
+
+### Outside this effort
+- Turborepo migration (separate in-flight branch) — this work should stay compatible but is not gated on it.
+- The `container_src` / dependency-policy decisions owned by `2026-05-31-001`.
+
+---
+
+## Dependencies / Assumptions
+
+- **Coordination:** `docs/plans/2026-05-31-001-refactor-monorepo-dependency-policy-plan.md` edits the same check-wiring triad and root `package.json`. Expect to rebase triad + catalog edits; the provenance manifest reuses its registry concept (in code form — D5/U9).
+- **Verified (2026-05-31):** 3 real `from 'radash'` sites; `api`'s radash is a dead dep; radashi/es-toolkit/remeda are net-new; biome `noRestrictedImports` is supported; internal packages are unbundled source; `packages/env` subpath-export precedent.
+- **Assumption:** vitest is the test runner (catalog `@vitest/coverage-v8`); new tests follow repo `*.test.ts` conventions and meet existing coverage gates ("test safety is everything").
+- **Assumption (reversible, D6):** the five libs are direct deps of utils, not catalog — flag on review to keep them cataloged.
+
+---
+
+## Verification Strategy
+
+- `bun check:all` green with all five enforcement layers active (master signal).
+- `bun check-types` green throughout (full type safety; never relax flags — fix code/tighten types).
+- Full existing test suites for `analytics`, `api`, `expo`, `guards`, `config` pass unchanged.
+- New tests: facade wrappers + barrel/manifest contract (U3), guards no-regression (U4), each new check's flag/exempt behavior (U6–U9).
+- No reach-around lib imports and no dead util-lib deps remain (biome + grep).
diff --git a/docs/runbooks/etl-pipeline.md b/docs/runbooks/etl-pipeline.md
new file mode 100644
index 0000000000..784525a865
--- /dev/null
+++ b/docs/runbooks/etl-pipeline.md
@@ -0,0 +1,343 @@
+# Catalog ETL Pipeline — Runbook
+
+Operational guide for the Cloudflare Workflows-based catalog ingest pipeline.
+Audience: on-call engineers triaging ETL issues; scraper operators triggering
+new runs; anyone debugging why the catalog isn't updating.
+
+## Architecture at a glance
+
+```
+Scraper → R2 object (packrat-scrapy-bucket)
+                    │
+                    ▼
+POST /api/catalog/etl  ── api-key auth
+                    │
+                    ▼
+chunkCsvForR2  → newline-aligned ChunkSpec[]
+                    │
+                    ▼
+INSERT etl_jobs (status='running', workflow_instance_id)
+                    │
+                    ▼
+env.ETL_WORKFLOW.create(...)  ──► CatalogEtlWorkflow instance
+                                            │
+                              ┌─────────────┴─────────────┐
+                              ▼                           ▼
+                     step.do("chunk-N", ...) × N    (durable, memoized,
+                              │                       per-step retry 3x
+                              ▼                       exp backoff)
+                     step.do("aggregate")
+                              │
+                              ▼
+                     step.do("finalize")  → UPDATE etl_jobs
+                                            SET status='completed'
+```
+
+Two backstops:
+- **CF Cron Trigger** `0 9 * * *` runs the `scheduled` handler, which calls
+  `sweepInvalidItemLogs` to DELETE `invalid_item_logs` rows older than 90
+  days in 10k-row batches.
+- The Workflows dashboard is the **forensic record** for any errored
+  instance — no DLQ table is needed; the dashboard surfaces full step
+  history with stack traces.
+
+## What's the engine?
+
+The producer endpoint accepts `?engine=workflow|queue`. Workflow is the
+default. The queue path is kept during the coexistence window — operators
+can opt back in via `?engine=queue` if the workflow path misbehaves in
+production. Plan: delete the queue path one week after the workflow path
+has been in steady-state production use.
+
+## Triggering an ETL
+
+```bash
+# Via curl (admin API key in $PACKRAT_API_KEY)
+curl -X POST 'https://packrat-api.orange-frost-d665.workers.dev/api/catalog/etl?engine=workflow' \
+  -H "x-api-key: $PACKRAT_API_KEY" \
+  -H 'content-type: application/json' \
+  -d '{
+        "filename": "cotopaxi_2026-05-14T16-54-05.csv",
+        "chunks": ["v2/cotopaxi/cotopaxi_2026-05-14T16-54-05.csv"],
+        "source": "cotopaxi",
+        "scraperRevision": "abc123"
+      }'
+```
+
+Response:
+```json
+{
+  "message": "Catalog ETL workflow triggered",
+  "jobId": "<uuid>",
+  "engine": "workflow",
+  "workflowInstanceId": "cotopaxi-cotopaxi_2026-05-14T16-54-05"
+}
+```
+
+The deterministic `workflowInstanceId` (`${source}-${filenameWithoutExtension}`) means
+duplicate triggers for the same file are rejected by the Workflows runtime
+— safe to retry the curl on network failures.
+
+Note: CF Workflows instance IDs only allow `[a-zA-Z0-9_-]` — the `.csv` extension is
+stripped when building the ID.
+
+## Inspecting a workflow instance
+
+```bash
+# List recent instances
+bunx wrangler workflows instances list packrat-catalog-etl
+
+# Describe one (replace <id> with workflowInstanceId or the UUID)
+bunx wrangler workflows instances describe packrat-catalog-etl <id>
+```
+
+`describe` shows:
+- Top-level status: `queued`, `running`, `paused`, `errored`, or `complete`
+- Each `chunk-N` step's start/end timestamps + output value (rowsProcessed,
+  rowsValid, rowsInvalid per chunk)
+- `aggregate` step result (the canonical totals written to `etl_jobs`)
+- `finalize` step result (status flip to `completed`)
+- For errored instances: full retry history with stack traces per attempt
+
+## Retrying a failed job
+
+```bash
+curl -X POST 'https://packrat-api.orange-frost-d665.workers.dev/api/admin/analytics/catalog/etl/<jobId>/retry' \
+  -H "Authorization: Bearer $ADMIN_JWT"
+```
+
+The retry endpoint:
+1. Looks up the original `etl_jobs` row (requires `status='failed'`)
+2. Re-chunks the source via `chunkCsvForR2` (newline-aligned)
+3. INSERTs a new `etl_jobs` row with a fresh `jobId` and a new
+   `workflowInstanceId` suffixed `-retry-<newJobId>` so duplicate retries
+   don't collide
+4. Calls `env.ETL_WORKFLOW.create(...)` with the chunks
+
+Response:
+```json
+{
+  "success": true,
+  "newJobId": "<uuid>",
+  "objectKey": "v2/cotopaxi/cotopaxi_2026-05-14T16-54-05.csv",
+  "workflowInstanceId": "retry-<newJobId>"
+}
+```
+
+Original job's `etl_jobs` row is left untouched (still `failed`); the new
+row reflects the retry. The new row's `superseded_by_job_id` is set to the
+original `jobId` (with `superseded_at = now()`) so the supersession chain
+is explicit — no manual correlation by `(source, filename)` and timestamp
+is required. Use `GET /admin/analytics/catalog/etl/:jobId` to see the full
+chain for any job.
+
+## Reconciling a job's row count
+
+After an ingest completes, you can compare the R2 source's logical row
+count against `etl_jobs.total_processed`:
+
+```bash
+curl -X POST 'https://packrat-api.orange-frost-d665.workers.dev/api/admin/analytics/catalog/etl/<jobId>/reconcile' \
+  -H "Authorization: Bearer $ADMIN_JWT"
+```
+
+The endpoint reads the entire R2 source, parses it with `csv-parse` (which
+correctly handles quoted multi-line fields, unlike raw `\n` counting), and
+writes the result to `etl_jobs.verified_row_count` + `etl_jobs.verified_at`.
+
+Response:
+```json
+{
+  "success": true,
+  "jobId": "<uuid>",
+  "expectedRowCount": 50100,
+  "actualRowCount": 50100,
+  "delta": 0
+}
+```
+
+A non-zero `delta` indicates data drift — either the source was modified
+since ingest, or the workflow dropped rows. Investigate before re-ingesting.
+
+For very large source files (>200 MB) this endpoint may exceed the fetch
+budget. Async-via-workflow is a documented follow-up.
+
+## The 7-job historical recovery procedure
+
+Seven jobs from 2026-05-14 were falsely marked `failed` by the old
+wall-clock-based stuck-job sweep. After this PR ships and is deployed:
+
+```sql
+-- List the affected jobs
+SELECT id, source, filename, total_processed, started_at, completed_at
+FROM etl_jobs
+WHERE status = 'failed'
+  AND completed_at = '2026-05-14T16:24:04.470Z';
+```
+
+For each `jobId` returned:
+
+```bash
+curl -X POST "https://packrat-api.orange-frost-d665.workers.dev/api/admin/analytics/catalog/etl/${jobId}/retry" \
+  -H "Authorization: Bearer $ADMIN_JWT"
+```
+
+Workflow instances will appear in the dashboard with names like
+`evo-evo_2026-04-27T03-25-18.csv-retry-<newJobId>`. Watch each to
+completion. Original `etl_jobs` rows stay `failed` for the audit trail;
+new rows reflect the successful re-ingest.
+
+If a source file has been overwritten since 2026-05-14, the retry will
+re-ingest the **current** content under the old `(source, filename)` —
+not the original. This is acceptable for the 7-job recovery (we want the
+latest catalog state) but operators should verify R2 contents before
+retrying if they're worried about historical accuracy. ETag-based
+fail-closed verification is a follow-up PR.
+
+## DLQ / forensic record
+
+There is no DLQ table. The CF Workflows dashboard is the forensic record:
+
+```bash
+# Errored instances
+bunx wrangler workflows instances list packrat-catalog-etl \
+  --status=errored
+```
+
+For each errored instance, `describe` shows the failed step, the
+exception message, and the retry attempt history. Workflows instance
+retention is per the CF account settings (default unlimited on paid
+plan).
+
+For DB-side history: the `etl_jobs` table retains all rows indefinitely.
+A failed `etl_jobs` row is the durable record that operators see in the
+admin UI; the linked workflow instance is the executable log behind it.
+
+## Invalid item logs retention
+
+`invalid_item_logs` is swept daily at 09:00 UTC by the `scheduled`
+handler in `packages/api/src/index.ts`. Default retention is 90 days.
+The sweep loops in 10k-row batches and caps at 100 iterations (1M rows
+per run). If the cap is hit, the next run picks up the remainder.
+
+To override defaults, edit `packages/api/src/services/retention/invalidLogRetention.ts`
+constants (no env-var override yet).
+
+To manually trigger a retention sweep (dev only):
+
+```bash
+bunx wrangler dev --test-scheduled
+# In another terminal:
+curl 'http://localhost:8787/__scheduled?cron=0+9+*+*+*'
+```
+
+## Draining / disabling the queue path
+
+After the workflow path bakes in production and the queue path is
+scheduled for removal:
+
+```bash
+# Check that no consumers are reading from the old queue
+bunx wrangler queues info packrat-etl-queue
+
+# Remove the consumer binding — NOTE: this does NOT drain messages already
+# sitting in the queue. Wait for the queue depth to reach 0 (visible in the
+# Cloudflare dashboard) before removing the consumer, or messages will be
+# lost. Only then is it safe to remove:
+bunx wrangler queues consumer remove packrat-etl-queue packrat-api
+```
+
+Then the queue path removal PR (follow-up to this work) deletes:
+- `packages/api/src/services/etl/queue.ts`
+- `packages/api/src/services/etl/processCatalogEtl.ts`
+- The `?engine=queue` branch in `packages/api/src/routes/catalog/index.ts`
+- The `packrat-etl-queue` producer + consumer entries in `wrangler.jsonc`
+- The legacy `processQueueBatch` arm in the `queue()` handler at
+  `packages/api/src/index.ts`
+- The `POST /admin/etl/reset-stuck` endpoint (the wall-clock sweep that
+  caused the 7-job false-failure incident; no longer needed with
+  Workflows owning instance lifecycle)
+
+## Interpreting admin dashboard fields
+
+`admin.packratai.com`'s catalog ETL page reads from `etl_jobs`. Field
+meanings under the Workflows architecture:
+
+| Field | Meaning |
+|---|---|
+| `status` | Mirrors the workflow's terminal state. `completed` = `finalize` step succeeded. `failed` = workflow errored (all retries exhausted). `running` = workflow still active. |
+| `total_processed`, `total_valid`, `total_invalid` | Written by the workflow's `aggregate` step. These are authoritative for the workflow run — any drift from per-row counts during processing is overridden by the aggregate write. |
+| `workflow_instance_id` | NULL for legacy queue-path rows; set for workflow-path rows. Use this to find the instance in the CF dashboard. |
+| `total_embedding_failures` | Number of SKUs upserted without embeddings because `generateManyEmbeddings` threw. Non-zero indicates degradation. The catalog items themselves are present; embeddings backfill happens via the existing `/admin/embeddings` workflow. |
+| `verified_at`, `verified_row_count` | NULL until an operator runs the reconcile endpoint. When set, `verified_row_count` is the R2 source's logical CSV row count; compare to `total_processed` to detect drift. |
+| `success_rate` (computed) | Existing field — `total_valid / total_processed`. Note that a job with `status='failed'` can still show 100% if all processed rows were valid before the failure; the field is per-row, not per-job. |
+
+## Accepted limitations
+
+- **No soft-delete / discontinued-item reconciliation.** When a catalog
+  item disappears from the source CSV, its row in `catalog_items` keeps
+  the last `availability` value. The catalog grows monotonically.
+  Reconciliation strategy not in scope; documented in audit P3 #3.
+- **`success_rate` on a `failed` job can read 100%.** Dashboard quirk —
+  the field is per-row, not per-job. A job that processed 400 rows
+  successfully then errored on chunk 5 shows `success_rate: 100`
+  because the 400 were all valid. The fix is documenting this above and
+  in the admin UI tooltip (admin app PR).
+- **Reconcile endpoint is synchronous.** Very large source files
+  (>200 MB) may exceed the fetch budget. Async-via-workflow path is a
+  documented follow-up.
+- **ETag fail-closed on repair-from-scratch (not plain retry).** The
+  `repair-from-scratch` endpoint compares the stored `source_etag` against
+  `r2.head().etag` and returns 409 on mismatch; pass `?force=true` to
+  override. The plain `retry` endpoint does not enforce ETag checks — if the
+  R2 source has been overwritten, retry re-ingests the new content. Use
+  repair-from-scratch when historical accuracy matters.
+- **Embedding failures still cost API calls on retry.** Workflows
+  memoizes step results, so a successful chunk step doesn't re-fire its
+  embedding call on a downstream failure. But a chunk that fails AT the
+  embedding call (and is then retried) calls the embedding API again.
+  Bounded by the per-step retry limit (3); cost is bounded.
+
+## Historical recoveries appendix
+
+Document each one-off recovery here for the audit trail.
+
+### 2026-05-14 false-failures (planned, post-merge)
+
+7 jobs from 2026-05-14T16:24:04.470Z were marked failed by the old
+wall-clock sweep mid-flight. Job IDs and recovery procedure documented
+above. To be executed after this PR deploys to production.
+
+## Sentry observability
+
+`@sentry/cloudflare` wraps the worker default export via `withSentry()` and
+the `CatalogEtlWorkflow` class via `instrumentWorkflowWithSentry()` —
+configured in `packages/api/src/index.ts`. Initialization uses
+`env.SENTRY_DSN`, `env.ENVIRONMENT`, and `env.CF_VERSION_METADATA.id`
+(release tag) with a 10% trace sample rate.
+
+The structured logger (`packages/api/src/utils/logger.ts`) forwards:
+- `logger.info(event, ctx)` → `Sentry.addBreadcrumb(level=info)`
+- `logger.warn(event, ctx)` → `Sentry.addBreadcrumb(level=warning)`
+- `logger.error(event, { err })` → `Sentry.captureException(err)` with `event` + ctx fields as tags
+- `logger.error(event)` without err → `Sentry.captureMessage(event, level=error)`
+
+ctx fields become Sentry tags (strings/numbers/booleans) or extras (objects).
+
+Source maps:
+- `upload_source_maps: true` in `wrangler.jsonc` uploads sourcemaps to
+  Cloudflare on every `wrangler deploy` — unminified stack traces in
+  `wrangler tail` and the Workers dashboard
+- For Sentry-side symbolication (unminified frames in the Sentry UI),
+  run `bunx @sentry/cli sourcemaps upload --release=$(git rev-parse HEAD) packages/api/dist`
+  after deploy. Not wired into CI because there's no automated deploy
+  pipeline today; run manually post-deploy until that changes.
+
+## References
+
+- [Audit (2026-05-16)](../audits/2026-05-16-etl-audit.md) — the source-of-truth list of pre-migration issues
+- [Active plan](../plans/2026-05-20-001-fix-etl-pipeline-workflows-migration-plan.md) — the Workflows migration plan
+- [Superseded plan](../plans/2026-05-19-001-fix-etl-pipeline-audit-remediation-plan.md) — the original Queues + outbox attempt (why we pivoted)
+- [Cloudflare Workflows docs](https://developers.cloudflare.com/workflows/)
+- [Cloudflare Workflows JS API](https://developers.cloudflare.com/workflows/build/workers-api/)
+- [Sentry on Cloudflare Workers](https://docs.sentry.io/platforms/javascript/guides/cloudflare/)
diff --git a/docs/solutions/ui-bugs/android-textinput-keyboard-focus-loss.md b/docs/solutions/ui-bugs/android-textinput-keyboard-focus-loss.md
index 7af27b181c..1933e67f11 100644
--- a/docs/solutions/ui-bugs/android-textinput-keyboard-focus-loss.md
+++ b/docs/solutions/ui-bugs/android-textinput-keyboard-focus-loss.md
@@ -325,7 +325,7 @@ const inputRef = useRef(null);
 ## Cross References
 
 - **Architecture**: [CLAUDE.md](../../../CLAUDE.md#L79-L96) - Mobile app architecture patterns
-- **Testing**: [TESTING.md](../../../TESTING.md#L57-L61) - Mobile component testing patterns
+- **Testing**: [testing.md](../../testing.md) - Mobile component testing patterns
 - **Component Patterns**: Enhanced component pattern can be applied to other third-party UI components
 
 ## Verification
diff --git a/docs/testing.md b/docs/testing.md
new file mode 100644
index 0000000000..4d53ad8a37
--- /dev/null
+++ b/docs/testing.md
@@ -0,0 +1,315 @@
+# PackRat Testing Guide
+
+PackRat uses **Vitest** across every workspace that runs tests. This document is the source of truth for:
+
+- the **per-workspace coverage thresholds** that each Vitest config enforces
+- the **coverage ratchet** that gates PRs in CI against regression
+- the **assertion-strength lint** that catches coverage theater
+- per-pattern testing conventions for services, fetch mocking, and pure utilities
+
+The current numbers below reflect the state of the configs on `main`. The policy that produced them is tracked in `docs/plans/2026-05-19-001-chore-coverage-ratchet-and-quality-gates-plan.md` (and its 2026-05-17 predecessor).
+
+---
+
+## Coverage Thresholds — Two Layers
+
+PackRat gates coverage at **two layers** that fail builds for different reasons:
+
+1. **Vitest per-config thresholds** (declared in each workspace's `vitest.config.ts` / `vitest.unit.config.ts`) fail that workspace's coverage run when *its own* numbers drop below the floor.
+2. **The coverage ratchet** (`scripts/lint/coverage-ratchet.ts` + `coverage-baselines.json`) fails the build when *any* tracked workspace drops below the baseline recorded for it on the last green `main`. The ratchet defends the threshold itself — if a PR lowers a Vitest threshold and the coverage drops accordingly, the Vitest gate passes but the ratchet does not.
+
+Current per-workspace thresholds (all four metrics: lines / branches / functions / statements):
+
+| Workspace | Lines | Branches | Functions | Statements |
+|---|---:|---:|---:|---:|
+| `packages/api` (unit suite) | 95 | 92 | 97 | 95 |
+| `apps/expo` | 95 | 92 | 97 | 95 |
+| `packages/mcp` | 95 | 90 | 95 | 95 |
+| `packages/analytics` | 80 | 80 | 85 | 80 |
+| `packages/overpass` | 80 | 70 | 80 | 80 |
+| `packages/units` | 100 | 100 | 100 | 100 |
+
+`packages/api` integration tests (the `@cloudflare/vitest-pool-workers` suite in `vitest.config.ts`) are **not** counted toward coverage. V8 coverage is unsupported under the Workers pool and the Istanbul path has an open upstream regression. The unit suite (`vitest.unit.config.ts`) is the coverage source of truth for that workspace. Integration tests still run in `api-tests.yml`.
+
+Untracked (no coverage threshold today): `apps/{admin,trails,web,landing,guides}`, `packages/{cli,osm-db,osm-import,web-ui,api-client,ui,guards,env,app,checks,config}`. These are deferred to follow-up plans.
+
+---
+
+## Coverage Ratchet
+
+Every PR is gated by a ratchet that fails CI if any workspace's coverage drops below the baseline in `coverage-baselines.json` (committed at the repo root).
+
+```bash
+# Local check — reads each workspace's coverage/[unit/]coverage-summary.json
+# and compares to coverage-baselines.json. Exits 1 on any regression.
+bun check:coverage
+```
+
+On a green push to `main`, the consolidated coverage workflow (deferred to a follow-up plan) auto-commits any baseline improvements back to `coverage-baselines.json` via:
+
+```bash
+bun check:coverage:update
+```
+
+The baseline only ever moves up. There is no manual edit step in the normal flow.
+
+To run coverage for a single workspace:
+
+```bash
+bun run --cwd packages/api test:unit:coverage
+bun run --cwd apps/expo test:coverage
+bun run --cwd packages/mcp test --coverage
+bun run --cwd packages/analytics test --coverage
+bun run --cwd packages/overpass test --coverage
+bun run --cwd packages/units test --coverage
+```
+
+To run the unit suite for the scripts themselves:
+
+```bash
+bun test:scripts
+```
+
+When a workspace's coverage genuinely improves, the ratchet's output reports the improvement and prints what the baseline-update script would commit — but day-to-day you don't apply it by hand: CI does it on merge to `main`.
+
+---
+
+## Assertion-Strength Lint
+
+`scripts/lint/no-weak-assertions.ts` walks every `*.test.ts` / `*.test.tsx` file under `apps/*` and `packages/*` and flags four coverage-theater patterns:
+
+| Rule | Flags |
+|---|---|
+| `assertion-free-test` | `it(...)` / `test(...)` blocks with zero `expect(...)` calls. Helper assertions (any call whose name starts with `expect`, e.g. `expectUnauthorized(res)`, `expectJsonResponse(res)`) count as assertions and prevent this rule from firing. |
+| `only-tobedefined` | `it(...)` blocks whose only assertions are `.toBeDefined()`, `.toBeTruthy()`, `.toBeFalsy()`, `.not.toBeUndefined()`, or `.not.toBeNull()`. **`.toBeUndefined()` and `.toBeNull()` alone are NOT flagged** — they assert specific return values. |
+| `bare-tohavebeencalled` | `.toHaveBeenCalled()` without a matching `.toHaveBeenCalledWith(...)` or `.toHaveBeenCalledTimes(N)` in the same block. |
+| `large-snapshot` | `toMatchInlineSnapshot(...)` body > 50 lines. |
+
+Run with:
+
+```bash
+bun lint:weak-assertions
+```
+
+File-level escape hatch: `// no-weak-assertions: disable` in the first 5 lines of a file skips the entire file. Use sparingly — grandfathered tests only.
+
+---
+
+## Test Patterns
+
+### Pattern 1 — Service tests with mocked dependencies
+
+```ts
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { CatalogService } from '../catalogService';
+import * as embeddingService from '@packrat/api/services/embeddingService';
+
+vi.mock('@packrat/api/db', () => ({
+  createDb: vi.fn(),
+  createDbClient: vi.fn(),
+}));
+
+vi.mock('@packrat/api/services/embeddingService', () => ({
+  generateEmbedding: vi.fn(),
+  generateManyEmbeddings: vi.fn(),
+}));
+
+describe('CatalogService', () => {
+  let service: CatalogService;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    service = new CatalogService(makeEnv(), false);
+  });
+
+  describe('vectorSearch', () => {
+    beforeEach(() => {
+      vi.mocked(embeddingService.generateEmbedding).mockResolvedValue(
+        new Array(1536).fill(0.1),
+      );
+    });
+
+    it('returns empty result for empty query string', async () => {
+      const result = await service.vectorSearch('', 10, 0);
+      expect(result).toEqual({
+        items: [],
+        total: 0,
+        limit: 10,
+        offset: 0,
+        nextOffset: 10,
+      });
+      expect(embeddingService.generateEmbedding).not.toHaveBeenCalled();
+    });
+  });
+});
+```
+
+Reference: `packages/api/src/services/__tests__/catalogService.test.ts`
+
+Key points:
+- `vi.mock()` for module-level mocks (hoisted to the top of the file).
+- `import * as service` then `vi.mocked(service.fn)` for type-safe mock assertions.
+- `vi.clearAllMocks()` in `beforeEach()` for test isolation.
+
+### Pattern 2 — API service tests with fetch mocking
+
+```ts
+beforeEach(() => {
+  vi.clearAllMocks();
+  fetchMock = vi.fn();
+  global.fetch = fetchMock;
+});
+
+it('returns formatted weather data for valid location', async () => {
+  fetchMock.mockResolvedValue({
+    ok: true,
+    json: async () => ({ main: { temp: 72.5, humidity: 65 }, weather: [{ main: 'Clear' }] }),
+  });
+  const result = await service.getWeatherForLocation('San Francisco');
+  expect(result.temperature).toBe(73);
+  expect(result.conditions).toBe('Clear');
+});
+```
+
+Reference: `packages/api/src/services/__tests__/weatherService.test.ts`
+
+### Pattern 3 — Pure utility function tests
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { convertToGrams } from '../convertToGrams';
+
+describe('convertToGrams', () => {
+  describe('metric conversions', () => {
+    it('returns same value for grams', () => {
+      expect(convertToGrams(100, 'g')).toBe(100);
+      expect(convertToGrams(0, 'g')).toBe(0);
+    });
+
+    it('converts kilograms to grams correctly', () => {
+      expect(convertToGrams(1, 'kg')).toBe(1000);
+      expect(convertToGrams(2.5, 'kg')).toBe(2500);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('handles zero weight', () => {
+      expect(convertToGrams(0, 'kg')).toBe(0);
+    });
+
+    it('returns original value for unknown units', () => {
+      expect(convertToGrams(100, 'invalid')).toBe(100);
+    });
+  });
+});
+```
+
+Reference: `apps/expo/features/packs/utils/__tests__/convertToGrams.test.ts`
+
+Floating-point comparisons:
+
+```ts
+// Avoid exact equality for floats
+expect(convertToGrams(1, 'oz')).toBeCloseTo(28.3495, 4);
+```
+
+### Pattern 4 — Integration tests (`packages/api/test/*.test.ts`)
+
+Run with `bun test` from `packages/api/`. Requires Docker (Postgres + neon-wsproxy via `docker-compose.test.yml`). Auth helpers live in `packages/api/test/utils/test-helpers.ts` — use `apiWithAuth`, `apiWithAdmin`, `apiWithApiKey`, never construct sessions by hand.
+
+Test fixtures must seed users through `userService.createUser`. Do not write new integration tests that `db.insert(users).values(...)` directly.
+
+---
+
+## What to Test (Priority Order)
+
+For every feature-bearing implementation unit, include scenarios from each category that applies:
+
+1. **Happy path** — core functionality with expected inputs and outputs.
+2. **Edge cases** — boundary values, empty inputs, nullish states, concurrent access.
+3. **Error paths** — invalid input, downstream service failures, timeout behavior, permission denials.
+4. **Integration** — behaviors that mocks alone will not prove (callback chains, middleware, multi-layer interactions).
+
+Avoid testing:
+- Third-party library internals.
+- Pure getters/setters with no logic.
+- Generated code (drizzle migrations, OpenAPI types).
+- Configuration files.
+- Pure type definitions.
+
+---
+
+## Commands
+
+```bash
+# Per-workspace coverage
+bun test:api:unit         # packages/api unit suite (Node env, all deps mocked)
+bun test:expo             # apps/expo pure-TS tests
+bun test:mcp              # packages/mcp
+bun run --cwd packages/units test
+bun run --cwd packages/overpass test
+bun run --cwd packages/analytics test
+
+# Integration (requires Docker)
+bun run --cwd packages/api test     # full pool-workers integration suite
+
+# Coverage gates
+bun check:coverage         # ratchet against coverage-baselines.json
+bun lint:weak-assertions   # custom lint over test files
+
+# Scripts test suite (ratchet + lint analyzer)
+bun test:scripts
+```
+
+Coverage reports for each workspace:
+- `packages/api/coverage/unit/index.html`
+- `apps/expo/coverage/unit/index.html`
+- `packages/mcp/coverage/index.html`
+- `packages/analytics/coverage/index.html`
+- `packages/overpass/coverage/index.html`
+- `packages/units/coverage/index.html`
+
+---
+
+## Troubleshooting
+
+### "Cannot access before initialization" in test files
+
+`vi.mock()` calls are hoisted to the top of the file by Vitest. Variables declared after the hoisted mock cannot be referenced inside it.
+
+```ts
+// Won't work
+const mockFn = vi.fn();
+vi.mock('./module', () => ({ fn: mockFn }));
+
+// Works
+vi.mock('./module', () => ({ fn: vi.fn() }));
+import * as module from './module';
+// Use vi.mocked(module.fn) inside tests
+```
+
+### Mock not resetting between tests
+
+Always call `vi.clearAllMocks()` in `beforeEach()`. Without it, call histories leak across tests.
+
+### Floating-point precision errors
+
+```ts
+expect(0.1 + 0.2).toBeCloseTo(0.3, 10);  // 10 decimal places
+```
+
+### Coverage ratchet fails locally but passes in CI
+
+Coverage outputs are workspace-local. Make sure you ran `--coverage` for the workspace that's failing — the ratchet treats a missing `coverage-summary.json` as a regression on purpose (silent skipping is exactly the mode the gate exists to prevent).
+
+### Lint flags a legitimate test as `assertion-free-test`
+
+Helpers whose names start with `expect` count as assertions. If your helper is named differently (e.g., `assertResponseShape(res)`), the lint will not see it. Either rename to `expectShape(res)` or add the file-level `// no-weak-assertions: disable` comment.
+
+---
+
+## Resources
+
+- [Vitest Documentation](https://vitest.dev/)
+- [Cloudflare Vitest pool — known issues](https://developers.cloudflare.com/workers/testing/vitest-integration/known-issues/) (why integration tests are not coverage-instrumented)
+- The plan that established the ratchet + lint policy: `docs/plans/2026-05-19-001-chore-coverage-ratchet-and-quality-gates-plan.md`
diff --git a/docs/utils-policy.md b/docs/utils-policy.md
new file mode 100644
index 0000000000..25872fd8be
--- /dev/null
+++ b/docs/utils-policy.md
@@ -0,0 +1,66 @@
+# `@packrat/utils` — Utility Policy
+
+`@packrat/utils` is the single, curated, type-safe home for general-purpose
+utilities in the monorepo. Type **narrowing / guards** live in
+`@packrat/guards`, not here. This doc is the rule a future maintainer (or agent)
+applies without archaeology.
+
+## The rule
+
+1. **Never hand-roll a utility that a blessed lib already provides.** Import it
+   from `@packrat/utils` (or add it to the facade). Re-implementing a facade
+   export is caught by `no-duplicate-utils`.
+2. **Never import the underlying libs directly** outside `packages/utils`.
+   `radashi`, `radash`, `es-toolkit`, `lodash`, and `remeda` are banned
+   everywhere else by Biome's `noRestrictedImports`. `@packrat/utils` is the
+   only package allowed to reach them.
+3. **Never raw `JSON.parse` / `JSON.stringify`.** Use `safeJsonParse` /
+   `safeJsonStringify` (or `stableJsonStringify`) from `@packrat/utils/json`. Enforced by
+   the `no-raw-json` ast-grep rule.
+
+## Source priority (soft)
+
+When more than one lib provides a function, prefer them in this order — but the
+real tiebreaker is **best types + has-the-function**, not rigid rank:
+
+1. **radashi** — TS-native, the maintained radash fork; the default source.
+2. **radash** — legacy; only for parity gaps radashi hasn't filled.
+3. **es-toolkit** — TS-native, tree-shakeable; chosen when it has a function or
+   capability the higher-priority libs lack (e.g. `round` with precision,
+   `sumBy`/`meanBy`/`maxBy`/`minBy`, `chunk`).
+4. **lodash** — kept available for old-school primitives the modern libs dropped.
+   _Currently sources no first-wave export_ (radashi covers `toFloat`/`toInt`);
+   enrolled so it's there the moment a lodash-only need appears.
+5. **remeda** — TS-native dataLast; the composition primitive (`pipe`).
+
+A deliberate lower-priority pick is legal **only when recorded** in the
+provenance manifest with a `reason` (see below). `round` is the current example.
+
+## Re-export vs wrap
+
+- **Default: thin re-export.** Most exports are a one-line `export { x } from 'lib'`.
+- **Wrap only when it earns it:** to normalize to repo conventions (single-object
+  args for Biome `useMaxParams: 2`, consistent naming) or to compose a primitive
+  the libs lack. The `json` helpers are the current wrap/compose example
+  (configured stringifiers + a typed `destr` wrapper).
+- Do **not** add speculative exports. The surface grows from real usage and the
+  duplication the sweep / `jscpd` surface (`docs/utils-sweep-findings.md`).
+
+## Provenance contract
+
+`src/provenance.ts` records, per export: `{ source, alsoIn?, reason? }`.
+`check-utils-provenance` (in `packages/checks`) enforces:
+
+- every barrel export has exactly one manifest entry, and vice-versa (no stale rows);
+- `source` is a known lib;
+- if any `alsoIn` lib outranks `source` in `LIB_PRIORITY`, `reason` is non-empty.
+
+Adding or removing an export means updating the manifest in the same change — the
+check fails CI otherwise.
+
+## Organization
+
+One barrel (`@packrat/utils`) plus category subpaths: `@packrat/utils/array`,
+`/object`, `/string`, `/async`, `/fn`, `/math`, `/json`. The root barrel
+re-exports every category. Import from the root or a subpath — both resolve to
+the same implementation.
diff --git a/docs/utils-sweep-findings.md b/docs/utils-sweep-findings.md
new file mode 100644
index 0000000000..01ca7baae2
--- /dev/null
+++ b/docs/utils-sweep-findings.md
@@ -0,0 +1,137 @@
+# @packrat/utils Sweep Findings (U2)
+
+Read-only sweep of `packages/` and `apps/` (excluding node_modules, dist, build, .next,
+.expo, *.gen.ts, src/codegen, test files). Goal: seed the curated `@packrat/utils` facade.
+
+## Summary
+
+- **~9 candidate exports** identified, **4 meaningful duplication clusters**, **~25 raw-primitive sites**.
+- Duplication is **moderate, not heavy**. The single highest-value targets are:
+  `capitalize` / `title` (string), `group` (array), `sum`/`sumBy` (math), `sleep` (async),
+  `unique` (array), `clamp` (math).
+- Most "debounce/throttle/slugify" hits are **already library-backed** (`use-debounce`,
+  `slugify`, Reanimated's `clamp`) — do NOT re-implement those; they are not migration targets.
+- Weight conversion (`toGrams`/`fromGrams`/`convertToGrams`) is **domain logic with its own
+  home (`packages/units`)** — explicitly OUT of scope for `@packrat/utils`. See Notes.
+- **Recommended first-wave facade surface (ship in U3):**
+  `string`: `capitalize`, `title`; `array`: `group`, `unique`, `sort`;
+  `math`: `sum`, `sumBy`, `clamp`, `round`; `async`: `sleep`, `tryit`.
+
+## Recommended facade exports (prioritized)
+
+| Export | Category | Best source lib | Why this lib | Call sites / duplication count |
+|--------|----------|-----------------|--------------|-------------------------------|
+| `capitalize` | string | **radashi** | TS-native, top priority, has it; matches `s[0].toUpperCase()+s.slice(1)` exactly | ~5 raw sites |
+| `title` (Title Case) | string | **radashi** | radashi `title` handles word-splitting + capitalizing; collapses the `.split().map(cap).join()` idiom | ~6 raw sites (the multi-word capitalizers) |
+| `group` (groupBy) | array | **radashi** | TS-native, returns `Partial<Record<K,T[]>>`, priority #1; es-toolkit `groupBy` is a fine alt | 1 hand-rolled (`gear-inventory.tsx`) + several DB `.groupBy` (N/A) |
+| `unique` (dedupe) | array | **radashi** | priority #1, supports key fn; replaces `[...new Set]` / `Array.from(new Set)` | 4 raw sites |
+| `sum` | math | **radashi** | priority #1, has `sum(arr, fn?)`; covers most `.reduce((a,b)=>a+b,0)` | ~10 raw `reduce`-sum sites |
+| `sumBy` | math | **es-toolkit** | radashi `sum` takes a mapper but `sumBy` reads cleaner for `sum + item.weight*qty`; es-toolkit is TS-native #3, radashi has no separate `sumBy` | subset of the sum sites |
+| `clamp` | math | **radashi** | priority #1 has `clamp(n,min,max)`; replaces `Math.min(Math.max(...))` | 2 raw sites (catalog/packs `validLimit`) |
+| `round` (to precision) | math | **es-toolkit** | `round(n, precision)`; radashi has no precision-rounding. Replaces `Math.round(x*100)/100` | several (analytics, compute-pack) — see Notes |
+| `sleep` | async | **radashi** | priority #1, `sleep(ms)`; replaces `new Promise(r=>setTimeout(r,ms))` | ~6 raw sites |
+| `tryit` | async | **radashi** | already in use; keep as facade re-export (see Known sites) | 1 site |
+
+## Duplication clusters
+
+1. **Title-case a hyphen/space-delimited string** — `str.split(...).map(w => w.charAt(0).toUpperCase()+w.slice(1)).join(...)`
+   - `apps/expo/features/guides/hooks/useGuideCategories.ts:18-19`
+   - `apps/expo/features/guides/screens/GuideDetailScreen.tsx:62`
+   - `apps/expo/features/guides/components/GuideCard.tsx:35`
+   - `apps/expo/features/ai/components/GuidesRAGGenerativeUI.tsx:79`
+   - `apps/web/components/screens/gear-inventory-screen.tsx:12-13`
+   - **Collapses to:** `title(str)` (radashi) — or `capitalize` per-word if split is needed.
+
+2. **Single-word capitalize** — `category.charAt(0).toUpperCase() + category.slice(1)`
+   - `apps/guides/components/footer.tsx:63`
+   - `apps/guides/components/header.tsx:85,156`
+   - `apps/guides/components/filterable-guides.tsx:35`
+   - **Collapses to:** `capitalize(str)` (radashi).
+
+3. **Sum a numeric field over a list** — `arr.reduce((sum,x)=>sum + x.field, 0)`
+   - `apps/web/components/screens/packs-screen.tsx:350,426`
+   - `apps/web/components/screens/shopping-list-screen.tsx:84,85`
+   - `apps/expo/features/packs/hooks/usePackWeightAnalysis.ts:10,18` (with a unit-convert mapper)
+   - `apps/admin/components/dashboard/dashboard-content.tsx:31,32`
+   - `packages/api/src/utils/compute-pack.ts:110`
+   - **Collapses to:** `sum(arr, x => x.field)` (radashi) or `sumBy` (es-toolkit).
+
+4. **Dedupe an array** — `[...new Set(...)]` / `Array.from(new Set(...))`
+   - `apps/guides/scripts/build-content.ts:58`
+   - `apps/expo/app/(app)/ai-chat.tsx:241`
+   - `packages/api/src/routes/packs/index.ts:544`
+   - `packages/api/src/routes/catalog/index.ts:147` (`Array.from(new Set(ids))`)
+   - **Collapses to:** `unique(arr)` (radashi).
+
+## Raw-primitive sites
+
+| Site | Pattern | Canonical facade replacement |
+|------|---------|------------------------------|
+| `apps/guides/scripts/build-content.ts:58` | `[...new Set(...flatMap)]` | `unique(...)` |
+| `apps/expo/app/(app)/ai-chat.tsx:241` | `Array.from(new Set(map))` | `unique(...)` |
+| `packages/api/src/routes/packs/index.ts:544` | `Array.from(new Set(map.filter))` | `unique(...)` |
+| `packages/api/src/routes/catalog/index.ts:147` | `Array.from(new Set(ids))` | `unique(ids)` |
+| `apps/expo/app/(app)/gear-inventory.tsx:51-62` | manual `reduce` groupBy w/ `assertDefined` | `group(items, i => i.category ?? 'Other')` |
+| `packages/api/src/routes/catalog/index.ts:545` | `Math.min(Math.max(limit,1),20)` | `clamp(limit, 1, 20)` |
+| `packages/api/src/routes/packs/index.ts:882` | `Math.min(Math.max(limit,1),20)` | `clamp(limit, 1, 20)` |
+| `apps/web/lib/data.ts:67` | `const delay = ms => new Promise(r=>setTimeout(r,ms))` | `sleep(ms)` |
+| `apps/guides/lib/enhanceGuideContent.ts:208`, `apps/guides/scripts/enhance-content.ts:305`, `apps/guides/scripts/generate-content.ts:482`, `packages/api/container_src/server.ts:268,271` | `await new Promise(r=>setTimeout(r,N))` | `sleep(N)` |
+| `apps/web/components/screens/profile-screen.tsx:69` | `packs.reduce((a,p)=>a+p.baseWeight,0)/packs.length` | `mean(packs, p=>p.baseWeight)` (radashi) / `meanBy` (es-toolkit) |
+| sum-reduce sites in cluster 3 | `reduce((s,x)=>s+x.f,0)` | `sum(arr, x=>x.f)` / `sumBy` |
+| capitalize/title sites in clusters 1-2 | `charAt(0).toUpperCase()...` | `capitalize` / `title` |
+| `packages/api/src/utils/compute-pack.ts:111`, `packages/analytics/src/core/spec-parser.ts:85,101`, `entity-resolver.ts:312` | `Math.round(x*100)/100` | `round(x, 2)` (es-toolkit) — see Notes (judgment call) |
+
+**Object map-building (`Object.fromEntries(arr.map(r => [k, v]))`)** — many sites in
+`packages/api/src/routes/admin/analytics/platform.ts:77-79,154-156`, `feed/index.ts:76,78,305`,
+`apps/admin/components/analytics/*.tsx`. These are lookup-map builds. radashi `objectify(arr, k, v)`
+is a clean replacement but the inline `Object.fromEntries` is already terse and type-safe; **low
+priority** — recommend leaving unless touched.
+
+## Known radash sites (migration map for U10/U4)
+
+| Site | Symbol | Replacement |
+|------|--------|-------------|
+| `packages/analytics/src/core/local-cache.ts:12,605` | `tryit` (radash) | Re-export `tryit` from `@packrat/utils/async` (radashi `tryit`). Swap import to `@packrat/utils`. |
+| `apps/expo/features/pack-templates/components/FeaturedPacksSection.tsx:5,58` | `isArray` (radash) | **Guard, not util.** Migrate to `@packrat/guards` `isArray` (U4). Not a `@packrat/utils` export. |
+| `packages/guides/src/index.ts:25` | barrel re-export from `radash` | Handled in **U4** (guards barrel). Noted only. NOTE: actual path is `packages/guards/src/index.ts:25` (no `packages/guides` package exists). |
+
+These are the only three `radash`/`radashi` import sites in non-test source. Confirmed via grep
+for `from 'radash'` / `from 'radashi'`.
+
+## Notes / judgment calls
+
+- **Weight conversion is OUT of scope.** `toGrams`/`fromGrams`/`gramsToLbs`
+  (`packages/app/src/shared/lib/weight.ts`), `convertToGrams`/`convertFromGrams`
+  (`apps/expo/features/packs/utils/`), and duplicates in `apps/web/lib/data.ts`,
+  `packages/api/src/utils/weight.ts`, `packages/analytics/src/core/spec-parser.ts` are **domain
+  logic** with a dedicated package `packages/units` (`normalize`, `convert`, `displayWeight`,
+  `parseWeightUnit`). Consolidating those belongs to a units-package effort, not `@packrat/utils`.
+  Flagging the duplication for awareness only.
+- **debounce/throttle: do NOT re-implement.** Expo uses `use-debounce` (`useDebounce`,
+  `useDebouncedCallback`) which is the correct React-hook form; AI chat uses the AI SDK's
+  `experimental_throttle`; admin uses nuqs `throttleMs`. A bare `debounce`/`throttle` facade
+  export is fine to *offer* (radashi/es-toolkit both have them) but there are **no hand-rolled
+  timers to migrate**, so it's not first-wave.
+- **slugify: leave as-is.** `apps/guides` already depends on the `slugify` package;
+  `packages/api/src/routes/wildlife/index.ts:62` has a tiny inline slugify — single site, not
+  worth a facade export. radashi `dash` is close but not URL-slug-equivalent.
+- **`clamp` in Expo messages** (`chat.tsx`, `conversations.tsx`) is **Reanimated's worklet
+  `clamp`** (runs on UI thread) — must NOT be swapped for a JS-thread util. Only the two API
+  `Math.min(Math.max())` sites are real targets.
+- **`round(x, precision)`**: radashi has **no** precision-rounding helper; es-toolkit `round`
+  does. The `Math.round(x*100)/100` idiom recurs in analytics/compute-pack. Worth a facade export
+  (`round` from es-toolkit) but lower confidence — many of these are intertwined with weight/unit
+  domain math, so migrate opportunistically.
+- **Library coverage confirmed by introspection** (`node -e require(...)`): radashi exports
+  `group, sum, unique, sort, sleep, debounce, throttle, retry, memo, tryit, range, mapValues,
+  pick, omit, capitalize, title, dash, snake, camel, pascal, clamp, objectify, mapEntries`.
+  es-toolkit adds the ones radashi lacks: `sumBy, meanBy, round`. lodash retains
+  `toFinite, toNumber, sumBy, meanBy, round, clamp` (kept for old-school primitives per plan).
+  remeda has equivalents but ranks last; no candidate needed it as best source.
+- **`sortBy`**: many `.sort((a,b)=>...)` sites exist but most are bespoke multi-key/date
+  comparators (e.g. `usePackWeightHistory.ts`, `guides/index.ts`). A generic `sort`/`sortBy`
+  facade (radashi `sort` / es-toolkit `sortBy`) helps the simple single-numeric-key cases
+  (`compute-pack.ts:118`, `data.ts:1312`) but is medium-value, not first-wave.
+- **pick/omit/memoize/once/retry/compose/pipe**: searched, **no hand-rolled implementations
+  found** in source. Offer them in the facade for completeness (cheap, well-typed in radashi),
+  but they have zero current migration sites.
diff --git a/lefthook.yml b/lefthook.yml
index 02dc451700..1a343d8952 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -15,14 +15,16 @@ pre-push:
     # All custom checks are now clean — no continue-on-error backlog remaining.
     clean-checks:
       run: >
-        bun scripts/lint/no-raw-typeof.ts &&
-        bun scripts/lint/no-raw-regex.ts &&
+        bun scripts/lint/no-raw-ast-grep.ts &&
         bun packages/env/scripts/no-raw-process-env.ts &&
         bun scripts/lint/no-circular-deps.ts &&
         bun scripts/lint/no-duplicate-deps.ts &&
         bun scripts/lint/no-duplicate-guards.ts &&
+        bun scripts/lint/no-duplicate-utils.ts &&
         bun scripts/lint/no-unauth-routes.ts &&
         bun scripts/format/sort-package-json.ts --check &&
         bun run --cwd packages/checks check:route-schemas:strict &&
-        bun check:casts:strict
+        bun run --cwd packages/checks check:provenance:strict &&
+        bun check:casts:strict &&
+        bun scripts/lint/check-duplication.ts
       fail_text: "Pre-push checks failed! Run `bun check:all` for the full picture."
diff --git a/package.json b/package.json
index 707070d950..98e3612448 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "packrat-monorepo",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "workspaces": [
     "apps/*",
     "packages/*"
@@ -13,14 +13,20 @@
     "bump": "bun .github/scripts/bump.ts",
     "check": "biome check --no-errors-on-unmatched",
     "check:all": "bun scripts/check-all.ts",
+    "check:ast-grep": "bun scripts/lint/no-raw-ast-grep.ts",
     "check:casts": "bun run --cwd packages/checks check:casts",
     "check:casts:strict": "bun run --cwd packages/checks check:casts:strict",
     "check:catalog": "bun scripts/lint/no-duplicate-deps.ts",
     "check:circular": "bun scripts/lint/no-circular-deps.ts",
+    "check:coverage": "bun run scripts/lint/coverage-ratchet.ts",
+    "check:coverage:update": "bun run scripts/lint/coverage-baseline-update.ts",
     "check:deps": "manypkg check",
+    "check:duplication": "bun scripts/lint/check-duplication.ts",
     "check:magic-strings": "bun run --cwd packages/checks check:magic-strings",
     "check:package-json": "bun scripts/format/sort-package-json.ts --check",
+    "check:provenance:strict": "bun run --cwd packages/checks check:provenance:strict",
     "check:react-doctor": "bun scripts/lint/check-react-doctor.ts",
+    "check:utils": "bun scripts/lint/no-duplicate-utils.ts",
     "check-types": "bun scripts/check-types.ts",
     "check-types:packages": "turbo run check-types --filter='./apps/*' --filter='./packages/*'",
     "check-types:tsgo": "bun scripts/check-types.ts --tsgo",
@@ -37,13 +43,13 @@
     "ios": "cd apps/expo && bun ios",
     "lefthook": "lefthook install",
     "lint": "biome check --write",
-    "lint:custom": "bun run scripts/lint/no-raw-typeof.ts && bun run scripts/lint/no-raw-regex.ts && bun run scripts/lint/no-owned-max-params.ts && bun run packages/env/scripts/no-raw-process-env.ts && bun run scripts/lint/no-duplicate-guards.ts && bun run scripts/lint/no-unauth-routes.ts && bun run scripts/lint/check-drizzle-migrations.ts && bun run scripts/lint/no-direct-wrapped-imports.ts",
+    "lint:custom": "bun run scripts/lint/no-raw-ast-grep.ts && bun run scripts/lint/no-owned-max-params.ts && bun run packages/env/scripts/no-raw-process-env.ts && bun run scripts/lint/no-duplicate-guards.ts && bun run scripts/lint/no-duplicate-utils.ts && bun run scripts/lint/no-unauth-routes.ts && bun run scripts/lint/check-drizzle-migrations.ts && bun run scripts/lint/no-direct-wrapped-imports.ts",
     "lint:strict": "biome check && bun run lint:custom",
+    "lint:weak-assertions": "bun run scripts/lint/no-weak-assertions.ts",
     "lint-unsafe": "biome check --write --unsafe",
     "mcp": "bun run --cwd packages/mcp dev",
     "mcp:deploy": "bun run --cwd packages/mcp deploy",
     "test:api:unit": "vitest run --config packages/api/vitest.unit.config.ts",
-    "test:api-client:types": "vitest run --config packages/api-client/vitest.config.ts",
     "test:e2e:android": "bash .github/scripts/e2e.sh android",
     "test:e2e:ios": "bash .github/scripts/e2e.sh ios",
     "test:expo": "vitest run --config apps/expo/vitest.config.ts",
@@ -51,6 +57,7 @@
     "test:guides": "vitest run --config apps/guides/vitest.config.ts",
     "test:landing": "vitest run --config apps/landing/vitest.config.ts",
     "test:mcp": "bun run --cwd packages/mcp test",
+    "test:scripts": "vitest run --config scripts/vitest.config.ts",
     "trails": "bun run --cwd apps/trails dev",
     "web": "bun run --cwd apps/web dev"
   },
@@ -62,6 +69,7 @@
     "react": "19.2.6"
   },
   "devDependencies": {
+    "@ast-grep/cli": "^0.43.0",
     "@biomejs/biome": "2.4.6",
     "@manypkg/cli": "^0.24.0",
     "@playwright/test": "^1.59.1",
@@ -71,9 +79,11 @@
     "@typescript/native-preview": "7.0.0-dev.20260527.2",
     "fs-extra": "^11.3.0",
     "glob": "^11.0.3",
+    "jscpd": "^4.2.4",
     "lefthook": "^1.11.14",
     "semver": "catalog:",
     "sort-package-json": "^3.6.1",
+    "ts-morph": "^28.0.0",
     "turbo": "^2.5.0"
   },
   "packageManager": "bun@1.3.14",
diff --git a/packages/analytics/package.json b/packages/analytics/package.json
index 65ec68b0d9..129e830a85 100644
--- a/packages/analytics/package.json
+++ b/packages/analytics/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/analytics",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "scripts": {
@@ -12,9 +12,9 @@
     "@duckdb/node-api": "catalog:",
     "@packrat/env": "workspace:*",
     "@packrat/guards": "workspace:*",
+    "@packrat/utils": "workspace:*",
     "consola": "catalog:",
     "magic-regexp": "catalog:",
-    "radash": "catalog:",
     "zod": "catalog:"
   },
   "devDependencies": {
diff --git a/packages/analytics/src/core/cache-metadata.ts b/packages/analytics/src/core/cache-metadata.ts
index c71a8c0eec..19b8cce24f 100644
--- a/packages/analytics/src/core/cache-metadata.ts
+++ b/packages/analytics/src/core/cache-metadata.ts
@@ -5,6 +5,7 @@
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { safeJsonParse, safeJsonStringify } from '@packrat/utils';
 import { z } from 'zod';
 import { DBConfig } from './constants';
 
@@ -36,7 +37,7 @@ export function loadMetadata(cacheDir: string): CacheMetadataFile | null {
 
   let raw: unknown;
   try {
-    raw = JSON.parse(readFileSync(path, 'utf-8'));
+    raw = safeJsonParse(readFileSync(path, 'utf-8'), { strict: true });
   } catch {
     return null;
   }
@@ -52,7 +53,7 @@ export function saveMetadata({
   data: CacheMetadataFile;
 }): void {
   const validated = MetadataSchema.parse(data);
-  writeFileSync(metadataPath(cacheDir), JSON.stringify(validated, null, 2));
+  writeFileSync(metadataPath(cacheDir), safeJsonStringify(validated, null, 2));
 }
 
 export function needsUpdate(metadata: CacheMetadataFile | null): boolean {
diff --git a/packages/analytics/src/core/data-export.ts b/packages/analytics/src/core/data-export.ts
index 0a39b0226c..2c05098d85 100644
--- a/packages/analytics/src/core/data-export.ts
+++ b/packages/analytics/src/core/data-export.ts
@@ -7,6 +7,7 @@
 
 import { mkdirSync, writeFileSync } from 'node:fs';
 import type { DuckDBConnection } from '@duckdb/node-api';
+import { safeJsonStringify } from '@packrat/utils';
 import { DBConfig, QUALITY_WEIGHTS } from './constants';
 import { SQLFragments } from './query-builder';
 
@@ -209,7 +210,7 @@ export class DataExporter {
 
     writeFileSync(
       filepath.replace(FILE_EXTENSION_PATTERN, '.summary.json'),
-      JSON.stringify(summary, null, 2),
+      safeJsonStringify(summary, null, 2),
     );
 
     return summary;
diff --git a/packages/analytics/src/core/local-cache.ts b/packages/analytics/src/core/local-cache.ts
index 0188c583bf..8f8c831351 100644
--- a/packages/analytics/src/core/local-cache.ts
+++ b/packages/analytics/src/core/local-cache.ts
@@ -9,7 +9,7 @@ import { mkdirSync } from 'node:fs';
 import type { DuckDBConnection } from '@duckdb/node-api';
 import { DuckDBInstance } from '@duckdb/node-api';
 import { analyticsEnv as env } from '@packrat/env/analytics';
-import { tryit } from 'radash';
+import { tryit } from '@packrat/utils';
 import type {
   BrandAnalysis,
   CatalogRow,
diff --git a/packages/api-client/package.json b/packages/api-client/package.json
index d1685a6837..36a5d86c4c 100644
--- a/packages/api-client/package.json
+++ b/packages/api-client/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/api-client",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "exports": {
@@ -13,7 +13,8 @@
   },
   "dependencies": {
     "@elysiajs/eden": "catalog:",
-    "@packrat/guards": "workspace:*"
+    "@packrat/guards": "workspace:*",
+    "@packrat/utils": "workspace:*"
   },
   "devDependencies": {
     "@packrat/api": "workspace:*",
diff --git a/packages/api-client/src/index.ts b/packages/api-client/src/index.ts
index 058f160b64..3bbeefceee 100644
--- a/packages/api-client/src/index.ts
+++ b/packages/api-client/src/index.ts
@@ -1,6 +1,7 @@
 import { treaty } from '@elysiajs/eden';
 import type { App } from '@packrat/api';
-import { isObject, isString } from '@packrat/guards';
+import { isFunction, isObject, isString } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 
 /**
  * Auth integration hooks. Session state (token storage, refresh dedup,
@@ -36,9 +37,7 @@ export type ApiClientConfig = {
  * other.
  */
 function isCloneable<T>(input: T): input is T & { clone(): T } {
-  return (
-    isObject(input) && 'clone' in input && typeof (input as { clone: unknown }).clone === 'function'
-  );
+  return isObject(input) && 'clone' in input && isFunction((input as { clone: unknown }).clone);
 }
 
 /**
@@ -62,7 +61,7 @@ export function createApiClient(config: ApiClientConfig) {
         const response = await baseFetcher(`${config.baseUrl}/api/auth/refresh`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ refreshToken }),
+          body: safeJsonStringify({ refreshToken }),
         });
         const data = (await response.json().catch(() => null)) as {
           success?: boolean;
@@ -130,11 +129,7 @@ export function createApiClient(config: ApiClientConfig) {
         });
       } else if (Array.isArray(existing)) {
         for (const entry of existing) {
-          if (
-            Array.isArray(entry) &&
-            typeof entry[0] === 'string' &&
-            typeof entry[1] === 'string'
-          ) {
+          if (Array.isArray(entry) && isString(entry[0]) && isString(entry[1])) {
             headers.set(entry[0], entry[1]);
           }
         }
@@ -267,7 +262,7 @@ export class PackRatApiClient {
     const response = await fetch(`${this.baseUrl}${path}`, {
       method: 'POST',
       headers: this.headers,
-      body: body !== undefined ? JSON.stringify(body) : undefined,
+      body: body !== undefined ? safeJsonStringify(body) : undefined,
     });
     return this.handleResponse<T>(response);
   }
@@ -276,7 +271,7 @@ export class PackRatApiClient {
     const response = await fetch(`${this.baseUrl}${path}`, {
       method: 'PUT',
       headers: this.headers,
-      body: body !== undefined ? JSON.stringify(body) : undefined,
+      body: body !== undefined ? safeJsonStringify(body) : undefined,
     });
     return this.handleResponse<T>(response);
   }
@@ -285,7 +280,7 @@ export class PackRatApiClient {
     const response = await fetch(`${this.baseUrl}${path}`, {
       method: 'PATCH',
       headers: this.headers,
-      body: body !== undefined ? JSON.stringify(body) : undefined,
+      body: body !== undefined ? safeJsonStringify(body) : undefined,
     });
     return this.handleResponse<T>(response);
   }
@@ -324,7 +319,7 @@ export function createPackRatClient({
 // ── MCP tool result helpers ───────────────────────────────────────────────────
 
 export function ok(data: unknown): { content: [{ type: 'text'; text: string }] } {
-  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+  return { content: [{ type: 'text', text: safeJsonStringify(data, null, 2) }] };
 }
 
 export function err(error: unknown): { content: [{ type: 'text'; text: string }]; isError: true } {
diff --git a/packages/api/container_src/package.json b/packages/api/container_src/package.json
index 0e066901c2..64a338239e 100644
--- a/packages/api/container_src/package.json
+++ b/packages/api/container_src/package.json
@@ -1,6 +1,6 @@
 {
   "name": "container",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "type": "module",
   "dependencies": {
     "@aws-sdk/client-s3": "^3.0.0",
diff --git a/packages/api/container_src/server.ts b/packages/api/container_src/server.ts
index 9c149124c4..cd76de448b 100644
--- a/packages/api/container_src/server.ts
+++ b/packages/api/container_src/server.ts
@@ -1,5 +1,6 @@
 import { PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
 import { GoogleGenAI } from '@google/genai';
+import { safeJsonStringify } from '@packrat/utils';
 import Tiktok from '@tobyg74/tiktok-api-dl';
 import { Elysia, status } from 'elysia';
 import { z } from 'zod';
@@ -337,7 +338,7 @@ async function fetchTikTokPostData(
       console.error('Response debug:', {
         status: result.status,
         url,
-        result: JSON.stringify(result, null, 2),
+        result: safeJsonStringify(result, null, 2),
       });
       throw new Error(`TikTok API failed: ${result.status}`);
     }
diff --git a/packages/api/drizzle.config.ts b/packages/api/drizzle.config.ts
index 59d6f0c44c..25f0acefc2 100644
--- a/packages/api/drizzle.config.ts
+++ b/packages/api/drizzle.config.ts
@@ -2,6 +2,9 @@ import { nodeEnv } from '@packrat/env/node';
 import { defineConfig } from 'drizzle-kit';
 
 export default defineConfig({
+  // Points at the in-package re-export at src/db/schema.ts, which re-exports
+  // everything from @packrat/db/schema. Keeps drizzle-kit + tooling scoped
+  // to packages/api without crossing the workspace boundary at config time.
   schema: './src/db/schema.ts',
   out: './drizzle',
   dialect: 'postgresql',
diff --git a/packages/api/drizzle/0047_clear_monster_badoon.sql b/packages/api/drizzle/0047_clear_monster_badoon.sql
new file mode 100644
index 0000000000..96f951f5d3
--- /dev/null
+++ b/packages/api/drizzle/0047_clear_monster_badoon.sql
@@ -0,0 +1,12 @@
+ALTER TABLE "etl_jobs" ADD COLUMN "workflow_instance_id" text;--> statement-breakpoint
+ALTER TABLE "etl_jobs" ADD COLUMN "total_embedding_failures" integer DEFAULT 0 NOT NULL;--> statement-breakpoint
+ALTER TABLE "etl_jobs" ADD COLUMN "verified_at" timestamp;--> statement-breakpoint
+ALTER TABLE "etl_jobs" ADD COLUMN "verified_row_count" integer;--> statement-breakpoint
+ALTER TABLE "etl_jobs" ADD COLUMN "source_etag" text;--> statement-breakpoint
+ALTER TABLE "etl_jobs" ADD COLUMN "source_last_modified" timestamp;--> statement-breakpoint
+ALTER TABLE "etl_jobs" ADD COLUMN "superseded_by_job_id" text;--> statement-breakpoint
+ALTER TABLE "etl_jobs" ADD COLUMN "superseded_at" timestamp;--> statement-breakpoint
+ALTER TABLE "etl_jobs" ADD CONSTRAINT "etl_jobs_superseded_by_job_id_etl_jobs_id_fk" FOREIGN KEY ("superseded_by_job_id") REFERENCES "public"."etl_jobs"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "etl_jobs_workflow_instance_id_idx" ON "etl_jobs" USING btree ("workflow_instance_id");--> statement-breakpoint
+CREATE INDEX "etl_jobs_superseded_by_idx" ON "etl_jobs" USING btree ("superseded_by_job_id");--> statement-breakpoint
+ALTER TABLE "etl_jobs" ADD CONSTRAINT "etl_jobs_no_self_supersede" CHECK ("etl_jobs"."superseded_by_job_id" IS NULL OR "etl_jobs"."superseded_by_job_id" <> "etl_jobs"."id");
\ No newline at end of file
diff --git a/packages/api/drizzle/meta/0047_snapshot.json b/packages/api/drizzle/meta/0047_snapshot.json
new file mode 100644
index 0000000000..c0ad26e3a6
--- /dev/null
+++ b/packages/api/drizzle/meta/0047_snapshot.json
@@ -0,0 +1,2351 @@
+{
+  "id": "79eab1cd-6669-4ece-95a3-4aecfcba8563",
+  "prevId": "1f086d6d-055d-4b37-a5d6-32b1141d2043",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.account": {
+      "name": "account",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "account_id": {
+          "name": "account_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "access_token": {
+          "name": "access_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "refresh_token": {
+          "name": "refresh_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "id_token": {
+          "name": "id_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "access_token_expires_at": {
+          "name": "access_token_expires_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "refresh_token_expires_at": {
+          "name": "refresh_token_expires_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scope": {
+          "name": "scope",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "password": {
+          "name": "password",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "account_userId_idx": {
+          "name": "account_userId_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "account_user_id_users_id_fk": {
+          "name": "account_user_id_users_id_fk",
+          "tableFrom": "account",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "account_provider_account_idx": {
+          "name": "account_provider_account_idx",
+          "nullsNotDistinct": false,
+          "columns": ["provider_id", "account_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.catalog_item_etl_jobs": {
+      "name": "catalog_item_etl_jobs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "catalog_item_id": {
+          "name": "catalog_item_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "etl_job_id": {
+          "name": "etl_job_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "catalog_item_etl_jobs_catalog_item_id_catalog_items_id_fk": {
+          "name": "catalog_item_etl_jobs_catalog_item_id_catalog_items_id_fk",
+          "tableFrom": "catalog_item_etl_jobs",
+          "tableTo": "catalog_items",
+          "columnsFrom": ["catalog_item_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "catalog_item_etl_jobs_etl_job_id_etl_jobs_id_fk": {
+          "name": "catalog_item_etl_jobs_etl_job_id_etl_jobs_id_fk",
+          "tableFrom": "catalog_item_etl_jobs",
+          "tableTo": "etl_jobs",
+          "columnsFrom": ["etl_job_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.catalog_items": {
+      "name": "catalog_items",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "product_url": {
+          "name": "product_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sku": {
+          "name": "sku",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "weight": {
+          "name": "weight",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "weight_unit": {
+          "name": "weight_unit",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "categories": {
+          "name": "categories",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "images": {
+          "name": "images",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "brand": {
+          "name": "brand",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "model": {
+          "name": "model",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "rating_value": {
+          "name": "rating_value",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "color": {
+          "name": "color",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "size": {
+          "name": "size",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "price": {
+          "name": "price",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "availability": {
+          "name": "availability",
+          "type": "availability",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "seller": {
+          "name": "seller",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "product_sku": {
+          "name": "product_sku",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "material": {
+          "name": "material",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "currency": {
+          "name": "currency",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "condition": {
+          "name": "condition",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "review_count": {
+          "name": "review_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "variants": {
+          "name": "variants",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "techs": {
+          "name": "techs",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "links": {
+          "name": "links",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "reviews": {
+          "name": "reviews",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "qas": {
+          "name": "qas",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "faqs": {
+          "name": "faqs",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "embedding": {
+          "name": "embedding",
+          "type": "vector(1536)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "embedding_idx": {
+          "name": "embedding_idx",
+          "columns": [
+            {
+              "expression": "embedding",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "vector_cosine_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "hnsw",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "catalog_items_sku_unique": {
+          "name": "catalog_items_sku_unique",
+          "nullsNotDistinct": false,
+          "columns": ["sku"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.comment_likes": {
+      "name": "comment_likes",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "comment_id": {
+          "name": "comment_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "comment_likes_comment_id_post_comments_id_fk": {
+          "name": "comment_likes_comment_id_post_comments_id_fk",
+          "tableFrom": "comment_likes",
+          "tableTo": "post_comments",
+          "columnsFrom": ["comment_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "comment_likes_user_id_users_id_fk": {
+          "name": "comment_likes_user_id_users_id_fk",
+          "tableFrom": "comment_likes",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "comment_likes_comment_id_user_id_unique": {
+          "name": "comment_likes_comment_id_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["comment_id", "user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.etl_jobs": {
+      "name": "etl_jobs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "etl_job_status",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source": {
+          "name": "source",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "filename": {
+          "name": "filename",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "completed_at": {
+          "name": "completed_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "total_processed": {
+          "name": "total_processed",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "total_valid": {
+          "name": "total_valid",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "total_invalid": {
+          "name": "total_invalid",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scraper_revision": {
+          "name": "scraper_revision",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "workflow_instance_id": {
+          "name": "workflow_instance_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "total_embedding_failures": {
+          "name": "total_embedding_failures",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "verified_at": {
+          "name": "verified_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "verified_row_count": {
+          "name": "verified_row_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "source_etag": {
+          "name": "source_etag",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "source_last_modified": {
+          "name": "source_last_modified",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "superseded_by_job_id": {
+          "name": "superseded_by_job_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "superseded_at": {
+          "name": "superseded_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "etl_jobs_scraper_revision_idx": {
+          "name": "etl_jobs_scraper_revision_idx",
+          "columns": [
+            {
+              "expression": "scraper_revision",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "etl_jobs_workflow_instance_id_idx": {
+          "name": "etl_jobs_workflow_instance_id_idx",
+          "columns": [
+            {
+              "expression": "workflow_instance_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "etl_jobs_superseded_by_idx": {
+          "name": "etl_jobs_superseded_by_idx",
+          "columns": [
+            {
+              "expression": "superseded_by_job_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "etl_jobs_superseded_by_job_id_etl_jobs_id_fk": {
+          "name": "etl_jobs_superseded_by_job_id_etl_jobs_id_fk",
+          "tableFrom": "etl_jobs",
+          "tableTo": "etl_jobs",
+          "columnsFrom": ["superseded_by_job_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "etl_jobs_no_self_supersede": {
+          "name": "etl_jobs_no_self_supersede",
+          "value": "\"etl_jobs\".\"superseded_by_job_id\" IS NULL OR \"etl_jobs\".\"superseded_by_job_id\" <> \"etl_jobs\".\"id\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.invalid_item_logs": {
+      "name": "invalid_item_logs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "job_id": {
+          "name": "job_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "errors": {
+          "name": "errors",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "raw_data": {
+          "name": "raw_data",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "row_index": {
+          "name": "row_index",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "invalid_item_logs_job_id_etl_jobs_id_fk": {
+          "name": "invalid_item_logs_job_id_etl_jobs_id_fk",
+          "tableFrom": "invalid_item_logs",
+          "tableTo": "etl_jobs",
+          "columnsFrom": ["job_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.jwks": {
+      "name": "jwks",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "public_key": {
+          "name": "public_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "private_key": {
+          "name": "private_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.pack_items": {
+      "name": "pack_items",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "weight": {
+          "name": "weight",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "weight_unit": {
+          "name": "weight_unit",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "quantity": {
+          "name": "quantity",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "category": {
+          "name": "category",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "consumable": {
+          "name": "consumable",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "worn": {
+          "name": "worn",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "notes": {
+          "name": "notes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "pack_id": {
+          "name": "pack_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "catalog_item_id": {
+          "name": "catalog_item_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "deleted": {
+          "name": "deleted",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_ai_generated": {
+          "name": "is_ai_generated",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "template_item_id": {
+          "name": "template_item_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "embedding": {
+          "name": "embedding",
+          "type": "vector(1536)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "pack_items_embedding_idx": {
+          "name": "pack_items_embedding_idx",
+          "columns": [
+            {
+              "expression": "embedding",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "vector_cosine_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "hnsw",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "pack_items_pack_id_packs_id_fk": {
+          "name": "pack_items_pack_id_packs_id_fk",
+          "tableFrom": "pack_items",
+          "tableTo": "packs",
+          "columnsFrom": ["pack_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "pack_items_catalog_item_id_catalog_items_id_fk": {
+          "name": "pack_items_catalog_item_id_catalog_items_id_fk",
+          "tableFrom": "pack_items",
+          "tableTo": "catalog_items",
+          "columnsFrom": ["catalog_item_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        },
+        "pack_items_user_id_users_id_fk": {
+          "name": "pack_items_user_id_users_id_fk",
+          "tableFrom": "pack_items",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        },
+        "pack_items_template_item_id_pack_template_items_id_fk": {
+          "name": "pack_items_template_item_id_pack_template_items_id_fk",
+          "tableFrom": "pack_items",
+          "tableTo": "pack_template_items",
+          "columnsFrom": ["template_item_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.pack_template_items": {
+      "name": "pack_template_items",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "weight": {
+          "name": "weight",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "weight_unit": {
+          "name": "weight_unit",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "quantity": {
+          "name": "quantity",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "category": {
+          "name": "category",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "consumable": {
+          "name": "consumable",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "worn": {
+          "name": "worn",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "notes": {
+          "name": "notes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "pack_template_id": {
+          "name": "pack_template_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "catalog_item_id": {
+          "name": "catalog_item_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "deleted": {
+          "name": "deleted",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "pack_template_items_pack_template_id_pack_templates_id_fk": {
+          "name": "pack_template_items_pack_template_id_pack_templates_id_fk",
+          "tableFrom": "pack_template_items",
+          "tableTo": "pack_templates",
+          "columnsFrom": ["pack_template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "pack_template_items_catalog_item_id_catalog_items_id_fk": {
+          "name": "pack_template_items_catalog_item_id_catalog_items_id_fk",
+          "tableFrom": "pack_template_items",
+          "tableTo": "catalog_items",
+          "columnsFrom": ["catalog_item_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        },
+        "pack_template_items_user_id_users_id_fk": {
+          "name": "pack_template_items_user_id_users_id_fk",
+          "tableFrom": "pack_template_items",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.pack_templates": {
+      "name": "pack_templates",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "category": {
+          "name": "category",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "tags": {
+          "name": "tags",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "is_app_template": {
+          "name": "is_app_template",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "deleted": {
+          "name": "deleted",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "content_source": {
+          "name": "content_source",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "content_id": {
+          "name": "content_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "local_created_at": {
+          "name": "local_created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "local_updated_at": {
+          "name": "local_updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "pack_templates_user_id_users_id_fk": {
+          "name": "pack_templates_user_id_users_id_fk",
+          "tableFrom": "pack_templates",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.weight_history": {
+      "name": "weight_history",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "pack_id": {
+          "name": "pack_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "weight": {
+          "name": "weight",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "local_created_at": {
+          "name": "local_created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "weight_history_user_id_users_id_fk": {
+          "name": "weight_history_user_id_users_id_fk",
+          "tableFrom": "weight_history",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "weight_history_pack_id_packs_id_fk": {
+          "name": "weight_history_pack_id_packs_id_fk",
+          "tableFrom": "weight_history",
+          "tableTo": "packs",
+          "columnsFrom": ["pack_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.packs": {
+      "name": "packs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "category": {
+          "name": "category",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "template_id": {
+          "name": "template_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "is_public": {
+          "name": "is_public",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "tags": {
+          "name": "tags",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "deleted": {
+          "name": "deleted",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_ai_generated": {
+          "name": "is_ai_generated",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "local_created_at": {
+          "name": "local_created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "local_updated_at": {
+          "name": "local_updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "packs_user_id_users_id_fk": {
+          "name": "packs_user_id_users_id_fk",
+          "tableFrom": "packs",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "packs_template_id_pack_templates_id_fk": {
+          "name": "packs_template_id_pack_templates_id_fk",
+          "tableFrom": "packs",
+          "tableTo": "pack_templates",
+          "columnsFrom": ["template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.post_comments": {
+      "name": "post_comments",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "post_id": {
+          "name": "post_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "content": {
+          "name": "content",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "parent_comment_id": {
+          "name": "parent_comment_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "post_comments_post_id_posts_id_fk": {
+          "name": "post_comments_post_id_posts_id_fk",
+          "tableFrom": "post_comments",
+          "tableTo": "posts",
+          "columnsFrom": ["post_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "post_comments_user_id_users_id_fk": {
+          "name": "post_comments_user_id_users_id_fk",
+          "tableFrom": "post_comments",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "post_comments_parent_comment_id_post_comments_id_fk": {
+          "name": "post_comments_parent_comment_id_post_comments_id_fk",
+          "tableFrom": "post_comments",
+          "tableTo": "post_comments",
+          "columnsFrom": ["parent_comment_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.post_likes": {
+      "name": "post_likes",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "post_id": {
+          "name": "post_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "post_likes_post_id_posts_id_fk": {
+          "name": "post_likes_post_id_posts_id_fk",
+          "tableFrom": "post_likes",
+          "tableTo": "posts",
+          "columnsFrom": ["post_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "post_likes_user_id_users_id_fk": {
+          "name": "post_likes_user_id_users_id_fk",
+          "tableFrom": "post_likes",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "post_likes_post_id_user_id_unique": {
+          "name": "post_likes_post_id_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["post_id", "user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.posts": {
+      "name": "posts",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "caption": {
+          "name": "caption",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "images": {
+          "name": "images",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "posts_user_id_users_id_fk": {
+          "name": "posts_user_id_users_id_fk",
+          "tableFrom": "posts",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.reported_content": {
+      "name": "reported_content",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_query": {
+          "name": "user_query",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "ai_response": {
+          "name": "ai_response",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_comment": {
+          "name": "user_comment",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'pending'"
+        },
+        "reviewed": {
+          "name": "reviewed",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": false,
+          "default": false
+        },
+        "reviewed_by": {
+          "name": "reviewed_by",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "reviewed_at": {
+          "name": "reviewed_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "reported_content_user_id_users_id_fk": {
+          "name": "reported_content_user_id_users_id_fk",
+          "tableFrom": "reported_content",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        },
+        "reported_content_reviewed_by_users_id_fk": {
+          "name": "reported_content_reviewed_by_users_id_fk",
+          "tableFrom": "reported_content",
+          "tableTo": "users",
+          "columnsFrom": ["reviewed_by"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.session": {
+      "name": "session",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token": {
+          "name": "token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "ip_address": {
+          "name": "ip_address",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_agent": {
+          "name": "user_agent",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "impersonated_by": {
+          "name": "impersonated_by",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "session_userId_idx": {
+          "name": "session_userId_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "session_user_id_users_id_fk": {
+          "name": "session_user_id_users_id_fk",
+          "tableFrom": "session",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "session_token_unique": {
+          "name": "session_token_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.trail_condition_reports": {
+      "name": "trail_condition_reports",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "trail_name": {
+          "name": "trail_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "trail_region": {
+          "name": "trail_region",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "surface": {
+          "name": "surface",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "overall_condition": {
+          "name": "overall_condition",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "hazards": {
+          "name": "hazards",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "water_crossings": {
+          "name": "water_crossings",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "water_crossing_difficulty": {
+          "name": "water_crossing_difficulty",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "notes": {
+          "name": "notes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "photos": {
+          "name": "photos",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "trip_id": {
+          "name": "trip_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "deleted": {
+          "name": "deleted",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "local_created_at": {
+          "name": "local_created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "local_updated_at": {
+          "name": "local_updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "trail_condition_reports_user_id_idx": {
+          "name": "trail_condition_reports_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "trail_condition_reports_active_created_idx": {
+          "name": "trail_condition_reports_active_created_idx",
+          "columns": [
+            {
+              "expression": "deleted",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": false,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "trail_condition_reports_trail_name_idx": {
+          "name": "trail_condition_reports_trail_name_idx",
+          "columns": [
+            {
+              "expression": "trail_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "trail_condition_reports_trip_id_idx": {
+          "name": "trail_condition_reports_trip_id_idx",
+          "columns": [
+            {
+              "expression": "trip_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"trail_condition_reports\".\"trip_id\" IS NOT NULL",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "trail_condition_reports_user_id_users_id_fk": {
+          "name": "trail_condition_reports_user_id_users_id_fk",
+          "tableFrom": "trail_condition_reports",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "trail_condition_reports_trip_id_trips_id_fk": {
+          "name": "trail_condition_reports_trip_id_trips_id_fk",
+          "tableFrom": "trail_condition_reports",
+          "tableTo": "trips",
+          "columnsFrom": ["trip_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.trips": {
+      "name": "trips",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "start_date": {
+          "name": "start_date",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "end_date": {
+          "name": "end_date",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "location": {
+          "name": "location",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "notes": {
+          "name": "notes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "pack_id": {
+          "name": "pack_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "trail_osm_id": {
+          "name": "trail_osm_id",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "local_created_at": {
+          "name": "local_created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "local_updated_at": {
+          "name": "local_updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "deleted": {
+          "name": "deleted",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "trips_user_id_users_id_fk": {
+          "name": "trips_user_id_users_id_fk",
+          "tableFrom": "trips",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        },
+        "trips_pack_id_packs_id_fk": {
+          "name": "trips_pack_id_packs_id_fk",
+          "tableFrom": "trips",
+          "tableTo": "packs",
+          "columnsFrom": ["pack_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.users": {
+      "name": "users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email_verified": {
+          "name": "email_verified",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'USER'"
+        },
+        "banned": {
+          "name": "banned",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": false,
+          "default": false
+        },
+        "ban_reason": {
+          "name": "ban_reason",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ban_expires": {
+          "name": "ban_expires",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "first_name": {
+          "name": "first_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_name": {
+          "name": "last_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "avatar_url": {
+          "name": "avatar_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "users_email_unique": {
+          "name": "users_email_unique",
+          "nullsNotDistinct": false,
+          "columns": ["email"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.verification": {
+      "name": "verification",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "identifier": {
+          "name": "identifier",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value": {
+          "name": "value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "verification_identifier_idx": {
+          "name": "verification_identifier_idx",
+          "columns": [
+            {
+              "expression": "identifier",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}
diff --git a/packages/api/drizzle/meta/_journal.json b/packages/api/drizzle/meta/_journal.json
index ca463a5058..61c4c6ea9d 100644
--- a/packages/api/drizzle/meta/_journal.json
+++ b/packages/api/drizzle/meta/_journal.json
@@ -337,6 +337,13 @@
       "when": 1778594728740,
       "tag": "0047_cute_bloodscream",
       "breakpoints": true
+    },
+    {
+      "idx": 47,
+      "version": "7",
+      "when": 1779334995277,
+      "tag": "0047_clear_monster_badoon",
+      "breakpoints": true
     }
   ]
 }
diff --git a/packages/api/package.json b/packages/api/package.json
index f1eb87961b..6b7dd8470b 100644
--- a/packages/api/package.json
+++ b/packages/api/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/api",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "exports": {
@@ -61,7 +61,8 @@
     "@packrat/schemas": "workspace:*",
     "@packrat/types": "workspace:*",
     "@packrat/units": "workspace:*",
-    "@sentry/cloudflare": "^10.0.0",
+    "@packrat/utils": "workspace:*",
+    "@sentry/cloudflare": "^10.37.0",
     "@sinclair/typebox": "^0.34.15",
     "@types/nodemailer": "^6.4.17",
     "ai": "catalog:",
@@ -77,7 +78,6 @@
     "linkedom": "^0.18.11",
     "nodemailer": "^6.10.0",
     "pg": "catalog:",
-    "radash": "catalog:",
     "resend": "^6.10.0",
     "workers-ai-provider": "^0.7.2",
     "ws": "catalog:",
diff --git a/packages/api/src/__test-stubs__/cloudflare-workers.ts b/packages/api/src/__test-stubs__/cloudflare-workers.ts
index f4cfbe60d9..f89e0a308e 100644
--- a/packages/api/src/__test-stubs__/cloudflare-workers.ts
+++ b/packages/api/src/__test-stubs__/cloudflare-workers.ts
@@ -1,5 +1,36 @@
-/**
- * Stub for `cloudflare:workers` — used only in unit-test environments.
- * The real module is only available in the Cloudflare Workers runtime.
- */
+// Stub for `cloudflare:workers` — used only in unit-test environments.
+// The real module is only available in the Cloudflare Workers runtime.
+
 export const env = {} as Record<string, unknown>;
+
+// Workflows surface — enough for unit tests to import and instantiate.
+// Tests provide their own `step` shim and never call `run` via the real
+// workflow runtime, so these are intentionally minimal.
+
+export type WorkflowEvent<T> = {
+  payload: Readonly<T>;
+  timestamp: Date;
+  instanceId: string;
+};
+
+export type WorkflowStepConfig = {
+  retries?: { limit: number; delay: string | number; backoff?: string };
+  timeout?: string | number;
+};
+
+export interface WorkflowStep {
+  do<T>(name: string, callback: () => Promise<T>): Promise<T>;
+  do<T>(name: string, config: WorkflowStepConfig, callback: () => Promise<T>): Promise<T>;
+  sleep(name: string, duration: string | number): Promise<void>;
+  sleepUntil(name: string, timestamp: Date | number): Promise<void>;
+}
+
+export abstract class WorkflowEntrypoint<Env = unknown, T = unknown> {
+  protected ctx: unknown;
+  protected env: Env;
+  constructor(ctx: unknown, env: Env) {
+    this.ctx = ctx;
+    this.env = env;
+  }
+  abstract run(event: Readonly<WorkflowEvent<T>>, step: WorkflowStep): Promise<unknown>;
+}
diff --git a/packages/api/src/auth/index.ts b/packages/api/src/auth/index.ts
index 95751c1c18..e137ba4117 100644
--- a/packages/api/src/auth/index.ts
+++ b/packages/api/src/auth/index.ts
@@ -14,6 +14,7 @@ import { createConnection } from '@packrat/api/db';
 import type { ValidatedEnv } from '@packrat/api/utils/env-validation';
 import * as schema from '@packrat/db';
 import { isObject } from '@packrat/guards';
+import { safeJsonParse } from '@packrat/utils';
 import { betterAuth } from 'better-auth';
 import { admin, bearer, jwt } from 'better-auth/plugins';
 
@@ -172,7 +173,7 @@ async function buildAuth(env: ValidatedEnv): Promise<any> {
             // biome-ignore lint/suspicious/noExplicitAny: jwks row type from Better Auth is not exported
             return keys.filter((key: any) => {
               try {
-                return isObject(JSON.parse(key.privateKey));
+                return isObject(safeJsonParse(key.privateKey, { strict: true }));
               } catch {
                 return false;
               }
diff --git a/packages/api/src/db/schema.ts b/packages/api/src/db/schema.ts
new file mode 100644
index 0000000000..c6a9fe1fcc
--- /dev/null
+++ b/packages/api/src/db/schema.ts
@@ -0,0 +1,7 @@
+// Re-export of the shared schema from @packrat/db so drizzle.config.ts can
+// point at a path inside the API package without crossing the package
+// boundary. The schema source of truth lives in packages/db/src/schema.ts;
+// this file exists purely so drizzle-kit + any drizzle-aware tooling stays
+// scoped to packages/api and doesn't break if the workspace layout changes.
+
+export * from '@packrat/db/schema';
diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts
index bd3776a81d..99dbfb90c6 100644
--- a/packages/api/src/index.ts
+++ b/packages/api/src/index.ts
@@ -18,6 +18,7 @@ import type { Env } from '@packrat/api/utils/env-validation';
 import { getEnv, setWorkerEnv } from '@packrat/api/utils/env-validation';
 import { packratOpenApi } from '@packrat/api/utils/openapi';
 import { captureApiException } from '@packrat/api/utils/sentry';
+import { safeJsonStringify } from '@packrat/utils';
 import { withSentry } from '@sentry/cloudflare';
 import { Elysia } from 'elysia';
 import { CloudflareAdapter } from 'elysia/adapter/cloudflare-worker';
@@ -65,18 +66,18 @@ export const app = new Elysia({ adapter: CloudflareAdapter })
     }
 
     if (code === 'VALIDATION' || code === 'PARSE') {
-      return new Response(JSON.stringify({ error: 'Validation failed' }), {
+      return new Response(safeJsonStringify({ error: 'Validation failed' }), {
         status: 400,
         headers: { 'Content-Type': 'application/json' },
       });
     }
     if (code === 'NOT_FOUND') {
-      return new Response(JSON.stringify({ error: 'Not found' }), {
+      return new Response(safeJsonStringify({ error: 'Not found' }), {
         status: 404,
         headers: { 'Content-Type': 'application/json' },
       });
     }
-    return new Response(JSON.stringify({ error: 'Internal server error' }), {
+    return new Response(safeJsonStringify({ error: 'Internal server error' }), {
       status: 500,
       headers: { 'Content-Type': 'application/json' },
     });
diff --git a/packages/api/src/routes/admin/analytics/catalog.ts b/packages/api/src/routes/admin/analytics/catalog.ts
index 90b901add5..2ec48d56a0 100644
--- a/packages/api/src/routes/admin/analytics/catalog.ts
+++ b/packages/api/src/routes/admin/analytics/catalog.ts
@@ -1,22 +1,179 @@
 import { createDb } from '@packrat/api/db';
-import { queueCatalogETL } from '@packrat/api/services/etl/queue';
+import { R2BucketService } from '@packrat/api/services/r2-bucket';
 import { getEnv } from '@packrat/api/utils/env-validation';
+import type { CatalogEtlWorkflowParams } from '@packrat/api/workflows/catalog-etl-workflow';
+import { type ChunkSpec, chunkCsvForR2 } from '@packrat/api/workflows/shared/chunkCsvForR2';
 import { catalogItems, etlJobs, invalidItemLogs } from '@packrat/db';
 import {
   AdminErrorResponses,
   BrandRowSchema,
+  CatalogAuditSchema,
   CatalogOverviewSchema,
   EtlFailureSummarySchema,
   EtlJobFailuresSchema,
+  EtlReconcileSchema,
   EtlResetStuckSchema,
   EtlResponseSchema,
   EtlRetrySchema,
   PriceBucketSchema,
 } from '@packrat/schemas/admin';
+import { parse } from 'csv-parse';
 import { and, avg, count, desc, eq, gt, isNotNull, lt, max, min, sql } from 'drizzle-orm';
 import { Elysia, status } from 'elysia';
 import { z } from 'zod';
 
+type ReingestResult =
+  | {
+      success: true;
+      newJobId: string;
+      objectKey: string;
+      workflowInstanceId: string;
+    }
+  | {
+      _statusCode: 400 | 404 | 409 | 500;
+      error: string;
+      code?: string;
+    };
+
+/**
+ * Shared body for retry + repair-from-scratch admin endpoints.
+ *
+ * mode:
+ *   - 'retry'  — only `status='failed'` jobs are eligible (defensive).
+ *   - 'repair' — any job is eligible; always sets supersededByJobId.
+ *
+ * force=true skips the etag fail-closed check. Use when:
+ *   - The original job has no source_etag (legacy queue-era rows, or the
+ *     2026-05-14 false-failure rows).
+ *   - The operator has manually verified the R2 source content.
+ */
+async function reingestJob(args: {
+  originalJobId: string;
+  mode: 'retry' | 'repair';
+  force: boolean;
+}): Promise<ReingestResult> {
+  const { originalJobId, mode, force } = args;
+  const db = createDb();
+
+  try {
+    const [original] = await db
+      .select()
+      .from(etlJobs)
+      .where(eq(etlJobs.id, originalJobId))
+      .limit(1);
+
+    if (!original) {
+      return { _statusCode: 404, error: 'ETL job not found' };
+    }
+
+    if (mode === 'retry' && original.status !== 'failed') {
+      return {
+        _statusCode: 409,
+        error:
+          original.status === 'running'
+            ? 'Job is still running — wait for it to complete or use repair-from-scratch'
+            : 'Only failed jobs can be retried — use repair-from-scratch for completed jobs',
+      };
+    }
+
+    if (mode === 'repair' && original.status === 'running') {
+      return {
+        _statusCode: 409,
+        error: 'Job is still running — wait for it to complete before repair',
+      };
+    }
+
+    const newJobId = crypto.randomUUID();
+    const objectKey = `v2/${original.source}/${original.filename}`;
+    const env = getEnv();
+
+    if (!env.ETL_WORKFLOW) {
+      return { _statusCode: 400, error: 'ETL_WORKFLOW is not configured' };
+    }
+
+    const r2 = new R2BucketService({ env, bucketType: 'catalog' });
+    const head = await r2.head(objectKey);
+    if (!head) {
+      return { _statusCode: 404, error: `R2 source not found at ${objectKey}` };
+    }
+
+    // ETag fail-closed: if we have a stored etag and the live etag has
+    // drifted, refuse unless the operator explicitly forces. This is the
+    // guard that stops a scraper overwrite from being silently re-applied
+    // to an old (source, filename) under the wrong audit record.
+    if (!force && original.sourceEtag !== null && original.sourceEtag !== head.etag) {
+      return {
+        _statusCode: 409,
+        error:
+          `R2 source etag has drifted (stored=${original.sourceEtag}, ` +
+          `live=${head.etag}). Pass ?force=true to re-ingest the current content.`,
+        code: 'ETL_ETAG_MISMATCH',
+      };
+    }
+
+    const {
+      etag: liveEtag,
+      lastModified: liveLastModified,
+      chunks,
+    } = await chunkCsvForR2({
+      r2,
+      objectKey,
+    });
+    const totalChunks = chunks.length;
+    const indexedChunks: ChunkSpec[] = chunks.map((c, i) => ({
+      ...c,
+      chunkIndex: i,
+      chunksTotal: totalChunks,
+    }));
+
+    // CF Workflows IDs allow [a-zA-Z0-9_-] only, max 64 chars.
+    // source-filename-retry-uuid can exceed 64 chars; use suffix+newJobId which is
+    // always unique (UUID) and well within limits.
+    const suffix = mode === 'retry' ? 'retry' : 'repair';
+    const workflowInstanceId = `${suffix}-${newJobId}`;
+
+    await db.insert(etlJobs).values({
+      id: newJobId,
+      status: 'running',
+      source: original.source,
+      filename: original.filename,
+      scraperRevision: original.scraperRevision,
+      startedAt: new Date(),
+      workflowInstanceId,
+      sourceEtag: liveEtag,
+      sourceLastModified: liveLastModified,
+      supersededByJobId: originalJobId,
+      supersededAt: new Date(),
+    });
+
+    const workflowParams: CatalogEtlWorkflowParams = {
+      jobId: newJobId,
+      source: original.source,
+      scraperRevision: original.scraperRevision,
+      chunks: indexedChunks,
+    };
+
+    try {
+      await env.ETL_WORKFLOW.create({ id: workflowInstanceId, params: workflowParams });
+    } catch (enqueueErr) {
+      await db
+        .update(etlJobs)
+        .set({ status: 'failed', completedAt: new Date() })
+        .where(eq(etlJobs.id, newJobId));
+      throw enqueueErr;
+    }
+
+    return { success: true, newJobId, objectKey, workflowInstanceId };
+  } catch (error) {
+    console.error(`ETL ${mode} error:`, error);
+    return {
+      _statusCode: 500,
+      error: `Failed to ${mode === 'retry' ? 'retry' : 'repair'} ETL job`,
+      code: mode === 'retry' ? 'ETL_RETRY_ERROR' : 'ETL_REPAIR_ERROR',
+    };
+  }
+}
+
 export const catalogAnalyticsRoutes = new Elysia({ prefix: '/catalog' })
   .get(
     '/overview',
@@ -212,6 +369,13 @@ export const catalogAnalyticsRoutes = new Elysia({ prefix: '/catalog' })
               j.totalProcessed != null && j.totalProcessed > 0 && j.totalValid != null
                 ? Math.round((j.totalValid / j.totalProcessed) * 1000) / 10
                 : null,
+            failureRate:
+              j.totalProcessed != null && j.totalProcessed > 0 && j.totalInvalid != null
+                ? Math.round((j.totalInvalid / j.totalProcessed) * 1000) / 10
+                : null,
+            totalEmbeddingFailures: j.totalEmbeddingFailures,
+            verifiedRowCount: j.verifiedRowCount ?? null,
+            verifiedAt: j.verifiedAt?.toISOString() ?? null,
           })),
           summary: {
             totalRuns: s?.totalRuns ?? 0,
@@ -409,62 +573,348 @@ export const catalogAnalyticsRoutes = new Elysia({ prefix: '/catalog' })
   )
 
   // ─── Retry a failed job ───────────────────────────────────────────────────────
+  //
+  // Re-ingests via the workflow path regardless of the original engine.
+  // Works for both legacy queue-era failures and workflow-era failures —
+  // the new instance carries chunks computed by chunkCsvForR2 so the
+  // re-ingest is row-boundary-aligned.
 
   .post(
     '/etl/:jobId/retry',
+    async ({ params, query }) => {
+      const result = await reingestJob({
+        originalJobId: params.jobId,
+        mode: 'retry',
+        force: query.force === true,
+      });
+      if ('_statusCode' in result) {
+        const { _statusCode, ...body } = result;
+        return status(_statusCode, body);
+      }
+      return result;
+    },
+    {
+      params: z.object({ jobId: z.string().uuid() }),
+      query: z.object({ force: z.coerce.boolean().optional() }),
+      response: { 200: EtlRetrySchema, ...AdminErrorResponses },
+      detail: { tags: ['Admin'], summary: 'Retry a failed ETL job via the workflow path' },
+    },
+  )
+
+  // ─── Repair-from-scratch (works on completed jobs too) ──────────────────────
+  //
+  // Same shape as retry but accepts `completed` jobs — for cases where an
+  // operator suspects the original ingest under-counted (e.g., the
+  // 2026-05-14 false-failures whose counters might be wrong even after
+  // status was correctly `completed`). Always sets superseded_by_job_id
+  // for full audit trail.
+
+  .post(
+    '/etl/:jobId/repair-from-scratch',
+    async ({ params, query }) => {
+      const result = await reingestJob({
+        originalJobId: params.jobId,
+        mode: 'repair',
+        force: query.force === true,
+      });
+      if ('_statusCode' in result) {
+        const { _statusCode, ...body } = result;
+        return status(_statusCode, body);
+      }
+      return result;
+    },
+    {
+      params: z.object({ jobId: z.string().uuid() }),
+      query: z.object({ force: z.coerce.boolean().optional() }),
+      response: { 200: EtlRetrySchema, ...AdminErrorResponses },
+      detail: {
+        tags: ['Admin'],
+        summary:
+          'Re-ingest a job from scratch via the workflow path (works on completed jobs; always supersedes)',
+      },
+    },
+  )
+
+  // ─── Reconcile a job's row count against its R2 source ───────────────────────
+  //
+  // Synchronous — counts logical CSV rows (csv-parse, not raw \n counting
+  // since quoted multi-line fields skew that) and persists the result on
+  // etl_jobs.verified_at + verified_row_count. For very large files this
+  // can be slow; an async-via-workflow path is a follow-up if needed.
+
+  .post(
+    '/etl/:jobId/reconcile',
     async ({ params }) => {
       const db = createDb();
 
       try {
-        const [original] = await db
-          .select()
-          .from(etlJobs)
-          .where(eq(etlJobs.id, params.jobId))
-          .limit(1);
-
-        if (!original) return status(404, { error: 'ETL job not found' });
-        if (original.status !== 'failed')
-          return status(409, {
-            error:
-              original.status === 'running'
-                ? 'Job is still running — wait for it to complete or reset stuck jobs first'
-                : 'Only failed jobs can be retried',
-          });
+        const [job] = await db.select().from(etlJobs).where(eq(etlJobs.id, params.jobId)).limit(1);
 
-        const newJobId = crypto.randomUUID();
-        const objectKey = `v2/${original.source}/${original.filename}`;
-        const env = getEnv();
+        if (!job) return status(404, { error: 'ETL job not found' });
 
-        if (!env.ETL_QUEUE) return status(400, { error: 'ETL_QUEUE is not configured' });
-
-        await db.insert(etlJobs).values({
-          id: newJobId,
-          status: 'running',
-          source: original.source,
-          filename: original.filename,
-          scraperRevision: original.scraperRevision,
-          startedAt: new Date(),
+        const objectKey = `v2/${job.source}/${job.filename}`;
+        const env = getEnv();
+        const r2 = new R2BucketService({ env, bucketType: 'catalog' });
+        const obj = await r2.get(objectKey);
+        if (!obj) return status(404, { error: `R2 source not found at ${objectKey}` });
+
+        const parser = parse({ relax_column_count: true, skip_empty_lines: true });
+        let totalRows = 0;
+        let isHeaderProcessed = false;
+
+        const writerPromise = (async () => {
+          const reader = obj.body.getReader();
+          const decoder = new TextDecoder();
+          try {
+            while (true) {
+              const { done, value } = await reader.read();
+              if (done) break;
+              const ok = parser.write(decoder.decode(value, { stream: true }));
+              if (!ok) {
+                await new Promise<void>((resolve) => parser.once('drain', resolve));
+              }
+            }
+          } finally {
+            reader.releaseLock();
+            parser.end();
+          }
+        })().catch((err) => {
+          parser.destroy(err instanceof Error ? err : new Error(String(err)));
+          throw err;
         });
 
         try {
-          await queueCatalogETL({ queue: env.ETL_QUEUE, chunks: [{ objectKey }], jobId: newJobId });
-        } catch (enqueueErr) {
-          await db
-            .update(etlJobs)
-            .set({ status: 'failed', completedAt: new Date() })
-            .where(eq(etlJobs.id, newJobId));
-          throw enqueueErr;
+          for await (const _record of parser) {
+            if (!isHeaderProcessed) {
+              isHeaderProcessed = true;
+              continue;
+            }
+            totalRows++;
+          }
+        } finally {
+          await writerPromise;
         }
 
-        return { success: true as const, newJobId, objectKey };
+        const expectedRowCount = totalRows;
+        const actualRowCount = job.totalProcessed;
+        const delta = actualRowCount === null ? null : expectedRowCount - actualRowCount;
+
+        await db
+          .update(etlJobs)
+          .set({
+            verifiedAt: new Date(),
+            verifiedRowCount: expectedRowCount,
+          })
+          .where(eq(etlJobs.id, params.jobId));
+
+        return {
+          success: true as const,
+          jobId: params.jobId,
+          expectedRowCount,
+          actualRowCount,
+          delta,
+        };
       } catch (error) {
-        console.error('ETL retry error:', error);
-        return status(500, { error: 'Failed to retry ETL job', code: 'ETL_RETRY_ERROR' });
+        console.error('ETL reconcile error:', error);
+        return status(500, {
+          error: 'Failed to reconcile ETL job',
+          code: 'ETL_RECONCILE_ERROR',
+        });
       }
     },
     {
       params: z.object({ jobId: z.string().uuid() }),
-      response: { 200: EtlRetrySchema, ...AdminErrorResponses },
-      detail: { tags: ['Admin'], summary: 'Retry a failed ETL job' },
+      response: { 200: EtlReconcileSchema, ...AdminErrorResponses },
+      detail: {
+        tags: ['Admin'],
+        summary: 'Count R2 source rows and persist verified_row_count on etl_jobs',
+      },
+    },
+  )
+
+  // ─── Catalog data-quality audit ────────────────────────────────────────────
+  //
+  // Per-source breakdown of catalog_items quality flags. Powers the scrapyd
+  // audit_db_catalog.py script so that scrapyd never needs DB credentials —
+  // it consumes the JSON from this endpoint and renders markdown.
+  //
+  // Flags surfaced (computed server-side from threshold constants):
+  //   decimal_bug — count of prices < $10 with 3+ decimal places
+  //   low_median — median price below $20 for a non-allowlisted source
+  //   high_null:<field> — > 30% NULL rate on a key field
+  //   bad_weight — count of weights < 1g or > 100kg
+  //   empty_name — count of empty/null names
+  //   stale — source has no completed ETL in 30+ days
+  //
+  // ?source=<name> filters to one source (faster + scoped). Omit for all sources.
+
+  .get(
+    '/etl/audit',
+    async ({ query }) => {
+      const db = createDb();
+
+      try {
+        const sourceFilter = query.source;
+
+        // Single GROUP BY query. catalog_item_etl_jobs is the per-item-per-job
+        // join; we attribute each catalog item to its most recent ingest source
+        // via DISTINCT ON. Then aggregate per source.
+        const rows = (await db.execute(sql`
+          WITH latest_per_item AS (
+            SELECT DISTINCT ON (cie.catalog_item_id)
+              cie.catalog_item_id,
+              j.source
+            FROM catalog_item_etl_jobs cie
+            JOIN etl_jobs j ON j.id = cie.etl_job_id
+            ORDER BY cie.catalog_item_id, cie.created_at DESC
+          ),
+          last_jobs AS (
+            SELECT DISTINCT ON (source)
+              source,
+              id AS last_id,
+              completed_at AS last_at
+            FROM etl_jobs
+            WHERE status = 'completed'
+            ORDER BY source, completed_at DESC NULLS LAST
+          )
+          SELECT
+            lpi.source,
+            COUNT(*)::int AS total_items,
+            lj.last_id,
+            lj.last_at,
+            percentile_cont(0.5) WITHIN GROUP (ORDER BY ci.price)::float AS median_price,
+            MIN(ci.price) FILTER (WHERE ci.price > 0)::float AS min_price,
+            MAX(ci.price)::float AS max_price,
+            COUNT(*) FILTER (WHERE ci.price IS NULL)::int AS null_price,
+            COUNT(*) FILTER (WHERE ci.brand IS NULL OR ci.brand = '')::int AS null_brand,
+            COUNT(*) FILTER (WHERE ci.description IS NULL OR ci.description = '')::int AS null_desc,
+            COUNT(*) FILTER (WHERE ci.weight IS NULL)::int AS null_weight,
+            COUNT(*) FILTER (
+              WHERE ci.images IS NULL OR jsonb_array_length(ci.images) = 0
+            )::int AS null_images,
+            COUNT(*) FILTER (WHERE ci.availability IS NULL)::int AS null_avail,
+            COUNT(*) FILTER (WHERE ci.name IS NULL OR ci.name = '')::int AS empty_name,
+            COUNT(*) FILTER (
+              WHERE ci.price IS NOT NULL
+                AND ci.price < 10
+                AND ci.price <> floor(ci.price)
+                AND (ci.price * 1000) = floor(ci.price * 1000)
+            )::int AS suspicious_decimal,
+            COUNT(*) FILTER (
+              WHERE ci.weight IS NOT NULL
+                AND (ci.weight < 1 OR ci.weight > 100000)
+            )::int AS suspicious_weight
+          FROM latest_per_item lpi
+          JOIN catalog_items ci ON ci.id = lpi.catalog_item_id
+          LEFT JOIN last_jobs lj ON lj.source = lpi.source
+          ${sourceFilter ? sql`WHERE lpi.source = ${sourceFilter}` : sql``}
+          GROUP BY lpi.source, lj.last_id, lj.last_at
+          ORDER BY lpi.source
+        `)) as unknown as Array<{
+          source: string;
+          total_items: number;
+          last_id: string | null;
+          last_at: Date | null;
+          median_price: number | null;
+          min_price: number | null;
+          max_price: number | null;
+          null_price: number;
+          null_brand: number;
+          null_desc: number;
+          null_weight: number;
+          null_images: number;
+          null_avail: number;
+          empty_name: number;
+          suspicious_decimal: number;
+          suspicious_weight: number;
+        }>;
+
+        const now = Date.now();
+        // Sources with no median price below this for non-allowlisted sources flag low_median.
+        // Allowlist matches the EXPECTED_LOW_PRICE_SOURCES constant in scrapyd's
+        // audit_r2_data.py — kept in sync manually for now.
+        const expectedLowPriceSources = new Set([
+          '3vgear',
+          'bioliteenergy',
+          'farmtofeet',
+          'kelty',
+          'darntough',
+        ]);
+        const minFillRate = 0.7;
+
+        const sources = rows.map((r) => {
+          const daysStale =
+            r.last_at !== null
+              ? Math.floor((now - new Date(r.last_at).getTime()) / (24 * 60 * 60 * 1000))
+              : null;
+          const total = r.total_items;
+          const nullRates = {
+            price: total > 0 ? r.null_price / total : 0,
+            brand: total > 0 ? r.null_brand / total : 0,
+            description: total > 0 ? r.null_desc / total : 0,
+            weight: total > 0 ? r.null_weight / total : 0,
+            images: total > 0 ? r.null_images / total : 0,
+            availability: total > 0 ? r.null_avail / total : 0,
+          };
+          const flags: string[] = [];
+          if (r.suspicious_decimal > 0) flags.push(`decimal_bug (${r.suspicious_decimal})`);
+          if (
+            r.median_price !== null &&
+            r.median_price < 20 &&
+            !expectedLowPriceSources.has(r.source)
+          ) {
+            flags.push(`low_median ($${r.median_price.toFixed(2)})`);
+          }
+          for (const [field, rate] of Object.entries(nullRates)) {
+            if (rate > 1 - minFillRate) {
+              flags.push(`high_null:${field} (${Math.round(rate * 100)}%)`);
+            }
+          }
+          if (r.suspicious_weight > 0) flags.push(`bad_weight (${r.suspicious_weight})`);
+          if (r.empty_name > 0) flags.push(`empty_name (${r.empty_name})`);
+          if (daysStale !== null && daysStale > 30) flags.push(`stale (${daysStale}d)`);
+
+          return {
+            source: r.source,
+            totalItems: total,
+            lastEtlId: r.last_id,
+            lastEtlAt: r.last_at ? new Date(r.last_at).toISOString() : null,
+            daysStale,
+            medianPrice: r.median_price,
+            minPrice: r.min_price,
+            maxPrice: r.max_price,
+            nullRates,
+            suspiciousDecimalCount: r.suspicious_decimal,
+            suspiciousWeightCount: r.suspicious_weight,
+            emptyNameCount: r.empty_name,
+            flags,
+          };
+        });
+
+        return {
+          generatedAt: new Date().toISOString(),
+          thresholds: {
+            decimalBugPriceThreshold: 10,
+            lowMedianPriceThreshold: 20,
+            minFillRate,
+            staleDaysThreshold: 30,
+            weightTooLightGrams: 1,
+            weightTooHeavyGrams: 100000,
+          },
+          sources,
+        };
+      } catch (error) {
+        console.error('Catalog audit error:', error);
+        return status(500, { error: 'Failed to generate catalog audit', code: 'AUDIT_ERROR' });
+      }
+    },
+    {
+      query: z.object({ source: z.string().optional() }),
+      response: { 200: CatalogAuditSchema, ...AdminErrorResponses },
+      detail: {
+        tags: ['Admin'],
+        summary:
+          'Per-source catalog_items data-quality audit (decimal bugs, NULL rates, staleness)',
+      },
     },
   );
diff --git a/packages/api/src/routes/admin/trails.ts b/packages/api/src/routes/admin/trails.ts
index e7a718e2f7..c3df1d94aa 100644
--- a/packages/api/src/routes/admin/trails.ts
+++ b/packages/api/src/routes/admin/trails.ts
@@ -10,6 +10,7 @@ import {
   TrailSearchResultSchema,
 } from '@packrat/schemas/admin';
 import { RouteSearchRowSchema } from '@packrat/schemas/trails';
+import { safeJsonParse } from '@packrat/utils';
 import { and, count, desc, eq, ilike, or, sql } from 'drizzle-orm';
 import { Elysia, status } from 'elysia';
 import { z } from 'zod';
@@ -69,7 +70,7 @@ export const adminTrailsRoutes = new Elysia({ prefix: '/trails' })
             distance: row.distance,
             difficulty: row.difficulty,
             description: row.description,
-            bbox: row.bbox ? JSON.parse(row.bbox) : null,
+            bbox: row.bbox ? safeJsonParse(row.bbox, { strict: true }) : null,
           })),
           hasMore,
           offset,
@@ -144,7 +145,7 @@ export const adminTrailsRoutes = new Elysia({ prefix: '/trails' })
 
         let geometry: unknown = null;
         if (row.geojson) {
-          geometry = JSON.parse(row.geojson);
+          geometry = safeJsonParse(row.geojson, { strict: true });
         } else if (row.members && row.members.length > 0) {
           const { stitchRouteGeometry } = await import('@packrat/api/services/trails');
           geometry = await stitchRouteGeometry({ db, members: row.members });
@@ -216,7 +217,7 @@ export const adminTrailsRoutes = new Elysia({ prefix: '/trails' })
           distance: row.distance,
           difficulty: row.difficulty,
           description: row.description,
-          bbox: row.bbox ? JSON.parse(row.bbox) : null,
+          bbox: row.bbox ? safeJsonParse(row.bbox, { strict: true }) : null,
         };
       } catch (error) {
         if (error instanceof Error && error.message.includes('not configured')) {
diff --git a/packages/api/src/routes/catalog/__tests__/instanceId.test.ts b/packages/api/src/routes/catalog/__tests__/instanceId.test.ts
new file mode 100644
index 0000000000..b4f876f2d8
--- /dev/null
+++ b/packages/api/src/routes/catalog/__tests__/instanceId.test.ts
@@ -0,0 +1,62 @@
+/**
+ * Regression tests for CF Workflows instanceId construction.
+ *
+ * CF Workflows only allows [a-zA-Z0-9_-] in instance IDs (max 64 chars).
+ * A prior bug let the raw filename (including its ".csv" extension) flow
+ * directly into the instanceId, producing dots that CF rejected with a 500.
+ *
+ * The fix (packages/api/src/routes/catalog/index.ts):
+ *   const FILE_EXT_RE = /\.[^.]*$/;
+ *   const instanceId = `${source}-${filename.replace(FILE_EXT_RE, '')}`.slice(0, 64);
+ */
+import { describe, expect, it } from 'vitest';
+
+// Mirror the exact logic from the route so this test breaks if the
+// implementation drifts.
+const FILE_EXT_RE = /\.[^.]*$/;
+
+function buildInstanceId(source: string, filename: string): string {
+  return `${source}-${filename.replace(FILE_EXT_RE, '')}`.slice(0, 64);
+}
+
+const CF_INSTANCE_ID_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+
+describe('catalog ETL instanceId', () => {
+  it('basic: strips .csv extension and produces a valid CF instance ID', () => {
+    const id = buildInstanceId('cotopaxi', 'cotopaxi_2026-05-14T16-54-05.csv');
+
+    expect(id).toMatch(CF_INSTANCE_ID_RE);
+    expect(id).not.toContain('.');
+    expect(id).toBe('cotopaxi-cotopaxi_2026-05-14T16-54-05');
+  });
+
+  it('no extension in input: still produces a valid CF instance ID', () => {
+    const id = buildInstanceId('foo', 'foo_2026-01-01T00-00-00');
+
+    expect(id).toMatch(CF_INSTANCE_ID_RE);
+    expect(id).not.toContain('.');
+    expect(id).toBe('foo-foo_2026-01-01T00-00-00');
+  });
+
+  it('long name truncation: result is capped at 64 chars', () => {
+    // 20-char source + '-' + 60-char filename (no ext) = 81 chars before slice
+    const source = 'a'.repeat(20);
+    const filename = `${'b'.repeat(60)}.csv`;
+
+    const id = buildInstanceId(source, filename);
+
+    expect(id.length).toBe(64);
+    expect(id).toMatch(CF_INSTANCE_ID_RE);
+  });
+
+  it('timestamp format: underscores and hyphens pass through as valid chars', () => {
+    // Typical scraper filename pattern uses underscores and ISO-8601 hyphens
+    const id = buildInstanceId('rei', 'rei_catalog_2026-05-14T16-54-05.csv');
+
+    expect(id).toMatch(CF_INSTANCE_ID_RE);
+    expect(id).not.toContain('.');
+    // Both _ and - must survive the strip
+    expect(id).toContain('_');
+    expect(id).toContain('-');
+  });
+});
diff --git a/packages/api/src/routes/catalog/index.ts b/packages/api/src/routes/catalog/index.ts
index 76c937a296..0f577b17f1 100644
--- a/packages/api/src/routes/catalog/index.ts
+++ b/packages/api/src/routes/catalog/index.ts
@@ -6,6 +6,8 @@ import { queueCatalogETL } from '@packrat/api/services/etl/queue';
 import { R2BucketService } from '@packrat/api/services/r2-bucket';
 import { getEmbeddingText } from '@packrat/api/utils/embeddingHelper';
 import { getEnv } from '@packrat/api/utils/env-validation';
+import type { CatalogEtlWorkflowParams } from '@packrat/api/workflows/catalog-etl-workflow';
+import { type ChunkSpec, chunkCsvForR2 } from '@packrat/api/workflows/shared/chunkCsvForR2';
 import { catalogItems, etlJobs, packItems } from '@packrat/db';
 import { isString } from '@packrat/guards';
 import {
@@ -37,6 +39,8 @@ import {
 import { Elysia, NotFoundError, status } from 'elysia';
 import { z } from 'zod';
 
+const FILE_EXT_RE = /\.[^.]*$/;
+
 export const catalogRoutes = new Elysia({ prefix: '/catalog' })
   .use(authPlugin)
   .use(apiKeyAuthPlugin)
@@ -228,19 +232,119 @@ export const catalogRoutes = new Elysia({ prefix: '/catalog' })
     },
   )
 
-  // -- ETL queue (api-key auth)
+  // -- ETL trigger (api-key auth)
+  //
+  // Default engine is 'workflow' — triggers a CatalogEtlWorkflow instance
+  // per source file. The 'queue' engine routes to the legacy queue path and
+  // remains available during the coexistence window so operators can fall
+  // back if the workflow path misbehaves in production. The queue path will
+  // be removed after the workflow path bakes (per the migration plan).
   .post(
     '/etl',
-    async ({ body }) => {
+    async ({ body, query }) => {
       const { filename, chunks, source, scraperRevision } = body;
+      const engine = query.engine ?? 'workflow';
+      // chunkMiB lets the caller tune chunk size per-source without a deploy.
+      // Both workflow and queue paths default to 2 MiB when omitted.
+      const chunkBytes = query.chunkMiB !== undefined ? query.chunkMiB * 1024 * 1024 : undefined;
       const db = createDb();
       const env = getEnv();
+      const jobId = crypto.randomUUID();
+
+      if (engine === 'queue') {
+        if (!env.ETL_QUEUE) {
+          return status(400, { message: 'ETL_QUEUE is not configured' });
+        }
+
+        await db.insert(etlJobs).values({
+          id: jobId,
+          status: 'running',
+          source,
+          filename,
+          scraperRevision,
+          startedAt: new Date(),
+        });
+
+        const CHUNK_BYTES = chunkBytes ?? 2 * 1024 * 1024; // 2 MiB default (matches workflow path)
+        const r2 = new R2BucketService({ env, bucketType: 'catalog' });
+        const queueChunks: Array<{
+          objectKey: string;
+          byteStart?: number;
+          byteEnd?: number;
+        }> = [];
+
+        for (const objectKey of chunks) {
+          const meta = await r2.head(objectKey);
+          if (!meta || meta.size <= CHUNK_BYTES) {
+            queueChunks.push({ objectKey });
+          } else {
+            const n = Math.ceil(meta.size / CHUNK_BYTES);
+            for (let i = 0; i < n; i++) {
+              queueChunks.push({
+                objectKey,
+                byteStart: i * CHUNK_BYTES,
+                byteEnd: Math.min((i + 1) * CHUNK_BYTES - 1, meta.size - 1),
+              });
+            }
+          }
+        }
 
-      if (!env.ETL_QUEUE) {
-        return status(400, { message: 'ETL_QUEUE is not configured' });
+        await queueCatalogETL({
+          queue: env.ETL_QUEUE,
+          chunks: queueChunks,
+          jobId,
+        });
+
+        return {
+          message: 'Catalog ETL job queued successfully (legacy queue path)',
+          jobId,
+          engine: 'queue' as const,
+        };
       }
 
-      const jobId = crypto.randomUUID();
+      // Workflow path (default).
+      if (!env.ETL_WORKFLOW) {
+        return status(400, { message: 'ETL_WORKFLOW is not configured' });
+      }
+
+      const r2 = new R2BucketService({ env, bucketType: 'catalog' });
+
+      // Chunk every source object up front so the workflow params carry the
+      // full plan. Single-file is the dominant case in prod (scrapers
+      // produce one CSV per run); multi-object requests bundle into one
+      // workflow instance. ETag from the first object is captured for the
+      // repair-from-scratch fail-closed verification (U5 follow-up).
+      const allChunks: ChunkSpec[] = [];
+      let firstEtag: string | null = null;
+      let firstLastModified: Date | null = null;
+      for (const objectKey of chunks) {
+        const {
+          etag,
+          lastModified,
+          chunks: chunkSpecs,
+        } = await chunkCsvForR2({
+          r2,
+          objectKey,
+          ...(chunkBytes !== undefined && { chunkBytes }),
+        });
+        if (firstEtag === null) {
+          firstEtag = etag;
+          firstLastModified = lastModified;
+        }
+        allChunks.push(...chunkSpecs);
+      }
+
+      // Re-index chunkIndex / chunksTotal across the combined chunk array so
+      // step names in the workflow are globally unique within an instance.
+      const totalChunks = allChunks.length;
+      const indexedChunks: ChunkSpec[] = allChunks.map((c, i) => ({
+        ...c,
+        chunkIndex: i,
+        chunksTotal: totalChunks,
+      }));
+
+      // CF Workflows instance IDs only allow [a-zA-Z0-9_-] — strip the file extension.
+      const instanceId = `${source}-${filename.replace(FILE_EXT_RE, '')}`.slice(0, 64);
 
       await db.insert(etlJobs).values({
         id: jobId,
@@ -249,48 +353,47 @@ export const catalogRoutes = new Elysia({ prefix: '/catalog' })
         filename,
         scraperRevision,
         startedAt: new Date(),
+        workflowInstanceId: instanceId,
+        sourceEtag: firstEtag,
+        sourceLastModified: firstLastModified,
       });
 
-      // Split large files into 20 MB byte-range chunks so each Worker
-      // invocation stays within the CPU time budget (~30k rows / chunk).
-      const CHUNK_BYTES = 20 * 1024 * 1024;
-      const r2 = new R2BucketService({ env, bucketType: 'catalog' });
-      const queueChunks: Array<{ objectKey: string; byteStart?: number; byteEnd?: number }> = [];
+      const params: CatalogEtlWorkflowParams = {
+        jobId,
+        source,
+        scraperRevision,
+        chunks: indexedChunks,
+      };
 
-      for (const objectKey of chunks) {
-        const meta = await r2.head(objectKey);
-        if (!meta || meta.size <= CHUNK_BYTES) {
-          queueChunks.push({ objectKey });
-        } else {
-          const n = Math.ceil(meta.size / CHUNK_BYTES);
-          for (let i = 0; i < n; i++) {
-            queueChunks.push({
-              objectKey,
-              byteStart: i * CHUNK_BYTES,
-              byteEnd: Math.min((i + 1) * CHUNK_BYTES - 1, meta.size - 1),
-            });
-          }
-        }
+      try {
+        await env.ETL_WORKFLOW.create({ id: instanceId, params });
+      } catch (err) {
+        await db
+          .update(etlJobs)
+          .set({ status: 'failed', completedAt: new Date() })
+          .where(eq(etlJobs.id, jobId));
+        throw err;
       }
 
-      await queueCatalogETL({
-        queue: env.ETL_QUEUE,
-        chunks: queueChunks,
-        jobId,
-      });
-
       return {
-        message: 'Catalog ETL job queued successfully',
+        message: 'Catalog ETL workflow triggered',
         jobId,
-        queued: true,
+        engine: 'workflow' as const,
+        workflowInstanceId: instanceId,
       };
     },
     {
       body: CatalogETLSchema,
+      query: z.object({
+        engine: z.enum(['workflow', 'queue']).optional(),
+        chunkMiB: z.coerce.number().int().min(1).max(20).optional(),
+      }),
       isValidApiKey: true,
       detail: {
         tags: ['Catalog'],
-        summary: 'Queue catalog ETL job from R2 CSV chunk files',
+        summary:
+          'Trigger catalog ETL ingest (Workflow by default; ?engine=queue for legacy path). ' +
+          'Pass ?chunkMiB=N to override the default 2 MiB chunk size (1–20 MiB).',
       },
     },
   )
diff --git a/packages/api/src/routes/packTemplates/index.ts b/packages/api/src/routes/packTemplates/index.ts
index be2ff601da..87d5b6e71e 100644
--- a/packages/api/src/routes/packTemplates/index.ts
+++ b/packages/api/src/routes/packTemplates/index.ts
@@ -14,6 +14,7 @@ import {
   UpdatePackTemplateItemRequestSchema,
   UpdatePackTemplateRequestSchema,
 } from '@packrat/schemas/packTemplates';
+import { safeJsonStringify } from '@packrat/utils';
 import { generateObject } from 'ai';
 import { and, eq, or, sql } from 'drizzle-orm';
 import { Elysia, status } from 'elysia';
@@ -59,7 +60,7 @@ async function fetchTikTokPostData(
     new Request('http://container/import', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ tiktokUrl: url }),
+      body: safeJsonStringify({ tiktokUrl: url }),
     }),
   );
 
diff --git a/packages/api/src/routes/packs/index.ts b/packages/api/src/routes/packs/index.ts
index e1935aec52..1c33c00672 100644
--- a/packages/api/src/routes/packs/index.ts
+++ b/packages/api/src/routes/packs/index.ts
@@ -34,6 +34,7 @@ import {
   UpdatePackRequestSchema,
 } from '@packrat/schemas/packs';
 import { ErrorResponseSchema } from '@packrat/schemas/shared';
+import { safeJsonStringify } from '@packrat/utils';
 import {
   and,
   cosineDistance,
@@ -506,7 +507,7 @@ export const packsRoutes = new Elysia({ prefix: '/packs' })
         if (destination) {
           try {
             const weatherResult = await weatherService.getWeatherForLocation(destination);
-            weatherContext = `Current weather in ${destination}: ${JSON.stringify(weatherResult)}`;
+            weatherContext = `Current weather in ${destination}: ${safeJsonStringify(weatherResult)}`;
           } catch (error) {
             console.warn('Weather lookup failed:', error);
           }
diff --git a/packages/api/src/routes/trails/index.ts b/packages/api/src/routes/trails/index.ts
index e1e0d606e9..cc249029ab 100644
--- a/packages/api/src/routes/trails/index.ts
+++ b/packages/api/src/routes/trails/index.ts
@@ -3,6 +3,7 @@ import { authPlugin } from '@packrat/api/middleware/auth';
 import { stitchRouteGeometry } from '@packrat/api/services/trails';
 import { captureApiException } from '@packrat/api/utils/sentry';
 import { RouteDetailRowSchema, RouteSearchRowSchema } from '@packrat/schemas/trails';
+import { safeJsonParse } from '@packrat/utils';
 import { sql } from 'drizzle-orm';
 import { Elysia, status } from 'elysia';
 import { z } from 'zod';
@@ -82,7 +83,7 @@ export const trailsRoutes = new Elysia({ prefix: '/trails' })
             distance: row.distance,
             difficulty: row.difficulty,
             description: row.description,
-            bbox: row.bbox ? JSON.parse(row.bbox) : null,
+            bbox: row.bbox ? safeJsonParse(row.bbox, { strict: true }) : null,
           })),
           hasMore,
         };
@@ -158,7 +159,7 @@ export const trailsRoutes = new Elysia({ prefix: '/trails' })
         let geometry: unknown = null;
 
         if (row.geojson) {
-          geometry = JSON.parse(row.geojson);
+          geometry = safeJsonParse(row.geojson, { strict: true });
         } else if (row.members && row.members.length > 0) {
           geometry = await stitchRouteGeometry({ db, members: row.members });
         }
@@ -239,7 +240,7 @@ export const trailsRoutes = new Elysia({ prefix: '/trails' })
           distance: row.distance,
           difficulty: row.difficulty,
           description: row.description,
-          bbox: row.bbox ? JSON.parse(row.bbox) : null,
+          bbox: row.bbox ? safeJsonParse(row.bbox, { strict: true }) : null,
         };
       } catch (error) {
         if (error instanceof Error && error.message.includes('not configured')) {
diff --git a/packages/api/src/services/catalogService.ts b/packages/api/src/services/catalogService.ts
index 21d7490cda..0d3f8d4608 100644
--- a/packages/api/src/services/catalogService.ts
+++ b/packages/api/src/services/catalogService.ts
@@ -8,6 +8,7 @@ import {
   catalogItems,
   type NewCatalogItem,
 } from '@packrat/db';
+import { safeJsonStringify } from '@packrat/utils';
 import {
   and,
   asc,
@@ -19,6 +20,7 @@ import {
   gt,
   ilike,
   inArray,
+  isNotNull,
   isNull,
   or,
   type SQL,
@@ -241,6 +243,8 @@ export class CatalogService {
 
     const { embedding: _embedding, ...columnsToSelect } = getTableColumns(catalogItems);
 
+    const vectorWhere = and(isNotNull(catalogItems.embedding), gt(similarity, 0.1));
+
     const [items, vectorTotalCountResult] = await Promise.all([
       this.db
         .select({
@@ -248,7 +252,7 @@ export class CatalogService {
           similarity,
         })
         .from(catalogItems)
-        .where(gt(similarity, 0.1))
+        .where(vectorWhere)
         .orderBy(desc(similarity))
         .limit(limit)
         .offset(offset),
@@ -257,7 +261,7 @@ export class CatalogService {
           totalCount: count(),
         })
         .from(catalogItems)
-        .where(gt(similarity, 0.1)),
+        .where(vectorWhere),
     ]);
     const totalCount = vectorTotalCountResult[0]?.totalCount ?? 0;
 
@@ -308,7 +312,7 @@ export class CatalogService {
           similarity,
         })
         .from(catalogItems)
-        .where(gt(similarity, 0.1))
+        .where(and(isNotNull(catalogItems.embedding), gt(similarity, 0.1)))
         .orderBy(desc(similarity))
         .limit(limit);
     });
@@ -381,7 +385,8 @@ export class CatalogService {
 
       return embeddingFields.some(
         (field) =>
-          inputItem[field] && JSON.stringify(inputItem[field]) !== JSON.stringify(item[field]),
+          inputItem[field] &&
+          safeJsonStringify(inputItem[field]) !== safeJsonStringify(item[field]),
       );
     });
 
diff --git a/packages/api/src/services/etl/CatalogItemValidator.ts b/packages/api/src/services/etl/CatalogItemValidator.ts
index b700d74120..11af59f9d1 100644
--- a/packages/api/src/services/etl/CatalogItemValidator.ts
+++ b/packages/api/src/services/etl/CatalogItemValidator.ts
@@ -3,6 +3,28 @@ import type { NewCatalogItem } from '@packrat/db';
 import { isNumber, isString } from '@packrat/guards';
 import type { ValidationError } from '@packrat/schemas/validation';
 
+// Hostname patterns rejected by isValidUrl to close the SSRF surface — any
+// future server-side fetch of a catalog URL (OG-tag generation, preview
+// rendering, etc.) cannot be tricked into hitting internal infrastructure.
+// String-level check only; no DNS resolution (which is itself an SSRF vector).
+// IPv6 hostnames are bracket-stripped before matching (URL.hostname returns
+// bracketed form: `[::1]`).
+const PRIVATE_HOSTNAME_PATTERN =
+  /^(?:localhost|127\.|10\.|192\.168\.|172\.(?:1[6-9]|2\d|3[01])\.|169\.254\.|::1$|fc00:|fd00:|fe80:)/i;
+
+// Length caps — chosen to accommodate the widest real-world catalog rows while
+// preventing a scraper bug or supply-chain compromise from saturating the
+// catalog with multi-MB blobs.
+const URL_MAX_LENGTH = 2048;
+const NAME_MAX_LENGTH = 500;
+const DESCRIPTION_MAX_LENGTH = 50_000;
+const BRAND_MAX_LENGTH = 200;
+const CATEGORY_MAX_LENGTH = 200;
+const SKU_MAX_LENGTH = 200;
+
+const SKU_PATTERN = /^[A-Za-z0-9_./-]+$/;
+const IPV6_BRACKET_PATTERN = /^\[(.+)\]$/;
+
 export class CatalogItemValidator {
   validateItem(item: Partial<NewCatalogItem>): ValidatedCatalogItem {
     const errors: ValidationError[] = [];
@@ -14,6 +36,12 @@ export class CatalogItemValidator {
         reason: 'Name is required and must be a non-empty string',
         value: item.name,
       });
+    } else if (item.name.length > NAME_MAX_LENGTH) {
+      errors.push({
+        field: 'name',
+        reason: `Name exceeds maximum length (${NAME_MAX_LENGTH} chars)`,
+        value: item.name,
+      });
     }
 
     if (!item.sku || !isString(item.sku) || item.sku.trim().length === 0) {
@@ -22,6 +50,18 @@ export class CatalogItemValidator {
         reason: 'SKU is required and must be a non-empty string',
         value: item.sku,
       });
+    } else if (item.sku.length > SKU_MAX_LENGTH) {
+      errors.push({
+        field: 'sku',
+        reason: `SKU exceeds maximum length (${SKU_MAX_LENGTH} chars)`,
+        value: item.sku,
+      });
+    } else if (!SKU_PATTERN.test(item.sku)) {
+      errors.push({
+        field: 'sku',
+        reason: 'SKU contains invalid characters (allowed: A-Z a-z 0-9 _ . / -)',
+        value: item.sku,
+      });
     }
 
     if (!item.productUrl || !isString(item.productUrl) || item.productUrl.trim().length === 0) {
@@ -30,17 +70,53 @@ export class CatalogItemValidator {
         reason: 'Product URL is required and must be a non-empty string',
         value: item.productUrl,
       });
+    } else if (item.productUrl.length > URL_MAX_LENGTH) {
+      errors.push({
+        field: 'productUrl',
+        reason: `Product URL exceeds maximum length (${URL_MAX_LENGTH} chars)`,
+        value: item.productUrl,
+      });
+    } else {
+      const urlError = this.validateUrl(item.productUrl);
+      if (urlError) {
+        errors.push({ field: 'productUrl', reason: urlError, value: item.productUrl });
+      }
     }
 
     // Additional validations
     // Note: weight and weightUnit are intentionally not required — clothing/footwear brands often
     // omit weight data. Items without weight are ingested but won't appear in weight comparisons.
-    if (item.productUrl && !this.isValidUrl(item.productUrl)) {
-      errors.push({
-        field: 'productUrl',
-        reason: 'Product URL must be a valid URL format',
-        value: item.productUrl,
-      });
+    if (item.description !== undefined && item.description !== null) {
+      if (isString(item.description) && item.description.length > DESCRIPTION_MAX_LENGTH) {
+        errors.push({
+          field: 'description',
+          reason: `Description exceeds maximum length (${DESCRIPTION_MAX_LENGTH} chars)`,
+          value: undefined, // omit the raw value — it can be huge
+        });
+      }
+    }
+
+    if (item.brand !== undefined && item.brand !== null) {
+      if (isString(item.brand) && item.brand.length > BRAND_MAX_LENGTH) {
+        errors.push({
+          field: 'brand',
+          reason: `Brand exceeds maximum length (${BRAND_MAX_LENGTH} chars)`,
+          value: item.brand,
+        });
+      }
+    }
+
+    if (Array.isArray(item.categories)) {
+      for (const category of item.categories) {
+        if (isString(category) && category.length > CATEGORY_MAX_LENGTH) {
+          errors.push({
+            field: 'categories',
+            reason: `Category exceeds maximum length (${CATEGORY_MAX_LENGTH} chars)`,
+            value: category,
+          });
+          break; // one error is enough; don't spam
+        }
+      }
     }
 
     if (item.price !== undefined && (!isNumber(item.price) || item.price < 0)) {
@@ -58,12 +134,47 @@ export class CatalogItemValidator {
     };
   }
 
-  private isValidUrl(url: string): boolean {
+  /**
+   * Returns null when the URL is acceptable; otherwise a reason string.
+   *
+   * Rejects:
+   * - Non-http(s) schemes (javascript:, mailto:, data:, file:, etc.)
+   * - Private/loopback/link-local hostnames (SSRF surface for any future
+   *   server-side fetch)
+   * - Hostnames containing non-ASCII characters that survive punycode
+   *   round-tripping (IDN homograph attack surface for the user-facing
+   *   catalog UI)
+   */
+  private validateUrl(url: string): string | null {
+    let parsed: URL;
     try {
-      new URL(url);
-      return true;
+      parsed = new URL(url);
     } catch {
-      return false;
+      return 'Product URL must be a valid URL format';
+    }
+
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      return `Product URL scheme must be http: or https: (got ${parsed.protocol})`;
+    }
+
+    // Strip IPv6 brackets so `[::1]` matches the IPv6 patterns and not the
+    // bracketed-string fallback.
+    const hostname = parsed.hostname.replace(IPV6_BRACKET_PATTERN, '$1');
+    if (PRIVATE_HOSTNAME_PATTERN.test(hostname)) {
+      return 'Product URL hostname must not be a private/loopback/link-local address';
+    }
+
+    // Hostnames with non-ASCII characters are IDN homograph candidates.
+    // Native URL parsing already encodes them to punycode in parsed.hostname,
+    // so non-ASCII presence here means the hostname survived encoding (rare)
+    // OR the URL was malformed in a way `new URL()` accepted. Either way,
+    // reject as a defense-in-depth measure for catalog-rendered links.
+    for (const ch of parsed.hostname) {
+      if (ch.charCodeAt(0) > 127) {
+        return 'Product URL hostname contains non-ASCII characters (IDN homograph guard)';
+      }
     }
+
+    return null;
   }
 }
diff --git a/packages/api/src/services/etl/__tests__/CatalogItemValidator.test.ts b/packages/api/src/services/etl/__tests__/CatalogItemValidator.test.ts
new file mode 100644
index 0000000000..df79a5e776
--- /dev/null
+++ b/packages/api/src/services/etl/__tests__/CatalogItemValidator.test.ts
@@ -0,0 +1,159 @@
+// Validator hardening tests — closes audit P3 #2 (the user-facing catalog
+// rendered any URL that new URL() accepted, including javascript: and
+// private IPs). These tests pin the new scheme / hostname / length
+// constraints so the attack surface cannot regress.
+
+import { CatalogItemValidator } from '@packrat/api/services/etl/CatalogItemValidator';
+import { describe, expect, it } from 'vitest';
+
+const baseItem = {
+  name: 'Test Item',
+  sku: 'SKU-1',
+  productUrl: 'https://example.com/product/1',
+};
+
+function reasonsFor(field: string, errors: { field: string; reason: string }[]): string[] {
+  return errors.filter((e) => e.field === field).map((e) => e.reason);
+}
+
+describe('CatalogItemValidator', () => {
+  const v = new CatalogItemValidator();
+
+  describe('URL scheme', () => {
+    it('accepts http and https URLs', () => {
+      const httpsOk = v.validateItem({ ...baseItem, productUrl: 'https://example.com/x' });
+      expect(httpsOk.isValid).toBe(true);
+
+      const httpOk = v.validateItem({ ...baseItem, productUrl: 'http://example.com/x' });
+      expect(httpOk.isValid).toBe(true);
+    });
+
+    it('rejects javascript:, mailto:, data:, file: URLs', () => {
+      for (const url of [
+        'javascript:alert(1)',
+        'mailto:foo@bar',
+        'data:text/html,x',
+        'file:///etc/passwd',
+      ]) {
+        const result = v.validateItem({ ...baseItem, productUrl: url });
+        expect(result.isValid).toBe(false);
+        expect(reasonsFor('productUrl', result.errors).join(' ')).toMatch(/scheme/i);
+      }
+    });
+  });
+
+  describe('URL hostname (SSRF guard)', () => {
+    it('rejects loopback hostnames', () => {
+      for (const url of [
+        'http://localhost/x',
+        'http://127.0.0.1/x',
+        'http://127.5.5.5/x',
+        'http://[::1]/x',
+      ]) {
+        const result = v.validateItem({ ...baseItem, productUrl: url });
+        expect(result.isValid).toBe(false);
+        expect(reasonsFor('productUrl', result.errors).join(' ')).toMatch(
+          /private|loopback|link-local/i,
+        );
+      }
+    });
+
+    it('rejects RFC-1918 private ranges', () => {
+      for (const url of [
+        'http://10.0.0.1/x',
+        'http://10.255.255.255/x',
+        'http://192.168.1.1/x',
+        'http://172.16.0.1/x',
+        'http://172.31.255.255/x',
+      ]) {
+        const result = v.validateItem({ ...baseItem, productUrl: url });
+        expect(result.isValid).toBe(false);
+        expect(reasonsFor('productUrl', result.errors).join(' ')).toMatch(
+          /private|loopback|link-local/i,
+        );
+      }
+    });
+
+    it('rejects link-local 169.254/16', () => {
+      const result = v.validateItem({ ...baseItem, productUrl: 'http://169.254.169.254/latest' });
+      expect(result.isValid).toBe(false);
+      expect(reasonsFor('productUrl', result.errors).join(' ')).toMatch(
+        /private|loopback|link-local/i,
+      );
+    });
+
+    it('allows 172.15 and 172.32 (outside the private 16-31 range)', () => {
+      const ok1 = v.validateItem({ ...baseItem, productUrl: 'http://172.15.0.1/x' });
+      expect(ok1.isValid).toBe(true);
+      const ok2 = v.validateItem({ ...baseItem, productUrl: 'http://172.32.0.1/x' });
+      expect(ok2.isValid).toBe(true);
+    });
+  });
+
+  describe('URL length cap', () => {
+    it('accepts a URL at the boundary (2048 chars)', () => {
+      const path = 'a'.repeat(2048 - 'https://example.com/'.length);
+      const url = `https://example.com/${path}`;
+      expect(url.length).toBe(2048);
+      const result = v.validateItem({ ...baseItem, productUrl: url });
+      expect(result.isValid).toBe(true);
+    });
+
+    it('rejects a URL of 2049 chars', () => {
+      const path = 'a'.repeat(2049 - 'https://example.com/'.length);
+      const url = `https://example.com/${path}`;
+      const result = v.validateItem({ ...baseItem, productUrl: url });
+      expect(result.isValid).toBe(false);
+      expect(reasonsFor('productUrl', result.errors).join(' ')).toMatch(/maximum length/i);
+    });
+  });
+
+  describe('SKU charset and length', () => {
+    it('accepts conventional SKUs (letters, digits, _ . / -)', () => {
+      const sku = 'ABC_def.123/test-9';
+      const result = v.validateItem({ ...baseItem, sku });
+      expect(result.isValid).toBe(true);
+    });
+
+    it('rejects SKUs with shell metacharacters or HTML', () => {
+      for (const sku of ['<script>', 'a"b', "a'b", 'a;b', 'a&b']) {
+        const result = v.validateItem({ ...baseItem, sku });
+        expect(result.isValid).toBe(false);
+        expect(reasonsFor('sku', result.errors).join(' ')).toMatch(/invalid characters/i);
+      }
+    });
+
+    it('rejects SKUs over 200 chars', () => {
+      const result = v.validateItem({ ...baseItem, sku: 'a'.repeat(201) });
+      expect(result.isValid).toBe(false);
+      expect(reasonsFor('sku', result.errors).join(' ')).toMatch(/maximum length/i);
+    });
+  });
+
+  describe('Length caps on prose fields', () => {
+    it('accepts a 500-char name; rejects 501', () => {
+      const ok = v.validateItem({ ...baseItem, name: 'a'.repeat(500) });
+      expect(ok.isValid).toBe(true);
+      const bad = v.validateItem({ ...baseItem, name: 'a'.repeat(501) });
+      expect(bad.isValid).toBe(false);
+    });
+
+    it('rejects description over 50,000 chars', () => {
+      const result = v.validateItem({ ...baseItem, description: 'a'.repeat(50_001) });
+      expect(result.isValid).toBe(false);
+      expect(reasonsFor('description', result.errors).join(' ')).toMatch(/maximum length/i);
+    });
+
+    it('rejects brand over 200 chars', () => {
+      const result = v.validateItem({ ...baseItem, brand: 'a'.repeat(201) });
+      expect(result.isValid).toBe(false);
+      expect(reasonsFor('brand', result.errors).join(' ')).toMatch(/maximum length/i);
+    });
+
+    it('rejects an oversized category', () => {
+      const result = v.validateItem({ ...baseItem, categories: ['ok', 'a'.repeat(201)] });
+      expect(result.isValid).toBe(false);
+      expect(reasonsFor('categories', result.errors).join(' ')).toMatch(/maximum length/i);
+    });
+  });
+});
diff --git a/packages/api/src/services/etl/processCatalogEtl.ts b/packages/api/src/services/etl/processCatalogEtl.ts
index 77f7b088d4..051d6bf69b 100644
--- a/packages/api/src/services/etl/processCatalogEtl.ts
+++ b/packages/api/src/services/etl/processCatalogEtl.ts
@@ -1,7 +1,10 @@
 import { createDbClient } from '@packrat/api/db';
 import { mapCsvRowToItem } from '@packrat/api/utils/csv-utils';
 import type { Env } from '@packrat/api/utils/env-validation';
+import { isJsonlFile, mapJsonRowToItem } from '@packrat/api/utils/json-utils';
 import { etlJobs, type NewCatalogItem, type NewInvalidItemLog } from '@packrat/db';
+import { toRecord } from '@packrat/guards';
+import { safeJsonParse } from '@packrat/utils';
 import { parse } from 'csv-parse';
 import { eq } from 'drizzle-orm';
 import { R2BucketService } from '../r2-bucket';
@@ -74,96 +77,220 @@ export async function processCatalogETL({
     }
 
     let rowIndex = 0;
-    let fieldMap: Record<string, number> = {};
-    let isHeaderProcessed = false;
     const validItemsBatch: Partial<NewCatalogItem>[] = [];
     const invalidItemsBatch: NewInvalidItemLog[] = [];
 
     const validator = new CatalogItemValidator();
+    const useJsonl = isJsonlFile(objectKey);
 
-    const parser = parse({
-      relax_column_count: true,
-      skip_empty_lines: true,
-    });
-
-    (async () => {
-      // Non-first chunks: inject the header row so csv-parse sees a valid header,
-      // then skip the partial row at the chunk boundary (tail of the previous chunk).
-      if (injectedHeader) {
-        parser.write(`${injectedHeader}\n`);
-      }
-      let skipPartialRow = byteStart !== undefined && byteStart > 0;
+    if (useJsonl) {
+      // --- JSONL streaming path ---
+      // No csv-parse, no header injection. Each line is a JSON object.
+      let buffer = '';
+      // The chunker snaps boundaries to newlines, so every chunk starts at a
+      // clean line boundary — no partial first-line skip needed for any chunk.
+      let firstLineSkipped = true;
 
       for await (const chunk of streamToText(r2Object.body)) {
-        let text = chunk;
-
-        if (skipPartialRow) {
-          // Discard bytes up to and including the first newline — those bytes are
-          // the tail of the row that the previous chunk already processed.
-          const nl = text.indexOf('\n');
-          if (nl === -1) continue; // entire buffer is still the partial row tail
-          text = text.slice(nl + 1);
-          skipPartialRow = false;
-          if (!text) continue;
-        }
+        buffer += chunk;
+        const lines = buffer.split('\n');
+        buffer = lines.pop() ?? '';
 
-        // Respect backpressure: if the parser buffer is full, wait for drain before
-        // pushing more data. Without this, R2 fills the parser buffer for the entire
-        // file (up to 600 MB) before the main loop processes any rows → Worker OOM.
-        const ok = parser.write(text);
-        if (!ok) await new Promise<void>((resolve) => parser.once('drain', resolve));
-      }
-      parser.end();
-    })();
-
-    for await (const record of parser) {
-      if (rowIndex % 100 === 0) await new Promise((resolve) => setTimeout(resolve, 1)); // Yield every 100 rows for GC; per-row yield hits the CF Worker wall-clock limit on large files
-      const row = record as string[];
-      if (!isHeaderProcessed) {
-        fieldMap = row.reduce<Record<string, number>>((acc, header, idx) => {
-          acc[header.trim()] = idx;
-          return acc;
-        }, {});
-        isHeaderProcessed = true;
-        console.log(
-          `🔍 [TRACE] Header processed - fields: ${Object.keys(fieldMap).length}, mapping:`,
-          Object.keys(fieldMap),
-        );
-        continue;
-      }
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+
+          if (!firstLineSkipped) {
+            firstLineSkipped = true;
+            continue; // discard partial row at chunk boundary
+          }
+
+          // Yield every 100 rows for GC; per-row yield hits the CF Worker wall-clock limit
+          if (rowIndex % 100 === 0) await new Promise((resolve) => setTimeout(resolve, 1));
+
+          let obj: Record<string, unknown>;
+          try {
+            obj = toRecord(safeJsonParse(trimmed, { strict: true }));
+          } catch (parseErr) {
+            invalidItemsBatch.push({
+              jobId,
+              errors: [{ field: 'json_parse', reason: String(parseErr) }],
+              rawData: { parseError: String(parseErr) },
+              rowIndex,
+            });
+            rowIndex++;
+            if (invalidItemsBatch.length >= BATCH_SIZE) {
+              await processLogsBatch({ jobId, logs: [...invalidItemsBatch], env });
+              invalidItemsBatch.length = 0;
+            }
+            continue;
+          }
 
-      const item = mapCsvRowToItem({ values: row, fieldMap });
+          const item = mapJsonRowToItem(obj);
+          if (item) {
+            const validated = validator.validateItem(item);
+            if (validated.isValid) {
+              validItemsBatch.push(validated.item);
+            } else {
+              invalidItemsBatch.push({
+                jobId,
+                errors: validated.errors,
+                rawData: validated.item,
+                rowIndex,
+              });
+            }
+          }
+          rowIndex++;
 
-      if (item) {
-        const validatedItem = validator.validateItem(item);
+          if (validItemsBatch.length >= BATCH_SIZE) {
+            await processValidItemsBatch({ jobId, items: [...validItemsBatch], env });
+            validItemsBatch.length = 0;
+          }
+          if (invalidItemsBatch.length >= BATCH_SIZE) {
+            await processLogsBatch({ jobId, logs: [...invalidItemsBatch], env });
+            invalidItemsBatch.length = 0;
+          }
+        }
+      }
 
-        if (validatedItem.isValid) {
-          validItemsBatch.push(validatedItem.item);
-        } else {
-          const invalidItemLog = {
+      // Flush remaining buffer line (last line without trailing newline)
+      const lastLine = buffer.trim();
+      if (lastLine && firstLineSkipped) {
+        try {
+          const obj = toRecord(safeJsonParse(lastLine, { strict: true }));
+          const item = mapJsonRowToItem(obj);
+          if (item) {
+            const validated = validator.validateItem(item);
+            if (validated.isValid) {
+              validItemsBatch.push(validated.item);
+            } else {
+              invalidItemsBatch.push({
+                jobId,
+                errors: validated.errors,
+                rawData: validated.item,
+                rowIndex,
+              });
+            }
+          }
+          rowIndex++;
+        } catch (parseErr) {
+          invalidItemsBatch.push({
             jobId,
-            errors: validatedItem.errors,
-            rawData: validatedItem.item,
+            errors: [{ field: 'json_parse', reason: String(parseErr) }],
+            rawData: { parseError: String(parseErr) },
             rowIndex,
-          };
-          invalidItemsBatch.push(invalidItemLog);
+          });
+          rowIndex++;
         }
       }
+    } else {
+      // --- CSV path (unchanged) ---
+      let fieldMap: Record<string, number> = {};
+      let isHeaderProcessed = false;
 
-      rowIndex++;
+      const parser = parse({
+        relax_column_count: true,
+        relax_quotes: true,
+        skip_empty_lines: true,
+        skip_records_with_error: true,
+        on_skip: (err) => {
+          const parserLine = (err as { lines?: number } | undefined)?.lines ?? rowIndex;
+          const message = err?.message ?? 'unknown parse error';
+          const parseErrorLog: NewInvalidItemLog = {
+            jobId,
+            errors: [{ field: 'csv_parse', reason: message }],
+            rawData: { parseError: message },
+            rowIndex: parserLine,
+          };
+          invalidItemsBatch.push(parseErrorLog);
+          console.warn(`[ETL] Skipped malformed CSV row at parser line ${parserLine}: ${message}`);
+        },
+      });
 
-      // Flush valid batch to DB every BATCH_SIZE rows to avoid Worker OOM on large files.
-      // totalProcessed is incremented atomically inside processValidItemsBatch via updateEtlJobProgress.
-      if (validItemsBatch.length >= BATCH_SIZE) {
-        await processValidItemsBatch({ jobId, items: [...validItemsBatch], env });
-        validItemsBatch.length = 0;
-      }
-      // Flush invalid batch to DB every BATCH_SIZE rows.
-      // totalProcessed is incremented atomically inside processLogsBatch via updateEtlJobProgress.
-      if (invalidItemsBatch.length >= BATCH_SIZE) {
-        await processLogsBatch({ jobId, logs: [...invalidItemsBatch], env });
-        invalidItemsBatch.length = 0;
+      const writerPromise = (async () => {
+        // Non-first chunks: inject the header row so csv-parse sees a valid header,
+        // then skip the partial row at the chunk boundary (tail of the previous chunk).
+        if (injectedHeader) {
+          parser.write(`${injectedHeader}\n`);
+        }
+        let skipPartialRow = byteStart !== undefined && byteStart > 0;
+
+        for await (const chunk of streamToText(r2Object.body)) {
+          let text = chunk;
+
+          if (skipPartialRow) {
+            // Discard bytes up to and including the first newline — those bytes are
+            // the tail of the row that the previous chunk already processed.
+            const nl = text.indexOf('\n');
+            if (nl === -1) continue; // entire buffer is still the partial row tail
+            text = text.slice(nl + 1);
+            skipPartialRow = false;
+            if (!text) continue;
+          }
+
+          // Respect backpressure: if the parser buffer is full, wait for drain before
+          // pushing more data. Without this, R2 fills the parser buffer for the entire
+          // file (up to 600 MB) before the main loop processes any rows → Worker OOM.
+          const ok = parser.write(text);
+          if (!ok) await new Promise<void>((resolve) => parser.once('drain', resolve));
+        }
+        parser.end();
+      })().catch((err) => {
+        parser.destroy(err instanceof Error ? err : new Error(String(err)));
+        throw err;
+      });
+
+      for await (const record of parser) {
+        if (rowIndex % 100 === 0) await new Promise((resolve) => setTimeout(resolve, 1)); // Yield every 100 rows for GC; per-row yield hits the CF Worker wall-clock limit on large files
+        const row = record as string[];
+        if (!isHeaderProcessed) {
+          fieldMap = row.reduce<Record<string, number>>((acc, header, idx) => {
+            acc[header.trim()] = idx;
+            return acc;
+          }, {});
+          isHeaderProcessed = true;
+          console.log(
+            `🔍 [TRACE] Header processed - fields: ${Object.keys(fieldMap).length}, mapping:`,
+            Object.keys(fieldMap),
+          );
+          continue;
+        }
+
+        const item = mapCsvRowToItem({ values: row, fieldMap });
+
+        if (item) {
+          const validatedItem = validator.validateItem(item);
+
+          if (validatedItem.isValid) {
+            validItemsBatch.push(validatedItem.item);
+          } else {
+            const invalidItemLog = {
+              jobId,
+              errors: validatedItem.errors,
+              rawData: validatedItem.item,
+              rowIndex,
+            };
+            invalidItemsBatch.push(invalidItemLog);
+          }
+        }
+
+        rowIndex++;
+
+        // Flush valid batch to DB every BATCH_SIZE rows to avoid Worker OOM on large files.
+        // totalProcessed is incremented atomically inside processValidItemsBatch via updateEtlJobProgress.
+        if (validItemsBatch.length >= BATCH_SIZE) {
+          await processValidItemsBatch({ jobId, items: [...validItemsBatch], env });
+          validItemsBatch.length = 0;
+        }
+        // Flush invalid batch to DB every BATCH_SIZE rows.
+        // totalProcessed is incremented atomically inside processLogsBatch via updateEtlJobProgress.
+        if (invalidItemsBatch.length >= BATCH_SIZE) {
+          await processLogsBatch({ jobId, logs: [...invalidItemsBatch], env });
+          invalidItemsBatch.length = 0;
+        }
       }
+
+      await writerPromise;
     }
 
     console.log(`🔍 [TRACE] Streaming complete - processing remaining batches`);
diff --git a/packages/api/src/services/etl/processLogsBatch.ts b/packages/api/src/services/etl/processLogsBatch.ts
index f8e7868107..f2e837c3bd 100644
--- a/packages/api/src/services/etl/processLogsBatch.ts
+++ b/packages/api/src/services/etl/processLogsBatch.ts
@@ -1,6 +1,7 @@
+import { createDbClient } from '@packrat/api/db';
 import type { Env } from '@packrat/api/utils/env-validation';
+import { logger } from '@packrat/api/utils/logger';
 import { invalidItemLogs, type NewInvalidItemLog } from '@packrat/db';
-import { createDbClient } from '../../db';
 import { updateEtlJobProgress } from './updateEtlJobProgress';
 
 export async function processLogsBatch({
@@ -13,6 +14,7 @@ export async function processLogsBatch({
   env: Env;
 }): Promise<void> {
   const db = createDbClient(env);
+
   try {
     await db.insert(invalidItemLogs).values(logs);
     await updateEtlJobProgress({
@@ -24,8 +26,16 @@ export async function processLogsBatch({
       },
     });
 
-    console.log(`📝 Processed and wrote ${logs.length} invalid items for job ${jobId}`);
+    logger.info({ event: 'etl.invalid_logs.persisted', ctx: { jobId, count: logs.length } });
   } catch (error) {
-    console.error(`Failed to process log message:`, error);
+    // Rethrow — invalid_item_logs is the forensic record of what failed
+    // validation. Silently swallowing a DB write loss here means an
+    // operator chasing a data-quality complaint has no trail. Closes
+    // audit P2 #2.
+    logger.error({
+      event: 'etl.invalid_logs.persist_failed',
+      ctx: { jobId, count: logs.length, err: error },
+    });
+    throw error;
   }
 }
diff --git a/packages/api/src/services/etl/processValidItemsBatch.ts b/packages/api/src/services/etl/processValidItemsBatch.ts
index 96232c080e..e6690e9f41 100644
--- a/packages/api/src/services/etl/processValidItemsBatch.ts
+++ b/packages/api/src/services/etl/processValidItemsBatch.ts
@@ -1,6 +1,9 @@
+import { createDbClient } from '@packrat/api/db';
 import { getEmbeddingText } from '@packrat/api/utils/embeddingHelper';
 import type { Env } from '@packrat/api/utils/env-validation';
-import type { NewCatalogItem } from '@packrat/db';
+import { logger } from '@packrat/api/utils/logger';
+import { etlJobs, type NewCatalogItem } from '@packrat/db';
+import { eq, sql } from 'drizzle-orm';
 import { CatalogService } from '../catalogService';
 import { generateManyEmbeddings } from '../embeddingService';
 import { mergeItemsBySku } from './mergeItemsBySku';
@@ -54,8 +57,19 @@ export async function processValidItemsBatch({
       },
     });
   } catch (error) {
-    console.error(`Error generating embeddings for batch ${jobId}:`, error);
-    // Fall back to processing without embeddings
+    // Embedding-fallback path. The upsert still happens (catalog gets the
+    // items minus their vectors), but we record the degradation on
+    // etl_jobs.total_embedding_failures so operators see the count via
+    // the admin endpoint without trawling logs. Closes audit P2 #3.
+    logger.warn({
+      event: 'etl.embedding.fallback',
+      ctx: {
+        jobId,
+        skuCount: items.length,
+        errorName: error instanceof Error ? error.name : 'unknown',
+      },
+    });
+
     const upsertedItems = await catalogService.upsertCatalogItems(mergedItems);
     await catalogService.trackEtlJob({ itemIds: upsertedItems, jobId });
     await updateEtlJobProgress({
@@ -66,7 +80,15 @@ export async function processValidItemsBatch({
         processed: items.length,
       },
     });
+
+    const db = createDbClient(env);
+    await db
+      .update(etlJobs)
+      .set({
+        totalEmbeddingFailures: sql`COALESCE(${etlJobs.totalEmbeddingFailures}, 0) + ${items.length}`,
+      })
+      .where(eq(etlJobs.id, jobId));
   } finally {
-    console.log(`📦 Batch ${jobId}: Processed ${items.length} valid items`);
+    logger.info({ event: 'etl.valid_items.batch_complete', ctx: { jobId, count: items.length } });
   }
 }
diff --git a/packages/api/src/services/imageDetectionService.ts b/packages/api/src/services/imageDetectionService.ts
index 71cfe51eb4..eb94498f44 100644
--- a/packages/api/src/services/imageDetectionService.ts
+++ b/packages/api/src/services/imageDetectionService.ts
@@ -24,11 +24,11 @@ const detectedItemSchema = z.object({
   description: z
     .string()
     .describe('Brief description including key characteristics optimized for catalog search'),
-  quantity: z.number().int().positive().default(1).describe('Number of this item visible'),
+  quantity: z.number().int().positive().describe('Number of this item visible'),
   category: z.string().describe('Category of outdoor gear (e.g., Sleep System, Clothing, etc.)'),
-  consumable: z.boolean().default(false).describe('Whether the item is consumable'),
-  worn: z.boolean().default(false).describe('Whether the item is worn'),
-  notes: z.string().nullable().optional(),
+  consumable: z.boolean().describe('Whether the item is consumable'),
+  worn: z.boolean().describe('Whether the item is worn'),
+  notes: z.string().nullable().describe('Additional notes, or null if none'),
   confidence: z.number().min(0).max(1).describe('Confidence level in the identification (0-1)'),
 });
 
diff --git a/packages/api/src/services/r2-bucket.ts b/packages/api/src/services/r2-bucket.ts
index 8aab0e06fd..21839a6add 100644
--- a/packages/api/src/services/r2-bucket.ts
+++ b/packages/api/src/services/r2-bucket.ts
@@ -14,6 +14,7 @@ import {
 } from '@aws-sdk/client-s3';
 import type { Env } from '@packrat/api/utils/env-validation';
 import { isDate, isFunction, isNumber, isObject, isString } from '@packrat/guards';
+import { safeJsonParse } from '@packrat/utils';
 
 // ── ETag normalization ────────────────────────────────────────────────
 const STRIP_DOUBLE_QUOTES = /"/g;
@@ -334,7 +335,9 @@ export class R2BucketService {
         },
         json: async <T>() => {
           assertStreamNotConsumed();
-          return JSON.parse(new TextDecoder().decode(await consumeStream())) as T; // safe-cast: caller-provided generic boundary — R2ObjectBody.json<T>() mirrors the R2 platform API
+          return safeJsonParse(new TextDecoder().decode(await consumeStream()), {
+            strict: true,
+          }) as T; // safe-cast: caller-provided generic boundary — R2ObjectBody.json<T>() mirrors the R2 platform API
         },
         blob: async () => {
           assertStreamNotConsumed();
@@ -436,9 +439,9 @@ export class R2BucketService {
         CacheControl: httpMetadata?.cacheControl,
         Expires: httpMetadata?.cacheExpiry,
         Metadata: options?.customMetadata,
-        ContentMD5: typeof options?.md5 === 'string' ? options.md5 : undefined,
-        ChecksumSHA1: typeof options?.sha1 === 'string' ? options.sha1 : undefined,
-        ChecksumSHA256: typeof options?.sha256 === 'string' ? options.sha256 : undefined,
+        ContentMD5: isString(options?.md5) ? options.md5 : undefined,
+        ChecksumSHA1: isString(options?.sha1) ? options.sha1 : undefined,
+        ChecksumSHA256: isString(options?.sha256) ? options.sha256 : undefined,
       });
 
       const response = await this.s3Client.send(command);
diff --git a/packages/api/src/services/retention/__tests__/invalidLogRetention.test.ts b/packages/api/src/services/retention/__tests__/invalidLogRetention.test.ts
new file mode 100644
index 0000000000..5011e2d014
--- /dev/null
+++ b/packages/api/src/services/retention/__tests__/invalidLogRetention.test.ts
@@ -0,0 +1,90 @@
+// Unit tests for the invalid_item_logs retention sweep.
+//
+// The function's behavior with real DB rows is covered by integration tests
+// (test/etl-log-retention.test.ts). These unit tests stub createDbClient to
+// verify the loop semantics — stop on empty batch, iteration cap, and the
+// returned RetentionResult shape — without touching Postgres.
+
+import { sweepInvalidItemLogs } from '@packrat/api/services/retention/invalidLogRetention';
+import type { Env } from '@packrat/api/utils/env-validation';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+type FakeRow = { id: number };
+
+// Hoisted state shared between the mock factory and the tests. `vi.mock` calls
+// hoist above imports, so this declaration uses `vi.hoisted` to ensure the
+// mock factory and the test code reference the same array.
+const mockState = vi.hoisted(() => ({
+  batches: [] as FakeRow[][],
+  callCount: 0,
+}));
+
+vi.mock('@packrat/api/db', () => {
+  const mockDb = {
+    select: () => ({ from: () => ({ where: () => ({ limit: () => mockState }) }) }),
+    delete: () => ({
+      where: () => ({
+        returning: async () => {
+          const batch = mockState.batches[mockState.callCount] ?? [];
+          mockState.callCount += 1;
+          return batch;
+        },
+      }),
+    }),
+  };
+  return { createDbClient: () => mockDb };
+});
+
+function setBatches(batches: FakeRow[][]) {
+  mockState.batches = batches;
+  mockState.callCount = 0;
+}
+
+describe('sweepInvalidItemLogs', () => {
+  afterEach(() => {
+    setBatches([]);
+  });
+
+  it('returns deleted=0 / iterations=1 when the first batch is empty', async () => {
+    setBatches([[]]);
+    const result = await sweepInvalidItemLogs({} as Env);
+    expect(result.deleted).toBe(0);
+    expect(result.iterations).toBe(1);
+    expect(result.capped).toBe(false);
+    expect(result.retentionDays).toBe(90);
+  });
+
+  it('accumulates deletions across batches until an empty one stops the loop', async () => {
+    const fullBatch: FakeRow[] = Array.from({ length: 10_000 }, () => ({ id: 1 }));
+    setBatches([fullBatch, fullBatch, [{ id: 1 }], []]);
+
+    const result = await sweepInvalidItemLogs({} as Env);
+
+    expect(result.deleted).toBe(20_001);
+    expect(result.iterations).toBe(4);
+    expect(result.capped).toBe(false);
+  });
+
+  it('caps at maxIterations and reports capped=true', async () => {
+    const fullBatch: FakeRow[] = Array.from({ length: 100 }, () => ({ id: 1 }));
+    setBatches([fullBatch, fullBatch, fullBatch, fullBatch, fullBatch]);
+
+    const result = await sweepInvalidItemLogs({} as Env, { maxIterations: 3 });
+
+    expect(result.iterations).toBe(3);
+    expect(result.capped).toBe(true);
+    expect(result.deleted).toBe(300);
+  });
+
+  it('honors a custom retentionDays option', async () => {
+    setBatches([[]]);
+    const result = await sweepInvalidItemLogs({} as Env, { retentionDays: 30 });
+    expect(result.retentionDays).toBe(30);
+  });
+
+  it('falls back to the default retentionDays when the option is zero or negative', async () => {
+    setBatches([[]]);
+    const result = await sweepInvalidItemLogs({} as Env, { retentionDays: 0 });
+    expect(result.retentionDays).toBe(90);
+  });
+});
diff --git a/packages/api/src/services/retention/invalidLogRetention.ts b/packages/api/src/services/retention/invalidLogRetention.ts
new file mode 100644
index 0000000000..f3fbc1e89a
--- /dev/null
+++ b/packages/api/src/services/retention/invalidLogRetention.ts
@@ -0,0 +1,93 @@
+// Bounded-batch DELETE of expired invalid_item_logs.
+//
+// Each ETL run can produce thousands of invalid_item_logs rows. Left alone
+// the table grows without bound — a single bad scraper upload can be
+// hundreds of MB of jsonb. This sweep is the periodic cleanup.
+//
+// Why batched: a naive `DELETE FROM invalid_item_logs WHERE created_at < ...`
+// on a table that has been accumulating for months would acquire row-level
+// locks on millions of rows in a single statement, hit Neon's statement
+// timeout, and roll back having pruned nothing. The batched loop deletes
+// in 10k-row chunks and bails after a configurable max iteration count so
+// a runaway first-run can't monopolize the daily window.
+
+import { createDbClient } from '@packrat/api/db';
+import type { Env } from '@packrat/api/utils/env-validation';
+import { invalidItemLogs } from '@packrat/db';
+import { inArray, lt, sql } from 'drizzle-orm';
+
+const DEFAULT_RETENTION_DAYS = 90;
+const DEFAULT_BATCH_SIZE = 10_000;
+const DEFAULT_MAX_ITERATIONS = 100;
+
+export type RetentionResult = {
+  /** Total rows deleted across all iterations. */
+  deleted: number;
+  /** How many DELETE batches ran. */
+  iterations: number;
+  /** True if the run hit `maxIterations` before exhausting expired rows; caller should alert. */
+  capped: boolean;
+  /** Effective retention window applied. */
+  retentionDays: number;
+};
+
+export type RetentionOptions = {
+  retentionDays?: number;
+  batchSize?: number;
+  maxIterations?: number;
+};
+
+/**
+ * Delete invalid_item_logs older than the retention window in bounded batches.
+ *
+ * Default retention is 90 days. The default 100-iteration cap × 10k batch
+ * size = up to 1M rows per run. If the table has more expired rows than
+ * that on first execution, the function returns `capped: true` and the
+ * remainder is swept on subsequent runs.
+ */
+export async function sweepInvalidItemLogs(
+  env: Env,
+  options: RetentionOptions = {},
+): Promise<RetentionResult> {
+  const retentionDays =
+    options.retentionDays !== undefined && options.retentionDays > 0
+      ? options.retentionDays
+      : DEFAULT_RETENTION_DAYS;
+  const batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+  const maxIterations = options.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+
+  const db = createDbClient(env);
+
+  let deleted = 0;
+  let iterations = 0;
+  let rowCount = 0;
+  const cutoff = sql`now() - (${retentionDays}::int * interval '1 day')`;
+
+  for (let i = 0; i < maxIterations; i++) {
+    iterations++;
+
+    const selectExpired = db
+      .select({ id: invalidItemLogs.id })
+      .from(invalidItemLogs)
+      .where(lt(invalidItemLogs.createdAt, cutoff))
+      .limit(batchSize);
+
+    const removed = await db
+      .delete(invalidItemLogs)
+      .where(inArray(invalidItemLogs.id, selectExpired))
+      .returning();
+
+    rowCount = removed.length;
+    deleted += rowCount;
+    if (rowCount === 0) break;
+  }
+
+  return {
+    deleted,
+    iterations,
+    // capped only when we hit the iteration ceiling with rows still remaining;
+    // if the last batch returned 0 rows we exhausted the table (not capped).
+    capped: rowCount > 0,
+    retentionDays,
+  };
+}
diff --git a/packages/api/src/services/trails.ts b/packages/api/src/services/trails.ts
index 8b0709b433..85586c8e95 100644
--- a/packages/api/src/services/trails.ts
+++ b/packages/api/src/services/trails.ts
@@ -1,5 +1,6 @@
 import type { createOsmDb } from '@packrat/api/db';
 import type { OsmMember } from '@packrat/schemas/trails';
+import { safeJsonParse } from '@packrat/utils';
 import { sql } from 'drizzle-orm';
 import { z } from 'zod';
 
@@ -52,7 +53,7 @@ export async function stitchRouteGeometry({
   if (!row?.geojson) return null;
 
   try {
-    return JSON.parse(row.geojson);
+    return safeJsonParse(row.geojson, { strict: true });
   } catch {
     return null;
   }
diff --git a/packages/api/src/utils/__tests__/auth.test.ts b/packages/api/src/utils/__tests__/auth.test.ts
index 0da7fc960a..24ce2247ce 100644
--- a/packages/api/src/utils/__tests__/auth.test.ts
+++ b/packages/api/src/utils/__tests__/auth.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { hashPassword, isValidApiKey, verifyPassword } from '../auth';
+import { hashPassword, isValidApiKey, timingSafeEqual, verifyPassword } from '../auth';
 
 vi.mock('bcryptjs', () => ({
   hash: vi.fn((password: string) => Promise.resolve(`hashed_${password}`)),
@@ -63,4 +63,10 @@ describe('auth utilities', () => {
       expect(isValidApiKey({ 'X-API-Key': 'test-api-key' })).toBe(true);
     });
   });
+
+  describe('timingSafeEqual', () => {
+    it('rejects when the first value is longer than the second', () => {
+      expect(timingSafeEqual({ a: 'test-api-key-extra', b: 'test-api-key' })).toBe(false);
+    });
+  });
 });
diff --git a/packages/api/src/utils/__tests__/csv-utils.test.ts b/packages/api/src/utils/__tests__/csv-utils.test.ts
index a9eef86948..c749e90238 100644
--- a/packages/api/src/utils/__tests__/csv-utils.test.ts
+++ b/packages/api/src/utils/__tests__/csv-utils.test.ts
@@ -2,10 +2,10 @@ import { describe, expect, it } from 'vitest';
 import {
   mapCsvRowToItem,
   normalizeJsonString,
+  parseCatalogJson,
   parseFaqs,
   parsePrice,
   parseWeight,
-  safeJsonParse,
 } from '../csv-utils';
 
 // ---------------------------------------------------------------------------
@@ -291,6 +291,15 @@ describe('csv-utils', () => {
       expect(result?.categories).toBeUndefined();
     });
 
+    it('handles blank categories gracefully', () => {
+      const values = ['   '];
+      const fieldMap = { categories: 0 };
+
+      const result = mapCsvRowToItem({ values, fieldMap });
+
+      expect(result?.categories).toBeUndefined();
+    });
+
     it('handles empty images gracefully', () => {
       const values = [''];
       const fieldMap = { images: 0 };
@@ -309,6 +318,42 @@ describe('csv-utils', () => {
       expect(result?.categories).toEqual(['invalid json']);
     });
 
+    it('wraps malformed JSON array categories in an array', () => {
+      const values = ['["Electronics",'];
+      const fieldMap = { categories: 0 };
+
+      const result = mapCsvRowToItem({ values, fieldMap });
+
+      expect(result?.categories).toEqual(['["Electronics",']);
+    });
+
+    it('ignores malformed JSON array images', () => {
+      const values = ['["img1.jpg",'];
+      const fieldMap = { images: 0 };
+
+      const result = mapCsvRowToItem({ values, fieldMap });
+
+      expect(result?.images).toBeUndefined();
+    });
+
+    it('maps array-shaped techs to an empty object', () => {
+      const values = ['["unexpected"]'];
+      const fieldMap = { techs: 0 };
+
+      const result = mapCsvRowToItem({ values, fieldMap });
+
+      expect(result?.techs).toEqual({});
+    });
+
+    it('ignores invalid availability values', () => {
+      const values = ['not_available'];
+      const fieldMap = { availability: 0 };
+
+      const result = mapCsvRowToItem({ values, fieldMap });
+
+      expect(result?.availability).toBeUndefined();
+    });
+
     it('processes description with newlines correctly', () => {
       const values = ['This is a\r\nmultiline\ndescription'];
       const fieldMap = { description: 0 };
@@ -523,35 +568,35 @@ describe('csv-utils', () => {
     });
   });
 
-  describe('safeJsonParse', () => {
+  describe('parseCatalogJson', () => {
     it('parses valid JSON', () => {
-      const result = safeJsonParse('{"key": "value"}');
+      const result = parseCatalogJson('{"key": "value"}');
       expect(result).toEqual({ key: 'value' });
     });
 
     it('returns empty array for invalid JSON', () => {
-      const result = safeJsonParse('invalid json');
+      const result = parseCatalogJson('invalid json');
       expect(result).toEqual([]);
     });
 
     it('returns empty array for empty string', () => {
-      expect(safeJsonParse('')).toEqual([]);
-      expect(safeJsonParse('undefined')).toEqual([]);
-      expect(safeJsonParse('null')).toEqual([]);
+      expect(parseCatalogJson('')).toEqual([]);
+      expect(parseCatalogJson('undefined')).toEqual([]);
+      expect(parseCatalogJson('null')).toEqual([]);
     });
 
     it('normalizes and parses Python-style JSON', () => {
-      const result = safeJsonParse("{'key': True, 'other': None}");
+      const result = parseCatalogJson("{'key': True, 'other': None}");
       expect(result).toEqual({ key: true, other: null });
     });
 
     it('handles arrays', () => {
-      const result = safeJsonParse('["a", "b", "c"]');
+      const result = parseCatalogJson('["a", "b", "c"]');
       expect(result).toEqual(['a', 'b', 'c']);
     });
 
     it('returns empty array on parse error', () => {
-      const result = safeJsonParse('{invalid: json}');
+      const result = parseCatalogJson('{invalid: json}');
       expect(result).toEqual([]);
     });
   });
diff --git a/packages/api/src/utils/__tests__/embeddingHelper.test.ts b/packages/api/src/utils/__tests__/embeddingHelper.test.ts
index b5bcf803be..919f6a49be 100644
--- a/packages/api/src/utils/__tests__/embeddingHelper.test.ts
+++ b/packages/api/src/utils/__tests__/embeddingHelper.test.ts
@@ -279,5 +279,23 @@ describe('embeddingHelper', () => {
       const result = getEmbeddingText({ item, existingItem });
       expect(result).toContain('Headwear');
     });
+
+    it('handles variant with string values (not array) on item', () => {
+      const item = {
+        name: 'Pants',
+        variants: [{ attribute: 'Color', values: 'Black' as unknown as string[] }],
+      };
+      const result = getEmbeddingText({ item });
+      expect(result).toContain('Color: Black');
+    });
+
+    it('handles variant with string values (not array) on existingItem', () => {
+      const item = { name: 'Pants' };
+      const existingItem = {
+        variants: [{ attribute: 'Size', values: 'Large' as unknown as string[] }],
+      };
+      const result = getEmbeddingText({ item, existingItem });
+      expect(result).toContain('Size: Large');
+    });
   });
 });
diff --git a/packages/api/src/utils/__tests__/json-utils.test.ts b/packages/api/src/utils/__tests__/json-utils.test.ts
new file mode 100644
index 0000000000..b5b593dc51
--- /dev/null
+++ b/packages/api/src/utils/__tests__/json-utils.test.ts
@@ -0,0 +1,254 @@
+import { describe, expect, it } from 'vitest';
+import { isJsonlFile, mapJsonRowToItem } from '../json-utils';
+
+describe('json-utils', () => {
+  describe('isJsonlFile', () => {
+    it('returns true for .jsonl extension', () => {
+      expect(isJsonlFile('v2/brand/file.jsonl')).toBe(true);
+    });
+
+    it('returns true for .ndjson extension', () => {
+      expect(isJsonlFile('v2/brand/file.ndjson')).toBe(true);
+    });
+
+    it('returns true for uppercase extensions', () => {
+      expect(isJsonlFile('FILE.JSONL')).toBe(true);
+      expect(isJsonlFile('FILE.NDJSON')).toBe(true);
+    });
+
+    it('returns false for .csv extension', () => {
+      expect(isJsonlFile('v2/brand/file.csv')).toBe(false);
+    });
+
+    it('returns false for .json extension', () => {
+      expect(isJsonlFile('v2/brand/file.json')).toBe(false);
+    });
+  });
+
+  describe('mapJsonRowToItem', () => {
+    it('maps basic string scalar fields', () => {
+      const result = mapJsonRowToItem({
+        name: '  Trail Shoe  ',
+        brand: 'Salomon',
+        model: 'XT-6',
+        color: 'Black',
+        size: 'M',
+        sku: 'SKU-001',
+        productSku: 'PROD-001',
+        seller: 'REI',
+        material: 'Mesh',
+        condition: 'new',
+        currency: 'USD',
+        productUrl: '  https://example.com  ',
+      });
+
+      expect(result).toMatchObject({
+        name: 'Trail Shoe',
+        brand: 'Salomon',
+        model: 'XT-6',
+        color: 'Black',
+        size: 'M',
+        sku: 'SKU-001',
+        productSku: 'PROD-001',
+        seller: 'REI',
+        material: 'Mesh',
+        condition: 'new',
+        currency: 'USD',
+        productUrl: 'https://example.com',
+      });
+    });
+
+    it('strips newlines from description', () => {
+      const result = mapJsonRowToItem({
+        description: 'Line one\nLine two\r\nLine three',
+      });
+      expect(result?.description).toBe('Line one Line two Line three');
+    });
+
+    it('maps reviewCount from number', () => {
+      const result = mapJsonRowToItem({ reviewCount: 42.9 });
+      expect(result?.reviewCount).toBe(42);
+    });
+
+    it('maps reviewCount from string', () => {
+      const result = mapJsonRowToItem({ reviewCount: '128' });
+      expect(result?.reviewCount).toBe(128);
+    });
+
+    it('defaults reviewCount to 0 for invalid strings', () => {
+      const result = mapJsonRowToItem({ reviewCount: 'not-a-number' });
+      expect(result?.reviewCount).toBe(0);
+    });
+
+    it('defaults reviewCount to 0 for missing value', () => {
+      const result = mapJsonRowToItem({});
+      expect(result?.reviewCount).toBe(0);
+    });
+
+    it('maps price from number', () => {
+      const result = mapJsonRowToItem({ price: 149.99 });
+      expect(result?.price).toBe(149.99);
+    });
+
+    it('maps price from string', () => {
+      const result = mapJsonRowToItem({ price: '$129.00' });
+      expect(result?.price).toBeCloseTo(129.0);
+    });
+
+    it('ignores invalid price strings', () => {
+      const result = mapJsonRowToItem({ price: 'contact for price' });
+      expect(result?.price).toBeUndefined();
+    });
+
+    it('maps ratingValue from number', () => {
+      const result = mapJsonRowToItem({ ratingValue: 4.5 });
+      expect(result?.ratingValue).toBe(4.5);
+    });
+
+    it('maps ratingValue from string', () => {
+      const result = mapJsonRowToItem({ ratingValue: '4.2' });
+      expect(result?.ratingValue).toBeCloseTo(4.2);
+    });
+
+    it('sets ratingValue to null for invalid string', () => {
+      const result = mapJsonRowToItem({ ratingValue: 'N/A' });
+      expect(result?.ratingValue).toBeNull();
+    });
+
+    it('passes categories array through', () => {
+      const result = mapJsonRowToItem({ categories: ['Footwear', 'Trail Running'] });
+      expect(result?.categories).toEqual(['Footwear', 'Trail Running']);
+    });
+
+    it('filters non-string values from categories array', () => {
+      const result = mapJsonRowToItem({ categories: ['Footwear', 42, null, 'Trail'] });
+      expect(result?.categories).toEqual(['Footwear', 'Trail']);
+    });
+
+    it('splits categories from comma-separated string', () => {
+      const result = mapJsonRowToItem({ categories: 'Footwear, Trail Running' });
+      expect(result?.categories).toEqual(['Footwear', 'Trail Running']);
+    });
+
+    it('parses categories from JSON array string', () => {
+      const result = mapJsonRowToItem({ categories: '["Footwear","Trail Running"]' });
+      expect(result?.categories).toEqual(['Footwear', 'Trail Running']);
+    });
+
+    it('filters non-strings from JSON array string categories', () => {
+      const result = mapJsonRowToItem({ categories: '["Footwear",42,null]' });
+      expect(result?.categories).toEqual(['Footwear']);
+    });
+
+    it('wraps malformed JSON array categories in an array', () => {
+      const result = mapJsonRowToItem({ categories: '["Footwear",' });
+      expect(result?.categories).toEqual(['["Footwear",']);
+    });
+
+    it('wraps unparseable categories string in array', () => {
+      const result = mapJsonRowToItem({ categories: 'Footwear' });
+      expect(result?.categories).toEqual(['Footwear']);
+    });
+
+    it('ignores blank category strings', () => {
+      const result = mapJsonRowToItem({ categories: '   ' });
+      expect(result?.categories).toBeUndefined();
+    });
+
+    it('passes images array through, filtering non-strings', () => {
+      const result = mapJsonRowToItem({ images: ['https://img1.jpg', 42, 'https://img2.jpg'] });
+      expect(result?.images).toEqual(['https://img1.jpg', 'https://img2.jpg']);
+    });
+
+    it('maps weight from number with unit string', () => {
+      const result = mapJsonRowToItem({ weight: 280, weightUnit: 'g' });
+      expect(result?.weight).toBeGreaterThan(0);
+      expect(result?.weightUnit).toBeDefined();
+    });
+
+    it('maps weight from string', () => {
+      const result = mapJsonRowToItem({ weight: '1.5 lbs' });
+      expect(result?.weight).toBeGreaterThan(0);
+    });
+
+    it('ignores non-positive weight strings', () => {
+      const result = mapJsonRowToItem({ weight: '-1 lb' });
+      expect(result?.weight).toBeUndefined();
+      expect(result?.weightUnit).toBeUndefined();
+    });
+
+    it('ignores weight of zero', () => {
+      const result = mapJsonRowToItem({ weight: 0 });
+      expect(result?.weight).toBeUndefined();
+    });
+
+    it('passes variants, links, reviews, qas arrays through', () => {
+      const variants = [{ color: 'Red' }];
+      const links = [{ url: 'https://example.com' }];
+      const reviews = [{ text: 'Great!' }];
+      const qas = [{ question: 'Size?', answer: 'True to size' }];
+      const result = mapJsonRowToItem({ variants, links, reviews, qas });
+      expect(result?.variants).toBe(variants);
+      expect(result?.links).toBe(links);
+      expect(result?.reviews).toBe(reviews);
+      expect(result?.qas).toBe(qas);
+    });
+
+    it('passes faqs array through', () => {
+      const faqs = [{ question: 'Is it waterproof?', answer: 'Yes' }];
+      const result = mapJsonRowToItem({ faqs });
+      expect(result?.faqs).toBe(faqs);
+    });
+
+    it('passes techs object through', () => {
+      const techs = { 'Claimed Weight': '280g', Material: 'Mesh' };
+      const result = mapJsonRowToItem({ techs });
+      expect(result?.techs).toEqual(techs);
+    });
+
+    it('parses techs from JSON string', () => {
+      const result = mapJsonRowToItem({
+        techs: '{"Claimed Weight":"280g","Material":"Mesh"}',
+      });
+      expect(result?.techs).toEqual({ 'Claimed Weight': '280g', Material: 'Mesh' });
+    });
+
+    it('maps array-shaped techs strings to an empty object', () => {
+      const result = mapJsonRowToItem({ techs: '["unexpected"]' });
+      expect(result?.techs).toEqual({});
+    });
+
+    it('falls back to weight from techs Claimed Weight field', () => {
+      const result = mapJsonRowToItem({ techs: { 'Claimed Weight': '280g' } });
+      expect(result?.weight).toBeGreaterThan(0);
+    });
+
+    it('falls back to weight from techs weight field', () => {
+      const result = mapJsonRowToItem({ techs: { weight: '1.2 lbs' } });
+      expect(result?.weight).toBeGreaterThan(0);
+    });
+
+    it('maps availability from valid string', () => {
+      const result = mapJsonRowToItem({ availability: 'in_stock' });
+      expect(result?.availability).toBe('in_stock');
+    });
+
+    it('ignores invalid availability value', () => {
+      const result = mapJsonRowToItem({ availability: 'InStock' });
+      expect(result?.availability).toBeUndefined();
+    });
+
+    it('returns empty item for empty input object', () => {
+      const result = mapJsonRowToItem({});
+      expect(result).toBeDefined();
+      expect(result?.reviewCount).toBe(0);
+    });
+
+    it('ignores non-string/non-number values for scalar fields', () => {
+      const result = mapJsonRowToItem({ name: 42, brand: null, price: [] });
+      expect(result?.name).toBeUndefined();
+      expect(result?.brand).toBeUndefined();
+      expect(result?.price).toBeUndefined();
+    });
+  });
+});
diff --git a/packages/api/src/utils/__tests__/logger.test.ts b/packages/api/src/utils/__tests__/logger.test.ts
new file mode 100644
index 0000000000..c1e8cd8e2b
--- /dev/null
+++ b/packages/api/src/utils/__tests__/logger.test.ts
@@ -0,0 +1,221 @@
+// Unit tests for the structured logger.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const sentry = vi.hoisted(() => ({
+  addBreadcrumb: vi.fn(),
+  captureException: vi.fn(),
+  captureMessage: vi.fn(),
+  isInitialized: vi.fn(() => false),
+}));
+
+vi.mock('@sentry/cloudflare', () => sentry);
+
+import { logger } from '@packrat/api/utils/logger';
+
+describe('logger', () => {
+  let logSpy: ReturnType<typeof vi.spyOn>;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    sentry.addBreadcrumb.mockReset();
+    sentry.captureException.mockReset();
+    sentry.captureMessage.mockReset();
+    sentry.isInitialized.mockReset();
+    sentry.isInitialized.mockReturnValue(false);
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+    warnSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  function parseLastLine(spy: ReturnType<typeof vi.spyOn>): Record<string, unknown> {
+    const calls = spy.mock.calls;
+    const last = calls[calls.length - 1];
+    if (!last) throw new Error('expected console output but got none');
+    const arg = last[0];
+    if (typeof arg !== 'string') throw new Error('expected console arg to be a string');
+    return JSON.parse(arg);
+  }
+
+  describe('info', () => {
+    it('emits a JSON line with level=INFO and event', () => {
+      logger.info({ event: 'etl.test' });
+      expect(logSpy).toHaveBeenCalledOnce();
+      const line = parseLastLine(logSpy);
+      expect(line.level).toBe('INFO');
+      expect(line.event).toBe('etl.test');
+      expect(typeof line.ts).toBe('string');
+    });
+
+    it('merges ctx fields into the emitted line', () => {
+      logger.info({ event: 'etl.test', ctx: { jobId: 'j1', count: 42 } });
+      const line = parseLastLine(logSpy);
+      expect(line.jobId).toBe('j1');
+      expect(line.count).toBe(42);
+    });
+
+    it('falls back to a serialization error line when ctx cannot be stringified', () => {
+      const ctx: Record<string, unknown> = {};
+      ctx.self = ctx;
+
+      logger.info({ event: 'etl.circular', ctx: ctx });
+
+      const line = parseLastLine(logSpy);
+      expect(line).toMatchObject({
+        level: 'INFO',
+        event: 'etl.circular',
+        serializationError: true,
+      });
+    });
+  });
+
+  describe('warn', () => {
+    it('emits to console.warn with level=WARN', () => {
+      logger.warn({ event: 'etl.fallback', ctx: { jobId: 'j2' } });
+      expect(warnSpy).toHaveBeenCalledOnce();
+      const line = parseLastLine(warnSpy);
+      expect(line.level).toBe('WARN');
+      expect(line.event).toBe('etl.fallback');
+      expect(line.jobId).toBe('j2');
+    });
+  });
+
+  describe('error', () => {
+    it('emits to console.error with level=ERROR', () => {
+      logger.error({ event: 'etl.failed', ctx: { jobId: 'j3' } });
+      expect(errorSpy).toHaveBeenCalledOnce();
+      const line = parseLastLine(errorSpy);
+      expect(line.level).toBe('ERROR');
+      expect(line.event).toBe('etl.failed');
+      expect(line.jobId).toBe('j3');
+    });
+
+    it('unpacks an Error attached as ctx.err into errorName / errorMessage / errorStack', () => {
+      const err = new Error('boom');
+      err.name = 'BoomError';
+      logger.error({ event: 'etl.failed', ctx: { jobId: 'j4', err } });
+      const line = parseLastLine(errorSpy);
+      expect(line.errorName).toBe('BoomError');
+      expect(line.errorMessage).toBe('boom');
+      expect(typeof line.errorStack).toBe('string');
+      // err should not appear as a raw field
+      expect(line.err).toBeUndefined();
+    });
+
+    it('coerces a non-Error err to a string errorMessage', () => {
+      logger.error({ event: 'etl.failed', ctx: { err: 'plain string' } });
+      const line = parseLastLine(errorSpy);
+      expect(line.errorMessage).toBe('plain string');
+      expect(line.errorName).toBeUndefined();
+    });
+
+    it('omits err-related fields when no err is provided', () => {
+      logger.error({ event: 'etl.failed', ctx: { jobId: 'j5' } });
+      const line = parseLastLine(errorSpy);
+      expect(line.errorName).toBeUndefined();
+      expect(line.errorMessage).toBeUndefined();
+      expect(line.errorStack).toBeUndefined();
+    });
+  });
+
+  describe('sentry forwarding', () => {
+    it('adds info breadcrumbs with primitive tags and complex extras', () => {
+      sentry.isInitialized.mockReturnValue(true);
+
+      logger.info({
+        event: 'etl.started',
+        ctx: {
+          jobId: 'j1',
+          count: 42,
+          dryRun: true,
+          metadata: { source: 'test' },
+        },
+      });
+
+      expect(sentry.addBreadcrumb).toHaveBeenCalledWith({
+        category: 'etl.started',
+        level: 'info',
+        data: {
+          event: 'etl.started',
+          jobId: 'j1',
+          count: '42',
+          dryRun: 'true',
+          metadata: { source: 'test' },
+        },
+      });
+    });
+
+    it('adds warn breadcrumbs at warning level', () => {
+      sentry.isInitialized.mockReturnValue(true);
+
+      logger.warn({ event: 'etl.retry', ctx: { jobId: 'j2' } });
+
+      expect(sentry.addBreadcrumb).toHaveBeenCalledWith({
+        category: 'etl.retry',
+        level: 'warning',
+        data: {
+          event: 'etl.retry',
+          jobId: 'j2',
+        },
+      });
+    });
+
+    it('captures error objects with event tags and extras', () => {
+      sentry.isInitialized.mockReturnValue(true);
+      const err = new Error('boom');
+
+      logger.error({
+        event: 'etl.failed',
+        ctx: {
+          err,
+          jobId: 'j3',
+          metadata: { source: 'test' },
+        },
+      });
+
+      expect(sentry.captureException).toHaveBeenCalledWith(err, {
+        tags: {
+          event: 'etl.failed',
+          jobId: 'j3',
+        },
+        extra: {
+          event: 'etl.failed',
+          metadata: { source: 'test' },
+        },
+      });
+    });
+
+    it('captures error events without error objects as messages', () => {
+      sentry.isInitialized.mockReturnValue(true);
+
+      logger.error({ event: 'etl.failed', ctx: { jobId: 'j4' } });
+
+      expect(sentry.captureMessage).toHaveBeenCalledWith('etl.failed', {
+        level: 'error',
+        tags: {
+          jobId: 'j4',
+        },
+        extra: {
+          event: 'etl.failed',
+        },
+      });
+    });
+
+    it('swallows sentry forwarding failures after console output', () => {
+      sentry.isInitialized.mockReturnValue(true);
+      sentry.addBreadcrumb.mockImplementation(() => {
+        throw new Error('sentry unavailable');
+      });
+
+      expect(() => logger.info({ event: 'etl.best-effort' })).not.toThrow();
+      expect(logSpy).toHaveBeenCalledOnce();
+    });
+  });
+});
diff --git a/packages/api/src/utils/csv-utils.ts b/packages/api/src/utils/csv-utils.ts
index 43daf4deb4..0138d1caf8 100644
--- a/packages/api/src/utils/csv-utils.ts
+++ b/packages/api/src/utils/csv-utils.ts
@@ -1,6 +1,7 @@
 import type { NewCatalogItem } from '@packrat/db';
 import { isString } from '@packrat/guards';
 import { AvailabilitySchema, WeightUnitSchema } from '@packrat/schemas/constants';
+import { safeJsonParse } from '@packrat/utils';
 
 // ── CSV sanitization regex constants ──
 const NEWLINE_CHARS = /[\r\n]+/g;
@@ -57,7 +58,7 @@ export function mapCsvRowToItem({
     if (val) {
       try {
         item.categories = val.startsWith('[')
-          ? JSON.parse(val)
+          ? safeJsonParse<string[]>(val, { strict: true })
           : val
               .split(',')
               .map((v) => v.trim())
@@ -78,7 +79,7 @@ export function mapCsvRowToItem({
       const val = values[fieldMap.images]?.trim();
       if (val) {
         images = val.startsWith('[')
-          ? JSON.parse(val)
+          ? safeJsonParse<string[]>(val, { strict: true })
           : val
               .split(',')
               .map((v) => v.trim())
@@ -112,10 +113,13 @@ export function mapCsvRowToItem({
     const val = values[fieldMap.variants]?.trim();
     if (val) {
       try {
-        item.variants = JSON.parse(val);
+        item.variants = safeJsonParse<NewCatalogItem['variants']>(val, { strict: true });
       } catch {
         try {
-          item.variants = JSON.parse(val.replace(SINGLE_QUOTE_TO_DOUBLE, '"'));
+          item.variants = safeJsonParse<NewCatalogItem['variants']>(
+            val.replace(SINGLE_QUOTE_TO_DOUBLE, '"'),
+            { strict: true },
+          );
         } catch {
           item.variants = [];
         }
@@ -144,7 +148,7 @@ export function mapCsvRowToItem({
     const fieldIndex = fieldMap[field as string];
     if (fieldIndex !== undefined && values[fieldIndex]) {
       try {
-        item[field] = safeJsonParse(values[fieldIndex]);
+        item[field] = parseCatalogJson(values[fieldIndex]);
       } catch {
         item[field] = [];
       }
@@ -155,7 +159,7 @@ export function mapCsvRowToItem({
   const techsStr = fieldMap.techs !== undefined ? values[fieldMap.techs] : undefined;
   if (techsStr) {
     try {
-      const parsed = safeJsonParse<Record<string, string>>(techsStr);
+      const parsed = parseCatalogJson<Record<string, string>>(techsStr);
       item.techs = Array.isArray(parsed) ? {} : parsed;
 
       if (!item.weight && !Array.isArray(parsed)) {
@@ -276,13 +280,21 @@ export function normalizeJsonString(value: string): string {
   );
 }
 
-export function safeJsonParse<T = unknown>(value: string): T | [] {
+/**
+ * Parses a messy, catalog-sourced JSON string: normalizes Python-style values
+ * and smart quotes first, then parses strictly. Returns `[]` for empty/sentinel
+ * inputs or when parsing fails — the empty-array fallback every caller relies
+ * on. Uses the `@packrat/utils` `safeJsonParse` facade (strict mode) so the
+ * underlying parse stays prototype-pollution-safe while still throwing on
+ * invalid input, which this function catches.
+ */
+export function parseCatalogJson<T = unknown>(value: string): T | [] {
   if (!value || value === 'undefined' || value === 'null') return [];
 
   const normalized = normalizeJsonString(value);
 
   try {
-    return JSON.parse(normalized) as T; // safe-cast: caller-provided generic boundary — caller is responsible for type safety
+    return safeJsonParse<T>(normalized, { strict: true });
   } catch (err) {
     console.warn('❌ Failed to parse JSON:', {
       error: err,
diff --git a/packages/api/src/utils/embeddingHelper.ts b/packages/api/src/utils/embeddingHelper.ts
index be6aa9e37d..221851f551 100644
--- a/packages/api/src/utils/embeddingHelper.ts
+++ b/packages/api/src/utils/embeddingHelper.ts
@@ -21,10 +21,20 @@ export const getEmbeddingText = ({
     ('category' in item && item.category) ||
       (existingItem && 'category' in existingItem && existingItem.category),
     ('variants' in item &&
-      item.variants?.map((v) => `${v.attribute}: ${v.values.join(', ')}`).join('; ')) ||
+      item.variants
+        ?.map((v) => {
+          const vals = Array.isArray(v.values) ? v.values : [v.values].filter(Boolean);
+          return `${v.attribute}: ${vals.join(', ')}`;
+        })
+        .join('; ')) ||
       (existingItem &&
         'variants' in existingItem &&
-        existingItem.variants?.map((v) => `${v.attribute}: ${v.values.join(', ')}`).join('; ')),
+        existingItem.variants
+          ?.map((v) => {
+            const vals = Array.isArray(v.values) ? v.values : [v.values].filter(Boolean);
+            return `${v.attribute}: ${vals.join(', ')}`;
+          })
+          .join('; ')),
     ('techs' in item && item.techs
       ? Object.entries(item.techs)
           .map(([k, v]) => `${k}: ${v}`)
diff --git a/packages/api/src/utils/env-validation.ts b/packages/api/src/utils/env-validation.ts
index 1d4e9a37a4..a271112d88 100644
--- a/packages/api/src/utils/env-validation.ts
+++ b/packages/api/src/utils/env-validation.ts
@@ -79,6 +79,7 @@ export const apiEnvObjectSchema = z.object({
   ETL_QUEUE: z.unknown(),
   LOGS_QUEUE: z.unknown(),
   EMBEDDINGS_QUEUE: z.unknown(),
+  ETL_WORKFLOW: z.unknown(),
   // App container Durable Object binding (APP_CONTAINER)
   APP_CONTAINER: z.unknown(),
   // Rate limiting binding (optional — not present in local dev/test)
@@ -109,6 +110,7 @@ const testEnvSchema = apiEnvObjectSchema.partial().extend({
   ETL_QUEUE: z.unknown().optional(),
   LOGS_QUEUE: z.unknown().optional(),
   EMBEDDINGS_QUEUE: z.unknown().optional(),
+  ETL_WORKFLOW: z.unknown().optional(),
   APP_CONTAINER: z.unknown().optional(),
   AUTH_KV: z.unknown().optional(),
 });
@@ -126,6 +128,7 @@ export type ValidatedEnv = Omit<
   | 'ETL_QUEUE'
   | 'LOGS_QUEUE'
   | 'EMBEDDINGS_QUEUE'
+  | 'ETL_WORKFLOW'
   | 'APP_CONTAINER'
   | 'TOKEN_RATE_LIMITER'
   | 'AUTH_KV'
@@ -138,6 +141,7 @@ export type ValidatedEnv = Omit<
   ETL_QUEUE: Queue;
   LOGS_QUEUE: Queue;
   EMBEDDINGS_QUEUE: Queue;
+  ETL_WORKFLOW: Workflow;
   APP_CONTAINER: DurableObjectNamespace<Container<unknown>>;
   TOKEN_RATE_LIMITER?: { limit(opts: { key: string }): Promise<{ success: boolean }> };
   OSM_HYPERDRIVE?: Hyperdrive;
@@ -178,6 +182,7 @@ function validate(rawEnv: Record<string, unknown>): ValidatedEnv {
     ETL_QUEUE: (rawEnv.ETL_QUEUE ?? validated.data.ETL_QUEUE) as Queue, // safe-cast: Cloudflare Worker binding injected by runtime
     LOGS_QUEUE: (rawEnv.LOGS_QUEUE ?? validated.data.LOGS_QUEUE) as Queue, // safe-cast: Cloudflare Worker binding injected by runtime
     EMBEDDINGS_QUEUE: (rawEnv.EMBEDDINGS_QUEUE ?? validated.data.EMBEDDINGS_QUEUE) as Queue, // safe-cast: Cloudflare Worker binding injected by runtime
+    ETL_WORKFLOW: (rawEnv.ETL_WORKFLOW ?? validated.data.ETL_WORKFLOW) as Workflow, // safe-cast: Cloudflare Worker binding injected by runtime
     // safe-cast: Cloudflare Worker binding injected by runtime
     APP_CONTAINER: (rawEnv.APP_CONTAINER ?? validated.data.APP_CONTAINER) as DurableObjectNamespace<
       Container<unknown>
diff --git a/packages/api/src/utils/json-utils.ts b/packages/api/src/utils/json-utils.ts
new file mode 100644
index 0000000000..13c407b724
--- /dev/null
+++ b/packages/api/src/utils/json-utils.ts
@@ -0,0 +1,207 @@
+import { parseCatalogJson, parseFaqs, parsePrice, parseWeight } from '@packrat/api/utils/csv-utils';
+import type { NewCatalogItem } from '@packrat/db';
+import { isNumber, isObject, isString, toStringRecord } from '@packrat/guards';
+import { AvailabilitySchema, WeightUnitSchema } from '@packrat/schemas/constants';
+import { safeJsonParse } from '@packrat/utils';
+
+// Module-level regex constant (Biome useTopLevelRegex)
+const NEWLINE_CHARS = /[\r\n]+/g;
+
+/**
+ * Returns true if the R2 object key has a JSONL or NDJSON extension.
+ */
+export function isJsonlFile(objectKey: string): boolean {
+  const lower = objectKey.toLowerCase();
+  return lower.endsWith('.jsonl') || lower.endsWith('.ndjson');
+}
+
+/**
+ * Maps a parsed JSON object (one line from a JSONL file) to a partial catalog item.
+ * Uses `unknown` with proper type narrowing — no `any`.
+ */
+export function mapJsonRowToItem(obj: Record<string, unknown>): Partial<NewCatalogItem> | null {
+  const item: Partial<NewCatalogItem> = {};
+
+  // --- String scalar fields ---
+  const rawName = obj.name;
+  if (isString(rawName)) item.name = rawName.trim();
+
+  const rawProductUrl = obj.productUrl;
+  if (isString(rawProductUrl)) item.productUrl = rawProductUrl.trim();
+
+  const rawCurrency = obj.currency;
+  if (isString(rawCurrency)) item.currency = rawCurrency.trim();
+
+  const rawBrand = obj.brand;
+  if (isString(rawBrand)) item.brand = rawBrand.trim();
+
+  const rawModel = obj.model;
+  if (isString(rawModel)) item.model = rawModel.trim();
+
+  const rawColor = obj.color;
+  if (isString(rawColor)) item.color = rawColor.trim();
+
+  const rawSize = obj.size;
+  if (isString(rawSize)) item.size = rawSize.trim();
+
+  const rawSku = obj.sku;
+  if (isString(rawSku)) item.sku = rawSku.trim();
+
+  const rawProductSku = obj.productSku;
+  if (isString(rawProductSku)) item.productSku = rawProductSku.trim();
+
+  const rawSeller = obj.seller;
+  if (isString(rawSeller)) item.seller = rawSeller.trim();
+
+  const rawMaterial = obj.material;
+  if (isString(rawMaterial)) item.material = rawMaterial.trim();
+
+  const rawCondition = obj.condition;
+  if (isString(rawCondition)) item.condition = rawCondition.trim();
+
+  // --- Description: strip newline chars ---
+  const rawDescription = obj.description;
+  if (isString(rawDescription)) {
+    item.description = rawDescription.replace(NEWLINE_CHARS, ' ').trim();
+  }
+
+  // --- reviewCount: direct number or parse from string ---
+  const rawReviewCount = obj.reviewCount;
+  if (isNumber(rawReviewCount)) {
+    item.reviewCount = Math.trunc(rawReviewCount) || 0;
+  } else if (isString(rawReviewCount)) {
+    item.reviewCount = parseInt(rawReviewCount, 10) || 0;
+  } else {
+    item.reviewCount = 0;
+  }
+
+  // --- price: direct number or parsePrice from string ---
+  const rawPrice = obj.price;
+  if (isNumber(rawPrice)) {
+    item.price = rawPrice;
+  } else if (isString(rawPrice)) {
+    item.price = parsePrice(rawPrice) ?? undefined;
+  }
+
+  // --- ratingValue: direct number or parseFloat from string ---
+  const rawRatingValue = obj.ratingValue;
+  if (isNumber(rawRatingValue)) {
+    item.ratingValue = rawRatingValue;
+  } else if (isString(rawRatingValue)) {
+    const parsed = parseFloat(rawRatingValue);
+    item.ratingValue = Number.isNaN(parsed) ? null : parsed;
+  }
+
+  // --- categories: array passthrough or split string ---
+  const rawCategories = obj.categories;
+  if (Array.isArray(rawCategories)) {
+    item.categories = rawCategories.filter((c): c is string => isString(c));
+  } else if (isString(rawCategories) && rawCategories.trim()) {
+    const val = rawCategories.trim();
+    try {
+      item.categories = val.startsWith('[')
+        ? safeJsonParse<unknown[]>(val, { strict: true }).filter((c): c is string => isString(c))
+        : val
+            .split(',')
+            .map((v) => v.trim())
+            .filter(Boolean);
+    } catch {
+      item.categories = [val];
+    }
+  }
+
+  // --- images: array passthrough ---
+  const rawImages = obj.images;
+  if (Array.isArray(rawImages)) {
+    item.images = rawImages.filter((i): i is string => isString(i));
+  }
+
+  // --- weight + weightUnit ---
+  const rawWeight = obj.weight;
+  const rawWeightUnit = obj.weightUnit;
+  const unitStr = isString(rawWeightUnit) ? rawWeightUnit : undefined;
+
+  if (isNumber(rawWeight) && rawWeight > 0) {
+    const { weight, unit } = parseWeight({ weightStr: String(rawWeight), unitStr });
+    item.weight = weight ?? undefined;
+    const parsedUnit = WeightUnitSchema.safeParse(unit);
+    item.weightUnit = parsedUnit.success ? parsedUnit.data : undefined;
+  } else if (isString(rawWeight) && parseFloat(rawWeight) > 0) {
+    const { weight, unit } = parseWeight({ weightStr: rawWeight, unitStr });
+    item.weight = weight ?? undefined;
+    const parsedUnit = WeightUnitSchema.safeParse(unit);
+    item.weightUnit = parsedUnit.success ? parsedUnit.data : undefined;
+  }
+
+  // --- variants: passthrough as-is (already objects) ---
+  const rawVariants = obj.variants;
+  if (Array.isArray(rawVariants)) {
+    item.variants = rawVariants as NewCatalogItem['variants'];
+  }
+
+  // --- links: passthrough ---
+  const rawLinks = obj.links;
+  if (Array.isArray(rawLinks)) {
+    item.links = rawLinks as NewCatalogItem['links'];
+  }
+
+  // --- reviews: passthrough ---
+  const rawReviews = obj.reviews;
+  if (Array.isArray(rawReviews)) {
+    item.reviews = rawReviews as NewCatalogItem['reviews'];
+  }
+
+  // --- qas: passthrough ---
+  const rawQas = obj.qas;
+  if (Array.isArray(rawQas)) {
+    item.qas = rawQas as NewCatalogItem['qas'];
+  }
+
+  // --- faqs: array passthrough or parseFaqs from string ---
+  const rawFaqs = obj.faqs;
+  if (Array.isArray(rawFaqs)) {
+    item.faqs = rawFaqs as NewCatalogItem['faqs'];
+  } else if (isString(rawFaqs) && rawFaqs.trim()) {
+    try {
+      item.faqs = parseFaqs(rawFaqs);
+    } catch {
+      item.faqs = [];
+    }
+  }
+
+  // --- techs: passthrough ---
+  const rawTechs = obj.techs;
+  if (isObject(rawTechs)) {
+    item.techs = toStringRecord(rawTechs);
+  } else if (isString(rawTechs) && rawTechs.trim()) {
+    try {
+      const parsed = parseCatalogJson<Record<string, string>>(rawTechs);
+      item.techs = Array.isArray(parsed) ? {} : toStringRecord(parsed);
+    } catch {
+      item.techs = {};
+    }
+  }
+
+  // --- weight fallback from techs (same as CSV path) ---
+  if (!item.weight && item.techs && isObject(item.techs)) {
+    const techs = toStringRecord(item.techs);
+    const claimedWeight = techs['Claimed Weight'] ?? techs.weight;
+    if (claimedWeight) {
+      const { weight, unit } = parseWeight({ weightStr: claimedWeight });
+      item.weight = weight ?? undefined;
+      const parsedUnit = WeightUnitSchema.safeParse(unit);
+      item.weightUnit = parsedUnit.success ? parsedUnit.data : undefined;
+    }
+  }
+
+  // --- availability: string → AvailabilitySchema.safeParse ---
+  const rawAvailability = obj.availability;
+  if (isString(rawAvailability) && rawAvailability.trim()) {
+    const parsedAvailability = AvailabilitySchema.safeParse(rawAvailability.trim());
+    if (parsedAvailability.success) {
+      item.availability = parsedAvailability.data;
+    }
+  }
+
+  return item;
+}
diff --git a/packages/api/src/utils/logger.ts b/packages/api/src/utils/logger.ts
new file mode 100644
index 0000000000..f59f636570
--- /dev/null
+++ b/packages/api/src/utils/logger.ts
@@ -0,0 +1,137 @@
+// Thin structured-logger surface for the API worker.
+//
+// Two reasons this exists instead of bare console.log calls:
+//   1. Structured JSON lines are searchable in Workers logpush without
+//      regex parsing. A consistent { level, event, ...ctx } shape lets
+//      operators pivot on `event="etl.embedding.fallback"` in seconds.
+//   2. The emit() boundary forwards to @sentry/cloudflare when the SDK
+//      has been initialized by withSentry() in src/index.ts:
+//        - INFO/WARN → Sentry.addBreadcrumb (correlated with the next
+//          captureException if one fires)
+//        - ERROR with ctx.err → Sentry.captureException with tags from
+//          ctx (jobId, chunkIndex, workflowInstanceId, etc.)
+//        - ERROR without ctx.err → Sentry.captureMessage at error level
+//      isInitialized() returns false during unit tests or before withSentry
+//      runs, in which case Sentry calls are skipped silently.
+//
+// The error_stack contract: error messages MUST NOT include raw CSV row
+// data. Logger functions accept a structured `ctx` so callers pass jobId,
+// chunkIndex, etc. without smuggling row content into stringified errors.
+// To log an Error, attach it under the `err` key of ctx — the emit()
+// boundary unpacks it into errorName/errorMessage/errorStack fields and
+// forwards to Sentry.
+
+import { isNumber, isString } from '@packrat/guards';
+import { configureJsonStringify, safeJsonStringify } from '@packrat/utils';
+import { addBreadcrumb, captureException, captureMessage, isInitialized } from '@sentry/cloudflare';
+
+// Stringifier that THROWS on circular structures (like raw JSON.stringify), so
+// the emit() fallback below can detect un-serializable ctx and emit a
+// serializationError line instead of silently writing a `[Circular]` placeholder.
+const stringifyOrThrow = configureJsonStringify({
+  circularValue: Error,
+  bigint: true,
+  deterministic: false,
+});
+
+export type LogContext = Record<string, unknown> & { err?: unknown };
+
+type LogLevel = 'INFO' | 'WARN' | 'ERROR';
+
+type EmitArgs = { level: LogLevel; event: string; ctx?: LogContext };
+
+function forwardToSentry({ level, event, ctx }: EmitArgs): void {
+  // The Sentry SDK throws if it's accessed before withSentry has initialized
+  // the client (e.g., in unit tests or during cold-start). Skip silently in
+  // that case — console output above is still the durable record.
+  if (!isInitialized()) return;
+
+  const sentryTags: Record<string, string> = {};
+  const sentryExtras: Record<string, unknown> = { event };
+  let err: unknown;
+  if (ctx) {
+    for (const [k, v] of Object.entries(ctx)) {
+      if (k === 'err') {
+        err = v;
+        continue;
+      }
+      if (isString(v) || isNumber(v) || v === true || v === false) {
+        sentryTags[k] = String(v);
+      } else {
+        sentryExtras[k] = v;
+      }
+    }
+  }
+
+  if (level === 'ERROR') {
+    if (err !== undefined) {
+      captureException(err, { tags: { event, ...sentryTags }, extra: sentryExtras });
+    } else {
+      captureMessage(event, { level: 'error', tags: sentryTags, extra: sentryExtras });
+    }
+    return;
+  }
+
+  addBreadcrumb({
+    category: event,
+    level: level === 'WARN' ? 'warning' : 'info',
+    data: { ...sentryTags, ...sentryExtras },
+  });
+}
+
+function emit({ level, event, ctx }: EmitArgs): void {
+  const line: Record<string, unknown> = {
+    level,
+    event,
+    ts: new Date().toISOString(),
+  };
+  if (ctx) {
+    for (const [k, v] of Object.entries(ctx)) {
+      if (k === 'err') continue;
+      line[k] = v;
+    }
+    const err = ctx.err;
+    if (err !== undefined) {
+      if (err instanceof Error) {
+        line.errorName = err.name;
+        line.errorMessage = err.message;
+        if (err.stack) line.errorStack = err.stack;
+      } else {
+        line.errorMessage = String(err);
+      }
+    }
+  }
+  let out: string;
+  try {
+    out = stringifyOrThrow(line);
+  } catch {
+    out = safeJsonStringify({ level, event, ts: line.ts, serializationError: true });
+  }
+  if (level === 'ERROR') {
+    console.error(out);
+  } else if (level === 'WARN') {
+    console.warn(out);
+  } else {
+    console.log(out);
+  }
+
+  // Best-effort forward to Sentry; failures here must never break the call
+  // site (the JSON line is already on console).
+  try {
+    forwardToSentry({ level, event, ctx });
+  } catch {
+    // swallow — Sentry forwarding is observability, not correctness
+  }
+}
+
+export const logger = {
+  info({ event, ctx }: { event: string; ctx?: LogContext }): void {
+    emit({ level: 'INFO', event, ctx });
+  },
+  warn({ event, ctx }: { event: string; ctx?: LogContext }): void {
+    emit({ level: 'WARN', event, ctx });
+  },
+  error({ event, ctx }: { event: string; ctx?: LogContext }): void {
+    emit({ level: 'ERROR', event, ctx });
+  },
+};
diff --git a/packages/api/src/workflows/catalog-etl-workflow.ts b/packages/api/src/workflows/catalog-etl-workflow.ts
new file mode 100644
index 0000000000..4d4c12e31d
--- /dev/null
+++ b/packages/api/src/workflows/catalog-etl-workflow.ts
@@ -0,0 +1,406 @@
+// Catalog ETL — runs as a Cloudflare Workflow.
+//
+// Replaces the Queues-based pipeline at packages/api/src/services/etl/queue.ts
+// + processCatalogEtl.ts. Workflows' durable step execution gives:
+//   - Per-step memoization (a successful step is never re-executed on retry)
+//   - Per-step retry policy (transient R2/DB/embedding failures retry with
+//     exponential backoff; persistent failures route the instance to errored)
+//   - Durable state between steps (no etl_job_chunks idempotency table needed)
+//   - Instance status as the source of truth for stuck-job detection (no
+//     wall-clock sweep cron needed)
+//
+// Counters on etl_jobs are written from the chunk steps (via existing
+// processValidItemsBatch / processLogsBatch which call updateEtlJobProgress).
+// On a step retry the underlying SKU upsert is idempotent (UNIQUE on
+// catalog_item_etl_jobs); embedding API calls and invalid_item_log inserts
+// can duplicate on retry — accepted trade-off for the simpler control flow.
+// The final aggregate step writes the authoritative totals from the
+// memoized step results.
+
+import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from 'cloudflare:workers';
+import { createDbClient } from '@packrat/api/db';
+import { CatalogItemValidator } from '@packrat/api/services/etl/CatalogItemValidator';
+import { BATCH_SIZE } from '@packrat/api/services/etl/processCatalogEtl';
+import { processLogsBatch } from '@packrat/api/services/etl/processLogsBatch';
+import { processValidItemsBatch } from '@packrat/api/services/etl/processValidItemsBatch';
+import { R2BucketService } from '@packrat/api/services/r2-bucket';
+import { mapCsvRowToItem } from '@packrat/api/utils/csv-utils';
+import type { Env } from '@packrat/api/utils/env-validation';
+import { setWorkerEnv } from '@packrat/api/utils/env-validation';
+import { isJsonlFile, mapJsonRowToItem } from '@packrat/api/utils/json-utils';
+import { etlJobs, type NewCatalogItem, type NewInvalidItemLog } from '@packrat/db';
+import { toRecord } from '@packrat/guards';
+import { safeJsonParse } from '@packrat/utils';
+import { parse } from 'csv-parse';
+import { eq } from 'drizzle-orm';
+import type { ChunkSpec } from './shared/chunkCsvForR2';
+
+export type CatalogEtlWorkflowParams = {
+  jobId: string;
+  source: string;
+  scraperRevision: string;
+  chunks: ChunkSpec[];
+};
+
+export type ChunkResult = {
+  chunkIndex: number;
+  rowsProcessed: number;
+  rowsValid: number;
+  rowsInvalid: number;
+};
+
+const HEADER_PEEK_SIZES = [4 * 1024, 16 * 1024, 64 * 1024];
+
+export class EtlHeaderError extends Error {
+  constructor(objectKey: string) {
+    super(`No newline found in the first 64 KiB of ${objectKey} — malformed CSV header.`);
+    this.name = 'EtlHeaderError';
+  }
+}
+
+async function* streamToText(stream: ReadableStream<Uint8Array>) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      yield decoder.decode(value, { stream: true });
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+async function fetchHeaderRow(r2: R2BucketService, objectKey: string): Promise<string> {
+  for (const length of HEADER_PEEK_SIZES) {
+    const obj = await r2.get(objectKey, { range: { offset: 0, length } });
+    if (!obj) throw new Error(`R2 header read returned null for ${objectKey}`);
+    const text = await obj.text();
+    const newlineIndex = text.indexOf('\n');
+    if (newlineIndex !== -1) {
+      return text.slice(0, newlineIndex);
+    }
+  }
+  throw new EtlHeaderError(objectKey);
+}
+
+export async function processChunk({
+  jobId,
+  chunk,
+  env,
+}: {
+  jobId: string;
+  chunk: ChunkSpec;
+  env: Env;
+}): Promise<ChunkResult> {
+  const r2 = new R2BucketService({ env, bucketType: 'catalog' });
+
+  const isNonFirstChunk = chunk.chunkIndex > 0;
+  const useJsonl = isJsonlFile(chunk.objectKey);
+
+  const length = chunk.byteEnd - chunk.byteStart + 1;
+  const obj = await r2.get(chunk.objectKey, {
+    range: { offset: chunk.byteStart, length },
+  });
+  if (!obj) throw new Error(`R2 chunk read returned null for ${chunk.objectKey}`);
+
+  const validItemsBatch: Partial<NewCatalogItem>[] = [];
+  const invalidItemsBatch: NewInvalidItemLog[] = [];
+  const validator = new CatalogItemValidator();
+
+  let rowIndex = 0;
+  let rowsValid = 0;
+  let rowsInvalid = 0;
+
+  if (useJsonl) {
+    // --- JSONL streaming path ---
+    // The chunker snaps boundaries to newlines, so every chunk starts at a
+    // clean line boundary — no partial first-line skip needed for any chunk.
+    let buffer = '';
+    let firstLineSkipped = true;
+
+    for await (const text of streamToText(obj.body)) {
+      buffer += text;
+      const lines = buffer.split('\n');
+      buffer = lines.pop() ?? '';
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+
+        if (!firstLineSkipped) {
+          firstLineSkipped = true;
+          continue; // discard partial row at chunk boundary
+        }
+
+        if (rowIndex % 100 === 0) {
+          await new Promise((resolve) => setTimeout(resolve, 0));
+        }
+
+        let parsedObj: Record<string, unknown>;
+        try {
+          parsedObj = toRecord(safeJsonParse(trimmed, { strict: true }));
+        } catch (parseErr) {
+          invalidItemsBatch.push({
+            jobId,
+            errors: [{ field: 'json_parse', reason: String(parseErr) }],
+            rawData: { parseError: String(parseErr) },
+            rowIndex,
+          });
+          rowIndex++;
+          if (invalidItemsBatch.length >= BATCH_SIZE) {
+            await processLogsBatch({ jobId, logs: [...invalidItemsBatch], env });
+            rowsInvalid += invalidItemsBatch.length;
+            invalidItemsBatch.length = 0;
+          }
+          continue;
+        }
+
+        const item = mapJsonRowToItem(parsedObj);
+        if (item) {
+          const validated = validator.validateItem(item);
+          if (validated.isValid) {
+            validItemsBatch.push(validated.item);
+          } else {
+            invalidItemsBatch.push({
+              jobId,
+              errors: validated.errors,
+              rawData: validated.item,
+              rowIndex,
+            });
+          }
+        }
+        rowIndex++;
+
+        if (validItemsBatch.length >= BATCH_SIZE) {
+          await processValidItemsBatch({ jobId, items: [...validItemsBatch], env });
+          rowsValid += validItemsBatch.length;
+          validItemsBatch.length = 0;
+        }
+        if (invalidItemsBatch.length >= BATCH_SIZE) {
+          await processLogsBatch({ jobId, logs: [...invalidItemsBatch], env });
+          rowsInvalid += invalidItemsBatch.length;
+          invalidItemsBatch.length = 0;
+        }
+      }
+    }
+
+    // Flush remaining buffer line (last line without trailing newline)
+    const lastLine = buffer.trim();
+    if (lastLine && firstLineSkipped) {
+      try {
+        const parsedObj = toRecord(safeJsonParse(lastLine, { strict: true }));
+        const item = mapJsonRowToItem(parsedObj);
+        if (item) {
+          const validated = validator.validateItem(item);
+          if (validated.isValid) {
+            validItemsBatch.push(validated.item);
+          } else {
+            invalidItemsBatch.push({
+              jobId,
+              errors: validated.errors,
+              rawData: validated.item,
+              rowIndex,
+            });
+          }
+        }
+        rowIndex++;
+      } catch (parseErr) {
+        invalidItemsBatch.push({
+          jobId,
+          errors: [{ field: 'json_parse', reason: String(parseErr) }],
+          rawData: { parseError: String(parseErr) },
+          rowIndex,
+        });
+        rowIndex++;
+      }
+    }
+  } else {
+    // --- CSV path ---
+    const injectedHeader = isNonFirstChunk ? await fetchHeaderRow(r2, chunk.objectKey) : '';
+
+    let fieldMap: Record<string, number> = {};
+    let isHeaderProcessed = false;
+
+    const parser = parse({
+      relax_column_count: true,
+      relax_quotes: true,
+      skip_empty_lines: true,
+      skip_records_with_error: true,
+      on_skip: (err) => {
+        const parserLine = (err as { lines?: number } | undefined)?.lines ?? rowIndex;
+        const message = err?.message ?? 'unknown parse error';
+        invalidItemsBatch.push({
+          jobId,
+          errors: [{ field: 'csv_parse', reason: message }],
+          rawData: { parseError: message },
+          rowIndex: parserLine,
+        });
+      },
+    });
+
+    const writerPromise = (async () => {
+      if (injectedHeader) {
+        parser.write(`${injectedHeader}\n`);
+      }
+      for await (const text of streamToText(obj.body)) {
+        const ok = parser.write(text);
+        if (!ok) {
+          await new Promise<void>((resolve) => parser.once('drain', resolve));
+        }
+      }
+      parser.end();
+    })().catch((err) => {
+      parser.destroy(err instanceof Error ? err : new Error(String(err)));
+      throw err;
+    });
+
+    for await (const record of parser) {
+      if (rowIndex % 100 === 0) {
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      }
+      const row = record as string[];
+
+      if (!isHeaderProcessed) {
+        fieldMap = {};
+        for (const [idx, header] of row.entries()) {
+          fieldMap[header.trim()] = idx;
+        }
+        isHeaderProcessed = true;
+        continue;
+      }
+
+      const item = mapCsvRowToItem({ values: row, fieldMap });
+      if (item) {
+        const validated = validator.validateItem(item);
+        if (validated.isValid) {
+          validItemsBatch.push(validated.item);
+        } else {
+          invalidItemsBatch.push({
+            jobId,
+            errors: validated.errors,
+            rawData: validated.item,
+            rowIndex,
+          });
+        }
+      }
+
+      rowIndex++;
+
+      if (validItemsBatch.length >= BATCH_SIZE) {
+        await processValidItemsBatch({ jobId, items: [...validItemsBatch], env });
+        rowsValid += validItemsBatch.length;
+        validItemsBatch.length = 0;
+      }
+      if (invalidItemsBatch.length >= BATCH_SIZE) {
+        await processLogsBatch({ jobId, logs: [...invalidItemsBatch], env });
+        rowsInvalid += invalidItemsBatch.length;
+        invalidItemsBatch.length = 0;
+      }
+    }
+
+    await writerPromise;
+  }
+
+  if (validItemsBatch.length > 0) {
+    await processValidItemsBatch({ jobId, items: validItemsBatch, env });
+    rowsValid += validItemsBatch.length;
+  }
+  if (invalidItemsBatch.length > 0) {
+    await processLogsBatch({ jobId, logs: invalidItemsBatch, env });
+    rowsInvalid += invalidItemsBatch.length;
+  }
+
+  return {
+    chunkIndex: chunk.chunkIndex,
+    rowsProcessed: rowIndex,
+    rowsValid,
+    rowsInvalid,
+  };
+}
+
+export class CatalogEtlWorkflow extends WorkflowEntrypoint<Env, CatalogEtlWorkflowParams> {
+  async run(
+    event: Readonly<WorkflowEvent<CatalogEtlWorkflowParams>>,
+    step: WorkflowStep,
+  ): Promise<{ jobId: string; rowsProcessed: number; rowsValid: number; rowsInvalid: number }> {
+    setWorkerEnv(this.env as unknown as Record<string, unknown>); // safe-cast: same shape as fetch handler
+    const { jobId, chunks } = event.payload;
+
+    // One step per chunk. Each step is memoized by name within the instance,
+    // so a chunk that succeeds is never re-run on a downstream step failure.
+    // Retries are bounded to 3 with exponential backoff for transient R2/DB
+    // failures; a chunk that exhausts retries marks the entire instance errored.
+    try {
+      const chunkResults: ChunkResult[] = [];
+      for (const chunk of chunks) {
+        const result = await step.do(
+          `chunk-${chunk.chunkIndex}`,
+          {
+            retries: { limit: 3, delay: '30 seconds', backoff: 'exponential' },
+            timeout: '5 minutes',
+          },
+          async () => processChunk({ jobId, chunk, env: this.env }),
+        );
+        chunkResults.push(result);
+      }
+
+      const totals = chunkResults.reduce(
+        (acc, r) => ({
+          rowsProcessed: acc.rowsProcessed + r.rowsProcessed,
+          rowsValid: acc.rowsValid + r.rowsValid,
+          rowsInvalid: acc.rowsInvalid + r.rowsInvalid,
+        }),
+        { rowsProcessed: 0, rowsValid: 0, rowsInvalid: 0 },
+      );
+
+      // Aggregate step writes the canonical totals — any over-counts from chunk
+      // retries (the inner processValidItemsBatch increments are non-idempotent
+      // on retry) get overridden here. This is the authoritative count.
+      if (chunks.length === 0) {
+        throw new Error(`Workflow ${jobId} received empty chunks array`);
+      }
+      await step.do('aggregate', async () => {
+        const db = createDbClient(this.env);
+        await db
+          .update(etlJobs)
+          .set({
+            totalProcessed: totals.rowsProcessed,
+            totalValid: totals.rowsValid,
+            totalInvalid: totals.rowsInvalid,
+          })
+          .where(eq(etlJobs.id, jobId));
+      });
+
+      await step.do('finalize', async () => {
+        const db = createDbClient(this.env);
+        await db
+          .update(etlJobs)
+          .set({ status: 'completed', completedAt: new Date() })
+          .where(eq(etlJobs.id, jobId));
+      });
+
+      return {
+        jobId,
+        rowsProcessed: totals.rowsProcessed,
+        rowsValid: totals.rowsValid,
+        rowsInvalid: totals.rowsInvalid,
+      };
+    } catch (err) {
+      // Best-effort: mark the DB row failed so operators aren't looking at a
+      // perpetually-running job. The workflow runtime also marks the instance
+      // errored, but that's only visible in the CF dashboard.
+      try {
+        const db = createDbClient(this.env);
+        await db
+          .update(etlJobs)
+          .set({ status: 'failed', completedAt: new Date() })
+          .where(eq(etlJobs.id, jobId));
+      } catch {
+        // ignore — status update is best-effort; don't mask the original error
+      }
+      throw err;
+    }
+  }
+}
diff --git a/packages/api/src/workflows/shared/__tests__/chunk-csv-for-r2.test.ts b/packages/api/src/workflows/shared/__tests__/chunk-csv-for-r2.test.ts
new file mode 100644
index 0000000000..77f8d70971
--- /dev/null
+++ b/packages/api/src/workflows/shared/__tests__/chunk-csv-for-r2.test.ts
@@ -0,0 +1,181 @@
+// Unit tests for the row-boundary-aligned R2 chunker.
+//
+// The chunker is the load-bearing piece for catalog ETL correctness: any
+// off-by-one at a chunk boundary either drops a row, invalidates one, or
+// produces duplicates. These tests exercise the boundary alignment against
+// in-memory CSV fixtures so the failure modes the audit identified
+// (P1 #3, #4, #5) cannot regress silently.
+
+import {
+  ChunkBoundaryError,
+  type ChunkerR2,
+  chunkCsvForR2,
+} from '@packrat/api/workflows/shared/chunkCsvForR2';
+import { describe, expect, it } from 'vitest';
+
+const encoder = new TextEncoder();
+
+function fakeR2(text: string, key = 'fixture.csv'): { r2: ChunkerR2; bytes: Uint8Array } {
+  const bytes = encoder.encode(text);
+
+  const head = async (k: string) => {
+    if (k !== key) return null;
+    return {
+      key,
+      size: bytes.length,
+      etag: 'fake-etag',
+      uploaded: new Date('2026-05-20T00:00:00Z'),
+    } as Awaited<ReturnType<ChunkerR2['head']>>;
+  };
+
+  const get = async (k: string, opts?: { range?: { offset: number; length: number } }) => {
+    if (k !== key) return null;
+    const offset = opts?.range?.offset ?? 0;
+    const length = opts?.range?.length ?? bytes.length - offset;
+    const slice = bytes.slice(offset, offset + length);
+    return {
+      size: slice.length,
+      etag: 'fake-etag',
+      text: async () => new TextDecoder().decode(slice),
+    } as Awaited<ReturnType<ChunkerR2['get']>>;
+  };
+
+  return { r2: { head, get } as unknown as ChunkerR2, bytes };
+}
+
+function makeCsv(rowCount: number, rowWidth = 50): string {
+  const header = 'col1,col2,col3\n';
+  const row = (i: number) => `row-${i},${'x'.repeat(rowWidth)},${i}\n`;
+  return header + Array.from({ length: rowCount }, (_, i) => row(i)).join('');
+}
+
+function expectDefined<T>(value: T | undefined, message: string): T {
+  if (value === undefined) throw new Error(message);
+  return value;
+}
+
+describe('chunkCsvForR2', () => {
+  it('returns a single chunk when the file is smaller than chunkBytes', async () => {
+    const csv = makeCsv(100);
+    const { r2 } = fakeR2(csv);
+    const result = await chunkCsvForR2({
+      r2,
+      objectKey: 'fixture.csv',
+      chunkBytes: 1024 * 1024,
+    });
+    expect(result.chunks).toHaveLength(1);
+    expect(result.chunks[0]).toMatchObject({
+      chunkIndex: 0,
+      chunksTotal: 1,
+      byteStart: 0,
+      byteEnd: result.size - 1,
+    });
+    expect(result.etag).toBe('fake-etag');
+  });
+
+  it('splits a larger file at newline boundaries', async () => {
+    const csv = makeCsv(1000, 50);
+    const { r2, bytes } = fakeR2(csv);
+    // Target ~3 chunks for a ~60KB file.
+    const result = await chunkCsvForR2({
+      r2,
+      objectKey: 'fixture.csv',
+      chunkBytes: Math.ceil(bytes.length / 3),
+      peekBytes: 256,
+    });
+
+    expect(result.chunks.length).toBeGreaterThanOrEqual(2);
+    const firstChunk = expectDefined(result.chunks[0], 'first chunk missing');
+    expect(firstChunk.chunkIndex).toBe(0);
+    const lastChunk = expectDefined(result.chunks.at(-1), 'last chunk missing');
+    expect(lastChunk.chunkIndex).toBe(result.chunks.length - 1);
+    expect(lastChunk.chunksTotal).toBe(result.chunks.length);
+    expect(lastChunk.byteEnd).toBe(bytes.length - 1);
+
+    // Every boundary byteEnd must be a newline; the byte immediately after
+    // must be the first byte of the next row.
+    for (let i = 0; i < result.chunks.length - 1; i++) {
+      const current = expectDefined(result.chunks[i], `chunk ${i} missing`);
+      const next = expectDefined(result.chunks[i + 1], `chunk ${i + 1} missing`);
+      const boundary = current.byteEnd;
+      expect(bytes[boundary]).toBe(0x0a); // '\n'
+      expect(next.byteStart).toBe(boundary + 1);
+    }
+  });
+
+  it('reassembles to the original byte content when chunks are concatenated', async () => {
+    const csv = makeCsv(500, 80);
+    const { r2, bytes } = fakeR2(csv);
+    const result = await chunkCsvForR2({
+      r2,
+      objectKey: 'fixture.csv',
+      chunkBytes: Math.ceil(bytes.length / 4),
+      peekBytes: 256,
+    });
+
+    // The chunks together must cover bytes [0, size-1] with no gaps or overlap.
+    let cursor = 0;
+    for (const chunk of result.chunks) {
+      expect(chunk.byteStart).toBe(cursor);
+      expect(chunk.byteEnd).toBeGreaterThanOrEqual(chunk.byteStart);
+      cursor = chunk.byteEnd + 1;
+    }
+    expect(cursor).toBe(bytes.length);
+  });
+
+  it('throws for an empty R2 object (0 bytes)', async () => {
+    const { r2 } = fakeR2('');
+    await expect(chunkCsvForR2({ r2, objectKey: 'fixture.csv' })).rejects.toThrow(
+      'empty (0 bytes)',
+    );
+  });
+
+  it('throws ChunkBoundaryError when no newline is found in the peek window', async () => {
+    // A single very long row with no internal newlines forces peekBytes=256
+    // to scan a tail with no \n at all.
+    const longRow = 'x'.repeat(8 * 1024);
+    const csv = `col1\n${longRow}\n`;
+    const { r2 } = fakeR2(csv);
+
+    await expect(
+      chunkCsvForR2({ r2, objectKey: 'fixture.csv', chunkBytes: 2048, peekBytes: 256 }),
+    ).rejects.toBeInstanceOf(ChunkBoundaryError);
+  });
+
+  it('uses DEFAULT_CHUNK_BYTES (2 MiB) when chunkBytes is omitted', async () => {
+    const csv = makeCsv(10);
+    const { r2 } = fakeR2(csv);
+    const result = await chunkCsvForR2({ r2, objectKey: 'fixture.csv' });
+    // Small file fits in one chunk regardless of default size
+    expect(result.chunks).toHaveLength(1);
+    expect(result.chunks[0]?.byteStart).toBe(0);
+  });
+
+  it('preserves a CSV row at the boundary — first row of chunk N+1 is intact', async () => {
+    const csv = makeCsv(200, 40);
+    const { r2, bytes } = fakeR2(csv);
+    const result = await chunkCsvForR2({
+      r2,
+      objectKey: 'fixture.csv',
+      chunkBytes: Math.ceil(bytes.length / 3),
+      peekBytes: 256,
+    });
+
+    const text = new TextDecoder().decode(bytes);
+    const allRows = text.split('\n').filter((line) => line.length > 0);
+    const headerRow = expectDefined(allRows[0], 'fixture has no header');
+    const dataRows = allRows.slice(1);
+
+    // For each non-first chunk, the bytes at byteStart..next-newline should be
+    // a complete data row (matches one of dataRows verbatim).
+    for (let i = 1; i < result.chunks.length; i++) {
+      const chunk = expectDefined(result.chunks[i], `chunk ${i} missing`);
+      const slice = new TextDecoder().decode(bytes.slice(chunk.byteStart, chunk.byteEnd + 1));
+      const firstRow = expectDefined(slice.split('\n')[0], `chunk ${i} has no first row`);
+      expect(firstRow.startsWith('row-')).toBe(true);
+      expect(dataRows).toContain(firstRow);
+      // The header must NOT appear inside a non-first chunk.
+      expect(slice).not.toContain(headerRow);
+    }
+  });
+});
diff --git a/packages/api/src/workflows/shared/chunkCsvForR2.ts b/packages/api/src/workflows/shared/chunkCsvForR2.ts
new file mode 100644
index 0000000000..500769baf6
--- /dev/null
+++ b/packages/api/src/workflows/shared/chunkCsvForR2.ts
@@ -0,0 +1,156 @@
+// Row-boundary-aligned byte-range chunking for catalog source CSVs in R2.
+//
+// The producer endpoint and the admin retry/repair endpoints both need the
+// same chunk spec. Boundaries snap to the byte immediately before a newline
+// so a chunk never splits a CSV row in half (closes audit P1 #4 and P1 #5).
+// Peek reads are issued in parallel to keep the producer's CPU budget under
+// control on multi-GB files (closes the deepening pass concern about
+// sequential peek latency).
+
+import type { R2BucketService } from '@packrat/api/services/r2-bucket';
+
+export type ChunkSpec = {
+  objectKey: string;
+  chunkIndex: number;
+  chunksTotal: number;
+  byteStart: number;
+  /** Inclusive end byte, matching R2 / S3 `Range: bytes=offset-end` semantics. */
+  byteEnd: number;
+};
+
+export type ChunkCsvResult = {
+  etag: string;
+  lastModified: Date;
+  size: number;
+  chunks: ChunkSpec[];
+};
+
+export type ChunkerR2 = Pick<R2BucketService, 'head' | 'get'>;
+
+const DEFAULT_CHUNK_BYTES = 2 * 1024 * 1024; // 2 MiB — keeps each workflow step well under the 5-minute timeout for large files
+const DEFAULT_PEEK_BYTES = 64 * 1024; // 64 KiB
+
+export class ChunkBoundaryError extends Error {
+  constructor(objectKey: string, byteRange: { from: number; to: number }) {
+    super(
+      `No newline found in ${byteRange.to - byteRange.from} bytes ending at ${byteRange.to} ` +
+        `of ${objectKey} — row larger than the peek window or file is not line-oriented.`,
+    );
+    this.name = 'ChunkBoundaryError';
+  }
+}
+
+/**
+ * Plan the byte-range chunks for one R2 object.
+ *
+ * For files smaller than `chunkBytes`, returns a single chunk spanning the
+ * whole object. For larger files, splits into N chunks whose boundaries are
+ * aligned to newlines via parallel peek reads of the tail of each window.
+ *
+ * Throws ChunkBoundaryError if no newline is found within `peekBytes` of any
+ * proposed boundary — caller should treat this as fatal (the source file is
+ * malformed or has a row wider than 64 KiB, both of which warrant a loud
+ * failure rather than silent row drops).
+ */
+export async function chunkCsvForR2({
+  r2,
+  objectKey,
+  chunkBytes = DEFAULT_CHUNK_BYTES,
+  peekBytes = DEFAULT_PEEK_BYTES,
+}: {
+  r2: ChunkerR2;
+  objectKey: string;
+  chunkBytes?: number;
+  peekBytes?: number;
+}): Promise<ChunkCsvResult> {
+  const meta = await r2.head(objectKey);
+  if (!meta) throw new Error(`R2 object not found: ${objectKey}`);
+
+  const size = meta.size;
+  const etag = meta.etag;
+  const lastModified = meta.uploaded;
+
+  if (size === 0) {
+    throw new Error(`R2 object ${objectKey} is empty (0 bytes) — not a valid CSV source`);
+  }
+
+  if (size <= chunkBytes) {
+    return {
+      etag,
+      lastModified,
+      size,
+      chunks: [
+        {
+          objectKey,
+          chunkIndex: 0,
+          chunksTotal: 1,
+          byteStart: 0,
+          byteEnd: size - 1,
+        },
+      ],
+    };
+  }
+
+  // Compute the candidate boundaries (the byte AFTER the last byte of each
+  // non-final chunk). The final chunk always ends at size - 1.
+  const boundaryCount = Math.ceil(size / chunkBytes) - 1;
+  const candidates: Array<{ index: number; from: number; to: number }> = [];
+  for (let i = 0; i < boundaryCount; i++) {
+    const target = (i + 1) * chunkBytes; // exclusive end of chunk i
+    const from = Math.max(0, target - peekBytes);
+    const to = Math.min(size, target);
+    candidates.push({ index: i, from, to });
+  }
+
+  // Peek reads in bounded-parallel batches of 16 to keep R2 from rate-limiting
+  // on multi-GB ingests with many chunk boundaries.
+  const PEEK_CONCURRENCY = 16;
+  const peeks: Array<{ index: number; byteEnd: number }> = [];
+  for (let i = 0; i < candidates.length; i += PEEK_CONCURRENCY) {
+    const batch = candidates.slice(i, i + PEEK_CONCURRENCY);
+    const batchResults = await Promise.all(
+      batch.map(async ({ index, from, to }) => {
+        const obj = await r2.get(objectKey, { range: { offset: from, length: to - from } });
+        if (!obj) throw new Error(`R2 peek read returned null for ${objectKey} [${from},${to})`);
+        const text = await obj.text();
+        const lastNewlineIndex = text.lastIndexOf('\n');
+        if (lastNewlineIndex === -1) {
+          throw new ChunkBoundaryError(objectKey, { from, to });
+        }
+        // TextEncoder gives byte length of the prefix — accurate for non-ASCII CSV
+        // content where char index != byte offset (e.g. accented product names).
+        const byteEnd = from + new TextEncoder().encode(text.slice(0, lastNewlineIndex)).byteLength;
+        return { index, byteEnd };
+      }),
+    );
+    peeks.push(...batchResults);
+  }
+
+  // Assemble the final chunk list in order. Each chunk's byteStart is the
+  // previous chunk's byteEnd + 1 (so the next chunk starts AFTER the
+  // newline at the previous boundary).
+  const sortedPeeks = peeks.sort((a, b) => a.index - b.index);
+  const chunksTotal = sortedPeeks.length + 1;
+  const chunks: ChunkSpec[] = [];
+  let byteStart = 0;
+  for (const [chunkIndex, { byteEnd }] of sortedPeeks.entries()) {
+    chunks.push({
+      objectKey,
+      chunkIndex,
+      chunksTotal,
+      byteStart,
+      byteEnd,
+    });
+    byteStart = byteEnd + 1;
+  }
+  // Final chunk runs to EOF.
+  chunks.push({
+    objectKey,
+    chunkIndex: chunksTotal - 1,
+    chunksTotal,
+    byteStart,
+    byteEnd: size - 1,
+  });
+
+  return { etag, lastModified, size, chunks };
+}
diff --git a/packages/api/test/catalog.test.ts b/packages/api/test/catalog.test.ts
index 7bb3010df1..bc61d8ef30 100644
--- a/packages/api/test/catalog.test.ts
+++ b/packages/api/test/catalog.test.ts
@@ -48,6 +48,29 @@ describe('Catalog Routes', () => {
       expect(Array.isArray(data) || data.items).toBeTruthy();
     });
 
+    it('returns catalog items with unknown weight', async () => {
+      const seededItem = await seedCatalogItem({
+        name: 'Mystery Weight Shell',
+        weight: null,
+        weightUnit: null,
+      });
+      const sort = encodeURIComponent(JSON.stringify({ field: 'createdAt', order: 'desc' }));
+
+      const res = await apiWithAuth(`/catalog?sort=${sort}`);
+
+      expect(res.status).toBe(200);
+      const data = await expectJsonResponse(res, ['items']);
+      const item = data.items.find(
+        (catalogItem: { id: number }) => catalogItem.id === seededItem.id,
+      );
+      expect(item).toBeDefined();
+      expect(item).toMatchObject({
+        id: seededItem.id,
+        weight: null,
+        weightUnit: null,
+      });
+    });
+
     it('accepts pagination parameters', async () => {
       const res = await apiWithAuth('/catalog?page=1&limit=10');
 
diff --git a/packages/api/test/db-schema-etl.test.ts b/packages/api/test/db-schema-etl.test.ts
new file mode 100644
index 0000000000..b972a7e450
--- /dev/null
+++ b/packages/api/test/db-schema-etl.test.ts
@@ -0,0 +1,64 @@
+// Schema smoke test for the ETL Workflows columns on etl_jobs. Runs against
+// the Docker Postgres wsproxy at localhost:5434 (docker-compose.test.yml).
+// If the proxy is down the queries throw — intentional; the test would not
+// silently skip schema drift.
+
+import { createDbClient } from '@packrat/api/db';
+import type { Env } from '@packrat/api/utils/env-validation';
+import { sql } from 'drizzle-orm';
+import { describe, expect, it } from 'vitest';
+
+type ColumnInfo = {
+  column_name: string;
+  data_type: string;
+  is_nullable: 'YES' | 'NO';
+  column_default: string | null;
+};
+
+type IndexInfo = { indexname: string; indexdef: string };
+
+async function describeColumns(table: string): Promise<ColumnInfo[]> {
+  const db = createDbClient({} as Env);
+  const result = (await db.execute(sql`
+    SELECT column_name, data_type, is_nullable, column_default
+    FROM information_schema.columns
+    WHERE table_schema = 'public' AND table_name = ${table}
+    ORDER BY ordinal_position
+  `)) as unknown as ColumnInfo[];
+  return result;
+}
+
+async function describeIndexes(table: string): Promise<IndexInfo[]> {
+  const db = createDbClient({} as Env);
+  const result = (await db.execute(sql`
+    SELECT indexname, indexdef
+    FROM pg_indexes
+    WHERE schemaname = 'public' AND tablename = ${table}
+  `)) as unknown as IndexInfo[];
+  return result;
+}
+
+describe('Migration 0047 — ETL workflow columns', () => {
+  it('adds workflow_instance_id as nullable text', async () => {
+    const cols = await describeColumns('etl_jobs');
+    const col = cols.find((c) => c.column_name === 'workflow_instance_id');
+    expect(col).toBeDefined();
+    expect(col?.data_type).toBe('text');
+    expect(col?.is_nullable).toBe('YES');
+  });
+
+  it('adds total_embedding_failures as integer NOT NULL DEFAULT 0', async () => {
+    const cols = await describeColumns('etl_jobs');
+    const col = cols.find((c) => c.column_name === 'total_embedding_failures');
+    expect(col).toBeDefined();
+    expect(col?.data_type).toBe('integer');
+    expect(col?.is_nullable).toBe('NO');
+    expect(col?.column_default).toBe('0');
+  });
+
+  it('adds the workflow_instance_id index', async () => {
+    const indexes = await describeIndexes('etl_jobs');
+    const names = new Set(indexes.map((i) => i.indexname));
+    expect(names.has('etl_jobs_workflow_instance_id_idx')).toBe(true);
+  });
+});
diff --git a/packages/api/vitest.unit.config.ts b/packages/api/vitest.unit.config.ts
index d8db428f52..c6771ce8ff 100644
--- a/packages/api/vitest.unit.config.ts
+++ b/packages/api/vitest.unit.config.ts
@@ -58,6 +58,10 @@ export default defineConfig({
         'src/auth/index.ts',
         // ETL and AI utilities (defer to integration tests)
         'src/services/etl/**',
+        // CatalogEtlWorkflow needs the CF Workflows runtime for end-to-end
+        // execution; covered by integration tests in /test once Docker Postgres
+        // is wired. Sibling chunker (src/workflows/shared/) IS unit-tested.
+        'src/workflows/catalog-etl-workflow.ts',
         'src/utils/ai/**',
         // Complex orchestration services (defer to integration tests)
         'src/services/aiService.ts',
diff --git a/packages/api/wrangler.jsonc b/packages/api/wrangler.jsonc
index d1058c53c8..68be45145f 100644
--- a/packages/api/wrangler.jsonc
+++ b/packages/api/wrangler.jsonc
@@ -5,9 +5,15 @@
   // Elysia 1.4+ CloudflareAdapter requires compatibility_date >= 2025-06-01.
   "compatibility_date": "2025-06-01",
   // nodejs_compat is kept because other dependencies (bcryptjs, pg) rely on it.
-  "compatibility_flags": ["nodejs_compat"],
+  // nodejs_als is required by @sentry/cloudflare for AsyncLocalStorage-based
+  // request/workflow context propagation across awaits.
+  "compatibility_flags": ["nodejs_compat", "nodejs_als"],
   "keep_vars": true,
   "logpush": true,
+  // Generate + upload source maps to Cloudflare so Workers logs show
+  // unminified stack traces. Sentry symbolication uses a separate
+  // @sentry/cli sourcemaps upload step in CI (see deploy workflow).
+  "upload_source_maps": true,
   "version_metadata": {
     "binding": "CF_VERSION_METADATA"
   },
@@ -90,6 +96,23 @@
   "ai": {
     "binding": "AI"
   },
+  // Catalog ETL workflow — the durable execution engine for catalog ingests.
+  // The producer endpoint at POST /catalog/etl triggers a new instance per
+  // source CSV; each chunk is a step.do call inside the workflow. Replaces
+  // the previous Queues-based path (which remains available during the
+  // coexistence window via ?engine=queue on the producer endpoint).
+  "workflows": [
+    {
+      "name": "packrat-catalog-etl",
+      "binding": "ETL_WORKFLOW",
+      "class_name": "CatalogEtlWorkflow"
+    }
+  ],
+  // Daily 09:00 UTC retention sweep of invalid_item_logs (>90 days old).
+  // Handled by the `scheduled` arm in src/index.ts.
+  "triggers": {
+    "crons": ["0 9 * * *"]
+  },
   // OSM / trail database — dedicated Postgres instance with PostGIS.
   // Add a Hyperdrive binding when ready:
   //   wrangler hyperdrive create osm-db --connection-string="postgresql://..."
@@ -202,6 +225,16 @@
       "ai": {
         "binding": "AI"
       },
+      "workflows": [
+        {
+          "name": "packrat-catalog-etl-dev",
+          "binding": "ETL_WORKFLOW",
+          "class_name": "CatalogEtlWorkflow"
+        }
+      ],
+      "triggers": {
+        "crons": ["0 9 * * *"]
+      },
       "containers": [
         {
           "name": "packrat-api-container-dev",
diff --git a/packages/app/package.json b/packages/app/package.json
index 6c361fefbf..fd6a413027 100644
--- a/packages/app/package.json
+++ b/packages/app/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/app",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "exports": {
diff --git a/packages/checks/package.json b/packages/checks/package.json
index 60ec0b041e..9ba796f205 100644
--- a/packages/checks/package.json
+++ b/packages/checks/package.json
@@ -1,14 +1,17 @@
 {
   "name": "@packrat/checks",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "scripts": {
     "check:casts": "bun ./src/check-type-casts.ts",
     "check:casts:strict": "bun ./src/check-type-casts.ts --strict",
     "check:magic-strings": "bun ./src/check-magic-strings.ts",
+    "check:provenance": "bun ./src/check-utils-provenance.ts",
+    "check:provenance:strict": "bun ./src/check-utils-provenance.ts --strict",
     "check:route-schemas": "bun ./src/check-route-schemas.ts",
     "check:route-schemas:strict": "bun ./src/check-route-schemas.ts --strict",
-    "check-types": "tsc --noEmit"
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
   }
 }
diff --git a/packages/checks/src/check-utils-provenance.test.ts b/packages/checks/src/check-utils-provenance.test.ts
new file mode 100644
index 0000000000..8af055bdf0
--- /dev/null
+++ b/packages/checks/src/check-utils-provenance.test.ts
@@ -0,0 +1,132 @@
+import * as barrel from '@packrat/utils';
+import { type ProvenanceEntry, provenance } from '@packrat/utils/provenance';
+import { describe, expect, it } from 'vitest';
+import { type ProvenanceViolation, validateProvenance } from './check-utils-provenance';
+
+/**
+ * A minimal valid manifest: barrel exports == manifest keys, every source
+ * known, no unjustified lower-priority pick. Each failure-mode test mutates
+ * a copy of this so the only variable is the invariant under test.
+ */
+const baseManifest: Record<string, ProvenanceEntry> = {
+  unique: { source: 'radashi' },
+  chunk: { source: 'es-toolkit' },
+  safeParse: { source: 'destr' },
+  round: {
+    source: 'es-toolkit',
+    alsoIn: ['radashi'],
+    reason: 'es-toolkit round supports precision; radashi round does not',
+  },
+};
+
+const baseExports = Object.keys(baseManifest);
+
+const kinds = (violations: ProvenanceViolation[]): ProvenanceViolation['kind'][] =>
+  violations.map((v) => v.kind);
+
+describe('validateProvenance', () => {
+  it('returns no violations when exports and manifest are in sync and valid', () => {
+    const violations = validateProvenance({ exportedNames: baseExports, manifest: baseManifest });
+    expect(violations).toEqual([]);
+  });
+
+  it('flags a barrel export with no manifest entry as MISSING', () => {
+    const violations = validateProvenance({
+      exportedNames: [...baseExports, 'orphanExport'],
+      manifest: baseManifest,
+    });
+    expect(kinds(violations)).toEqual(['missing']);
+    expect(violations[0]?.name).toBe('orphanExport');
+    expect(violations[0]?.detail).toContain('orphanExport');
+  });
+
+  it('flags a manifest entry with no matching export as STALE', () => {
+    const violations = validateProvenance({
+      exportedNames: baseExports,
+      manifest: { ...baseManifest, ghost: { source: 'radashi' } },
+    });
+    expect(kinds(violations)).toEqual(['stale']);
+    expect(violations[0]?.name).toBe('ghost');
+    expect(violations[0]?.detail).toContain('ghost');
+  });
+
+  it('flags an entry whose source is not a known lib as UNKNOWN', () => {
+    const violations = validateProvenance({
+      exportedNames: [...baseExports, 'weird'],
+      // 'underscore' is not a SourceLib — forge an invalid source via unknown.
+      manifest: { ...baseManifest, weird: { source: 'underscore' as unknown as 'radashi' } },
+    });
+    expect(kinds(violations)).toEqual(['unknown']);
+    expect(violations[0]?.name).toBe('weird');
+    expect(violations[0]?.detail).toContain('underscore');
+  });
+
+  it('flags a lower-priority source without a reason as UNJUSTIFIED', () => {
+    const violations = validateProvenance({
+      exportedNames: [...baseExports, 'roundNoReason'],
+      manifest: {
+        ...baseManifest,
+        // es-toolkit is outranked by radashi in alsoIn, but no reason given.
+        roundNoReason: { source: 'es-toolkit', alsoIn: ['radashi'] },
+      },
+    });
+    expect(kinds(violations)).toEqual(['unjustified']);
+    expect(violations[0]?.name).toBe('roundNoReason');
+    expect(violations[0]?.detail).toContain('es-toolkit');
+  });
+
+  it('treats a whitespace-only reason as no reason (UNJUSTIFIED)', () => {
+    const violations = validateProvenance({
+      exportedNames: [...baseExports, 'roundBlank'],
+      manifest: {
+        ...baseManifest,
+        roundBlank: { source: 'es-toolkit', alsoIn: ['radashi'], reason: '   ' },
+      },
+    });
+    expect(kinds(violations)).toEqual(['unjustified']);
+    expect(violations[0]?.name).toBe('roundBlank');
+  });
+
+  it('does not flag a higher-or-equal-priority source listed in alsoIn', () => {
+    const violations = validateProvenance({
+      exportedNames: [...baseExports, 'higherPick'],
+      manifest: {
+        ...baseManifest,
+        // radashi outranks es-toolkit, so listing es-toolkit in alsoIn needs no reason.
+        higherPick: { source: 'radashi', alsoIn: ['es-toolkit'] },
+      },
+    });
+    expect(violations).toEqual([]);
+  });
+
+  it('reports every distinct failure mode at once', () => {
+    const violations = validateProvenance({
+      exportedNames: [...baseExports, 'orphanExport'],
+      manifest: {
+        ...baseManifest,
+        ghost: { source: 'radashi' },
+        weird: { source: 'underscore' as unknown as 'radashi' },
+        roundNoReason: { source: 'es-toolkit', alsoIn: ['radashi'] },
+      },
+    });
+    // weird and roundNoReason have no export, so they are also STALE.
+    expect(kinds(violations).sort()).toEqual(
+      ['missing', 'stale', 'stale', 'stale', 'unjustified', 'unknown'].sort(),
+    );
+    expect(violations.length).toBe(6);
+  });
+});
+
+describe('real @packrat/utils manifest', () => {
+  it('is in sync with the barrel and passes every invariant', () => {
+    const violations = validateProvenance({
+      exportedNames: Object.keys(barrel),
+      manifest: provenance,
+    });
+    expect(violations).toEqual([]);
+  });
+
+  it('has exactly as many manifest entries as barrel exports', () => {
+    expect(Object.keys(provenance).length).toBe(Object.keys(barrel).length);
+  });
+});
diff --git a/packages/checks/src/check-utils-provenance.ts b/packages/checks/src/check-utils-provenance.ts
new file mode 100644
index 0000000000..6f3864a28f
--- /dev/null
+++ b/packages/checks/src/check-utils-provenance.ts
@@ -0,0 +1,144 @@
+#!/usr/bin/env bun
+/**
+ * check-utils-provenance.ts — validates the @packrat/utils provenance manifest
+ * (packages/utils/src/provenance.ts) against the actual barrel exports
+ * (packages/utils/src/index.ts) and enforces the source-priority policy.
+ *
+ * The manifest is the source-of-truth for where each curated util comes from.
+ * This check is the CI-enforced version of packages/utils/src/provenance.test.ts:
+ * it asserts the manifest and the barrel never drift apart, and that every
+ * lower-priority source pick is justified.
+ *
+ * Invariants (a violation of any fails the run):
+ *   - MISSING:      every barrel export has exactly one manifest entry;
+ *   - STALE:        every manifest key maps to a real barrel export;
+ *   - UNKNOWN:      every `source` is a known lib (LIB_PRIORITY ∪ unranked);
+ *   - UNJUSTIFIED:  if any lib in an entry's `alsoIn` outranks its `source`
+ *                   in LIB_PRIORITY, a non-empty `reason` is required.
+ *
+ * Priority is a soft default — `reason` is how a deliberate lower-priority pick
+ * is recorded and kept honest. See docs/utils-policy.md.
+ *
+ * Run:         bun ./src/check-utils-provenance.ts
+ * Strict mode: bun ./src/check-utils-provenance.ts --strict
+ *
+ * Both modes exit 1 on any violation (the manifest must always be in sync);
+ * `--strict` exists only to mirror the sibling checks' flag convention.
+ */
+
+import * as barrel from '@packrat/utils';
+import { LIB_PRIORITY, type ProvenanceEntry, provenance } from '@packrat/utils/provenance';
+
+const KNOWN_SOURCES = new Set<string>([...LIB_PRIORITY, 'destr', 'safe-stable-stringify']);
+
+const rankOf = (lib: string): number => (LIB_PRIORITY as readonly string[]).indexOf(lib);
+const isRanked = (lib: string): boolean => rankOf(lib) !== -1;
+
+export interface ProvenanceViolation {
+  kind: 'missing' | 'stale' | 'unknown' | 'unjustified';
+  name: string;
+  detail: string;
+}
+
+/**
+ * Pure validator — feeds the real barrel/manifest in production and synthetic
+ * fixtures in tests. Returns one violation per problem found (empty = valid).
+ */
+export function validateProvenance({
+  exportedNames,
+  manifest,
+}: {
+  exportedNames: string[];
+  manifest: Record<string, ProvenanceEntry>;
+}): ProvenanceViolation[] {
+  const violations: ProvenanceViolation[] = [];
+  const exportSet = new Set(exportedNames);
+  const manifestNames = Object.keys(manifest);
+
+  // a. Every barrel export has a manifest entry.
+  for (const name of exportedNames) {
+    if (!(name in manifest)) {
+      violations.push({
+        kind: 'missing',
+        name,
+        detail: `barrel export "${name}" has no manifest entry`,
+      });
+    }
+  }
+
+  // b. No stale manifest entries.
+  for (const name of manifestNames) {
+    if (!exportSet.has(name)) {
+      violations.push({
+        kind: 'stale',
+        name,
+        detail: `manifest entry "${name}" is not a barrel export`,
+      });
+    }
+  }
+
+  for (const [name, entry] of Object.entries(manifest)) {
+    // c. Known source.
+    if (!KNOWN_SOURCES.has(entry.source)) {
+      violations.push({
+        kind: 'unknown',
+        name,
+        detail: `source "${entry.source}" is not a known lib`,
+      });
+    }
+
+    // d. Lower-priority source requires a reason.
+    if (isRanked(entry.source) && entry.alsoIn) {
+      const outranked = entry.alsoIn.some(
+        (alt) => isRanked(alt) && rankOf(alt) < rankOf(entry.source),
+      );
+      if (outranked && !entry.reason?.trim()) {
+        violations.push({
+          kind: 'unjustified',
+          name,
+          detail: `source "${entry.source}" is outranked by a lib in alsoIn (${entry.alsoIn.join(
+            ', ',
+          )}) but no reason is given`,
+        });
+      }
+    }
+  }
+
+  return violations;
+}
+
+function report(violations: ProvenanceViolation[]): void {
+  if (violations.length === 0) {
+    const count = Object.keys(provenance).length;
+    console.log(
+      `✓ @packrat/utils provenance manifest in sync (${count} exports = ${count} entries).`,
+    );
+    return;
+  }
+
+  console.log(`Found ${violations.length} provenance violation(s) in @packrat/utils:\n`);
+
+  const labels: Record<ProvenanceViolation['kind'], string> = {
+    missing: 'Missing manifest entry',
+    stale: 'Stale manifest entry',
+    unknown: 'Unknown source lib',
+    unjustified: 'Unjustified lower-priority source (missing reason)',
+  };
+
+  for (const v of violations) {
+    console.log(`  [${labels[v.kind]}] ${v.detail}`);
+  }
+
+  console.log('\nFix packages/utils/src/provenance.ts so it matches the barrel exports.');
+  console.log('See docs/utils-policy.md for the source-priority policy.');
+}
+
+if (import.meta.main) {
+  const violations = validateProvenance({
+    exportedNames: Object.keys(barrel),
+    manifest: provenance,
+  });
+  report(violations);
+  // Both modes fail on any violation; --strict mirrors the sibling checks' flag.
+  process.exit(violations.length === 0 ? 0 : 1);
+}
diff --git a/packages/checks/vitest.config.ts b/packages/checks/vitest.config.ts
new file mode 100644
index 0000000000..3ec03ac340
--- /dev/null
+++ b/packages/checks/vitest.config.ts
@@ -0,0 +1,10 @@
+import { resolve } from 'node:path';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    name: 'checks',
+    environment: 'node',
+    include: [resolve(__dirname, 'src/**/*.test.ts')],
+  },
+});
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 4c40f617e1..f5a20e3cf6 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/cli",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "@packrat/api-client": "workspace:*",
     "@packrat/env": "workspace:*",
     "@packrat/guards": "workspace:*",
+    "@packrat/utils": "workspace:*",
     "chalk": "catalog:",
     "citty": "^0.2.1",
     "cli-table3": "^0.6.5",
diff --git a/packages/cli/src/api/config.ts b/packages/cli/src/api/config.ts
index d9de3e3bf1..b48f439467 100644
--- a/packages/cli/src/api/config.ts
+++ b/packages/cli/src/api/config.ts
@@ -14,6 +14,7 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { nodeEnv } from '@packrat/env/node';
+import { safeJsonParse, safeJsonStringify } from '@packrat/utils';
 import { z } from 'zod';
 
 const DEFAULT_BASE_URL = 'https://packrat.world';
@@ -51,7 +52,7 @@ async function loadPersisted(): Promise<CliConfig> {
   if (persisted) return persisted;
   try {
     const raw = await readFile(CONFIG_PATH, 'utf8');
-    const parsed = CliConfigSchema.safeParse(JSON.parse(raw));
+    const parsed = CliConfigSchema.safeParse(safeJsonParse(raw, { strict: true }));
     persisted = parsed.success ? parsed.data : emptyConfig;
   } catch (e) {
     if (isNotFound(e)) persisted = { ...emptyConfig };
@@ -83,7 +84,7 @@ export async function saveConfig(patch: Partial<CliConfig>): Promise<CliConfig>
   const next: CliConfig = { ...current, ...patch };
   await mkdir(dirname(CONFIG_PATH), { recursive: true });
   const tmp = `${CONFIG_PATH}.tmp`;
-  await writeFile(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
+  await writeFile(tmp, safeJsonStringify(next, null, 2), { mode: 0o600 });
   const { rename } = await import('node:fs/promises');
   await rename(tmp, CONFIG_PATH);
   persisted = next;
diff --git a/packages/cli/src/api/run.ts b/packages/cli/src/api/run.ts
index 51ba8f4520..3a6abba356 100644
--- a/packages/cli/src/api/run.ts
+++ b/packages/cli/src/api/run.ts
@@ -5,6 +5,7 @@
  */
 
 import { isObject, isString } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import chalk from 'chalk';
 import consola from 'consola';
 import { loadConfig } from './config';
@@ -170,7 +171,7 @@ function extractMessage(body: unknown): string | null {
     if (isString(obj.message)) return obj.message;
     if (isString(obj.error)) return obj.error;
     try {
-      return JSON.stringify(body);
+      return safeJsonStringify(body);
     } catch {
       return null;
     }
diff --git a/packages/cli/src/commands/admin/analytics.ts b/packages/cli/src/commands/admin/analytics.ts
index a1644ffbbb..e0d8a82af8 100644
--- a/packages/cli/src/commands/admin/analytics.ts
+++ b/packages/cli/src/commands/admin/analytics.ts
@@ -1,9 +1,10 @@
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import { getAdminClient } from '../../api/client';
 import { requireAdmin, runApi } from '../../api/run';
 
 function dump(value: unknown): void {
-  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+  process.stdout.write(`${safeJsonStringify(value, null, 2)}\n`);
 }
 
 const growthCmd = defineCommand({
diff --git a/packages/cli/src/commands/admin/catalog.ts b/packages/cli/src/commands/admin/catalog.ts
index cbecb68e14..83fa294eea 100644
--- a/packages/cli/src/commands/admin/catalog.ts
+++ b/packages/cli/src/commands/admin/catalog.ts
@@ -1,4 +1,5 @@
 import { isString, toRecord, toRecordArray } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import consola from 'consola';
 import { getAdminClient } from '../../api/client';
@@ -28,7 +29,7 @@ const listCmd = defineCommand({
       requiresAdmin: true,
     });
     if (args.json) {
-      process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+      process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
       return;
     }
     // Endpoint returns { data: [...], total, limit, offset }
diff --git a/packages/cli/src/commands/admin/etl.ts b/packages/cli/src/commands/admin/etl.ts
index 3fa6bb5676..42cfe25ed5 100644
--- a/packages/cli/src/commands/admin/etl.ts
+++ b/packages/cli/src/commands/admin/etl.ts
@@ -1,3 +1,4 @@
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import consola from 'consola';
 import { getAdminClient } from '../../api/client';
@@ -16,7 +17,7 @@ const listCmd = defineCommand({
       action: 'admin list ETL jobs',
       requiresAdmin: true,
     });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
@@ -33,7 +34,7 @@ const failureSummaryCmd = defineCommand({
       action: 'admin ETL failure summary',
       requiresAdmin: true,
     });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
@@ -54,7 +55,7 @@ const jobFailuresCmd = defineCommand({
       resourceHint: `job ${args.id}`,
       requiresAdmin: true,
     });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
@@ -68,7 +69,7 @@ const resetStuckCmd = defineCommand({
       action: 'admin reset stuck ETL',
       requiresAdmin: true,
     });
-    consola.success(`Done: ${JSON.stringify(data)}`);
+    consola.success(`Done: ${safeJsonStringify(data)}`);
   },
 });
 
@@ -84,7 +85,7 @@ const retryCmd = defineCommand({
       resourceHint: `job ${args.id}`,
       requiresAdmin: true,
     });
-    consola.success(`Retried: ${JSON.stringify(data)}`);
+    consola.success(`Retried: ${safeJsonStringify(data)}`);
   },
 });
 
diff --git a/packages/cli/src/commands/admin/packs.ts b/packages/cli/src/commands/admin/packs.ts
index b39c865e85..edaf0b4ae8 100644
--- a/packages/cli/src/commands/admin/packs.ts
+++ b/packages/cli/src/commands/admin/packs.ts
@@ -1,4 +1,5 @@
 import { toRecord, toRecordArray } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import consola from 'consola';
 import { getAdminClient } from '../../api/client';
@@ -30,7 +31,7 @@ const listCmd = defineCommand({
       requiresAdmin: true,
     });
     if (args.json) {
-      process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+      process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
       return;
     }
     // Endpoint returns { data: [...], total, limit, offset }
diff --git a/packages/cli/src/commands/admin/trails.ts b/packages/cli/src/commands/admin/trails.ts
index 58228a2897..410adefdee 100644
--- a/packages/cli/src/commands/admin/trails.ts
+++ b/packages/cli/src/commands/admin/trails.ts
@@ -1,4 +1,5 @@
 import { toRecord, toRecordArray } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import consola from 'consola';
 import { getAdminClient } from '../../api/client';
@@ -64,7 +65,7 @@ const reportsCmd = defineCommand({
       requiresAdmin: true,
     });
     if (args.json) {
-      process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+      process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
       return;
     }
     // Endpoint returns { data: [...], total, limit, offset }
diff --git a/packages/cli/src/commands/admin/users.ts b/packages/cli/src/commands/admin/users.ts
index 501d056b3e..4fdf883a2f 100644
--- a/packages/cli/src/commands/admin/users.ts
+++ b/packages/cli/src/commands/admin/users.ts
@@ -1,4 +1,5 @@
 import { toRecord, toRecordArray } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import consola from 'consola';
 import { getAdminClient } from '../../api/client';
@@ -28,7 +29,7 @@ const listCmd = defineCommand({
       requiresAdmin: true,
     });
     if (args.json) {
-      process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+      process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
       return;
     }
     // Endpoint returns { data: [...], total, limit, offset }
diff --git a/packages/cli/src/commands/ai/index.ts b/packages/cli/src/commands/ai/index.ts
index cdc224d884..104e6093e6 100644
--- a/packages/cli/src/commands/ai/index.ts
+++ b/packages/cli/src/commands/ai/index.ts
@@ -1,3 +1,4 @@
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import { getUserClient } from '../../api/client';
 import { requireAuth, runApi } from '../../api/run';
@@ -17,7 +18,7 @@ const ragCmd = defineCommand({
       }),
       action: 'rag search',
     });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
@@ -31,7 +32,7 @@ const webCmd = defineCommand({
       promise: client.ai['web-search'].get({ query: { q: args.q } }),
       action: 'web search',
     });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
@@ -51,7 +52,7 @@ const sqlCmd = defineCommand({
       }),
       action: 'execute sql',
     });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
@@ -61,7 +62,7 @@ const schemaCmd = defineCommand({
     await requireAuth();
     const client = await getUserClient();
     const data = await runApi({ promise: client.ai['db-schema'].get(), action: 'fetch db schema' });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
diff --git a/packages/cli/src/commands/auth/login.ts b/packages/cli/src/commands/auth/login.ts
index 505e9fe793..8bffd538a2 100644
--- a/packages/cli/src/commands/auth/login.ts
+++ b/packages/cli/src/commands/auth/login.ts
@@ -1,3 +1,4 @@
+import { safeJsonStringify } from '@packrat/utils';
 import chalk from 'chalk';
 import { defineCommand } from 'citty';
 import consola from 'consola';
@@ -35,7 +36,7 @@ export default defineCommand({
     const response = await fetch(`${baseUrl}/api/auth/sign-in/email`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ email, password }),
+      body: safeJsonStringify({ email, password }),
     });
 
     if (!response.ok) {
diff --git a/packages/cli/src/commands/auth/refresh.ts b/packages/cli/src/commands/auth/refresh.ts
index 35326a1aed..7b80b63b73 100644
--- a/packages/cli/src/commands/auth/refresh.ts
+++ b/packages/cli/src/commands/auth/refresh.ts
@@ -1,3 +1,4 @@
+import { safeJsonStringify } from '@packrat/utils';
 import chalk from 'chalk';
 import { defineCommand } from 'citty';
 import consola from 'consola';
@@ -26,7 +27,7 @@ export default defineCommand({
     const response = await fetch(`${baseUrl}/api/auth/refresh`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ refreshToken: config.refreshToken }),
+      body: safeJsonStringify({ refreshToken: config.refreshToken }),
     });
     const parsed = RefreshResponseSchema.safeParse(await response.json().catch(() => null));
     if (!response.ok || !parsed.success || !parsed.data.accessToken) {
diff --git a/packages/cli/src/commands/auth/register.ts b/packages/cli/src/commands/auth/register.ts
index 55cb05d6cc..22e2488885 100644
--- a/packages/cli/src/commands/auth/register.ts
+++ b/packages/cli/src/commands/auth/register.ts
@@ -1,3 +1,4 @@
+import { safeJsonStringify } from '@packrat/utils';
 import chalk from 'chalk';
 import { defineCommand } from 'citty';
 import consola from 'consola';
@@ -31,7 +32,7 @@ export default defineCommand({
     const response = await fetch(`${baseUrl}/api/auth/sign-up/email`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ email, password, name }),
+      body: safeJsonStringify({ email, password, name }),
     });
 
     if (!response.ok) {
diff --git a/packages/cli/src/commands/catalog/index.ts b/packages/cli/src/commands/catalog/index.ts
index 15e3f07613..63a868f327 100644
--- a/packages/cli/src/commands/catalog/index.ts
+++ b/packages/cli/src/commands/catalog/index.ts
@@ -1,4 +1,5 @@
 import { isString, toRecord, toRecordArray } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import { getUserClient } from '../../api/client';
 import { requireAuth, runApi } from '../../api/run';
@@ -25,7 +26,7 @@ const searchCmd = defineCommand({
       action: 'search catalog',
     });
     if (args.json) {
-      process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+      process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
       return;
     }
     printTable({
@@ -58,7 +59,7 @@ const semanticCmd = defineCommand({
       action: 'semantic catalog search',
     });
     if (args.json) {
-      process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+      process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
       return;
     }
     printTable({
@@ -88,7 +89,7 @@ const getCmd = defineCommand({
       resourceHint: `item ${args.id}`,
     });
     if (args.json) {
-      process.stdout.write(`${JSON.stringify(item, null, 2)}\n`);
+      process.stdout.write(`${safeJsonStringify(item, null, 2)}\n`);
       return;
     }
     const r = toRecord(item);
@@ -117,7 +118,7 @@ const categoriesCmd = defineCommand({
       promise: client.catalog.categories.get({ query: { limit: 50 } }),
       action: 'list catalog categories',
     });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
diff --git a/packages/cli/src/commands/feed/index.ts b/packages/cli/src/commands/feed/index.ts
index ff5417641d..dc8e24b702 100644
--- a/packages/cli/src/commands/feed/index.ts
+++ b/packages/cli/src/commands/feed/index.ts
@@ -1,3 +1,4 @@
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import { getUserClient } from '../../api/client';
 import { requireAuth, runApi } from '../../api/run';
@@ -17,7 +18,7 @@ const listCmd = defineCommand({
       }),
       action: 'list feed',
     });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
@@ -40,7 +41,7 @@ const postCmd = defineCommand({
       promise: client.feed.post({ caption: args.caption, images }),
       action: 'create feed post',
     });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
@@ -55,7 +56,7 @@ const likeCmd = defineCommand({
       action: 'toggle post like',
       resourceHint: `post ${args.id}`,
     });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
@@ -77,7 +78,7 @@ const commentCmd = defineCommand({
       action: 'create feed comment',
       resourceHint: `post ${args.id}`,
     });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
diff --git a/packages/cli/src/commands/packs/gap-analysis.ts b/packages/cli/src/commands/packs/gap-analysis.ts
index 831ad8b943..39542feea3 100644
--- a/packages/cli/src/commands/packs/gap-analysis.ts
+++ b/packages/cli/src/commands/packs/gap-analysis.ts
@@ -1,3 +1,4 @@
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import consola from 'consola';
 import { getUserClient } from '../../api/client';
@@ -43,6 +44,6 @@ export default defineCommand({
       action: 'analyze pack gaps',
       resourceHint: `pack ${args.id}`,
     });
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(result, null, 2)}\n`);
   },
 });
diff --git a/packages/cli/src/commands/packs/get.ts b/packages/cli/src/commands/packs/get.ts
index eaa39372cc..6952efea89 100644
--- a/packages/cli/src/commands/packs/get.ts
+++ b/packages/cli/src/commands/packs/get.ts
@@ -1,4 +1,5 @@
 import { toRecord } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import { getUserClient } from '../../api/client';
 import { requireAuth, runApi } from '../../api/run';
@@ -19,7 +20,7 @@ export default defineCommand({
       resourceHint: `pack ${args.id}`,
     });
     if (args.json) {
-      process.stdout.write(`${JSON.stringify(pack, null, 2)}\n`);
+      process.stdout.write(`${safeJsonStringify(pack, null, 2)}\n`);
       return;
     }
     const p = toRecord(pack);
diff --git a/packages/cli/src/commands/packs/items.ts b/packages/cli/src/commands/packs/items.ts
index 6e94b3e0c0..6c4599561d 100644
--- a/packages/cli/src/commands/packs/items.ts
+++ b/packages/cli/src/commands/packs/items.ts
@@ -1,4 +1,5 @@
 import { toRecordArray } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import { getUserClient } from '../../api/client';
 import { requireAuth, runApi } from '../../api/run';
@@ -19,7 +20,7 @@ export default defineCommand({
       resourceHint: `pack ${args.id}`,
     });
     if (args.json) {
-      process.stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+      process.stdout.write(`${safeJsonStringify(items, null, 2)}\n`);
       return;
     }
     printTable({
diff --git a/packages/cli/src/commands/packs/list.ts b/packages/cli/src/commands/packs/list.ts
index 68921b1a67..418e6e2067 100644
--- a/packages/cli/src/commands/packs/list.ts
+++ b/packages/cli/src/commands/packs/list.ts
@@ -1,4 +1,5 @@
 import { toRecordArray } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import { getUserClient } from '../../api/client';
 import { requireAuth, runApi } from '../../api/run';
@@ -23,7 +24,7 @@ export default defineCommand({
       action: 'list packs',
     });
     if (args.json) {
-      process.stdout.write(`${JSON.stringify(packs, null, 2)}\n`);
+      process.stdout.write(`${safeJsonStringify(packs, null, 2)}\n`);
       return;
     }
     printTable({
diff --git a/packages/cli/src/commands/seasons/index.ts b/packages/cli/src/commands/seasons/index.ts
index 40c4ae8d01..181756008f 100644
--- a/packages/cli/src/commands/seasons/index.ts
+++ b/packages/cli/src/commands/seasons/index.ts
@@ -1,3 +1,4 @@
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import { getUserClient } from '../../api/client';
 import { requireAuth, runApi } from '../../api/run';
@@ -18,6 +19,6 @@ export default defineCommand({
       promise: client['season-suggestions'].post({ location: args.location, date: args.date }),
       action: 'season suggestions',
     });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
diff --git a/packages/cli/src/commands/templates/index.ts b/packages/cli/src/commands/templates/index.ts
index 319a961d57..927b68893e 100644
--- a/packages/cli/src/commands/templates/index.ts
+++ b/packages/cli/src/commands/templates/index.ts
@@ -1,4 +1,5 @@
 import { toRecordArray } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import { getUserClient } from '../../api/client';
 import { nowIso, shortId } from '../../api/ids';
@@ -16,7 +17,7 @@ const listCmd = defineCommand({
       action: 'list pack templates',
     });
     if (args.json) {
-      process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+      process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
       return;
     }
     printTable({
@@ -42,7 +43,7 @@ const getCmd = defineCommand({
       action: 'get pack template',
       resourceHint: `template ${args.id}`,
     });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
@@ -74,7 +75,7 @@ const createCmd = defineCommand({
       }),
       action: 'create pack template',
     });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
diff --git a/packages/cli/src/commands/trails/index.ts b/packages/cli/src/commands/trails/index.ts
index f3899d477f..7d47e29208 100644
--- a/packages/cli/src/commands/trails/index.ts
+++ b/packages/cli/src/commands/trails/index.ts
@@ -1,4 +1,5 @@
 import { toRecord, toRecordArray } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import { getUserClient } from '../../api/client';
 import { requireAuth, runApi } from '../../api/run';
@@ -34,7 +35,7 @@ const searchCmd = defineCommand({
       action: 'search trails',
     });
     if (args.json) {
-      process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+      process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
       return;
     }
     printTable({
@@ -60,7 +61,7 @@ const getCmd = defineCommand({
       action: 'get trail',
       resourceHint: `trail ${args.id}`,
     });
-    process.stdout.write(`${JSON.stringify(trail, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(trail, null, 2)}\n`);
   },
 });
 
@@ -75,7 +76,7 @@ const geometryCmd = defineCommand({
       action: 'get trail geometry',
       resourceHint: `trail ${args.id}`,
     });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
diff --git a/packages/cli/src/commands/trips/index.ts b/packages/cli/src/commands/trips/index.ts
index e6f7f60752..b3cf2de9d4 100644
--- a/packages/cli/src/commands/trips/index.ts
+++ b/packages/cli/src/commands/trips/index.ts
@@ -1,4 +1,5 @@
 import { toRecord, toRecordArray } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import { getUserClient } from '../../api/client';
 import { nowIso, shortId } from '../../api/ids';
@@ -13,7 +14,7 @@ const listCmd = defineCommand({
     const client = await getUserClient();
     const trips = await runApi({ promise: client.trips.get(), action: 'list trips' });
     if (args.json) {
-      process.stdout.write(`${JSON.stringify(trips, null, 2)}\n`);
+      process.stdout.write(`${safeJsonStringify(trips, null, 2)}\n`);
       return;
     }
     printTable({
@@ -44,7 +45,7 @@ const getCmd = defineCommand({
       resourceHint: `trip ${args.id}`,
     });
     if (args.json) {
-      process.stdout.write(`${JSON.stringify(trip, null, 2)}\n`);
+      process.stdout.write(`${safeJsonStringify(trip, null, 2)}\n`);
       return;
     }
     const t = toRecord(trip);
@@ -101,7 +102,7 @@ const createCmd = defineCommand({
       }),
       action: 'create trip',
     });
-    process.stdout.write(`${JSON.stringify(trip, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(trip, null, 2)}\n`);
   },
 });
 
diff --git a/packages/cli/src/commands/user/index.ts b/packages/cli/src/commands/user/index.ts
index 96af7dd03f..22f7a38385 100644
--- a/packages/cli/src/commands/user/index.ts
+++ b/packages/cli/src/commands/user/index.ts
@@ -1,4 +1,5 @@
 import { toRecord } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import { getUserClient } from '../../api/client';
 import { requireAuth, runApi } from '../../api/run';
@@ -41,7 +42,7 @@ const updateCmd = defineCommand({
     if (args.email) body.email = args.email;
     if (args.avatar) body.avatarUrl = args.avatar;
     const data = await runApi({ promise: client.user.profile.put(body), action: 'update profile' });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
diff --git a/packages/cli/src/commands/weather/index.ts b/packages/cli/src/commands/weather/index.ts
index 0649994212..a5e470208d 100644
--- a/packages/cli/src/commands/weather/index.ts
+++ b/packages/cli/src/commands/weather/index.ts
@@ -1,3 +1,4 @@
+import { safeJsonStringify } from '@packrat/utils';
 import { defineCommand } from 'citty';
 import { getUserClient } from '../../api/client';
 import { requireAuth, runApi } from '../../api/run';
@@ -18,7 +19,7 @@ const forecastCmd = defineCommand({
       action: 'get weather forecast',
       resourceHint: args.location,
     });
-    process.stdout.write(`${JSON.stringify(forecast, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(forecast, null, 2)}\n`);
   },
 });
 
@@ -32,7 +33,7 @@ const searchCmd = defineCommand({
       promise: client.weather.search.get({ query: { q: args.q } }),
       action: 'search weather',
     });
-    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    process.stdout.write(`${safeJsonStringify(data, null, 2)}\n`);
   },
 });
 
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index d800ace122..afbfb2ea3a 100755
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -9,6 +9,7 @@ import { readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { nodeEnv } from '@packrat/env/node';
+import { safeJsonParse } from '@packrat/utils';
 import { defineCommand, runMain } from 'citty';
 import consola from 'consola';
 import { z } from 'zod';
@@ -21,7 +22,9 @@ function getCliVersion(): string {
   try {
     const currentDir = dirname(fileURLToPath(import.meta.url));
     const packageJsonPath = resolve(currentDir, '../package.json');
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as unknown;
+    const packageJson = safeJsonParse(readFileSync(packageJsonPath, 'utf-8'), {
+      strict: true,
+    }) as unknown;
     const parsed = packageVersionSchema.safeParse(packageJson);
     if (!parsed.success) {
       consola.warn('package.json is missing a valid string "version" field.');
diff --git a/packages/config/package.json b/packages/config/package.json
index 700d85b193..7eeb7030d7 100644
--- a/packages/config/package.json
+++ b/packages/config/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/config",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "exports": {
diff --git a/packages/constants/package.json b/packages/constants/package.json
index 3162cad936..871e4bd5bc 100644
--- a/packages/constants/package.json
+++ b/packages/constants/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/constants",
-  "version": "0.0.0",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "exports": {
diff --git a/packages/db/package.json b/packages/db/package.json
index 43aafc6b19..a78c2785bc 100644
--- a/packages/db/package.json
+++ b/packages/db/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/db",
-  "version": "0.0.0",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "exports": {
diff --git a/packages/db/src/schema.ts b/packages/db/src/schema.ts
index 6f8b9d807a..e8bc3edfe2 100644
--- a/packages/db/src/schema.ts
+++ b/packages/db/src/schema.ts
@@ -4,6 +4,7 @@ import {
   type AnyPgColumn,
   bigint,
   boolean,
+  check,
   index,
   integer,
   jsonb,
@@ -472,9 +473,42 @@ export const etlJobs = pgTable(
     totalValid: integer('total_valid'),
     totalInvalid: integer('total_invalid'),
     scraperRevision: text('scraper_revision').notNull(),
+    // Workflows-aware columns. workflowInstanceId links the row to its
+    // CatalogEtlWorkflow instance (null on legacy queue-path rows; set on
+    // workflow-path rows). totalEmbeddingFailures counts SKUs that were
+    // upserted without embeddings because generateManyEmbeddings threw —
+    // observable degradation signal for the embedding service.
+    workflowInstanceId: text('workflow_instance_id'),
+    totalEmbeddingFailures: integer('total_embedding_failures').default(0).notNull(),
+    // Post-ingestion row-count verification, written by the admin reconcile
+    // endpoint. verifiedRowCount is the logical CSV row count parsed from
+    // the R2 source; mismatches against totalProcessed indicate data drift.
+    verifiedAt: timestamp('verified_at'),
+    verifiedRowCount: integer('verified_row_count'),
+    // R2 source provenance captured at ingest time. Repair-from-scratch
+    // refuses to re-ingest when the live R2 etag no longer matches the
+    // stored value (unless overridden with ?force=true) so a scraper
+    // overwrite mid-flight can't be silently re-applied under the old
+    // (source, filename).
+    sourceEtag: text('source_etag'),
+    sourceLastModified: timestamp('source_last_modified'),
+    // Audit trail for repair-from-scratch / retry. supersededByJobId
+    // points at the ORIGINAL job (the new repair-job row carries the
+    // pointer); supersededAt is the time of supersession. CHECK
+    // constraint prevents self-reference.
+    supersededByJobId: text('superseded_by_job_id').references((): AnyPgColumn => etlJobs.id, {
+      onDelete: 'set null',
+    }),
+    supersededAt: timestamp('superseded_at'),
   },
   (table) => ({
     scraperRevisionIdx: index('etl_jobs_scraper_revision_idx').on(table.scraperRevision),
+    workflowInstanceIdIdx: index('etl_jobs_workflow_instance_id_idx').on(table.workflowInstanceId),
+    supersededByIdx: index('etl_jobs_superseded_by_idx').on(table.supersededByJobId),
+    noSelfSupersede: check(
+      'etl_jobs_no_self_supersede',
+      sql`${table.supersededByJobId} IS NULL OR ${table.supersededByJobId} <> ${table.id}`,
+    ),
   }),
 );
 
diff --git a/packages/env/package.json b/packages/env/package.json
index 8613670b3b..6e0781a68f 100644
--- a/packages/env/package.json
+++ b/packages/env/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/env",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "exports": {
diff --git a/packages/guards/package.json b/packages/guards/package.json
index cbd461f0fe..dd0e2800bf 100644
--- a/packages/guards/package.json
+++ b/packages/guards/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/guards",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "exports": {
@@ -12,7 +12,7 @@
     "check-types": "tsc --noEmit"
   },
   "dependencies": {
-    "radash": "catalog:",
+    "@packrat/utils": "workspace:*",
     "ts-extras": "catalog:",
     "zod": "catalog:"
   }
diff --git a/packages/guards/src/index.ts b/packages/guards/src/index.ts
index 27247c2a64..d797fefc60 100644
--- a/packages/guards/src/index.ts
+++ b/packages/guards/src/index.ts
@@ -2,12 +2,12 @@
  * @packrat/guards — runtime type guards and narrowing helpers.
  *
  * Single import path for all type narrowing in the monorepo.
- * Composes radash primitives, ts-extras utilities, and custom
- * project-specific helpers. Never use `as SomeType` casts — use
- * a guard or parser from this package instead.
+ * Composes generic predicates (via @packrat/utils, the sole lib importer),
+ * ts-extras utilities, and custom project-specific helpers. Never use
+ * `as SomeType` casts — use a guard or parser from this package instead.
  */
 
-// --- radash primitives ---
+// --- generic predicates (sourced through @packrat/utils) ---
 export {
   isArray,
   isDate,
@@ -22,7 +22,7 @@ export {
   isPromise,
   isString,
   isSymbol,
-} from 'radash';
+} from '@packrat/utils';
 // --- ts-extras: nullish guards ---
 // --- ts-extras: assertion helpers ---
 // --- ts-extras: type-safe object/array utilities ---
diff --git a/packages/mcp/package.json b/packages/mcp/package.json
index 966d4e32d9..63e2595c5e 100644
--- a/packages/mcp/package.json
+++ b/packages/mcp/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/mcp",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "description": "PackRat MCP Server — outdoor adventure planning via Model Context Protocol",
   "scripts": {
@@ -16,6 +16,7 @@
     "@cloudflare/workers-oauth-provider": "^0.4.0",
     "@modelcontextprotocol/sdk": "^1.11.0",
     "@packrat/api-client": "workspace:*",
+    "@packrat/utils": "workspace:*",
     "agents": "^0.11.0",
     "magic-regexp": "catalog:",
     "zod": "catalog:"
diff --git a/packages/mcp/src/auth.ts b/packages/mcp/src/auth.ts
index 7a18b6eafd..fcbd9499ca 100644
--- a/packages/mcp/src/auth.ts
+++ b/packages/mcp/src/auth.ts
@@ -14,6 +14,7 @@
  */
 
 import { isString } from '@packrat/guards';
+import { safeJsonParse, safeJsonStringify } from '@packrat/utils';
 import { createRegExp, exactly, global as globalFlag } from 'magic-regexp';
 import { z } from 'zod';
 import type { Env, Props } from './types';
@@ -175,7 +176,7 @@ async function handleAuthorize({
   }
 
   const stateKey = crypto.randomUUID();
-  await env.OAUTH_KV.put(oauthStateKey(stateKey), JSON.stringify(oauthReq), {
+  await env.OAUTH_KV.put(oauthStateKey(stateKey), safeJsonStringify(oauthReq), {
     expirationTtl: STATE_TTL,
   });
 
@@ -238,7 +239,7 @@ async function handleLoginPost({
     signInRes = await fetch(`${env.PACKRAT_API_URL}/api/auth/sign-in/email`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ email, password }),
+      body: safeJsonStringify({ email, password }),
     });
   } catch {
     return new Response(loginPage({ state, error: 'Could not reach PackRat. Try again.' }), {
@@ -268,7 +269,7 @@ async function handleLoginPost({
     );
   }
 
-  await env.OAUTH_KV.put(sessionKey(state), JSON.stringify({ token: betterAuthToken, userId }), {
+  await env.OAUTH_KV.put(sessionKey(state), safeJsonStringify({ token: betterAuthToken, userId }), {
     expirationTtl: STATE_TTL,
   });
 
@@ -294,8 +295,8 @@ async function handleCallback({ request, env }: { request: Request; env: Env }):
     );
   }
 
-  const oauthReqResult = OAuthStateSchema.safeParse(JSON.parse(oauthReqStr));
-  const sessionResult = SessionKvSchema.safeParse(JSON.parse(sessionStr));
+  const oauthReqResult = OAuthStateSchema.safeParse(safeJsonParse(oauthReqStr));
+  const sessionResult = SessionKvSchema.safeParse(safeJsonParse(sessionStr));
 
   if (!oauthReqResult.success || !sessionResult.success) {
     return Response.json(
diff --git a/packages/mcp/src/client.ts b/packages/mcp/src/client.ts
index 4ab69eaa6e..4a1431aba0 100644
--- a/packages/mcp/src/client.ts
+++ b/packages/mcp/src/client.ts
@@ -16,6 +16,7 @@
 
 import { type ApiClient, createApiClient } from '@packrat/api-client';
 import { isObject, isString } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 
 export type TokenProvider = () => string | null | undefined;
 
@@ -66,7 +67,7 @@ export type McpToolResult = {
 };
 
 export function ok(data: unknown): McpToolResult {
-  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+  return { content: [{ type: 'text', text: safeJsonStringify(data, null, 2) }] };
 }
 
 export function errMessage(message: string): McpToolResult {
@@ -166,7 +167,7 @@ function extractErrorMessage(body: unknown): string | null {
     if (isString(obj.message)) return obj.message;
     if (isString(obj.error)) return obj.error;
     try {
-      return JSON.stringify(body);
+      return safeJsonStringify(body);
     } catch {
       return null;
     }
diff --git a/packages/mcp/src/resources.ts b/packages/mcp/src/resources.ts
index e5785a81f3..d85984bc49 100644
--- a/packages/mcp/src/resources.ts
+++ b/packages/mcp/src/resources.ts
@@ -1,5 +1,6 @@
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { isObject, isString } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import type { AgentContext } from './types';
 
 type TreatyResult = {
@@ -22,7 +23,7 @@ function asContent({ uri, body }: { uri: string; body: object }): {
   contents: Array<{ uri: string; mimeType: string; text: string }>;
 } {
   return {
-    contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(body, null, 2) }],
+    contents: [{ uri, mimeType: 'application/json', text: safeJsonStringify(body, null, 2) }],
   };
 }
 
diff --git a/packages/mcp/src/tools/auth.ts b/packages/mcp/src/tools/auth.ts
index c13c0f0af5..33ada1cba3 100644
--- a/packages/mcp/src/tools/auth.ts
+++ b/packages/mcp/src/tools/auth.ts
@@ -12,6 +12,7 @@
  */
 
 import { isObject } from '@packrat/guards';
+import { safeJsonStringify } from '@packrat/utils';
 import { z } from 'zod';
 import { call, errMessage, ok } from '../client';
 import type { AgentContext } from '../types';
@@ -47,7 +48,7 @@ export function registerAuthTools(agent: AgentContext): void {
       if (result.error || !result.data) {
         const detail = isObject(result.error) ? (result.error.value ?? null) : null;
         return errMessage(
-          `Admin login failed (HTTP ${result.status})${detail ? `: ${JSON.stringify(detail)}` : ''}`,
+          `Admin login failed (HTTP ${result.status})${detail ? `: ${safeJsonStringify(detail)}` : ''}`,
         );
       }
       agent.setAdminToken(result.data.token);
diff --git a/packages/osm-db/package.json b/packages/osm-db/package.json
index 172194d623..4db6952504 100644
--- a/packages/osm-db/package.json
+++ b/packages/osm-db/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/osm-db",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "exports": {
diff --git a/packages/osm-import/package.json b/packages/osm-import/package.json
index d769b33b27..6881c464c0 100644
--- a/packages/osm-import/package.json
+++ b/packages/osm-import/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/osm-import",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "description": "osm2pgsql flex config and import tooling for PackRat outdoor routes",
   "type": "module",
diff --git a/packages/overpass/package.json b/packages/overpass/package.json
index 2b8662a748..697bf37657 100644
--- a/packages/overpass/package.json
+++ b/packages/overpass/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/overpass",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "exports": {
diff --git a/packages/schemas/package.json b/packages/schemas/package.json
index 627dece8c8..ad400aaba7 100644
--- a/packages/schemas/package.json
+++ b/packages/schemas/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/schemas",
-  "version": "0.0.0",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "exports": {
@@ -20,6 +20,7 @@
     "@packrat/constants": "workspace:*",
     "@packrat/db": "workspace:*",
     "@packrat/guards": "workspace:*",
+    "@packrat/utils": "workspace:*",
     "zod": "catalog:"
   },
   "devDependencies": {
diff --git a/packages/schemas/src/admin.ts b/packages/schemas/src/admin.ts
index 17b2fe4a72..2a9f38a27c 100644
--- a/packages/schemas/src/admin.ts
+++ b/packages/schemas/src/admin.ts
@@ -179,6 +179,10 @@ export const EtlJobSchema = z.object({
   totalValid: z.number().nullable(),
   totalInvalid: z.number().nullable(),
   successRate: z.number().nullable(),
+  failureRate: z.number().nullable(),
+  totalEmbeddingFailures: z.number(),
+  verifiedRowCount: z.number().nullable(),
+  verifiedAt: z.string().nullable(),
 });
 
 export const EtlResponseSchema = z.object({
@@ -230,6 +234,51 @@ export const EtlRetrySchema = z.object({
   success: z.literal(true),
   newJobId: z.string(),
   objectKey: z.string(),
+  workflowInstanceId: z.string().nullable(),
+});
+
+export const EtlReconcileSchema = z.object({
+  success: z.literal(true),
+  jobId: z.string(),
+  expectedRowCount: z.number().int(),
+  actualRowCount: z.number().int().nullable(),
+  delta: z.number().int().nullable(),
+});
+
+export const CatalogAuditSourceSchema = z.object({
+  source: z.string(),
+  totalItems: z.number().int(),
+  lastEtlId: z.string().nullable(),
+  lastEtlAt: z.string().nullable(),
+  daysStale: z.number().int().nullable(),
+  medianPrice: z.number().nullable(),
+  minPrice: z.number().nullable(),
+  maxPrice: z.number().nullable(),
+  nullRates: z.object({
+    price: z.number(),
+    brand: z.number(),
+    description: z.number(),
+    weight: z.number(),
+    images: z.number(),
+    availability: z.number(),
+  }),
+  suspiciousDecimalCount: z.number().int(),
+  suspiciousWeightCount: z.number().int(),
+  emptyNameCount: z.number().int(),
+  flags: z.array(z.string()),
+});
+
+export const CatalogAuditSchema = z.object({
+  generatedAt: z.string(),
+  thresholds: z.object({
+    decimalBugPriceThreshold: z.number(),
+    lowMedianPriceThreshold: z.number(),
+    minFillRate: z.number(),
+    staleDaysThreshold: z.number(),
+    weightTooLightGrams: z.number(),
+    weightTooHeavyGrams: z.number(),
+  }),
+  sources: z.array(CatalogAuditSourceSchema),
 });
 
 // ─── Trails ───────────────────────────────────────────────────────────────────
diff --git a/packages/schemas/src/catalog.ts b/packages/schemas/src/catalog.ts
index 627dad23d1..86a080d365 100644
--- a/packages/schemas/src/catalog.ts
+++ b/packages/schemas/src/catalog.ts
@@ -1,5 +1,6 @@
 import { WEIGHT_UNITS } from '@packrat/constants';
 import { isString } from '@packrat/guards';
+import { safeJsonParse } from '@packrat/utils';
 import { z } from 'zod';
 import { datetimeString } from './utils';
 
@@ -8,8 +9,8 @@ export const CatalogItemSchema = z.object({
   name: z.string(),
   productUrl: z.string(),
   sku: z.string(),
-  weight: z.number(),
-  weightUnit: z.enum(WEIGHT_UNITS),
+  weight: z.number().nullable(),
+  weightUnit: z.enum(WEIGHT_UNITS).nullable(),
   description: z.string().nullable(),
   categories: z.array(z.string()).nullable(),
   images: z.array(z.string()).nullable(),
@@ -125,7 +126,7 @@ export const CatalogItemsQuerySchema = z.object({
     .preprocess((val) => {
       if (isString(val)) {
         try {
-          return JSON.parse(val);
+          return safeJsonParse(val, { strict: true });
         } catch {
           return undefined;
         }
diff --git a/packages/types/package.json b/packages/types/package.json
index 236c2df0a4..a56ac2522c 100644
--- a/packages/types/package.json
+++ b/packages/types/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/types",
-  "version": "0.0.0",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "exports": {
diff --git a/packages/ui/package.json b/packages/ui/package.json
index d0e9229b9a..d5708a9659 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/ui",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "scripts": {
     "_disabled-check-types-reason": "Renamed from check-types so turbo skips this workspace. The package only re-exports from @packrat-ai/nativewindui — that upstream package ships source .tsx (not .d.ts) so tsc deep-checks it and surfaces 197 errors from upstream code we don't control. Fix path: either update upstream, or replace the re-export pattern with a proper shim. Tracked separately.",
diff --git a/packages/units/package.json b/packages/units/package.json
index 43b1d462b7..e89105151e 100644
--- a/packages/units/package.json
+++ b/packages/units/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/units",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "exports": {
diff --git a/packages/utils/package.json b/packages/utils/package.json
new file mode 100644
index 0000000000..6d9ab88101
--- /dev/null
+++ b/packages/utils/package.json
@@ -0,0 +1,37 @@
+{
+  "name": "@packrat/utils",
+  "version": "2.0.27",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./array": "./src/array.ts",
+    "./object": "./src/object.ts",
+    "./string": "./src/string.ts",
+    "./async": "./src/async.ts",
+    "./fn": "./src/fn.ts",
+    "./json": "./src/json.ts",
+    "./math": "./src/math.ts",
+    "./predicates": "./src/predicates.ts",
+    "./provenance": "./src/provenance.ts"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "destr": "^2.0.5",
+    "es-toolkit": "^1.47.0",
+    "lodash": "^4.18.1",
+    "radash": "catalog:",
+    "radashi": "^12.9.1",
+    "remeda": "^2.37.0",
+    "safe-stable-stringify": "^2.5.0"
+  },
+  "devDependencies": {
+    "@types/lodash": "^4.17.24",
+    "vitest": "catalog:"
+  }
+}
diff --git a/packages/utils/src/array.ts b/packages/utils/src/array.ts
new file mode 100644
index 0000000000..7fdc896575
--- /dev/null
+++ b/packages/utils/src/array.ts
@@ -0,0 +1,9 @@
+/**
+ * Array utilities — curated re-exports. See ./provenance for source mapping.
+ */
+
+// es-toolkit — chunk (radashi's equivalent is `cluster`; `chunk` is the
+// ecosystem-standard name, so we source it here)
+export { chunk } from 'es-toolkit';
+// radashi — dedupe, group, sort, build
+export { group, list, sort, unique } from 'radashi';
diff --git a/packages/utils/src/async.ts b/packages/utils/src/async.ts
new file mode 100644
index 0000000000..245a180906
--- /dev/null
+++ b/packages/utils/src/async.ts
@@ -0,0 +1,6 @@
+/**
+ * Async / concurrency utilities — curated re-exports. See ./provenance for source mapping.
+ */
+
+// radashi — sleep, error-tuple wrappers, retry, bounded concurrency
+export { all, guard, parallel, retry, sleep, tryit } from 'radashi';
diff --git a/packages/utils/src/fn.ts b/packages/utils/src/fn.ts
new file mode 100644
index 0000000000..b612c54df3
--- /dev/null
+++ b/packages/utils/src/fn.ts
@@ -0,0 +1,8 @@
+/**
+ * Function utilities — curated re-exports. See ./provenance for source mapping.
+ */
+
+// radashi — memoize, once, rate-limiters
+export { debounce, memo, once, throttle } from 'radashi';
+// remeda — typed dataLast `pipe` for composition (composability primitive)
+export { pipe } from 'remeda';
diff --git a/packages/utils/src/index.ts b/packages/utils/src/index.ts
new file mode 100644
index 0000000000..40a7789750
--- /dev/null
+++ b/packages/utils/src/index.ts
@@ -0,0 +1,21 @@
+/**
+ * @packrat/utils — curated, type-safe utility surface for the monorepo.
+ *
+ * Single import path for general-purpose utilities. Curates the best-typed
+ * implementation of each helper across radashi, radash, es-toolkit, lodash,
+ * and remeda (soft priority in that order; real tiebreaker is best types +
+ * has-the-function). Re-export by default; wrap only when normalization
+ * (single-object args, consistent naming) or composition earns it.
+ *
+ * This is the ONLY package allowed to import those libraries directly —
+ * everything else imports from '@packrat/utils' (or '@packrat/guards' for
+ * type narrowing). See docs/utils-policy.md.
+ */
+export * from './array';
+export * from './async';
+export * from './fn';
+export * from './json';
+export * from './math';
+export * from './object';
+export * from './predicates';
+export * from './string';
diff --git a/packages/utils/src/json.test.ts b/packages/utils/src/json.test.ts
new file mode 100644
index 0000000000..b91bbaf7e0
--- /dev/null
+++ b/packages/utils/src/json.test.ts
@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import {
+  configureJsonStringify,
+  safeJsonParse,
+  safeJsonStringify,
+  stableJsonStringify,
+} from './json';
+
+describe('safeJsonStringify', () => {
+  it('preserves key insertion order (drop-in for JSON.stringify)', () => {
+    expect(safeJsonStringify({ b: 2, a: 1 })).toBe('{"b":2,"a":1}');
+  });
+
+  it('does not throw on circular references', () => {
+    const circular: Record<string, unknown> = { name: 'root' };
+    circular.self = circular;
+    const out = safeJsonStringify(circular);
+    expect(typeof out).toBe('string');
+    expect(out).toContain('"name":"root"');
+  });
+
+  it('serializes BigInt instead of throwing', () => {
+    expect(safeJsonStringify({ n: 10n })).toBe('{"n":10}');
+  });
+
+  it('honors the space argument', () => {
+    expect(safeJsonStringify({ a: 1 }, null, 2)).toBe('{\n  "a": 1\n}');
+  });
+
+  it('returns undefined for undefined input, matching JSON.stringify', () => {
+    expect(safeJsonStringify(undefined)).toBeUndefined();
+  });
+});
+
+describe('stableJsonStringify', () => {
+  it('sorts keys deterministically regardless of input order', () => {
+    expect(stableJsonStringify({ b: 2, a: 1 })).toBe('{"a":1,"b":2}');
+    expect(stableJsonStringify({ a: 1, b: 2 })).toBe(stableJsonStringify({ b: 2, a: 1 }));
+  });
+});
+
+describe('configureJsonStringify', () => {
+  it('builds a custom stringifier (maximumDepth)', () => {
+    const shallow = configureJsonStringify({ maximumDepth: 1, deterministic: false });
+    const out = shallow({ a: { b: { c: 1 } } });
+    // Beyond the depth limit the value is replaced rather than throwing.
+    expect(typeof out).toBe('string');
+    expect(out).not.toContain('"c"');
+  });
+});
+
+describe('safeJsonParse', () => {
+  it('parses valid JSON into the expected shape', () => {
+    expect(safeJsonParse<{ a: number }>('{"a":1}')).toEqual({ a: 1 });
+  });
+
+  it('coerces JSON primitives', () => {
+    expect(safeJsonParse('123')).toBe(123);
+    expect(safeJsonParse('true')).toBe(true);
+  });
+
+  it('never throws on non-JSON input (returns the input unchanged)', () => {
+    expect(safeJsonParse('not json at all')).toBe('not json at all');
+  });
+
+  it('guards against prototype pollution', () => {
+    const parsed = safeJsonParse<Record<string, unknown>>('{"__proto__":{"polluted":true}}');
+    expect(({} as Record<string, unknown>).polluted).toBeUndefined();
+    expect(Object.getPrototypeOf(parsed)).toBe(Object.prototype);
+  });
+
+  it('throws on invalid input when { strict: true } (preserves JSON.parse behavior)', () => {
+    expect(() => safeJsonParse('not json at all', { strict: true })).toThrow();
+    expect(safeJsonParse<{ a: number }>('{"a":1}', { strict: true })).toEqual({ a: 1 });
+  });
+});
diff --git a/packages/utils/src/json.ts b/packages/utils/src/json.ts
new file mode 100644
index 0000000000..a17640b07b
--- /dev/null
+++ b/packages/utils/src/json.ts
@@ -0,0 +1,55 @@
+/**
+ * JSON utilities — safe stringify/parse. NEVER use raw `JSON.stringify` or
+ * `JSON.parse` outside this package; route everything through here (enforced
+ * by the `no-raw-json` ast-grep rule).
+ *
+ * Names are `*Json*` (not bare `safeParse`/`safeStringify`) to avoid confusion
+ * with zod's `.safeParse`. Sources: `safe-stable-stringify` + `destr`.
+ */
+import { destr } from 'destr';
+import { configure } from 'safe-stable-stringify';
+
+/**
+ * Safe drop-in for `JSON.stringify`: circular- and BigInt-safe, and
+ * **preserves key insertion order** (`deterministic: false`) so output matches
+ * raw `JSON.stringify` for normal data — it only differs by not throwing on
+ * circular references or BigInt. Use this everywhere you'd reach for
+ * `JSON.stringify`.
+ *
+ * Typed as `typeof JSON.stringify` (returns `string`) so it's a true drop-in —
+ * safe-stable-stringify's own type is `string | undefined`, which would break
+ * every `string`-typed call site (storage setters, headers, log lines). This
+ * mirrors the convenient `string` return TS already assigns to `JSON.stringify`.
+ */
+export const safeJsonStringify = configure({
+  deterministic: false,
+  bigint: true,
+}) as typeof JSON.stringify;
+
+/**
+ * Deterministic stringify: keys are sorted, circular- and BigInt-safe. Use for
+ * cache keys, hashing, and structural equality — NOT where output key order
+ * must mirror input order.
+ */
+export const stableJsonStringify = configure({
+  deterministic: true,
+  bigint: true,
+}) as typeof JSON.stringify;
+
+/**
+ * Escape hatch to build a custom stringifier (`maximumDepth`, `circularValue`,
+ * `maximumBreadth`, `strict`, …). See the safe-stable-stringify docs.
+ */
+export { configure as configureJsonStringify } from 'safe-stable-stringify';
+
+/**
+ * Safe drop-in for `JSON.parse`: guards against prototype pollution
+ * (`__proto__`) and, by default, never throws — returning the input unchanged
+ * for non-JSON. Pass a type parameter for the expected shape.
+ *
+ * For call sites that relied on `JSON.parse` THROWING on invalid input (e.g. a
+ * surrounding try/catch drives control flow), pass `{ strict: true }` to
+ * preserve that behavior exactly.
+ */
+export const safeJsonParse = <T = unknown>(value: string, options?: { strict?: boolean }): T =>
+  destr<T>(value, options);
diff --git a/packages/utils/src/math.ts b/packages/utils/src/math.ts
new file mode 100644
index 0000000000..6fa742d0fc
--- /dev/null
+++ b/packages/utils/src/math.ts
@@ -0,0 +1,10 @@
+/**
+ * Numeric / math utilities — curated re-exports. See ./provenance for source mapping.
+ */
+
+// es-toolkit — *-by selectors + precision round (radashi's `round` has no
+// precision argument, so es-toolkit wins here on capability)
+export { maxBy, meanBy, minBy, round, sumBy } from 'es-toolkit';
+// radashi — sum, clamp, min/max, numeric coercion (toFloat/toInt are the
+// "old-school" coercions; radashi covers them, so lodash isn't needed here)
+export { clamp, max, min, sum, toFloat, toInt } from 'radashi';
diff --git a/packages/utils/src/object.ts b/packages/utils/src/object.ts
new file mode 100644
index 0000000000..20c735e605
--- /dev/null
+++ b/packages/utils/src/object.ts
@@ -0,0 +1,6 @@
+/**
+ * Object utilities — curated re-exports. See ./provenance for source mapping.
+ */
+
+// radashi — pick/omit/map/merge/clean
+export { assign, mapEntries, mapValues, omit, pick, shake } from 'radashi';
diff --git a/packages/utils/src/predicates.ts b/packages/utils/src/predicates.ts
new file mode 100644
index 0000000000..2a440be7e6
--- /dev/null
+++ b/packages/utils/src/predicates.ts
@@ -0,0 +1,24 @@
+/**
+ * Type predicates — the lib-sourced `is*` narrowing primitives. `@packrat/utils`
+ * is the technical source (it's the only package allowed to import the libs);
+ * `@packrat/guards` re-exports these as the semantic home for narrowing and
+ * layers its custom assertions/coercions/enum/zod helpers on top. Prefer
+ * importing narrowing from `@packrat/guards`.
+ */
+
+// radashi — all 13 predicates guards exposes
+export {
+  isArray,
+  isDate,
+  isEmpty,
+  isEqual,
+  isFloat,
+  isFunction,
+  isInt,
+  isNumber,
+  isObject,
+  isPrimitive,
+  isPromise,
+  isString,
+  isSymbol,
+} from 'radashi';
diff --git a/packages/utils/src/provenance.test.ts b/packages/utils/src/provenance.test.ts
new file mode 100644
index 0000000000..0aca33c5a8
--- /dev/null
+++ b/packages/utils/src/provenance.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import * as barrel from './index';
+import { LIB_PRIORITY, provenance, type RankedLib } from './provenance';
+
+const exportedNames = Object.keys(barrel).sort();
+const manifestNames = Object.keys(provenance).sort();
+
+const rankOf = (lib: string): number => LIB_PRIORITY.indexOf(lib as RankedLib);
+const isRanked = (lib: string): boolean => rankOf(lib) !== -1;
+
+describe('provenance manifest', () => {
+  it('has an entry for every barrel export', () => {
+    const missing = exportedNames.filter((name) => !manifestNames.includes(name));
+    expect(missing).toEqual([]);
+  });
+
+  it('has no stale entries (every entry maps to a real export)', () => {
+    const stale = manifestNames.filter((name) => !exportedNames.includes(name));
+    expect(stale).toEqual([]);
+  });
+
+  it('sources every export from a known lib', () => {
+    const known = new Set<string>([...LIB_PRIORITY, 'destr', 'safe-stable-stringify']);
+    const unknown = Object.entries(provenance)
+      .filter(([, entry]) => !known.has(entry.source))
+      .map(([name]) => name);
+    expect(unknown).toEqual([]);
+  });
+
+  it('requires a reason when a lower-priority lib is chosen over a higher-priority one', () => {
+    const unjustified = Object.entries(provenance)
+      .filter(([, entry]) => {
+        if (!isRanked(entry.source) || !entry.alsoIn) return false;
+        const outranked = entry.alsoIn.some(
+          (alt) => isRanked(alt) && rankOf(alt) < rankOf(entry.source),
+        );
+        return outranked && !entry.reason?.trim();
+      })
+      .map(([name]) => name);
+    expect(unjustified).toEqual([]);
+  });
+
+  it('documents round as a justified lower-priority (es-toolkit over radashi) pick', () => {
+    const round = provenance.round;
+    expect(round?.source).toBe('es-toolkit');
+    expect(round?.alsoIn).toContain('radashi');
+    expect(round?.reason?.length ?? 0).toBeGreaterThan(0);
+  });
+});
diff --git a/packages/utils/src/provenance.ts b/packages/utils/src/provenance.ts
new file mode 100644
index 0000000000..01a239e893
--- /dev/null
+++ b/packages/utils/src/provenance.ts
@@ -0,0 +1,106 @@
+/**
+ * Provenance manifest — the source-of-truth for where each `@packrat/utils`
+ * export comes from. Enforced by `check-utils-provenance` (packages/checks):
+ *
+ *  - every barrel export MUST have an entry here (and vice-versa — no stale rows);
+ *  - `source` MUST be a known lib;
+ *  - if any lib in `alsoIn` outranks `source` in LIB_PRIORITY, a non-empty
+ *    `reason` MUST justify the lower-priority choice (the "best types +
+ *    has-the-function" tiebreaker, made explicit).
+ *
+ * Priority is a soft default, not a rigid rule — `reason` is how a deliberate
+ * lower-priority pick is recorded and kept honest. See docs/utils-policy.md.
+ */
+
+/** The five general-utility libs, highest priority first. */
+export const LIB_PRIORITY = ['radashi', 'radash', 'es-toolkit', 'lodash', 'remeda'] as const;
+
+export type RankedLib = (typeof LIB_PRIORITY)[number];
+
+/** Sources that sit outside the priority ladder (special-purpose libs). */
+export type UnrankedLib = 'destr' | 'safe-stable-stringify';
+
+export type SourceLib = RankedLib | UnrankedLib;
+
+export interface ProvenanceEntry {
+  /** The lib this export is sourced from. */
+  source: SourceLib;
+  /** Higher-or-equal-priority ranked libs that ALSO expose this name. */
+  alsoIn?: RankedLib[];
+  /** Required when `source` is outranked by something in `alsoIn`. */
+  reason?: string;
+}
+
+export const provenance: Record<string, ProvenanceEntry> = {
+  // --- array ---
+  unique: { source: 'radashi' },
+  group: { source: 'radashi' },
+  sort: { source: 'radashi' },
+  list: { source: 'radashi' },
+  chunk: { source: 'es-toolkit' }, // radashi's equivalent is named `cluster`
+
+  // --- async ---
+  all: { source: 'radashi' },
+  guard: { source: 'radashi' },
+  parallel: { source: 'radashi' },
+  retry: { source: 'radashi' },
+  sleep: { source: 'radashi' },
+  tryit: { source: 'radashi' },
+
+  // --- fn ---
+  debounce: { source: 'radashi' },
+  memo: { source: 'radashi' },
+  once: { source: 'radashi' },
+  throttle: { source: 'radashi' },
+  pipe: { source: 'remeda' }, // typed dataLast composition primitive
+
+  // --- json ---
+  safeJsonStringify: { source: 'safe-stable-stringify' },
+  stableJsonStringify: { source: 'safe-stable-stringify' },
+  configureJsonStringify: { source: 'safe-stable-stringify' },
+  safeJsonParse: { source: 'destr' },
+
+  // --- math ---
+  clamp: { source: 'radashi' },
+  max: { source: 'radashi' },
+  min: { source: 'radashi' },
+  sum: { source: 'radashi' },
+  toFloat: { source: 'radashi' },
+  toInt: { source: 'radashi' },
+  maxBy: { source: 'es-toolkit' },
+  meanBy: { source: 'es-toolkit' },
+  minBy: { source: 'es-toolkit' },
+  sumBy: { source: 'es-toolkit' },
+  round: {
+    source: 'es-toolkit',
+    alsoIn: ['radashi'],
+    reason: 'es-toolkit `round` supports a precision argument; radashi `round` does not',
+  },
+
+  // --- object ---
+  assign: { source: 'radashi' },
+  mapEntries: { source: 'radashi' },
+  mapValues: { source: 'radashi' },
+  omit: { source: 'radashi' },
+  pick: { source: 'radashi' },
+  shake: { source: 'radashi' },
+
+  // --- string ---
+  capitalize: { source: 'radashi' },
+  title: { source: 'radashi' },
+
+  // --- predicates (technical source for @packrat/guards) ---
+  isArray: { source: 'radashi' },
+  isDate: { source: 'radashi' },
+  isEmpty: { source: 'radashi' },
+  isEqual: { source: 'radashi' },
+  isFloat: { source: 'radashi' },
+  isFunction: { source: 'radashi' },
+  isInt: { source: 'radashi' },
+  isNumber: { source: 'radashi' },
+  isObject: { source: 'radashi' },
+  isPrimitive: { source: 'radashi' },
+  isPromise: { source: 'radashi' },
+  isString: { source: 'radashi' },
+  isSymbol: { source: 'radashi' },
+};
diff --git a/packages/utils/src/string.ts b/packages/utils/src/string.ts
new file mode 100644
index 0000000000..b3048cbbdb
--- /dev/null
+++ b/packages/utils/src/string.ts
@@ -0,0 +1,6 @@
+/**
+ * String utilities — curated re-exports. See ./provenance for source mapping.
+ */
+
+// radashi — capitalize (first letter) + title (Title Case)
+export { capitalize, title } from 'radashi';
diff --git a/packages/utils/src/surface.test.ts b/packages/utils/src/surface.test.ts
new file mode 100644
index 0000000000..e0688f7754
--- /dev/null
+++ b/packages/utils/src/surface.test.ts
@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+import * as array from './array';
+import * as asyncUtils from './async';
+import * as fn from './fn';
+import * as math from './math';
+import * as object from './object';
+import * as predicates from './predicates';
+import * as string from './string';
+
+// Re-export files carry no logic of their own — these tests confirm the
+// curated surface is wired and the right implementation answers to each name.
+// (Upstream lib behavior is the libs' own concern; we assert representative
+// behavior so a mis-wired or renamed export is caught.)
+
+describe('array surface', () => {
+  it('unique dedupes', () => expect(array.unique([1, 1, 2, 3, 3])).toEqual([1, 2, 3]));
+  it('group buckets by key fn', () => {
+    expect(array.group([1, 2, 3, 4], (n) => (n % 2 === 0 ? 'even' : 'odd'))).toEqual({
+      odd: [1, 3],
+      even: [2, 4],
+    });
+  });
+  it('chunk splits into fixed sizes', () =>
+    expect(array.chunk([1, 2, 3, 4, 5], 2)).toEqual([[1, 2], [3, 4], [5]]));
+});
+
+describe('object surface', () => {
+  it('pick selects keys', () => expect(object.pick({ a: 1, b: 2 }, ['a'])).toEqual({ a: 1 }));
+  it('omit drops keys', () => expect(object.omit({ a: 1, b: 2 }, ['a'])).toEqual({ b: 2 }));
+  it('mapValues transforms values', () =>
+    expect(object.mapValues({ a: 1, b: 2 }, (v) => v * 10)).toEqual({ a: 10, b: 20 }));
+});
+
+describe('string surface', () => {
+  it('capitalize upper-cases the first letter', () =>
+    expect(string.capitalize('trail')).toBe('Trail'));
+  it('title produces Title Case', () =>
+    expect(string.title('pack rat utils')).toBe('Pack Rat Utils'));
+});
+
+describe('math surface', () => {
+  it('sum adds a list', () => expect(math.sum([1, 2, 3])).toBe(6));
+  it('sumBy adds a selected field', () =>
+    expect(math.sumBy([{ w: 2 }, { w: 3 }], (o) => o.w)).toBe(5));
+  it('clamp bounds a value', () => expect(math.clamp(50, 1, 20)).toBe(20));
+  it('round respects precision', () => expect(math.round(1.2345, 2)).toBe(1.23));
+  it('maxBy selects by field', () =>
+    expect(math.maxBy([{ h: 1 }, { h: 9 }, { h: 4 }], (o) => o.h)).toEqual({ h: 9 }));
+});
+
+describe('fn surface', () => {
+  it('once invokes the underlying fn a single time', () => {
+    let calls = 0;
+    const init = fn.once(() => {
+      calls += 1;
+      return calls;
+    });
+    expect(init()).toBe(1);
+    expect(init()).toBe(1);
+    expect(calls).toBe(1);
+  });
+  it('pipe threads a value through transforms (dataLast composition)', () => {
+    expect(
+      fn.pipe(
+        2,
+        (n: number) => n + 1,
+        (n: number) => n * 3,
+      ),
+    ).toBe(9);
+  });
+});
+
+describe('predicates surface (technical source for @packrat/guards)', () => {
+  it('isString narrows strings', () => {
+    expect(predicates.isString('x')).toBe(true);
+    expect(predicates.isString(1)).toBe(false);
+  });
+  it('isArray narrows arrays', () => {
+    expect(predicates.isArray([1])).toBe(true);
+    expect(predicates.isArray('no')).toBe(false);
+  });
+  it('isEmpty detects empties', () => {
+    expect(predicates.isEmpty([])).toBe(true);
+    expect(predicates.isEmpty([1])).toBe(false);
+  });
+});
+
+describe('async surface', () => {
+  it('sleep resolves after the delay', async () => {
+    const start = performance.now();
+    await asyncUtils.sleep(5);
+    expect(performance.now() - start).toBeGreaterThanOrEqual(4);
+  });
+  it('tryit returns an error-tuple instead of throwing', async () => {
+    const [ok, okVal] = await asyncUtils.tryit(async () => 42)();
+    expect(ok).toBeUndefined();
+    expect(okVal).toBe(42);
+    const [err] = await asyncUtils.tryit(async () => {
+      throw new Error('boom');
+    })();
+    expect(err).toBeInstanceOf(Error);
+  });
+});
diff --git a/packages/utils/vitest.config.ts b/packages/utils/vitest.config.ts
new file mode 100644
index 0000000000..d7a8c4ccca
--- /dev/null
+++ b/packages/utils/vitest.config.ts
@@ -0,0 +1,23 @@
+import { resolve } from 'node:path';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    name: 'utils',
+    environment: 'node',
+    include: [resolve(__dirname, 'src/**/*.test.ts')],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json-summary'],
+      reportsDirectory: resolve(__dirname, 'coverage'),
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/*.test.ts'],
+      thresholds: {
+        statements: 100,
+        branches: 100,
+        functions: 100,
+        lines: 100,
+      },
+    },
+  },
+});
diff --git a/packages/web-ui/package.json b/packages/web-ui/package.json
index 9d89487890..a8acb4218f 100644
--- a/packages/web-ui/package.json
+++ b/packages/web-ui/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@packrat/web-ui",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "private": true,
   "type": "module",
   "exports": {
diff --git a/packages/web-ui/src/components/chart.tsx b/packages/web-ui/src/components/chart.tsx
index b78a6fc1eb..6329ccebe4 100644
--- a/packages/web-ui/src/components/chart.tsx
+++ b/packages/web-ui/src/components/chart.tsx
@@ -364,12 +364,12 @@ function getPayloadConfigFromPayload({
 
   if (key in config) {
     configLabelKey = key;
-  } else if (key in payload && typeof payload[key as keyof typeof payload] === 'string') {
+  } else if (key in payload && isString(payload[key as keyof typeof payload])) {
     configLabelKey = payload[key as keyof typeof payload] as string;
   } else if (
     payloadPayload &&
     key in payloadPayload &&
-    typeof payloadPayload[key as keyof typeof payloadPayload] === 'string'
+    isString(payloadPayload[key as keyof typeof payloadPayload])
   ) {
     configLabelKey = payloadPayload[key as keyof typeof payloadPayload] as string;
   }
diff --git a/scripts/check-all.ts b/scripts/check-all.ts
index 154784955a..82ee577ad7 100644
--- a/scripts/check-all.ts
+++ b/scripts/check-all.ts
@@ -3,9 +3,8 @@
 // check-all.ts — master orchestrator for all custom PackRat check scripts.
 //
 // Runs the following checks in parallel and prints a unified summary table:
-//   - scripts/lint/no-raw-regex.ts
+//   - scripts/lint/no-raw-ast-grep.ts  (ast-grep: no-raw-typeof + no-raw-regex)
 //   - scripts/lint/no-owned-max-params.ts
-//   - scripts/lint/no-raw-typeof.ts
 //   - packages/env/scripts/no-raw-process-env.ts
 //   - scripts/lint/no-circular-deps.ts
 //   - scripts/lint/no-duplicate-deps.ts  (skipped if file doesn't exist)
@@ -56,17 +55,13 @@ interface CheckDef {
 
 const ALL_CHECKS: CheckDef[] = [
   {
-    name: 'no-raw-regex',
-    script: join(ROOT, 'scripts', 'lint', 'no-raw-regex.ts'),
+    name: 'ast-grep',
+    script: join(ROOT, 'scripts', 'lint', 'no-raw-ast-grep.ts'),
   },
   {
     name: 'no-owned-max-params',
     script: join(ROOT, 'scripts', 'lint', 'no-owned-max-params.ts'),
   },
-  {
-    name: 'no-raw-typeof',
-    script: join(ROOT, 'scripts', 'lint', 'no-raw-typeof.ts'),
-  },
   {
     name: 'no-raw-process-env',
     script: join(ROOT, 'packages', 'env', 'scripts', 'no-raw-process-env.ts'),
@@ -83,6 +78,19 @@ const ALL_CHECKS: CheckDef[] = [
     name: 'no-duplicate-guards',
     script: join(ROOT, 'scripts', 'lint', 'no-duplicate-guards.ts'),
   },
+  {
+    name: 'no-duplicate-utils',
+    script: join(ROOT, 'scripts', 'lint', 'no-duplicate-utils.ts'),
+  },
+  {
+    name: 'check-utils-provenance',
+    script: join(ROOT, 'packages', 'checks', 'src', 'check-utils-provenance.ts'),
+    args: ['--strict'],
+  },
+  {
+    name: 'duplication',
+    script: join(ROOT, 'scripts', 'lint', 'check-duplication.ts'),
+  },
   {
     name: 'no-unauth-routes',
     script: join(ROOT, 'scripts', 'lint', 'no-unauth-routes.ts'),
diff --git a/scripts/lint/__tests__/coverage-ratchet.test.ts b/scripts/lint/__tests__/coverage-ratchet.test.ts
new file mode 100644
index 0000000000..f07b0aa326
--- /dev/null
+++ b/scripts/lint/__tests__/coverage-ratchet.test.ts
@@ -0,0 +1,223 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type CoverageSummary,
+  compareWorkspace,
+  loadBaseline,
+  runRatchet,
+  type WorkspaceBaseline,
+} from '../coverage-ratchet';
+
+function makeBaseline(overrides: Partial<WorkspaceBaseline> = {}): WorkspaceBaseline {
+  return {
+    summaryPath: 'pkg/coverage/coverage-summary.json',
+    tier: 'A',
+    lines: 80,
+    branches: 70,
+    functions: 90,
+    statements: 80,
+    recordedAt: '2026-05-17',
+    ...overrides,
+  };
+}
+
+function makeSummary(pct: number): CoverageSummary {
+  return {
+    total: {
+      lines: { pct },
+      branches: { pct },
+      functions: { pct },
+      statements: { pct },
+    },
+  };
+}
+
+function makeMixedSummary(
+  lines: number,
+  branches: number,
+  functions: number,
+  statements: number,
+): CoverageSummary {
+  return {
+    total: {
+      lines: { pct: lines },
+      branches: { pct: branches },
+      functions: { pct: functions },
+      statements: { pct: statements },
+    },
+  };
+}
+
+describe('compareWorkspace', () => {
+  it('passes when every metric matches or exceeds the baseline', () => {
+    const result = compareWorkspace('pkg', makeBaseline(), makeMixedSummary(85, 75, 95, 85), 0.5);
+    expect(result.status).toBe('improvement');
+    expect(result.regressions).toBeUndefined();
+  });
+
+  it('passes (status=ok) when every metric is exactly the baseline', () => {
+    const result = compareWorkspace('pkg', makeBaseline(), makeMixedSummary(80, 70, 90, 80), 0.5);
+    expect(result.status).toBe('ok');
+  });
+
+  it('flags regression when one metric drops more than epsilon', () => {
+    const result = compareWorkspace(
+      'pkg',
+      makeBaseline({ branches: 70 }),
+      makeMixedSummary(80, 65, 90, 80),
+      0.5,
+    );
+    expect(result.status).toBe('regression');
+    expect(result.regressions).toEqual([{ metric: 'branches', before: 70, after: 65 }]);
+  });
+
+  it('tolerates noise below epsilon (default 0.5)', () => {
+    // baseline 80.0 vs current 79.7 — within epsilon, not a regression.
+    const result = compareWorkspace('pkg', makeBaseline(), makeMixedSummary(79.7, 70, 90, 80), 0.5);
+    expect(result.status).toBe('ok');
+  });
+
+  it('rejects drops just above epsilon', () => {
+    // baseline 80.0 vs current 79.4 — drop of 0.6 > epsilon 0.5.
+    const result = compareWorkspace('pkg', makeBaseline(), makeMixedSummary(79.4, 70, 90, 80), 0.5);
+    expect(result.status).toBe('regression');
+    expect(result.regressions?.[0]?.metric).toBe('lines');
+  });
+
+  it('reports multiple regressions in one workspace', () => {
+    const result = compareWorkspace('pkg', makeBaseline(), makeMixedSummary(60, 50, 70, 60), 0.5);
+    expect(result.status).toBe('regression');
+    expect(result.regressions).toHaveLength(4);
+  });
+});
+
+describe('runRatchet', () => {
+  it('passes when every workspace meets its baseline', () => {
+    const baseline = {
+      'packages/a': makeBaseline({
+        summaryPath: 'a/coverage-summary.json',
+        lines: 80,
+        branches: 70,
+        functions: 90,
+        statements: 80,
+      }),
+      'packages/b': makeBaseline({
+        summaryPath: 'b/coverage-summary.json',
+        lines: 60,
+        branches: 50,
+        functions: 70,
+        statements: 60,
+      }),
+    };
+    const summaries: Record<string, CoverageSummary> = {
+      'a/coverage-summary.json': makeMixedSummary(85, 75, 95, 85), // beats packages/a
+      'b/coverage-summary.json': makeMixedSummary(70, 60, 80, 70), // beats packages/b
+    };
+    const report = runRatchet(baseline, 0.5, (path) => summaries[path] ?? null);
+    expect(report.passed).toBe(true);
+  });
+
+  it('fails when any workspace regresses', () => {
+    const baseline = {
+      'packages/a': makeBaseline({
+        summaryPath: 'a/coverage-summary.json',
+        lines: 80,
+        branches: 70,
+        functions: 90,
+        statements: 80,
+      }),
+      'packages/b': makeBaseline({
+        summaryPath: 'b/coverage-summary.json',
+        lines: 60,
+        branches: 50,
+        functions: 70,
+        statements: 60,
+      }),
+    };
+    const summaries: Record<string, CoverageSummary> = {
+      'a/coverage-summary.json': makeSummary(85),
+      'b/coverage-summary.json': makeSummary(40),
+    };
+    const report = runRatchet(baseline, 0.5, (path) => summaries[path] ?? null);
+    expect(report.passed).toBe(false);
+    const failed = report.checks.find((c) => c.workspace === 'packages/b');
+    expect(failed?.status).toBe('regression');
+  });
+
+  it('fails when a workspace has no coverage summary on disk', () => {
+    const baseline = {
+      'packages/a': makeBaseline({
+        summaryPath: 'missing/coverage-summary.json',
+      }),
+    };
+    const report = runRatchet(baseline, 0.5, () => null);
+    expect(report.passed).toBe(false);
+    expect(report.checks[0]?.status).toBe('missing-summary');
+  });
+
+  it('fails when the summary file is missing required total metrics', () => {
+    const baseline = {
+      'packages/a': makeBaseline({ summaryPath: 'a/coverage-summary.json' }),
+    };
+    const malformed = { total: { lines: { pct: 80 } } } as unknown as CoverageSummary;
+    const report = runRatchet(baseline, 0.5, (path) =>
+      path === 'a/coverage-summary.json' ? malformed : null,
+    );
+    expect(report.passed).toBe(false);
+    expect(report.checks[0]?.status).toBe('invalid-summary');
+  });
+});
+
+describe('loadBaseline', () => {
+  it('parses workspace entries and ignores comment keys', () => {
+    const json = JSON.stringify({
+      _comment: 'ignored',
+      _epsilon: 0.3,
+      'packages/a': {
+        summaryPath: 'a/x.json',
+        tier: 'A',
+        lines: 80,
+        branches: 70,
+        functions: 90,
+        statements: 80,
+        recordedAt: '2026-05-17',
+      },
+    });
+    const { baseline, epsilon } = loadBaseline(json);
+    expect(epsilon).toBe(0.3);
+    expect(Object.keys(baseline)).toEqual(['packages/a']);
+    expect(baseline['packages/a']?.lines).toBe(80);
+  });
+
+  it('falls back to default epsilon when not specified', () => {
+    const json = JSON.stringify({
+      'packages/a': {
+        summaryPath: 'a/x.json',
+        tier: 'A',
+        lines: 80,
+        branches: 70,
+        functions: 90,
+        statements: 80,
+        recordedAt: '2026-05-17',
+      },
+    });
+    const { epsilon } = loadBaseline(json);
+    expect(epsilon).toBe(0.05);
+  });
+
+  it('skips entries that look malformed', () => {
+    const json = JSON.stringify({
+      'packages/a': { summaryPath: 'a/x.json' }, // missing metric fields
+      'packages/b': {
+        summaryPath: 'b/x.json',
+        tier: 'A',
+        lines: 80,
+        branches: 70,
+        functions: 90,
+        statements: 80,
+        recordedAt: '2026-05-17',
+      },
+    });
+    const { baseline } = loadBaseline(json);
+    expect(Object.keys(baseline)).toEqual(['packages/b']);
+  });
+});
diff --git a/scripts/lint/__tests__/no-duplicate-utils.test.ts b/scripts/lint/__tests__/no-duplicate-utils.test.ts
new file mode 100644
index 0000000000..f3c3f7ee0d
--- /dev/null
+++ b/scripts/lint/__tests__/no-duplicate-utils.test.ts
@@ -0,0 +1,142 @@
+import { provenance } from '@packrat/utils/provenance';
+import { describe, expect, it } from 'vitest';
+import { analyzeSource, isExcluded, UTIL_NAMES } from '../no-duplicate-utils';
+
+const outsideFile = 'apps/expo/features/foo/utils.ts';
+const insideFile = 'packages/utils/src/array.ts';
+
+describe('no-duplicate-utils', () => {
+  describe('flags re-implementations outside @packrat/utils', () => {
+    it('flags a function declaration of a manifest name', () => {
+      const src = [
+        'export function unique(items: number[]) {',
+        '  return [...new Set(items)];',
+        '}',
+      ].join('\n');
+      const violations = analyzeSource(outsideFile, src);
+      expect(violations).toHaveLength(1);
+      expect(violations[0]).toMatchObject({ name: 'unique', line: 1, file: outsideFile });
+    });
+
+    it('flags an arrow-function const assignment of a manifest name', () => {
+      const src =
+        'export const clamp = (n: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, n));';
+      const violations = analyzeSource(outsideFile, src);
+      expect(violations).toHaveLength(1);
+      expect(violations[0]?.name).toBe('clamp');
+    });
+
+    it('flags a typed arrow-function const (type annotation before =)', () => {
+      const src = 'const isString: (v: unknown) => boolean = (v) => typeof v === "string";';
+      const violations = analyzeSource(outsideFile, src);
+      expect(violations).toHaveLength(1);
+      expect(violations[0]?.name).toBe('isString');
+    });
+
+    it('flags a single-bare-param arrow const', () => {
+      const src = 'const capitalize = (s) => s.slice(0, 1).toUpperCase() + s.slice(1);';
+      const violations = analyzeSource(outsideFile, src);
+      expect(violations).toHaveLength(1);
+      expect(violations[0]?.name).toBe('capitalize');
+    });
+  });
+
+  describe('does NOT flag re-exports or imports', () => {
+    it('ignores a re-export line', () => {
+      const src = "export { unique, clamp } from '@packrat/utils';";
+      const violations = analyzeSource(outsideFile, src);
+      expect(violations).toHaveLength(0);
+    });
+
+    it('ignores a named import line', () => {
+      const src = "import { unique, sort, group } from '@packrat/utils';";
+      const violations = analyzeSource(outsideFile, src);
+      expect(violations).toHaveLength(0);
+    });
+
+    it('ignores a comment mentioning a manifest name', () => {
+      const src = '// const unique = () => {} would be a re-implementation';
+      const violations = analyzeSource(outsideFile, src);
+      expect(violations).toHaveLength(0);
+    });
+  });
+
+  describe('does NOT flag data-valued locals that share a generic name', () => {
+    it('ignores `const list = await bucket.list()`', () => {
+      const src = 'const list = await bucket.list();';
+      const violations = analyzeSource(outsideFile, src);
+      expect(violations).toHaveLength(0);
+    });
+
+    it('ignores `const title = "some string"`', () => {
+      const src = "const title = 'Open up the code for this screen:';";
+      const violations = analyzeSource(outsideFile, src);
+      expect(violations).toHaveLength(0);
+    });
+
+    it('ignores `const group = markersRef.current`', () => {
+      const src = 'const group = markersRef.current;';
+      const violations = analyzeSource(outsideFile, src);
+      expect(violations).toHaveLength(0);
+    });
+
+    it('ignores `const all = Object.values(store.get())`', () => {
+      const src = 'const all = Object.values(packTemplatesStore.get());';
+      const violations = analyzeSource(outsideFile, src);
+      expect(violations).toHaveLength(0);
+    });
+  });
+
+  describe('banned set is derived from the provenance manifest', () => {
+    it('UTIL_NAMES equals the manifest keys exactly (auto-syncs as the facade grows)', () => {
+      const manifestKeys = Object.keys(provenance);
+      expect([...UTIL_NAMES].sort()).toEqual([...manifestKeys].sort());
+    });
+
+    it('flags every current manifest name when re-implemented as a function', () => {
+      for (const name of Object.keys(provenance)) {
+        const src = `export const ${name} = (x) => x;`;
+        const violations = analyzeSource(outsideFile, src);
+        expect(violations.map((v) => v.name)).toContain(name);
+      }
+    });
+
+    it('a name absent from the manifest is NOT flagged', () => {
+      expect(UTIL_NAMES.has('definitelyNotAManifestName')).toBe(false);
+      const src = 'export const definitelyNotAManifestName = (x) => x;';
+      const violations = analyzeSource(outsideFile, src);
+      expect(violations).toHaveLength(0);
+    });
+  });
+
+  describe('canonical-source roots are excluded from the walk', () => {
+    it('excludes packages/utils (the source of truth)', () => {
+      expect(isExcluded('packages/utils')).toBe(true);
+      expect(isExcluded(insideFile)).toBe(true);
+    });
+
+    it('excludes packages/checks (the analyzer package)', () => {
+      expect(isExcluded('packages/checks')).toBe(true);
+      expect(isExcluded('packages/checks/src/check-utils-provenance.ts')).toBe(true);
+    });
+
+    it('does NOT exclude app code or other packages', () => {
+      expect(isExcluded(outsideFile)).toBe(false);
+      expect(isExcluded('packages/api/src/routes/guides/index.ts')).toBe(false);
+    });
+
+    it('does NOT exclude a sibling path that merely shares a prefix', () => {
+      // `packages/utils-extra` must not be treated as inside `packages/utils`.
+      expect(isExcluded('packages/utils-extra/src/index.ts')).toBe(false);
+    });
+  });
+
+  describe('analyzeSource reports the file path it was given', () => {
+    it('uses the caller-supplied file path (exclusion is the walker’s job, not the analyzer’s)', () => {
+      const src = 'export function unique(xs) { return xs; }';
+      const violations = analyzeSource(insideFile, src);
+      expect(violations).toHaveLength(1);
+      expect(violations[0]?.file).toBe(insideFile);
+    });
+  });
+});
diff --git a/scripts/lint/__tests__/no-weak-assertions.test.ts b/scripts/lint/__tests__/no-weak-assertions.test.ts
new file mode 100644
index 0000000000..eff2f2af69
--- /dev/null
+++ b/scripts/lint/__tests__/no-weak-assertions.test.ts
@@ -0,0 +1,225 @@
+import { describe, expect, it } from 'vitest';
+import { analyzeSource, isFileDisabled } from '../no-weak-assertions';
+
+const fakeFile = 'apps/test/example.test.ts';
+
+describe('no-weak-assertions', () => {
+  describe('assertion-free-test', () => {
+    it('flags an it() block with zero expect() or expect-helper calls', () => {
+      const src = `
+        describe('thing', () => {
+          it('does something', () => {
+            const x = 1 + 1;
+            console.log(x);
+          });
+        });
+      `;
+      const violations = analyzeSource(fakeFile, src);
+      expect(violations).toHaveLength(1);
+      expect(violations[0]?.rule).toBe('assertion-free-test');
+      expect(violations[0]?.line).toBe(3);
+    });
+
+    it('does NOT flag when a custom expect-helper is used', () => {
+      const src = `
+        it('rejects unauth', async () => {
+          const res = await api('/x');
+          expectUnauthorized(res);
+        });
+      `;
+      const violations = analyzeSource(fakeFile, src);
+      expect(violations.filter((v) => v.rule === 'assertion-free-test')).toHaveLength(0);
+    });
+
+    it('does NOT flag it.todo or it.skip blocks', () => {
+      const src = `
+        it.todo('eventually');
+        it.skip('not yet', () => {
+          const x = 1;
+        });
+      `;
+      const violations = analyzeSource(fakeFile, src);
+      expect(violations).toHaveLength(0);
+    });
+  });
+
+  describe('only-tobedefined', () => {
+    it('flags a block where every expect() uses .toBeDefined()', () => {
+      const src = `
+        it('returns something', () => {
+          const x = parse('foo');
+          expect(x).toBeDefined();
+        });
+      `;
+      const violations = analyzeSource(fakeFile, src);
+      expect(violations).toHaveLength(1);
+      expect(violations[0]?.rule).toBe('only-tobedefined');
+    });
+
+    it('flags .toBeTruthy() and .toBeFalsy() blocks', () => {
+      const src = `
+        it('truthy', () => {
+          expect(x).toBeTruthy();
+        });
+        it('falsy', () => {
+          expect(y).toBeFalsy();
+        });
+      `;
+      const violations = analyzeSource(fakeFile, src);
+      expect(violations.filter((v) => v.rule === 'only-tobedefined')).toHaveLength(2);
+    });
+
+    it('does NOT flag .toBeUndefined() — that asserts a specific return value', () => {
+      const src = `
+        it('returns undefined when input is missing', () => {
+          expect(getNotes(item)).toBeUndefined();
+        });
+        it('returns null when not found', () => {
+          expect(lookup(id)).toBeNull();
+        });
+      `;
+      const violations = analyzeSource(fakeFile, src);
+      expect(violations).toHaveLength(0);
+    });
+
+    it('does NOT flag when at least one expect() uses a specific matcher', () => {
+      const src = `
+        it('returns a valid result', () => {
+          const x = parse('foo');
+          expect(x).toBeDefined();
+          expect(x.value).toBe(42);
+        });
+      `;
+      const violations = analyzeSource(fakeFile, src);
+      expect(violations).toHaveLength(0);
+    });
+
+    it('does NOT flag when an expect-helper is present', () => {
+      const src = `
+        it('returns a valid result', () => {
+          const x = parse('foo');
+          expect(x).toBeDefined();
+          expectShape(x);
+        });
+      `;
+      const violations = analyzeSource(fakeFile, src);
+      expect(violations).toHaveLength(0);
+    });
+  });
+
+  describe('bare-tohavebeencalled', () => {
+    it('flags .toHaveBeenCalled() without .toHaveBeenCalledWith or Times', () => {
+      const src = `
+        it('calls the thing', () => {
+          doIt();
+          expect(spy).toHaveBeenCalled();
+        });
+      `;
+      const violations = analyzeSource(fakeFile, src);
+      expect(violations.filter((v) => v.rule === 'bare-tohavebeencalled')).toHaveLength(1);
+    });
+
+    it('does NOT flag when .toHaveBeenCalledWith is present in the same block', () => {
+      const src = `
+        it('calls the thing with the right arg', () => {
+          doIt('foo');
+          expect(spy).toHaveBeenCalled();
+          expect(spy).toHaveBeenCalledWith('foo');
+        });
+      `;
+      const violations = analyzeSource(fakeFile, src);
+      expect(violations.filter((v) => v.rule === 'bare-tohavebeencalled')).toHaveLength(0);
+    });
+
+    it('does NOT flag when .toHaveBeenCalledTimes is present', () => {
+      const src = `
+        it('calls the thing twice', () => {
+          doIt(); doIt();
+          expect(spy).toHaveBeenCalled();
+          expect(spy).toHaveBeenCalledTimes(2);
+        });
+      `;
+      const violations = analyzeSource(fakeFile, src);
+      expect(violations.filter((v) => v.rule === 'bare-tohavebeencalled')).toHaveLength(0);
+    });
+  });
+
+  describe('large-snapshot', () => {
+    it('flags toMatchInlineSnapshot bodies > 50 lines', () => {
+      const snapshotBody = `\n${'  line\n'.repeat(60)}`;
+      const src = `
+        it('matches snapshot', () => {
+          expect(big).toMatchInlineSnapshot(\`${snapshotBody}\`);
+        });
+      `;
+      const violations = analyzeSource(fakeFile, src);
+      expect(violations.some((v) => v.rule === 'large-snapshot')).toBe(true);
+    });
+
+    it('does NOT flag small inline snapshots', () => {
+      const src = `
+        it('matches snapshot', () => {
+          expect(small).toMatchInlineSnapshot(\`"hello"\`);
+        });
+      `;
+      const violations = analyzeSource(fakeFile, src);
+      expect(violations.filter((v) => v.rule === 'large-snapshot')).toHaveLength(0);
+    });
+  });
+
+  describe('file-level disable comment', () => {
+    it('skips the entire file when "no-weak-assertions: disable" is in the first 5 lines', () => {
+      const src = `// no-weak-assertions: disable
+        it('grandfathered', () => {
+          expect(x).toBeDefined();
+        });
+        it('also grandfathered', () => {
+          // assertion-free
+        });
+      `;
+      expect(isFileDisabled(src)).toBe(true);
+      const violations = analyzeSource(fakeFile, src);
+      expect(violations).toHaveLength(0);
+    });
+
+    it('does NOT skip when the disable comment is after line 5', () => {
+      const src = `
+        // line 1
+        // line 2
+        // line 3
+        // line 4
+        // line 5
+        // no-weak-assertions: disable
+        it('not grandfathered', () => {
+          const x = 1;
+        });
+      `;
+      expect(isFileDisabled(src)).toBe(false);
+      const violations = analyzeSource(fakeFile, src);
+      expect(violations.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('multiple violations in one file', () => {
+    it('reports each violation separately', () => {
+      const src = `
+        it('first violation', () => {
+          const x = 1;
+        });
+        it('second violation', () => {
+          expect(y).toBeDefined();
+        });
+        it('third violation', () => {
+          expect(spy).toHaveBeenCalled();
+        });
+      `;
+      const violations = analyzeSource(fakeFile, src);
+      expect(violations).toHaveLength(3);
+      expect(violations.map((v) => v.rule).sort()).toEqual([
+        'assertion-free-test',
+        'bare-tohavebeencalled',
+        'only-tobedefined',
+      ]);
+    });
+  });
+});
diff --git a/scripts/lint/check-duplication.ts b/scripts/lint/check-duplication.ts
new file mode 100644
index 0000000000..af4e756044
--- /dev/null
+++ b/scripts/lint/check-duplication.ts
@@ -0,0 +1,23 @@
+#!/usr/bin/env bun
+//
+// check-duplication.ts — runs jscpd (copy-paste detector) over apps/ + packages/
+// and propagates its exit code. Config lives in .jscpd.json (threshold, ignores,
+// formats). Fails when duplication exceeds the threshold.
+//
+// Baseline at introduction: ~5.2% duplicated lines (ts + tsx). The gate is set
+// to 7% to block NEW duplication while leaving headroom; ratchet the threshold
+// down in follow-ups as clones are collapsed into @packrat/utils.
+//
+// Exit code mirrors jscpd: 0 — under threshold; 1 — over threshold.
+
+import { join } from 'node:path';
+
+const ROOT = join(import.meta.dir, '..', '..');
+
+const proc = Bun.spawn(['bunx', 'jscpd', 'apps', 'packages'], {
+  cwd: ROOT,
+  stdout: 'inherit',
+  stderr: 'inherit',
+});
+
+process.exit(await proc.exited);
diff --git a/scripts/lint/coverage-baseline-update.ts b/scripts/lint/coverage-baseline-update.ts
new file mode 100644
index 0000000000..56c52744e1
--- /dev/null
+++ b/scripts/lint/coverage-baseline-update.ts
@@ -0,0 +1,99 @@
+#!/usr/bin/env bun
+//
+// coverage-baseline-update.ts — bumps coverage-baselines.json upward.
+//
+// For every workspace in `coverage-baselines.json`, read its current
+// `coverage-summary.json` and update the baseline metric if (and only if)
+// the current value is higher. Never lowers a baseline — that's what the
+// ratchet is for.
+//
+// Designed to run on `main` post-merge from CI via:
+//   `bun scripts/lint/coverage-baseline-update.ts`
+// followed by an auto-commit of `coverage-baselines.json`. Do not invoke
+// this from PR workflows — it would silently move the floor up before the
+// PR's coverage drops below it.
+//
+// Exit code:
+//   0 — file updated (or no changes needed)
+//   1 — fatal error (missing baseline file, malformed summaries)
+//
+// Honours the same `_epsilon` value the ratchet uses — improvements smaller
+// than epsilon are ignored so we don't churn the baseline on v8 jitter.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  type BaselineFile,
+  type CoverageSummary,
+  loadBaseline,
+  METRICS,
+  type Metric,
+  type WorkspaceBaseline,
+} from './coverage-ratchet';
+
+interface Bump {
+  workspace: string;
+  metric: Metric;
+  before: number;
+  after: number;
+}
+
+if (import.meta.main) {
+  const HERE = dirname(fileURLToPath(import.meta.url));
+  const ROOT = join(HERE, '..', '..');
+  const BASELINE_PATH = join(ROOT, 'coverage-baselines.json');
+
+  if (!existsSync(BASELINE_PATH)) {
+    console.error(`coverage-baselines.json not found at ${BASELINE_PATH}`);
+    process.exit(1);
+  }
+  const raw = readFileSync(BASELINE_PATH, 'utf-8');
+  const parsed = JSON.parse(raw) as BaselineFile;
+  const { baseline, epsilon } = loadBaseline(raw);
+
+  const today = new Date().toISOString().slice(0, 10);
+  const bumps: Bump[] = [];
+
+  for (const [workspace, entry] of Object.entries(baseline)) {
+    const abs = join(ROOT, entry.summaryPath);
+    if (!existsSync(abs)) {
+      console.warn(`Skipping ${workspace} — no summary at ${entry.summaryPath}`);
+      continue;
+    }
+    let summary: CoverageSummary;
+    try {
+      summary = JSON.parse(readFileSync(abs, 'utf-8')) as CoverageSummary;
+    } catch (err) {
+      console.warn(`Skipping ${workspace} — malformed summary: ${(err as Error).message}`);
+      continue;
+    }
+    const next: WorkspaceBaseline = { ...entry };
+    let changed = false;
+    for (const metric of METRICS) {
+      const before = entry[metric];
+      const after = summary.total[metric].pct;
+      if (after - before > epsilon) {
+        next[metric] = after;
+        changed = true;
+        bumps.push({ workspace, metric, before, after });
+      }
+    }
+    if (changed) {
+      next.recordedAt = today;
+      parsed[workspace] = next;
+    }
+  }
+
+  if (bumps.length === 0) {
+    console.log('Coverage baselines: no improvements above epsilon. File unchanged.');
+    process.exit(0);
+  }
+
+  writeFileSync(BASELINE_PATH, `${JSON.stringify(parsed, null, 2)}\n`, 'utf-8');
+  console.log(`Coverage baselines: bumped ${bumps.length} metric(s).`);
+  for (const b of bumps) {
+    console.log(`  ${b.workspace} ${b.metric}: ${b.before.toFixed(2)}% → ${b.after.toFixed(2)}%`);
+  }
+  process.exit(0);
+}
diff --git a/scripts/lint/coverage-ratchet.ts b/scripts/lint/coverage-ratchet.ts
new file mode 100644
index 0000000000..12ea09f8ff
--- /dev/null
+++ b/scripts/lint/coverage-ratchet.ts
@@ -0,0 +1,232 @@
+#!/usr/bin/env bun
+//
+// coverage-ratchet.ts — enforces per-workspace coverage baselines.
+//
+// Reads `coverage-baselines.json` at the repo root, then for each workspace
+// entry reads its coverage summary (vitest's `coverage-summary.json`,
+// emitted by the `json-summary` reporter) and compares each metric (lines /
+// branches / functions / statements) to the baseline.
+//
+// A regression on any metric fails the run. A workspace that's in the
+// baseline but missing a coverage summary also fails — silent skipping is
+// exactly the mode the ratchet exists to prevent.
+//
+// Exit code:
+//   0 — every baseline metric met or exceeded
+//   1 — at least one regression (or missing summary)
+//
+// Coverage *improvements* are reported but never required to update the
+// baseline locally; the `coverage-baseline-update.ts` script handles that
+// on the main branch via CI.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const METRICS = ['lines', 'branches', 'functions', 'statements'] as const;
+export type Metric = (typeof METRICS)[number];
+
+export interface WorkspaceBaseline {
+  summaryPath: string;
+  tier: 'A' | 'B' | 'C';
+  lines: number;
+  branches: number;
+  functions: number;
+  statements: number;
+  recordedAt: string;
+}
+
+export interface BaselineFile {
+  _comment?: string;
+  _epsilon?: number;
+  [workspace: string]: WorkspaceBaseline | string | number | undefined;
+}
+
+export interface CoverageSummary {
+  total: {
+    lines: { pct: number };
+    branches: { pct: number };
+    functions: { pct: number };
+    statements: { pct: number };
+  };
+}
+
+export interface RatchetCheck {
+  workspace: string;
+  status: 'ok' | 'regression' | 'improvement' | 'missing-summary' | 'invalid-summary';
+  before?: Record<Metric, number>;
+  after?: Record<Metric, number>;
+  regressions?: Array<{ metric: Metric; before: number; after: number }>;
+  message?: string;
+}
+
+export interface RatchetReport {
+  checks: RatchetCheck[];
+  passed: boolean;
+}
+
+const DEFAULT_EPSILON = 0.05;
+
+function isBaselineEntry(v: unknown): v is WorkspaceBaseline {
+  if (v === null || typeof v !== 'object') return false;
+  const e = v as Record<string, unknown>;
+  return (
+    typeof e.summaryPath === 'string' &&
+    typeof e.lines === 'number' &&
+    typeof e.branches === 'number' &&
+    typeof e.functions === 'number' &&
+    typeof e.statements === 'number'
+  );
+}
+
+export function loadBaseline(baselineJson: string): {
+  baseline: Record<string, WorkspaceBaseline>;
+  epsilon: number;
+} {
+  const parsed = JSON.parse(baselineJson) as BaselineFile;
+  const epsilon = typeof parsed._epsilon === 'number' ? parsed._epsilon : DEFAULT_EPSILON;
+  const baseline: Record<string, WorkspaceBaseline> = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (key.startsWith('_')) continue;
+    if (isBaselineEntry(value)) baseline[key] = value;
+  }
+  return { baseline, epsilon };
+}
+
+export function compareWorkspace(
+  workspace: string,
+  baseline: WorkspaceBaseline,
+  summary: CoverageSummary,
+  epsilon: number,
+): RatchetCheck {
+  const before: Record<Metric, number> = {
+    lines: baseline.lines,
+    branches: baseline.branches,
+    functions: baseline.functions,
+    statements: baseline.statements,
+  };
+  const after: Record<Metric, number> = {
+    lines: summary.total.lines.pct,
+    branches: summary.total.branches.pct,
+    functions: summary.total.functions.pct,
+    statements: summary.total.statements.pct,
+  };
+  const regressions: Array<{ metric: Metric; before: number; after: number }> = [];
+  let improved = false;
+  for (const metric of METRICS) {
+    const drop = before[metric] - after[metric];
+    if (drop > epsilon) {
+      regressions.push({ metric, before: before[metric], after: after[metric] });
+    } else if (after[metric] - before[metric] > epsilon) {
+      improved = true;
+    }
+  }
+  if (regressions.length > 0) {
+    return { workspace, status: 'regression', before, after, regressions };
+  }
+  if (improved) {
+    return { workspace, status: 'improvement', before, after };
+  }
+  return { workspace, status: 'ok', before, after };
+}
+
+export function runRatchet(
+  baseline: Record<string, WorkspaceBaseline>,
+  epsilon: number,
+  readSummary: (path: string) => CoverageSummary | null,
+): RatchetReport {
+  const checks: RatchetCheck[] = [];
+  for (const [workspace, entry] of Object.entries(baseline)) {
+    const summary = readSummary(entry.summaryPath);
+    if (summary === null) {
+      checks.push({
+        workspace,
+        status: 'missing-summary',
+        message: `no coverage summary at ${entry.summaryPath} — run the workspace's coverage script before the ratchet`,
+      });
+      continue;
+    }
+    if (
+      typeof summary?.total?.lines?.pct !== 'number' ||
+      typeof summary?.total?.branches?.pct !== 'number' ||
+      typeof summary?.total?.functions?.pct !== 'number' ||
+      typeof summary?.total?.statements?.pct !== 'number'
+    ) {
+      checks.push({
+        workspace,
+        status: 'invalid-summary',
+        message: `coverage summary at ${entry.summaryPath} is missing required total metrics`,
+      });
+      continue;
+    }
+    checks.push(compareWorkspace(workspace, entry, summary, epsilon));
+  }
+  const passed = checks.every((c) => c.status === 'ok' || c.status === 'improvement');
+  return { checks, passed };
+}
+
+function fmtPct(n: number): string {
+  return `${n.toFixed(2)}%`;
+}
+
+function renderReport(report: RatchetReport): string {
+  const lines: string[] = [];
+  const DIVIDER = '─'.repeat(60);
+  lines.push('\nCoverage Ratchet');
+  lines.push(DIVIDER);
+  for (const c of report.checks) {
+    if (c.status === 'ok') {
+      lines.push(`✅  ${c.workspace} — baseline met`);
+    } else if (c.status === 'improvement') {
+      lines.push(`📈  ${c.workspace} — coverage improved (CI on main will bump baseline)`);
+      if (c.before && c.after) {
+        for (const m of METRICS) {
+          if (c.after[m] - c.before[m] > 0.05) {
+            lines.push(`     ${m}: ${fmtPct(c.before[m])} → ${fmtPct(c.after[m])}`);
+          }
+        }
+      }
+    } else if (c.status === 'regression' && c.regressions) {
+      lines.push(`❌  ${c.workspace} — REGRESSION:`);
+      for (const r of c.regressions) {
+        lines.push(`     ${r.metric}: ${fmtPct(r.before)} → ${fmtPct(r.after)}`);
+      }
+    } else if (c.status === 'missing-summary' || c.status === 'invalid-summary') {
+      lines.push(`❌  ${c.workspace} — ${c.message}`);
+    }
+  }
+  lines.push(DIVIDER);
+  if (report.passed) {
+    lines.push('All workspaces ≥ baseline.');
+  } else {
+    lines.push('One or more workspaces regressed. Run the workspace coverage');
+    lines.push('script locally to reproduce, add tests for the affected files,');
+    lines.push('and commit until the ratchet passes. See docs/testing.md.');
+  }
+  return lines.join('\n');
+}
+
+if (import.meta.main) {
+  const HERE = dirname(fileURLToPath(import.meta.url));
+  const ROOT = join(HERE, '..', '..');
+  const BASELINE_PATH = join(ROOT, 'coverage-baselines.json');
+
+  if (!existsSync(BASELINE_PATH)) {
+    console.error(`coverage-baselines.json not found at ${BASELINE_PATH}`);
+    process.exit(1);
+  }
+  const { baseline, epsilon } = loadBaseline(readFileSync(BASELINE_PATH, 'utf-8'));
+
+  const report = runRatchet(baseline, epsilon, (relPath) => {
+    const abs = join(ROOT, relPath);
+    if (!existsSync(abs)) return null;
+    try {
+      return JSON.parse(readFileSync(abs, 'utf-8')) as CoverageSummary;
+    } catch {
+      return null;
+    }
+  });
+
+  console.log(renderReport(report));
+  process.exit(report.passed ? 0 : 1);
+}
diff --git a/scripts/lint/no-duplicate-utils.ts b/scripts/lint/no-duplicate-utils.ts
new file mode 100644
index 0000000000..9b4488de99
--- /dev/null
+++ b/scripts/lint/no-duplicate-utils.ts
@@ -0,0 +1,215 @@
+#!/usr/bin/env bun
+//
+// no-duplicate-utils.ts — flags re-implementations of helpers that are already
+// exported from @packrat/utils.
+//
+// The utils package (packages/utils/) is the single source of truth for the
+// curated general-utility surface (array / async / fn / json / math / object /
+// string / predicates). Duplicating those helpers in app code leads to subtle
+// behavioural divergence and defeats the "one import path" policy.
+//
+// The banned-name set is DERIVED from the @packrat/utils provenance manifest
+// (packages/utils/src/provenance.ts), whose keys ARE the canonical export
+// names. The check therefore auto-syncs as the facade grows — adding a row to
+// the manifest extends coverage with no edit here.
+//
+// A "re-implementation" is any top-level function declaration or arrow-function
+// assignment whose name matches one of the manifest names, found outside
+// packages/utils/ and packages/checks/ (the check scripts themselves).
+// Re-exports (`export { x } from ...`, `import { x } from ...`) and comments
+// are NOT flagged — only home-grown re-IMPLEMENTATIONS.
+//
+// Matching precision: this flags only *callable* declarations — a `function`
+// declaration, or a `const`/`let` whose value is a function (arrow `=>` or
+// `function`). It does NOT flag method calls, object keys, property accesses,
+// or data-valued locals. This matters because several manifest names are
+// generic (sort, min, max, group, pipe, round, chunk, sum, list, once, assign,
+// title); a naive name match flags innocent locals like `const list = await
+// bucket.list()` or `const title = 'Open up the code'`. Requiring a function
+// value eliminates that whole class of false positive while still catching any
+// home-grown re-implementation (a re-implementation is, by definition, a
+// function). Verified clean against the current repo (a naive declaration
+// match flagged 9 data-valued locals; the function-value scope flags 0).
+//
+// Exit code:
+//   0 — no violations
+//   1 — violations found
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { provenance } from '@packrat/utils/provenance';
+
+const SCAN_ROOTS = ['apps', 'packages'];
+
+// Names exported from @packrat/utils that should not be re-implemented
+// elsewhere — derived from the provenance manifest keys so this auto-syncs.
+export const UTIL_NAMES = new Set(Object.keys(provenance));
+
+// Excluded source roots (the canonical definitions live here).
+// Mirrors no-duplicate-guards: utils is the source of truth, and the checks
+// package houses the analyzers themselves.
+const EXCLUDED_ROOTS = ['packages/utils', 'packages/checks'];
+
+const EXCLUDED_DIRS = new Set(['node_modules', 'dist', 'build', '.next', '.expo', 'drizzle']);
+
+// Matches a function *declaration* — always a re-implementation:
+//   export function unique(...)
+//   function unique(...)
+const FUNCTION_DECL_PATTERN = /(?:export\s+)?function\s*\*?\s*([A-Za-z][A-Za-z0-9_]*)\s*[(<]/g;
+
+// Matches a const/let bound to a function value — also a re-implementation:
+//   const unique = (...) => ...
+//   export const unique = async (a, b) => ...
+//   const unique = function (...) { ... }
+//   export const unique = <T>(x: T) => ...
+//   const unique = (a: number): number => ...
+// The trailing lookahead requires the right-hand side to begin a function:
+// an arrow's param list `(`, a generic `<`, a single bare param + `=>`, or the
+// `function`/`async` keyword. A data-valued `const list = await bucket.list()`
+// does NOT match (its RHS is `await ...`, not a function literal).
+const FUNCTION_CONST_PATTERN =
+  /(?:export\s+)?(?:const|let)\s+([A-Za-z][A-Za-z0-9_]*)\s*=\s*(?:async\s+)?(?:function\b|\(|<|[A-Za-z_$][\w$]*\s*=>)/g;
+
+// Matches a const/let whose TYPE ANNOTATION is a function type — a function-
+// typed binding is still a re-implementation:
+//   const isString: (v: unknown) => boolean = (v) => ...
+//   export const clamp: (n: number) => number = clampImpl;
+// The `=>` inside the annotation (before the value `=`) is the signal. This is
+// kept separate from FUNCTION_CONST_PATTERN because the annotation can itself
+// contain `=>`, which a single combined regex cannot cleanly span.
+const FUNCTION_TYPED_CONST_PATTERN =
+  /(?:export\s+)?(?:const|let)\s+([A-Za-z][A-Za-z0-9_]*)\s*:[^=]*=>/g;
+
+export interface Violation {
+  file: string;
+  line: number;
+  name: string;
+  source: string;
+}
+
+/**
+ * Scan a single file's source text for home-grown re-implementations of
+ * @packrat/utils helpers. Pure (no filesystem) so it is unit-testable.
+ */
+export function analyzeSource(file: string, content: string): Violation[] {
+  const violations: Violation[] = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? '';
+    const trimmed = line.trimStart();
+
+    // Skip comment lines and import/export-from lines
+    if (
+      trimmed.startsWith('//') ||
+      trimmed.startsWith('*') ||
+      trimmed.startsWith('/*') ||
+      /^\s*export\s*\{/.test(line) ||
+      /^\s*(import|export)\s+.*\s+from\s+['"]/.test(line)
+    ) {
+      continue;
+    }
+
+    const seen = new Set<string>();
+    for (const pattern of [
+      FUNCTION_DECL_PATTERN,
+      FUNCTION_CONST_PATTERN,
+      FUNCTION_TYPED_CONST_PATTERN,
+    ]) {
+      pattern.lastIndex = 0;
+      for (let m = pattern.exec(line); m !== null; m = pattern.exec(line)) {
+        const name = m[1];
+        // A function-typed const can match both const patterns; dedupe per line.
+        if (name && UTIL_NAMES.has(name) && !seen.has(name)) {
+          seen.add(name);
+          violations.push({ file, line: i + 1, name, source: line.trimEnd() });
+        }
+      }
+    }
+  }
+
+  return violations;
+}
+
+function isTargetFile(name: string): boolean {
+  return (
+    /\.(ts|tsx|cts|mts)$/.test(name) && !/\.(test|spec|stories|d)\.(ts|tsx|cts|mts)$/.test(name)
+  );
+}
+
+/** True for paths under a canonical-source root that must never be flagged. */
+export function isExcluded(relPath: string): boolean {
+  return EXCLUDED_ROOTS.some((p) => relPath === p || relPath.startsWith(`${p}/`));
+}
+
+function walkDir(dir: string, relPath: string, violations: Violation[]): void {
+  if (isExcluded(relPath)) return;
+
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (EXCLUDED_DIRS.has(entry)) continue;
+
+    const fullPath = join(dir, entry);
+    const entryRel = `${relPath}/${entry}`;
+
+    let isDir = false;
+    try {
+      isDir = statSync(fullPath).isDirectory();
+    } catch {
+      continue;
+    }
+
+    if (isDir) {
+      walkDir(fullPath, entryRel, violations);
+    } else if (isTargetFile(entry)) {
+      let content: string;
+      try {
+        content = readFileSync(fullPath, 'utf8');
+      } catch {
+        continue;
+      }
+
+      violations.push(...analyzeSource(entryRel, content));
+    }
+  }
+}
+
+function main(): void {
+  const root = join(import.meta.dir, '..', '..');
+  const violations: Violation[] = [];
+  for (const scanRoot of SCAN_ROOTS) {
+    walkDir(join(root, scanRoot), scanRoot, violations);
+  }
+
+  if (violations.length === 0) {
+    console.log('No duplicate @packrat/utils implementations found.');
+    process.exit(0);
+  }
+
+  console.log(
+    `Found ${violations.length} util re-implementation(s) outside @packrat/utils — import from '@packrat/utils' instead:\n`,
+  );
+
+  let lastFile = '';
+  for (const v of violations) {
+    if (v.file !== lastFile) {
+      console.log(`  ${v.file}`);
+      lastFile = v.file;
+    }
+    console.log(`    line ${v.line}: ${v.name}`);
+    console.log(`      ${v.source}`);
+  }
+
+  console.log("\nFix: remove the local copy and import from '@packrat/utils'.");
+  process.exit(1);
+}
+
+if (import.meta.main) {
+  main();
+}
diff --git a/scripts/lint/no-owned-max-params.ts b/scripts/lint/no-owned-max-params.ts
index fa4a94b7d9..c7924ce1a9 100644
--- a/scripts/lint/no-owned-max-params.ts
+++ b/scripts/lint/no-owned-max-params.ts
@@ -31,6 +31,9 @@ const EXCLUDED_DIRS = new Set([
 const EXCLUDED_PATH_PARTS = ['/test/', '/__tests__/', '/mocks/', '/playwright/'];
 const EXCLUDED_SUFFIXES = ['.test.ts', '.test.tsx', '.spec.ts', '.spec.tsx'];
 const EXCLUDED_FILES = new Set([
+  // safeJsonParse(value, options) is a deliberate drop-in for the native
+  // JSON.parse(text, reviver) / destr(value, options) signature.
+  'packages/utils/src/json.ts',
   // This service intentionally mirrors Cloudflare R2's positional API.
   'packages/api/src/services/r2-bucket.ts',
   // These build scripts override globalThis.fetch with a shim that must
diff --git a/scripts/lint/no-raw-ast-grep.ts b/scripts/lint/no-raw-ast-grep.ts
new file mode 100644
index 0000000000..f497249da3
--- /dev/null
+++ b/scripts/lint/no-raw-ast-grep.ts
@@ -0,0 +1,32 @@
+#!/usr/bin/env bun
+//
+// no-raw-ast-grep.ts — runs the ast-grep structural lint suite and propagates
+// its exit code.
+//
+// This replaces the former regex-based scripts no-raw-typeof.ts and
+// no-raw-regex.ts. They were ported to AST-accurate ast-grep rules (under
+// ast-grep-rules/) which catch every pattern the regex versions did — plus the
+// optional-chaining / bracket / member-expression cases the regex versions
+// silently missed (e.g. `typeof options?.md5 === 'string'`). Parity is proven
+// by the ast-grep rule tests (`ast-grep test`); see ast-grep-rules/PARITY.md.
+//
+// Rules enforced (error → fails CI):
+//   - no-raw-typeof    → use @packrat/guards predicates instead of raw typeof
+//   - no-raw-regex     → use magic-regexp instead of raw regex literals
+// Rules at warning level (do NOT fail CI yet):
+//   - no-raw-json*     → use @packrat/utils safeParse/safeStringify
+//                        (the repo-wide JSON migration flips these to error)
+//
+// Exit code mirrors ast-grep: 0 — clean; 1 — error-level diagnostics found.
+
+import { join } from 'node:path';
+
+const ROOT = join(import.meta.dir, '..', '..');
+
+const proc = Bun.spawn(['bunx', 'ast-grep', 'scan', '-c', join(ROOT, 'sgconfig.yml')], {
+  cwd: ROOT,
+  stdout: 'inherit',
+  stderr: 'inherit',
+});
+
+process.exit(await proc.exited);
diff --git a/scripts/lint/no-raw-regex.ts b/scripts/lint/no-raw-regex.ts
deleted file mode 100644
index 4976eff886..0000000000
--- a/scripts/lint/no-raw-regex.ts
+++ /dev/null
@@ -1,120 +0,0 @@
-#!/usr/bin/env bun
-//
-// no-raw-regex.ts — enforces using magic-regexp instead of raw regex literals
-// or `new RegExp(...)` in non-test production code.
-//
-// The reference implementation lives in packages/analytics/src/core/enrichment.ts.
-// Raw regex literals are easy to get wrong (missing escapes, unintended group
-// captures, poor readability) and magic-regexp gives us a typed, composable
-// builder that's easier to review.
-//
-// What gets flagged:
-//   - `new RegExp(...)` anywhere in apps/ or packages/ (excluding tests)
-//   - Any `.replace(/.../)`, `.match(/.../)`, `.test(/.../)`, `.split(/.../)`,
-//     `.search(/.../)`, `.replaceAll(/.../)` call — a strong signal of a raw
-//     literal being used against a string method.
-//
-// Note: this is an intentionally coarse check — it will miss regex literals
-// assigned to variables, and it will over-flag a handful of call sites. That's
-// fine for a nudge-style rule. Biome's `performance/useTopLevelRegex` covers
-// the stricter AST check.
-//
-// Exit code:
-//   0 — no violations
-//   1 — violations found (details printed to stdout)
-
-import { readdirSync, readFileSync, statSync } from 'node:fs';
-import { join } from 'node:path';
-
-const ROOT = join(import.meta.dir, '..', '..');
-
-const ROOTS = ['apps', 'packages'];
-
-// Matches: new RegExp(...) or string method calls with a regex literal argument.
-// `\(\/` reliably identifies a regex literal start (opening paren + forward slash),
-// since division expressions like `.test(x/2)` would not begin with `(/`. This
-// check is intentionally coarse — it may over-flag a handful of call sites, which
-// is acceptable for a nudge-style rule. Biome's `performance/useTopLevelRegex`
-// covers the stricter AST-level check.
-const REGEX_PATTERN =
-  /(new\s+RegExp\s*\()|(\.(replace|replaceAll|match|matchAll|test|split|search)\(\/)/;
-
-const EXCLUDED_DIRS = new Set(['node_modules', 'dist', 'build', '.wrangler']);
-
-// Files explicitly allowed to use raw regex.
-// alltrails.ts: builds regex from a dynamic `property` argument — can't be a static constant.
-const EXCLUDED_FILES = new Set([
-  'packages/analytics/src/core/enrichment.ts',
-  'packages/api/src/routes/alltrails.ts',
-]);
-
-function isTargetFile(name: string): boolean {
-  return /\.(ts|tsx|cts|mts)$/.test(name) && !/\.(test|spec)\.(ts|tsx|cts|mts)$/.test(name);
-}
-
-interface Violation {
-  file: string;
-  line: number;
-  content: string;
-}
-
-function walkDir(dir: string, relPath: string, violations: Violation[]): void {
-  let entries: string[];
-  try {
-    entries = readdirSync(dir);
-  } catch {
-    return;
-  }
-
-  for (const entry of entries) {
-    if (EXCLUDED_DIRS.has(entry)) continue;
-
-    const entryFull = join(dir, entry);
-    const entryRel = `${relPath}/${entry}`;
-
-    let isDir = false;
-    try {
-      isDir = statSync(entryFull).isDirectory();
-    } catch {
-      continue;
-    }
-
-    if (isDir) {
-      walkDir(entryFull, entryRel, violations);
-    } else if (isTargetFile(entry)) {
-      if (EXCLUDED_FILES.has(entryRel)) continue;
-
-      let content: string;
-      try {
-        content = readFileSync(entryFull, 'utf-8');
-      } catch {
-        continue;
-      }
-
-      const lines = content.split('\n');
-      for (let i = 0; i < lines.length; i++) {
-        if (REGEX_PATTERN.test(lines[i] ?? '')) {
-          violations.push({ file: entryRel, line: i + 1, content: lines[i]?.trimEnd() ?? '' });
-        }
-      }
-    }
-  }
-}
-
-const violations: Violation[] = [];
-
-for (const root of ROOTS) {
-  walkDir(join(ROOT, root), root, violations);
-}
-
-if (violations.length > 0) {
-  console.log(
-    `Raw regex literals found (${violations.length}) — prefer magic-regexp (see packages/analytics/src/core/enrichment.ts for a reference):\n`,
-  );
-  for (const { file, line, content } of violations) {
-    console.log(`${file}:${line}:${content}`);
-  }
-  process.exit(1);
-}
-
-console.log('No raw regex literals in non-test production code.');
diff --git a/scripts/lint/no-raw-typeof.ts b/scripts/lint/no-raw-typeof.ts
deleted file mode 100644
index 88510b5299..0000000000
--- a/scripts/lint/no-raw-typeof.ts
+++ /dev/null
@@ -1,123 +0,0 @@
-#!/usr/bin/env bun
-//
-// no-raw-typeof.ts — enforces using @packrat/guards instead of raw typeof checks.
-//
-// Flags any code outside of @packrat/guards itself that uses
-//   typeof x === 'string' | 'number' | 'boolean' | 'function' | 'object' |
-//              'undefined' | 'symbol' | 'bigint'
-// (or the !== counterpart). The guard package is the canonical place for
-// primitive narrowing — everything else should import isString/isNumber/etc.
-//
-// Exit code:
-//   0 — no violations
-//   1 — violations found (details printed to stdout)
-//
-// Wired into `bun lint:strict`. Not yet in default CI while the backlog
-// is worked down.
-
-import { readdirSync, readFileSync, statSync } from 'node:fs';
-import { join } from 'node:path';
-
-const ROOT = join(import.meta.dir, '..', '..');
-
-const ROOTS = ['apps', 'packages'];
-
-// Matches: typeof x === 'string' (and !== counterpart, all primitive types).
-// Uses a backreference (\3) to ensure the opening and closing quotes match.
-// Group 1 captures the identifier being checked.
-const TYPEOF_PATTERN =
-  /typeof\s+([A-Za-z_][A-Za-z0-9_.]*)\s*(===|!==)\s*(['"])(string|number|boolean|object|function|undefined|symbol|bigint)\3/;
-
-// Globally-available identifiers used for SSR/environment availability checks.
-// `typeof window !== 'undefined'` cannot be replaced with `isDefined(window)`
-// because accessing an undeclared global throws a ReferenceError. These are
-// intentionally exempted from the no-raw-typeof rule.
-const GLOBAL_IDENTIFIERS = new Set([
-  'window',
-  'document',
-  'globalThis',
-  'Bun',
-  'navigator',
-  'process',
-]);
-
-const EXCLUDED_DIRS = new Set(['node_modules', 'dist', 'build', '.wrangler']);
-
-function isExcludedPath(relPath: string): boolean {
-  return relPath === 'packages/guards' || relPath.startsWith('packages/guards/');
-}
-
-function isTargetFile(name: string): boolean {
-  return /\.(ts|tsx|cts|mts)$/.test(name) && !/\.(test|spec)\.(ts|tsx|cts|mts)$/.test(name);
-}
-
-interface Violation {
-  file: string;
-  line: number;
-  content: string;
-}
-
-function walkDir(dir: string, relPath: string, violations: Violation[]): void {
-  if (isExcludedPath(relPath)) return;
-
-  let entries: string[];
-  try {
-    entries = readdirSync(dir);
-  } catch {
-    return;
-  }
-
-  for (const entry of entries) {
-    if (EXCLUDED_DIRS.has(entry)) continue;
-
-    const entryFull = join(dir, entry);
-    const entryRel = `${relPath}/${entry}`;
-
-    let isDir = false;
-    try {
-      isDir = statSync(entryFull).isDirectory();
-    } catch {
-      continue;
-    }
-
-    if (isDir) {
-      walkDir(entryFull, entryRel, violations);
-    } else if (isTargetFile(entry)) {
-      let content: string;
-      try {
-        content = readFileSync(entryFull, 'utf-8');
-      } catch {
-        continue;
-      }
-
-      const lines = content.split('\n');
-      for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        const match = TYPEOF_PATTERN.exec(line);
-        if (match) {
-          const identifier = match[1] ?? '';
-          if (GLOBAL_IDENTIFIERS.has(identifier)) continue;
-          violations.push({ file: entryRel, line: i + 1, content: line.trimEnd() });
-        }
-      }
-    }
-  }
-}
-
-const violations: Violation[] = [];
-
-for (const root of ROOTS) {
-  walkDir(join(ROOT, root), root, violations);
-}
-
-if (violations.length > 0) {
-  console.log(
-    `Raw typeof checks found (${violations.length}) — use @packrat/guards (isString, isNumber, isBoolean, isFunction, isObject) instead:\n`,
-  );
-  for (const { file, line, content } of violations) {
-    console.log(`${file}:${line}:${content}`);
-  }
-  process.exit(1);
-}
-
-console.log('No raw typeof checks in non-test code.');
diff --git a/scripts/lint/no-weak-assertions.ts b/scripts/lint/no-weak-assertions.ts
new file mode 100644
index 0000000000..9c5c946c20
--- /dev/null
+++ b/scripts/lint/no-weak-assertions.ts
@@ -0,0 +1,354 @@
+#!/usr/bin/env bun
+//
+// no-weak-assertions.ts — catches coverage theater in test files.
+//
+// Walks every `.test.ts` / `.test.tsx` file under apps/* and packages/* and
+// flags `it(...)` / `test(...)` blocks that contain one of the following:
+//
+//   • assertion-free-test    — zero `expect(` or `expect*(...)` calls in
+//                              the block. Helper assertions whose names
+//                              start with `expect` (e.g. `expectUnauthorized`,
+//                              `expectJsonResponse`) count as assertions.
+//   • only-tobedefined       — every direct `expect(...)` ends in a
+//                              non-specific matcher (`.toBeDefined()`,
+//                              `.toBeTruthy()`, `.toBeFalsy()`,
+//                              `.not.toBeUndefined()`, or
+//                              `.not.toBeNull()`) AND no expect-helper is
+//                              called in the block. `.toBeUndefined()` and
+//                              `.toBeNull()` alone are NOT flagged — they
+//                              assert specific return values.
+//   • bare-tohavebeencalled  — `.toHaveBeenCalled()` present without
+//                              `.toHaveBeenCalledWith(...)` or
+//                              `.toHaveBeenCalledTimes(...)` in the same
+//                              block.
+//   • large-snapshot         — `toMatchInlineSnapshot(...)` body > 50 lines.
+//
+// These patterns provably hide regressions and inflate coverage without
+// proving behaviour. Tests should assert specific values, specific call
+// shapes, or both.
+//
+// Escape hatch:
+//   // no-weak-assertions: disable
+// placed within the file's first 5 lines skips the file entirely. Use
+// sparingly — grandfathered tests only.
+//
+// `it.todo(...)`, `it.skip(...)`, `it.each(...)` are not flagged (they
+// either have no body or carry parameterised bodies that this rule does
+// not analyse).
+//
+// Exit code:
+//   0 — no violations
+//   1 — violations found
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SCAN_ROOTS = ['apps', 'packages'];
+const EXCLUDED_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  '.next',
+  '.expo',
+  '.wrangler',
+  'coverage',
+]);
+
+const LARGE_SNAPSHOT_THRESHOLD_LINES = 50;
+const DISABLE_COMMENT = 'no-weak-assertions: disable';
+
+// Matchers that assert *non-specific* shape — covered tests should usually
+// assert a concrete value instead. `.toBeUndefined()` and `.toBeNull()` are
+// intentionally NOT in this list: when the function under test is documented
+// to return `undefined` / `null`, these are specific assertions, not weak.
+const WEAK_MATCHER_PATTERN =
+  /\.(?:toBeDefined|toBeTruthy|toBeFalsy)\s*\(\s*\)|\.not\.(?:toBeUndefined|toBeNull)\s*\(\s*\)/;
+
+// Match `it(`, `test(`, `it.only(`, `test.only(`. Skip `.todo`, `.skip`,
+// `.each`, `.concurrent`, `.failing` since they don't carry a runnable body
+// the rule applies to.
+const TEST_OPENER_PATTERN = /\b(?:it|test)(?:\.only)?\s*\(/g;
+
+export type WeakAssertionRule =
+  | 'assertion-free-test'
+  | 'only-tobedefined'
+  | 'bare-tohavebeencalled'
+  | 'large-snapshot';
+
+export interface Violation {
+  file: string;
+  line: number;
+  rule: WeakAssertionRule;
+  message: string;
+}
+
+export function isFileDisabled(src: string): boolean {
+  const head = src.split('\n').slice(0, 5).join('\n');
+  return head.includes(DISABLE_COMMENT);
+}
+
+// Locate the matching closing paren / brace, starting from `start` (the
+// index of the opening character in `src`). Returns the index of the close,
+// or -1 if not found (unbalanced).
+function findMatchingClose(src: string, start: number, open: string, close: string): number {
+  let depth = 0;
+  let inString: '"' | "'" | '`' | null = null;
+  let inLineComment = false;
+  let inBlockComment = false;
+  let inRegex = false;
+  for (let i = start; i < src.length; i++) {
+    const ch = src[i] ?? '';
+    const prev = src[i - 1] ?? '';
+    const next = src[i + 1] ?? '';
+
+    if (inLineComment) {
+      if (ch === '\n') inLineComment = false;
+      continue;
+    }
+    if (inBlockComment) {
+      if (ch === '*' && next === '/') {
+        inBlockComment = false;
+        i++;
+      }
+      continue;
+    }
+    if (inString) {
+      if (ch === '\\') {
+        i++;
+        continue;
+      }
+      if (ch === inString) inString = null;
+      continue;
+    }
+    if (inRegex) {
+      if (ch === '\\') {
+        i++;
+        continue;
+      }
+      if (ch === '/') inRegex = false;
+      continue;
+    }
+
+    if (ch === '/' && next === '/') {
+      inLineComment = true;
+      i++;
+      continue;
+    }
+    if (ch === '/' && next === '*') {
+      inBlockComment = true;
+      i++;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === '`') {
+      inString = ch as '"' | "'" | '`';
+      continue;
+    }
+    if (ch === '/' && /[(,=:!&|?+\-*%~^[{;]/.test(prev)) {
+      inRegex = true;
+      continue;
+    }
+
+    if (ch === open) depth++;
+    else if (ch === close) {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+function lineNumberOf(src: string, index: number): number {
+  let line = 1;
+  for (let i = 0; i < index; i++) {
+    if (src[i] === '\n') line++;
+  }
+  return line;
+}
+
+function pushIfNew(violations: Violation[], v: Violation): void {
+  // Avoid duplicate (file, line, rule) entries when a block contains both
+  // a snapshot violation and a block-level violation on the same line.
+  if (violations.some((x) => x.file === v.file && x.line === v.line && x.rule === v.rule)) return;
+  violations.push(v);
+}
+
+function checkInlineSnapshots(src: string, file: string, violations: Violation[]): void {
+  const pattern = /\.toMatchInlineSnapshot\s*\(/g;
+  let match: RegExpExecArray | null = pattern.exec(src);
+  while (match !== null) {
+    const openIdx = match.index + match[0].length - 1;
+    const closeIdx = findMatchingClose(src, openIdx, '(', ')');
+    if (closeIdx !== -1) {
+      const snippet = src.slice(openIdx + 1, closeIdx);
+      const lineCount = snippet.split('\n').length;
+      if (lineCount > LARGE_SNAPSHOT_THRESHOLD_LINES) {
+        pushIfNew(violations, {
+          file,
+          line: lineNumberOf(src, match.index),
+          rule: 'large-snapshot',
+          message: `inline snapshot is ${lineCount} lines (limit ${LARGE_SNAPSHOT_THRESHOLD_LINES})`,
+        });
+      }
+    }
+    match = pattern.exec(src);
+  }
+}
+
+function checkTestBlocks(src: string, file: string, violations: Violation[]): void {
+  TEST_OPENER_PATTERN.lastIndex = 0;
+  let match: RegExpExecArray | null = TEST_OPENER_PATTERN.exec(src);
+  while (match !== null) {
+    const openParenIdx = match.index + match[0].length - 1;
+    const closeParenIdx = findMatchingClose(src, openParenIdx, '(', ')');
+    if (closeParenIdx === -1) {
+      match = TEST_OPENER_PATTERN.exec(src);
+      continue;
+    }
+
+    const head = src.slice(openParenIdx, closeParenIdx + 1);
+    const bodyBraceMatch = /=>\s*\{|function[^(]*\([^)]*\)\s*\{|async\s*\([^)]*\)\s*=>\s*\{/.exec(
+      head,
+    );
+    if (!bodyBraceMatch) {
+      match = TEST_OPENER_PATTERN.exec(src);
+      continue;
+    }
+    const bodyBraceIdx = openParenIdx + bodyBraceMatch.index + bodyBraceMatch[0].length - 1;
+    const bodyCloseIdx = findMatchingClose(src, bodyBraceIdx, '{', '}');
+    if (bodyCloseIdx === -1) {
+      match = TEST_OPENER_PATTERN.exec(src);
+      continue;
+    }
+    const body = src.slice(bodyBraceIdx + 1, bodyCloseIdx);
+    const startLine = lineNumberOf(src, match.index);
+
+    // Count any function call whose name starts with `expect` — covers both
+    // bare `expect(` and convention-based helpers like `expectUnauthorized(`,
+    // `expectJsonResponse(`, `expectForbidden(`, etc., which encapsulate
+    // assertion logic inside a named helper.
+    const expectLikeCalls = (body.match(/\bexpect[A-Za-z0-9]*\s*\(/g) ?? []).length;
+
+    if (expectLikeCalls === 0) {
+      pushIfNew(violations, {
+        file,
+        line: startLine,
+        rule: 'assertion-free-test',
+        message: 'test block has no expect() or expect-helper calls',
+      });
+      match = TEST_OPENER_PATTERN.exec(src);
+      continue;
+    }
+
+    // only-tobedefined: every direct `expect(...)` ends in a weak matcher AND
+    // there are no expect-helper calls (helpers like expectUnauthorized are
+    // assumed to assert specific shape internally).
+    const bareExpectSites = [...body.matchAll(/\bexpect\s*\(/g)];
+    const helperExpectSites = expectLikeCalls - bareExpectSites.length;
+    let weakCount = 0;
+    for (const m of bareExpectSites) {
+      const after = body.slice(m.index ?? 0, (m.index ?? 0) + 200);
+      if (WEAK_MATCHER_PATTERN.test(after)) weakCount++;
+    }
+    if (
+      helperExpectSites === 0 &&
+      bareExpectSites.length > 0 &&
+      weakCount === bareExpectSites.length
+    ) {
+      pushIfNew(violations, {
+        file,
+        line: startLine,
+        rule: 'only-tobedefined',
+        message:
+          'every expect() uses a non-specific matcher (toBeDefined / toBeTruthy / toBeFalsy / .not.toBeUndefined / .not.toBeNull) — assert specific values',
+      });
+    }
+
+    // bare-tohavebeencalled: `.toHaveBeenCalled()` present without
+    // `.toHaveBeenCalledWith(` or `.toHaveBeenCalledTimes(` in the same block.
+    const hasBareCalled = /\.toHaveBeenCalled\s*\(\s*\)/.test(body);
+    const hasArgMatcher = /\.toHaveBeenCalledWith\s*\(|\.toHaveBeenCalledTimes\s*\(/.test(body);
+    if (hasBareCalled && !hasArgMatcher) {
+      pushIfNew(violations, {
+        file,
+        line: startLine,
+        rule: 'bare-tohavebeencalled',
+        message:
+          '.toHaveBeenCalled() without .toHaveBeenCalledWith(...) or .toHaveBeenCalledTimes(N) — assert the call shape',
+      });
+    }
+
+    match = TEST_OPENER_PATTERN.exec(src);
+  }
+}
+
+// Analyse a single source string and return the violations it contains.
+// `file` is used purely as a label in the returned violations; this function
+// does not read from disk and is safe to call from tests with inline source.
+export function analyzeSource(file: string, src: string): Violation[] {
+  if (isFileDisabled(src)) return [];
+  const violations: Violation[] = [];
+  checkInlineSnapshots(src, file, violations);
+  checkTestBlocks(src, file, violations);
+  return violations;
+}
+
+function isTestFile(name: string): boolean {
+  return /\.(test|spec)\.(ts|tsx|cts|mts)$/.test(name);
+}
+
+function walkDir(dir: string, relPath: string, files: string[]): void {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (EXCLUDED_DIRS.has(entry)) continue;
+    const full = join(dir, entry);
+    const rel = `${relPath}/${entry}`;
+    let isDir = false;
+    try {
+      isDir = statSync(full).isDirectory();
+    } catch {
+      continue;
+    }
+    if (isDir) {
+      walkDir(full, rel, files);
+    } else if (isTestFile(entry)) {
+      files.push(rel);
+    }
+  }
+}
+
+if (import.meta.main) {
+  const ROOT = join(import.meta.dir, '..', '..');
+  const files: string[] = [];
+  for (const root of SCAN_ROOTS) {
+    walkDir(join(ROOT, root), root, files);
+  }
+
+  const violations: Violation[] = [];
+  for (const file of files) {
+    let src: string;
+    try {
+      src = readFileSync(join(ROOT, file), 'utf-8');
+    } catch {
+      continue;
+    }
+    for (const v of analyzeSource(file, src)) violations.push(v);
+  }
+
+  if (violations.length > 0) {
+    console.log(`Weak assertion patterns found (${violations.length} violations):\n`);
+    for (const v of violations) {
+      console.log(`${v.file}:${v.line}:${v.rule}: ${v.message}`);
+    }
+    console.log(
+      '\nFix by asserting specific values, specific call shapes, or both. See docs/testing.md.',
+    );
+    process.exit(1);
+  }
+
+  console.log('No weak-assertion patterns found.');
+}
diff --git a/scripts/vitest.config.ts b/scripts/vitest.config.ts
new file mode 100644
index 0000000000..5e8f9107c9
--- /dev/null
+++ b/scripts/vitest.config.ts
@@ -0,0 +1,20 @@
+import { resolve } from 'node:path';
+import { defineConfig } from 'vitest/config';
+
+/**
+ * Vitest configuration for the repo-level scripts in `scripts/`.
+ *
+ * Run with: bun test:scripts
+ *
+ * Custom lint scripts (`scripts/lint/*.ts`) and the coverage ratchet
+ * (`scripts/lint/coverage-ratchet.ts`) get their own test coverage via
+ * files under `scripts/lint/__tests__/`.
+ */
+export default defineConfig({
+  test: {
+    name: 'scripts-unit',
+    environment: 'node',
+    globals: true,
+    include: [resolve(__dirname, '**/__tests__/**/*.test.ts')],
+  },
+});
diff --git a/sgconfig.yml b/sgconfig.yml
new file mode 100644
index 0000000000..d237036461
--- /dev/null
+++ b/sgconfig.yml
@@ -0,0 +1,4 @@
+ruleDirs:
+  - ast-grep-rules
+testConfigs:
+  - testDir: ast-grep-tests