feat(receipts): ReceiptIntake state machine + intake endpoint + worker (pipeline v2 phase 1)

.env.example

@@ -31,6 +31,44 @@ MCP_SECRET=
 BANK_LEDGER_INGEST_SECRET=generate_a_strong_random_secret_here
 BANK_LEDGER_STATUS_SECRET=generate_a_different_strong_random_secret_here
 
+# --- Receipt Pipeline v2 (docs/plans/PHASE-1-INTAKE-CORE-SPEC.md) ---
+# TWO machine secrets, deliberately separate: they belong to different programs
+# with different blast radii, and they rotate independently. Setting them to the
+# SAME value is refused at runtime — that would silently re-merge the two.
+#
+# The Apps Script forwarders. May only INGEST (POST /api/receipts/intake,
+# /start, /{id}/finalize) and only under source drive|email|chat. Cannot read
+# the queue and cannot archive.
+RECEIPT_INTAKE_SECRET=
+# The nightly Drive archive mirror. May only READ BOOKED/ARCHIVED rows
+# (GET /api/receipts/intake?state=BOOKED) and report back what it archived
+# (POST /api/receipts/intake/{id}/archived). Cannot create or publish a row.
+RECEIPT_ARCHIVE_SECRET=
+#
+# Storage note (not an env var): receipts live in their OWN private bucket,
+# `receipt-intake`, carrying an 8 MiB file-size limit and an allow-list of the
+# six formats QuickBooks can attach. Two-step uploads go straight to a signed
+# URL and never pass through this server, so the bucket is the only place a
+# too-large or wrong-type write can actually be refused; MAX_STORED_BYTES in
+# src/lib/receipt-intake/intake-core.ts only lets the server reject the object
+# after the fact. It is separate from `secure-docs` because those limits are
+# per-bucket, and because a signed upload URL is a write capability that must
+# not point at the bucket holding signed contracts.
+#
+# Do NOT create it by hand: scripts/apply-receipt-intake.mjs creates it when
+# missing and VERIFIES it when present (it needs SUPABASE_URL and
+# SUPABASE_SERVICE_KEY in the environment, and exits nonzero if the bucket
+# exists with a different limit, MIME list, or public flag).
+#
+# Shadow mode. UNSET or "true" = dry run: rows are read, deduped and routed, and
+# NOTHING is booked. Set to the literal "false" only at cutover.
+RECEIPT_INTAKE_DRYRUN=
+# The instant the Apps Script stopped booking (ISO 8601). Written at the flip to
+# forwarder mode; the first live worker pass uses it to split the shadow backlog
+# into "v1 already booked this" and "nobody booked this". With it unset the
+# cutover refuses to touch either side. Can also live in the `cutoverV1StoppedAt`
+# AutomationSetting row, which takes precedence.
+CUTOVER_V1_STOPPED_AT=
 # Payroll period configuration (src/lib/payroll-config.ts). ALL OPTIONAL — the
 # built-in defaults are shown, and they are DEFAULTS PENDING JUSTIN'S DECISION
 # (Phase 5 spec section 7, risks 2 and 3), not settled policy. Not secrets.

.github/workflows/ci.yml

@@ -91,6 +91,32 @@ jobs:
       # The focused integration regression deliberately drifts the disposable
       # database's function and trigger after proving the checker recognizes
       # the production snapshot. It therefore runs last in this job.
+      # The receipt-intake claim transaction against a REAL Postgres. The rest
+      # of that feature's suites mock every DB call, so the SQL — a void
+      # function read through $queryRaw, a claim that behaves differently than
+      # its mock — is the one part they cannot see.
+      - name: Receipt-intake claim + advisory locks against real Postgres
+        run: npx tsx --test tests/receipt-intake-claim-db.test.ts
+        env:
+          RECEIPT_INTAKE_DB_TEST_URL: postgresql://probuild:probuild@localhost:5432/probuild_migrations
+
+      # THE APPLY SCRIPT ITSELF, run end to end the way production will run it.
+      # Its exported helpers are unit-tested and its statement list is replayed
+      # by the DB-gated suite, but main() is executed by nothing else: not the
+      # flag parsing, not the identity gate, not the statements running in order
+      # against a real server, not the second run being a genuine no-op. It
+      # builds two databases -- one pre-Phase-1, and one carrying the OLD
+      # Phase-1 table with DEFAULT 'RECEIVED' so the additive upgrade and the
+      # state-default repair are exercised -- and asserts both end up matching
+      # what the committed migration produces.
+      #
+      # `--target ci` inside the driver: the ambient URL, no production baseline
+      # or project-ref check, and a refusal if that URL looks like Supabase.
+      - name: Apply script end-to-end against real Postgres
+        run: node scripts/ci-apply-receipt-intake-e2e.mjs
+        env:
+          APPLY_E2E_SERVER_URL: postgresql://probuild:probuild@localhost:5432/postgres
+          APPLY_E2E_DB: probuild_apply_fresh
       # Two REAL connections contending on a User row. Every other concurrency
       # proof in the suite is an injected sequence, which shows the branch exists
       # but not that PostgreSQL serializes the way the code assumes. Runs BEFORE
@@ -500,13 +526,26 @@ jobs:
       # against the throwaway DB — so unlike the provider secrets above it's a
       # literal here rather than a repo secret (there's nothing to rotate).
       DEPOSIT_INGEST_SECRET: "e2e-ci-deposit-ingest-secret"
+
+      # Shared secret for the Receipt Pipeline v2 intake endpoint
+      # (src/app/api/receipts/intake/route.ts). Same reasoning as
+      # DEPOSIT_INGEST_SECRET above: nothing external depends on this value, it
+      # only gates e2e/receipt-intake.spec.ts against the throwaway DB, so it is
+      # a literal rather than a repo secret. The spec's "env var unset" case is
+      # a unit test (tests/receipt-intake-auth.test.ts), not this job.
+      RECEIPT_INTAKE_SECRET: "e2e-ci-receipt-intake-secret"
+      # The archive mirror's key is DELIBERATELY different — the specs assert
+      # that cross-use between the two capabilities is a 403.
+      RECEIPT_ARCHIVE_SECRET: "e2e-ci-receipt-archive-secret"
+
       # The deposit sweep's live-apply switch (src/lib/deposit-sweep.ts). It is
       # OFF by default — booking money on an amount-only match is Justin's
       # decision, not a default — so the e2e cases that exercise the MONEY
       # WRITE need the server under test configured the way a live deployment
       # would be. Everything here runs against the throwaway CI database with
       # QuickBooks mocked (E2E_QBO_MOCK), so no real money can move.
       DEPOSIT_SWEEP_LIVE_APPLY: "true"
+
       # Forces the Stage A daily-log task matcher (daily-log-task-match.ts) onto
       # its deterministic keyword fallback instead of calling Gemini, so
       # time-suggestion.spec.ts's Stage A end-to-end test is reproducible in CI.