← WI-009 HITL file upload + review (e.g. S-corp proposal -> Paul review) ★ Live Board · Overview WI-011 Provider gateway + adapter boundary — core (registry, capability, schema+prompt compiler, image prep, ProviderAttempt) →

WI-010 · Platform & Contracts · llm-io-contracts

Freeze scan I/O contract schemas + versioning

done P0 high risk   Owner: Paul   100% · 4/4 tasks complete

Gates: P1 Requirements: REQ-CONTRACT-001 REQ-CONTRACT-005 REQ-CONTRACT-006 REQ-CONTRACT-007 REQ-CONTRACT-009 Updated: 2026-06-22

At a glance

CodeWI-010
PhasePlatform & Contracts
Order10 of 93
Story points13
Primary surfaceContract schemas / spike — no production code yet
Retires—
Depends on—
BlocksProvider gateway + adapter boundary — core (registry, capability, schema+prompt compiler, image prep, ProviderAttempt), Output validation core — trust pipeline (stages 0–9, issue/receipt model, rule registry, deterministic repair, branded TrustedScanResult), Candidate ranking engine — deterministic features, fixed-point scoring, priority bands, tie-break, explainability, canonical hash, Scan Session & Orchestration — session identity + candidate lineage + next-scan execution, Sprint 4: Vision Contract POC - scan types, watchlists, overlays, appraisal routing, Vision scan service contract and provider adapter scaffold
Evidence
packages/scan-contracts/schemas/p1-scan-contract.schema.json; packages/scan-contracts/fixtures; packages/scan-contracts/scripts/validate-p1-contract.mjs

Goals

Freeze the model-facing I/O contracts so every vision feature builds on stable shapes — request envelope, per-scan_type result schemas, versioning, shared enums, and coordinates (vision-scanning-spec §5-10, 28).

Spec document

P1-scan-io-contract → · source ↗

Implementation — what to build

Spec (docs/specs/P1)

  • Canonical request + result envelopes; 7 discriminated scan-result schemas; coordinate/evidence/identity/watchlist/next-scan primitives; 4 independent version dimensions (envelope, scan-behavior, result-schema, supporting-data).

Artifacts (spec §17)

  • JSON Schema (canonical) for envelopes + shared primitives + 7 scan-result schemas + enums/reason-codes + taxonomy + watchlist reference; generated TS types.

Tests (spec §18)

  • Golden valid/invalid fixtures + deterministic schema validation; coordinate round-trip; semantic-invariant suite (per-scan-type prohibited/required); versioning + cross-image identity tests. Keyless (no live provider).

Freeze (spec §19/§20/§21)

  • Resolve Open Questions §21 (E8/comps/scan-session/taxonomy/version-capture), then freeze so P2/E build against it; Spine pairs once P1+P5+P6 freeze.

Gap-resolution expansion (D26, 2026-06-20)

  • Acceptance guard: no invented comparables; the request envelope carries an explicit supplied-comparables channel for appraisal_value (guards G6).

Checklist

  • ✓ Author docs/specs/P1 schemas: request envelope + 7 discriminated scan-result schemas + shared primitives
  • ✓ Publish canonical JSON Schema + generated TS types; shared enums/reason-codes + taxonomy/watchlist reference
  • ✓ Golden valid/invalid fixtures + coordinate round-trip + semantic-invariant + versioning tests (keyless)
  • ✓ Resolve §21 open questions (comps channel, cross-scan identity defer, model_priority_hint) then freeze

Gates & testing

  • ✓ P1 Scan I/O contract schemas and versioning are frozen: request envelope, per-scan_type result schemas, scan_version/result_version, shared enums, and the normalized 0-1000 coordinate contract.
    CODE TEST

