Implement ADR 0004: unified model information subsystem #10290

Goal

Implement ADR 0004: Model information management incrementally, replacing independently maintained model tables with schema-validated source records, shared provider-qualified identity/resolution, and deterministic consumer projections.

User-directed amendment: expose all new model information through the existing /reflect endpoint. Do not add /reflect/v2, endpoint-version negotiation, or a v2-to-v1 fallback. Preserve existing /reflect fields and meanings through additive changes. Catalogue/schema revisions and versioned input/export formats remain applicable. The ADR was updated accordingly in Phase 2 (#10310); this remains binding for all later phases.

2026-10-21 user-directed scope correction: this is model management, not a new execution-security architecture. Retain model schemas/data, scoped overlays and source handling, shared eligibility/resolution, ordinary harness-version checks through existing backends, consumer migration, accounting parity, reasoning/compatibility metadata, additive exports, and maintenance. Discard the unmerged kernel/native-hardening, new process/controller authentication, protected spawn/launch-attestation, private execution-plan transport, and immutable agent-runtime closure work. Preserve existing sandbox/network/security controls unchanged. Missing runtime-version evidence is an explicit unknown/ineligible result, not a mandate to build a new isolation system. No phase may introduce that architecture as a model-management prerequisite.

Phase plan

One implementation issue per gate:

1. Characterization and drift baseline (incorporates existing test: characterize model metadata behavior and drift #10032).
2. Canonical schemas, provider-qualified identity, and cross-repository handoff contracts.
3. Deterministic compiler, maintained records, imports, and legacy projections.
4. Lifecycle consumers, workflow overlays, and actual-harness eligibility.
5. Pricing resolver, configurable/offline-first refresh, and accounting parity.
6. Shared reasoning metadata and directed feature compatibility.
7. Additive /reflect, persisted snapshots, CLI, and package exports.
8. Unified updater, drift review, and central snapshot publication.
9. Legacy removal after parity and compatibility gates.

Native sub-issues below track implementation. Existing #10029 (pricing/availability) and #10030 (reasoning/context) are named coverage requirements, not competing sources of truth. Coordinate any fixes landing there with Phase 1's baseline and Phase 3's canonical records; do not duplicate their implementation blindly.

Merged foundation and current status

Status reconciled against merged PRs on 2026-10-20:

The canonical subsystem is now available under shared/model-information/: reuse schema.v1.json, identity.js, contracts.js, maintained sources/, and the governed imported snapshot. scripts/model-information/compile.cjs produces compatibility assets, static catalogues, manifest.generated.json, target.generated.json, and baseline-to-target.generated.json. Use npm run models:generate and npm run models:check; ordinary generation/checking is offline and must not refresh source capture times.

Generated ownership is not the same as activating target corrections. The two API-mapping copies are generated compatibility outputs preserving existing behavior. Since #10360, host support/suggestions and proxy retirement use the generated compatibility projections; curated-pricing projections remain staged until Phase 5. The #10029/#10030 corrections are still staged separately for explicit activation in Phases 4-6, so those coverage issues are not complete merely because the compiler and compatibility readers merged. Target provenance records issue evidence with estimated confidence; verify the cited provider evidence before activating corrections. The governed import preserves captured namespaces without asserting native-provider billing scope; Phase 5 needs evidenced mappings before using imported prices for a deployment.

The former endpoint-only updater is now manual and read-only, with run-summary/noop output rather than repository authoring. This satisfies Phase 3's ownership safeguard, not Phase 8's unified maintenance or publication requirements.

Cross-repository companion tracking is now github/gh-aw#70728. The implementation direction is model-information frontmatter -> AWF modelInformation, with canonical scoped overlays and explicit source settings; the model-only contract must be reconciled after removing launch-attestation metadata. Initial compiler transport retains the existing 21,000-byte final expression-bearing rendered-script limit with explicit oversize rejection; larger-snapshot staging is excluded. Initial source support is inline/offline, with actionable live-URL rejection. Payload/semantic parity, model-feature version compatibility, ordinary execution-environment version checks, and consumer round trips remain required; a new protected controller, kernel, or agent-runtime attestation system does not.

Dependency and assignment strategy

• The hard foundation chain, Phase 1 -> Phase 2 -> Phase 3, has merged. Do not reimplement its schemas, identity API, source layout, compiler, or staged corrections.
• Phase 4 (ADR 0004 phase 4: migrate lifecycle validation, overlays, and harness eligibility #10294) is the next integration gate. Its compatibility-reader slice landed in Migrate lifecycle readers to generated data (ADR 0004 phase 4, partial) #10360. Shared eligibility and actual-environment harness work can proceed from that baseline, but workflow overlay wiring and phase completion remain blocked on the unresolved github/gh-aw agreement, now tracked in github/gh-aw#70728. A linked issue is not evidence that the handoff is agreed.
• The Phase 4 handoff must agree exact frontmatter/config keys, versioned payload and supported versions, provider/channel/deployment scope, workflow/operator conflicts, sanitized provenance, older-pinned-AWF rejection, central source/offline settings, and actual execution-environment harness/version semantics. Companion compiler support and compiler-to-AWF round-trip fixtures are required; do not invent incompatible field names independently.
• Phase 5 (ADR 0004 phase 5: unify pricing resolution and offline-first catalogue refresh #10295) may proceed now with bounded static pricing, configured/runtime input migration, and old-authoritative shadow comparisons, followed by refresh/cache integration. It can run alongside Phase 4, but refresh-triggered harness eligibility re-evaluation must integrate with Phase 4 before closure. Preserve configured catalogue authority above runtime prices; fetched central feed data has a different, lower authority.
• Phase 8 (ADR 0004 phase 8: unify catalogue maintenance, drift review, and feed publication #10298) may proceed now with source-aware maintenance and drift review against the merged schema/compiler. Keep generated files out of independent authoring paths. Central feed publication must remain gated on Phase 5 loader/source-authentication integration; a static full-catalogue export is not automatically a valid central feed.
• Phase 6 (ADR 0004 phase 6: unify reasoning and directed protocol compatibility #10296) follows Phase 4's shared eligibility integration and can run alongside Phase 5. Activate staged reasoning corrections only with parity or explicitly reviewed behavior changes.
• Phase 7 (ADR 0004 phase 7: expose unified catalogue through /reflect, snapshots, CLI, and package #10297) integrates Phases 4-6. Downstream adoption also requires linked github/gh-aw / gh-aw-router-training companion work and accounting/export parity; source-tree generated files alone are not the public export rollout.
• Phase 9 (ADR 0004 phase 9: remove legacy model tables after parity and release gates #10299) follows all migrations, updater completion, downstream adoption, a stable release of affected paths, and explicit compatibility-window approval. It is not ready for assignment merely because earlier PRs merged.

Immediate next actions

1. Remove the unmerged execution-security expansion, preserve independently useful model-management changes, and reconcile a model-only compiler/config contract with github/gh-aw#70728. Do not describe local partial work as merged or complete.
2. Finish Phase 4 scoped overlay ingestion, shared eligibility and existing-backend harness-version checks across actual consumers, using explicit unknown/incompatible outcomes instead of new launch-proof infrastructure.
3. Make scheduled canonical source retrieval, evidence-backed update proposals, validation/regeneration, and deduplicated review PRs a required deliverable of ADR 0004 phase 8: unify catalogue maintenance, drift review, and feed publication #10298; the system must not rely on maintainers remembering to update sources. Source upkeep can proceed against the merged foundation without waiting for live feed publication. Review the bounded Phase 5 pricing shadow separately; reasoning, exports, and legacy removal retain their phase gates. This requirement does not authorize workflow dispatch or auto-merging model changes.
4. Keep Add curated AI-credit prices for current Copilot models #10029/Complete routing effort metadata for current OpenAI and Anthropic models #10030 open until their required corrections are activated and covered in the relevant consumer migrations. Keep Phases 6/7/9 behind their stated integration, parity, and release gates.

Agent execution contract

Each phase issue supplies scope, entry points, acceptance criteria, and non-goals. Re-read the current ADR and prerequisite implementations before starting; the paths listed are discovery entry points, not mandatory module boundaries. Keep each PR bounded to its phase, update directly related docs, and report prerequisite issue/PR links and evidence for acceptance criteria. Do not mark a phase complete with known acceptance gaps. Do not implement later phases speculatively.

Existing behavior remains authoritative until characterization and parity cover its replacement. High-risk pricing, reasoning, and compatibility changes use temporary shadow comparison: old result controls the request, sanitized structured differences become fixtures or explicitly reviewed changes, and the temporary path is removed only after parity and a stable release. Maintain fail-closed model/network/budget safeguards, scoped overlays, explicit unknown/stale states, and sanitized per-field provenance.

Validation and completion

• Run targeted root tests (npm test -- <test selectors>) and the separate proxy suite (cd containers/api-proxy && npm test -- <test selectors>) for affected behavior. Root Jest does not discover proxy tests. Run build/type-check when host/shared code changes; escalate scope as integration warrants.
• Run npm run models:generate after canonical source changes and npm run models:check to verify deterministic generated outputs. Review sources and all affected projections together; generation/check mode must not fetch upstream data.
• Require deterministic regeneration/staleness checks, named Add curated AI-credit prices for current Copilot models #10029/Complete routing effort metadata for current OpenAI and Anthropic models #10030 fixtures, old/new accounting and routing parity, overlay/source rejection cases, and real consumer/packaging integration—not just isolated resolver tests.
• Test network-denied, offline/local-only, expired-source, incomplete-provider, and unsupported-pinned-version cases without requiring live external APIs.
• Final outcome: host, proxy, routing, accounting, docs, exports, and downstream consumers derive facts from the canonical subsystem; no independent source tables or duplicated canonicalizers remain after approved legacy removal.

Scope boundary

This issue plans and tracks implementation only. It does not authorize dispatching agents, workflow runs, production changes, model-selection policy changes, lossy translation, or broad unrelated refactors.

Assignment index

• ADR 0004 phase 1: characterize model metadata behavior and drift #10291 — characterize model metadata behavior and drift; merged test: Characterize model metadata behavior and drift #10301
• ADR 0004 phase 2: define canonical schemas and provider-qualified identity #10292 — define canonical schemas and provider-qualified identity; merged Define versioned model contracts and provider-qualified identity #10310; cross-repository handoff carried into Phase 4
• ADR 0004 phase 3: compile maintained model records into deterministic projections #10293 — compile maintained model records into deterministic projections; merged Compile reviewed model records into deterministic compatibility projections #10317; target corrections remain staged
• ADR 0004 phase 4: migrate lifecycle validation, overlays, and harness eligibility #10294 — migrate lifecycle validation, overlays, and harness eligibility; compatibility readers merged in Migrate lifecycle readers to generated data (ADR 0004 phase 4, partial) #10360; shared eligibility, harness enforcement, and github/gh-aw contract/wiring remain
• ADR 0004 phase 5: unify pricing resolution and offline-first catalogue refresh #10295 — unify pricing resolution and offline-first catalogue refresh; ready for bounded implementation, closure depends on Phase 4 integration
• ADR 0004 phase 6: unify reasoning and directed protocol compatibility #10296 — unify reasoning and directed protocol compatibility; depends on Phase 4
• ADR 0004 phase 7: expose unified catalogue through /reflect, snapshots, CLI, and package #10297 — expose unified catalogue through /reflect, snapshots, CLI, and package; depends on Phases 4-6 and downstream adoption
• ADR 0004 phase 8: unify catalogue maintenance, drift review, and feed publication #10298 — unify catalogue maintenance, drift review, and feed publication; updater work can begin, publication gated on Phase 5 integration
• ADR 0004 phase 9: remove legacy model tables after parity and release gates #10299 — remove legacy model tables after parity and release gates; not ready