footprintjs 9.32.0 → 9.34.0

package/dist/esm/lib/memory/commitLogUtils.d.ts

@@ -4,62 +4,153 @@
  * The commitLog is an ordered array of CommitBundle — one per stage commit.
  * These helpers provide type-safe queries without (b: any) casts.
  */
+import type { RegisteredCode } from './honesty.js';
 import type { CommitBundle } from './types.js';
 import { type Touch } from './verbs.js';
-/** Find the first commit by stageId, optionally filtering by a written key. */
+/**
+ * Find the first commit by `stageId`, optionally the first one that WROTE `key` — under the writer
+ * rule: a row on the key, inside it, or around it that changed it (see {@link writersOf}).
+ */
 export declare function findCommit(commitLog: CommitBundle[], stageId: string, key?: string): CommitBundle | undefined;
 /** Find all commits by stageId. */
 export declare function findCommits(commitLog: CommitBundle[], stageId: string): CommitBundle[];
-/** Find the last commit that wrote a specific key (for backtracking). */
-export declare function findLastWriter(commitLog: CommitBundle[], key: string, beforeIdx?: number): CommitBundle | undefined;
 /**
- * Every row on `key` in `commitLog[0..end]`, in commit order — the touches a
- * per-path fold ({@link foldKey}) runs over. `key` is matched against
- * `TraceEntry.path` exactly (DELIM-joined for nested paths). A row whose verb
- * is not one of the four is refused with {@link UnknownVerbError} naming the
- * row — whether or not the fold would have reached it: the answer must not
- * depend on where an optimisation starts.
+ * Find the last commit that WROTE `key` before `beforeIdx` (exclusive; default: the whole log) —
+ * the anchor of every backward question ("who made it this?").
  *
- * Internal: `commitValueAt` and `arrayProvenance` are its two readers.
+ * The writer rule (`keyPaths.ts`): a commit writes `key` when one of its rows is ON the key,
+ * INSIDE it (a subflow's input seed writes `cfg␟a`; an outputMapper merge-back writes `cfg␟b`;
+ * either is a write of `cfg`), or AROUND it with the value at the key different across the commit
+ * (a `set` of `cfg` writes `cfg␟a`; a `merge` of `cfg` that never reaches `a` does not). A write
+ * found through a row INSIDE the key wrote only PART of its value — the slice readers say so with
+ * the `'nested-rows'` note.
+ *
+ * @param key  A DELIM-joined path (`normalisePath`); a top-level key is a one-segment path.
+ */
+export declare function findLastWriter(commitLog: CommitBundle[], key: string, beforeIdx?: number): CommitBundle | undefined;
+/** What {@link writersOf} is asked. */
+export interface WritersOptions {
+    /** The last commit ARRAY index considered, inclusive. Default: the whole log. */
+    readonly end?: number;
+}
+/**
+ * The ARRAY positions (ascending) of every commit in `commitLog[0..end]` that WROTE `key` — the
+ * writer rule of `keyPaths.ts`, the one definition every key query shares (`logModel.ts` applies it).
+ */
+export declare function writersOf(commitLog: readonly CommitBundle[], key: string, options?: WritersOptions): number[];
+/**
+ * Every row under `key`'s TOP-LEVEL key in `commitLog[0..end]`, in commit order — the rows the value
+ * rule folds ({@link foldKey}), each with its {@link Touch.relation} to `key` (absent for a sibling
+ * under the same top-level key: applied, not observed) — found through the log's index. A row whose
+ * verb is not one of the four is refused with {@link UnknownVerbError} naming the row — whether or
+ * not the fold would have reached it: the answer must not depend on where an optimisation starts.
  */
