Diagnostics | ESSEvery code and refusal name the ess specification, conformance, realization, composition and deployment commands print, what it means, and how to repair it.ESSreferenceessreferenceadopterdevelopertry-spec-driven-developmentreference

Diagnostics

ReferenceESS

ForAdopter · Developer

PreviewPublic

Source & revision

ess/website/docs/reference/diagnostics.md · b89faaa411bd

Every diagnostic ess prints for a specification, a scenario, a suite, a history, a realization, a composition or a deployment carries a stable code or name, and this page lists each one with what it means and how to repair it. A harness matches on the code. The sentence after it and the help: line are for the reader, and may be reworded between releases. The ess infra commands report their own findings and are not listed here.

Specification diagnostics: ESS-<FAMILY>-<NNN>

ess specify validate reports a defect in a specification twice: once under its validation name in brackets, and once as a compiler diagnostic with a code, a location and a repair hint:

  - [undeclared_reference] command.billing.invoice.CreateInvoice.outcomes.accepted.emits: `billing.invoice.InvoiceRaised` is not a declared event (hint: …)
  - error[ESS-COMMAND-001]: `billing.invoice.InvoiceRaised` is not a declared event

The code has two parts. The family says which part of the specification the defect is in, and the number says what kind of defect it is. A number means the same thing in every family: ESS-BINDING-002 and ESS-VIEW-002 are both type mismatches, one in a binding and one in a view. Any family can carry any class, so the two tables below cover every code.

Classes

Number	Class	Meaning	Repair
001	UNDECLARED	It names something nothing declares.	Correct the name to one that is declared, or declare what it names; the diagnostic lists what is declared.
002	TYPE_MISMATCH	Two types that have to agree do not, and no conversion says they may.	Make the two types agree, or declare a conversion between them.
003	UNREADABLE	It reads something its subject does not have.	Read a field the subject declares, or declare the field it reads.
004	CONFLICT	Two declarations contradict each other.	Change or remove one of the two declarations so they agree.
005	MISSING	Something required is absent.	Write the key or the declaration the diagnostic names.
006	DUPLICATE	The same thing is declared twice.	Rename or remove one of the two declarations.
007	EMPTY	It declares nothing, so it names nothing.	Declare at least one member, or remove the construct.
008	SELF_REFERENCE	It requires itself, so no value of it can exist.	Give the recursion a way to stop: make the reference Optional<…>, or add a union variant that does not refer back.
009	UNSUPPORTED	A construct or a version this build does not implement.	Use a construct and a format version this build reads, or run a build that reads them.
010	MISSPELLED	It nearly names something that is declared.	Use the declared name the diagnostic suggests.
011	LIFECYCLE	A lifecycle that cannot run: a dead end, an unreachable state, an unknown one.	Declare the state, or add the transition that reaches it or leaves it.
012	OTHER	A rule with no class of its own yet.	Follow the diagnostic's message and its help: line.
013	ACCESSOR_DEPTH	A bounded accessor has too many authored segments.	Shorten the path to the number of segments an accessor allows.
014	ACCESSOR_TRAVERSAL	An accessor reaches a deliberately unsupported traversal.	Map from a field that holds the value directly, not through a list, a map or a type that contains itself.
015	PARTIAL_ACCESSOR	A possibly unavailable projection fills a required input.	Fill the required input from a path that is always present, or declare the input Optional<…>.
016	ACCESSOR_RESOURCE	A plan exceeds its declared construction or output resource budget.	Simplify the mapping until it fits the stated budget.
017	NULL_COMPARISON	A predicate compares a fact with an unquoted null, which no fact value can be.	Test for absence with defined(x) or not defined(x), or quote 'null' to compare with the text.
018	UNSET_AT_CREATION	An invariant reads a required field that a creating branch leaves with no value.	Set the field with a sets: entry on the creating branch, or declare it Optional<…>.
019	IMPLIED_RELATION	A relation the specification relies on and does not declare, reported as a warning.	Declare the references relation the warning names, or the target's owns; a warning leaves the exit status and the compiled model unchanged.

Families

