@tikoci/centrs 0.1.4 → 0.1.7

package/src/explain/symbol-values.ts

@@ -24,7 +24,10 @@ import type {
 	ExplainSymbolOccurrence,
 	ExplainValueOccurrence,
 } from "../explain.ts";
-import { scopeBlocks } from "./blocks.ts";
+import { scopeBlocksIn } from "./blocks.ts";
+import { documentRange, type MaskedRange, nestedRange } from "./segment.ts";
+import type { SplitOwnerIndex } from "./split-owner.ts";
+import { buildSplitOwnerIndex } from "./split-owner.ts";
 import type { SymbolOccurrence } from "./symbols.ts";
 import type { DocumentVerbSplit } from "./verbsplit.ts";
 
@@ -36,88 +39,118 @@ interface BlockInfo {
 	branchArm?: "do" | "else";
 }
 
+/**
+ * One binding's reaching literals at a program point.
+ *
+ * Treated as immutable: a state is replaced, never edited in place, so the same
+ * object can sit in the live map and in a journal entry at once. That aliasing
+ * is what makes an unchanged binding cost nothing at a block edge (#320).
+ */
 type BindingState = {
-	valueIds: Set<string>;
-	unknown: boolean;
+	readonly valueIds: ReadonlySet<string>;
+	readonly unknown: boolean;
 };
 
