Docs

justin-napolitano/jayburd-bookkeeping / docs/runbooks/plaid-85-verification.md

Plaid lifecycle and failure verification

Synced 2026-11-04 · Updates are made in the source repository.

Plaid lifecycle and failure verification

Status and boundary

Issue #85, parent #88; lease PLAID-88-SWARM-20261022T1540Z, lane VERIFY85. Base 52ef702. Tests and this proposal only; no runtime, SQL, HTTP, dependency, cloud, provider credential or financial contract change. No provider calls. Synthetic evidence cannot qualify the hosted application or close #85/#88.

Stage ledger

  1. Read repository index, bibliography, #85/#86 acceptance, matrix T04–T09 and R01–R03, runner/runtime contracts, corpus independence rules and existing acquisition/sync/providerflow source. Inspected actual assertions rather than treating suite names as proof.
  2. Re-read official Plaid transaction states pending/posted and testing sections, and Transactions errors pagination mutation and Item-limit sections, 2026-10-22. These are P88-11/12 in the canonical source register. Relevant sections were read; no unseen Dashboard or institution behavior claimed.
  3. Added one fixed lifecycle oracle through original loopback HTTP, the actual Plaid adapter/decoder, restricted SQL worker and disposable PostgreSQL29. Separate literal expected facts are not generated by the decoder or fixtures.
  4. Added second-page rate-limit, unavailable-institution HTTP503, malformed-body raw-byte-overflow and network-timeout faults after a known completed publication.

Current evidence

make acquisition-test PASS with cached pinned Docker images, local Go1.26.5 and external modfile (tracked Go1.26.10 unchanged). Log: /private/tmp/jayburd-85-acquisition.log. Initial sandbox Docker access denial was environmental; approved rerun reached the actual synthetic database.

TestExact assertionsMatrix coverage and limits
TestAcquisitionLifecycleOraclePending removal and posted replacement across two pages; changed amount/date/name; explicit lineage; null-linked new posted transaction; disappearing authorization hold; added/modified/removed; exact magnitude, original numeric lexeme, currency, date, direction, state and revision; corrected API review projection; C1 remains visible until whole update completes; receipt replay performs no fetch; zero journals and outbox messages.New synthetic T04/T05/T07/R02/R03 evidence. API projection uses the actual restricted API SQL login and fictional actor; no trusted browser identity or hosted API authentication proof. Unmatched transaction is deliberately not inferred to be a replacement. Existing namespace overlap policy remains visible in expected states.
TestAcquisitionPageFaultPreservesPublicationFive independent second-page faults leave C0, original observation/revision and zero journal/outbox counts unchanged; exactly three total provider calls, no automatic refetch.New synthetic R01/T07 evidence. HTTP503 is a simulated unavailable institution, not a real institution test. Network timeout uses a shortened 250ms test-only HTTP client deadline against a stalled loopback response; production ten-second configuration is unchanged. It does not test a real institution or worker restart.

Existing tests separately exercise committed response loss at claim/stage/complete, whole-loop mutation restart, permission revocation, expired leases, SQL bounds, posted evidence immutability and wakeup concurrency. Their source was inspected; this branch does not rename them as the original issue's broader acceptance names. These deterministic scenarios are not #86 seeded sequence/fuzz proof.

Remaining work

Hosted T04–T09/R01–R03 remain open. Run provider Refresh to induce dynamic lifecycle; another local sync is not the stimulus. Compare named-account custom fixtures, not only UI counts. Independent hosted equality and zero-journal proof need the scoped capability below before execution. Reconstruction of an entire runner/evidence adapter after process loss, and original #85 trigger matrix need final assertion-level inventory; no claim that all are closed here.

Proposed runtime comparator — review required, not implemented

Question: obtain R02/R03 evidence without exposing source records or granting a worker general ledger access. Proposed owner: #88/#85, coordinator review pending. This is an operational verification protocol, not an ISO20022 financial message; existing proprietary Plaid API2020-09-14, ISO4217 currency and date assessment apply. No new accounting or conformance claim.

