spec(0.10.0): §4 — a top_ngrams sequence is ngram_size consecutive records of one observation stream

[coderoast-dev]

The problem

§4 sizes the behavior block by ngram_size ("size of n-grams") and calls it a sequence fingerprint, but never says what a sequence is. A producer can therefore read it as any template-to-template relation it observes. The reference implementation did exactly that: at ngram_size 3 it put a second relation, a declared link between two records (a span's parent link), into top_ngrams as a two-id sequence beside the log-order trigrams, and fed the same relation to branching, dominant_path and graph_edge_count. A producer that does not parse such links computes different values for the same records, so the members stopped meaning the same thing across producers. The 0.10.0 draft then added a clause to the probability paragraph conditioning each length among its own, which made the mixed block look legal.

The proposed change (diff against SPEC.md §4)

• The example's sequence comment reads array of ngram_size template_ids — see below.
• A new sentence under the example: an entry's sequence is the template ids of ngram_size consecutive records of one observation stream, in observation order, so every entry of top_ngrams holds exactly ngram_size ids. What a producer treats as one observation stream (the whole window, or a narrower scope such as one trace) stays its own; the sentence names no scope on purpose.
• The probability paragraph drops the clause about a top_ngrams holding sequences of more than one length, which no conforming document can now hold, and reads n as ngram_size. The conditional definition itself (p(last | first n − 1), before the top_ngrams_size cut) is unchanged.
• CHANGELOG.md records it under 0.10.0 → Clarified.

Classification, for the editor

Against every released version (0.9.0 and earlier) this changes no document's validity: those texts sized every n-gram by ngram_size and never admitted a second length. Against the unreleased 0.10.0 draft it withdraws one clause that admitted two lengths, so it can be read as breaking by the letter of that draft; 0.10.0 has no tag and no Release, so no implementer relied on it. The changelog entry files it as Clarified; reclassifying it is the editor's call.

Alternatives considered

• Admitting declared links into the standard block, with a provenance flag per entry: keeps branching, dominant_path and graph_edge_count mixed, and a flag in a closed object is itself a spec change.
• A standard span/trace block: needs a trace model (span identity, parent semantics, an OTel mapping) and a second producer to make comparability more than a promise; premature during 0.x.

Migration impact

The reference implementation now carries declared links in a vendor extension under the document root's extensions (§7), with its own diff member under the MetaLogDiff root's extensions, and its top_ngrams holds ngram_size-long sequences only. No schema changed. conformance/metalog_validate.py --selftest: 31/31 fixtures pass on this branch.

🤖 Generated with Claude Code