Pin the telltale wire contract (consumer side)

[adbarc92]

telltale declares this payload in src/read.ts (TelltaleIssueDTO / IssuesResponse); this repo declares it again in feedback.ts (TelltaleIssue / FeedbackIssuesResponse). They agree today, field for field — and nothing made them keep agreeing. Either side could add, rename or drop a field with both suites green and the wire broken. That is finding 2 of the 2026-08-31 integration audit, and the gap SYSTEM-TEST-PLAN.md records as "no contract test between any two stages."

Mechanism

The contract JSON is vendored byte-for-byte from NEXUS docs/contracts/, where it is documented. telltale vendors the same file and pins the same hash. Moving the contract for one side leaves the other side's constant stale and red — that duplication is the mechanism, not redundancy. A shared package would give the same guarantee only if both sides upgraded, and nothing forces an upgrade.

Two independent checks, deliberately not one:

Layer	Catches
runtime (vitest)	contract's canonical SHA-256 moved; TelltaleIssue's key set ≠ contract's, exactly — an added field fails as loudly as a removed one
compile time (npm run check)	Record<keyof TelltaleIssue, true> makes tsc fail if the interface gains or loses a field, before the suite even runs

Hashing is over the canonical JSON, not raw bytes — a byte hash would fail spuriously the first time someone checks the file out with CRLF.

Proved to fail before being kept

A verification that cannot fail is not verification, so both halves were driven red on purpose:

contract gains a `severity` field        →  2 of 5 red (hash freeze + key set)
test declares a field the interface lacks →  tsc: 1 ERROR, 'severity' does not exist
                                             in type 'Record<keyof TelltaleIssue, true>'
reverted                                  →  22 files / 159 tests green
                                             check: 357 files, 0 errors

Suite went 154 → 159. No existing test changed.

Scope

Consumer side only. The producer-side twin in telltale is written but not yet opened — that repo had an active working session in it at the time.

🤖 Generated with Claude Code