Epic: harness-neutral USAi model catalog + per-harness emitters #357

Problem

The USAi model catalog (models, context windows, prices, backend routing) lives only inside integrations/isolation/acq-kits/usai-provider/'s opencode.jsonc, produced by a ~900-line sync-usai-models.mjs that fetches feeds, enriches, AND renders the OpenCode block in one pass. No other harness (prime-agent, Codex, Claude Code, Copilot CLI) can read it, so every new harness means a second fetch-and-enrich pipeline or hand-transcribed prices that go stale silently.

Approach (verified incremental + additive; 7/7 consensus)

Split into integrations/providers/usai/: live feeds → catalog.json → one small emitter per harness, guarded by a byte-exact round-trip test that regenerates the LIVE committed opencode GENERATED USAI MODELS block and asserts equality against the real shipped file (not a fixture). This test already caught a real tiered-pricing (context_over_200k) bug.

Phase A (add, zero cutover risk): add the catalog + opencode emitter + round-trip test WITHOUT changing the shipped opencode.jsonc. Phase B (later, gated by the green round-trip test): reduce sync-usai-models.mjs to a thin build-catalog + emit wrapper.

MVP — DONE

All five shipped. Measured at origin/main 665373d: node --test gives 63/63 in integrations/providers/usai, and make test-kits runs that suite in CI (ci.yml, after a pinned setup-node).

• Catalog schema + integrations/providers/usai/ scaffold
• build-catalog.mjs (live feeds → catalog.json; bounded fetch, backend-routed models.dev enrichment)
• OpenCode emitter + byte-exact round-trip test (the load-bearing guarantee)
• prime-agent emitter + no-secret/shape tests
• Generate + commit the prime-agent models.json (consumed by the prime-agent kit)

The round-trip guard is real: it reads both shipped opencode.jsonc copies by relative path, so catalog/config drift fails CI rather than a fixture agreeing with itself.

Phase B — what "deliver OpenCode" actually means now

An OpenCode kit already exists twice over — acq-kits/opencode/ installs the pinned, SHA-256-verified binary and declares the agent: block, and acq-kits/usai-provider/ ships a 20-model opencode.jsonc merged into the global config at startup. So shipping OpenCode is not the gap.

The gap is that the pipeline's render half is not wired to anything. emitters/opencode.mjs has zero non-test callers (3 grep hits, all in tests/emitters.test.mjs). The shipped config is still written by sync-usai-models.mjs, which contains zero references to catalog.json and does its own fetch, vendor classification, matching and rendering. The dependency currently runs backwards: catalog.json records "bootstrappedFrom" the shipped opencode.jsonc. The emitter is a verified-correct shadow of the monolith.

Closing that is the cutover below, and it has a prerequisite that was not previously recorded.

Ordered work (OpenCode first)

• Harden the matcher — the models.dev enrichment matcher scored candidates but never rejected one, so a gateway model absent from the enrichment source was enriched with the nearest same-family model's data (measured: claude_4_5_haiku came out with Opus limits and a 5x price overstatement). PR open: fix(usai-catalog): refuse a near-miss instead of enriching from the wrong model #484.
• Validate feed-controlled strings before the emitter becomes load-bearing. A model's id and name arrive from the feed verbatim and are interpolated into the generated JSONC with no escaping; catalog.schema.json declares both as bare {"type": "string"} with no pattern and no maxLength. This is reported privately via the repository's Security tab per SECURITY.md, and is sequenced before the cutover deliberately: the monolith currently self-corrupts on such input (its name line is derived from the id, so an escaping id mangles both lines), and that accidental mitigation disappears the moment the emitter — which takes name from an independent field — becomes the writer.
• Default-model selection in the catalog pipeline (moved up from "Later" — it is a hard prerequisite, not a nice-to-have). OpenCode's role keys (model, small_model, agent.*.model, compaction.model) sit at lines 364-386 of the shipped config, outside the emitter's marker block (94-357), and catalog.json carries no role data at all. sync-usai-models.mjs owns them via a ROLE_PRIORITY constant. So the emitter cannot produce a complete config until role selection has a home, and the cutover cannot proceed without this. Two constraints found while scoping it: nothing currently cross-checks a role id against the model map (a renamed default satisfies both shipped assertions — "key exists" and "starts with usai/" — while matching no model, so it ships dangling and silent), and role vocabulary must not leak OpenCode-specific names (small_model, compaction) into a deliberately harness-neutral catalog.
• Reduce sync-usai-models.mjs → build-catalog + emitter (the cutover; gated by the round-trip test and by the two items above). Also needs: the two generators currently disagree on model sort order — 17 of 20 positions differ — so running the monolith today reorders the block and breaks the byte-exact test; and the monolith has no post-write validation, so it wrote an unparseable config, printed Updated … with 1 models, and exited 0.