-export declare function keyTouches(commitLog: readonly CommitBundle[], key: string, end: number): Touch[];
+export declare function rowsUnderRoot(commitLog: readonly CommitBundle[], key: string, end: number): Touch[];
 /**
  * Reconstruct the FULL value of `key` as of commit array index `idx`
  * (inclusive) — the migration helper for the "read `bundle.overwrite[key]`
  * as the full value written" pattern (#13c-B).
  *
- * Under `commitValues: 'delta'`, an `append` bundle's `overwrite[key]` holds
- * only the TAIL of the array; this helper folds the verbs back together:
- * it scans `commitLog[0..idx]` for trace entries on `key`, anchors at the
- * latest full-value write (`set` — or `delete`, which resets to absent), and
- * folds forward with the SAME step and clone discipline the replay uses
- * (`verbs.ts` · `foldKey`) — the per-key slice of `applySmartMerge`'s replay,
- * O(key's commit span) instead of a full `materialise()`. Two `merge` rows of
- * one bundle see one copy of the bundle's delta, as the replay's do (a clone per
- * row, as this helper once took, made an array union — which deduplicates by
- * reference — duplicate the elements the first row had placed).
+ * The value rule (`keyPaths.ts`, 9.33.0): every row under the key's TOP-LEVEL
+ * key in `commitLog[0..idx]` is folded, anchored at that key's last `set` /
+ * `delete`, with the SAME step and clone discipline the replay uses
+ * (`verbs.ts` · `foldKey`), and the result is read at `key`. So the answer is
+ * the value `stateAt` gives at that path when it folds the log alone — rows
+ * INSIDE the key (a subflow seed, an outputMapper merge-back) and AROUND it (a
+ * `set` of the container) count; before 9.33.0 only rows on the exact path did,
+ * and a seeded `cfg` read as `undefined`. Under `commitValues: 'delta'`, an
+ * `append` row's `overwrite[key]` holds only the TAIL; the fold puts the array
+ * back together. Two `merge` rows of one bundle see one copy of the bundle's
+ * delta, as the replay's do.
  *
- * Works on full-mode logs too (every `set` is its own anchor — equivalent to
- * `findLastWriter(...).overwrite[key]`).
- *
- * @param key  Matched against `TraceEntry.path` exactly (same contract as
- *   `findLastWriter`) — DELIM-joined for nested paths.
+ * @param key  A DELIM-joined path (`normalisePath`); a top-level key is a
+ *   one-segment path.
  * @param idx  CommitBundle ARRAY index (the `bundle.idx` position),
  *   inclusive. NOT the executionIndex from a runtimeStageId.
- * @returns The reconstructed value (a detached clone), or `undefined` when
- *   the key was never written in `commitLog[0..idx]` or its last write was a
- *   delete. Caveat: values derived purely from the run's INITIAL state (no
- *   `set` anchor in the log — e.g. merges onto a seeded key) fold from
- *   absent; the commit log alone cannot see the pre-run base (the same blind
- *   spot `findLastWriter` has). Since 9.17.0 the base TRAVELS with the log, so
- *   `stateAt(snapshot, idx).state[key]` (footprintjs/trace) answers this case
- *   correctly — it folds from `RuntimeSnapshot.initialState`, which this
- *   function never receives.
- * @throws {@link UnknownVerbError} when a row on `key` carries a verb other
- *   than `set | merge | append | delete` — a foreign or corrupted log is
- *   refused, not folded as a `merge`. Engine-written logs never carry one.
+ * @returns The reconstructed value (a detached clone), or `undefined` when no
+ *   row in `commitLog[0..idx]` is on, inside or around the key, or the fold
+ *   leaves it absent (its last write was a delete). Caveat: a key that held a
+ *   value in the run's INITIAL state folds from absent here — the log alone
+ *   cannot see the pre-run base, so merges and nested writes onto a seeded key
+ *   give only what they added. Since 9.17.0 the base TRAVELS with the log:
+ *   `stateAt(snapshot, idx)` (footprintjs/trace) folds from
+ *   `RuntimeSnapshot.initialState`, which this function never receives.
+ * @throws {@link UnknownVerbError} when a row under the key's top-level key
+ *   carries a verb other than `set | merge | append | delete` — a foreign or
+ *   corrupted log is refused, not folded as a `merge`. Engine-written logs
+ *   never carry one.
+ * @see commitValueAtWithBasis — the same answer, with the codes that say WHY it is
+ *   `undefined` or partial (and the `initialState` base this function never receives).
  */
 export declare function commitValueAt(commitLog: CommitBundle[], idx: number, key: string): unknown;
