feat(worker): atomic at-most-once settlement worker (A03)

[kapustazh]

Summary

Milestone A03 — Atomic At-Most-Once Worker (milestones/coder-a/A03-atomic-worker.md):

• Implements atomic compare-and-set (CAS) submission ownership claimSubmission (READY -> SUBMITTING) committing transaction before calling external settlement port.
• Implements completeSubmission: persists confirmed settlements to COMMITTED, terminal failures to FAILED_SAFE, and uncertainty/timeout outcomes to UNKNOWN with enqueued reconciliation job.
• Implements @oneshot/worker package (apps/worker) with dual runner modes: Graphile Worker TaskList (createTaskList) and PostgreSQL transactional outbox draining (drainOutboxJobs with FOR UPDATE SKIP LOCKED).
• Adds migration 003_worker_jobs.sql adding submit_settlement task identifier.
• Validates concurrency, failure catalog, and multi-process isolation via parallel worker storm (10 workers) and OS child worker processes (apps/worker/test/child-worker-process.mjs).

Scope and acceptance criteria

• The change is limited to the stated milestone or issue.
• Acceptance criteria are listed and satisfied.
• No unrelated cleanup is included.

Product and security invariants

• Tenant isolation remains fail-closed.
• Sponsor authorization, auditability, and daily caps remain enforced where applicable.
• Recipients cannot modify sponsor controls or access sponsor-only data.
• No secret, token, production identifier, or personal data is committed or pasted into review prompts.
• Any non-applicable invariant is explained below.

Invariant notes:

• 1 intent -> at most 1 settlement: Guaranteed by PostgreSQL atomic CAS claimSubmission and unique constraint on settlements table.
• UNKNOWN never retried blindly: Timeouts and uncertain adapter responses transition state to UNKNOWN and enqueue reconciliation work instead of retry.
• Transaction before effects: Database transactions commit before any external port execution.

Validation

Commands and results:

pnpm install --frozen-lockfile: PASS
pnpm build: PASS
pnpm typecheck: PASS
pnpm lint: PASS
pnpm format:check: PASS
markdownlint-cli2: PASS (61 files, 0 issues)
pnpm test: PASS (9 files, 81 tests)
TEST_POSTGRES=1 pnpm test:integration: PASS (PostgreSQL container integration tests)

Independent review evidence

Gate A — exact candidate tree before push

• Base commit SHA: 64d0a6fb65c3bedce169cc95867595e3f79b90c7

• Candidate tree SHA: 5c1bc4f7101ad5fd796027dc220df5c25a5927cd

• Candidate commit SHA: 7eb82d5009d2e7db8213d60ed38639dfc7a17a28

• Reviewer tool: free-pi-cli

• Reviewer model: glm 5.3

• Verdict: VERDICT: PASS

• Findings or residual risks: None

• The reviewed tree equals the committed tree.

Gate B — exact remote PR head

• Pull request URL/number: feat(worker): atomic at-most-once settlement worker (A03) #18

• Remote head commit SHA: 7eb82d5009d2e7db8213d60ed38639dfc7a17a28

• Remote head tree SHA: 5c1bc4f7101ad5fd796027dc220df5c25a5927cd

• Reviewer tool: free-pi-cli

• Reviewer model: glm 5.3

• Verdict: VERDICT: PASS

• Findings or residual risks: None

• Gate B reviewed the current remote head and matches Gate A's approved tree, or a fresh Gate A was run for the changed tree.

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

Risk and rollback

• Residual risks: None.
• Rollback: Revert PR or rollback migration 003.

[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 failed View logs	oneshot	7eb82d5	Sep 07 2026, 03:36 PM