-function cloneStateMap(
-	source: Map<string, BindingState>,
-): Map<string, BindingState> {
-	const out = new Map<string, BindingState>();
-	for (const [k, v] of source)
-		out.set(k, { valueIds: new Set(v.valueIds), unknown: v.unknown });
-	return out;
-}
-
-function setsEqual(a: Set<string>, b: Set<string>): boolean {
+function setsEqual(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
 	if (a.size !== b.size) return false;
 	for (const v of a) if (!b.has(v)) return false;
 	return true;
 }
 
-function mergeExhaustiveBranches(
-	left: Map<string, BindingState>,
-	right: Map<string, BindingState>,
-): Map<string, BindingState> {
-	const merged = new Map<string, BindingState>();
-	const allIds = new Set<string>([...left.keys(), ...right.keys()]);
-	for (const id of allIds) {
-		const a = left.get(id);
-		const b = right.get(id);
-		if (a === undefined || b === undefined) {
-			const present = a ?? b;
-			if (present !== undefined)
-				merged.set(id, {
-					valueIds: new Set(present.valueIds),
-					unknown: true,
-				});
-			continue;
-		}
-		merged.set(id, {
-			valueIds: new Set([...a.valueIds, ...b.valueIds]),
-			unknown: a.unknown || b.unknown,
-		});
+/**
+ * Merge one binding across a non-exhaustive block edge: the block may not have
+ * run, so the state after it admits both the pre-block value and whatever the
+ * block left. A loop body may also have run more than once, which is what makes
+ * a changed binding `unknown` even when both ends spell the same literal.
+ *
+ * Returning `snap` itself when the block did not change the binding is
+ * deliberate: it is the case that used to cost a full map copy.
+ */
+function mergeBlockExit(
+	snap: BindingState | undefined,
+	current: BindingState,
+	isLoop: boolean,
+): BindingState {
+	// Introduced inside the block: after the block it may never have been set.
+	if (snap === undefined)
+		return { valueIds: new Set(current.valueIds), unknown: true };
+	if (
+		!snap.unknown &&
+		!current.unknown &&
+		setsEqual(snap.valueIds, current.valueIds)
+	)
+		return snap;
+	return {
+		valueIds: new Set([...snap.valueIds, ...current.valueIds]),
+		unknown: snap.unknown || current.unknown || isLoop,
+	};
+}
+
+/**
+ * Merge one binding across an exhaustive `if`/`else` pair. Exactly one arm runs,
+ * so a value seen in both arms stays known and the reaching set is their union;
+ * a binding only one arm defines is `unknown` after the merge.
+ */
+function mergeBranchArms(
+	left: BindingState | undefined,
+	right: BindingState | undefined,
+): BindingState | undefined {
+	if (left === undefined || right === undefined) {
+		const present = left ?? right;
+		if (present === undefined) return undefined;
+		return { valueIds: new Set(present.valueIds), unknown: true };
 	}
-	return merged;
+	return {
+		valueIds: new Set([...left.valueIds, ...right.valueIds]),
+		unknown: left.unknown || right.unknown,
+	};
 }
 
 /**
- * Collect all scope blocks in `text`, rebased to `base`, recursively.
+ * Collect all scope blocks in `range`, recursively.
  *
  * `splits` are the flattened statement splits for the same document; they are
  * used to decide whether a `do={...}` body belongs to a loop verb (`foreach`,
  * `for`, `while`) or to a branch (`if`, `do`, `else`, `on-error`).
+ *
+ * The range replaces the `(text, base)` pair it used to take — `base` was
+ * already the body's offset in the document, so nothing is lost, and the
+ * document's comment mask now descends with it instead of being re-derived over
+ * each nested body. A body carries every body below it, so that re-derivation
+ * was the O(bytes x depth) term (#322).
  */
 function collectBlocks(
-	text: string,
-	base: number,
-	analyzed: string,
+	range: MaskedRange,
+	owners: SplitOwnerIndex,
 	splits: readonly DocumentVerbSplit[],
 ): BlockInfo[] {
 	const out: BlockInfo[] = [];
-	const blocks = scopeBlocks(text).map((block) => {
-		const start = base + block.start;
+	const blocks = scopeBlocksIn(range).map((block) => {
+		const start = range.start + block.start;
 		const bracePos = start - 1;
-		const ownerIndex = owningSplitIndex(
-			analyzed,
-			splits,
-			bracePos,
-			bracePos + 1,
-		);
+		const ownerIndex = owners.ownerOf(bracePos, bracePos + 1);
 		return {
 			block,
 			ownerIndex,
 			owner: ownerIndex === undefined ? undefined : splits[ownerIndex],
 		};
 	});
+	// Group the siblings once. Re-filtering `blocks` inside a loop over
+	// `blocks` is the same quadratic shape #317 removed from the owner lookup,
+	// and a `do={…}`-heavy document grows both factors together.
+	const byOwner = new Map<number, typeof blocks>();
+	for (const entry of blocks) {
+		if (entry.ownerIndex === undefined) continue;
+		const list = byOwner.get(entry.ownerIndex);
+		if (list === undefined) byOwner.set(entry.ownerIndex, [entry]);
+		else list.push(entry);
+	}
 	const exhaustiveGroups = new Set<number>();
-	for (const candidate of blocks) {
-		if (candidate.ownerIndex === undefined) continue;
-		if (candidate.owner?.verb?.toLowerCase() !== "if") continue;
-		const siblings = blocks.filter(
-			(other) => other.ownerIndex === candidate.ownerIndex,
-		);
+	// One pass per owner, not per block: every sibling of an `if` reaches the
+	// same verdict, so asking each of them re-runs both filters over the whole
+	// group. Siblings share an owner index, so they share the owner itself.
+	for (const [ownerIndex, siblings] of byOwner) {
+		if (siblings[0]?.owner?.verb?.toLowerCase() !== "if") continue;
 		const doBlocks = siblings.filter(
 			(other) => other.block.name.toLowerCase() === "do",
 		);
@@ -130,11 +163,11 @@ function collectBlocks(
 			(doBlocks[0]?.block.start ?? Number.POSITIVE_INFINITY) <
 				(elseBlocks[0]?.block.start ?? Number.NEGATIVE_INFINITY)
 		)
-			exhaustiveGroups.add(candidate.ownerIndex);
+			exhaustiveGroups.add(ownerIndex);
 	}
 
 	for (const { block: b, ownerIndex, owner } of blocks) {
-		const start = base + b.start;
+		const start = range.start + b.start;
 		const end = start + b.body.length;
 		// If source mapping cannot identify the owning statement, use loop-like
 		// merging: an incomplete reaching set is safer than treating an unknown
@@ -156,7 +189,13 @@ function collectBlocks(
 				? { branchGroup: ownerIndex, branchArm }
 				: {}),
 		});
-		out.push(...collectBlocks(b.body, start, analyzed, splits));
+		out.push(
+			...collectBlocks(
+				nestedRange(range, b.start, b.start + b.body.length),
+				owners,
+				splits,
+			),
+		);
 	}
 	return out;
 }
@@ -170,35 +209,11 @@ function collectBlocks(
  * link `i` to the `in` attribute. Only the same statement's values are
  * candidates, which also prevents cross-statement mis-linking.
  */
-function owningSplitIndex(
-	analyzed: string,
-	splits: readonly DocumentVerbSplit[],
-	start: number,
-	end: number,
-): number | undefined {
-	let owner: number | undefined;
-	let ownerLength = Number.POSITIVE_INFINITY;
-	for (let i = 0; i < splits.length; i++) {
-		const split = splits[i] as DocumentVerbSplit;
-		if (split.span.start > start || end > split.span.end) continue;
-		// A widened fallback span cannot prove statement ownership. Match the
-		// same addressability gate used by `valuesOf`/`argumentsOf`.
-		if (analyzed.slice(split.span.start, split.span.end) !== split.text)
-			continue;
-		const length = split.span.end - split.span.start;
-		if (length < ownerLength) {
-			owner = i;
-			ownerLength = length;
-		}
-	}
-	return owner;
-}
-
 function defValueId(
 	occurrence: SymbolOccurrence,
 	splitIndex: number | undefined,
 	values: readonly ExplainValueOccurrence[],
-	valueSplitIndexes: readonly (number | undefined)[],
+	positionalValuesBySplit: ReadonlyMap<number, readonly number[]>,
 ): string | undefined {
 	if (
 		occurrence.role !== "declaration" &&
@@ -217,18 +232,15 @@ function defValueId(
 
 	let best: ExplainValueOccurrence | undefined;
 	let bestDist = Number.POSITIVE_INFINITY;
-	for (let i = 0; i < values.length; i++) {
+	// Parent statement spans include their scope bodies. Requiring the
+	// innermost addressable statement to match prevents `:local f do={:put 1}`
+	// from claiming the body's `1`, and prevents one branch from lending a
+	// literal to a non-literal definition in another branch. That same
+	// requirement is what lets the candidates be bucketed per statement once
+	// instead of re-scanned per symbol (#317).
+	for (const i of positionalValuesBySplit.get(splitIndex) ?? []) {
 		const value = values[i] as ExplainValueOccurrence;
-		// Parent statement spans include their scope bodies. Requiring the
-		// innermost addressable statement to match prevents `:local f do={:put
-		// 1}` from claiming the body's `1`, and prevents one branch from lending
-		// a literal to a non-literal definition in another branch.
-		if (valueSplitIndexes[i] !== splitIndex) continue;
-		if (value.kind === "element") continue;
 		if (value.span.start <= occurrence.start) continue;
-		// RouterOS declaration/assignment RHS syntax is positional. Attribute
-		// values in the same statement belong to the directive, not this symbol.
-		if (value.kind !== "positional") continue;
 		const dist = value.span.start - occurrence.end;
 		if (dist < 0 || dist >= bestDist) continue;
 		bestDist = dist;
@@ -252,12 +264,25 @@ export function augmentSymbolOccurrences(
 	splits: readonly DocumentVerbSplit[],
 ): ExplainSymbolOccurrence[] {
 	const augmented: ExplainSymbolOccurrence[] = [];
+	const owners = buildSplitOwnerIndex(analyzed, splits);
 	const symbolSplitIndexes = symbols.map((occ) =>
-		owningSplitIndex(analyzed, splits, occ.start, occ.end),
-	);
-	const valueSplitIndexes = values.map((value) =>
-		owningSplitIndex(analyzed, splits, value.span.start, value.span.end),
+		owners.ownerOf(occ.start, occ.end),
 	);
+	// RouterOS declaration/assignment RHS syntax is positional, so an attribute
+	// value in the same statement belongs to the directive, not to the symbol —
+	// `:foreach i in={…}` must not link `i` to the `in` attribute. Bucketing
+	// only the positional values keeps `defValueId`'s search inside the one
+	// statement that can supply the RHS.
+	const positionalValuesBySplit = new Map<number, number[]>();
+	for (let i = 0; i < values.length; i++) {
+		const value = values[i] as ExplainValueOccurrence;
+		if (value.kind !== "positional") continue;
+		const splitIndex = owners.ownerOf(value.span.start, value.span.end);
+		if (splitIndex === undefined) continue;
+		const list = positionalValuesBySplit.get(splitIndex);
+		if (list === undefined) positionalValuesBySplit.set(splitIndex, [i]);
+		else list.push(i);
+	}
 	const valueOrder = new Map(values.map((value, index) => [value.id, index]));
 	// Map from occurrence index -> valueId for quick lookup during flow pass
 	const defMap = new Map<number, string>();
@@ -267,12 +292,12 @@ export function augmentSymbolOccurrences(
 			occ,
 			symbolSplitIndexes[i],
 			values,
-			valueSplitIndexes,
+			positionalValuesBySplit,
 		);
 		if (vid !== undefined) defMap.set(i, vid);
 	}
 
-	const blocks = collectBlocks(analyzed, 0, analyzed, splits);
+	const blocks = collectBlocks(documentRange(analyzed), owners, splits);
 	type FlowEvent =
 		| {
 				offset: number;
@@ -331,18 +356,51 @@ export function augmentSymbolOccurrences(
 
 	// Occurrences are already sorted by start
 	const ordered = symbols.map((occ, index) => ({ occ, index }));
-	// Flow state
-	let current = new Map<string, BindingState>();
-	const stack: {
-		snapshot: Map<string, BindingState>;
+	// Flow state.
+	//
+	// One live map, plus a journal per open block recording the pre-block value
+	// of every binding that block writes. A block edge then costs what the block
+	// CHANGED, not what the document declares (#320): snapshotting the whole map
+	// at every enter and rebuilding it at every exit made a branch-dense script
+	// quadratic — 3.1 M binding copies on 89 KiB — because blocks and bindings
+	// both grow with the document.
+	const current = new Map<string, BindingState>();
+	type Frame = {
+		/** binding id -> its value when this block was entered (absent = new). */
+		journal: Map<string, BindingState | undefined>;
 		isLoop: boolean;
 		branchGroup?: number;
 		branchArm?: "do" | "else";
-	}[] = [];
+	};
+	const stack: Frame[] = [];
+	/** Per exhaustive `if` group: the `do` arm's pre/post pair per touched id. */
 	const branchGroups = new Map<
 		number,
-		{ doFinal: Map<string, BindingState> }
+		Map<string, { snap: BindingState | undefined; doFinal: BindingState }>
 	>();
+	/** Record a binding's pre-block value once per frame; later writes keep it. */
+	const note = (
+		frame: Frame | undefined,
+		id: string,
+		before: BindingState | undefined,
+	): void => {
+		if (frame !== undefined && !frame.journal.has(id))
+			frame.journal.set(id, before);
+	};
+	const setBinding = (id: string, state: BindingState): void => {
+		note(stack[stack.length - 1], id, current.get(id));
+		current.set(id, state);
+	};
+	/** Write a merged/rewound value for a binding the enclosing frame now owns. */
+	const applyToParent = (
+		id: string,
+		before: BindingState | undefined,
+		after: BindingState | undefined,
+	): void => {
+		note(stack[stack.length - 1], id, before);
+		if (after === undefined) current.delete(id);
+		else current.set(id, after);
+	};
 	let eventIdx = 0;
 	const processEventsUpTo = (pos: number): void => {
 		while (eventIdx < events.length) {
@@ -351,86 +409,64 @@ export function augmentSymbolOccurrences(
 			eventIdx++;
 			if (ev.type === "unknown-definition") {
 				for (const bid of ev.bindingIds)
-					current.set(bid, { valueIds: new Set(), unknown: true });
+					setBinding(bid, { valueIds: new Set(), unknown: true });
 				continue;
 			}
 			if (ev.type === "enter") {
 				stack.push({
-					snapshot: cloneStateMap(current),
+					journal: new Map(),
 					isLoop: ev.isLoop,
 					...(ev.branchGroup === undefined || ev.branchArm === undefined
 						? {}
 						: { branchGroup: ev.branchGroup, branchArm: ev.branchArm }),
 				});
-			} else {
-				const top = stack.pop();
-				if (top === undefined) continue;
-				const snapshot = top.snapshot;
-				const isLoop = top.isLoop;
-				if (top.branchGroup !== undefined && top.branchArm === "do") {
-					branchGroups.set(top.branchGroup, {
-						doFinal: cloneStateMap(current),
-					});
-					current = cloneStateMap(snapshot);
-					continue;
-				}
-				if (top.branchGroup !== undefined && top.branchArm === "else") {
-					const group = branchGroups.get(top.branchGroup);
-					if (group !== undefined) {
-						current = mergeExhaustiveBranches(group.doFinal, current);
-						branchGroups.delete(top.branchGroup);
-						continue;
-					}
-				}
-				const merged = cloneStateMap(snapshot);
-				const allIds = new Set<string>([...snapshot.keys(), ...current.keys()]);
-				for (const id of allIds) {
-					const snap = snapshot.get(id);
-					const cur = current.get(id);
-					if (snap === undefined && cur !== undefined) {
-						// Defined inside block only — after block it may not have run
-						merged.set(id, {
-							valueIds: new Set(cur.valueIds),
-							unknown: true,
-						});
-					} else if (snap !== undefined && cur !== undefined) {
-						const equal =
-							!snap.unknown &&
-							!cur.unknown &&
-							setsEqual(snap.valueIds, cur.valueIds);
-						if (!equal) {
-							const union = new Set<string>([
-								...snap.valueIds,
-								...cur.valueIds,
-							]);
-							const unknown = snap.unknown || cur.unknown || isLoop;
-							merged.set(id, { valueIds: union, unknown });
-						} else if (snap.unknown || cur.unknown) {
-							merged.set(id, {
-								valueIds: new Set(snap.valueIds),
-								unknown: true,
-							});
-						}
-					}
+				continue;
+			}
+			const top = stack.pop();
+			if (top === undefined) continue;
+			// A binding the block never wrote has the same state on both sides of
+			// the edge, and every merge rule below maps that pair back to itself.
+			// So the journal — the bindings the block DID write — is the whole
+			// edge, whatever else the document has declared.
+			if (top.branchGroup !== undefined && top.branchArm === "do") {
+				const arm = new Map<
+					string,
+					{ snap: BindingState | undefined; doFinal: BindingState }
+				>();
+				for (const [id, snap] of top.journal) {
+					arm.set(id, { snap, doFinal: current.get(id) as BindingState });
+					// Rewind: the `else` arm starts from the state before the `if`.
+					if (snap === undefined) current.delete(id);
+					else current.set(id, snap);
 				}
-				// Loops make every variable assigned inside unknown after exit,
-				// even if the pre/post sets happen to match (e.g. same literal)
-				if (isLoop) {
-					for (const id of current.keys()) {
-						const snap = snapshot.get(id);
-						const cur = current.get(id);
-						if (cur === undefined) continue;
-						if (snap === undefined) {
-							const m = merged.get(id);
-							if (m !== undefined) m.unknown = true;
-						} else if (!setsEqual(snap.valueIds, cur.valueIds)) {
-							const m = merged.get(id);
-							if (m !== undefined) m.unknown = true;
-						}
+				branchGroups.set(top.branchGroup, arm);
+				continue;
+			}
+			if (top.branchGroup !== undefined && top.branchArm === "else") {
+				const arm = branchGroups.get(top.branchGroup);
+				if (arm !== undefined) {
+					const touched = new Set<string>([
+						...arm.keys(),
+						...top.journal.keys(),
+					]);
+					for (const id of touched) {
+						const recorded = arm.get(id);
+						// Untouched by one arm means that arm left the pre-`if` value.
+						const before =
+							recorded === undefined ? top.journal.get(id) : recorded.snap;
+						const left = recorded === undefined ? before : recorded.doFinal;
+						applyToParent(id, before, mergeBranchArms(left, current.get(id)));
 					}
+					branchGroups.delete(top.branchGroup);
+					continue;
 				}
-				current = merged;
 			}
+			for (const [id, snap] of top.journal)
+				applyToParent(
+					id,
+					snap,
+					mergeBlockExit(snap, current.get(id) as BindingState, top.isLoop),
+				);
 		}
 	};
 
@@ -453,7 +489,7 @@ export function augmentSymbolOccurrences(
 			(base as { valueId?: string }).valueId = vid;
 			// Update flow state for this binding
 			for (const bid of occ.bindingIds) {
-				current.set(bid, { valueIds: new Set([vid]), unknown: false });
+				setBinding(bid, { valueIds: new Set([vid]), unknown: false });
 			}
 		} else if (
 			occ.role === "declaration" ||
@@ -463,7 +499,7 @@ export function augmentSymbolOccurrences(
 			// Defining occurrence with no literal RHS — introduces unknown
 			if (occ.bindingIds.length > 0 && !deferredDefinitions.has(index)) {
 				for (const bid of occ.bindingIds) {
-					current.set(bid, { valueIds: new Set(), unknown: true });
+					setBinding(bid, { valueIds: new Set(), unknown: true });
 				}
 			}
 		} else if (occ.role === "reference" || occ.role === "field") {

package/src/explain/symbols.ts

@@ -477,7 +477,10 @@ const isIdentStart = (c: string): boolean => /[A-Za-z_]/.test(c);
 export function resolveSymbols(original: string): SymbolAnalysis {
 	const analysis = analyzeCoordinates(original);
 	// `analyzed` is pure ASCII, so a string built from it has index === byte.
-	const text = new TextDecoder().decode(analysis.analyzed);
+	// An already-ASCII input is that string, so the decode is skipped (#322).
+	const text = analysis.ascii
+		? original
+		: new TextDecoder().decode(analysis.analyzed);
 
 	// S7's "inside a `(…)` expression" test, precomputed in one forward pass.
 	// Scanning backward per bare word was O(n²) on a long single-line script: an
@@ -875,6 +878,23 @@ export function resolveSymbols(original: string): SymbolAnalysis {
 			break;
 		}
 
+		// --- `'` is not a RouterOS token (#355) ---------------------------------
+		//
+		// Same fail-closed stop as the malformed escape above, for the same reason:
+		// the device rejects at this byte and classes nothing after it, so carrying
+		// confident symbol classes across it would publish facts about bytes the
+		// console never reached. `:put 'abc'; :put $after` must not name `$after`.
+		//
+		// This walk reaches here only in CODE — a `"` string is consumed by the
+		// quote phase above and a comment by the `#` branch below — so an
+		// apostrophe inside either never trips it, matching `segment.ts`.
+		// Occurrences BEFORE the defect stand (the lab's X1 rule).
+		if (c === "'") {
+			defects.push(defectAt("invalid-apostrophe", i, "'"));
+			defect = true;
+			break;
+		}
+
 		// --- comments: `#` in statement-leading position (Q1 rule H4) ------------
 		//
 		// Done inline rather than through `segment.ts`'s shared `maskComments`:

package/src/explain/transport.ts

@@ -101,6 +101,16 @@ export interface ExplainTransportInput {
 	arguments: ExplainArguments;
 	/** The statement exactly as written, for the execute invocation. */
 	source: string;
+	/**
+	 * Why the statement is not accepted by RouterOS, when the analysis has decided
+	 * that it is not (#311).
+	 *
+	 * Distinct from an unread argument list, which means "offline cannot name the
+	 * request" and correctly falls through to `execute` — the raw CLI surface can
+	 * still carry those bytes. Here the bytes themselves are the defect, so no
+	 * centrs surface should be offered for them and none is rendered.
+	 */
+	rejected?: string;
 }
 
 export interface ExplainTransportOptions {
@@ -424,6 +434,13 @@ export function classifyExplainTransport(
 	const { path, verb, args = {} } = input.command;
 	const lower = verb.toLowerCase();
 
+	// Before every mapping rule: a statement the analysis has REJECTED gets no
+	// invocation at all. Falling through to `execute` here would print a
+	// ready-to-paste `centrs execute` line for bytes the same result declares a
+	// syntax error, which is the false confident reading in a second place.
+	if (input.rejected !== undefined)
+		return unknown(input.rejected, options.evidenceId);
+
 	// Root scripting directives have no RouterOS REST path. They always ride the
 	// raw execute surface, regardless of whether their operands are literal.
 	if (path === "/")

package/src/explain/value-tokens.ts

@@ -2,11 +2,11 @@
  * B2 value fill — claims argument value bytes and array-literal interiors on the residual.
  *
  * This is the third B2 fill of #264, after the argument `name=` fill. It runs
- * **after** proof-only `spans` (comment + variable-*) and the `arg` fill and
- * **before** the operator fill, so the fill order is structural:
- * `spans → arg → value → operator`. That ordering retires the glued-dot residue
- * already noted in `operator-tokens.ts`: once value bytes are claimed a `.`
- * inside a value is no longer read as concatenation.
+ * **after** proof-only `spans` (comment + variable-*), the `arg` fill and the
+ * `escaped` fill, and **before** the operator fill, so the fill order is
+ * structural: `spans → arg → escaped → value → operator`. That ordering retires
+ * the glued-dot residue already noted in `operator-tokens.ts`: once value bytes
+ * are claimed a `.` inside a value is no longer read as concatenation.
  *
  * Source is `data.values.occurrences` (already rebased into document analyzed-byte
  * space by `src/explain.ts`), not `Argument.valueSpan`. That is the load-bearing
@@ -20,14 +20,17 @@
  * that is nobody's `parent`. Container detection is `Set` of `parent` ids — no
  * tree walk, members follow their container in the same flat list.
  *
- * `span` is quotes-INCLUDED by contract (deliberate; the quotes/escapes fill is
- * a separate staging row and must not double-claim them).
+ * `span` is quotes-INCLUDED by contract, and the quotes stay part of the `value`
+ * run — a consumer recovers them from its own first and last byte (#264 B5).
+ * Escapes do NOT: the `escaped` fill claims them one stage earlier, so a value
+ * carrying one arrives here already holed and this fill emits a fragment either
+ * side. Nothing double-claims, because that fill offered only residual.
  *
- * Vocabulary is provisional until #264 B5: one `value` class for every leaf span,
- * regardless of shape/observed/schema type — the three #225 facts stay where
- * they already are, in `data.values[]`, joined by offset. Do not read
- * `ExplainValueOccurrence.facts` to pick a class. Whether `value` later splits
- * per shape is B5 and does not move byte coverage.
+ * One `value` class for every leaf span, regardless of shape/observed/schema
+ * type — the three #225 facts stay where they already are, in `data.values[]`,
+ * joined by offset. Do not read `ExplainValueOccurrence.facts` to pick a class.
+ * #264 B5 kept this merge for that reason: a class per shape would be a fourth
+ * copy of those axes, free to contradict the three that are already published.
  *
  * ~1,720 leaf bytes are already held by `variable-*` spans (a variable inside
  * a quoted value). Reuses the clipping shape from `arg-tokens.ts`: offer only