0013: Shared workflow and report guarantees
Esdieff’s public boundary is document-supplied domain work with owned immutable source content, borrowed typed source/effective views, and scoped results that preserve independent findings. The public workflow and report contract gives checking, inspection, future sample-value checking and authored-document consumers one source/location/outcome foundation while keeping internal parser, graph and numeric types replaceable. This follows ADR 0010: Domain-oriented library and caller simplicity.
The immutable default assessment esdieff.initial/1 retains its predetermined structure/composition inventory and four guarded advisory proof classes. Broader recorded-baseline requests keep their own immutable baseline/inventory identities and cannot complete without all applicable requested work. Mathematical number capability remains separate from normative CDDL admission, following ADR 0012: Exact numbers and JSON input policies. New membership or meaning receives a new identity; implementation progress cannot redefine success.
Initial completes its eight areas through the existing traversal, composition and required-declaration resolver on the original cumulative allowance. Removing placeholder diagnostics follows completed work. Full knows 54 exclusive model obligations grouped into 13 requested areas, while genuinely unfinished applicable model meaning remains unassessed or undetermined. Sample admission, conversion, protocol/device behavior, registry administration and operator duties do not earn model completion. General satisfiability and optional refinement analyses are separate.
The shared requiredness seam retains copied declaration identity, original resolution policy, independent definite errors and unavailable needed targets. It does not build a parallel graph or replenish work. Fixed states are updated before optional finding retention; producing inspection conditions keep their identities and receive a Full owner only in the applicable recording context.
Report JSON 1.0 is a supported explicit wire contract, independent of Rust layout. It separates completion, aggregate findings, strict-warning disposition, requested/broader coverage, basis and omitted diagnostic detail. Stable condition codes retain their meanings; additive fields cannot change them. Source/effective/sample locations and available inheritance/override/deletion explanations remain distinct. No exhaustive provenance history is promised. This makes report consumers independent of human wording, following ADR 0011: Machine-readable report contracts.
The shared contract pins nested field types, absence/null states, compact source IDs, count bounds and units, and fixed acquisition/decode/basis values. Initial checks count eight immutable assessment areas. Standalone inspection requests no model assessment: it counts one declared view-establishment operation and discloses broader partial coverage. Future sample/author payloads remain their dedicated contract decisions, with unknown-operation guards protecting existing check/inspect readers.
Finite catalogue-wide parsed nodes/allocation, effective nodes/allocation/byte work, reference/checking work, compact ancestry and pointer/report budgets complement the input/number limits in ADR 0012. Storage and work are charged before derived allocation or traversal. Count/byte/pointer presentation truncation preserves aggregate errors and semantic completion; a required semantic capability limit leaves affected work incomplete, following ADR 0009: Bounded processing and reporting. Ordinary caller exercises guide simplicity and avoidable allocation without inventing a performance target.
Before copying, metadata preflight bounds keys, labels, acquisition URIs, content-version tokens, digests, exact raw filesystem identities and repeated references across all source roles. Semantic identities are never clipped. Only presentation labels can be shortened/omitted with reasons. Whole-request caller metadata and library-owned baseline/inventory metadata have separate finite caps. A worst-escaping mandatory report reserve preserves every source attempt and aggregate outcome; too-small report configurations fail before processing.
The CLI accepts explicit paths and one stdin document, defaults to catalogue checking, requires explicit supplied roots for selected-model checking, and emits one human or JSON report with exits distinguishing passed, failed, invocation error, undetermined and host-output failure. Direct checking can additionally prepare supplied files through bounded directory discovery, following ADR 0004: Supplied catalogues and checking scope. Preparation errors occur before acquisition and emit no model report. Future sample/author operations share these guarantees; their specific request/write decisions precede their implementation. No implicit acquisition, input precedence or generic mutable checked JSON is introduced.
Saved Check plans group named Check cases through the existing Catalogue operations. Explicit source keys and roles preserve acquisition attempts, and local paths are resolved beside the supplied plan path without canonicalizing a symlink to its target. Cases run sequentially with independent native allowances and continue after failed or incomplete work. The CLI owns this workflow rather than exposing a second semantic interpreter or a public batch API.
A Revision comparison case names each revision’s documents literally by source key and acquires them only when it runs, into two Catalogues of its own, as direct comparison does under ADR 0039: Client-side revision comparison. Earlier revisions therefore never join the plan’s sources, where they would become dependency candidates of its checks and could make references ambiguous. Its optional acknowledgement file is decoded with the plan, before any acquisition, and its case counts by the disposition its acknowledgements decide under ADR 0040: Acknowledged revision differences. The plan stays at version 1, since older releases refuse the new operation as a configuration error.
The separate esdieff.check-run envelope counts cases rather than combined RFC obligations. Its mandatory source/case summaries are reserved before acquisition or execution, including each comparison case’s classification and a share for each of its documents. Optional whole native reports use only the remaining allowance, preserving exact numerical serialization. Run-level detail omission cannot change authoritative outcomes, completion or exit precedence. Version 1.1 adds comparison cases, and every run report is emitted at that version. See the Check plan contract and runnable example.
Considered Options
A pass/fail-only report hides unfinished work and can let omitted later errors disappear behind retained warnings. Implicit source labels or namespace URIs as identity confuse acquisition, content and model names. Public parser/decimal types or mutable JSON graphs require caller migrations and semantic bookkeeping. Expanding every reference into copied content without byte/work charging permits allocation amplification despite input caps. Full ancestor pointers stored at every node amplify path memory. Freezing sample/author request details now adds decisions without their concrete acceptance cases; only their shared foundation is settled here.
Naming plan sources as a comparison’s revisions would put earlier revisions into every check’s Catalogue, or need a new source role to keep them out. Discovering revision directories inside a plan would make its results depend on the current directory contents, against ADR 0004: Supplied catalogues and checking scope. Deleting unfinished diagnostics alone would misrepresent requested work. Resetting an allowance for requiredness, or adding a second resolver, would bypass cumulative operation limits. Dummy samples and successful supplied-value checks cannot prove model-side capability. A mandatory heap inventory or 54-row DTO would impose unrelated Full storage on Initial/source-only callers. Fixed producer states and wholly optional detail retain bounded admission and the existing result’s fallback lifetime.