Family	Where it applies
SPEC	The specification as a whole: its header, a document that cannot be read, a predicate that does not parse, and anything with no better home. A refusal of a document's structure — a missing required key, an unknown key, a value of the wrong shape — stops that file at the first one; a predicate that does not parse does not, and is reported at its declaration beside the file's other refusals. A declaration with an unparsable predicate is withheld whole, so its own other refusals appear once the predicate parses; the file's other declarations are still checked and reported.
DOMAIN	A bounded context and what it declares as a whole.
TYPE	A named type, or a declared conversion between two types.
ENTITY	An entity: its identity, its fields, its lifecycle and its invariants.
COMMAND	A command: its input, its outcomes and their guards, and what an outcome creates:, sets: or fills in a payload:.
EVENT	An event and its payload.
ERROR	A declared error and its fields.
VIEW	A view: its source entity, its fields, its filter, its order and its parameters.
ACTOR	An actor and the commands it may: invoke.
BINDING	A binding: the event it reacts to, the command it invokes, its mapping from the event to the command's input, and its escalate:.
COMPONENT	A component and the constructs it owns.
TOPOLOGY	The topology: the workloads components are placed in.

Validation names

Each bracketed validation name is reported under the class below. Its family is the construct the defect is in, except unparsable_predicate and null_comparison, which are SPEC wherever the predicate is written.

Validation name	Class
empty_workflow	007 EMPTY
unknown_initial_state	011 LIFECYCLE
unknown_state	011 LIFECYCLE
dead_end_state	011 LIFECYCLE
unreachable_state	011 LIFECYCLE
duplicate_transition	006 DUPLICATE
unknown_principle	001 UNDECLARED
duplicate_principle	006 DUPLICATE
unknown_profile	001 UNDECLARED
unknown_workflow	001 UNDECLARED
unknown_protocol	001 UNDECLARED
unsupported_protocol_version	009 UNSUPPORTED
unsupported_format_version	009 UNSUPPORTED
unsupported_construct	009 UNSUPPORTED
accessor_depth	013 ACCESSOR_DEPTH
accessor_traversal	014 ACCESSOR_TRAVERSAL
partial_accessor	015 PARTIAL_ACCESSOR
accessor_resource	016 ACCESSOR_RESOURCE
undeclared_capability	001 UNDECLARED
undeclared_evidence_kind	001 UNDECLARED
rollback_on_irreversible_state	012 OTHER
capability_conflict	004 CONFLICT
production_write_without_approval	012 OTHER
unobservable_fact	003 UNREADABLE
unknown_phase	011 LIFECYCLE
version_mismatch	002 TYPE_MISMATCH
incomplete_rollback_policy	012 OTHER
self_reference	008 SELF_REFERENCE
empty_change	007 EMPTY
refusal_mutated_state	004 CONFLICT
unreconstructable_change	012 OTHER
unexplained_decision	012 OTHER
redaction_inconsistent	012 OTHER
event_payload_mismatch	002 TYPE_MISMATCH
incomplete_event_subject	005 MISSING
missing_causation	005 MISSING
misspelled_reference	010 MISSPELLED
undeclared_reference	001 UNDECLARED
duplicate_declaration	006 DUPLICATE
empty_declaration	007 EMPTY
missing_declaration	005 MISSING
conflicting_declaration	004 CONFLICT
type_mismatch	002 TYPE_MISMATCH
non_exhaustive_branches	005 MISSING
unreachable_branch	012 OTHER
invariant_reads_unset_field	018 UNSET_AT_CREATION
unparsable_predicate	012 OTHER
null_comparison	017 NULL_COMPARISON
implied_relation	019 IMPLIED_RELATION
path_segment_wire_name	012 OTHER

Authored scenarios: ESS-AUTHOR

An authored scenario file that cannot become a scenario is refused with one of these codes: by ess specify validate for a specification's scenarios: list, and by ess verify conform synthesize for the files it reads. The refusal names the file, and the scenario where the file said enough to name one:

refusal[ESS-AUTHOR-012]: `billing.invoice/authored/a-scenario` in a.yaml
  `billing.invoice.AllInvoices` is not a view this specification declares
  help: name a view the specification declares

