foottrace 0.0.0-stage → 1.0.0

package/dist/lib/memory/equality.js

@@ -0,0 +1,265 @@
+"use strict";
+/**
+ * equality.ts — structural equality of committed-state values: THE owner of
+ * "what counts as a change". What `TransactionBuffer`'s net-change filter, the
+ * admitted record's compare, the read model's writer rule and the
+ * borrowed-mutation guard all ask. Its one import is the classifier of value
+ * kinds (`capture/valueKinds.ts`, a leaf); re-exported from `utils.ts`, so no
+ * importer moved.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepEqual = void 0;
+const valueKinds_js_1 = require("../capture/valueKinds.js");
+/**
+ * Structural deep equality for committed-state values.
+ *
+ * Used by {@link TransactionBuffer} to decide whether a stage actually CHANGED
+ * a path or merely re-wrote / reverted it to the value it already held (a
+ * "no-op write"), and by `borrowedMutation.firstDifferingPath` to find where a
+ * borrowed read moved. Committed state must survive `structuredClone`, so the
+ * values it can hold are the kinds the clone keeps, and two values are equal
+ * when a record holds the same thing for both. Every kind has ONE arm below
+ * (`equalPairs`' switch over `ValueKind` — a kind added to the union does not
+ * compile until it is compared). Before 9.22.0 a Date, Map or Set was compared
+ * as an object with no own keys, and until 9.44.2 so were a RegExp, an Error,
+ * a boxed primitive, an ArrayBuffer, a DataView and a Blob: any two of a kind
+ * were "equal", so `$setValue('re', /y/g)` over `/x/g` committed no row and
+ * live state kept the OLD value.
+ *
+ * Semantics:
+ *   - reference / identical-primitive short-circuits first (cheap fast path)
+ *   - `NaN` equals `NaN` (primitive compare falls back to `Object.is`)
+ *   - two values of different KINDS are never equal (a `Date` is never `{}`,
+ *     an array never `{ 0: … }`)
+ *   - `Date`: same `getTime()` (two invalid dates are equal)
+ *   - `RegExp`: same `source` and `flags` (the clone resets `lastIndex`)
+ *   - `Error`: the same restored kind (one of the six built-in error names,
+ *     else `Error`), own `message`, `stack` and own `cause` (deep) — what the
+ *     clone keeps; any other own field is dropped by it, so it never counts
+ *     (the admitted record's law)
+ *   - a boxed primitive: the same wrapper type and the same primitive inside
+ *   - an `ArrayBuffer`: length, resizability and bytes; a typed array or a
+ *     `DataView`: its type and the bytes IT views — never the rest of its
+ *     buffer (a Node `Buffer` views a slice of a shared pool, and the record
+ *     keeps the view's bytes only: `capture/freeze.ts · freezeRecord`)
+ *   - `Map`: same size AND, per key of `a`, `b` holds a deep-equal value —
+ *     keys by `Map` identity (`SameValueZero`), values deep
+ *   - `Set`: same size AND every member of `a` is deep-equal to SOME member
+ *     of `b` (order-insensitive — a Set has no order to compare by)
+ *   - an OPAQUE value (a Blob, a `DOMException` — content this library cannot
+ *     read): by the caller's {@link OpaqueRule} — equal only to itself by
+ *     default (replacing one is always a change), or, when both sides are
+ *     copies of one record, equal to any other of its kind
+ *   - arrays: equal length AND deep-equal element-wise (order-sensitive; an
+ *     array's expando keys are out of contract and not compared)
+ *   - objects: identical set of keys that HOLD a value AND deep-equal per key.
+ *     An own key whose value is `undefined` counts as ABSENT: it is this
+ *     library's other spelling of a deleted key (`'full'` mode flattens
+ *     `delete` into `key: undefined`; `'delta'` mode's `delete` verb removes
+ *     the key), and every consumer — JSON, the fold, `commitValueAt`, the
+ *     mirror — reads the two spellings as one state. So must the net-change
+ *     filter (9.19.1): `{}` and `{ k: undefined }` are not a change. Arrays
+ *     are untouched — a slot holding `undefined` is still a slot.
+ *
+ * Cost & safety:
+ *   - Allocates only transient `Object.keys` arrays, an error's property
+ *     descriptors and a byte view per compared buffer — no clones (but one
+ *     probe clone per class prototype, remembered: `capture/valueKinds.ts ·
+ *     kindOf`). It is strictly cheaper than the `structuredClone` the commit
+ *     already performs.
+ *   - Primitive comparisons (the bulk of state) are O(1) via the `===` /
+ *     `Object.is` fast paths; only nested objects/arrays incur a walk, bounded
+ *     by the value's own size.
+ *   - Terminates on CYCLIC values (9.18.1): a state value must survive
+ *     `structuredClone`, and `structuredClone` preserves cycles — so a
+ *     self-referencing value is a legal value, not an out-of-contract one. A
+ *     pair of objects already under comparison is treated as equal (the
+ *     structural answer, lodash `isEqual` semantics); acyclic inputs see no
+ *     change. Dev mode still warns about cycles at write time
+ *     (`ScopeFacade.setValue`) because they surprise narrative and JSON.
+ */
+function deepEqual(a, b, opaque = 'identity') {
+    return equalPairs(a, b, undefined, opaque);
+}
+exports.deepEqual = deepEqual;
+function equalPairs(a, b, seen, opaque) {
+    if (a === b)
+        return true; // same reference or identical primitive
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null)
+        return a === b; // one is null, the other isn't
+    if (typeof a !== 'object')
+        return Object.is(a, b); // NaN-safe primitive compare
+    const kind = (0, valueKinds_js_1.kindOf)(a);
+    if (kind !== (0, valueKinds_js_1.kindOf)(b))
+        return false;
+    switch (kind) {
+        // Atoms: their content is a slot, not their keys.
+        case 'date':
+            return Object.is(Date.prototype.getTime.call(a), Date.prototype.getTime.call(b));
+        case 'regexp':
+            return a.source === b.source && a.flags === b.flags;
+        case 'boxed':
+            return tagOf(a) === tagOf(b) && equalPairs(a.valueOf(), b.valueOf(), seen, opaque);
+        case 'buffer':
+            return equalBuffers(a, b);
+        case 'view':
+            return equalViews(a, b);
+        case 'opaque':
+            return opaque === 'copies' && tagOf(a) === tagOf(b); // `a === b` was answered above
+        case 'plain':
+        case 'array':
+        case 'map':
+        case 'set':
+        case 'error':
+            return equalContainers(a, b, kind, seen, opaque);
+        default:
+            return unknownKind(kind);
+    }
+}
+/** The kinds whose content is other values: compared part by part, under the cycle guard. */
+function equalContainers(a, b, kind, seen, opaque) {
+    // Cycle guard — a pair we are already inside is equal by assumption.
+    seen ??= new WeakMap();
+    let partners = seen.get(a);
+    if (partners?.has(b))
+        return true;
+    if (!partners)
+        seen.set(a, (partners = new WeakSet()));
+    partners.add(b);
+    if (kind === 'map')
+        return equalMaps(a, b, seen, opaque);
+    if (kind === 'set')
+        return equalSets(a, b, seen, opaque);
+    if (kind === 'error')
+        return equalErrors(a, b, seen, opaque);
+    if (kind === 'array') {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (!equalPairs(a[i], b[i], seen, opaque))
+                return false;
+        }
+        return true;
+    }
+    // Objects: only keys that HOLD a value take part — an own `undefined` is a
+    // deleted key, the same state as an absent one (see the contract above).
+    let aHeld = 0;
+    for (const key of Object.keys(a)) {
+        if (a[key] === undefined)
+            continue;
+        aHeld++;
+        if (!Object.prototype.hasOwnProperty.call(b, key))
+            return false;
+        if (!equalPairs(a[key], b[key], seen, opaque))
+            return false;
+    }
+    let bHeld = 0;
+    for (const key of Object.keys(b))
+        if (b[key] !== undefined)
+            bHeld++;
+    return aHeld === bHeld;
+}
+function unknownKind(kind) {
+    throw new TypeError(`deepEqual: no comparison for the value kind '${String(kind)}'`);
+}
+/** `[object Number]`, `[object Uint8Array]` … — the built-in type a boxed value or a view carries. */
+function tagOf(value) {
+    return Object.prototype.toString.call(value);
+}
+/** The same view type over the same bytes — the bytes the view sees, wherever they sit in its buffer. */
+function equalViews(a, b) {
+    if (tagOf(a) !== tagOf(b) || a.byteLength !== b.byteLength)
+        return false;
+    if (a.buffer === b.buffer && a.byteOffset === b.byteOffset)
+        return true;
+    const p = new Uint8Array(a.buffer, a.byteOffset, a.byteLength);
+    const q = new Uint8Array(b.buffer, b.byteOffset, b.byteLength);
+    for (let i = 0; i < p.length; i++)
+        if (p[i] !== q[i])
+            return false;
+    return true;
+}
+/** The same length, resizability and bytes. */
+function equalBuffers(a, b) {
+    if (a === b)
+        return true;
+    const x = a;
+    const y = b;
+    if (x.byteLength !== y.byteLength || x.resizable !== y.resizable || x.maxByteLength !== y.maxByteLength) {
+        return false;
+    }
+    const p = new Uint8Array(a);
+    const q = new Uint8Array(b);
+    for (let i = 0; i < p.length; i++)
+        if (p[i] !== q[i])
+            return false;
+    return true;
+}
+/** The six error names `structuredClone` restores; any other name comes back an `Error`. */
+const ERROR_NAMES = new Set(['EvalError', 'RangeError', 'ReferenceError', 'SyntaxError', 'TypeError', 'URIError']);
+/**
+ * Two errors as the clone keeps them: the restored kind, the own `message`,
+ * the `stack` and the own `cause` (deep). Any other own field is dropped by
+ * the clone, so it never counts.
+ */
+function equalErrors(a, b, seen, opaque) {
+    if (errorKindOf(a) !== errorKindOf(b) || stackOf(a) !== stackOf(b))
+        return false;
+    const aMessage = ownData(a, 'message');
+    const bMessage = ownData(b, 'message');
+    if (String(aMessage?.value) !== String(bMessage?.value) || !aMessage !== !bMessage)
+        return false;
+    const aCause = ownData(a, 'cause');
+    const bCause = ownData(b, 'cause');
+    if (!aCause || !bCause)
+        return !aCause === !bCause;
+    return equalPairs(aCause.value, bCause.value, seen, opaque);
+}
+function errorKindOf(error) {
+    const name = String(error.name);
+    return ERROR_NAMES.has(name) ? name : 'Error';
+}
+function stackOf(error) {
+    const stack = error.stack;
+    return typeof stack === 'string' ? stack : undefined;
+}
+/** An own DATA property, boxed — how the clone reads an error's `message` and `cause`. */
+function ownData(value, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor !== undefined && Object.prototype.hasOwnProperty.call(descriptor, 'value')
+        ? { value: descriptor.value }
+        : undefined;
+}
+function equalMaps(a, b, seen, opaque) {
+    if (a.size !== b.size)
+        return false;
+    for (const [key, value] of a) {
+        if (!b.has(key))
+            return false;
+        if (!equalPairs(value, b.get(key), seen, opaque))
+            return false;
+    }
+    return true;
+}
+/**
+ * Order-insensitive, deep per member. Quadratic in the worst case for sets of
+ * objects — a set of primitives (the common shape) is one `has` per member.
+ */
+function equalSets(a, b, seen, opaque) {
+    if (a.size !== b.size)
+        return false;
+    const unmatched = [...b];
+    for (const member of a) {
+        // SameValueZero first — primitives and shared references, one `has`.
+        // Each match retires its slot so two structurally-equal members of `a`
+        // cannot both claim the same member of `b`.
+        const at = unmatched.indexOf(member);
+        const found = at >= 0 ? at : unmatched.findIndex((candidate) => equalPairs(member, candidate, seen, opaque));
+        if (found < 0)
+            return false;
+        unmatched.splice(found, 1);
+    }
+    return true;
+}

