@manyoars/oars 0.2.0 → 0.3.0

package/dist/sessions/store.d.ts

@@ -0,0 +1,297 @@
+import type { GoldEvaluator } from './gold-arms.js';
+import { type FileHandle } from 'node:fs/promises';
+import { CliError } from '../errors.js';
+import { slugOf } from './allow.js';
+import { type Source } from './sources.js';
+import { type RepoSize } from './public-vocabulary.js';
+import { type DerivedRecords, type ErrorObservation, type PromptObservation, type RecallCall, type SessionObservation, type SignatureRecord, type StepCounts, type Skeleton, type ToolObservation } from './schema.js';
+/** Where the store and the operator's Claude Code logs are; `bin.ts` fills it from the environment. */
+export interface SessionsRuntime {
+    /** `<config>/oars/sessions`. */
+    storeDir: string;
+    /** `~/.claude/projects` (or `$CLAUDE_CONFIG_DIR/projects`). */
+    projectsRoot: string;
+    /** Cursor's `User` folder (`cursorRoot` in cursor.ts), kept as the alias of `sourceRoots.cursor`; absent means no Cursor source. */
+    cursorRoot?: string;
+    /** Where each non-Claude source's store lives, by `Source.name` (sources.ts); a source with no root is not read. `deposit` reads one only when `--allow` names it. */
+    sourceRoots?: {
+        [source: string]: string;
+    };
+    /** The source table; absent means `SOURCES`. The seam a test uses to prove an entry needs no other wiring. */
+    sources?: readonly Source[];
+    /** Where the account's salt comes from; absent means this machine's own (`localSalt`). The seam an account identity replaces (M4). */
+    accountSalt?: (storeDir: string) => Promise<AccountSalt>;
+    /** The fresh single-turn reader behind `gold arms`; absent in a run that has none. */
+    evaluator?: GoldEvaluator | undefined;
+    stdin: NodeJS.ReadableStream;
+    stdout: {
+        write: (text: string) => unknown;
+    };
+}
+interface FileState {
+    size: number;
+    mtimeMs: number;
+    rev: number;
+    /** The capture version that wrote this file's records; a file recorded under another version is deposited again. */
+    v: string;
+    /** The `sid` of the salt the file's records were hashed with; a file recorded under another salt is captured again from raw (spec Section 4). */
+    s?: string;
+    /** The sorted `--redact-domain` set in force when this file was deposited; a file recorded under another set is deposited again. */
+    d: string[];
+    /**
+     * The repository size bucket this file's first frame read, so a later capture's frame does not follow the repository. Held here as well as
+     * in the log because the SessionEnd hook has seconds to run and the log can run to hundreds of MB; absent on a file captured before frames.
+     */
+    repoSize?: RepoSize | null;
+}
+export interface State {
+    files: {
+        [key: string]: FileState;
+    };
+    /** Every `--redact-domain` any deposit used, so recall masks a query the same way the log was masked. */
+    redactDomains: string[];
+    /** Every `--allow` entry any deposit used (folders, prefixes, globs): the SessionEnd hook deposits a session only from a folder these name. */
+    allow: string[];
+}
+export declare const paths: (storeDir: string) => {
+    observations: string;
+    state: string;
+    derived: string;
+    skeletons: string;
+    calls: string;
+    hookCalls: string;
+    pipelineRuns: string;
+    salt: string;
+    raw: string;
+};
+/** The salt every path hash in a store uses, and its `sid`: the first 8 hex characters of SHA-256(salt), stamped on each capture record. */
+export interface AccountSalt {
+    salt: string;
+    sid: string;
+}
+export declare const sidOf: (salt: string) => string;
+/**
+ * This machine's salt, created on first use: path targets hashed with it join inside this store only. This is the one seam where the
+ * account's salt replaces the machine's (`SessionsRuntime.accountSalt`, Open question M4): a store whose `sid` then changes captures its
+ * files again from raw at the next deposit, and nothing else moves.
+ */
+export declare const localSalt: (storeDir: string) => Promise<AccountSalt>;
+export declare const readState: (storeDir: string) => Promise<State>;
+export declare const readRedactDomains: (storeDir: string) => Promise<string[]>;
+/** The `--allow` entries and `--redact-domain` set earlier deposits used; the nightly run repeats them. */
+export declare const readSaved: (storeDir: string) => Promise<{
+    allow: string[];
+    redactDomains: string[];
+}>;
+export declare const writeAtomic: (file: string, text: string) => Promise<void>;
+export { slugOf };
+export interface DepositOptions {
+    allow: readonly string[];
+    redactDomains: readonly string[];
+    now: () => number;
+}
+/** What one deposit run read from one source. */
+export interface SourceTally {
+    /** Of `sessions`, the ones this source supplied. */
+    read: number;
+    /** Why the store (or a file in it) could not be read: the full path for the terminal. */
+    unreadable: string[];
+    /** The same reasons with the file reduced to its base name: the hook-call record (class A) must not carry the user name in a path. */
+    unreadableLogged: string[];
+    /** Sessions skipped because their id is not a safe file name. */
+    rejected: number;
+}
+export interface DepositResult {
+    /** Session files parsed this run. */
+    sessions: number;
+    /** Session files skipped because size, mtime, capture version, salt, and redact-domain set were all unchanged. */
+    unchanged: number;
+    lines: number;
+    badLines: number;
+    observations: number;
+    /** Subagent transcripts parsed this run (A24); not counted in `sessions`, so per-session denominators stay main sessions. */
+    subagents: number;
+    /** Per source name (sources.ts): what this run read from it. A source that was not allowed or has no store has no entry. */
+    sources: {
+        [source: string]: SourceTally;
+    };
+    /** Of `sessions`, the Cursor composer sessions parsed this run; 0 when the Cursor source is not allowed or absent. Alias of `sources.cursor`. */
+    cursor: number;
+    /** Why the Cursor store could not be read this run (locked, corrupt, or from a Cursor version this reader does not know); empty when it was read or absent. */
+    cursorUnreadable: string[];
+    /** The same reasons with the store file reduced to its base name: the hook-call record (class A) must not carry the user name in a path. */
+    cursorUnreadableLogged: string[];
+    /** Cursor composers skipped this run because their id is not a safe file name. */
+    cursorRejected: number;
+    /** Project folders under the projects root that are not on the allowlist, so were not opened. */
+    skippedFolders: number;
+    /** The allowed folders that exist under the projects root. */
+    folders: string[];
+    /** Allowed names that matched no project folder. */
+    missing: string[];
+}
+/** What a deposit never reads: project folders that hold transcripts but that no `--allow` entry names. */
+export interface SkippedScope {
+    folders: number;
+    /** Main transcripts in those folders; subagent transcripts are not counted, as everywhere else. */
+    transcripts: number;
+    /** The folder names, sorted. */
+    names: string[];
+}
+/**
+ * The scan rule is the allowlist (`depositLocked`, `depositSessionLocked`): a folder no entry names is not opened, by design, so
+ * a worktree folder of an allowed repository is skipped when only the repository's own folder is named. This reads folder listings
+ * only, never a transcript, so `verify` and `books` can say what the store does not hold.
+ */
+export declare const skippedFolders: (runtime: SessionsRuntime) => Promise<SkippedScope>;
+export declare const listDir: (dir: string) => Promise<import("fs").Dirent<string>[]>;
+interface SubagentFile {
+    dir: string;
+    /** The folders between `subagents` and the file, for example `['workflows', 'wf_x']`. */
+    path: string[];
+    parent: string;
+    name: string;
+}
+export declare const subagentFiles: (folder: string, sessions: readonly string[]) => Promise<SubagentFile[]>;
+/** The session folders under a project folder: each may hold subagent transcripts, even when its main transcript is gone. */
+export declare const sessionFolders: (folder: string) => Promise<string[]>;
+/** What a derive pass read and wrote, for the step log (spec 3.1 `in` and `out`, 4.2 `key`). */
+export interface DeriveTrace {
+    ms: number;
+    in: StepCounts;
+    out: StepCounts;
+    key: string;
+}
+/** What a deposit wrote, filled in by the caller's trace so `DepositResult` and the `--json` document keep their shape. */
+export interface DepositTrace {
+    /** Records written, by kind: `session` (main), `subagent`, `user-prompt`, `tool`, `error-line`. */
+    kinds: StepCounts;
+    /** Pending sessions this deposit took before its own, as step-row `in` counts: `pending` found, `pendingDropped` (transcript gone, folder no longer allowed, not an entry, or removed at `PENDING_MAX_FAILURES` failures), `pendingKept` (failed, or an unreadable file; left for the next run). */
+    pending?: StepCounts;
+    /** Set to the refusal's first line when the Stop hook found the store locked and recorded its session in the pending list instead of depositing: the caller logs a `deferred` row, not an `error` one. */
+    deferred?: string;
+    /** The derive pass a whole-store deposit ends with (the index pass follows it: `index`). */
+    derive?: DeriveTrace;
+    /** A derive pass that failed after the deposit's records and `state.json` were written: the caller logs `deposit` ok and `derive` error, then rethrows. */
+    deriveFailure?: {
+        error: unknown;
+        key: string;
+        ms: number;
+    };
+    /** The index pass after a derive that succeeded: its own step (spec 3.1), run at the nightly and manual runs. */
+    index?: DeriveTrace;
+    /** An index pass that failed after the derive was written: the caller logs `derive` ok and `index` error, then rethrows. */
+    indexFailure?: {
+        error: unknown;
+        key: string;
+        ms: number;
+    };
+}
+export declare const newTrace: () => DepositTrace;
+export declare const digest: (parts: readonly string[]) => string;
+/**
+ * Rewrites `derived.json` (the derive step), then the hook index (the index step), from the whole store. With a trace, a failure of
+ * either is recorded on it instead of thrown, so the caller can log the deposit that already wrote its records, then the failed step
+ * (spec 3.1: one row per step, a failed derive leaving the index skipped), and rethrow.
+ */
+export declare const refresh: (runtime: SessionsRuntime, redactDomains: readonly string[], at: string, trace?: DepositTrace, held?: LockHold) => Promise<void>;
+/** Another deposit holds the store lock and the wait ran out: the one failure the Stop hook defers instead of counting as a failed run. */
+export declare class StoreLockedError extends CliError {
+    constructor();
+}
+interface LockOptions {
+    /** How long to wait for a holder before giving up. */
+    waitMs: number;
+    /** A lock file older than this belongs to a process that died or passed `holdMs`; it is broken. */
+    staleMs: number;
+    /**
+     * The longest a holder keeps its lock refreshed; default six times `staleMs` (an hour). Past it the heartbeat stops, so a holder that
+     * hangs while its process lives ages out like a dead one and the next waiter breaks it, rather than every deposit waiting on it for good.
+     */
+    holdMs?: number;
+}
+/** What `withLock` gives its work: whether this run's lock file is still the one standing. */
+export type LockHold = () => Promise<boolean>;
+/** The store lock was broken and taken by another run while this one worked: it writes nothing more. */
+export declare class StoreLockLostError extends CliError {
+    constructor();
+}
+/**
+ * Runs `work` as the only writer of `state.json` and the observations file. The SessionEnd hooks of parallel sessions and the nightly
+ * run each read, extract, and rewrite `state.json`; without this one's `files` and `allow` entries are lost to another's write.
+ */
+export declare const withLock: <T>(storeDir: string, work: (held: LockHold) => Promise<T>, options?: LockOptions) => Promise<T>;
+export declare const deposit: (runtime: SessionsRuntime, options: DepositOptions, trace?: DepositTrace) => Promise<DepositResult>;
+/**
+ * The log's lines, a chunk at a time: the log can pass the longest string Node can hold (536,870,888 characters), so it is never one string.
+ * It splits on the newline alone, not through `readline`, which also ends a line at U+2028 and U+2029: `JSON.stringify` leaves those raw inside a
+ * value. A missing log has no lines, and a last line with no newline is yielded as it stands, for the reader to parse or skip.
+ */
+export declare const logLines: (file: string, held?: FileHandle) => AsyncGenerator<string>;
+/** The inverse of `sessionOfRelative`: `<id>.jsonl`, or `<parent>/subagents/[workflows/<wf>/]<agent>.jsonl` for a `<parent>~[<wf>~]agent-x` id. */
+export declare const relativeOfSession: (session: string) => string[];
+/**
+ * The sessions of `behind` (captured before the current version) whose source is gone (the transcript from both the harness and `raw/`, or the
+ * session from its source's store, such as a Cursor composer): they can never be captured again, so `verify` counts them `cv-frozen` instead of failing `--strict` over them.
+ */
+export declare const frozenSessions: (runtime: SessionsRuntime, behind: readonly {
+    project: string;
+    session: string;
+}[]) => Promise<Set<string>>;
+export type SessionDeposit = 'deposited' | 'unchanged' | 'not-allowed' | 'missing' | 'deferred';
+/**
+ * Deposits one transcript, as the SessionEnd hook does: only from a folder that earlier `--allow` entries name, and idempotent by size and
+ * mtime. It does not rebuild `derived.json` or the hook index (that is a whole-store pass; the nightly run does it), so it stays fast.
+ * Under the lock it first takes up to `PENDING_HOOK_CAP` sessions an earlier hook deferred, then its own. If the lock is still held after the
+ * wait it records the session in the pending list, which needs no lock, and returns `deferred`: the next deposit of any kind takes it.
+ */
+export declare const depositSession: (runtime: SessionsRuntime, transcript: string, now: () => number, trace?: DepositTrace) => Promise<SessionDeposit>;
+export interface Store {
+    /** Main transcripts only, so session counts and per-session denominators are unchanged by subagent deposits. */
+    sessions: SessionObservation[];
+    prompts: PromptObservation[];
+    errors: ErrorObservation[];
+    /** Subagent transcripts (A24), kept apart from `sessions` so G1 denominators stay main sessions. */
+    subagents: SessionObservation[];
+    /** The tool calls of every version-3 or later transcript, main and subagent. */
+    tools: ToolObservation[];
+    /** Sessions whose capture records a newer oars wrote: read for the fields known here, and reported by the commands that print the store. Set by `loadStore` only. */
+    newerCaptures: number;
+}
+/** What one pass over the log keeps: a number or two per session, never the records. */
+interface LogScan {
+    /** Each session's highest rev, over every kind of record. */
+    latest: Map<string, number>;
+    /** True when some session has a record below its highest rev, which a compaction would drop. */
+    superseded: boolean;
+    /** Sessions whose newest capture record was written by a newer oars, counted as `loadStore` counts them. */
+    newerCaptures: number;
+}
+export declare const scanLog: (file: string, held?: FileHandle) => Promise<LogScan>;
+/**
+ * The store as a reader sees it: for each session only the highest `rev`. A version-3 or later session is derived here from its capture records
+ * (EXTRACTOR_VERSION rules); a session whose last deposit was version 2 keeps the prompt and error lines that deposit wrote.
+ * `afterFirstPass` runs between the two passes over the log: a seam for the test that compacts the log there.
+ */
+export declare const loadStore: (storeDir: string, afterFirstPass?: () => Promise<void>) => Promise<Store>;
+/**
+ * Drops the superseded revs from the log, so a re-capture does not leave a full copy of every session behind. The caller holds the store lock,
+ * the same one every append takes. Only a line a higher rev of its session replaces goes: a line this version cannot read stays, since a later
+ * oars may read it, and a kept line is written back byte for byte. A crash before the rename leaves the old log whole and a temp file that no
+ * reader opens and the next compaction removes. Throws, with the log as it was, when the rewrite cannot finish.
+ */
+export declare const compactLog: (storeDir: string, renameWaitMs?: number, held?: LockHold) => Promise<void>;
+/** A version-3 `contextFingerprint` is `<prompt|->.<environment|->`: only the prompt half survives, and `-` reads as none. */
+export declare const promptHalf: (contextFingerprint: unknown) => string | null;
+export declare const readCalls: (storeDir: string) => Promise<RecallCall[]>;
+/**
+ * `unreadable` counts skeleton files that are torn, corrupted, or not a skeleton, so verify reports them instead of aborting. With `lean`, each
+ * line's `hashes` read as empty: `verify` holds every skeleton at once and checks structure, never content.
+ */
+export declare const readSkeletons: (storeDir: string, only?: string, lean?: boolean) => Promise<{
+    skeletons: Skeleton[];
+    unreadable: number;
+}>;
+/** The derived records, a pure function of the store. */
+export declare const derive: (store: Store, at: string) => DerivedRecords;
+export declare const signatureRecord: (sig: string, list: readonly ErrorObservation[]) => SignatureRecord;