MIF Level-3 I/O conformance as the harness substrate
ADR-0002: MIF Level-3 I/O conformance as the harness substrate
Section titled “ADR-0002: MIF Level-3 I/O conformance as the harness substrate”Status
Section titled “Status”Accepted
Context
Section titled “Context”Background and Problem Statement
Section titled “Background and Problem Statement”The harness needs one authoritative interchange format so that every artifact
crossing the project boundary — findings, the knowledge graph, citations,
provenance, reports, ingested sources — is machine-validated against a single
contract (docs/explanation/mif-io-conformance.md,
docs/explanation/architecture.md §6c). The question is which format binds these
artifacts, and at what conformance level.
Current Limitations
Section titled “Current Limitations”The prior system suffered schema drift: findings, the knowledge graph, citations, and provenance each used ad-hoc shapes that had to be reconciled by hand, and the graph was derived from tags rather than being first-class.
Decision Drivers
Section titled “Decision Drivers”Primary Decision Drivers
Section titled “Primary Decision Drivers”- One machine-validated contract for findings, graph, citations, and provenance.
- Reports and ingested sources, not just findings, must be held to the contract.
Secondary Decision Drivers
Section titled “Secondary Decision Drivers”- The knowledge graph should be first-class, not derived from tags.
- Harness lifecycle state (falsification, quarantine, lineage) must be carried without forking the base format.
Considered Options
Section titled “Considered Options”Option 1: Bespoke per-artifact JSON schemas
Section titled “Option 1: Bespoke per-artifact JSON schemas”Description: Define a tailored JSON schema for each artifact type independently, as the prior system did.
- Advantages: Maximally tailored to each artifact’s exact needs.
- Disadvantages: Reproduces the schema drift this template exists to eliminate, and the graph stays tag-derived.
- Risk Assessment: technical medium; schedule low; ecosystem high.
Option 2: MIF Level-1 (identity only)
Section titled “Option 2: MIF Level-1 (identity only)”Description: Adopt MIF but require only Level-1 frontmatter concept identity, without enforcing provenance or a citation closure.
- Advantages: Cheap — only frontmatter identity is required of each artifact.
- Disadvantages: Does not bind provenance or a citation closure, so findings could ship without verifiable evidence.
- Risk Assessment: technical low; schedule low; ecosystem medium.
Option 3: MIF Level-3 with a harness extension
Section titled “Option 3: MIF Level-3 with a harness extension”Description: Require MIF Level-3 (provenance + citations + entities + extensions) validated against the vendored schemas/mif/ closure, with harness-only patterns under extensions.harness.
- Advantages: Every finding is a MIF memory unit validated against the vendored closure; the graph is MIF entities and typed relationships; citations are MIF Citation objects; provenance is the W3C-PROV block; harness-local concerns close the gap locally rather than forking MIF.
- Disadvantages: The vendored MIF closure must be tracked and updated.
- Risk Assessment: technical low; schedule low; ecosystem low.
Decision
Section titled “Decision”Adopt Option 3: MIF Level-3 with a harness extension. harness.config.json
sets mifConformanceLevel: 3. A finding is an individual MIF memory unit
validated against the vendored schemas/mif/ closure; reports
(reports/<topic>/<slug>.md) are MIF L3 held to the same bar as a finding; and
ingested sources are wrapped as validated MIF source-envelopes.
schemas/findings.schema.json $refs the real vendored MIF schema and only
adds harness-local concerns under extensions.harness, never overriding MIF
(§8b).
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- Schema drift collapses into one machine-validated contract.
- The knowledge graph becomes first-class instead of tag-derived.
Negative
Section titled “Negative”- Vendoring the MIF closure adds an upstream-tracking obligation
(
schemas/mif/VENDOR.lock).
Neutral
Section titled “Neutral”- The L3 floor binds the whole I/O surface, not findings alone, which raises the bar uniformly for reports and ingested sources.
Decision Outcome
Section titled “Decision Outcome”A single authoritative format makes findings, the graph, citations, and provenance one validated contract, with harness lifecycle state added locally rather than by forking MIF. The upstream-tracking cost is contained by the vendor lock file.
Related Decisions
Section titled “Related Decisions”More Information
Section titled “More Information”- Date: 2026-06-23
- Source:
docs/explanation/mif-io-conformance.md,schemas/findings.schema.json,harness.config.json
2026-06-23
Section titled “2026-06-23”Status: Compliant
| Finding | Files | Assessment |
|---|---|---|
| Conformance level declared | harness.config.json (mifConformanceLevel: 3) | compliant |
| Findings schema refs vendored MIF | schemas/findings.schema.json | compliant |
| Vendored MIF closure present | schemas/mif/, schemas/mif/VENDOR.lock | compliant |
Summary: The L3 conformance level is declared, the findings schema references the vendored MIF closure, and the closure is vendored under schemas/mif/.
Action Required: None