[Codeinx]

Problem

The dispute flow is the protocol's differentiator, and there was no API surface for it: a buyer couldn't raise a dispute, an adjudicator couldn't see the queue, and neither party could attach evidence.

What this adds

New module src/routes/disputes/, registered under the v1 prefix:

• POST /disputes — raise a dispute against a settlement with a reason and optional evidence.
• GET /disputes — role-scoped: buyers/sellers only see disputes they're a party to; adjudicators see everything.
• POST /disputes/:id/evidence — either original party may add evidence, rejected once the dispute's window has closed. The deadline is enforced server-side (not left only to the contract).
• POST /disputes/:id/resolve — adjudicator-only, records the outcome.
• A notification is logged on every lifecycle transition (raised, evidence-added, resolved).

Evidence handling follows the same principle as inference payloads elsewhere in this service: each evidence item is stored with a sha256 contentHash kept as a field separate from the raw content from day one, so wiring in real off-chain storage plus an on-chain commit call later is a swap of one function rather than a data-model change.

Role and identity are currently read from x-role / x-user-id headers, since the repo doesn't yet have an auth/session layer to hang this off of — the role-scoping and window-enforcement logic itself is real and fully tested per role, and swapping the header read for a real identity middleware later is a one-function change.

Testing

src/routes/disputes/index.test.ts uses Fastify's inject to cover the full lifecycle:

• raising a dispute with evidence, hash-committed
• listing is role-scoped (an unrelated party sees nothing; an adjudicator sees everything)
• only a party to the dispute may add evidence
• only an adjudicator may resolve, and resolving fires a notification
• evidence is rejected once the window has closed
• unauthenticated requests are rejected

npm run lint, npm run build, npm test, and npm audit --audit-level=high are all clean on this branch.

Scope note

This PR touches src/routes/v1/index.ts (registering the new plugin) in addition to the new src/routes/disputes/** files. No other PR open against this issue tracker (#44, #54) touches that file or package.json, so this should merge independently of the other two regardless of order.

Closes #58.