docs: model-catalog-entry v0.2 design notes for baseBinding debt#20
Merged
Conversation
…t v0.1 Implements the ModelCatalogEntry admission contract for model-router. Designed from forensic analysis of Apple Foundation Models delivery, Claude Code/Codex lifecycle failures, and SourceOS differentiators (SAE interpretability, SCOPE-D epistemic labeling, guardrail-fabric policy, Ontogenesis ontologies, TriTRPC provenance wire). Seven hard admission gates — a single failure denies, no silent admission: 1. content_hash_mismatch — sha256 format + payload verification; encrypted=true invariant 2. attestation_invalid — signer identity, signature, hash-chain (provenance anchor) 3. base_version_mismatch — adapters/steering/guardrail must declare exact base binding 4. capability_not_granted — highPrivilege requires non-empty requiredPermissions 5. missing_epistemic_label — SCOPE-D level required; no label = inadmissible 6. epistemic_rejected — retained for audit, never loadable 7. steering_diff_unsupported — steeringTier full/local requires emitsSteeringDiff=true Artifacts: contracts/sourceos/model-catalog-entry.v0.1.ts — TypeScript source of truth schemas/model-catalog-entry.v0.1.schema.json — JSON Schema (draft-07) examples/model-catalog-entry.admitted.json — valid admitted entry examples/model-catalog-entry.denied.epistemic-rejected.json examples/model-catalog-entry.denied.steering-diff-unsupported.json tools/validate_model_catalog_entry.py — Python admission implementation tools/tests/test_model_catalog_entry.py — 35 tests, all gates covered Makefile: validate-model-catalog-entry wired into make validate .github/workflows/model-catalog-entry.yml — path-scoped CI
Documents the v0.1 design debt where kind=base entries are required to carry a semantically redundant baseBinding object. Records the v0.2 fix (if/then conditional schema), the gate condition (real base entry example + consuming-repo readiness), and the current state. Links from MODEL_ROUTER.md.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the known v0.1 design debt where
kind: "base"catalog entries are required by the JSON Schema to carry abaseBindingobject, even though that field is semantically self-referential for base entries (there is no parent base to point at).baseBindingfor all kinds; validator already soft-handleskind=base(skipsbaseModelIdcheck); TypeScript contract has a comment about it; but no formal tracking existedif/thenconditional that makesbaseBindingoptional forkind=baseand fully required (includingbaseModelId) for adapter/steering/guardrail kindskind=baseexample with confirmedartifact.contentHash+ consuming-repo readiness confirmationMODEL_ROUTER.mdNo schema change in this PR — this is documentation only. The v0.2 schema change will be a separate coordinated PR when the gate condition is met.
Test plan
make validatepasses🤖 Generated with Claude Code