Skip to content

spec(0.9.0): §3.5.2 said the reference producer does not emit param_histograms — it does - #10

Merged
coderoast-dev merged 1 commit into
mainfrom
spec/wire-emission-note-is-half-stale
Aug 25, 2026
Merged

coderoast-dev merged 1 commit into
mainfrom
spec/wire-emission-note-is-half-stale

Conversation

@coderoast-dev

Copy link
Copy Markdown
Collaborator

Change class: Editorial (GOVERNANCE.md §2) — editor merges, no version bump. No
normative sentence changes, no field's required/optional status moves, no document
changes verdict.

What was wrong

§3.5.2's Wire-emission status note said the reference producer (insight-metalog)
computes param_histograms, carries them through compose() in its internal
representation
, and "does not yet emit them on the wire".

It emits them. The block is serialised inside every top_k entry that has tracked
slots, whenever the producer's per-template slot-tracking cap is above zero. That cap
is off by default — which is the true half buried inside the false one, and why a
consumer still has to apply §3.5's absent-array rule — but the shipped batch
configurations set it above zero, so published documents carry the block, and the
producer has a byte-exact wire test pinning its key-sorted shape.

This spec already disagreed with itself about it. §11's size budget prices
param_histograms as a live wire cost and names its two undeclared producer parameters
as residuals of the envelope. That paragraph cannot be written about a block nobody
emits. Two sections described one field's wire status in opposite terms, and a reader
sizing a document was reading the informative one.

The scheduling clause, and why it goes rather than moves

The note gated emission on a magnitude-aware ordinal metric landing first, on the
argument that js_divergence over value_counts reads a numeric slot's support as
unordered. The argument is sound; the gate is not what answered it. A slot the
producer declares ordinal is routed to a different carrier and never appears in this
block at all. That is now stated as an exclusion — a property of the block, which a
reader can check — instead of a schedule.

It should not have been a schedule in the first place. This is a vendor-neutral
standard: GOVERNANCE.md §3 makes the reference implementation an oracle, not a release
calendar the spec text waits on.

The half that stands

MetaLogDiff.field_histogram_deltas is computed on every diff and is not
serialised. It now sits in its own paragraph so it cannot be repaired away together with
the first half. It is a declared limitation, not a defect: §13.2 makes the member
optional, so a diff carrying any other signal field satisfies the clause without it, and
it lands with the full-fidelity (batch) diff surface for §11's reason.

What is preserved verbatim

  • "When emitted, value_counts MUST serialise in a deterministic (key-sorted)
    order for replay bit-identity (§15.6)."
  • The batch-vs-streaming reasoning (§11's envelope) — re-attached to the two halves it
    actually governs.
  • The js_divergence order-blindness caveat, restated as the reason for the ordinal
    exclusion.

Checks

conformance/metalog_validate.py --selftest → SELFTEST PASSED: 16/16 fixtures, and
the shipped example validates CONFORMANT. Neither reaches prose; both are run because
the branch touches the repo the workflow gates.

…istograms — it does

The note has been half wrong for the whole life of the block, and the wrong half is
the half a reader prices a document by. `param_histograms` is serialised inside every
`top_k` entry that has tracked slots whenever the producer's per-template slot-tracking
cap is above zero; the cap is off by default, and the shipped batch configurations set
it above zero, so published documents carry the block. The note said the producer keeps
the histograms in its internal representation and puts none of them on the wire.

§11 already disagreed with it. The size budget prices `param_histograms` as a live wire
cost and states its two undeclared producer parameters as residuals — a section that
cannot be written about a block nobody emits. Two sections of this spec described the
same field's wire status in opposite terms, and the informative one was the wrong one.

The note also gated emission on a magnitude-aware ordinal metric landing first, on the
argument that `js_divergence` over `value_counts` reads a numeric slot's support as
unordered. The argument is sound and the gate was not what answered it: a slot the
producer declares ordinal is routed to a different carrier and never appears in this
block at all. That is stated now as an exclusion, which is checkable, rather than as a
schedule. A status note in a vendor-neutral standard should not be gated on any one
implementation's delivery milestones in the first place — GOVERNANCE.md §3 makes the
reference implementation an oracle, not a release calendar this text waits on.

The other half stands and is now stated on its own so it cannot be repaired away with
the first: `MetaLogDiff.field_histogram_deltas` is computed on every diff and is NOT
serialised. That is a conformant choice and not a defect — §13.2 makes the member
optional, so a diff carrying any other signal field satisfies the clause without it —
and it lands with the full-fidelity (batch) diff surface, for §11's reason.

No normative effect. The key-sorted `value_counts` MUST is unchanged, no field's
required/optional status moves, and no document changes verdict. What changes is the
spec's description of what the reference producer puts on the wire. Editorial under
GOVERNANCE.md §2.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@coderoast-dev
coderoast-dev merged commit 3dc993e into main Aug 25, 2026
1 check passed
@coderoast-dev
coderoast-dev deleted the spec/wire-emission-note-is-half-stale branch September 19, 2026 08:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant