spec: the temporal and located companion declarations (issue #410)

[espg]

Refs #410 — step 4 of the consolidated plan and its correction. Spec-only: the contract, the conformance fixtures, and the writer-side declaration seams. The kernel/pipeline PR (plan step 5) implements the fold and read behavior; nothing here folds or reads a companion.

PR #446 landed §8's domain-neutral word-typed declaration — {spec, shape, grammar} with the shape vocabulary {"coordinate", "per-cell", "per-centroid"} and the mortie-toc/1 token — and instantiated only "coordinate". This PR instantiates the two remaining shapes and the located (spatial) family under the same pattern.

What lands

§8.2 shape: "per-cell" — a dense uint64 array on the cells axis, index-aligned with morton, fill_value: 0 reserved as the unobserved-cell marker — and the reservation is stated as cost-free, since no mortie-toc/1 encoder emits 0 and word 0 decodes as the empty range [0, 0) (see the fold on the review thread, and withdrawn question 4 below). A cell covering one observation is an exact timestamp word; a pooled cell a conservative range. The pooled word is stated as the grammar's toc_merge join (associative/commutative/idempotent ⇒ bit-identical under any fold tree) — envelope semantics only, with no zagg fold implementation detail specified.

§8.3 shape: "per-centroid" — a zagg-ragged/1 uint64 sibling sharing the digest's per-cell row counts, bound from the payload array by a spec-owned times key. Exact instant while a centroid is a single observation, conservative envelope once merges pool. Stored word order is the payload's §2.1 value order, so the section carries §8.1's "do not bisect" warning explicitly. A closing contract clause records the ruled overview policy: leaf "per-centroid" and overview "per-cell" coexist in one product, each array read through its own declaration.

§8.4 composition / merge legality — scoped to the companion shapes (§8.2/§8.3): the time-axis join rule is §8.1's, which takes precedence wherever both could be read to apply, and §9.2's wholesale import inherits that bound. The two differ exactly on absence, deliberately — an undeclared companion carries no information (compose, drop the channel), an undeclared coordinate array carries the legacy encoding, which is information, so §8.1 MUST-refuses a legacy ↔ zagg-toc/1 axis join. The section then names two distinct operations rather than one ambiguous "match": a peer join (contributors match each other on {shape, grammar}, MUST-refuse otherwise, result inherits their shape — the §2.0 weights-gate pattern) and a shape-coarsening reduction, licensed explicitly for the ruled "per-centroid" → "per-cell" overview fold (contributors peers of each other; output declares the coarser shape; output word for cell i is toc_merge over that cell's centroid words; grammar and spec never move). A reduction can never satisfy the peer gate by construction, which is why it needed naming rather than inference — as written before, a conforming writer could not produce the ruled overview and a conforming reader could reject it. No other cross-shape combination is defined. An absent declaration is never a refusal, and both consequences bind reductions as well as peer joins. The two normative consequences are unchanged: a composed result must not carry a declaration unless every contributor carried one matching the others' (dropping the channel is the honest outcome — a word omitting an undeclared contributor is not a conservative envelope), and an undeclared store supports no temporal subsetting, which a reader must report rather than approximate.

§9 zagg-located/1 — the located companion under the same pattern, key located, grammar: "mortie-morton/1", stamped on the {field}_locations sibling. Absent key ⇒ §2.2 verbatim, never a refusal. §9.1 adds the overview semantics §2.2 does not cover: an overview centroid's word is the deepest common ancestor of every contributing observation, so one array's words sit at heterogeneous orders and a reader must decode each word's order rather than assume one per array/level/store. The mortie-morton/1 citation names mortie spec §1 (bit layout) and §4 (encoding-carried kind), both enumerated as frozen for 1.x by its §10 — i.e. the same class of citation §2.2 already makes, and explicitly stronger than §8's toc pointer (which §8 already discloses as weaker, pending espg/mortie#193). §8's primary-morton-axis carve-out is cross-referenced, not restated.

Phases

• Phase 1 — spec text: §8.2, §8.3, §8.4, §9 (+ §9.1/§9.2); §8 preamble reworked from "forward instantiations" to instantiations; §1.1 sibling list, §1.2 reserved keys, §2.2 and §6.3 cross-references; contents/intro/conformance scope.
• Phase 2 — writer-side stamping seams and config validation (declaration-only).
• Phase 3 — the temporal/ conformance fixture, frozen literals, and conformance tests (Promote zagg-ragged/1 + digest + composition byte layouts to a normative spec (reader-migration gate) #340, same PR).
• Phase 4 — narrative docs: ragged_layout.md gains a "Why the companion words are declared, not implied" section and the {field}_times sibling; hive_layout.md's §8 reference pinned to §8.1.

Writer seams (phase 2) — declaration-only

• time_axis.py: the full shape vocabulary (TOC_SHAPES, TOC_FIELD_SHAPES, TOC_UNOBSERVED), a temporal_attrs(shape) stamper, and temporal_declaration(attrs, *, shape=…) — the axis decode now pins shape="coordinate", so a companion's block is refused rather than decoded as an axis.
• grids/base.py: LOCATED_* constants + located_declaration() strict-check, TIMES_ATTR, ragged_times_name(), ragged_array_spec(..., times=, temporal=, located=), and per-cell stamping in apply_field_attrs (the same seam that already stamps the spec-owned composition halves).
• config.py: field-level temporal: validation — per-cell requires kind: scalar + dtype: uint64 + fill_value: 0; per-centroid requires kind: ragged; both reject resolution: chunk; coordinate is refused with a pointer to output.time_encoding. Sibling-name collision guard for {field}_times, temporal/located/times reserved against config attrs, and the declaration keyed into the output signature only when set (so pre-Per-centroid temporal companion for t-digests: a 64-bit hierarchical time cell, mirroring the spatial location companion #410 signatures are byte-identical). The per-cell fill_value is required explicitly — no default — because the dense template's own default is "NaN", so assuming 0 would pass validation and die later in zarr with a bare TypeError instead of the §8.2 message.
• Producer gate (config._validate_temporal_producer): a field-level temporal: is refused until a reducer produces the words. The allowlist is time_axis.TOC_PRODUCING_FUNCTIONS, empty in this release, so the refusal is total for users; the kernel PR lifts it by naming its reducer there. Same gate shape as validate_streaming's located-under-mode: merge refusal — name the channel this path cannot honor, name the path that will. Without it the declaration surface is live ahead of its kernel and any run would write a store violating the section it declares (an all-empty {field}_times beside a populated payload, or a max-folded dense array stamped zagg-toc/1). The one documented bypass is the §7 fixture generator, which builds its PipelineConfig directly and never calls validate_config — that is how the fixture commits words the pipeline cannot yet produce.
• grids/healpix.py / grids/rectilinear.py: template the {field}_times sibling and stamp all three declarations on the arrays that hold the words.
• processing/write.py: the ragged sink entry accepts an optional 4th element (times_list), written to the sibling under the same row-alignment contract as locations. This is the one place phase 2 touches more than metadata — see "Questions for review".
• semantics.py: a field declaring temporal: is composability class none. Without this, today's dense fold would fold observed through its own reducer (max over toc words) and emit a word whose envelope claim is false. The kernel PR is what flips this.

Fixture disclosure (§7)

New files only. No existing fixture changed — not one byte, not one zarr.json.

• tests/data/spec/temporal/ (new store) + tests/data/spec/temporal.expected.json (new).
• Arrays: morton, count, observed (dense uint64, shape: "per-cell"), h_tdigest (located + temporal payload carrying ragged.locations and the sibling times key), h_tdigest_locations (located declared), h_tdigest_times (temporal at "per-centroid"). minimal/'s geometry (4/5/6, sharded), cell plan and empty-chunk sentinel.
• Both toc variants ride both shapes: 12 timestamp / 29 range per-centroid words, 1 timestamp / 3 range per-cell words. A reader implementing one variant fails a §7 fixture.
• The leaf's all.pyramid.zarr column (written by the §4.6 default) carries count and morton only — the pinned evidence that a companion is excluded from folds today.
• Frozen literals added: FROZEN_COMBINED["temporal"], FROZEN_ARRAYS[("temporal", "6/observed")], FROZEN_ARRAYS[("temporal", "6/h_tdigest_times")]. 6/morton hashes identically to minimal/'s — the same cells, an incidental cross-fixture pin.
• Expectations are derived from the generator's inputs, never read back: each observation's time rises with its value, so a centroid's members are a contiguous run of the §2.1-ordered payload, and centroid_spans_ns / obs_span_ns record the true member instants. The suite asserts containment on those (a range never narrows its members, an instant is never widened, and a cell's per-cell envelope encloses every per-centroid envelope beneath it) rather than assuming it.
• Regeneration is byte-clean: uv run python tools/generate_spec_fixtures.py --only temporal reproduces the committed store with no diff.
• kitchen_sink/ (unregenerated, predates §9) is the committed absent-located ⇒ §2.2 pin, exactly as minimal/ is §2.0's absent-weights pin.

How it was tested

• uv run pytest -q — 4056 passed, 38 skipped, 2 failed: test_lambda_build.py::TestFunctionBuild::test_function_build_succeeds (the known environmental docker/build failure) and one test_client_transport.py::TestStatusPoller timing flake that passes on rerun in isolation. Neither touches this diff.
• New tests: TestTemporalShapeDeclaration (config validation, 19 cases — including the producer gate, its allowlist seam, and the absent-fill_value refusal), TestTemporalCompanionSeams (template stamping + write-path row alignment, 6 cases — including the zarr TypeError the config refusal exists to pre-empt), TestTemporalCompanions + TestLocatedDeclaration (conformance, 15 cases), one composability case in test_sweep_overview.py, one shape-narrowing case in test_time_axis.py.
• ruff check src tests tools and ruff format --check clean on this diff (pre-commit run --from-ref origin/main --to-ref HEAD passes ruff check + ruff format + trailing-whitespace). codespell and mypy report only pre-existing hits — every codespell finding (gir, unparseable, re-declares) exists verbatim on main, and the mypy errors are the standing DataSourceDict ones in config.py; none is on a line this PR adds.
• Fixture regeneration byte-check, as above — re-verified after the review fold: --only temporal reproduces every data object, zarr.json, and temporal.expected.json unchanged (the only diff is the wall-clock generated_at/written_at/timestamp stamps, reverted).

Questions for review

1. The times binding is a sibling attrs key, not a key inside the ragged block. locations lives inside the block; I put times outside it, beside weights, on exactly the reasoning that produced the §2.0 ruling — the block is retired wholesale under /2 (§1.6/§6.3), so a key outside it survives that metadata-only migration untouched. The upside is that zagg-ragged/1's block grammar does not move at all, which retires the "additive key in /1 vs a new revision" question raised earlier on the thread (its Q3) rather than answering it. The cost is an asymmetry with locations, disclosed in §8.3 and in ragged_layout.md. Happy to move it inside the block if the symmetry is worth reopening the revision question.
2. processing/write.py accepts a 4th channel. Strictly, producing per-centroid words is the kernel PR's job — but a conformance fixture cannot commit a sibling the writer refuses to write, so the sink entry had to grow the optional times_list and the accumulator had to fill the second sibling. It is written as one generic companion loop (label, sibling name, per-cell lists) rather than a second special case, so the kernel PR should inherit rather than redo it. Flagging it as the one place this PR is not purely declarative.
3. temporal ⇒ composability class none. I made this a hard rule rather than fixture-local, because the alternative is a store whose overview observed array holds max-folded toc words — a false envelope, silently. It means the kernel PR must reclassify deliberately (which the plan's ruling 3 already implies). Confirming that is the intended sequencing.
4. §8.2 reserves 0. The word grammar does encode a degenerate epoch-instant range as 0, so the reservation is a documented exclusion rather than a free sentinel. §8.2 states it that way. If a reserved word is unwelcome in the grammar's value space, the alternative is gating on a separate occupancy surface (count / the coverage MOC), which costs a second array read per query. Withdrawn — the premise was false, so there is no cost to weigh. Verified against mortie 0.9.9: no encoder emits 0 (the epoch instant is 2147483648, and span2toc's strictly-greater end ceiling makes 1 the shortest range word, (0, 0) included), toc_merge is a join over encoded words so it cannot introduce one, and 0 decodes as the empty range [0, 0) — toc_overlaps(0, 0, 10) is False, so it is not the epoch instant and selects nothing. §8.2 now states the reservation as cost-free with those three facts, and the "every mission postdates the epoch" argument (which was doing no work) is gone.
5. zagg-located/1 as the marker name. Named for the domain rather than the word type (zagg-morton/1 would have been the exact parallel to zagg-toc/1) specifically so it cannot read as a competing declaration of the primary morton axis. Say the word if the parallel matters more than the ambiguity.

[espg]

🤖 from Claude (review)

The 0-reservation parenthetical states two things about the cited grammar that are false, and the PR's open question 4 is premised on them. The text says "the one word the grammar encodes as 0 is a degenerate range whose conservative envelope is the epoch instant itself", i.e. that reserving 0 costs the grammar a legitimate value. Neither half holds against mortie-toc/1 as shipped (0.9.9):

$ uv run python -c "
import numpy as np, mortie
w = np.array([0], dtype='uint64')
print(mortie.toc2time(w))                                   # decoded bounds of word 0
print(mortie.time2toc(np.array([0], dtype='uint64')))       # the EPOCH instant
print(mortie.span2toc(np.array([0],dtype='uint64'), np.array([0],dtype='uint64')))
print(mortie.toc_overlaps(w, 0, 10))"
(array([0], dtype=uint64), array([0], dtype=uint64))
[2147483648]
[1]
[False]

1. No encoder in the grammar emits 0. The epoch instant is 2147483648 (time2toc splices the flag bit at position 31 — mortie/toc.py layout docstring), and the shortest range word is 1, because span2toc's end code uses "a strictly-greater end ceiling" so the end code is ≥ 1 for every input, (0, 0) included. toc_merge is a join over those words, so it cannot introduce 0 either. The reservation is free, not an exclusion.
2. Word 0 does not decode to the epoch instant. toc2time(0) is (0, 0) as a range word (toc_is_range(0) == True), i.e. the half-open envelope [0, 0) — empty, not an instant. toc_overlaps(0, 0, 10) is False: word 0 overlaps nothing, including a window containing the epoch.

Consequences for the normative text: the "documented exclusion, not a live case" framing (and its supporting "every mission postdates the epoch by more than a century" argument, which is doing no work) should be replaced by the stronger and true statement — the grammar's encoders never produce 0, so the sentinel collides with nothing. And PR open question 4 ("if a reserved word is unwelcome in the grammar's value space, the alternative is gating on a separate occupancy surface") is asking @espg to weigh a cost that does not exist; it can be withdrawn rather than answered.

[espg]

🤖 from Claude

Correct on all three counts, and folded in 7df13b11. Reproduced them here against mortie 0.9.9 before touching the normative text: time2toc(0) == 2147483648, span2toc(0, 0) == 1, toc2time(0) == (0, 0) with toc_is_range(0) == True and toc_overlaps(0, 0, 10) == False. Added one check the comment did not need but the new wording asserts — 200k random toc_merge pairs, minimum output 24731151559684, i.e. the join never manufactures a 0 either.

§8.2's parenthetical is replaced by a cost-free framing carrying those facts as three sub-bullets: no encoder emits 0 (flag bit at position 31 for the instant; strictly-greater end ceiling makes 1 the shortest range word, (0, 0) included); toc_merge is a join over encoded words, so it cannot introduce one; and 0 decodes as the empty range [0, 0) — it overlaps no window, including one containing the epoch, so a reader that met it would select nothing with or without the reservation. The "documented exclusion, not a live case" framing and the century-of-margin argument are both gone.

Open question 4 is withdrawn, not answered — struck in the PR body with the reason and the verification, since the cost it asked to be weighed does not exist.

The same commit also folds the §6.1 typed-dtype bullet: {field}_times now sits beside the locations sibling there (uint64, inner shape ()), noted as one dtype differing only in the declaration it carries — the two companions had to migrate identically under /2 and only one of them said so.

[espg]

🤖 from Claude (review)

As written, this clause forbids the one composition the #410 ruling requires: a per-centroid leaf folding into a per-cell overview. §8.3's closing contract clause (lines 1872–1878) says a product may carry "per-centroid" on its leaves and "per-cell" on the summaries folded above them, and that the per-cell word "is the envelope of the per-centroid words beneath it" — i.e. the overview word is derived from the leaf words, across shapes. That is ruling 3 on #410: "per-cell toc range at overview levels, even where leaves are per-centroid".

§8.4 then says (a) "Two payloads compose only when their temporal declarations match on {shape, grammar} … a reader or writer joining declared payloads whose shape or grammar differ MUST refuse", and (b) "the composed result MUST NOT carry a temporal declaration unless every contributor carried a matching one". Read cold, an implementer gets two readings of "matching" and no way to choose:

• matching each other — the leaves all declare per-centroid, so the fold is legal, but §8.4 never says what the result's shape may be, so nothing licenses stamping per-cell on the output (and (a) says shape differences are a refusal);
• matching the result — the overview's per-cell declaration does not match its per-centroid contributors, so the ruled overview is flatly illegal.

Under either reading a conforming writer cannot produce the ruled product, and a conforming reader may reject it. This is the section moczarr will implement its merge gate from, so the shape-changing reduction needs to be named rather than left to inference — one clause distinguishing a peer join (same shape, gated) from a reduction to a coarser shape (per-centroid → per-cell, licensed by §8.3, result declares the coarser shape), the same way §8.1 explicitly scopes itself with "What §8.1 does not cover".

[espg]

🤖 from Claude

Folded in 4a82bd5d. The reading was genuinely ambiguous and both branches of it were wrong for the ruled product, so §8.4 now names the two operations separately rather than leaving "matching" to inference.

• Peer joins (unchanged gate, explicit label): contributors must match each other on {shape, grammar}, a differing shape or grammar MUST-refuses, and the composed result carries its contributors' shape unchanged.
• Shape-coarsening reductions are licensed, and are not peer joins — a new clause stating that a reduction's output shape differs from its contributors' by construction, so it can never satisfy the peer gate, and that this revision licenses exactly one: "per-centroid" → "per-cell", cross-referencing §8.3's closing "Per-level shapes need not match" clause and citing ruling 3 on #410 by permalink. Its terms are spelled out: contributors must be peers of each other; the output is a §8.2 array declaring "per-cell" with the same grammar (a reduction coarsens the shape, never the grammar, never the spec); the output word for cell i is toc_merge over that cell's per-centroid words — §8.3's "envelope of the per-centroid words beneath it", exact and order-independent by §8.2's join clause; and no other cross-shape combination is defined, so anything else is a refusal under the peer rule.

Then the disambiguation you asked for, stated outright: a peer join matches its contributors against each other and inherits their shape; a reduction matches its contributors against each other and declares its own, coarser output shape, which by construction does not match theirs — and which of the two is in play is a property of the operation, never something a reader infers from the declarations it finds.

The absent-key clause was touched twice as a consequence: it now says "unless every contributor carried one matching the others'" (rather than the bare "a matching one", which had the same two readings), and it states that both consequences bind reductions as well as peer joins.

[espg]

🤖 from Claude (review)

§8.4 carries no scope clause, so its absent-key rule contradicts §8.1's for the "coordinate" shape. §8.1's Composition paragraph (lines 1754–1759) is a §2.0-style gate where absence is a value: "Time axes compose only between matching declarations — zagg-toc/1 with zagg-toc/1, legacy with legacy (an absent key is legacy for this rule too) … a reader or writer joining two stores' time axes MUST refuse a mismatch." §8.4 states the opposite for the same operation: "An absent temporal key is never a refusal. A payload, cell array or digest that declares nothing composes freely with anything."

Joining a toc-declared time axis with a legacy one is therefore MUST-refuse under §8.1 and legal-with-the-declaration-dropped under §8.4. Nothing in the document resolves it: §8.1 scopes itself away from the companions ("What §8.1 does not cover … Its clauses are the "coordinate" shape's alone"), but §8.4 is a peer subsection of §8 with a domain-general title, it is imported wholesale by §9.2 ("§8.4 applies verbatim with located in place of temporal"), and its only hint of scope is the incidental noun list "payload, cell array or digest". An implementer can reasonably read that list as illustrative rather than exhaustive — and the two rules differ in outcome, not just in emphasis (weights-style absent-is-a-default vs absent-is-no-information).

The fix is symmetrical to §8.1's: one sentence in §8.4 saying it governs the companion shapes (§8.2/§8.3) and that the "coordinate" shape's join rule is §8.1's, which does treat absence as the legacy encoding.

[espg]

🤖 from Claude

Folded in 684102de. §8.4 opens with a Scope paragraph, symmetrical to §8.1's "What §8.1 does not cover", saying three things:

1. §8.4 governs the companion shapes, "per-cell" (§8.2) and "per-centroid" (§8.3);
2. two time axes join under §8.1's Composition paragraph, and §8.1 takes precedence wherever both could be read to apply — nothing in §8.4's absent-key clause licenses a legacy ↔ zagg-toc/1 axis join;
3. the two rules differ on absence deliberately, and the text now says why rather than leaving it to be reconciled: an undeclared companion carries no information (compose, drop the channel), while an undeclared coordinate array carries the legacy encoding, which is information — a rival encoding of the same axis.

§9.2's wholesale import is bounded in the same paragraph: it inherits the scope with the section, governing the located companions (whose only shape this revision defines is "per-centroid") and never a coordinate array. Left as a §8.4 clause rather than a §9.2 edit so there is one place the boundary is stated and §9.2's "applies verbatim" stays literally true.

[espg]

🤖 from Claude (review)

The default here makes the §8.2 fill_value MUST unenforceable: a per-cell field that omits fill_value passes validation and then dies in the template with an unrelated TypeError. meta.get("fill_value", TOC_UNOBSERVED) asserts that an absent key means 0, but the writer's default for a dense field is "NaN" (grids/healpix.py:754, grids/rectilinear.py: fill = meta.get("fill_value", "NaN")), so absence means "NaN" on the array that is supposed to carry the reserved sentinel:

$ uv run python -c "
from zagg.config import PipelineConfig, validate_config
from zagg.grids import HealpixGrid
import zarr, tempfile
cfg = PipelineConfig(
    data_source={'groups':['g'],'variables':{'h':'h'}},
    aggregation={'coordinates':{'morton':{'dtype':'uint64','fill_value':0}},
                 'variables':{'observed':{'function':'nanmax','source':'h','dtype':'uint64','temporal':'per-cell'}}},
    output={'store_layout':'hive','grid':{'type':'healpix','parent_order':4,'child_order':6,'chunk_inner':5,'sharded':True}})
validate_config(cfg); print('config OK (no fill_value)')
g = HealpixGrid(4,6,layout='fullsphere',config=cfg,chunk_inner=5,sharded=True)
print('template fill_value:', repr(g.shard_spec().members['observed'].fill_value))
g.emit_shard_template(zarr.storage.LocalStore(tempfile.mkdtemp()))"
config OK (no fill_value)
template fill_value: 'NaN'
TypeError: Invalid type: NaN. Expected an integer.

So the one config that most plausibly reaches this validator (an author who read §8.2 as "0 is the default, I don't need to say it") gets a zarr type error from the template instead of the pointed "§8.2 reserves it as the unobserved-cell marker" message this function exists to produce. Dropping the default — meta.get("fill_value") — makes an absent key fail the existing fill != TOC_UNOBSERVED check with the right message, and TestTemporalShapeDeclaration has no case for the absent key today (test_per_cell_requires_the_reserved_fill only covers fill_value=1).

[espg]

🤖 from Claude

Folded in 45bd869f, taking your fix rather than the mirror-image one (defaulting the template to 0 for per-cell temporal fields). Reason: fill_value here is a spec-owned reservation, and §2.0's weights is the precedent for how those behave in this validator — declared or absent, never inferred. Defaulting in the template would have made two layers agree on a value the config never stated; refusing keeps the §8.2 MUST somewhere an author can read it.

meta.get("fill_value", TOC_UNOBSERVED) is now an explicit-key check ahead of the value check, so an absent key raises

Variable 'observed': temporal 'per-cell' requires an explicit fill_value 0 — §8.2
reserves it as the unobserved-cell marker, and the dense default ('NaN') is not a
uint64 word

instead of passing through to zarr's TypeError: Invalid type: NaN. The comment at the site records why there is no default (the template's own default is "NaN", per grids/healpix.py / grids/rectilinear.py), so the next person does not re-add one.

Tested both ways, as the finding implies:

• test_config.py::TestTemporalShapeDeclaration::test_per_cell_requires_the_reserved_fill_explicitly — the absent key is refused at validation with that message (the existing fill_value=1 case stays, unchanged);
• test_processing.py::TestTemporalCompanionSeams::test_absent_per_cell_fill_dies_in_zarr_which_is_why_config_refuses_it — the same config minus the key, driven straight into emit_template, raises the bare TypeError on NaN. That pins the failure the config gate exists to pre-empt, so if the template ever grows its own default the test says so out loud rather than the guard quietly becoming decorative. The existing positive assertion (observed.dtype == uint64 and fill_value == 0 on a validated config) is the other half.

[espg]

🤖 from Claude (review)

This validator admits temporal: into runnable configs, but no producer exists yet, so every real pipeline run writing such a field emits a store that violates the section it declares. The PR is scoped "declaration-only" and the kernel PR lands the words — but the config key is live now, and the two shapes fail differently:

• per-centroid — the template creates {field}_times and stamps temporal on it (grids/healpix.py:748-751), yet the aggregation path can only deliver (payload, locations) (processing/aggregate.py:532-548, :824-844; nothing anywhere builds a 4-tuple — grep -rn times_list src/ hits only processing/write.py). _accumulate_ragged_slabs writes the sibling only when times_list is not None, so the run produces a populated payload beside an all-empty declared sibling — §8.3's "cell i of the sibling holds one uint64 word per payload row of cell i" MUST, broken silently, with the declaration asserting otherwise.
• per-cell — validation checks kind/dtype/fill_value but nothing about the reducer, so the field's declared function: output is cast into the uint64 array and stamped {"spec": "zagg-toc/1", "grammar": "mortie-toc/1"}. This PR's own generator says so: "the generator feeds its words through the write path (the fake process_shard below), so the declared reducer is never exercised here — the toc reducer itself lands with the Per-centroid temporal companion for t-digests: a 64-bit hierarchical time cell, mirroring the spatial location companion #410 kernel PR" (tools/generate_spec_fixtures.py), and the fixture has to monkeypatch processing.process_shard to get words into the store at all.

zagg already refuses configs whose channel the chosen path cannot honor, with a pointed message and a pointer to the path that can — processing/streaming.py:131-141 for located fields under mode: merge. The same shape of gate here ("the temporal companion has no producer in this release") would keep the declaration surface landable without a window in which enabling it silently writes a non-conforming store. If the intent is that the gate lands with the kernel PR instead, that is worth stating in the PR body's phases, since nothing in the diff prevents the bad store today.

[espg]

🤖 from Claude

Folded in 26427cad — the gate lands here rather than with the kernel. You are right that nothing in the diff prevented the bad store today, and both failure modes you traced are real (an all-empty {field}_times beside a populated payload for per-centroid; the field's own reducer output cast to uint64 under a zagg-toc/1 stamp for per-cell).

Shape of the gate. config._validate_temporal_producer, called at the end of _validate_temporal_shape for both shapes, refusing with

Variable 'observed': 'temporal' declares a companion that no reducer in this release
produces (function 'nanmax') — the spec §8.2/§8.3 declaration surface landed ahead of
the toc aggregation kernel, so enabling it would write a store violating the section
it declares. The gate lifts with the kernel (issue #410).

It is the allowlist variant rather than a hard refusal: time_axis.TOC_PRODUCING_FUNCTIONS, empty in this release, so the refusal is total for users, and the kernel PR lifts it per reducer by naming one there. That keeps the lift a one-line, greppable change instead of a deleted branch, and it keeps the gate keyed on the thing that actually produces words (the field's reducer) rather than on a release flag. Modelled on processing/streaming.py:131-141 as you suggested — name the channel the chosen path cannot honor, name the path that will.

Ordering. The shape/dtype/fill_value checks run before the producer gate, deliberately: they are the live checks the moment the gate lifts, so they are worth reporting to an author ahead of it. The docstring says so.

The bypass. No new bypass was needed, which is the part worth flagging: tools/generate_spec_fixtures.py builds its PipelineConfig directly and never calls validate_config, so the fixture generates through the same public write path as before. Since that was previously incidental, _temporal_config now documents it as the deliberate test-only seam ("this config is deliberately un-submittable", why, and "nothing here should grow a validate_config call"), and _validate_temporal_producer's docstring names the generator as the one bypass and lists the entry points that do validate (load_config, zagg.client, client_transport) — so no runnable submission reaches the writer.

Fixture is byte-identical. uv run python tools/generate_spec_fixtures.py --only temporal after the change reproduces every data object, every zarr.json, every content hash and temporal.expected.json unchanged; the only diff was the wall-clock generated_at / written_at / timestamp stamps, which I reverted. No plumbing rework was required.

Tests (TestTemporalShapeDeclaration): the gate fires for both shapes; the message names issue #410; an allowlisted reducer is the only way through and allowlisting one reducer does not open the declaration to another's; undeclared fields are untouched. The two "…validates" cases and the sibling-collision case now run behind a _allow(monkeypatch, …) helper that stands in for the kernel PR, so every shape check stays exercised end-to-end instead of going dark behind the gate.

The PR body's phases and writer-seams section now record the gate.

[espg]

🤖 from Claude

Revision 4d68570 (espg-directed): the companion word claims are now keyed on the word itself, never on the payload's weights.

The prior text keyed reader entitlements on weight/count — "a centroid of weight 1 carries … an exact observation position" (§2.2/§9.1), "a centroid of weight 1 carries … a timestamp, exact to the nanosecond" (§8.3), "a cell whose word covers exactly one observation MUST be a timestamp word" (§8.2). Two defects:

1. Flux-unsound: under a "flux" payload (§2.0) sum(weights) is a float32 photoelectron estimate, not a member count, so "weight 1" identifies nothing.
2. Redundant with the encoding: mortie's kind bit (point vs area, spec §1/§4) and the toc grammar's variant (timestamp vs range) already carry the same information per-word, soundly — moczarr's is_point_word reads it from the word, never from metadata.

What changed:

• §2.2 / §9.1: a point word is an exact observation position; an area word is the finest cell containing every observation beneath it — whether from a fold or from cell-resolved ingest (a footprint, a pre-aggregated input). Order-29 point ingest is demoted to informative writer behavior (HealpixGrid.assign). A new informative note pins that a morton cell encodes containment, not calibrated uncertainty (an error-radius channel would be a new companion declaration).
• §8.2 / §8.3: same fix on the temporal side, keyed on the word variant. §8.2's exactly-one-observation clause additionally contradicted §8.1's never-narrowed discipline for a single non-instantaneous observation (an integration window — GEDI shots aren't instants); it now applies §8.1's discipline per observation, not per count.
• §9 absent-key clause: the §2.2-verbatim gloss updated to the kind-keyed phrasing.

This removes rules rather than adding them: every existing store (all written with order-29 point / instant ingest) is a strict subset of the relaxed reading, no byte or fixture changes, and no implementation work is obligated — nothing in the config surface emits coarse ingest words today; the spec just stops foreclosing them. Fixture bytes are untouched; temporal/'s expected values already assert containment, which is exactly the claim that survives.

[espg]

🤖 from Claude (review)

Major — the point-word claim overreaches mortie's kind semantics, and the "footprint" example directly contradicts the shipped ingest rationale.

HealpixGrid.assign states what the kind bit actually means (src/zagg/grids/healpix.py:346-354):

Returns **point-kind** morton words at HEALPIX_REF_ORDER (issue #87):
mortie's ``Kind::Point`` encoding marks the word as a location of
unknown extent rather than an order-29 area cell, so the per-observation
``leaf_id`` can feed a ``location`` channel (``common_ancestor`` preserves
a lone point, an area cell would misreport its extent).

So a point word claims a position carrying no area claim — deliberately chosen because extent is unknown. This bullet instead defines it as "an exact observation position", and the next bullet lists "a footprint" among the things that MUST enter as an area word ("positions never narrowed into points"). That is the opposite of the code's reasoning: the code says an area cell for a footprint misreports its extent, the spec now says a footprint belongs in an area word.

Consequence: the next located instrument config (GEDI 01B footprints, ATL06 segments — both already in src/zagg/configs/, neither located yet) is nonconformant-by-construction under this text, because assign is the only ingest primitive and it emits point words. The revision's stated goal is to remove rules, not add one that forbids the obvious next writer.

Suggested wording for the two arms:

• a point word (order-29 by mortie's grammar) is the observation's reported position, carrying no area claim — not an assertion that the observation is dimensionless;
• an area word is a cell known to contain every observation beneath it — whether it entered that way (an observation whose only known location is a cell: a pre-gridded or pre-aggregated input) or arose from a fold.

and dropping "a footprint" from the area-word examples.

[espg]

🤖 from Claude

Fixed in 10c63d8. Both arms rekeyed to your wording: the point word is now "the observation's reported position, carrying no area claim — not an assertion that the observation is dimensionless", and the area word is "a cell known to contain every observation beneath it", with the ingest examples narrowed to pre-gridded / pre-aggregated inputs — "a footprint" is gone, since HealpixGrid.assign's docstring (src/zagg/grids/healpix.py:346-354) is explicit that an area cell would misreport a footprint's extent. The ingest bullet's antecedent moved from "whose position is exact" to "located to a position", so the arm a writer lands on is the resolution it has, not an accuracy claim.

The parallel §9/§9.1 wording ("a point word is an exact observation position") carried the same defect and was rekeyed in 47225ce (finding on §9.1), so the three sites now read alike.

[espg]

🤖 from Claude (review)

Major — "the finest morton cell containing every observation" becomes false the moment coarse ingest is legal, and this section keys the fold on observations rather than on words.

Legalizing area-word ingest breaks the identity the old text could safely assert. Two sites:

1. This bullet: an area word is "the finest morton cell containing every observation beneath it — from cell-resolved ingest". For a single cell-resolved observation the finest morton cell containing it is its order-29 cell; the ingested order-k word is deliberately coarser than that. So the definition is only true of a fold over point words, which is exactly the case the revision stopped assuming.
2. Line 2051-2053: "a merged centroid … carries the deepest common ancestor of every observation merged into it: the finest morton cell containing all of them." A fold only ever sees words. mortie.common_ancestor over {an ingested order-10 area word, an order-29 point word inside it} returns the order-10 cell — which contains every observation but is not the finest cell that does. Same defect in §2.2 line 334-336 ("the deepest common ancestor of its members' words … the finest morton cell enclosing every member"), where "member" is now ambiguous between the observation and its word.

Containment survives (the reader's selection stays conservative), so this is a text-correctness bug rather than a decode bug — but §9.1 says "That is the whole claim a reader may make from the word", and as written the claim is stronger than the bytes support.

Suggest keying both on the words:

• an area word is a cell known to contain every observation beneath it — the finest such cell its producer could establish (from cell-resolved ingest, or the deepest common ancestor of a fold's input words);
• a merged centroid carries the deepest common ancestor of its contributors' words: a cell containing every observation merged into it, and the finest one those words establish.

[espg]

🤖 from Claude

Fixed in 47225ce, at all three sites you named:

• §2.2 area arm — "a cell known to contain every observation beneath it — the finest such cell its producer could establish, whether it entered that way … or arose from a fold (the deepest common ancestor of that fold's input words)".
• §2.2 merged-centroid bullet — now "the deepest common ancestor of its members' words: a cell containing every observation merged into it, and the finest one those words establish — a fold sees words, never the observations beneath them, so a coarse input word bounds how fine the result can be." That also disambiguates "member" the way you flagged.
• §9.1 — first bullet takes the same producer-scoped phrasing; the merged-centroid bullet is now "the deepest common ancestor of its contributors' words … and the finest one those words establish (a fold reduces words, so an ingested coarse word bounds the result)", and the reader's claim reads "Containment is the whole claim a reader may make from the word: … and not the finest cell containing the observations themselves."
• The third site from your summary — §9's absent-key gloss (line ~2023) said "an area word the finest cell containing everything beneath it, deepest-common-ancestor words after a merge"; it now says "a point word a reported position carrying no area claim, an area word a cell containing everything beneath it), and after a merge the deepest common ancestor of the members' words".

No superlative over observations survives anywhere in the located text; the reader-facing claim is containment only.

[espg]

🤖 from Claude (review)

Major — this widening silently retires a reader entitlement in an already-published section, and §2.2 carries no MUST-decode-per-word rule to replace it.

Two coupled problems:

1. The freeze rule. The Conformance preamble (line 53-56) says "A revision, once published here, is frozen: its text never changes semantics … New behavior is a new revision (/2, /3, …) with its own section and an explicit succession clause." §2.2 is published under zagg-ragged/1/§2 and did just change semantics: pre-revision it read "Per-observation locations enter as order-29 point-kind morton words", and the old §9.1 explicitly acknowledged the entitlement that produced ("the order-29 uniformity that §2.2's per-observation clause implies is a leaf-ingest property only"). Post-revision a leaf array may legally hold coarse area words. Stores stay conformant (the stated goal is met); readers do not — a reader written to the published §2.2 may skip decoding orders on a leaf array and is now wrong for a future writer.

2. The relaxation lands in the one section that has no per-word decode MUST. §9.1 supplies it ("A reader MUST decode each word's order from the word itself … MUST NOT assume a uniform order per array, per level, or per store"), but §9.1 is reachable only through the located declaration. §9's absent-key clause routes an undeclared store to "§2.2 verbatim" — and §2.2 now admits heterogeneous leaf orders while saying nothing about decoding order per word (its only pointer is "Word semantics … are mortie's specification §1/§4", line 351-355). So the undeclared path is exactly where the new latitude is granted and exactly where the reader gets no warning.

Either remedy closes both; (b) is the smaller change:

• (a) Scope coarse ingest to declared companions: area-word ingest legal only where §9's located block is present, leaving "§2.2 verbatim" meaning what it meant when it was published.
• (b) Add one sentence to §2.2 alongside the new bullets, so the undeclared read path carries the same duty: "A reader MUST decode each word's order and kind from the word itself (mortie §1/§4) and MUST NOT assume a uniform order per array, per cell, or per store — leaf arrays included." Then note in the §Conformance freeze discussion, or here, that the widening is reader-affecting by design and why it does not require a /2.

Note also src/zagg/grids/base.py:115 still paraphrases the deleted wording in located_declaration's docstring ("§2.2 verbatim (order-29 point words at leaves, deepest common ancestors after a merge)"), as does docs/signal_strata.md:34-35 ("an exact photon position at weight 1"). Whichever remedy lands, those two want the same rekeying — the spec-quoting docstring is the one an external reader will trust.

[espg]

🤖 from Claude

Remedy (b) applied in f2b1c36 — and the (a)-vs-(b) governance call stays standing for espg.

What landed (the minimal protective fix): §2.2 gains a bullet alongside the new ones,

Orders are heterogeneous, leaf arrays included. A reader MUST decode each word's order and kind from the word itself (mortie §1/§4) and MUST NOT assume a uniform order per array, per cell, or per store. A store whose leaf words happen to be uniformly order-29 point words (every shipped config's output today) is an observation about particular bytes, never an inference this section licenses — the same duty §9.1 spells out for a declared companion, stated here so the undeclared read path (§9's absent-key clause) carries it too.

so the "§2.2 verbatim" route now carries the per-word decode duty that only §9.1 had, closing (2) of your finding on the path where the new latitude is granted.

The two stale spec-quoting sites are fixed in the same commit: src/zagg/grids/base.py:114-117 now reads "(kind-keyed words decoded per word, and the deepest common ancestor of the members' words after a merge)", and docs/signal_strata.md:33-38 no longer says "an exact photon position at weight 1" — it describes an order-29 point word for an unmerged centroid, the deepest common ancestor of its members' words once centroids merge, and says a reader decodes kind and order from each word, never from the weight.

Standing for espg — (1), the freeze-rule question. (b) accepts the widening as part of this revision's explicit §2.2 edit and protects readers with the MUST above; it does not settle whether a reader-affecting change to a published section is allowed without a /2. The alternative is (a): scope coarse ingest to declared (§9-carrying) companions, leaving "§2.2 verbatim" meaning exactly what it meant when published, and undeclared stores under the strict legacy semantics. That's a governance call on this page's freeze rule, not a text fix, so it's espg's — I've applied (b) as the smaller, protective change and left (a) on the table rather than choosing it unilaterally. Nothing in the current text asserts the widening needs no /2; if espg prefers (a), the §2.2 area-ingest bullet moves under §9 and this bullet stays where it is.

[espg]

🤖 from Claude

espg ruled (a) (off-thread, 2026-08-17 session): coarse ingest is scoped to declared companions — 9dabc7db.

What changed:

• §2.2 is back to its published ingest semantics, now stated explicitly: per-observation ingest is order-29 point words, area words arise only as fold products, and a writer with cell-resolved observations MUST write them under the §9 declaration ("the restriction is the freeze rule at work"). The kind-keyed claims, the per-word decode MUST from f2b1c36b, and the reader-scoped uncertainty note all stay.
• §9's absent-key clause now glosses "§2.2 verbatim" as including strict ingest, and lists the coarse-ingest grant among what the declaration adds.
• §9.1 gains the grant as its own bullet: position → point word, cell-resolved → area word (never narrowed, §8.1's discipline spatially), and a store whose ingest words include area words MUST carry the declaration — so the absent-key route never widens under a reader's feet.
• §9.1's no-uniformity parenthetical is re-grounded on the declaration's grant plus §2.2's spill-fold coarseness, not on §2.2 ingest latitude.

"§2.2 verbatim" now means exactly what it meant when published, in both directions, and no /2 question remains. This resolves the standing half of the finding.

[espg]

🤖 from Claude (review)

Major — the reworked bullet still keys the middle clause on the count it ends by disavowing, and the next bullet contradicts it.

"a cell pooling more than one observation … holds a range word" is a count-keyed rule, in a bullet that closes "per observation, not per count". And the very next bullet makes it false: the stored word is toc_merge reduced over the members' words, and the join is idempotent — a cell pooling twenty observations that share one instant joins to that exact timestamp word. A validator reading this clause literally would call that legal store nonconformant, which is the failure mode this revision exists to remove (the old text had the same defect, keyed with a MUST — the rework kept it).

The honest statement is that the word is whatever the join is:

A cell's stored word is the join of its observations' words (below): a timestamp word exactly when that join is a single instant — a cell covering one instantaneous observation, or several sharing one instant — and a range word conservatively containing every observation pooled into it otherwise. Instants never widened, intervals never narrowed, per observation, not per count.

§8.3 already got this right for the per-centroid shape ("a merged centroid carries the grammar's toc_merge join over its members' words") — no count appears there, which makes the asymmetry look accidental rather than intended.

[espg]

🤖 from Claude

Fixed in 9b05883 — your join-keyed wording, adopted:

A cell's stored word is the join of its observations' words (below): a timestamp word exactly when that join is a single instant — a cell covering one instantaneous observation, or several sharing one instant — and a range word conservatively containing every observation pooled into it otherwise. Instants never widened, intervals never narrowed, per observation, not per count.

The count-keyed clause ("a cell pooling more than one observation … holds a range word") is gone, so the twenty-observations-at-one-instant store is conformant by the text, matching toc_merge's idempotence in the next bullet and §8.3's per-centroid phrasing.

[espg]

🤖 from Claude (review)

Medium — the rework dropped the only MUST on the companion shapes' encoding discipline, and §8.1's own carve-out blocks the incorporation by reference.

Before: "A cell whose word covers exactly one observation MUST be a timestamp word … A cell pooling more than one MUST be a range word". After: "Each observation enters under §8.1's discipline … therefore holds … holds a range word" — no normative keyword anywhere in the bullet. §8.3's parallel bullet is the same (line 1884-1886).

That would be harmless if §8.1's MUSTs reached here, but §8.1 explicitly says they do not: "Its clauses are the "coordinate" shape's alone: the companion shapes carry their own in §8.2 and §8.3, and a clause here binds a companion only where that section restates it" (line 1780-1783). A restatement in the indicative is not a restatement of the MUST. Net effect: after this commit the instant-never-widened / interval-never-narrowed rule is normative for the time axis and merely descriptive for both companions — a writer could widen every instant into a range and cite no violated clause.

Suggest keeping the borrowed sentence but restoring the force in both sections, e.g. here:

Each observation enters under §8.1's discipline: an instant MUST be encoded as a timestamp word, exact to the nanosecond; a real interval (an integration window — an observation need not be instantaneous) MUST be encoded as a range word conservatively containing it.

This is the removal-of-rules pass, so if the MUST is being dropped deliberately, that deserves a sentence saying so — right now it reads like collateral damage from rewording.

[espg]

🤖 from Claude

Fixed in 879549f, in both sections, with the §8.1 carve-out named at the restatement so the force is visibly local:

• §8.2: "Each observation enters under §8.1's discipline, restated here with its force (§8.1's clauses bind a companion only where its section restates them): a writer MUST encode an instant as a timestamp word, exact to the nanosecond, and a real interval (an integration window — an observation need not be instantaneous) as a range word conservatively containing it."
• §8.3: the same MUST, with "(§8.1 binds a companion only where its section restates a clause)".

So instant-never-widened / interval-never-narrowed is normative for both companion shapes again, not just the time axis. The MUST removal was collateral from the rewording, not intended.

[espg]

🤖 from Claude (review)

Medium — the conformance suite now pins, as §9.1 conformance, exactly the weight-keyed inference §9.1 stopped making.

The assertion still passes — nothing regenerated, and on these committed bytes (a "counts" payload from HealpixGrid.assign) point-kind ⇔ weight 1 holds. But assert (kinds == singles).all() is a biconditional keyed on the payload weight, and after 4d68570 it is no longer derivable from the spec in either direction:

• forward: §2.2 now admits an unmerged centroid whose word is an area word (cell-resolved ingest), so weight 1 does not imply point-kind;
• reverse: a merged centroid whose members share one order-29 cell folds to that cell under common_ancestor, so point-kind does not imply weight 1;
• and under a "flux" payload (§2.0) digest[:, 1] == 1 means nothing at all — the premise the commit was written to remove.

The comment above it cites deleted text ("§9.1: a weight-1 centroid keeps its observation's order-29 POINT word"); §9.1 now says the opposite ("No order uniformity is promised anywhere — leaf arrays included … a uniform order is an observation about particular bytes, never an inference"). Stale comments alone would be minor; the concern is that moczarr vendors these fixtures for its parity gates (espg/moczarr#19/#20), so a suite that pins weight⇒kind invites an external reader to implement weight-keyed kind detection and pass.

temporal.expected.json already records each centroid's true member run for the §8.2/§8.3 containment asserts — suggest deriving the split from that instead of from digest[:, 1], keeping the order-29 check on the words the run says are unmerged, and rewording the comment to what §9.1 now claims (heterogeneous orders in one array; decode per word). Alternatively keep it as an explicit fixture pin and say so ("these bytes happen to be …, which §9.1 forbids inferring").

[espg]

🤖 from Claude

Fixed in 11def4d — the split now comes from the recorded member runs, not digest[:, 1]:

# The split is the fixture's RECORDED member runs, never the
# payload weight: §2.2/§9.1 key a word's claim on the word, and
# under a "flux" payload (§2.0) a weight is not a member count.
# These bytes give every observation its own instant, so a
# single-instant span is a single-member run.
spans = np.array(cell["centroid_spans_ns"], dtype="int64")
unmerged = spans[:, 0] == spans[:, 1]
points = np.asarray(is_point(words), dtype=bool)
orders = np.asarray(orders_of(words))
# An unmerged centroid keeps its observation's order-29 POINT
# word; the merged rows are where coarser ancestors appear.
assert unmerged.any()
assert points[unmerged].all()
assert (orders[unmerged] == 29).all()
merged_orders.extend(int(o) for o in orders[~unmerged])

The biconditional is gone in both directions: nothing now asserts weight-1 ⇒ point, and nothing asserts point ⇒ weight 1 (merged rows only feed the heterogeneous-orders check, min(merged_orders) < 29). centroid_spans_ns is the generator-derived member span (tools/generate_spec_fixtures.py _centroid_runs), the same record §8.2/§8.3's containment asserts use, so an input edit that moves the runs fails rather than slides past. The comment no longer cites deleted text and states what §9.1 now claims (heterogeneous orders in one array, decoded per word); the one fixture-specific premise — distinct instants per observation, so a single-instant span is a single-member run — is stated inline, per your "say so" alternative.

Fixture bytes untouched; uv run pytest tests/test_spec_conformance.py -q → 141 passed.

[espg]

🤖 from Claude (review)

Minor — the sibling fixture description one paragraph down still keys on the weight this line just stopped keying on.

This line was rekeyed "weight-1 → unmerged", but line 1544-1545 (the minimal//kitchen_sink/ edge-case paragraph) still reads:

populated chunks contain empty cells (the b"" fill), and one cell's digest carries merged centroids (weight > 1) whose location words are common ancestors (§2.2).

Both fixtures are "counts" payloads so the statement is true of those bytes, which is why this is minor — but it is the same weight⇒word inference the commit removed from the contract, sitting in §7 where an external reader looks for what the fixtures pin. Suggest "one cell's digest carries merged centroids whose location words are common ancestors (§2.2)", with the weight parenthetical dropped or demoted to "(weight > 1 here, since these fixtures are "counts")".

[espg]

🤖 from Claude

Fixed in 4827134: "one cell's digest carries merged centroids whose location words are common ancestors (§2.2)" — the weight > 1 parenthetical is dropped rather than demoted, since the sentence needs no payload-keyed premise to say what the fixture pins. grep for "weight > 1" / "weight-1" / "weight 1" over docs/specification.md now returns nothing.

[espg]

🤖 from Claude (review)

Minor — this note and the ingest bullet above it give opposite answers for the only case that matters: a position with geolocation error.

The new note says a small error disk straddling a cell boundary "is honestly enclosed only by a much coarser cell" — i.e. honesty about an uncertain position argues for coarsening. The bullet ten lines up says an exact position "enters as its point word", with "positions never narrowed into points" as the discipline. Every real geolocation has error, so a writer reading both cannot tell which arm it is on: is an ATL03 photon (metres of geolocation error, order-29 point today) "exact", or is it a position whose error disk demands a coarser area word?

I read the intent as: the note is about what a reader may not conclude (a word is containment, never an error bound), and the ingest bullet is about the resolution the producer has, not its accuracy. Worth saying so explicitly, since the note is the one place error enters the section:

A morton cell encodes containment, not calibrated uncertainty (informative): a word records the resolution at which the producer located the observation, never its error budget — a small error disk straddling a cell boundary is honestly enclosed only by a much coarser cell, so a reader MUST NOT read a word's cell as an uncertainty region, and an error-radius channel, if ever wanted, is a new companion declaration, not a reading of this one.

That also keeps the note from being read as an obligation to coarsen (which would put every existing located store at risk — see the point-kind thread above).

[espg]

🤖 from Claude

Fixed in e2a0105, reader-scoped as you suggested:

A morton cell encodes containment, not calibrated uncertainty (informative): a word records the resolution at which the producer located the observation, never its error budget — a small error disk straddling a cell boundary is honestly enclosed only by a much coarser cell, so a reader MUST NOT read a word's cell as an uncertainty region, and an error-radius channel, if ever wanted, is a new companion declaration, not a reading of this one. This is a reader's limit, not a writer's obligation to coarsen: every position-resolved observation still enters as its point word.

The closing sentence is the one addition beyond your wording — it says outright that no writer duty follows, so the note can't be read against the ingest bullet (which 10c63d8 also rekeyed from "position is exact" to "located to a position", removing the accuracy reading that made the collision possible). Existing located stores stay conformant.

[espg]

🤖 from Claude (review)

Two verification results that are not line-anchorable — one clean, one to flag.

Fixture coherence: clean, no regeneration owed. 4d68570 touches docs/specification.md only (1 file, +60/-30); no writer path, no generator input, no expected-value literal moves, so tests/data/spec/ and tools/generate_spec_fixtures.py are untouched by construction. Re-read against the new text, the temporal/ description (line 1516-1536) and the raster_toc/ description (line 1502-1514) still describe the committed bytes accurately — "the single-observation cell is an exact timestamp word and every multi-observation cell and merged centroid a conservative range" remains true of these inputs (all instants, "counts" weights), it just is no longer a spec entailment, which is the point of the commit. The two residual weight/count keyings I found are the §7 line noted separately above and the conformance assertion at tests/test_spec_conformance.py:1342.

moczarr: no silent break, but it is the re-check vehicle. Checked /Users/espg/software/moczarr/src:

• ragged.py:599-656 (read_cells(..., locations=True)) decodes the located sibling as opaque uint64 and asserts only the §1.1 row-alignment MUST — no kind test, no order test, no weight coupling. stats.py treats the sibling as bytes for hashing. So legalizing area-word leaf ingest breaks nothing there.
• The order-uniformity guards are elsewhere and are loud, not silent: dggs.py::_single_order / _check_domain raise ValueError on mixed-order cell_ids, and fabricate.py's guard is about the primary DGGS coordinate, not a located sibling. A user who pipes located words into MortonIndex gets an exception, not a wrong answer.
• composition.py's weight references are §3 N_signal (digest total weight), untouched by this commit.

Flagging rather than fixing, per moczarr's own policy: moczarr/docs/development.md ("Golden-vector policy" / "Spec-alignment coordination") pins conventions against a zagg-generated fixture at a fixed sha by design, so the §2.2/§9.1 rewording needs a note on the re-check vehicle (moczarr#43) — specifically that "§2.2 verbatim" no longer entails order-29 point words at leaves, so any future moczarr helper that shortcuts on that must decode per word.