135 lines
5.6 KiB
Markdown
135 lines
5.6 KiB
Markdown
# ADR-0091 — Domain Pack Contract v1
|
|
|
|
**Status:** Accepted
|
|
**Date:** 2026-05-21
|
|
**Accepted:** 2026-05-22
|
|
**Author:** CORE agents + reviewers
|
|
|
|
---
|
|
|
|
## Acceptance evidence
|
|
|
|
Accepted after ADR-0093 implementation wired Domain Pack Contract v1 into the validator and capability ledger:
|
|
|
|
- `language_packs/domain_contract.py` parses the optional contract fields and rejects malformed structure.
|
|
- `core/capability/domain_contract_predicates.py` evaluates the nine ADR-0091 semantic predicates.
|
|
- `tests/test_capability_cli.py` verifies `core capability ledger --json` emits reasoning-capable rows for the ratified domains.
|
|
- `tests/test_adr_0097_mathematics_logic_ratification.py` and `tests/test_adr_0100_0102_sibling_ratifications.py` verify all nine predicates pass for the ratified domain packs.
|
|
|
|
---
|
|
|
|
## Context
|
|
|
|
CORE is moving from compact cognition packs toward expert-domain
|
|
articulation. The risk is predictable: broad vocabulary can grow faster
|
|
than reviewed chains, eval lanes, reviewer coverage, and provenance. If
|
|
that happens, the system looks larger while the reasoning substrate stays
|
|
thin.
|
|
|
|
The capability ledger introduced in Phase A-C makes this visible. It
|
|
does not promote a domain because a pack exists. It promotes only when
|
|
manifest validity, closure, chain coverage, holdout presence, eval
|
|
evidence, and known-gap state all line up.
|
|
|
|
Domain packs need a contract that connects those artifacts without
|
|
forcing all existing linguistic packs into a reasoning-heavy schema.
|
|
|
|
---
|
|
|
|
## Decision
|
|
|
|
Introduce **Domain Pack Contract v1** as a pack discipline for packs that
|
|
claim domain capability status.
|
|
|
|
The contract extends pack manifests with optional fields. Existing
|
|
linguistic packs remain valid without these fields. A pack must provide
|
|
the reasoning fields only when it claims `reasoning-capable` or
|
|
`expert-demo` status in the generated capability ledger.
|
|
|
|
### Optional manifest fields
|
|
|
|
```jsonc
|
|
{
|
|
"domain_contract_version": 1,
|
|
"domain_id": "mathematics_logic",
|
|
"axioms": null,
|
|
"rules": null,
|
|
"teaching_chains": ["math_logic_chains_v1"],
|
|
"eval_lanes": [
|
|
{"lane": "mathematics_logic", "version": "v1", "splits": ["dev", "public", "holdout"]}
|
|
],
|
|
"reviewers": ["reviewer_id"],
|
|
"known_gaps": ["gap:math_logic_modal_chains_absent"],
|
|
"provenance": "adr-0090:reviewed:YYYY-MM-DD"
|
|
}
|
|
```
|
|
|
|
| Field | Required for ordinary linguistic pack | Required for reasoning-capable domain claim | Purpose |
|
|
| --- | --- | --- | --- |
|
|
| `domain_contract_version` | no | yes | Version gate for domain-pack validation semantics. |
|
|
| `domain_id` | no | yes | Stable key used by `core capability ledger`. |
|
|
| `axioms` | no | yes when the domain uses explicit axioms | References an axioms/rules JSONL file or `null`. |
|
|
| `rules` | no | yes when the domain uses explicit rules | References inference-rule definitions or `null`. |
|
|
| `teaching_chains` | no | yes | Registered corpora that exercise claimed operator families. |
|
|
| `eval_lanes` | no | yes | Eval lanes and split paths that prove the domain claim. |
|
|
| `reviewers` | no | yes | Reviewer IDs resolved through `docs/reviewers.yaml`. |
|
|
| `known_gaps` | no | yes if blocked | Gap IDs resolved through `docs/gaps.md`. |
|
|
| `provenance` | no | yes | Review trail for the domain claim. |
|
|
|
|
`axioms` and `rules` are deliberately optional. Cognition, relations,
|
|
register, identity, safety, and many lexical packs legitimately do not
|
|
carry formal axiom sets. Requiring those fields globally would create
|
|
schema churn without adding reasoning evidence.
|
|
|
|
---
|
|
|
|
## Validation Semantics
|
|
|
|
A domain pack can affect capability claims only if:
|
|
|
|
1. The base pack manifest is valid and checksums match bytes on disk.
|
|
2. Gloss checksum and definitional closure pass for packs that provide
|
|
glosses or definitions.
|
|
3. `domain_id` maps to a known ledger domain.
|
|
4. Every `teaching_chains` corpus is registered and read-only.
|
|
5. Every claimed operator family has at least 8 reviewed active chains
|
|
for that domain.
|
|
6. At least 3 intent shapes are present before `reasoning-capable`.
|
|
7. Every `eval_lanes` entry has `dev`, `public`, and `holdout` paths.
|
|
8. Every `reviewers` entry resolves to reviewer metadata.
|
|
9. Every open `known_gaps` entry blocks promotion until closed and the
|
|
next status predicate passes.
|
|
|
|
No validator may mutate a pack. Mutation remains a reviewed proposal
|
|
flow.
|
|
|
|
---
|
|
|
|
## Capability Status
|
|
|
|
The generated ledger owns status. Manifest fields provide evidence and
|
|
links; they do not manually assert maturity.
|
|
|
|
| Status | Predicate |
|
|
| --- | --- |
|
|
| `seeded` | Manifest/schema valid, checksum valid, provenance present, no unsafe paths. |
|
|
| `grounded` | Gloss coverage threshold passes, closure passes, pack is mount-eligible, gaps are registered. |
|
|
| `reasoning-capable` | Claimed operator families each have at least 8 reviewed chains, at least 3 intent shapes are present, eval lane and holdout path exist. |
|
|
| `expert-demo` | Dev/public/holdout pass thresholds, provenance/replay pass, audit-tour or equivalent reports all claims supported. |
|
|
| `blocked` | A registered gap names the missing substrate, reviewer, or eval. |
|
|
|
|
`blocked` lifts only when the named gap closes and the next predicate
|
|
passes. Closing a gap never promotes a row by itself.
|
|
|
|
---
|
|
|
|
## Consequences
|
|
|
|
- Existing packs remain valid. No mass re-ratification is caused by this
|
|
ADR alone.
|
|
- Expert-domain work becomes evidence-coupled: packs, chains, evals,
|
|
reviewers, and gaps have one generated ledger surface.
|
|
- Operator work cannot drift away from chain authoring: a claimed
|
|
operator family without chains remains below `reasoning-capable`.
|
|
- Hebrew/Greek textual reasoning cannot advance on pack names alone; it
|
|
must close gloss coverage and chain foundation first.
|