0011: Machine-readable report contracts
Esdieff provides versioned JSON reports and stable diagnostic codes from the first useful checking milestone. Callers can read outcomes, requested assessments, model scope, coverage, incompleteness, truncation, standards baseline, and the distinction between RFC findings and acceptance-policy findings structurally. Human wording can improve without becoming an automation interface.
Before implementation, the concrete report schema and compatibility rules must cover changes to assessment inventories and diagnostic meanings as well as field evolution. An unchanged assessment identity or condition code must not silently acquire a different meaning. The design should accommodate intended future capabilities while keeping the report’s current guarantees precise, following ADR 0010: Domain-oriented library and caller simplicity.
Full retains assessment and baseline rfc9880/base-1. The existing mandatory request.inventory esdieff.full-model/1 binds its immutable13-area membership and54-member rfc9880.model/1 relation, documented in the model inventory. Known membership replaces unavailable membership without implying completed capability. Historical null inventories still mean unavailable membership, never an empty set. New membership needs a new identity; Initial and other profiles retain their meanings.
Borrowed requirement descriptors and fixed semantic statuses remain available independently of rendering. New optional aliases, summaries, rows and coverage owners may be wholly omitted. Area aggregates retain their existing count unit; requirement aggregates explicitly count requirements. Conditions preserve producing assessment_unit IDs, while optional coverage_owner and the immutable relation identify their actual requested Full owner. Generic rules use actual field/role context. Semantic states, aggregate errors and incompleteness never depend on retained diagnostics. The report contract pins exact fields and omission accounting.
Full broader.state follows the54 model obligations named by its inventory, while requested completion follows13 areas including independent advice. Completed model work can contain errors or coexist with unfinished advice. The optional Full omitted-areas list is absent; mandatory state is authoritative. Human and JSON share this calculation. Other operations retain their broader partial meaning.
Considered Options
Treating initial JSON as debugging output would postpone interface design, but require consumers to parse prose and migrate their integrations later. A supported report contract places that burden in Esdieff. It does not require serializing internal Rust structures or freezing every future diagnostic in advance.
Renaming assessment_unit according to the selected profile would silently change a published field’s meaning. A separate optional owner preserves its producer. Requiring a new inventory alias would break mandatory-only consumers; the existing inventory binding carries membership when optional detail is absent. Treating historical null membership as empty would invent completion. Counting supporting citations again, or replacing complete model obligations with a smaller implemented subset, would inflate coverage.
Deriving broader model completion from all13 areas is conservative but couples the named54-member model inventory to separate advice. Permanent partial cannot express established completion. An unconditional unimplemented-requirements list would falsely describe both completed model work and partial work caused by acquisition or processing limits.
Sample 1.1 adds mandatory final meaning sets and actual consulted-interpretation observations within the existing Sample result and baseline envelope, following ADR 0025: Selected numeric samples. The current nine-area identity, authoritative outcome, admission, counts and older operations are unchanged. Reference sets use complete kind/ID/citation identity: RFC views omit IDs; operational views preserve existing precise citations when present. Clients reading older additive 1.x reports treat absent meaning fields as an unavailable capability, never as an established empty set or not-applicable status.