Later (follow-on)

• Codex / Claude Code / Copilot CLI emitters — needs a research spike first. A repo-wide search found no model/provider configuration for any of the three: no kit, template, ADR, fixture, or config.toml. The load-bearing safety property here is a byte-exact round-trip against a committed, human-reviewed artifact, and no such artifact can exist for a harness whose config shape is not yet established. The repo already set this precedent — pi-coding-agent deliberately cut its models.json step rather than ship an unpopulated placeholder with no emitter to fill it. So: spike the target shape, commit a reviewed reference config, then write the emitter against it. Codex first.
• prime-agent follow-up (demoted from the MVP's consumer to an optional follow-up — OpenCode is the main path). The emitter→artifact link is real and CI-gated by a byte-exact lockstep test, but the in-guest consumer (prime-agent-install-models-json.sh) is still a placeholder that only echos. Three of the kit's own documents also still assert the emitter "does not exist yet" and that models is empty — both false since the MVP landed.
• Promote reasoning + inputModalities (read from models.dev today, then discarded; declared in the schema with "Not populated yet.")
• Second round-trip test for the sbx-kit usai-provider-kit copy — landed with the opencode emitter; the test asserts against both shipped copies.
• Reconcile the coexisting catalog schemas (tracked by chore(isolation): formalize JSON Schema for acq-provider-facts/v1 and acq-neutral-model-catalog/v1 #435). There are now four shapes describing one provider: usai-model-catalog/v1 (this epic), acq-neutral-model-catalog/v1 (already shipping in the kit as model-catalog-snapshot.json), acq-provider-facts/v1 (pending, docs(isolation): add ADR 0004 for neutral model-provider discovery #423), and the credential/diagnostic metadata in feat(provider-facts): declare constrained provider credential operations #486. The credential env-var name alone is currently recorded in three of them.

Notes / conditions (from consensus review)

• CI determinism: build-catalog / round-trip tests must run against a pinned fixture/snapshot offline (the network live-feed path is a separate --models-url/--no-enrichment mode) so CI isn't flaky.
• §4.3 inspired-not-copied: the scripts/emitters/schema are the repo's own code (may be structurally similar to prior art); catalog.json content must be re-derived from live feeds, never copied from any stale snapshot.
• Dependency: the MVP was a blocking upstream dependency of the prime-agent kit's models.json, and that dependency is discharged — the kit ships the real generated artifact today. The remaining prime-agent work is its in-guest install step, not the catalog.
• Sequencing rationale: the ordering above was reviewed by a 7-seat panel against an inlined evidence artifact (6 of 7 seats decided, 0 rejections, 5 of 6 selecting this sequence; recorded as no_quorum under absolute_quorum because one seat could not read the artifact). The dissent argued for fixing every correctness defect before any structural work — a reasonable position, and the two defects it most cared about (input validation, the dangling-default guard) are inside the sequence above rather than deferred behind it.

Built fresh on GSA-TTS canonical. AI-assisted (OpenCode).