Code	Meaning	Repair
ESS-AUTHOR-001	The file is not a document this format can read.	The document is YAML with the keys type, domain, scenario and summary; a key it does not know is refused rather than ignored.
ESS-AUTHOR-002	The document claims a format this build does not implement.	A scenario's type: is ess-scenario/1, ess-scenario/2 for entity setup, ess-scenario/3 for fixture values, ess-scenario/4 for direct responses, ess-scenario/5 for caller values, or ess-scenario/6 for member paths in claims; a document in a repository-defined trace format is not a scenario input, so leave it out of --scenarios and ess-inputs.yaml.
ESS-AUTHOR-003	Two files produce the same scenario id.	Two files name one scenario in one domain; rename one of them.
ESS-AUTHOR-004	The model declares no such bounded context.	Name a bounded context the specification declares, or add it to the model.
ESS-AUTHOR-005	The model declares no such entity.	Name an entity the specification declares; an authored scenario acts on the model's own instances and invents none.
ESS-AUTHOR-006	The model declares no such command.	Name a command the specification declares; a scenario that invokes anything else is checking a system this model does not describe.
ESS-AUTHOR-007	That command declares no such branch.	Name one of the branches the command declares, or declare the branch you meant.
ESS-AUTHOR-008	The model declares no such actor.	Name an actor the specification declares, or drop actor:.
ESS-AUTHOR-009	The actor is declared, and the specification does not grant it this command.	Grant the command to this actor with may:, act as one that already has it, or write refused: not_granted where the act expects the refusal.
ESS-AUTHOR-010	The model declares no such event.	Name an event the specification declares.
ESS-AUTHOR-011	The model declares no such error.	Name a declared error the specification declares.
ESS-AUTHOR-012	The model declares no such view.	Name a view the specification declares.
ESS-AUTHOR-013	A value is supplied under a name the surface does not declare.	Name a field the construct declares; the scenario and the model disagree about what it has. A dotted key is a member path, which a claim reads from ess-scenario/6 and nothing else reads.
ESS-AUTHOR-014	A declared field that has to be supplied is not.	Supply the field; a command is invoked with all of its input, and one left out is a call that could not be made. A nested value in a claim is compared whole, so write every member it declares, or from ess-scenario/6 claim one member alone by its path, member.leaf: value.
ESS-AUTHOR-015	A value is not of the shape its declared type calls for.	Write a value of the type the model declares there.
ESS-AUTHOR-016	A value names something a declared enum does not have as a variant.	Write one of the variants the enum declares; the set is closed.
ESS-AUTHOR-017	A value names a lifecycle state the entity does not declare.	Write one of the states the entity's lifecycle declares.
ESS-AUTHOR-018	A reference names an instance the arrangement does not declare.	Declare the instance under arrange:, so the scenario says whose it is.
ESS-AUTHOR-019	A reference names an instance nothing has bound yet.	Capture the instance from an event before the step that names it; a suite carries no identity of its own.
ESS-AUTHOR-020	A reference reads an event no earlier act required.	Require the event in an earlier act; a value is read off an occurrence the run produced, and this scenario has not required one.
ESS-AUTHOR-021	A reference sits where the suite compares values it carries itself.	Write the value the field must hold; an event's payload and an error's fields are compared against values the suite carries.
ESS-AUTHOR-022	An instance is bound to a field of a type that is not its entity's identity.	Bind the instance to a field typed as the entity's identity, or arrange the entity whose identity this field carries.
ESS-AUTHOR-023	The timeline's instants do not strictly ascend.	Give each act an instant later than the one before it; the file's order is the scenario's order and at: is what states it.
ESS-AUTHOR-024	A position or an order is asserted of a view that declares no order.	Declare order_by: on the view, or assert contains: instead; a position in an unordered view names a different row on every read.
ESS-AUTHOR-025	An assertion states other than exactly one claim.	State exactly one of contains, excludes, counts, ranked, at, satisfies or halts_after per assertion.
ESS-AUTHOR-026	A predicate reads something the view does not publish.	Read only fields the view projects, or project the field the predicate reads.
ESS-AUTHOR-027	The scenario runs no command and asserts nothing.	Give the scenario a timeline; a scenario that runs nothing is a check that cannot fail.
ESS-AUTHOR-028	A window is measured from an instant nothing marked before it.	Write mark: on the earlier act the window opens at; a duration is measured from an instant somebody named, never from wherever the step before it happened to end.
ESS-AUTHOR-029	Two acts mark the same instant.	Give the two acts different names; one name for two instants is a window whose length depends on which one a reader had in mind.
ESS-AUTHOR-030	A window has no width.	Give the window a length; a window of no seconds is a claim about no time, and there is no target it can fail against.
ESS-AUTHOR-031	A bounded negative forbids no occurrence.	Name the events the window must stay clear of; a bounded negative that forbids nothing is satisfied by every implementation there is.
ESS-AUTHOR-032	The timeline's own instants say something the window contradicts.	Move the act's at: so the file's own instants agree with the claim, or state the length the file already shows; the timeline is what a reader believes.
ESS-AUTHOR-033	A window states other than exactly one bound.	State exactly one of not_before, within or quiet per window, and write a second window for a second claim.
ESS-AUTHOR-034	An early stop is claimed after no rows at all.	Say how many rows the reader takes before it stops; a reader that takes none never sees a row and so never says stop, and what a source produced before being refused its first row is a different answer in two implementations that are both right.
ESS-AUTHOR-035	An assertion's paths resolve, but its operands or quantified target are ill-typed.	Use compatible scalar operands and quantify only over a declared List or Map.
ESS-AUTHOR-036	The model holds a Binary64 where the conformance suite does not carry one.	A suite carries a finite Binary64 in an entity's fields, a command's input and response, an event's and an error's fields, and a view's fields and row shape; move it out of an entity identity, a view parameter, an actor attribute, a binding or a conversion, or use a Decimal there.
ESS-AUTHOR-037	An act claims what only an external answer it does not state satisfies.	No input the act sends decides an external branch, so name the act's own one under outcome: and the suite configures that answer for its call; an answer a command invoked through a binding must give cannot be stated in an authored act, so drop the claim there and leave it to synthesis.
ESS-AUTHOR-038	An act expects the refusal an ungranted actor gets, and the actor holds the grant.	Act as an actor the specification does not grant the command, or drop refused: not_granted and claim what the command answers.
ESS-AUTHOR-039	An act expects the refusal an ungranted actor gets, and names no actor or claims what only a command that ran answers.	A refused command takes no branch, reports no declared error and returns nothing: keep actor: beside refused: not_granted, drop outcome, error, response, events and capture, and list under no_events: what must not appear anywhere in the target's log after the refused send.
ESS-AUTHOR-040	An act sends a served command no actor is granted, which every caller is refused.	Grant the command to an actor with may: and send the act as that actor, or write refused: not_granted with an actor: the specification declares.
ESS-AUTHOR-041	An act expects a branch the command's guards do not take for the input it sends.	Send an input the expected branch's when: admits and no branch answered before it claims, or expect the branch that input takes: input-guarded refusals answer first, the first declared of them, then accepting when: and external branches in declaration order, and the default only where no when: holds.
ESS-AUTHOR-042	An act states an exact value for a field the outcome marks {generated: true}.	The implementation mints a {generated: true} field, so an exact value passes only where it happens to mint that one: in an event's payload or an error's fields, drop the field from the expectation, and the suite still checks its presence and type there, or relate it to another value with capture: on the event; in a view row, drop it and assert satisfies: defined(<field>) on the view, which requires it on every row and at least one row, or state its relation to an event's value with {$observed: {event: …, field: …}}; from format: ess/30 an exact value there is the scenario's own claim, which the suite checks as written.
ESS-AUTHOR-043	An act reads the head of an order declaring ties: unordered, and the arranged rows tie on every key and rank first.	The model leaves the order of tying rows to the implementation, so a head chosen among them is no particular row: arrange the rows so that one ranks first on the keys alone, or declare a total order ending in the identity where the model fixes how ties break.
ESS-AUTHOR-044	An act sends a command the system issues itself as a system actor.	No caller can be the system: name no actor:, and the act awaits the system's step; to check that an outside caller cannot issue it, name an actor the specification does not grant it, with refused: not_granted.
ESS-AUTHOR-045	An act awaiting a command the system issues itself names no record to await it on.	State the input the outcomes name as instance: under input:, a literal or {$instance: name}; a step the system takes to create a record, or over rows with no subject, is not awaited in this release.
ESS-AUTHOR-046	An act expects a refusal of a command the system issues itself and claims what only an issued command answers.	A refusal of the system's own step is checked as nothing issued within the bound, none of its events published: state only the instance under input:, and drop error, response, events and capture.
ESS-AUTHOR-047	A mapping in the document repeats a key.	Write each key once; YAML keeps only one of two equal keys, and which one is not the author's choice.