+/**
+ * Why {@link commitValueAtWithBasis} answered what it did. Each code is registered, with the one
+ * sentence that says what it means, in `memory/honesty.ts · HONESTY_CODES` (served on
+ * `footprintjs/trace`); the union declares its members through `RegisteredCode`.
+ *
+ * - `'never-written'`      — no commit in range wrote the key (the writer rule — the answer
+ *                            `findLastWriter` and the slice layer give), unless the run removed a value
+ *                            the passed `initialState` held (then `'deleted'`), or a redaction at or
+ *                            around the key hid the write (then `'redacted'` alone).
+ * - `'deleted'`            — the answer is `undefined` and the key WAS written: its last write left it
+ *                            absent.
+ * - `'nested-rows'`        — the value rests on rows INSIDE the key (a subflow seed, an outputMapper
+ *                            merge-back, a fork child's namespace) with no `set`/`delete` of the key or
+ *                            of a container around it in range.
+ * - `'from-initial-state'` — no `set`/`delete` of the key or around it in range, so the value rests on
+ *                            the pre-run base: folded from `options.initialState` when it holds the
+ *                            key's top-level key, partial when no `initialState` was passed.
+ * - `'redacted'`           — a path at, inside or around the key is in the `redactedPaths` of a commit
+ *                            the value rests on (from its last `set`/`delete` on, or the whole range).
+ */
+export type ValueBasis = RegisteredCode<'never-written' | 'deleted' | 'nested-rows' | 'from-initial-state' | 'redacted'>;
+/** What {@link commitValueAtWithBasis} is asked besides the log, the index and the key. */
+export interface ValueBasisOptions {
+    /**
+     * The state before the run — `RuntimeSnapshot.initialState` (or a subflow's
+     * `treeContext.initialState`). When given, a key with no `set`/`delete` in range folds from it, as
+     * `stateAt` does; when absent, such an answer is the log-only fold and carries `'from-initial-state'`.
+     */
+    readonly initialState?: Readonly<Record<string, unknown>>;
+}
+/** A key's value read off the log, and the codes that say what it rests on — absent codes = an exact answer. */
+export interface ValueWithBasis {
+    readonly value: unknown;
+    /** In the order of {@link ValueBasis}'s list; EMPTY when a `set`/`delete` of the key or around it anchors the value and no redaction touched it. */
+    readonly basis: ValueBasis[];
+}
+/**
+ * {@link commitValueAt}, with the codes that say what the answer rests on. Without `options.initialState`
+ * the value IS `commitValueAt(commitLog, idx, key)` (pinned by a property); with it, a key that has no
+ * `set`/`delete` of itself or of a container around it in range folds from that base — the value
+ * `stateAt(snapshot, idx)` gives at the key. Refuses an unknown verb exactly as `commitValueAt` does.
+ *
+ * @example
+ * ```typescript
+ * const { value, basis } = commitValueAtWithBasis(snap.commitLog, i, 'cfg', { initialState: snap.initialState });
+ * for (const code of basis) console.log(code, HONESTY_CODES[code]);
+ * ```
+ */
+export declare function commitValueAtWithBasis(commitLog: CommitBundle[], idx: number, key: string, options?: ValueBasisOptions): ValueWithBasis;
+/**
+ * Why {@link findLastWriterWithBasis} answered what it did — registered in `HONESTY_CODES`:
+ * `'never-written'` (no writer before the bound), `'nested-rows'` (the writer reached the key only
+ * through rows inside it, so it wrote part of the value), `'redacted'` (no writer the log can see, because a
+ * redaction at or around the key hid the write — the rule `commitValueAtWithBasis` follows).
+ */
+export type WriterBasis = RegisteredCode<'never-written' | 'nested-rows' | 'redacted'>;
+/** The last writer of a key, and the codes that say what kind of write it was — absent codes = a write on or around the key. */
+export interface WriterWithBasis {
+    /** Absent exactly when `basis` holds `'never-written'` or `'redacted'`. */
+    readonly writer?: CommitBundle;
+    readonly basis: WriterBasis[];
+}
+/**
+ * {@link findLastWriter}, with the code that says why: `writer` is `findLastWriter(commitLog, key, beforeIdx)`;
+ * `basis` is `['never-written']` when there is none and `['nested-rows']` when that commit wrote the key
+ * only through rows inside it.
+ */
+export declare function findLastWriterWithBasis(commitLog: CommitBundle[], key: string, beforeIdx?: number): WriterWithBasis;
 /**
  * Position index over a commit log: `runtimeStageId` → the ARRAY INDEX of the
  * FIRST bundle that stage committed.