Requirements

  • REQ-CONTRACT-001 accepted Scan I/O contract schemas and versioning must be frozen before vision features build on them.
    Done when: Request envelope, per-scan_type result schemas, scan_version/result_version, shared enums, and the normalized 0-1000 coordinate contract are specified and frozen.
    Spec: docs/CC-Analysis/trovesnap-vision-scanning-spec.md (5-9, 28)
  • REQ-CONTRACT-005 accepted All seven scan types must be defined as versioned, UI-triggered contracts.
    Done when: table_hunt, room_scan, item_scan, mark_scan, condition_scan, appraisal_prepare, appraisal_value each have input/output schemas, rules, and acceptance criteria; UI actions resolve to scan_type + version.
    Spec: docs/CC-Analysis/trovesnap-vision-scanning-spec.md (4, 11-17)
  • REQ-CONTRACT-006 accepted Watchlists must be a separate, versioned, tenant-scoped input whose match IDs are restricted to those supplied in the request.
    Done when: Watchlist entries (query/aliases/makers/clues/priority), the allowed match types, and the restriction that result watch_id values must be supplied IDs are enforced.
    Spec: docs/CC-Analysis/trovesnap-vision-scanning-spec.md (8)
  • REQ-CONTRACT-007 accepted Shared enums and the category taxonomy must be canonical, versioned inputs the model is constrained to.
    Done when: identity_certainty, visibility, condition, priority, appraisal_state/readiness, reason codes, next_action, overlay_state, and the category roots/hierarchy are defined; the profile compiler can send relevant subsets.
    Spec: docs/CC-Analysis/trovesnap-vision-scanning-spec.md (9-10)
  • REQ-CONTRACT-009 accepted Scans must store both raw and normalized results with full provenance.
    Done when: scan_record persists scan/version, input image ids, watchlist/taxonomy versions, provider+model, prompt/schema hashes, result refs, and metrics; raw + normalized results both stored.
    Spec: docs/CC-Analysis/trovesnap-vision-scanning-spec.md (5, 22)

Verify (done when)

The §17 schema package + shared vocabulary + golden valid/invalid fixtures + contract tests are merged and pass; all seven scan types have concrete, separately-versioned result schemas with 0–1000 coords, evidence/claim/unknown distinctions, retake/partial/warning states, and watchlist + next-scan + appraisal contracts — consumable by P2/P3/P4/UI/storage/appraisal without inventing fields (spec §19/§20). Open Questions §21 resolved before freeze.

Cost triggers

No paid API / infra spend triggered by this item.

Status & editing

done   Sprint: P&C Wave 1: Foundations

Edit status / sprint on the ★ Live Board → — changes are logged live with who / when / why.

Human-in-the-loop

No human tasks linked.

Findings

  • Spec is docs/specs/P1-scan-io-contract.md (frozen-quality draft); §17 = required artifacts, §18 = test plan, §19/§20 = acceptance.
  • Keyless deterministic tests only — no live provider needed for P1.
  • P1 Section 17/18 require a real contract artifact package, not just a doc update.
  • The repo has no existing JSON Schema validator dependency, so the P1 test runner should stay keyless and dependency-free unless the project later adopts one.
  • appraisal_value now has an explicit comparables input channel and rejects unsupplied comparable IDs.
  • Cross-scan identity remains deferred to P10; P1 candidate IDs are result-local and provisional.
  • Candidate priority is replaced with model_priority_hint; P4 owns authoritative ranking.
  • The suite is keyless and deterministic, satisfying the no-provider requirement for P1.
  • No provider credentials or live APIs are required for P1.
  • The remaining tracker warnings are the known owner/coverage warnings outside this WI-010 scope.
  • Future agent use of tracker:promote should pass --actor Codex or --actor Claude explicitly.

Concerns

None recorded yet.

Risks

None recorded yet.

Tech debt

None recorded yet.

Tools used

  • Shell — read AGENTS.md, llminterchange.md, session-handoff.md, status.json, latest closed spec-gap round, decision-log.md, CHANGELOG.md, and P1/P9 specs
  • Edit — added packages/scan-contracts canonical P1 JSON Schema bundle, generated TypeScript types, fixtures, validator, coordinate helpers, and tests
  • Edit — updated docs/specs/P1-scan-io-contract.md to resolve Section 21 (comparables channel, P10 identity deferral, model_priority_hint)
  • Edit — opened Codex coordination deliberation for WI-068 P9 floor ID/idempotency/correlation convention
  • Shell — ran P1 type generation and keyless contract fixture validation
  • Shell — ran Node test suite for coordinate round-trip, comparables channel, scan echo, and model_priority_hint guards
  • Shell — ran npm run contracts:p1 (generated types, validated fixtures, 5 Node tests passed)
  • Shell — ran npm run tracker:check in apps/web (0 errors / 18 warnings)
  • Shell — regenerated tracker/spec/item pages with build-sprint-tracker.mjs
  • Shell — ran npm run tracker:promote -- WI-010 --to done --apply; Live Board moved in_progress -> done, but audit actor used script default Claude because --actor Codex was omitted