Synthesis: ESS-SYNTH

ess verify conform synthesize reports a construct it could build no scenario for with one of these codes, beside the suite rather than instead of it. The help: line can be more specific than the repair below, because some refusals carry the reason that decides it:

refusal[ESS-SYNTH-011]: entity billing.invoice.Invoice has no scenario `…`
  `reminder_count >= 0` reads what no view of `billing.invoice.Invoice` publishes
    - `reminder_count` is published by no view of the entity
  help: publish the fields the invariant reads in a view of this entity, or state the invariant over what one already publishes

Code	Meaning	Repair
ESS-SYNTH-001	No value of the command's declared input type could be constructed at all.	Give the field a type that has a finite value, or drop it from the command's input; where the reason names a view, declare the view of the entity it asks for, projecting its identity, its state and the fields named; where it names rows a filter selects, let a command that creates the entity write each field the filter reads, from an input or from a caller attribute.
ESS-SYNTH-002	The guard could not be decided against a candidate, and no other candidate would change it.	The guard reads something no input can supply; correct the path or the type it walks into.
ESS-SYNTH-003	Every candidate this synthesizer knows how to try was refuted.	Write the branch's condition over values a candidate can carry, or supply a fixture for it.
ESS-SYNTH-004	The scenario needed an instance of an entity, and the specification cannot arrange one.	Give some outcome creates: for the entity, or declare a transition and an outcome that reach the state; where the route runs through a branch no input reaches, repair that branch's own refusal.
ESS-SYNTH-005	A view's filter could not be decided against the state the scenario reaches.	Filter the view on the entity's state, which is what a generated scenario knows after the command it ran.
ESS-SYNTH-006	A construct this build does not synthesise yet.	Nothing to change in the specification; cover the construct with an authored scenario until a later release synthesises it.
ESS-SYNTH-007	Two declarations produced one scenario id.	Two declarations produced one scenario id; rename one of them.
ESS-SYNTH-008	The branch is selected in a way this scenario family cannot arrange: by the subject's stored fields, or by a row of another entity (when_related:).	Cover the branch with an authored scenario (ess-scenario/1); where the help: line says two parts of ess have drifted apart, that is a defect in ess to report.
ESS-SYNTH-009	A value synthesis built is not a value of the input's declared type.	Nothing to change in the specification; this is a defect in ess to report, with the specification that produced it.
ESS-SYNTH-010	A binding clause has nothing a scenario could observe.	Follow the help: line, which names the gap: an event nothing emits, a flow with no consequence, an invocation that maps nothing, a failure no scenario can force, or a drop or at_most_once policy that is unobservable by design.
ESS-SYNTH-011	An entity invariant nothing observable reads.	Publish the fields the invariant reads in a view of this entity, or state the invariant over what one already publishes.
ESS-SYNTH-012	A command attempted in a state none of its transitions run from declares no outcome for that refusal.	Give the command a wrong_state: outcome naming the error it reports; the states it answers in are already declared, as the states its transitions do not run from.
ESS-SYNTH-013	A value object's declared invariants, with nowhere observable to read them.	Publish a field that holds a value of this type in some view, directly or inside a list, a map, a union or an Optional; where one is published, declare an outcome that leaves an instance the view shows, with that field set from a value the command sends.
ESS-SYNTH-014	A view declares an order and the scenario cannot put two rows in it.	Declare an outcome that can leave a second instance where this view shows one, or drop order_by:; an order over one row is a claim no implementation can fail.
ESS-SYNTH-015	A binding's mapping uses a native accessor whose expected result cannot be reconstructed from what a scenario observes.	Provide a separately executable host conversion or an unambiguous observable assignment.
ESS-SYNTH-016	An aggregate view whose rows this scenario cannot keep apart from every other scenario's.	Group by, or filter by a parameter over, a String or Uuid field the creating command sets from its input.
ESS-SYNTH-017	An aggregate view the arrangement cannot produce rows for as the page's pattern requires.	Let the creating command set every field the view groups by or aggregates from its input, and read a parameter only as field == param.name at the top of the filter.
ESS-SYNTH-018	A guard compares a .count with a number whose boundary lies past what this synthesizer builds.	The guard compares .count with a value above the 1024 this synthesizer builds; cover the branch with an authored scenario (ess-scenario/1), or lower the bound.
ESS-SYNTH-019	A synthesized step requires a branch for an input its own guard refutes, or another branch answers first under the precedence order.	Nothing to change in the specification; this is a defect in ess to report, with the specification that produced it.
ESS-SYNTH-020	A reference a {related: …} value follows may be absent, and no arrangement leaves it absent to witness the absent value; the branch's scenario stands without it.	Fill the reference from an Optional input that the branch, or the branch creating the row that holds it, can be sent without; or cover the absent value with an authored scenario (ess-scenario/1).
ESS-SYNTH-021	An invariant compares two Timestamp facts without the tag that compares them as instants.	Write the comparison in an ess/22 source, which tags it, or write {compare: {left, op, right, as: timestamp}}.
ESS-SYNTH-022	No input was found where one child of an any/all alone decides it and it decides the guard; the branch's scenario stands without that input. An admitted authored scenario that sends such an input and expects the branch withdraws the refusal.	Cover the child with an authored scenario (ess-scenario/1) that sends an input where it alone decides the connective, or write the guard so that such an input exists.
ESS-SYNTH-023	A command the system issues itself, whose outcome addresses no existing record (creates:, or no instance:), has no awaited scenario, and is not driven in its place.	A step the system takes to create a record, or over rows with no subject, is not awaited in this release; grant the command to a caller as well to keep it driven, or move the step onto an existing record that its outcomes name with instance:.
ESS-SYNTH-024	A refusal of a command the system issues itself is decided by its input, or by rows its input names, which the system chooses; no scenario claims it.	Cover the refusal with an authored scenario (ess-scenario/1) that arranges the rows the system chooses among, so that every choice is refused, and expects nothing to be issued.

