feat(expenses): project + phase attribution, tax paid at source (pipeline v2 phase 3)

.env.example

@@ -30,3 +30,42 @@ MCP_SECRET=
 # Bank-ledger automation: keep these separate; the posting-status key is read-only.
 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=

.github/workflows/ci.yml

@@ -66,6 +66,96 @@ 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 phase invariant's PHANTOM hole. Everything else in that suite runs
+      # against a scripted fake, which has no lock manager and so cannot tell a
+      # verdict that holds its rows from one that merely read them.
+      - name: Phase-invariant proof-query lock against real Postgres
+        run: npx tsx --test tests/phase-invariant-db.test.ts
+        env:
+          PHASE_INVARIANT_DB_TEST_URL: postgresql://probuild:probuild@localhost:5432/probuild_migrations
+
+      # The deploy bridge's TRIGGERS. Every other test of them reads the SQL as
+      # text; only a real server can say whether a BEFORE UPDATE trigger
+      # actually keeps an old writer's amount change from leaving a stale tax
+      # classification — or from failing the CHECK constraints outright.
+      - name: Expense attribution compatibility triggers against real Postgres
+        run: npx tsx --test tests/expense-attribution-triggers-db.test.ts
+        env:
+          PHASE_INVARIANT_DB_TEST_URL: postgresql://probuild:probuild@localhost:5432/probuild_migrations
+
+      # The Project/Estimate acquisition order, both ways round. Carries its own
+      # pre-fix CONTROL: the old Estimate-then-Project sequence really does
+      # raise 40P01 against a Project-first editor, so the tests that follow are
+      # measuring the fix rather than an interleaving that never collided.
+      - name: Attribution lock order against real Postgres
+        run: npx tsx --test tests/attribution-lock-order-db.test.ts
+        env:
+          PHASE_INVARIANT_DB_TEST_URL: postgresql://probuild:probuild@localhost:5432/probuild_migrations
+
+      # THE MIXED-VERSION DRAIN WINDOW. An old instance's INSERT is raw SQL that
+      # names neither new column -- a shape today's Prisma client cannot express --
+      # and the fix is a trigger that stamps it and takes the route's advisory lock.
+      # Neither half exists outside a real server.
+      - name: Receipt-ingest drain-window bridge against real Postgres
+        run: npx tsx --test tests/receipt-ingest-drain-window-db.test.ts
+        env:
+          PHASE_INVARIANT_DB_TEST_URL: postgresql://probuild:probuild@localhost:5432/probuild_migrations
+
+      # The backfill's coverage headline against the report it claims to describe,
+      # on one seeded database. A hand-built fixture cannot catch the two readers
+      # drifting apart, because the fixture is written by whoever wrote the code.
+      - name: Backfill coverage parity with the variance report
+        run: npx tsx --test tests/backfill-coverage-parity-db.test.ts
+        env:
+          PHASE_INVARIANT_DB_TEST_URL: postgresql://probuild:probuild@localhost:5432/probuild_migrations
+
+      # An index can EXIST and enforce nothing. A failed CREATE INDEX
+      # CONCURRENTLY leaves the index behind with the right name and
+      # `indisvalid = false`; the planner ignores it, a UNIQUE one guards
+      # nothing, and `IF NOT EXISTS` then matches the name forever. Only a real
+      # server can produce that state, so only a real server can prove the
+      # verifier notices it and rebuilds it.
+      - name: Apply-script index validity against real Postgres
+        run: npx tsx --test tests/apply-script-index-db.test.ts
+        env:
+          PHASE_INVARIANT_DB_TEST_URL: postgresql://probuild:probuild@localhost:5432/probuild_migrations
+
+      # The excise deduction's FILTER, against the real planner. A relation
+      # filter like `{ estimate: { projectId: null } }` compiles to an EXISTS,
+      # so it silently excludes rows with no estimate at all -- the shape
+      # ON DELETE SET NULL creates. Only a real database can answer that.
+      - name: Tax-at-source report filter against real Postgres
+        run: npx tsx --test tests/tax-at-source-report-db.test.ts
+        env:
+          PHASE_INVARIANT_DB_TEST_URL: postgresql://probuild:probuild@localhost:5432/probuild_migrations
+
+      # THE APPLY SCRIPT, RUN FOR REAL (round 46, item 0).
+      #
+      # Every other test in this repo imports the script's CONSTANTS and checks
+      # their text. `main()` -- the part that connects, runs the phases and
+      # VERIFIES the result -- had never executed in CI, and it was broken: the
+      # CHECK-constraint comparison used regexes that do not match Postgres 16's
+      # rendering, so the script exited 1 on a database it had just built
+      # correctly. A deploy blocker no amount of source-text testing could see.
+      #
+      # The driver builds a PRE-PHASE-3 database (the phase-3 migration is moved
+      # aside), so this is a genuine from-scratch apply, then runs pre-deploy,
+      # post-deploy, and pre-deploy again for idempotency.
+      - name: Apply script end-to-end against real Postgres
+        run: node scripts/ci-apply-expense-attribution-e2e.mjs
+        env:
+          APPLY_E2E_SERVER_URL: postgresql://probuild:probuild@localhost:5432/postgres
+          APPLY_E2E_DB: probuild_apply
+
       - name: Prove the blind-spot checker rejects function and trigger drift
         run: npx tsx --test tests/migration-history-blind-spots.test.ts
         env:
@@ -198,6 +288,16 @@ 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