package/dist/lib/memory/eventPosition.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/memory/honesty.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * honesty.ts — the ONE vocabulary for what a reader cannot see.
+ *
+ * WHY THIS FILE EXISTS. A recording cannot always answer what it is asked, and the library says
+ * so in several places, each in its own words: a slice carries `HonestyNote`s and, when it has no
+ * answer, a `missing` reason; a fed edge and an element birth carry a `basis`; a fold carries a
+ * `basis` and its `redacted` paths; a stored log reports `LogGap`s; a causal node carries
+ * `incompleteSources` and `truncated`. A reader that wants to EXPLAIN any of them to a person (a
+ * why-panel, an agent tool) kept its own table of code → sentence, and tables kept apart drift.
+ * This file is that table, once.
+ *
+ * WHAT IT HOLDS.
+ *   - `HONESTY_CODES` — a frozen, closed registry: code → the ONE sentence that says what the code
+ *     means. The shape of rustc's `--explain` and LSP's `Diagnostic.code`: the code is the stable
+ *     key a consumer BRANCHES on; the sentence is for whoever reads the screen. It is not the
+ *     per-instance `detail` a note carries (that names the key, the budget, the rows).
+ *   - `HonestyCode` / `RegisteredCode` — what makes the registry the owner and not a suggestion:
+ *     each public union of these codes (`HonestyNoteCode`, `MissingSliceReason`,
+ *     `MissingProvenanceReason`, `FedBasis`, `AttributionBasis`, `FoldBasis`, and since 9.33.0 `ValueBasis` /
+ *     `WriterBasis` — the basis twins of `commitValueAt` / `findLastWriter`) declares its members
+ *     through `RegisteredCode`, so a member the registry does not hold fails to COMPILE. And
+ *     `test/architecture/honesty-vocabulary.test.ts` asks the type checker for every exported type
+ *     alias of `foottrace` that is a union of string literals: each one is inside the
+ *     registry or is named, with its reason, as not an honesty vocabulary.
+ *
+ * NO OBJECT GAINS A FIELD from being registered. Three signals carry no code of their own — a
+ * `LogGap` (`'log-gap'`), `CausalNode.incompleteSources` (`'incomplete-sources'`) and
+ * `FoldedState.redacted` / `redactedPaths` (`'redacted'`) — and a `truncated: { byDepth, byNodes }`
+ * field means `'truncated'`; they are registered so a reader explains them from the same place.
+ *
+ * NOT HERE: the two strings a redaction leaves where a value was. The engine writes those on every
+ * redacted run; the log's lives in its own leaf, `memory/placeholders.ts` (the scope channel's with
+ * the verdict, in FootPrint's `memory/redaction.ts`), so that an app which only runs charts does not carry these
+ * sentences in its bundle (`HONESTY_CODES` is a pure expression, so a bundler drops it wherever
+ * nothing reads it).
+ *
+ * WHY L0. This file imports NOTHING, and `slice/` and `time-travel/` (L3) type their codes through
+ * it, so it sits below them — the layer table is `scripts/layers.json`.
+ *
+ * @example
+ * ```typescript
+ * import { HONESTY_CODES } from 'foottrace';
+ *
+ * for (const { code } of forwardSlice.notes) console.log(code, '→', HONESTY_CODES[code]);
+ * // reads-not-recorded → This log carries no recorded read at all (the readTracking: 'off' signature), …
+ * HONESTY_CODES[foldedState.basis]; // 'log-only' → No initialState travelled with this log (…), …
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HONESTY_CODES = void 0;
+/**
+ * Every honesty code the trace readers (`foottrace`) speak, with the one sentence that says
+ * what it means.
+ *
+ * Frozen and closed: the keys are exactly the codes below, and {@link HonestyCode} is derived from
+ * them. A new code is one new line here: a union declared through {@link RegisteredCode} cannot hold
+ * a code that is not on it, and `test/architecture/honesty-vocabulary.test.ts` fails on an exported
+ * type alias of `foottrace` that is a union of string literals neither inside the registry
+ * nor named there as not an honesty vocabulary. The values are typed `string`, not literal types,
+ * on purpose: the sentences are for a screen and may be reworded; a consumer branches on the KEY.
+ */
+exports.HONESTY_CODES = Object.freeze({
+    // ── a slice's notes — `HonestyNote.code` (slice/) ─────────────────────────
+    'conservative-fed-edges': "At least one 'fed' edge is stage-level (conservative): its write carries no per-write read provenance, so the edge may not be real — turn on writeProvenance: 'reads-prefix' for exact edges.",
+    'nested-rows': "A write this answer rests on reached the key only through paths inside it (a subflow's input seed, an outputMapper merge-back, a fork child's namespace), so it changed part of the key's value, not the whole: earlier writes may account for the rest, and a reader of the key may not have read the part that write changed.",
+    'pre-run-origin': 'The value being followed was absent or already there before the first write this log can see (initial state, frozen run input or a closure), so who put it there is outside the commit log.',
+    'reads-not-recorded': "This log carries no recorded read at all (the readTracking: 'off' signature), so 'nothing read this value' is unknowable here, not true.",
+    'unknown-key': "This log has no write and no recorded read of the key, which is most likely a typo or the wrong run's log rather than a variable with no history.",
+    truncated: 'A budget (maxDepth or maxNodes) cut the walk, so more of the answer exists beyond the horizon it stopped at.',
+    // ── why a slice has no answer — `missing` (slice/: MissingSliceReason, MissingProvenanceReason) ─
+    'empty-log': 'The commit log holds no commit at all (nothing has executed, or the log handed in is empty), so there is no history to answer from.',
+    'never-written': 'No commit in the range asked about wrote the key — not its whole value, not a path inside it, and not a container around it in a way that changed it (a forward slice or a timeline also found no recorded read on, inside or around it) — so there is no write to start from: any value it has came from the initial state, the frozen run input or a closure, none of which the commit log can see.',
+    'not-an-array': 'The key was written, but its value at the point asked about is not an array (a scalar or object key, a deleted key, or a merge that degraded it), so element provenance does not apply: sliceForKey is the query for it.',
+    // ── how a fed edge was attributed — `ForwardEdge.basis` (slice/: FedBasis) ─
+    'per-write': "This fed edge is exact: the downstream write carries per-write read provenance (TraceEntry.readKeys, recorded under writeProvenance: 'reads-prefix') and that list names the key, so the value was read before the write it feeds.",
+    stage: 'This fed edge is conservative: the downstream write carries no per-write read provenance (the writeProvenance dial was off, or the log is mixed), so all that is known is that its stage read this key and wrote that path in some order, and the edge may not be real.',
+    // ── how an element's birth was attributed — `ElementBirth.basis` (slice/: AttributionBasis) ─
+    'append-verb': "The engine recorded the element in an append row's tail (how commitValues: 'delta' records an array's growth), so the commit that added it is known exactly, not inferred.",
+    'prefix-inference': 'A whole-value write (a set or a merge) kept the previous array as its prefix, so the new tail is attributed to that commit by inference: a write that replaced the array with one that happens to begin the same way looks identical.',
+    'whole-value': "This commit placed the array wholesale (there was no earlier array, or the new one does not begin with it), so every element's birth resets to this commit: exact, but coarse.",
+    // ── how a fold was derived — `FoldedState.basis` (time-travel/) ───────────
+    'initial+log': 'The fold started from the fold base that travelled with the log (initialState) and replayed the commit log onto it, so nothing seeded before the run is missing; rows it could not read are listed apart, in skipped.',
+    'log-only': 'No initialState travelled with this log (a snapshot stored before 9.17, a redacted snapshot or a hand-built log), so the fold started from an empty object: a key seeded before the run is whole only once a commit since wrote its whole value, and until then it holds just what its merges, appends and nested writes added, or nothing.',
+    // ── a row of a stored log that is not a commit bundle — `LogGap` ──────────
+    'log-gap': 'A row of the stored log could not be read as a commit bundle, so it keeps its index but contributes no state, and any fold that crosses it is missing whatever that row wrote.',
+    // ── untracked reads a stage also consumed — `CausalNode.incompleteSources` ─
+    'incomplete-sources': 'The stage also consumed read paths that bypass read tracking (args, env or an unshadowed silent read), so a slice through it may be incomplete: those reads produce no read-to-write edge to follow.',
+    // ── values scrubbed at write time — `FoldedState.redacted` / `redactedPaths`, a value basis ─
+    redacted: "Values at the paths listed in redactedPaths (a fold's, or a commit's in the range a key's value rests on) were scrubbed when they were written (by a redaction policy, or a write marked redacted), so where the answer holds the log's placeholder 'REDACTED', or lost a key under a container the placeholder replaced, it stands in for a value the log never recorded.",
+    // ── how one key's value was read off the log — `ValueBasis` (commitValueAtWithBasis) ─
+    deleted: "The key's last write in the range asked about left it absent (a delete of the key or of a container around it, or a set of a container that no longer holds it), so the answer is undefined because the record says the key was gone at that point, not because nothing was recorded.",
+    'from-initial-state': "No set or delete of the key, or of a container around it, is in the range asked about, so the answer rests on the value the key had before the run: folded from the initialState passed in when there was one, and otherwise only what the log's merges, appends and nested writes added to it (or nothing), which is partial for a key seeded before the run.",
+});

package/dist/lib/memory/keyPaths.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * keyPaths.ts — which rows of a commit log touch a state key. ONE answer (F3, 9.33.0).
+ *
+ * WHY THIS FILE EXISTS. A key query (`commitValueAt`, `findLastWriter`, `causalChain`, the slice
+ * layer) asks "which rows wrote `key`?". Each reader used to answer with its own `row.path === key`,
+ * so a row written INSIDE the key — `cfg␟b`, which every subflow seed of an object, every
+ * outputMapper merge-back and every fork child's namespace produces — was invisible to all of
+ * them, while the fold (`stateAt`, the live commit) applied it. The fold said `{a:1,b:2}`; the key
+ * queries said "never written". Every reader now asks here.
+ *
+ * THE PATH HALF (this file, L0 — it imports only the path codec and types):
+ *   - {@link relation} — how a row's path sits against a key's path. A segment prefix on the
+ *     DELIM-joined path, the way RFC 6901 prefixes a JSON Pointer: `cfg` is a prefix of `cfg␟a`,
+ *     never of `cfgX`. A row is `'exact'` (on the key), `'inside'` (below it — it wrote part of the
+ *     key's value) or `'around'` (above it — it wrote a container that holds the key).
+ *   - {@link buildWriterIndex} / {@link writerCandidates} — one pass over a log, then the rows that
+ *     can have written a key, found through its top-level key instead of a scan.
+ *
+ * THE RULES (defined here; the fold is L1 and the log readers L3, so `commitLogUtils.ts` applies
+ * them — `writersOf`, `findLastWriter`, `commitValueAt`):
+ *   - THE WRITER RULE — commit `c` WRITES key `K` iff `c` has a row `'exact'` or `'inside'` `K`,
+ *     or a row `'around'` `K` across which the value at `K` differs (compared over the whole commit,
+ *     not row by row: a value that changes and changes back inside one commit was not written).
+ *     A top-level key has no `'around'` rows, so for it the rule is the path check alone.
+ *     Why not every `'around'` row: `$update('cfg', { list: [3] })` is a `merge` row on `cfg`, but
+ *     it never reaches `cfg␟a` — counting it named the wrong writer of `cfg␟a`.
+ *   - THE VALUE RULE — the value of `K` at commit `i` is the fold of EVERY row under `K`'s top-level
+ *     key up to `i`, anchored at that key's last `set`/`delete`, read at `K`: the fold `stateAt`
+ *     does, restricted to one top-level key. Top-level keys never interact under the step, so the
+ *     restriction is exact. Folding only the rows that touch `K` is NOT: an array union
+ *     (`deepSmartMerge`) dedups the whole array, so a sibling element written beside `a␟1` changes
+ *     where a later merge on `a` leaves `a[1]`.
+ *
+ * @example
+ * ```typescript
+ * relation('cfg\u001Fb', 'cfg'); // 'inside' — the row wrote part of cfg
+ * relation('cfg', 'cfg\u001Fa'); // 'around' — the row wrote the container cfg.a lives in
+ * relation('cfgX', 'cfg');       // undefined — a different key, not a prefix match
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writesOnlyInside = exports.ascendingUnion = exports.writerCandidates = exports.between = exports.lastBefore = exports.lowerBound = exports.subtreePositions = exports.ancestorNodes = exports.nodeAt = exports.pathsWritten = exports.buildWriterIndex = exports.rootOf = exports.relation = exports.queryWork = void 0;
+const paths_js_1 = require("./paths.js");
+/**
+ * The WORK every key query has done — rows indexed and scanned, fold steps, around-verdicts, trie and
+ * ancestor steps, binary searches, a causal walk's own loops — summed across calls. A deterministic cost
+ * measure: `test/lib/memory/boundary/key-query-scaling.test.ts` asserts a causal walk's work grows linearly
+ * in the log by COUNTING it (a wall-clock ratio failed on a busy machine). Never read by the library; one
+ * integer add per unit of work it already does. Here, at L0, so every layer that does that work can count it.
+ */
+exports.queryWork = { units: 0 };
+const DELIM_CODE = paths_js_1.DELIM.charCodeAt(0);
+/**
+ * How the row path `rowPath` sits against the key `key` — both DELIM-joined `TraceEntry.path`
+ * strings (a top-level key is a one-segment path). `'exact'` when they are equal, `'inside'` when
+ * the row is below the key, `'around'` when the row is above it, `undefined` when neither is a
+ * segment prefix of the other.
+ */
+function relation(rowPath, key) {
+    if (rowPath === key)
+        return 'exact';
+    if (rowPath.length > key.length) {
+        return rowPath.charCodeAt(key.length) === DELIM_CODE && rowPath.startsWith(key) ? 'inside' : undefined;
+    }
+    return key.charCodeAt(rowPath.length) === DELIM_CODE && key.startsWith(rowPath) ? 'around' : undefined;
+}
+exports.relation = relation;
+/** The top-level key a DELIM-joined path belongs to — its first segment. */
+function rootOf(path) {
+    const cut = path.indexOf(paths_js_1.DELIM);
+    return cut === -1 ? path : path.slice(0, cut);
+}
+exports.rootOf = rootOf;
+function nodeOf(path) {
+    return { path, positions: [], totals: [], writes: [], children: new Map() };
+}
+/** Append `i` to an ascending list unless it is already its last element. */
+function pushOnce(list, i) {
+    if (list[list.length - 1] !== i)
+        list.push(i);
+}
+/**
+ * One pass over `commitLog`: the path trie of every written path. Build it ONCE when a reader asks about
+ * many keys (a causal walk, a forward slice) — or let `commitLogUtils · logModel` memoise it for a frozen log.
+ */
+function buildWriterIndex(commitLog) {
+    const roots = new Map();
+    for (let i = 0; i < commitLog.length; i++) {
+        const trace = commitLog[i].trace;
+        for (let row = 0; row < trace.length; row++) {
+            const { path, verb } = trace[row];
+            const segs = path.split(paths_js_1.DELIM);
+            let node = roots.get(segs[0]);
+            if (node === undefined) {
+                node = nodeOf(segs[0]);
+                roots.set(segs[0], node);
+            }
+            for (let s = 1; s < segs.length; s++) {
+                let child = node.children.get(segs[s]);
+                if (child === undefined) {
+                    child = nodeOf(node.path + paths_js_1.DELIM + segs[s]);
+                    node.children.set(segs[s], child);
+                }
+                node = child;
+            }
+            pushOnce(node.positions, i);
+            if (verb === 'set' || verb === 'delete')
+                pushOnce(node.totals, i);
+            if (verb !== 'delete')
+                pushOnce(node.writes, i);
+        }
+    }
+    return { roots };
+}
+exports.buildWriterIndex = buildWriterIndex;
+/** Every path a row was written on, in trie order. */
+function pathsWritten(index) {
+    const out = [];
+    const stack = [...index.roots.values()];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (node.positions.length > 0)
+            out.push(node.path);
+        for (const child of node.children.values())
+            stack.push(child);
+    }
+    return out;
+}
+exports.pathsWritten = pathsWritten;
+/** The node for `key`, or undefined when no row was written on it or below it. */
+function nodeAt(index, key) {
+    const segs = key.split(paths_js_1.DELIM);
+    exports.queryWork.units += segs.length;
+    let node = index.roots.get(segs[0]);
+    for (let s = 1; node !== undefined && s < segs.length; s++)
+        node = node.children.get(segs[s]);
+    return node;
+}
+exports.nodeAt = nodeAt;
+/** The nodes of `key`'s PROPER ancestors that exist in the index, top-level key first. */
+function ancestorNodes(index, key) {
+    const segs = key.split(paths_js_1.DELIM);
+    const out = [];
+    exports.queryWork.units += segs.length;
+    let node = index.roots.get(segs[0]);
+    for (let s = 1; node !== undefined && s < segs.length; s++) {
+        out.push(node);
+        node = node.children.get(segs[s]);
+    }
+    return out;
+}
+exports.ancestorNodes = ancestorNodes;
+/** Every commit with a row on `node`'s path or below it — ascending, memoised on the node. */
+function subtreePositions(node) {
+    exports.queryWork.units += 1;
+    if (node.subtree === undefined) {
+        if (node.children.size === 0)
+            node.subtree = node.positions;
+        else {
+            const lists = [node.positions];
+            for (const child of node.children.values())
+                lists.push(subtreePositions(child));
+            node.subtree = ascendingUnion(lists);
+            exports.queryWork.units += node.subtree.length;
+        }
+    }
+    return node.subtree;
+}
+exports.subtreePositions = subtreePositions;
+/** The first index in an ascending list holding a value >= `value`. */
+function lowerBound(sorted, value) {
+    exports.queryWork.units += 1;
+    let lo = 0;
+    let hi = sorted.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (sorted[mid] < value)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+exports.lowerBound = lowerBound;
+/** The last value in an ascending list that is < `before`, or -1. */
+function lastBefore(sorted, before) {
+    const at = lowerBound(sorted, before);
+    return at > 0 ? sorted[at - 1] : -1;
+}
+exports.lastBefore = lastBefore;
+/** The values of an ascending list in the OPEN range (`after`, `before`). */
+function between(sorted, after, before) {
+    const out = sorted.slice(lowerBound(sorted, after + 1), lowerBound(sorted, before));
+    exports.queryWork.units += out.length;
+    return out;
+}
+exports.between = between;
+/** The path half of the writer rule over an index: every commit that can have written `key`. `O(depth + matches)`. */
+function writerCandidates(index, key) {
+    const node = nodeAt(index, key);
+    const written = node === undefined ? [] : subtreePositions(node);
+    const ancestors = ancestorNodes(index, key);
+    if (ancestors.length === 0)
+        return { atOrInside: written, aroundOnly: [] };
+    const already = new Set(written);
+    return {
+        atOrInside: written,
+        aroundOnly: ascendingUnion(ancestors.map((a) => a.positions)).filter((i) => !already.has(i)),
+    };
+}
+exports.writerCandidates = writerCandidates;
+/** The ascending, de-duplicated union of ascending position lists. */
+function ascendingUnion(lists) {
+    if (lists.length === 0)
+        return [];
+    if (lists.length === 1)
+        return [...lists[0]];
+    const all = new Set();
+    for (const list of lists)
+        for (const i of list)
+            all.add(i);
+    return [...all].sort((a, b) => a - b);
+}
+exports.ascendingUnion = ascendingUnion;
+/**
+ * Did this commit reach `key` ONLY through rows inside it — at least one row `'inside'` the key, and no
+ * row on it or around it? Such a write changed part of the key's value, not the whole: the one test
+ * behind every `'nested-rows'` code (a slice note, a causal edge's `basis`, `findLastWriterWithBasis`).
+ */
+function writesOnlyInside(bundle, key) {
+    let inside = false;
+    for (const t of bundle.trace) {
+        const r = relation(t.path, key);
+        if (r === 'exact' || r === 'around')
+            return false;
+        if (r === 'inside')
+            inside = true;
+    }
+    return inside;
+}
+exports.writesOnlyInside = writesOnlyInside;