Verify Identity Contracts

Verify Identity Contracts

When This Fires

Any of these, whether or not the change is UI work:

• an entity is read from more than one data source — a one-shot inventory fetch, the live monitor stream, the archive, or a persisted store key;
• a surface selects, attributes, or names an entity keyed by a backend-produced id;
• an id is persisted and restored across sessions;
• a fixture, factory, or seed supplies ids for any of the above.

Each step names the boundary it guards, and applies exactly when the change crosses it — no more:

So a Core change that only produces ids owes the contract and, if it ships a fixture, fixture realism — not a React hook. Attribution UI that persists nothing owes the contract, the resolution owner, and surface parity — not a migration.

Within its own boundary no trigger is exempt. Attribution UI and fixture work are covered rather than incidental: the contract is what makes an attribution honest, and a fixture is where a wrong contract gets certified as correct.

The motivating failure: the getHardwareInfo inventory and the monitor stream key GPUs in different id namespaces on every platform (ADR 0016). Building a selector on an assumed shared namespace produced eleven review rounds of consequence bugs, all discoverable up front by reading the producers.

1. Write The Contract Table Before Any Consuming Code

Applies to every trigger, in every layer.

For every id the change consumes or produces — including one that only a fixture supplies — read the producing code (or the change itself, when it is the producer) and record: the source, the per-platform id shape, and whether any two sources share a namespace. When they do not, name the join key the sources actually share (typically the reported name) and state where the join must refuse (ambiguity: the key matches more than one entry on either side).

Record it at the smallest durable owner that fits the change, per the decision-preservation rule in AGENTS.md: a focused test or a code comment next to the join for an implementation-level fact, commit or PR context for a change-local why, and an ADR only when the contract itself is an architecturally significant decision. A local change that ships no PR still needs the reading — it does not need paperwork.

Do not infer the contract from fixtures, tests, or frontend types — those can encode the same wrong assumption the change is about to build on.

2. Fixtures Must Reproduce The Namespace Split

Applies wherever the change supplies ids — a Rust test fixture can flatten a namespace exactly as an e2e one can.

A fixture may share one id across two sources only if production does, and its ids take their shapes from the contract table — nvapi:12345 beside 12345 — not two arbitrary strings that merely differ. One that flattens a real namespace difference certifies broken joins: the classic GPU selector shipped non-functional on real hardware while its e2e passed, because GPU_FIXTURES used one id for both sources.

Frontend Consumption

The remaining steps describe how src/ consumes a contract. Each applies only when the change crosses that step's boundary; a change that produces or persists ids in core/ or src-tauri/ keeps the fact where its layer owns it rather than moving it into the frontend.