Prefer a separate, explicit, Sandbox-only one-shot verifier identity over an API route or widening sync worker privileges. New forward migration required before implementation; immutable merged migrations stay untouched. It gets EXECUTE only on two new fixed security-definer functions, no table SELECT or posting grants, no role membership in owner/API/sync/publisher. Validate session/current identity, NOINHERIT and forbidden mixed memberships exactly as existing runtime probes. No bypass through caller-supplied actor IDs. Current authorization uses a separately owner-installed finite mandate binding verified service login, exact entity/book/source/Item/account/namespace, expected completed generation and expiry; recheck at every call. Revocation/expiry/foreign scope fail closed. Never accept arbitrary SQL, DSN, object path, raw payload or unrestricted account list.

  1. verification_snapshot(mandate_id) executes a single read-only snapshot and returns only bounded counters/revisions: source revision, current generation, completion state, all-book journal count and journal-posting outbox count, plus a random verification nonce. It does not return transaction fields. Before/after measurements must pin the same mandate and book. Counts alone cannot establish causation under concurrent manual posting: require an explicit isolated test window and record that limitation. It must neither persist the receipt nor enqueue an event; output is collected as a redacted run artifact.
  2. verification_compare(mandate_id, expected_fixture) accepts at most the existing 1,000-change/2MiB bound, rejects duplicate fixture identities, and compares the complete authorized source projection, revisions and exact provider lexemes, currency IDs/codes, dates, state, direction and pending lineage against an independently authored fixed fixture. Include retained history when expected, not only the latest pointer. Check review evidence through its authorized projection as well. Return total and per-field mismatch counts, complete-set equality and fixed error codes only; never values, IDs, names or hashes that could disclose small amounts. The fixture is ephemeral input, never logged, persisted, retained in a command, or echoed. Secret/raw-provider payloads are not an allowed fixture source. For hosted use start with named custom synthetic transactions, independently specified before provider injection.

The CLI must be inert by default and require explicit operation, manifest and mandate; finite timeout, one attempt, no automatic provider sync, no credential file/environment scanning and no default cloud operation. Bind redacted results to reviewed image/build, schema version, manifest digest and observation time. Snapshot race/expired mandate and unknown outcome fail evidence, never silently retry as a pass. No mechanism may authorize a posting or mutate source data.

Acceptance before hosted execution: restricted-role disposable PG tests deny wrong/revoked/expired mandate, foreign entity/book/source, mixed roles, oversized fixtures and unknown fields; demonstrate unit/date/state/lineage mismatch detection and missing/extra/duplicate identities; demonstrate no sensitive outputs; unchanged journal/outbox zero for acquisition and replay. Trigger a controlled synthetic journal addition in the disposable DB to prove counters detect it. Production mandates must be rejected. Retain failed comparator evidence as fixed reasons.

Alternative: owner-run arbitrary SQL/dumps are quicker but violate the narrow runtime/privacy boundary. Reusing worker authority for ledger reads couples acquisition to posting evidence and unnecessarily expands its privilege. A public comparison endpoint expands sensitive input and authorization surfaces. Deferred one-shot scoped functions add migration/review work but give inspectable least privilege and exact reproducible proof. Neither this proposal nor source review approves that migration or authorizes hosted execution.

PR handoff

Tests only; migration impact none. Links #85/#88; does not close #86 or hosted acceptance. Core and additional integration gates are recorded below after running.

Final local gates PASS: make check test build; make acquisition-test (including all five second-page faults); make sync-state-test provider-flow-test ledger-test (including restore replay). No skips/failures in the disposable integration logs. Core synthetic listeners required approved execution after the initial sandbox bind denial. Logs: /private/tmp/jayburd-85-core.log, /private/tmp/jayburd-85-acquisition.log, /private/tmp/jayburd-85-integrations.log. Staged runbook guard and git diff --check run before commit. No browser/API wire contract changed, so browser build/recovery gates are not added for these tests.

Follow-up: signed socket to actual restricted SQL

Coordinator requested the missing composition proof after independent review. Dependency commits f79e3ea (bounded host) and 2422e68 (runtime identity contract) were applied before this test-only follow-up; they are not implemented again here. Extended TestProviderEnrollmentAcquisitionFlow rather than adding another harness: real ephemeral loopback listener → maintained-library synthetic ES256 signature → actual verifier → Host.NewSQL → synthetic_webhook login → PostgreSQL29 receipt and wakeup → existing acquisition runner → review evidence. The script adds only a fictional webhook login to its disposable database. No live DSN or provider access.

make provider-flow-test PASS, log /private/tmp/jayburd-85-webhook-flow.log: invalid signature and altered bytes each return401 with no receipt/generation change; exact signed delivery and duplicate each return204 but persist one receipt, one webhook wakeup and one generation increment (1→2). Existing acquisition then publishes two exact cents observations and replays without another fetch, with zero journal entries and journal outbox rows. Disconnect makes the same valid signed replay return403 and leaves receipt/generation counts unchanged. Synthetic HTTP identity remains the existing test adapter; this proves listener/signature/ SQL composition, not provider enrollment, hosted IAM, proxy timing or delivery. Core checks and staged guard recorded before the follow-up commit.

Follow-up core make check test build PASS, including race tests for the bounded host, log /private/tmp/jayburd-85-webhook-core.log; provider-flow proof above PASS without skips. This follow-up adds no production implementation or migration.