Mutation audit: ESS-MUTATE

ess verify conform mutate reports an audit it cannot run, or a mutant it cannot score, with one of these codes. ESS-MUTATE-001 and ESS-MUTATE-003 refuse the whole audit and exit 3; the others are the verdict on one mutant.

Code	Meaning	Repair
ESS-MUTATE-001	A baseline scenario failed or ended error against the target, so no failure under a mutant can be shown to be because of the mutant.	Make the unmutated suite pass against the target first; a scenario reported unsupported or skipped is not scored and does not cause this.
ESS-MUTATE-002	A mutant was refused by assemble or compile, so there was nothing to run.	Nothing to repair in the specification; the mutant is reported and not scored.
ESS-MUTATE-003	The selected mutant classes found no site in this specification, so the audit would run nothing.	Select classes that apply to the specification, or leave --class out to run every class.
ESS-MUTATE-004	A mutant's suite gained synthesis refusals the baseline's does not have, or asks exactly what the baseline's asks, and no scored scenario failed, so passing it says nothing about the mutant.	Repair the synthesis refusal the verdict names, or declare what makes the change observable, so the suite has a scenario for what the mutant changed.
ESS-MUTATE-005	A guard mutant left its outcome's guard satisfied by no input: the rule it wrote is dead, not missed.	Nothing to repair in the implementation; read the named guard, which no input can satisfy under the mutation.

