@vibe-commit/capture 0.8.0 → 0.10.0

package/dist/codex_folders.d.ts

@@ -0,0 +1,340 @@
+/**
+ * Codex record isolation (any-folder capture, part (b)): the EFFECTIVE FOLDER of a Codex rollout record.
+ *
+ * A Codex record names a folder on very few types (`session_meta` and `turn_context` carry `payload.cwd`, a finished command item carries `item.cwd` as a
+ * `file://` URL, `thread_settings_applied` carries `thread_settings.cwd`). Everything else (the user's prompt, the agent's prose, a command's output) runs
+ * "somewhere" without saying where, so a copy for repo A of a session that also worked in repo B would carry B's turns. Every record therefore gets an
+ * effective folder, told by these rules:
+ *
+ *   1. a record that carries its OWN folder (`payload.cwd`, `payload.item.cwd`, `payload.thread_settings.cwd`) takes it; an unreadable one is UNKNOWN. Only
+ *      `session_meta` and `turn_context` CHANGE the turn folder.
+ *   2. a CALL takes the folders its tool ran in. The rule is per tool name and DEFAULT DENY: `exec_command` / `shell` / `local_shell_call` (workdir, else the
+ *      turn folder, plus the files of a patch they carry), `apply_patch` (the files it changes), `exec` (the whole-literal workdirs of the program, the turn
+ *      folder, and the folders of the sessions it polls), `write_stdin` (the folders of the session it polls), `wait` (the folders of the cell it waits on),
+ *      `view_image` (its path), `update_plan` (the turn folder). ANY OTHER tool name, in either call form, is UNKNOWN.
+ *   3. an OUTPUT takes the folders of its call, matched by `call_id`; an output whose call is not known is UNKNOWN. A process an `exec_command` started and a
+ *      cell an `exec` program started are named in the output (`Process running with session ID <n>`, `Script running with cell ID <id>`, a `"session_id"`
+ *      field): the SESSION and CELL maps learned from those lines are how a later `write_stdin` or `wait` is placed.
+ *   4. otherwise the TURN FOLDER in force, the latest `session_meta` / `turn_context` cwd at or before the record in the SAME stream.
+ *
+ * The common failure the rules are built against: a record whose folder cannot actually be read must come out UNKNOWN, never as a KNOWN but wrong folder
+ * (usually the turn folder), because UNKNOWN is withheld from a multi-repo copy and a wrong known folder is kept.
+ *
+ * Pure: no filesystem, no clock. The caller supplies the turn folder, the call table and the two maps, so the resolver's scan (which writes the checkpoint)
+ * and the redactor (which reads it) share ONE definition of "where a record ran".
+ */
+/** A folder given as a `file://` URL (a finished command item's `cwd`) or as a path, as a plain absolute path; null when it is neither. */
+export declare function folderFromValue(value: unknown): string | null;
+/** EVERY readable folder a record carries on its own (C49 (7): discovery reads folders by this one definition, `file://` decoded). */
+export declare function ownFoldersOf(record: Record<string, unknown>): string[];
+/** Folders as a set where an EMPTY list means "cannot be told" and absorbs the rest. */
+export declare function unionDirs(a: readonly string[], b: readonly string[]): string[];
+/**
+ * C48 (10): only a MEASURED record kind takes the turn folder. Everything else is UNKNOWN (kept in a single-repo copy, withheld in a multi-repo one), so a
+ * kind Codex adds later, a `compacted` summary of earlier turns (which can describe another repo's work), or an old-format item with no `payload` is never
+ * placed by a guess. The kinds C40 (2) withholds from every copy (`world_state`, `additional_tools`, `entered_review_mode`, a user or developer message)
+ * need no placing: nothing of theirs is sent.
+ */
+export declare function takesTurnFolder(record: Record<string, unknown>): boolean;
+/** A "file" that lies inside no copy's tree: a record whose named files could not all be judged names it, so it is withheld from every copy. */
+export declare const UNJUDGED_FILE = "\0unjudged";
+/** The folders of a process or script a call started, and which of them are files the call named (C49 (4): the call's FULL placement). */
+export interface Place {
+    readonly paths: readonly string[];
+    readonly files: readonly string[];
+    /** C54 (3): the id is UNKNOWN (`paths` is `[]`); `files` and `evidence` are what the calls that announced it still named. */
+    readonly unknown?: true;
+    readonly evidence?: readonly string[];
+}
+/** What a call needs to be placed. */
+export interface CallContext {
+    /** The turn folder in force at the call. */
+    readonly turn: string | null;
+    /** The placement of session `id` (a process an `exec_command` started); undefined when it is not known. */
+    session(id: string): Place | undefined;
+    /** The placement of cell `id` (a script an `exec` program started); undefined when it is not known. */
+    cell(id: string): Place | undefined;
+    /** C56 (13): the placement of EVERY session entry known at the call that carries something (folders, files); for a program that polls a session it cannot name. */
+    allSessions?(): readonly Place[];
+}
+/**
+ * What a CALL touches. `paths`: the places it ran (workdirs, the turn folder) AND the files it names, for evidence and for the work-tree check. `files`: the
+ * subset of `paths` that are FILES (a patch's headers, `view_image`'s path): judged like a Claude path, by the copy's roots and holes, for the call AND its
+ * output (C48 (11)). `inputFiles`: places that only the call's own INPUT is judged by (an `exec` program's whole-literal workdirs: the program is source
+ * text, so it is withheld for parity, while its output is the stated residual).
+ */
+export interface Placed {
+    readonly paths: string[];
+    readonly files: string[];
+    readonly inputFiles: string[];
+}
+/**
+ * The places a CALL ran in and the files it names, or null when they cannot be told (DEFAULT DENY: a tool this module has no rule for, a malformed argument
+ * document, a `workdir` that is not a string, a relative path with no turn folder, an id that names no known session or cell).
+ */
+export declare function placeCall(record: Record<string, unknown>, ctx: CallContext): Placed | null;
+/**
+ * What a call whose placement CANNOT be fully told still names that can be read (C53): `evidence` (every readable folder and file, kept as discovery
+ * evidence so a work tree it lies in is found), `files` (the files it names, judged per copy for the call AND its output) and `inputFiles` (an `exec`
+ * program's whole-literal workdirs, judged for its own input). The verdict stays UNKNOWN; this is only what it must not throw away.
+ */
+export interface Readable {
+    readonly evidence: string[];
+    readonly files: string[];
+    readonly inputFiles: string[];
+    /**
+     * C54 (1): the call named more places than are kept (`files` then carries UNJUDGED_FILE), or (C56 (10)) named a folder the client could not read (a workdir
+     * that is not a string, a program workdir that is not a whole literal): the evidence is incomplete, so the session is multi. The verdict stays UNKNOWN.
+     */
+    readonly overflow?: true;
+}
+export declare function readableOf(record: Record<string, unknown>, ctx: CallContext): Readable;
+/** The places a call ran in (see `placeCall`), or null when they cannot be told. */
+export declare function callFolders(record: Record<string, unknown>, ctx: CallContext): string[] | null;
+/**
+ * The text of an output record. `header`: the part that can teach an id (before the first `\nOutput:\n` of the FIRST block); `all`: every block's text. A
+ * `custom_tool_call_output` and a `wait` output are real arrays of `{type:"input_text", text}` blocks (C49 (1)); a function output is a string. An array
+ * is read from its TEXT blocks only (C56 (6): an image block is skipped), the header from the first of them. `undefined`: no readable text.
+ */
+export interface OutputText {
+    readonly header: string;
+    readonly all: string;
+}
+export declare function outputTextOf(record: Record<string, unknown>): OutputText | undefined;
+/**
+ * What an output teaches about the processes and scripts its call started (C48 (1)): from an `exec_command` / `write_stdin` output, the session id in the
+ * header line `Process running with session ID <n>` (never from the body, where a printed log could remap an id); from an `exec` program's output, a
+ * `"session_id": <n>` field (either JSON escaping, anywhere in the text) and the header line `Script running with cell ID <id>`.
+ */
+export declare function learnFromOutput(tool: string, text: OutputText): {
+    sessions: string[];
+    cells: string[];
+};
+/** The most entries a session or cell map keeps; the oldest is evicted, and an evicted id is UNKNOWN. */
+export declare const MAX_ID_MAP = 4096;
+/** C75 (9) / C76: the bytes of freeable path text ONE id map (the session map, or the cell map) may store per stream (`dirs`, `files` and `evidence` of live entries and tombstones). */
+export declare const ID_MAP_BUDGET_BYTES: number;
+/** The most distinct folders one id keeps (C49 (10)); past it the id is UNKNOWN for good. */
+export declare const MAX_ID_FOLDERS = 64;
+/** One folder an id was learned to run in, and the byte offset of the output that announced it. */
+export interface Learned {
+    readonly dir: string;
+    readonly at: number;
+    /** The folder is a FILE the call named (a patch's header): judged per copy like a Claude path. */
+    readonly file?: true;
+}
+/** Everything a session or cell id is known to run in, each with where it was learned (C49 (2): a lookup uses only what came BEFORE its position). */
+export interface IdEntry {
+    readonly dirs: readonly Learned[];
+    /** From this offset the id is UNKNOWN: a call whose folders could not be told announced it, or it grew past `MAX_ID_FOLDERS`. */
+    readonly unknownAt?: number;
+    /** C50 (5): the entry was EVICTED from the bounded map; the id is UNKNOWN for good (a re-announcement does not bring it back). */
+    readonly tomb?: true;
+    /** C54 (3): the files (and folders, as evidence) that the UNKNOWN calls which announced this id still named: an unknown id lookup carries them. */
+    readonly files?: readonly string[];
+    readonly evidence?: readonly string[];
+}
+/** The most tombstones (evicted ids) a map keeps; past that the whole map is UNKNOWN from that offset (sticky). */
+export declare const MAX_ID_TOMBS = 4096;
+/** The map key that holds the "whole map is unknown from `unknownAt`" mark. */
+export declare const ALL_UNKNOWN = "\0all-unknown";
+/**
+ * A session or cell map with the checkpoint's bounds: at most `MAX_ID_MAP` live entries; the oldest live entry that is evicted becomes a TOMBSTONE (UNKNOWN
+ * for good), at most `MAX_ID_TOMBS` of those; past that the whole map is UNKNOWN from that offset. It is a `Map`, so it persists as an array of entries.
+ */
+export declare class IdMap extends Map<string, IdEntry> {
+    live: number;
+    tombs: number;
+    /**
+     * C75 (9) / C76: the FREEABLE text the entries store (the path text of `dirs`, `files` and `evidence` with their quoting), live entries and tombstones alike. The byte budget compares only
+     * this: the fixed cost of an entry (its key and field names) is bounded by the count caps (`MAX_ID_MAP` + `MAX_ID_TOMBS`) and is its own term of the record's worst case.
+     */
+    text: number;
+    /** C75 (9): the byte budget collapsed an entry since the flag was last taken: evidence was LOST (the session counts as multi from that offset). */
+    collapsed: boolean;
+    private readonly liveOrder;
+    private readonly tombOrder;
+    private readonly liveTextOrder;
+    private readonly tombTextOrder;
+    constructor(entries?: Iterable<readonly [string, IdEntry]>);
+    /** Remove an entry, keeping the text count and the order indexes (the live and tombstone counts are kept by the callers). */
+    delete(id: string): boolean;
+    /** Set an entry, keeping the live, tombstone and text counts and the order indexes. */
+    put(id: string, entry: IdEntry): void;
+    /** Read and clear the "the byte budget collapsed an entry" flag. */
+    takeCollapsed(): boolean;
+    /**
+     * C75 (9): the map's byte budget. Past `ID_MAP_BUDGET_BYTES` of freeable text the OLDEST entry that stores any is collapsed to a tombstone whose only file is `UNJUDGED_FILE` (its
+     * polls and outputs are withheld from every copy), live entries first, then tombstones that kept files. A collapse loses evidence: the caller counts the session as multi (C54 (1)).
+     * C76: each step takes the oldest text-bearing entry from an index, so learning one id costs O(1) amortized whatever the map holds.
+     */
+    fit(at: number): void;
+    /** The oldest entry that holds freeable text (a live one first), or undefined. */
+    oldestText(): string | undefined;
+    /** Store `id` as a tombstone that withholds its polls and outputs, whatever it held. */
+    collapse(id: string, at: number): void;
+    /** Enforce the bounds after a learning at offset `at`. */
+    bound(at: number): void;
+    /**
+     * Forget the OLDEST tombstone: the id is no longer remembered as evicted, so the whole map is marked UNKNOWN from `at` (`ALL_UNKNOWN`) and every lookup past it fails closed.
+     * Returns the forgotten [id, entry], or undefined when there is none.
+     */
+    evictOldestTomb(at: number): [string, IdEntry] | undefined;
+}
+/**
+ * C56 (12): the entries of an id map as they are persisted. The tracker bounds the map (live entries, tombstones and the whole-map mark), so the limit below
+ * is never reached; if it ever were, the oldest entries would be CUT, and a cut loses their files: the whole map is marked UNKNOWN from the start instead.
+ */
+export declare function boundedIdEntries(entries: readonly (readonly [string, IdEntry])[]): [string, IdEntry][];
+/** The placement of `id` in `map` at `position` (see `lookupId`), UNKNOWN when the whole map has been marked unknown from before `position`. */
+export declare function lookupIn(map: ReadonlyMap<string, IdEntry> | undefined, id: string, position?: number): Place | undefined;
+/**
+ * C56 (13): the placement of EVERY entry of `map` at `position` that carries something (folders or files), for a program that polls an id it cannot name:
+ * it may reach any of them. A whole-map mark that is in force returns the one unknown-and-unjudged place (every entry's files are lost).
+ */
+export declare function placesIn(map: ReadonlyMap<string, IdEntry> | undefined, position?: number): Place[];
+/** The placement of an id at `position` (`undefined`: the whole entry), or `undefined` when it is unknown there. */
+export declare function lookupId(entry: IdEntry | undefined, position?: number): Place | undefined;
+/** What the caller knows about the position of the record being judged. */
+export interface CodexFolderEnv {
+    /** The turn folder in force at the record (the latest `session_meta` / `turn_context` cwd at or before it, in this stream); null when none is known. */
+    turnFolder(): string | null;
+    /** The folders of the call `id`; `undefined` when that call is not known. An empty list means the call's folder could not be told. */
+    callFolders(id: string): readonly string[] | undefined;
+    /** The subset of the call's places that are FILES (a patch's headers, `view_image`'s path); empty when none or when the call is not known. */
+    callFiles(id: string): readonly string[];
+    /** The checkpoint's own entry for the CALL record being judged, when there is one (C49 (2): the same source its output uses). */
+    ownCall?(id: string): CallInfo | undefined;
+    /**
+     * C56 (8)(9): true when a call unknown at this record may have been LOST rather than never made: a line before the record was skipped (too long to be read),
+     * or the record lies at or below the call log's horizon and the view does not start at the stream's first byte. An output whose call is unknown there is unjudged.
+     */
+    callsLost?(): boolean;
+    /** The placement of session `id` / cell `id` as learned BEFORE the record being judged; `undefined` when unknown. */
+    session(id: string): Place | undefined;
+    cell(id: string): Place | undefined;
+    /** C56 (13): every session entry known at the record, as places (see `placesIn`). */
+    sessionPlaces?(): readonly Place[];
+}
+/**
+ * `dirs`: the places the record ran (files it names included). `files`: the subset that are files, judged by the copy's roots and holes (C48 (11)), on a
+ * call AND its output. `inputFiles`: places only a call's own input is judged by. `unknown`: it cannot be told.
+ */
+export type RecordFolders = {
+    readonly dirs: readonly string[];
+    readonly files?: readonly string[];
+    readonly inputFiles?: readonly string[];
+} | {
+    readonly unknown: true;
+    readonly files?: readonly string[];
+    readonly inputFiles?: readonly string[];
+    readonly evidence?: readonly string[];
+    readonly overflow?: true;
+};
+/** The effective folder(s) of `record` (see the module note). The guard stage first, then the placement. */
+export declare function recordFolders(record: Record<string, unknown>, env: CodexFolderEnv): RecordFolders;
+/** C56 (1): a call whose files were lost (it was evicted from a bounded table, or its entry is gone): its output and the ids it started are unjudged. */
+export declare const DROPPED_CALL: CallInfo;
+/**
+ * C62 (3): a call that opens an id ALREADY KNOWN in its stream (still open, closed, dropped, or in the checkpoint) POISONS it: from that call on the id's entry
+ * carries the unjudged mark and `named`, so the repeated call, every later output with the id and every id learned from such an output are withheld from
+ * every copy. ONE function, shared by the checkpoint fold and `CodexTracker`, so the two views agree.
+ */
+export declare function poisonRepeated<T extends {
+    readonly files?: readonly string[];
+}>(info: T): T & {
+    readonly files: readonly string[];
+    readonly named: true;
+};
+/** The call carried files or evidence (so evicting it loses something). */
+export declare function carriesNames(info: {
+    readonly files?: readonly string[];
+    readonly evidence?: readonly string[];
+    readonly named?: true;
+}): boolean;
+/** A call known to the tracker. */
+export interface CallInfo {
+    readonly tool: string;
+    /** The folders it ran in; `[]` when they could not be told. */
+    readonly paths: readonly string[];
+    /** The subset of `paths` that are files the call named (C48 (11)). With `paths` `[]` (unknown) these are the files that could still be read. */
+    readonly files?: readonly string[];
+    /** C53: every folder and file a call whose placement is unknown still named that could be read: discovery evidence. */
+    readonly evidence?: readonly string[];
+    /** C61 (2): the checkpoint does not keep a call's evidence, only that it HAD some (or files): evicting a call rebuilt from the checkpoint must still leave a mark. */
+    readonly named?: true;
+}
+/** What one record contributed. */
+export interface StepResult {
+    /** The record set a new turn folder (`null`: an UNREADABLE header, the turn folder is unknown from here). */
+    readonly turnChange?: string | null;
+    /** The record opened a call. */
+    readonly open?: {
+        readonly id: string;
+        readonly tool: string;
+        readonly paths: string[];
+        readonly files?: string[];
+        readonly evidence?: string[];
+        readonly overflow?: true;
+    };
+    /** The record is the output of this call. */
+    readonly close?: string;
+    /** C75 (9): the output's announcements passed an id map's byte budget and an entry was collapsed (evidence lost): the session counts as multi from here. */
+    readonly collapsed?: true;
+    /** The record's folder could not be told (a call whose folder is unreadable, an output whose call is unknown, a record before any turn folder). */
+    readonly unknown: boolean;
+}
+/** The bounds the checkpoint's call log keeps, which the tracker mirrors so the scan and the delivery agree (C49 (9)). */
+export interface CallBounds {
+    readonly open: number;
+    readonly closed: number;
+    readonly dropped: number;
+}
+/**
+ * The in-order state of one Codex stream: the turn folder, the session map, the cell map and the call table. The resolver's scan and the delivery's observer
+ * both walk records through it, so the checkpoint and the in-span view are built by the same code. The call table has the CHECKPOINT's bounds: at most
+ * `bounds.open` open calls (the oldest is dropped, and its output is UNKNOWN), calls closed on their output, `bounds.closed` of those kept.
+ */
+export declare class CodexTracker {
+    /** The calls known from before this tracker started (the persisted table). */
+    private readonly known;
+    private readonly bounds;
+    /** C62 (3): has the checkpoint seen a call with this id (an entry, or one it dropped)? Exact membership: the sticky all-mark does not count. */
+    private readonly seen;
+    turn: string | null;
+    readonly sessions: IdMap;
+    readonly cells: IdMap;
+    private readonly open;
+    private readonly closed;
+    private readonly dropped;
+    /** C56 (1): the evicted calls that carried files or evidence (bounded by `bounds.dropped`): their outputs are UNJUDGED. */
+    private readonly droppedNamed;
+    /** C56 (1): `droppedNamed` overflowed: every output whose call cannot be found is unjudged from here on. */
+    private droppedNamedAll;
+    constructor(init: {
+        readonly turn: string | null;
+        readonly sessions: Iterable<readonly [string, IdEntry]>;
+        readonly cells: Iterable<readonly [string, IdEntry]>;
+        /** The calls still waiting for an output when this tracker starts, oldest first. */
+        readonly openCalls?: Iterable<readonly [string, CallInfo]>;
+    }, 
+    /** The calls known from before this tracker started (the persisted table). */
+    known: (id: string) => CallInfo | undefined, bounds: CallBounds, 
+    /** C62 (3): has the checkpoint seen a call with this id (an entry, or one it dropped)? Exact membership: the sticky all-mark does not count. */
+    seen?: (id: string) => boolean);
+    /**
+     * C65 (1): an independent copy of this tracker's state (the delivery observer snapshots it before a read and restores it when the same bytes are read again).
+     * The persisted lookups are shared; every map and set is copied. Id entries and call infos are never mutated in place (`learnInto` and `register` replace
+     * them), so they are shared too.
+     */
+    clone(): CodexTracker;
+    /** A call this tracker has seen, else one the persisted table knows; a dropped one is not known. */
+    callInfo(id: string): CallInfo | undefined;
+    /** An evicted call: remembered as unknown, and (C56 (1)) as unjudged when it carried files or evidence. */
+    private evict;
+    /** C62 (3): is `id` already known in this stream? */
+    private repeated;
+    private register;
+    private close;
+    step(record: Record<string, unknown>, at?: number): StepResult;
+}