[SimonHeybrock]

Stacked on #192 (base branch 184-adr-what-is-durable). Merge #192 first, or this PR lands in that branch, not in main.

First part of ADR 0009: a digest of a spec's interface in ess.spec, and a check for technique packages. Nothing in ess.apps changes yet; the next PR stores the digest in a workspace's log and reads a record of another spec as plain data.

The digest. WorkflowSpec.digest is a short hash of the name, type, and requiredness of every field of the params and outputs models, including the fields of groups nested in them. Two specs have the same digest when a request and an output stored under one still fit the models of the other.

class Centre(BaseModel):          # digest A
    x: float
    y: float

class Centre(BaseModel):          # digest B: a stored x no longer fits
    x_mm: float = 0.0
    y: float

What counts and what does not:

Counts	Does not count
a field's name, type, and whether it is required	titles, descriptions, defaults, constraints, validators
the fields of a group, at any depth	a group's class name or module, and the order of fields
the values of a Literal or an enum	the names of enum members
the metadata of a file field	the spec's own name and version
the root type of a RootModel; module and name of any other class

The check. A technique package keeps its specs' digests in a file and compares them in its tests, so a changed model without a new version fails in the author's CI:

DIGESTS = Path(__file__).with_name('spec_digests.json')
check_digests(specs, DIGESTS)   # AssertionError: the interface of loki-iofq/v1 changed: give the spec a new version, or ...
write_digests(specs, DIGESTS)

The file's entries must match the given specs exactly. LoKI has the file and the test.

Choices to be aware of.

• Requiredness of a param is in the digest although a stored request holds its defaults filled in. A param that becomes required breaks callers, which the check should report.
• A reference Referenced[T] counts by T's fields. Replacing T by another class with the same fields keeps the digest; that case is caught when an old reference is checked, since a reference fits by class.
• Changing the metadata of a file field, including the role of a raw file, changes the digest.
• Specs now refuse serializers attached with Annotated, as they already refuse serializers written as decorators: they change the stored form unseen. A type that is not resolved raises an error that names the field.

Review. A fresh reviewer probed for specs with equal digests whose stored forms differ, and for digests that change without reason. Fixed from it: a class that is not a group was described by its bare name, so two RootModel classes of one name with different content had the same digest; unresolved forward references were hashed by their text; the check passed when given no specs. The digest does not depend on the hash seed or on how a union or a list is spelled (Optional[X] and X | None agree).

Not done here. The serialized form of a spec does not carry the digest; that is settled where the digest is first compared, in the next PR.

🤖 Generated with Claude Code

[SimonHeybrock]

LGTM