Recorded histories: history.*

ess verify conform check-history and ess verify conform import-history refuse an ess-history/1, ess-history/2 or ess-history/3 document they cannot admit under one of these names, before any operation is checked. The message is the name, a colon and the detail:

history.no-clients: `clients` is 0

Name	Meaning	Repair
history.malformed	The bytes are not an ess-history/1, ess-history/2 or ess-history/3 document: not JSON, an unknown or missing field, a value outside its declared type, a decision_time that is null, not the one spelling of an instant, or in an ess-history/1 document, an input, events or arranged that is null or in a document below ess-history/3, a key written twice inside an input or a payload, or a number there in another spelling than its one.	Write the document as schemas/ess-history.schema.json describes; the detail names the field or the position.
history.unsupported-format	The format is absent, or names a format this build does not read.	Write format: ess-history/1, ess-history/2 where an operation records a decision_time, or ess-history/3 where one records its input, events or arranged.
history.spec-digest-mismatch	The history was recorded against another specification.	Check the history against the specification it was recorded against, or record it again against this one.
history.no-clients	The history counts no clients.	Set clients to the number of clients that sent operations.
history.duplicate-operation	Two operations carry one identity.	Give every operation its own identity.
history.client-out-of-range	An operation names a client at or above clients.	Number clients from 0 to clients minus 1, or raise clients.
history.returned-without-return-instant	An operation is Returned and carries no return instant.	Record returned_at for an operation that returned, or mark it Indeterminate.
history.return-before-invoke	An operation's return instant precedes its invoke instant.	Record instants from one clock, so an operation returns at or after it was invoked.
history.indeterminate-with-return-instant	An operation is Indeterminate and carries a return instant.	Drop returned_at, or mark the operation Returned if it did return.
history.indeterminate-with-outcome	An operation is Indeterminate and carries an outcome.	Drop outcome, or mark the operation Returned if it did return.
history.indeterminate-with-rows	An operation is Indeterminate and carries rows: a read that never answered answered no rows.	Drop rows, or mark the operation Returned if it did return.
history.indeterminate-with-events	An operation is Indeterminate and carries events: a call that never answered published nothing anyone saw.	Drop events, or mark the operation Returned if it did return.
history.returned-without-outcome	An operation is Returned and carries no outcome.	Record the outcome the operation returned.
history.non-canonical-uuid	A UUID is written with upper-case hexadecimal; its one spelling is lower case.	Write the UUID in lower case.
history.integer-out-of-range	An integer is above the largest integer a history admits.	Keep the value at or below the bound the message states.
history.retry-of-unknown	An operation's retry_of names no earlier operation of the same client and command.	Name the earlier operation this one sends again, from the same client and command, or drop retry_of.

Realization

The ess specify realization commands refuse a realization document with one of these categories, each at the path in the document it concerns:

- UnresolvedReference at components: component `ledger` is not declared by the ESS

A JSON report spells the category in snake case, shown second.

Category	Meaning	Repair
UnsupportedFormat (unsupported_format)	The document's type is not a realization format this build reads.	Write a realization format this build reads; the message names the ones it accepts.
SpecificationMismatch (specification_mismatch)	The realization names a different ESS system, version or digest than the specification it is compiled against.	Compile it against the specification it names, or update specification: to the system, version and digest of this one.
DuplicateIdentity (duplicate_identity)	A list declares the same identity more than once.	Remove or rename the repeated entry.
UnresolvedReference (unresolved_reference)	A component, actor, semantic surface or implementation it names is not declared.	Correct the name, or declare what it names in the specification or the realization.
ReferenceOutsideRealization (reference_outside_realization)	A component or actor lies outside the part of the system this realization declares.	Add it to the realization's components or actors, or stop referring to it.
ImplementationCoverage (implementation_coverage)	A component has no implementation, or more than one.	Give every component exactly one implementation.
EmptyDeclaration (empty_declaration)	No component, implementation, entrypoint or surface was declared where one is required.	Declare at least one of what the message names.
PrimaryEntrypoint (primary_entrypoint)	No entrypoint, or more than one, is marked primary.	Mark exactly one entrypoint primary.
InvalidValue (invalid_value)	An invocation, artifact locator, synthesis identity, title or summary is malformed.	Write the value in the form the message describes.
SecretValue (secret_value)	Invocation text looks like a credential rather than a reference to one.	Name an environment or credential source that supplies the value, instead of writing the value in the invocation.

Build, release, stack and deployment

The build, component, release, stack and deployment commands under ess generate share one set of categories. Each diagnostic also names the stage that has to resolve it:

[missing_binding:Deployment] …

Category	Meaning	Repair
unsupported_format	The document's format marker is not one this build reads.	Write a format this build reads, or run a build that reads this one.
duplicate_identifier	One identity is declared more than once.	Remove or rename the repeated declaration.
unknown_reference	A reference does not resolve in the inputs it is resolved against.	Correct the name, or supply the input that declares it.
dependency_cycle	The declared dependencies form a cycle.	Remove one dependency so the graph has an order.
invalid_value	A value is not valid for what it declares.	Write the value in the form the message describes.
unpinned_input	A remote or base input has no immutable identity, such as a digest.	Pin the input by digest.
undeclared_secret	A build step asks for a secret the build interface does not declare.	Declare the secret in the build interface, or stop asking for it.
missing_output	A stage does not produce a named artifact it is required to.	Declare the output the message names.
missing_component	A component of the specification has no runtime realization, or more than one candidate for it.	Realize the component exactly once in the runtime document.
duplicate_component	A component is realized more than once.	Keep one realization of the component.
missing_evidence	A release lacks provenance, an SBOM, a signature or conformance evidence it requires.	Supply the evidence the message names before releasing.
digest_mismatch	A claimed content digest differs from the digest of the input supplied.	Supply the input the digest names, or update the digest to the input's.
unsatisfied_constraint	No released system satisfies a requirement of the stack.	Relax the requirement, or release a system that satisfies it.
missing_binding	A required environment coordinate is not bound.	Bind the coordinate the message names in the environment.
authority_unbound	A required authority or service-account binding is absent.	Bind the authority or service account the message names in the environment.
secret_value_forbidden	Credential bytes appear where only a reference to a secret is allowed.	Replace the value with a reference to the secret that holds it.

Composition

ess specify compose refuses a composition document with one of these categories:

[unknown_component] …

Category	Meaning	Repair
unsupported_format	The document's format marker is not one this build reads.	Write a composition format this build reads.
duplicate_service_key	Two imports declare the same service key.	Give each import its own key.
duplicate_service_identity	Two imports bind the same ESS system, version and component.	Import each system, version and component once.
missing_service_input	No compiled specification was supplied for a declared import.	Supply the compiled specification for the import, or remove the import.
undeclared_service_input	A compiled specification was supplied that the document does not import.	Import it in the document, or stop supplying it.
duplicate_service_input	The same key was supplied more than once.	Supply each import once.
system_mismatch	The compiled specification names a different system than the import.	Supply the specification of the system the import names, or correct the import.
version_mismatch	The compiled specification's version differs from the import's.	Supply the version the import names, or update the import.
digest_mismatch	The compiled specification's digest differs from the import's.	Supply the specification the digest names, or update the digest.
unknown_reference_service	A reference names a service the document does not import.	Import the service, or correct the key in the reference.
unresolved_semantic_reference	A name does not resolve in the service its key selects.	Correct the name to one the imported specification declares.
unknown_component	The imported specification does not declare the selected component.	Select a component the imported specification declares.
reference_outside_component	A name exists in the imported specification but is outside the selected component.	Select a component the detail names, or widen the selected one by the name's kind: add a type's or view's domain to its owns, or a command to its accepts. Under ess-composition/1 a type is exported only where the component's commands, events, errors or views reach it. An event is exported by a component that publishes it or accepts a command that emits it, an error by one that accepts a command that raises it.
type_conformance_drift	A local type or payload said to conform to an imported type or payload differs from it in kind, or in a field's name, presence or type; from ess-composition/5 also in a value constraint (alphabet, prefix, invariant) or an enum variant attribute.	Change the local type or payload to match the imported one field for field, and constraint for constraint under ess-composition/5.
unknown_role_service	A role's service or plays names a service the composition does not import.	Import the service, or correct the key in the role.
conflicting_role	A role plays its own service, repeats a role already declared for the same two services, or repeats a command entry.	Name another imported service in plays, and write each role and each command entry once.
role_input_drift	A local command said to implement a contract command lacks one of its input fields, reads one as another type, or requires an input the contract's caller never sends.	Give the local command every contract input field with a conforming type, make its other inputs optional, or say gates if it only decides before the contract command.