fix: production hardening and runtime documentation

[SuPuHe]

Summary

Hardens the current OneShot release candidate in three focused commits:

• Adds shared PostgreSQL-backed API rate limiting with configurable fail-closed admission and completes the worker Cloud Run configuration contract.
• Narrows the Privy raw-signing fallback to the intended relay-authorization boundary, adds regression coverage for generic authentication failures and policy denials, and hardens PostgreSQL Testcontainers teardown.
• Reconciles runtime, deployment, architecture, qualification, P5, and environment documentation with the current implementation.

Scope and acceptance criteria

• The change is limited to the three requested production-hardening parts.
• Part 1 committed as eb232ec4ee1f331d9b5367e556b971e93e7066f0.
• Part 2 committed as c9f41c8f5031b5b1464ec415601801c41244afb3.
• Part 3 committed as db6c046cdf588bf344a247d9019b4782ef2e8b36.
• No unrelated cleanup is included.

Product and security invariants

• One intent remains at most one committed settlement; no settlement state machine was changed.
• UNKNOWN remains reconciliation-only and no blind retry path was opened.
• Privy policy denial cannot reach raw broadcast in the new fallback regression coverage.
• Rate-limit store failure fails closed for authenticated POST admission.
• Tenant isolation and sponsor-specific invariants are not applicable to these changes; existing boundaries are unchanged.
• No secrets, tokens, private keys, or sensitive runtime configuration were committed or sent to reviewers.

Validation

pnpm.cmd typecheck: PASS
pnpm.cmd lint: PASS
pnpm.cmd format:check: PASS
pnpm.cmd test: PASS (66 files, 977 tests)
pnpm.cmd --filter @oneshot/api test: PASS (50 tests)
pnpm.cmd --filter @oneshot/storage-postgres test: PASS (8 tests)
pnpm.cmd --filter @oneshot/privy-adapter test: PASS (130 tests)
pnpm.cmd --filter @oneshot/worker test: PASS (39 tests)
npx.cmd --yes markdownlint-cli2@0.18.1 **/*.md #node_modules: PASS (142 files, 0 errors)
PostgreSQL Testcontainers integration: NOT RUN LOCALLY (no Docker/Podman runtime available)

Independent review evidence

Gate A — exact candidate tree before push

• Base commit SHA: c9f41c8f5031b5b1464ec415601801c41244afb3

• Candidate tree SHA: 67e8831f809f1465cc544eb1a305ca8e17d1f848

• Candidate commit SHA: db6c046cdf588bf344a247d9019b4782ef2e8b36

• Reviewer tool: free-pi-cli

• Reviewer model: glm-5.3-flash

• Verdict: VERDICT: PASS

• Findings or residual risks: historical context records retain retired terminology; container-backed integration remains unverified locally.

• The reviewed tree equals the committed tree.

Gate B — exact remote PR head

• Pull request URL/number: #70

• Remote head commit SHA: 9f81beeb0caca700ad0514b750e8422562fb68f0

• Remote head tree SHA: 930e2061b2bf7446d9048261754fae041e298f49

• Reviewer tool: free-pi-cli

• Reviewer model: glm-5.3-flash

• Verdict: VERDICT: PASS

• Findings or residual risks: no blocking findings; request-IP rate-limit granularity behind Cloud Run, migration-fixture version coupling, Graph claim NOT VERIFIED, and manual frontend click-through remain documented.

• Gate B reviewed the current remote PR head and matches Gate A's approved tree.

• Agent policy / repository-policy and all applicable CI checks pass.

Risk and rollback

• Residual risks: PostgreSQL integration requires CI or a local container runtime; API rate limiting uses request IP and route; the Graph sponsor claim remains NOT VERIFIED; manual frontend click-through remains open.
• Rollback or recovery plan: revert the three commits in reverse order; database migration 005 is append-only and the rate-limit table can be left unused after application rollback.

CI follow-up

CI initially reported the combined ESLint and TypeScript job as failed, but the failing step was PostgreSQL integration. The rollback test used synthetic 005_broken.sql after migration 005 became real, so it observed the real schema version instead of testing version 6 rollback. Commit 9f81beeb0caca700ad0514b750e8422562fb68f0 changes the synthetic fixture to 006_broken.sql and checks for absent version 6.

Fresh Gate A for the CI fix

• Base commit SHA: db6c046cdf588bf344a247d9019b4782ef2e8b36
• Candidate tree SHA: 930e2061b2bf7446d9048261754fae041e298f49
• Candidate commit SHA: 9f81beeb0caca700ad0514b750e8422562fb68f0
• Reviewer tool: free-pi-cli
• Reviewer model: glm-5.3-flash
• Verdict: VERDICT: PASS
• Findings: None blocking; synthetic migration version must be bumped again if a real migration 006 is added.

The latest PR head is the Gate A-approved tree. PostgreSQL integration remains a CI-only verification because no local container runtime is available.

Human merge

• A human owner has reviewed the evidence and will perform the merge.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	oneshot	9f81bee	Sep 10 2026, 08:35 PM