Fix pagination clamping, snapshot error envelopes, and the missing idempotency store (#1318, #1319, #1322)

[Max-Owolabi]

Fixes #1318, #1319, #1322.

What this changes

Six commits, in dependency order.

1. a36865fa — #1318 / #1319 / #1322

• GET /receipts clamped limit with Math.min(parseInt(...), 100), so
  limit=abc became NaN and limit=-5 stayed negative. Both reach Prisma as
  take and 500 the request instead of serving a valid page. Now routed through
  clampLimitNumber with an explicit RECEIPTS_PAGINATION_CONFIG.
• The same endpoint ordered by createdAt, which does not exist on
  Transaction (the field is timestamp), so Prisma rejected every query and
  the route could only ever answer 500.
• Snapshot sub-resources that stand in for an HTTP endpoint (referral stats,
  referral code) hand-rolled their error bodies, so impersonation responses
  drifted from the real route. They now go through buildApiErrorBody, and a
  failing sub-resource returns its own error envelope instead of taking down
  the whole snapshot.
• Added endpointResponseContract.test.ts to assert direct versus impersonated
  responses are field-for-field identical for 200/404/500.

2. 76ae7c70 — restore the idempotency store

idempotencyStore was missing, so the transfer, withdrawal and governance
mutations imported a name that did not exist. 71 tests across 6 suites failed
on this. Restores the Redis/NodeCache store, fingerprinting, metrics,
inspection, deletion, clearing and pruning, keeping the existing Prisma
helpers.

3. 58d83a83 — unterminated block in the snapshot differ

diffSchemaShapes()'s currentRequired loop never closed its
if (!(key in current.properties ?? {})) branch, so the closing brace of the
if and of the loop collapsed together and everything after the loop was
parsed inside the if. The compiled module was rejected with
Unexpected token 'export', making apiContractSnapshots.ts unimportable —
so openApiContractTests and issues711 could not even load.

4. 3124f789 — publish the documented error fields

Three error-envelope assertions had no implementation behind them. The admin
webhook contract tests and #634 read the field list from a top-level errors
key plus a stable summary; the 404 contract test reads path from the top
level. sendApiError only ever emitted details, and the catch-all handler
buried path inside it. All three are now optional fields on ApiErrorBody,
emitted only when the caller has the information; details.path is retained.

This commit also corrects the argument order in the #711 snapshot test. It
called diffSchemaShapes(baseline, current) with the live schema as
baseline and the mutated older snapshot as current — the reverse of every
production call site — so it asserted on a field removed message while
searching for now required. Note the neighbouring detects removed fields
test relies on the reversed order, so only the one test is corrected.

5. 64926543 — two type errors the syntax errors were hiding

tsc aborts after a parse error. While apiContractSnapshots.ts and
vaultEndpoints.ts each had a syntax error, the type check stopped there and
reported nothing else; fixing the syntax in commits 1 and 3 let it run to
completion and surfaced two real defects that were already in the tree:

• key in baseline.properties ?? {} parses as (key in baseline.properties) ?? {} because in binds tighter than ??, so the guard threw a TypeError
  instead of falling back to {} whenever a committed snapshot carried no
  properties key. Two occurrences, now parenthesised. This guard decides
  whether a required field is an orphaned reference, so it runs on every diff.
• POST /strategy returns from its 429 cooldown branch but fell through to a
  bare res.status(200).json(...) (TS7030 under noImplicitReturns).

6. 04cdb732 — close WalletTenantAssociation

The model is missing the brace that terminates it, so
model IdempotencyKey { is parsed as a field definition inside it and
prisma validate fails with This line is not a valid field or attribute definition at schema.prisma:678. prisma generate runs in every backend
job, so this failed Backend build and backend-governance before either
reached the source it is meant to check. Same defect shape as commit 3.

Four pre-existing breakages found on main

None of these are part of #1318/#1319/#1322, but the branch could not be
verified without fixing them:

File	Defect	Fixed in
vaultEndpoints.ts	orphaned duplicate router.post('/strategy', ...)	a36865fa
vaultEndpoints.ts	readsLimiter used on /receipts, never imported	a36865fa
apiContractSnapshots.ts	unclosed block + in/?? precedence bug	58d83a83, 64926543
prisma/schema.prisma	WalletTenantAssociation never closed	04cdb732

The first two made src/index.ts fail to compile, so on main no backend
test suite that imports index.ts can run at all — they all abort with
SyntaxError: Unexpected token 'export' or
ReferenceError: readsLimiter is not defined. The fourth stopped
prisma generate, which gates every backend job.

Verification

• npx jest: 92/92 suites, 1347/1347 tests pass on current main
  (711c4332) with the Prisma client regenerated. On main the same suite
  cannot load.
• Confirmed by differential baseline: with only the two vaultEndpoints.ts
  syntax fixes applied to a main checkout, the identical remaining failures
  reproduce, so none of them come from these commits.
• npm run lint: 0 errors (423 pre-existing warnings; 0 errors in the files
  touched here).
• check-migrations.js, check:migrations:canary, snapshots:check,
  check-adrs.js: all pass.
• prisma validate and prisma generate: pass.
• tsc --noEmit: 78 errors, none in the files this PR touches. On main
  the count reads as 2 only because two syntax errors abort the check before it
  can type-check anything; those 78 were already in the tree, mostly
  stale-Prisma-client property errors in exposureGuardrails.ts,
  tenantBoundary.ts and operationalMetrics.ts.

Known failing checks

These are red on main already and are not addressed here:

• Backend build — tsc fails on the 78 pre-existing type errors above.
  Fixing the syntax unmasked them; it did not create them.
• Backend lint + test — fails at the npm audit step (26 pre-existing
  advisories: 19 moderate, 7 high) before lint or tests run, so those steps
  are skipped.
• Backend Test Coverage (Threshold >= 80%) — npm test runs
  jest --coverage and jest.config.js requires 80% global coverage; actual
  global coverage is 67.06% statements / 54.43% branches / 67.64% lines. A
  repo-wide gap, not something these six commits move.

main is also red on Dependency Vulnerability Scan, Frontend Test Coverage, Cargo Security Audit and GitHub Dependency Review, none of
which are affected by backend source changes in this PR.

[drips-wave]

@Max-Owolabi Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits