spec(0.9.0): run_outcome and reservoir_delta are described — adr/0003's adoption arm

[coderoast-dev]

Additive under GOVERNANCE.md §2 — two new optional fields. The CHANGELOG entries join the existing ## [0.9.0] — unreleased section; v0.8.0 is still the last tag.

Executes the adoption arm of adr/0003 — decisions 1 (run_outcome) and 2 (reservoir_delta). This is the opposite move from the diff-root grant: those two members are standard-shaped, so they stay exactly where they are and become described. Nothing relocates.

Was stacked on #6 — both PRs edit the same CHANGELOG section, the same README row and the same diff schema. #6 has since been squash-merged, so this branch was rebased onto main and retargeted: its three commits are the only content here, and main is an ancestor of the head (a fast-forward, no conflict).

The sweep — every bare member at both roots, re-derived from the current wire

adr/0003 enumerated four members in August. Rather than trust that count, both document roots were re-derived from the reference implementation's serializer and compared, mechanically, against both schemas' root properties.

member	position	state today	disposition
run_outcome	MetaLog root	bare, undescribed	adopt — this PR (§2.5)
reservoir_delta	MetaLogDiff root	bare, undescribed	adopt — this PR (§13.7)
ruleset	MetaLog root	already relocated to extensions["fr.coderoast.ruleset"]	done
service_edge_delta	MetaLogDiff root	already relocated to extensions["fr.coderoast.service_edge_delta"]	done — #6 grants the placement it needed

The list is exactly those four, and after this PR both roots are fully described. The same comparison was run one level down at every position the schema closes — producer, window, source, stats, behavior, stability, cube, coordinate, provenance[], and the diff's current / previous / cube_diff — and found no member the schema does not describe.

One member outside the roots is worth naming, because no instrument here can see it. The reference producer writes a latency_shift key into cube_diff border-cell coordinates. §16.4 defines a coordinate's keys as axis names, and latency_shift is not among the declared axes — it cannot be, since cube_diff.axes must equal both inputs' cube.axes and this is a diff-time value. It is nonetheless schema-valid: a coordinate is a map, closed over its values and open over its key set, so no closed object and no root closure reaches it, and it is not reported as undescribed either. It is out of scope here and is left as-is; the disposition it wants is a reverse-DNS key, which a map admits without any spec change.

run_outcome — §2.5

A closed enum: success / failure / unstable / aborted. Same species as level and §3.8's component — a low-cardinality label the observed stream carries about itself — which is what makes it freezable vendor-neutrally today.

The normative half is where the value is:

• MUST be derived from the observed events, never from producer state or an out-of-band control plane. A field sourced from outside the window's bytes is not re-derivable from them, and §15's replay guarantee is the thing this format sells.
• MUST be omitted when no verdict was observed. There is no wire value for "unknown" — and that absence of an absence token is exactly what makes a missing member mean the same thing in every version of this spec, including every document written before this one.
• Consumers MUST NOT read absence as success.
• aborted carries a consequence: the observed stream is truncated, so every count in that document is a count over a stream that stopped early, and a template that looks vanished may simply never have been reached. A consumer that misses this reads a truncation as a behaviour change.

compose() was adr/0003's open question, and it is closed in the only direction that cannot assert something false. A composed document MUST NOT carry a verdict unless every input that carries one carries the same value. The ADR's conservative proposal — omit when inputs disagree — is right, but it needs absence to be defined as "this document asserts no verdict" rather than "no verdict was observed"; otherwise a composed document silently claims nothing was observed about a window in which two verdicts were. §2.5 states the wider meaning and lists all three causes.

The one place the spec and the shipped producer disagree

The values are lower-case. Every vocabulary this spec mints is lower-case — sketch_type (§6), cube.axes[].kind (§16.2) — and level is the deliberate contrast: its tokens come from the observed stream, not from here.

The reference implementation currently emits SUCCESS / FAILURE / UNSTABLE / ABORTED. Under GOVERNANCE.md §3 the spec wins and that producer is non-conformant on this member until it normalises. Four facts made this the right way to resolve it rather than widening the enum to match:

1. adr/0003 decision 1 — accepted by the editor — writes the vocabulary in lower case.
2. The same producer already spells its other minted enum, reservoir_delta's direction, in lower case. The upper case is an artefact of reusing an internal display spelling, not a wire vocabulary decision.
3. "Match what CI systems publish" does not settle it: Jenkins publishes upper case, GitHub Actions and GitLab lower case. The tie-break has to be this spec's own convention.
4. The cost is zero published bytes. The member has never reached a published surface, and the MetaLog format has no reader in that implementation — only a writer. README.md's implementation row now records the divergence rather than hiding it.

reservoir_delta — §13.7

§13 already carries a delta for every other stats block. Without this one a consumer cannot see change in the block that exists precisely to keep the rare-but-important single: a lone fatal that starts appearing, or stops, moves no count large enough to surface anywhere else in a diff. Structurally the same gap field_histogram_deltas closed in 0.8.0.

The rule an implementer would otherwise get wrong: membership is decided over top_k ∪ reservoir, never over reservoir alone. A template frequent enough for top_k in one window and only salient enough for the reservoir in the other has not appeared or disappeared — it moved between two retention mechanisms, and differencing the reservoirs alone reports that migration as a birth and a death, both false. §3.7.1 already makes the two blocks disjoint, so the union needs no precedence rule.

frontier_crossings reports a template present on both sides whose level crossed the {ERROR, FATAL} frontier — the same absolute frontier §16.10 forbids banding across.

• Frontier membership MUST be a set test, never an ordinal compare against ERROR. A level ladder carrying any value above FATAL would otherwise classify it as a failure by accident of ordering.
• A producer whose level vocabulary does not use those tokens MUST map onto the frontier or omit the list, and MUST NOT report crossings against a private frontier — the member's whole meaning is that two producers name the same boundary.
• direction is oriented previous → current and polarity-mute: a template leaving ERROR because its code path stopped running is not a repair, and this spec cannot tell the two apart, so that reading stays the consumer's.

count and salience are copied from the document the entry comes from, never re-derived at diff time — a diff is a statement about two documents, not a third computation over them. salience is comparable across the pair only because §2.4's gate already requires a matching retention_profile. §3.7.2.1 applies in full: across a template-text change the delta is re-selection, not signal.

§13.2's satisfying set gains reservoir_delta, because a diff whose only finding is a reservoir membership change is a correct document and the clause would otherwise reject it. The enumeration is loosened, never tightened. It stays hand-kept and still lags the schema by three members (stability_score, field_histogram_deltas, cube_diff); that correction belongs with the clause's rewrite, not with this adoption.

Why nothing here invalidates a 0.8.0 document

The only class that could falsify 0.9.0's "no conformant 0.8.0 document becomes invalid" is a 0.8.0 document carrying a bare root member named run_outcome or reservoir_delta in a shape the new schema rejects — a wrong-case verdict, an unknown member inside the delta block. Such a document validated at 0.8.0, because both roots are open.

It was never conformant. §7's placement rule (v0.8.0) is unambiguous: extensions is the only carrier of non-standard members, and a producer MUST NOT write vendor data as a bare member of a standard object at any depth, including objects the schema does not currently close. A member no spec text described is exactly that. So no §7-conformant 0.8.0 document carries a bare run_outcome or reservoir_delta at all, whatever its shape.

That generalises, and it is worth stating once: §7's placement rule is what makes every future root adoption additive. Since v0.8.0 the only legal home for an undescribed member is extensions, whose payloads are unconstrained — so describing a member at an open root can never invalidate a document that was conformant.

The rest is inert: §13.2 is loosened only; §2's table is informative; the shipped example is not normative.

Is a fixture owed?

Yes — one per document type, on the same test #6 used: what check does this introduce that nothing else in the set can distinguish? Describing a member at an open root turns "anything validates" into a closed vocabulary, and no existing fixture reaches either position. Neither, in fact, exercises an enum violation anywhere — every finding in the set was additionalProperties, required or pattern.

• invalid/run_outcome_vocabulary.metalog.jsonl — two documents, because one document carries one verdict and both arms are needed: failure must validate and must not be reported undescribed; SUCCESS must be rejected. SUCCESS is not an invented mistake — it is what the reference implementation emits today, so this fixture is the executable form of the divergence above, and it stops being red the day that producer normalises.
• invalid/reservoir_delta_direction.diff.json — a fully conformant new_salient entry beside a frontier_crossings entry spelling direction as increased, so the report must name the offending member rather than reject the block. direction is the right place for teeth: it is the one member here where a plausible synonym changes meaning.

Mutation-measured on all four ways a wrong adoption could look right. Remove either property and its fixture reds three ways — the finding disappears, the exit drops to 0, the member joins the undescribed list. Grant either as an unconstrained string / object — a schema that still "describes" the member to anyone skimming it — and the same fixture reds on the finding. 1 of 16 each time, nothing else moving.

Gates

leg	result
--selftest	16/16 · 5 controls armed · mirrored $defs agree
schema/metalog.v0.example.json (now carrying run_outcome)	1 document · CONFORMANT
published determinism evidence	10 sections · 17 documents · CONFORMANT — 0 invalid, 0 cap-exceeded, 0 undescribed
published diff documents	2 documents · CONFORMANT

19 published documents, verdict unchanged.

For the editor

• The 0.9.0 heading's — unreleased date is still yours. With this PR and spec(0.9.0): the extension container is granted at the MetaLogDiff root #6, adr/0003's Consequences are complete: both adoptions described, the diff-root placement granted, both relocations already executed by the producer.
• §2's top-level table gained two rows, not one: run_outcome, and coordinate — described in §15 and in the schema since v0.5.0, and missing from that table ever since. The second is beyond adr/0003's scope and rides in the run_outcome commit rather than its own; say the word and it comes back out.
• structural_role's values are spelled terminator in §3.7.1 and Terminator / GroupBegin in §16.2. It is an open string and this PR mints nothing for it, so nothing here depends on the answer — but the two spellings should agree before anything does.