feat: multi-actor concurrency harness for race-prone mutations (#218)

[OkeyAmy]

Closes #218

What this delivers

A multi-actor concurrency harness for race-prone mutations, plus harness-driven tests against the two critical writes with the most exposure: the idempotency claim that guards every idempotent write, and the approval-intent claim that guards maintainer actions. All four scenarios from the acceptance criteria — concurrent actors, duplicate submissions, stale versions, retry storms — are covered as invariant tests, with an operator guide covering edge cases, failure modes and recovery.

The harness — src/testing/concurrency/

Sits alongside the existing chaos/ and fault-injection/ helpers:

• runConcurrently releases every actor through one start barrier: each operation's synchronous prefix runs before any actor can complete, so the race actually races. Staggered Promise.all starts never overlap, and a broken claim path silently passes.
• duplicateSubmissions and retryStorm model the two production shapes: identical payloads arriving at once (double-clicks, proxy replays) and one client hammering while the original is still in flight.
• Reports classify every outcome (status, exception class, message), so assertions read as invariants — "exactly one winner", "every loser saw 409", "the handler ran once" — rather than as microtask ordering. Rejections are captured as data; Promise.all would hide all but the first.
• Deterministic by construction: no sleeps, no jitter, no probability. The barrier itself is under test — if it degrades, races everywhere silently stop racing.

What the harness caught (all fixed here)

1. Unique-index losers surfaced as raw 500s. Both the entity comment and the service docs promise concurrent duplicates get a 409 — but IdempotencyService.execute never handled the INSERT collision: the loser's SQLSTATE 23505 went straight to the client. The claim is now a bounded loop that catches the violation, re-reads the winner's record, and either replays it, rejects with 409, or — the winner's attempt having failed — claims the key itself.
2. Cancel and expiry could clobber live executions. ApprovalIntentService.cancel and expireIntent did read → check → unconditional save: a withdrawal racing an in-flight execution rewrote executing rows to cancelled, and two racing cancellations could both "succeed" and double-write evidence. Both now claim with UPDATE ... WHERE status = 'proposed' and answer 409 with the observed status when the claim is gone — the discipline execute already used. Cancel-vs-execute mutual exclusion is now structural.
3. Two spec fakes were silently broken. The idempotency fake's remove() ignored arrays (TypeORM accepts both, and purgeExpired passes one — the purge test never deleted anything), and the interceptor harness lacked getHandler/getClass (all seven tests died on a TypeError). That suite went from 10/18 to 18/18.

Known limitation, documented rather than papered over

Intent proposal dedupe is sequential-strength only: genuinely concurrent identical proposals can both persist, because the table has no live-row uniqueness on fingerprint. Duplicates stay single-use, audited and cancel-able; docs/CONCURRENCY_HARNESS.md records the hardening path (partial unique index + conflict mapping) as follow-up rather than smuggling a migration into a test-focused PR.

Scenario coverage

Scenario	Target	Pinned invariant
Concurrent actors	intent claim	one proposed → executing winner, one operation run, losers 409
Duplicate submissions	idempotency	handler runs once; losers 409 — never a raw 500
Stale versions	intent + idempotency	state re-read from the store; stale writes lose or replay
Retry storms	in-flight and post-terminal	409s throughout; work never runs twice
Withdrawal vs execution	cancel racing execute	exactly one side effect; the row agrees with which

Failure modes and recovery (in the guide)

Why 409 storms from retry loops are correct responses; the two stuck-row modes with SQL recovery recipes — idempotent in_progress rows (TTL expiry + purgeExpired, early-release DELETE) and intents stuck executing (... AND receipt IS NULL guard so a completed execution can never be faked into failed). Rollback: no schema changes anywhere in this PR — both fixes are code-only and backward compatible with every existing status code and response shape.

Verification

14 suites / 122 tests across the affected surface, all green (harness self-tests, idempotency 18+5 concurrency, intents 53+4 concurrency, plus migrations, quota and admin-role suites). The concurrency suites were run three times back to back with identical results. npx tsc --noEmit reports nothing for any file in this PR. The intent-side specs build on the approval-intent foundation that landed in #377/#378.

[github-actions]

Code Review & Auto-Merge — @dorismaduegbunam 🚀

Thank you @OkeyAmy for your contribution!

• PR Title: feat: multi-actor concurrency harness for race-prone mutations (Trellis API: Build multi-actor concurrency harness for race-prone mutations #218)
• Author: @OkeyAmy
• Branch: feat/218-concurrency-harness -> main
• Linked Issues: Closes Trellis API: Build multi-actor concurrency harness for race-prone mutations #218
• Status: Approved & Merged into main.

Verified code changes and repository requirements. Merging pull request.