Formats and digests
Choose a reader by the document's producer and shape as well as its marker. Some ESS outputs are unversioned, and two different shapes can share a marker. A successful JSON or YAML parse does not necessarily validate the document's claims.
A format version such as ess/1, a specification version such as v3, and a software release
such as 0.18.0 identify different things. Specification versions are major-only; typed IR serializes
that major as a number. Delivery release versions and constraints use SemVer independently.
Version owners, specification format support.
Which digest is this?
| Identity | Hash input and spelling |
|---|---|
Compiled model: source_digest or suite spec_digest | SHA-256 of compact typed EssIr JSON, with no appended newline. Bare 64 lowercase hexadecimal characters. This is not a hash of raw YAML or pretty ess compile output. Source |
Whole contract: whole-model contract_digest | SHA-256 of a compact, key-sorted construct payload. Bare 64 lowercase hex; the payload differs from the compiled-model hash input. Source |
Sliced contract: Constructs contract_digest | slice-sha256/2:<64 lowercase hex>, from the selected constructs and their dependency closure. The profile prefix is part of identity; a bare legacy slice digest requires regeneration. Source |
Delivery document: Digest | sha256:<64 lowercase hex>. Canonical delivery digest() methods hash pretty JSON including its final LF. Artifact/OCI digests can use the same spelling for different bytes. Source |
Realization: realization_digest | Prefixed SHA-256 of the compact specification/synthesis/implementations tuple in v1; v2 prepends ess-realization/2 to that tuple. Not the entire realization document. Source |
Infrastructure model: InfraIR digest | Bare SHA-256 of compact, key-sorted model JSON, excluding the envelope and observation provenance. Source |
Infrastructure intent: InfraSpec::digest(), projection provenance.specification_digest | Bare 64 lowercase SHA-256 of compact, key-sorted serialized typed InfraSpec: format, name and expectations, with no appended newline. Array order, including declared expectation order, remains significant. This differs from authored-file, InfraIR-model and whole-projection identity. Digest, consumer |
More columns: swipe horizontally, or focus the table and use the arrow keys.
A digest field identifies only the bytes its producer defines. Matching syntax does not establish that two digest domains are interchangeable, that a report covers its exact suite, or that a remote artifact has been fetched and verified.
Generated output state
ess-output-state/1 is an unreleased private checkpoint format for CLI generation, adoption and
recovery. Its .ess-output directory binds an enrolled root to its fixed generator owners,
file inventory and any pending transaction. It is not part of a generated artifact's format or
model digest. Generated artifact bytes retain their existing identities.
The reader accepts canonical sorted-key JSON with a final LF and rejects unknown versions,
fields, duplicate keys, noncanonical bytes, unsafe paths and contradictory inventories.
UnixBytes1 encodes native path components as lowercase hexadecimal; it preserves native names
without interpreting them as UTF-8. File digests use lowercase SHA-256. The checkpoint checksum
covers its canonical payload without the checksum member and detects inconsistent bytes; it
does not authenticate another writer.
Recovery follows the recorded staging, prepared, committed or restored decision and retains it
until cleanup finishes. An unpublished state.next is not recovery authority. Preserve unknown
state and initialization entries for diagnosis. Older ESS versions have no reader or lock
protocol for this format. See the generation workflow
for the filesystem assumptions and recovery command.
Directory input configuration
This format is available in current source and is unreleased.
ess-inputs.yaml declares one format: ess-inputs/1 document with exactly three required fields:
format, specification and scenarios. The latter two are lists of strings. Nulls, wrong types,
unknown fields, duplicate mapping keys, multiple YAML documents and other format versions refuse.
This is optional immediate-directory acquisition configuration, not an authored ESS fragment or a
persisted IR. Pass its containing directory; passing the file itself keeps ordinary direct-file
reader behavior. Reader.
Each path is a nonempty UTF-8 identity relative to that root. Split on /: empty, . and ..
segments refuse, as do backslashes, colons and control characters. Case and Unicode are preserved;
* is a literal filename character. Duplicates within either list and the same spelling across
roles refuse. There are no globs, includes, remote expansion or inherited configuration.
Only the active role resolves filesystem entries. Its list must be nonempty. The root, manifest, selected files and intermediate directories below that root must not be symlinks; selected inputs must be regular files whose canonical targets stay inside the root and are not repeated. Inactive paths receive structural checks only and may name missing files. Unlisted files are not enumerated, inspected or read. Distinct copied or hardlinked files retain separate identities and can trigger existing semantic duplicate refusals.
Selected original UTF-8 text is retained without newline conversion. Entries are read in sorted identity order. Model Source/SourceMap and suite/5 source identities are the listed relative paths; suite/4 keeps a readable joined origin label. The manifest has no canonical writer or raw-file hash contract and is not added to EssIr, suite provenance or suite/5 authored sources. Source-byte and semantic digests keep their existing, separate meanings.
An invalid reserved filename refuses without legacy fallback. Rename an older ESS fragment named
ess-inputs.yaml or adopt this configuration. Older readers do not understand this format and
refuse it; some old conformance semantic-refusal paths can retain incomplete diagnostic outputs.
Supported legacy direct-file, recursive-model and shallow-scenario layouts remain available when
configuration is absent. Manifest selection does not infer generation, authorship or ownership.
The named ESS model describes the closed fields, singleton format enum, lists and string values. Its projection does not enforce complete path grammar, cross-list uniqueness, active-role cardinality, filesystem facts, deterministic acquisition or exact source-byte custody. The CLI reader owns those checks; declaration validation alone is not discovery evidence.
Specifications and implementation plans
“Closed DTO” below means unknown fields are refused. The named compile or validation step still checks semantics. “Pretty JSON” means the writer's deterministic rendering with a final LF unless the row says otherwise; it does not imply that those bytes are hashed.
| Document and discriminator | Version/identity carried separately | Reader and byte contract |
|---|---|---|
Authored specification: format: ess/1, ess/2, ess/3 or ess/4 | Specification vN | RawSpecFile::parse, assembly/validation and compilation. Binary64 requires major 2 or later at every declared position; map keys refuse. Unreleased major 3 adds bounded binding accessors, ordered list selection, periodic host causes, subject-state guards and clock-reading attachments; earlier source formats refuse those declarations. Unreleased major 4 adds error naming, typed command responses and explicit emitted-payload ownership; majors 1–3 preserve sparse payload semantics. No canonical raw-source hash. Source |
Compiled EssIr: unversioned | Numeric specification major | Compiler-minted, Serialize-only; no general persisted-IR reader. Pretty JSON output; compiled-model digest uses compact bytes instead. There is no current ess-ir/1 marker. Source |
Authored composition: format: ess-composition/1 with a services array | Composition/service keys, system/version, selected component and exact compiled-model digest | Closed JSON/YAML DTO, then compile checks identity and selected-surface membership against supplied services. Pretty canonical JSON; no whole-composition digest. Source |
Compiled composition: format: ess-composition/1 with a services map | Resolved imported model identities, components and selected named references | Serialize-only compiler output; no complete payload or codec definitions. The authored reader does not read this shape. Pretty JSON; model digests remain references. Source |
Client plan: format: ess-client-plan/1 | Composition key and the same selected service metadata/names | Derived from compiled composition; Serialize-only. No complete payload or codec definitions. Pretty JSON; no client-plan byte digest or live service identity check. Source |
Authored realization: type: ess-realization/1 | Realization id and specification/synthesis identities | Closed JSON/YAML DTO, then compilation against supplied ESS authority. No raw-document digest contract. Source |
Compiled realization: type: ess-realization-ir/1 | Same identities plus realization digest | Serialize-only compiled output. Pretty JSON; realization tuple digest. Source |
Authored realization: type: ess-realization/2 | Realization id and specification/synthesis identities | Opt-in implementation-only selection: empty entrypoints allowed only without actors or conformance claims. Nonempty entrypoints retain v1 rules. Closed DTO and semantic compilation; v1 readers reject this version. Source |
Compiled realization: type: ess-realization-ir/2 | Same identities plus version-separated realization digest | Serialize-only compiled output; pretty JSON. V1 canonical bytes and identity remain unchanged. Source |
plan.json: unversioned SynthesisPlan | Specification provenance | Neutral generated plan, consumed as a typed value by emitters. Pretty JSON and PLAN.md; compiled-model/whole-contract references, no plan-file hash. Source |
target.json: unversioned TargetReport | Target name and specification provenance | Successful Go/Web/Clap synthesis includes this refusal/weakening report; successful Rust has target: None and no target metadata. No persisted admission reader. Unchanged pretty JSON and TARGET.md; provenance references, no report-file hash. Source |
Complete failure: format: ess-target-failure/1 | Target rust or web; unchanged neutral plan and its provenance | Serialize-only TargetFailure has format, target, plan, nonempty causes; private construction, read-only accessors, no Deserialize/admission reader. Typed pretty JSON+LF or CLI YAML; no failure-file digest or artifacts. Source |
Complete failure: format: ess-target-failure/2 | Target go or clap; unchanged neutral plan and provenance | Located finite Binary64 codec refusal, or Go missing-type-owner refusal, with the same failure fields and no artifacts. Rust/Web keep target-failure/1. Source |
Unreleased complete failure: format: ess-target-failure/3 | Target and originating model provenance | Selected for accessor/selection plans, periodic causes or clock-reading attachments, including early failures. Includes bounded-output and required-periodic-host causes. Same envelope fields and no artifacts. Legacy models retain /1 or /2 output. Source |
More columns: swipe horizontally, or focus the table and use the arrow keys.
Composition selects commands from the component's accepts and views from its owned domains.
Its named-type traversal covers command inputs, event/error fields and query row shapes/fields,
but not view parameters. The imported digest identifies compiled semantics, not raw YAML, plan
bytes or a running endpoint. The generated Rust client restricts normal callers to selected
operation descriptors while forwarding &[u8] requests and Vec<u8> responses unchanged through
Transport<Authority>. Provider injection adds no authority verification or live model handshake;
the client does no payload admission, decoding or sanitization.
See the executed Todo example,
where both a String title and an incompatible numeric title reach the same selected command.
ess_synth::synthesize and synthesize_for return Result<Synthesis, TargetFailure>.
The direct rust::workspace and web::workspace APIs return Result<Vec<Artifact>, TargetFailure>
and Result<web::Emission, TargetFailure> respectively. Go and Clap workspace APIs
now also return Result<Emission, TargetFailure> in ESS 0.20.0. Rust checks allocation and representation
before rendering; Web checks its Rust prerequisite and Web codec allocation. Err withholds the
whole requested workspace, even if some modules could be emitted. Ok retains the existing
Synthesis fields and neutral plan bytes; partial Go/Web/Clap reports remain successful values.
Synthesis itself has no serialized envelope.
Facade, Rust, Web.
Each failure cause has a code, nonempty sorted unique sources, and nonempty detail; causes
are also sorted and deduplicated. Current codes are invalid-identifier, symbol-collision,
path-collision, recursive-layout, binding-assignment, missing-type-owner, wire-collision
and missing-representation. Unreleased format /3 also admits accessor-resource
when bounded accessor generation exceeds its output budget, and selection-constraint
when list selection requires invariant or reading validation outside its supported capability. A plan with zero capabilities can still fail. The typed error
implements Display and std::error::Error; it carries no independent digest.
Go checks every named type against the actual domain type rosters before package allocation,
including unreferenced types. A missing owner returns missing-type-owner with that qualified
type as its source; the existing Binary64 refusal takes precedence.
These checks do not constitute a universal compiler proof; internal coverage assertions remain,
and direct workspace calls require the plan for the supplied IR.
Error, API limits.
For a complete target failure, ess synthesize prints the text error or JSON/YAML envelope to
stdout and exits 1 before writing artifacts. It creates no output directory and leaves an existing
destination untouched. Successful text output still counts the neutral plan; partial target notes
are in TARGET.md/target.json. Later I/O failures have no new rollback guarantee.
CLI.
Schema imports and data realization
These surfaces are separate from full application synthesis. Structural data targets do not implement a model's lifecycle, and normalization executes only an explicitly checked recipe.
| Document | Reader and byte contract |
|---|---|
format: ess-schema-bundle/1 | Qualified component import. Bundle::read reimports retained source and compares the complete typed result, including selection and dialect. Pretty typed JSON plus LF; source_digest hashes exact retained UTF-8 source bytes. Source |
format: ess-schema-bundle/2 | Document-root import with explicit document_root identity and local definition closure. The same replay reader checks this shape; /1 cannot carry document-root identity and its existing bytes remain unchanged. Source |
format: ess-types-report/3 | Serialize-only structural target accounting: roots, declarations, configuration, annotations and obligations. Bundle input carries raw-source and complete-bundle identities; model input carries compiled-model, contract and model-schema projection identities. No report-file digest or persisted admission reader. Earlier /1 and /2 reports are not current writers. Source |
format: ess-normalization/1 | Closed recipe DTO, then normalize::Plan::read/check with supplied checked bundles. All branches and ordered stage boundaries check before execution. Canonical typed pretty JSON plus LF; parsing alone is not admission. Source |
format: ess-normalization/2 | Extends /1 with ordered text/list construction, original item indices, filtered mapping, first-match selection and explicit binary64 input/conversion declarations. The /1 checker refuses these additions; existing /1 canonical bytes and numeric admission remain unchanged. Source |
format: ess-normalization/3 | Adds compiler-owned model roots with complete provenance and explicit selected root sets. Plan::check_with_models requires sealed model selections; imported x-ess-* annotations cannot provide authority. Versions 1 and 2 refuse model roots. Model invariant obligations refuse until an executable evaluator exists. Generated targets use ess-normalization-target/2 for this recipe version. Source |
format: ess-normalization-target/1 | Serialize-only standalone library report from Plan::rust, Plan::go or Plan::typescript, with explicit target configuration, recipe, root/schema and emitted-file identities. Pretty typed JSON plus LF; no persisted report-admission API. It is not a full-synthesis target report. Source |
format: ess-normalization/4 | Adds explicit branch/field/items/root lexical capture through raw_json_inputs before first input-schema validation. Selected tokens become canonical standard base64; captures preserve duplicate members and numeric spelling while enforcing JSON grammar, Unicode and global depth 64. Capture/numeric overlaps refuse; decoded-value APIs require the text edge for capture branches. Versions 1–3 refuse the member, including an empty map. Source |
format: ess-normalization-target/2 | Report for format-3 recipes, retaining complete model-root identities and source/schema/file digests. Existing format-1/2 recipes retain target/1. Source |
format: ess-normalization/5 | Adds modeled finite Binary64 with explicit complete input policy, token-string binary64_literal, finite value-producing binary64 steps and two-typed-Binary64 IEEE equality. Formats 1–4 refuse selected Binary64 models and the new expressions; their qualified-schema numeric behavior and full emitted maps remain unchanged. Raw capture/helpers remain available. Source |
format: ess-normalization/6 | Adds closed positional_inputs declarations and checked position { value, index } reads. Explicit fixed-string-array policies prepare the first input into an exact closed tuple; raw capture and Binary64 remain available. Formats 1–5 refuse the new member and operation, retaining their complete emitted maps at the same generator version. Report version remains target/3. Source |
format: ess-normalization-target/3 | Report for every format-4, format-5 or format-6 recipe. The embedded canonical recipe and its digest bind input policies; first-stage schemas describe the prepared representation. Same report fields, new semantics; older readers must reject this version. No general report-admission API exists. Formats 1–5 preserve generated file maps through frozen legacy templates; generator versions remain truthful across releases. Source |
More columns: swipe horizontally, or focus the table and use the arrow keys.
The TypeScript normalization writer adds a package-bearing configuration arm local to normalization; structural TypeScript configuration remains separate. Recipes 1/2 retain target report 1, recipe 3 uses report 2, and recipes 4/5/6 use report 3. These are serialize-only reports, so the additional target needs no new report version. Its fixed schema profile and runtime files enter the existing file-digest map; unsupported constraints refuse before a report exists. Complete Rust/Go maps retain exact bytes at a fixed generator version.
Format-5/6 static checking adds equality for two typed Binary64 operands. The frozen runtime has a broader floating-pair branch: two floating representations compare numerically even in an admitted Integer expression. Mixed integer/floating pairs still require integer eligibility. TypeScript preserves that reference limitation without granting general Number equality or Binary64 output provenance. No core equality tightening is included in this target addition.
The following hashes are bare lowercase SHA-256, but have different input domains:
- Bundle
source_digest: original source bytes, not parsed or canonicalized JSON. bundle_digest: completeBundle::to_json()bytes, including retained source, dialect, root selection, format identity and final LF. A raw-source digest cannot replace it.- Model
projection_digest: completeModelTypes::to_json()JSON Schema projection bytes, including provenance and final LF. Its modelsource_digestandcontract_digestretain their separately defined semantic domains. Model projection - Normalization
recipe_digest: checkedPlan::to_json()bytes, including final LF. - Normalization
schema_digestandfilesvalues: exact emitted UTF-8 file bytes.normalization-report.jsonis deliberately excluded from its own file-digest map.
Component delivery
Every marker here uses the format key. Build/runtime/component inputs are closed DTOs followed
by compilation. Persisted IR, release, bundle, catalog and lock readers validate through generic
Serde as well as convenience readers; nested documents cross that boundary too. Revalidate mutable
values before use. These checks establish local consistency, with additional checks where authority
inputs are supplied; they do not prove remote artifact contents or authenticity.
Validation owner.
| Document | Independent version or identity | Reader / canonical digest |
|---|---|---|
ess-build/1 | Build/system and semantic references | BuildSpec DTO → compile_build; authored bytes have no canonical digest. Source |
ess-build-ir/1 | Compiled build identity | Checked BuildIr; pretty JSON, delivery-document digest. Source |
ess-runtime/1 | Exact ESS/realization/build references | RuntimeSpec DTO → compile_runtime; no raw-input digest. Source |
ess-runtime-ir/1 | Compiled runtime identity | Checked RuntimeIr; supplied-build validation is separate. Pretty JSON, delivery-document digest. Source |
ess-component/1 | Semantic major and release-unit names | ComponentSpec DTO → compile_component; no raw-input digest. Source |
ess-component-ir/1 | Component and semantic version | Checked ComponentIr; pretty JSON, delivery-document digest. Source |
ess-release/1 | Release SemVer, source commit and exact artifact/evidence identities | Checked ReleaseManifest; verify against supplied build/runtime where available. Pretty JSON, delivery-document digest. Source |
ess-release-bundle/1 | Independent runtime/chart releases | Checked ReleaseBundle and bundle verification. Pretty JSON, delivery-document digest, separate from the OCI registry manifest digest. Source |
ess-release-catalog/1 | Candidate semantic versions and release SemVers | Checked ReleaseCatalog; no whole-catalog canonical hash API. Source |
ess-stack/1 | Semantic-major and release SemVer constraints | Closed StackSpec DTO → resolver with catalog; no raw-input digest. Source |
ess-stack-lock/1 | Exact selected release versions/digests | Checked StackLock; pretty JSON, delivery-document digest. Source |
ess-environment/1 | Environment id and exact stack digest | Closed EnvironmentSpec DTO → deployment compiler; no raw-input digest. Source |
ess-deployment/1 | Exact stack and release identities | Checked DeploymentIr; pretty JSON, delivery-document digest. Source |
ess-deployment-diff/1 | Before/after deployment digests | CLI-produced added/changed/removed sets; no reader. Key-sorted pretty JSON; no diff-file digest. Source |
More columns: swipe horizontally, or focus the table and use the arrow keys.
Release and bundle /1 wire fields, canonical bytes and four required evidence kinds are unchanged.
Their validators establish consistency of declared metadata and relationships. Evidence.digest
is the OCI attachment manifest digest, not the SHA-256 of a report file. Provenance, SBOM,
signature and conformance entries remain declared attachments: attachment binding, producer origin
and artifact execution are unverified; signature verification is unsupported. Fetch additionally
checks OCI content identity without authenticating the evidence references inside a bundle.
Local release qualification uses existing report/2 plus an independent original suite/5 or fully admitted input/1 carrier and an explicit model/deployment context. It creates no new envelope or persisted assessment. Only the supplied nonempty complete all-pass selection qualifies; legacy report/1 readers remain unchanged and cannot satisfy this positive gate. Optional CLI/action raw pins cover the complete original report and selected suite/carrier files. They do not change any format's canonical digest profile or provide remote attachment proof. See the action migration.
Change and conformance records
| Document and discriminator | Separate identity | Reader and byte contract |
|---|---|---|
format: ess-diff/1 | Before/after compiled-model digests and specification majors | Legacy vocabulary/bytes retained; raw closed DTO → validated delta. Explicit legacy writing refuses new-only kinds. Pretty JSON; no delta-file hash. Writer, reader |
Default format: ess-diff/2 | Same endpoint identities | Supported delta majors are 1, 2 and 3; legacy changes retain /2. Admission checks ids, relations, order, uniqueness and same-system identity; serialization checks the selected vocabulary. Pretty JSON. Source |
Unreleased format: ess-diff/3 | Same endpoint identities | New periodic-cause, selection-plan and clock-reading-contract changes retain typed before/after values. Explicit /1 or /2 writing refuses these variants. Source |
Unreleased format: ess-diff/4 | Same endpoint identities | Error naming, command response declarations and response/generated payload source changes. Earlier delta writers refuse this vocabulary; legacy-only changes keep their existing formats. Source |
Current format: ess-impact/3 | Embedded versioned delta, optional suite and artifact identities | ess_diff::impact returns EssImpact with typed dependency relations; no persisted report reader. Pretty JSON; references input digests. Source |
Authored type: ess-scenario/1 or unreleased ess-scenario/2 | Domain/scenario identity and purpose | Closed authored DTO, then compilation against IR. /2 adds typed backend entity setup; /1 refuses setup fields. No raw-source canonical digest. Source |
Suite provenance.suite_version: ess-conformance/4 | Specification vN, model and whole-contract digests | Historical Deserialize/from_json parses an unadmitted DTO. Original-byte admission checks the closed, major-specific vocabulary before execution; serialize-once admission of a DTO binds only its newly serialized bytes. Suite bytes/defaults stay frozen; report/2 separately carries exact identity. Source |
Rust format: ess-conformance-report/1 | Model digest, implementation and suite-version claim | Checked closed reader validates version/counts/list/status; it does not establish exact-suite coverage or unique opaque result ids. Pretty JSON; unsigned u64 completed_at. Source |
Go format: ess-conformance-report/1 | Same claims, Go failed/skipped vocabulary | Generated Go writer; current Rust admission accommodates its non-pass vocabulary. Indented JSON+LF, signed int64 completed_at; no cross-producer byte/range equivalence is implied. Source |
Default detailed ConformanceReport: unversioned | Suite provenance, implementation, run/scenario identities | Detailed CLI JSON/YAML is distinct from standalone --report-out JSON. Serialize-only; pretty canonical JSON, no report-file or exact-suite hash. Source |
Opt-in ess-conformance-report/2 and ess-conformance-run/2 | Exact original suite/1–7 bytes, producer profile and five outcome categories | Separate standalone and detailed surfaces with paired readers. Sorted UTF-8 object keys, two-space JSON plus LF, exact unsigned u64 counts/timestamps. Ordinary coverage remains unknown; complete nonempty suite/5 or /7 selection can qualify. Suites /6 and /7 are unreleased. Count contracts |
Opt-in provenance.suite_version: ess-conformance/5 | Model/contract provenance and complete declared selection inventory | Closed original-byte admission retains source ownership, known outside IDs and every refusal occurrence. Explicit selections require exact parent input. Coverage contract |
Unreleased provenance.suite_version: ess-conformance/6 or ess-conformance/7 | Existing provenance; /7 also carries declared coverage | Conditional accessor, entity setup, selection, periodic and clock-observation vocabulary: /6 is ordinary, /7 retains the /5 coverage and exact-parent contract. Execution requires existing report/2; report/1 refuses before target callbacks. Existing /4 and /5 bytes remain unchanged. Accessor observation |
Unreleased provenance.suite_version: ess-conformance/8 or ess-conformance/9 | Existing provenance; /9 also carries declared coverage | Typed command-response observations compare an invocation's actual response with its emitted event payload. Structured text predicates requiring lossless literal decoding also select these versions. /8 is ordinary; /9 retains exact-parent coverage lineage. Rust and generated Go require report/2; older suite envelopes refuse the new vocabulary before execution. Browser execution retains explicit refusals for unsupported steps. |
format: ess-conformance-input/1 | Selected inner original bytes and full original parent chain | Closed format/suite_json/parent_suites carrier; complete admission checks original references and typed lineage. Only selected inner bytes are hashed. Coverage contract |
format: ess-conformance-replay/1 | Paired typed model, exact selected suite reference and input | Closed format/model/suite/input; browser admission precedes replay state. Reduced projection, no execution evidence or full model digest reconstruction. Replay contract |
More columns: swipe horizontally, or focus the table and use the arrow keys.
ess verify impact computes generated-artifact obligations from the compared models. The CLI
has no --generated option and does not inspect a committed output tree. The library API can accept
a GeneratedTree for that additional check. See Track specification change
and the impact implementation.
ConformanceSuite::to_canonical_json, Go/Web emit and Runner::run now return
Result with a located AdmissionError for unsupported Binary64 contracts. The
model producer/CLI guard also checks sparse models whose unsupported fields would
be absent from the suite. Suite readers and serializers reject the new primitive
under the existing suite vocabulary; no new suite version or float codec support
is implied. Existing admitted canonical suites retain their bytes.
Generated documents and external formats
| Document | Independent version/identity | Reader and bytes |
|---|---|---|
format: ess-docs/1 | Specification version and per-page provenance | Derived document/page parsing; explicit page-id and renderer checks are separate. CLI pretty JSON; nested String digests are not automatically profile-validated. Source |
format: ess-browser-catalog/1 | Specification version and plan provenance | Web writer/generated browser consumer; no general catalog-admission API. Key-sorted pretty JSON, whole-contract provenance. Source |
format: ess-service-interface/1 | source_openapi version and service.version | Retained structural DTO, then explicit validate; legacy integer, number and boolean unit variants discard unknown fields. Unchanged pretty JSON; no interface digest or durable import-accounting claim. Legacy files require original-source reimport for checked CLI projection. Source |
format: ess-openapi-import/1 | Fixed ess-openapi-service-subset/1 profile, admitted schema dialect and source version | Closed envelope; read_import refuses duplicate keys, reimports retained source and compares the complete interface, accounting and identity. Typed pretty JSON plus LF. source.sha256 is bare lowercase SHA-256 of exact retained UTF-8 source bytes, distinct from compiled-model identity. Old interface readers reject this wrapper. Source |
| JSON Schema draft 2020-12 | Specification version and ESS provenance; no generated root $id | ESS contract projection for external schema consumers. Pretty JSON, source/sliced stamps. An adopter-owned registry copy can add its own resource ID. Source |
| OpenAPI 3.1.0 from ESS | info.version and ESS provenance | ESS generation and HTTP synthesis; deterministic YAML or pretty JSON, source/sliced stamps. Source |
| OpenAPI 3.1.0 from imported interface | Interface service version | Checked CLI projection requires complete semantic accounting and resolved references; legacy or partial input refuses before output. Known annotation omissions may pass. The retained low-level interface API is structural. Deterministic YAML, no invented compiled-ESS digest. Source |
| AsyncAPI 3.0.0 | info.version and ESS provenance | ESS generation; deterministic YAML, source/sliced stamps. Source |
| ESS authoring schema, draft-07 | Describes source format/version syntax | cargo xtask schema; pretty JSON, complete-byte drift check. Schema validation does not resolve a whole specification. Source |
Rust HTTP startup JSON lines: log: ess/1 | Specification facts plus runtime language/address/port | Generated server output; compact lines, no whole-record hash. This shared marker value does not make the log a specification document. Source |
Go HTTP startup JSON lines: log: ess/1 | Shared specification facts plus Go runtime fields | Separate generated writer using shared startup facts; no log-admission reader or cross-language byte promise. Source |
More columns: swipe horizontally, or focus the table and use the arrow keys.
web::browser_catalog(ir, plan) -> BrowserCatalog remains a separate semantic catalog API with
unchanged ess-browser-catalog/1 bytes. It does not run the workspace's fatal feasibility gate;
catalog availability does not establish that a Rust/Web workspace can be emitted. When a Web
workspace is emitted, its catalog uses the same bytes. Catalog API.
Generated artifact maps, validation/refusal/adapter summaries, inspected declarations, interaction graphs, delivery/composition/realization diagnostics, infrastructure diagnoses and schema-validation reports are unversioned machine presentations. Their JSON/YAML can be saved, but there is no general ESS reader for those report files or an implicit whole-report digest. CLI owners, schema reports, infrastructure diagnosis.
Markdown, HTML, generated source code and build manifests follow their individual writers.
Kubernetes apiVersion/kind, Helm artifacts and BuildKit inputs use their external contracts;
they do not introduce another ESS format marker. Adopter-owned JSON Schema $id identifies its
schema resource independently of any digest. Neither the contract nor syntax schema generator
assigns that ID or a hosted schema endpoint. The
local registry workflow
adds only root IDs to separate copies and uses strict application envelopes with absolute payload
references. Original generated bytes, dialects, constraints and provenance remain intact; a copied
resource's model or slice digest is not its file checksum. Registry validation resolves the supplied
resources offline, and its successful records identify the selected envelopes. It does not establish
whole-system semantic validity or support in the separate restricted TypeScript projector.
Infrastructure records
The source-preview ess verify bindings command connects admitted realization selections to
native infrastructure observations. ess-observed-bindings/1 is a closed authored JSON/YAML DTO;
its binding digest hashes compact typed JSON after sorting bindings by id and sorting
declared evidence. It retains all authored image expectations and the exact realization digest.
ess-observed-bindings-report/1 is serialize-only, deterministic pretty JSON plus LF with no
whole-report digest or report-admission reader. It carries that binding digest, realization digest,
observation model digest and provenance, per-binding results and explicit exclusions. These
identities name different bytes. Missing evidence produces unknown, never an empty successful
comparison. Binding guide.
The namespace topology profile adds infra-observation/2, infra-ir/2, infra-graph/2,
infra-drift/2 and infra-simulation/2. Its closed coverage claim names the namespace and
namespace_topology profile. IR coverage belongs to the canonical model and its digest;
graph and drift retain that coverage, and simulation retains it in its typed unknown reason.
Version 1 bytes remain unchanged, and version 1 cannot carry version 2 qualifications.
See namespace collection
for omitted content, comparison restrictions and projection refusal.
| Document and discriminator | Independent identity | Reader and byte contract |
|---|---|---|
format: infra-observation/1 | Context, scan time, scanner release | Sanitized scanner output; permissive raw DTO → observation validation. Pretty JSON without an appended LF; scanner-reported hash covers those file bytes. It does not prove complete collection scope. Writer, reader |
format: infra-ir/1 | Observation provenance and model digest | read_document checks exact format, closed mirrors, hash and resolved-reference membership. CLI pretty envelope; infrastructure-model digest. Checked model transformations add no wire version or completeness proof. API, reader |
format: infra-spec/1 | Human-readable intent name and typed-intent digest | JSON/YAML → raw shapes → validated InfraSpec. digest() hashes the compact sorted typed intent; no canonical authored-file digest. Reader, digest |
format: infra-drift/1 | Before/after context and model digests | Serialize-only typed comparison; key-sorted pretty JSON. Context agreement does not prove equal collection scope. Source |
format: infra-simulation/1 | Intent name and snapshot digest | Serialize-only simulation with unknown outcomes; key-sorted pretty JSON, no simulation hash. Source |
format: infra-graph/1 | Context/namespace and source_digest | Serialize-only graph; pretty JSON. Its source digest names the InfraIR model, not EssIr. Source |
format: infra-projection/1 JSON, artifacts list | Intent name; provenance.snapshot_digest names InfraIR model, provenance.specification_digest names typed InfraSpec | ProjectionDocument contains emitted file contents and both input digests; key-sorted pretty JSON, no reader or whole-output hash. Source |
format: infra-projection/1 YAML, patches/objects lists | Same intent name, snapshot digest and typed-intent specification_digest | CLI serializes Projection directly, retaining both input digests. This differs from the JSON document despite the shared marker; no persisted reader. Type, CLI |
More columns: swipe horizontally, or focus the table and use the arrow keys.
Compatibility boundaries
Use the owning reader's validation API. The stamp reader accepts complete authoritative envelopes and supported profiles, including matching comment/structured copies where the writer emits both. Generic String deserialization does not perform that check. Cargo synthesis stamp recognition does not validate TOML, and a docs document has per-page stamps rather than one artifact stamp. Stamp reader.
Explicit report /2 and detailed ess-conformance-run/2 pair admitted original suite/1–7
bytes under sha256-json-bytes/1; support for /6 and /7 is unreleased. Ordinary suite/1–4 and /6 coverage remains unknown, including all-pass runs.
Suite /5 adds a closed declared inventory: exact selection, origin/source ownership, outside
scenarios and every refusal occurrence. Only nonempty all-pass execution with complete inventory
and no in-scope refusal qualifies for that exact selection. Suite/7 retains these rules with
extended observation/setup vocabulary. Legacy defaults remain suite/4, report/1 and diagnostic execution;
an extended suite requires explicit report/2. Suites /5, /6 and /7 with report/1 refuse before execution, including without an
output destination or with allow-incomplete. Report/1 keeps its historical non-pass aggregate and
does not establish exact suite-byte identity. Coverage workflow.
ess-conformance-input/1 has exactly format, original selected suite_json and nearest-first
parent_suites strings. Every explicit child needs its complete original parent chain. The selected
inner string is hashed, never the carrier or the reduced execution DTO; all surviving definitions,
dependencies, source mappings and refusal occurrences must agree. ess-conformance-replay/1 pairs
that input with the exact SuiteReference and a closed typed reduced model before browser state is
created. The player displays coverage but emits no evidence; it does not reconstruct the full model
digest, authenticate a publisher or fill the existing literal-assignment/view-evaluation omissions.
New counts and timestamps use exact unsigned decimal u64 tokens. Go's selected execution adapter
separately checks its host int width after admitting all parents, and its clock remains nonnegative
int64; Rust timestamps retain the full u64 range. Declared Node payloads retain finite binary64
meaning. Modeled Binary64 remains refused before conformance output. Impact with complete admitted
input retains ess-impact/3 and presents selection separately; unknown/incomplete input refuses.
A format catalog alone does not establish an installed external consumer upgrade.