footprintjs 9.48.2 → 10.0.0

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

@@ -1,217 +0,0 @@
-/**
- * Typed utilities for querying the commit log.
- *
- * 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, CommitPhase } from './types.js';
-import { type Touch } from './verbs.js';
-/**
- * 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 `key` before `beforeIdx` (exclusive; default: the whole log) —
- * the anchor of every backward question ("who made it this?").
- *
- * 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 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).
- *
- * 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.
- *
- * @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 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. The map's insertion order is the order
- * the stages first committed — execution order.
- *
- * "First" is the contract, and it is load-bearing. A stage normally commits
- * exactly one bundle, but some executions commit more under one
- * `runtimeStageId`: a subflow MOUNT (the merge-back, then the exit), a fork
- * child (its own commit, then the fan-out's). Since 9.39.0 the WRITER names
- * each continuation on the bundle (`CommitBundle.phase`: `'exit'` /
- * `'repeat'`), and every continuation is written after the execution's own
- * bundle — so "where does this stage start?" is the first bundle, and the
- * grouping every reader's axis uses (`commitStops`) is this index. No reader
- * tells a continuation from the log's shape.
- *
- * Build this ONCE when resolving many ids; use {@link commitIndexOf} for a
- * single lookup.
- *
- * @param commitLog Ordered commit bundles — `getSnapshot().commitLog`.
- * @returns A fresh Map, owned by the caller.
- */
-export declare function buildCommitIndex(commitLog: readonly CommitBundle[]): Map<string, number>;
-/**
- * Whether a log RECORDS phases — any bundle carries `phase` — i.e. it was
- * written by 9.39.0 or later and holds at least one continuation. A log that
- * does not either has no continuation at all, or predates the field (see
- * {@link inferLegacyPhases}).
- */
-export declare function recordsPhases(commitLog: readonly CommitBundle[]): boolean;
-/**
- * THE LEGACY READER — the one place a continuation's phase is INFERRED, for a
- * log written before 9.39.0 (which carries no `phase` anywhere). Returns the
- * phase each bundle would have been stamped with, by the rule every reader
- * applied through 9.38.0: a stage's bundle that IMMEDIATELY follows its first
- * bundle is a mount's exit; any later bundle of the same `runtimeStageId` is
- * a fork child's repeat; a first bundle is the stage's own (`undefined`).
- *
- * The rule is a guess, and the guess has a known miss — a single-child fork
- * whose child is a leaf looks exactly like a mount — which is why a reader
- * asks it only when the log records no phase AND it has no execution tree to
- * ask instead (`commitStops`). A log that records phases is never inferred.
- */
-export declare function inferLegacyPhases(commitLog: readonly CommitBundle[]): (CommitPhase | undefined)[];
-/**
- * The ARRAY INDEX of the first commit a given `runtimeStageId` produced, or
- * `-1` when that stage is not in this log (`indexOf` semantics — the name's
- * promise).
- *
- * This is the address translation every reader needs and nobody exported: a
- * `runtimeStageId` is the id an event carries, a commit index is what
- * `commitValueAt` / `stateAt` / `CommitRangeIndex` speak. O(n) — for many
- * lookups build the map once with {@link buildCommitIndex}.
- *
- * A stage that ran inside a SUBFLOW is not in the run-level log (subflows
- * commit to their own isolated log); look it up in that subflow's own
- * `history` instead — see `getSubtreeSnapshot`.
- *
- * @example
- * ```typescript
- * const idx = commitIndexOf(snapshot.commitLog, 'score-risk#7');
- * const before = idx > 0 ? commitValueAt(snapshot.commitLog, idx - 1, 'risk') : undefined;
- * ```
- */
-export declare function commitIndexOf(commitLog: readonly CommitBundle[], runtimeStageId: string): number;