Files & artifacts

Update log

Update · 2026-06-20 · Wave 1 kickoff — P1 scan I/O contract

Started as part of P&C Wave 1: Foundations (D36). Codex is building this (the most self-contained, fully-specced contract). Owner Paul. Builds on the WI-068 floor conventions where applicable; no other dependencies.

  • Spec is docs/specs/P1-scan-io-contract.md (frozen-quality draft); §17 = required artifacts, §18 = test plan, §19/§20 = acceptance.
  • Keyless deterministic tests only — no live provider needed for P1.
Update · 2026-06-20 · Codex baseline pass - schema package implementation started

Read AGENTS.md -> llminterchange.md -> session-handoff.md -> status.json -> latest closed spec-gap round -> decision-log.md, then inspected P1/P9 specs and existing repo tooling. Building P1 as a keyless contract package with canonical JSON Schemas, generated TypeScript types, fixtures, and deterministic tests. WI-068 owns the broader ID/idempotency/correlation convention, so WI-010 will not invent operation/correlation fields beyond the P1 scan request_id already in the spec.

CheckResult
Open deliberationsNone at start of work
P1 scopeJSON Schema + fixtures + semantic tests; no provider calls
P9 coordinationDo not define competing idempotency/correlation convention; consume after WI-068 lands
Keyless requirementUse deterministic local Node tests only
  • P1 Section 17/18 require a real contract artifact package, not just a doc update.
  • The repo has no existing JSON Schema validator dependency, so the P1 test runner should stay keyless and dependency-free unless the project later adopts one.
Update · 2026-06-20 · P1 contract package implemented and keyless tests passing

Implemented the P1 schema package as a standalone packages/scan-contracts module. JSON Schema is canonical; TypeScript types are generated. The package includes valid/invalid golden fixtures, 0-1000 coordinate helpers/tests, semantic invariants for each scan type, explicit input.comparables[] for appraisal_value, and the model_priority_hint rename so P4 remains authoritative for ranking. No provider calls or secrets are used.

VerificationCommandResult
Type generationnode packages/scan-contracts/scripts/generate-types.mjspass
Golden fixtures + semantic invariantsnode packages/scan-contracts/scripts/validate-p1-contract.mjspass
Node contract testsnode --test packages/scan-contracts/test/p1-contract.test.mjs5 passed
P9 conventionopen-codex-2026-06-20-wi010-p9-floor-coordination.mdping opened; no competing convention invented
  • appraisal_value now has an explicit comparables input channel and rejects unsupplied comparable IDs.
  • Cross-scan identity remains deferred to P10; P1 candidate IDs are result-local and provisional.
  • Candidate priority is replaced with model_priority_hint; P4 owns authoritative ranking.
  • The suite is keyless and deterministic, satisfying the no-provider requirement for P1.
Update · 2026-06-20 · Final verification - P1 npm wrapper + tracker gate

Ran the exact npm wrappers after the direct keyless Node checks. npm run contracts:p1 generated the TypeScript types, validated all golden fixtures/semantic invariants, and passed the Node test suite. npm run tracker:check passed with 0 errors and the existing 18 out-of-scope warnings. Regenerated tracker pages after updating WI-010 evidence.

CommandResult
npm run contracts:p1pass - fixture validation passed; 5 Node tests passed
npm run tracker:checkpass - 0 errors / 18 known warnings
node scripts/build-sprint-tracker.mjspass - regenerated tracker/spec/item pages
  • No provider credentials or live APIs are required for P1.
  • The remaining tracker warnings are the known owner/coverage warnings outside this WI-010 scope.
Update · 2026-06-20 · Live Board promoted - audit actor caveat

Moved WI-010 on the Live Board with tracker:promote after the git/status work was complete. The live row moved in_progress -> done. Caveat: the promote script defaults --actor Claude; I omitted --actor Codex, so the audit event label says Claude even though Codex ran this work. I did not create extra status churn to rewrite the audit trail.

Live actionResult
npm run tracker:promote -- WI-010 --to done --reason "WI-010 P1 scan I/O contract package implemented; keyless contract suite and tracker:check pass" --applyLive Board: in_progress -> done
Audit actorRecorded as Claude by script default; should be read as a tooling caveat for this event
  • Future agent use of tracker:promote should pass --actor Codex or --actor Claude explicitly.