@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/governance/store/run-store.d.ts

@@ -0,0 +1,229 @@
+/**
+ * RunStore - the single writer of `<root>/<runId>/` (governance-mode section 12.1).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * RESPONSIBILITIES AND WHY THEY ARE ONE CLASS. Every write funnels through ONE FIFO mutex
+ * so that two concurrent engine paths (a submission landing while a stage-end checkpoint
+ * is being written) can never interleave their bytes or their sequence numbers.
+ * Cross-process exclusion is a separate mechanism (`run.lock`, see `run-lock.ts`).
+ *
+ * TRUTH VS CHECKPOINT. `events.jsonl` is the truth (append + fsync, one JSON row per
+ * line); `run.json` and `ledger.json` are atomic-replace checkpoints. `load()` compares
+ * the checkpoint `seq` values with the log tail and reports `needsReplay`; the actual
+ * fold of events into state is supplied by the engine as a callback, which keeps this
+ * file free of any dependency on `rules/ledger.ts` (I-G2 stays the ledger's business).
+ * Checkpoint writers must therefore stamp the CURRENT tail seq, otherwise `needsReplay`
+ * is true forever.
+ *
+ * SEQUENCES ARE ASSIGNED HERE, not by callers: the store caches the tail per run, so a
+ * caller can never reuse or skip a number. A row dropped by compaction consumes no seq,
+ * which keeps the checkpoint-vs-tail comparison honest.
+ *
+ * The root directory is a constructor argument (`getGovernanceDir()` lives in
+ * `config/app-paths.ts`); nothing here reads the environment.
+ */
+import type { LedgerState, RunDigest, RunState, RunStatus, StoredEvent, StoredEventType } from '../types.js';
+import { type GovFs } from './atomic.js';
+import { type AcquireResult } from './run-lock.js';
+export type GovStoreErrorCode = 'BAD_RUN_ID' | 'BAD_PATH' | 'READ_ONLY' | 'EXISTS' | 'NOT_FOUND';
+/** Programmer-facing store failures (the engine turns them into tool text). */
+export declare class GovStoreError extends Error {
+    readonly code: GovStoreErrorCode;
+    constructor(code: GovStoreErrorCode, message: string);
+}
+export interface RunStoreOptions {
+    /** `getGovernanceDir()`: the directory holding `index.jsonl` and the run folders. */
+    root: string;
+    fs?: GovFs;
+    platform?: NodeJS.Platform;
+    now?: () => number;
+    /** Returns the 3 random `[a-z0-9]` characters of a run id. */
+    newId?: () => string;
+    pid?: number;
+    isPidAlive?: (pid: number) => boolean;
+    heartbeatMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    /** Called when a heartbeat finds the lock gone or taken by another pid. */
+    onLockLost?: (runId: string) => void;
+}
+export interface IndexEntry {
+    runId: string;
+    cwd: string;
+    sessionId?: string;
+    goal: string;
+    status: RunStatus;
+    createdAt: number;
+    updatedAt: number;
+    /**
+     * The `/gov runs` summary (governance-mode-v1-1 V-6). Optional: rows written before it
+     * existed simply lack it and read back as `undefined`; nothing needs migrating.
+     */
+    digest?: RunDigest;
+}
+export interface AppendEventInput {
+    type: StoredEventType;
+    actor: string;
+    payload: Record<string, unknown>;
+    at?: number;
+    /**
+     * Caller-assigned sequence number. The engine mutates memory synchronously and queues
+     * the writes, so it must stamp checkpoints and ledger entries with a seq BEFORE the
+     * (async) append resolves; it therefore owns the counter. Absent => `lastSeq + 1`.
+     */
+    seq?: number;
+}
+export interface ReplayInput {
+    run: RunState | null;
+    ledger: LedgerState | null;
+    /** Every parsed event in file order; the callback filters by `seq` itself. */
+    events: StoredEvent[];
+    tailSeq: number;
+}
+export interface ReplayOutput {
+    run?: RunState | null;
+    ledger?: LedgerState | null;
+}
+export type ReplayFn = (input: ReplayInput) => ReplayOutput;
+export interface LoadedRun {
+    run: RunState | null;
+    ledger: LedgerState | null;
+    tailSeq: number;
+    /** A checkpoint is missing, unreadable, or behind the log tail. */
+    needsReplay: boolean;
+    /** A `replay` callback ran and the repaired checkpoints were written back. */
+    replayed: boolean;
+    /** A higher major schemaVersion: viewable, never writable or resumable. */
+    readOnly: boolean;
+    /** The log has bytes but not one valid row: the run cannot be rebuilt. */
+    eventsUnreadable: boolean;
+    /** Human-readable findings (torn tail, skipped rows, corrupt checkpoints). */
+    problems: string[];
+}
+export interface LoadOptions {
+    replay?: ReplayFn;
+}
+export interface PruneResult {
+    pruned: string[];
+    skippedLocked: string[];
+    failed: string[];
+}
+export type ArtifactWrite = {
+    ok: true;
+    bytes: number;
+    totalBytes: number;
+} | {
+    ok: false;
+    exhausted: true;
+    message: string;
+};
+export interface DirEntry {
+    name: string;
+    isDirectory: boolean;
+    size: number;
+}
+export declare class RunStore {
+    readonly root: string;
+    private readonly fs;
+    private readonly platform;
+    private readonly now;
+    private readonly newId;
+    private readonly pid;
+    private readonly isPidAlive;
+    private readonly heartbeatMs;
+    private readonly sleep;
+    private readonly onLockLost;
+    private readonly mutex;
+    private readonly caches;
+    private readonly heartbeats;
+    private readonly heldLocks;
+    constructor(options: RunStoreOptions);
+    /** Validates the id first: a run id is the only caller-influenced path segment. */
+    runDir(runId: string): string;
+    private runFile;
+    /** "g" + base36(timeMs) + 3 random [a-z0-9]; retried until the folder is unused. */
+    allocateRunId(): Promise<string>;
+    /** Create the folder, `spec.md` (verbatim) and the first `run.json`; index the run. */
+    createRun(input: {
+        state: RunState;
+        spec: string;
+    }): Promise<void>;
+    /**
+     * Atomic replace of `run.json`; appends an index row when the status changed OR, for a
+     * caller that supplies one, when the digest did. `index.jsonl` is append-only and
+     * `listRuns` keeps the newest row per run, so appending IS the update. A caller without a
+     * digest behaves byte-for-byte as before.
+     */
+    writeRun(state: RunState, digest?: RunDigest): Promise<void>;
+    /** Atomic replace of `ledger.json`. The caller stamps `ledger.seq`. */
+    writeLedger(runId: string, ledger: LedgerState): Promise<void>;
+    /** One-way `token_ledger.py` v2.0 projection. Never read back. */
+    exportScoreboard(runId: string, ledger: LedgerState): Promise<void>;
+    /**
+     * Append one event and fsync. Returns the stored row, or `null` when compaction
+     * dropped it (past the byte cap only audit-only types are dropped).
+     */
+    appendEvent(runId: string, input: AppendEventInput): Promise<StoredEvent | null>;
+    private writeCompactionMarker;
+    private writeEventRow;
+    /** Rows with `seq > afterSeq`, in file order. Missing file reads as empty. */
+    readEvents(runId: string, afterSeq?: number): Promise<StoredEvent[]>;
+    /** How many rows compaction dropped in this process (the marker row says why). */
+    droppedEventCount(runId: string): number;
+    private parseEvents;
+    /** Read both checkpoints and the log tail; optionally repair via `options.replay`. */
+    load(runId: string, options?: LoadOptions): Promise<LoadedRun>;
+    private isNewerSchema;
+    private checkpointsBehind;
+    private readCheckpoint;
+    private writeRepaired;
+    private lockDeps;
+    /** Take `run.lock` (stale locks are taken over). Refusal text names the holder pid. */
+    acquireLock(runId: string): Promise<AcquireResult>;
+    /** Start the unref'd heartbeat timer; idempotent. */
+    startHeartbeat(runId: string): void;
+    stopHeartbeat(runId: string): void;
+    /** One heartbeat tick (public so tests need no fake timers). False = lock lost. */
+    heartbeatOnce(runId: string): Promise<boolean>;
+    releaseLock(runId: string): Promise<void>;
+    /** Stop every timer and release every lock this process holds. Safe to call twice. */
+    dispose(): Promise<void>;
+    private isRunLocked;
+    /** Atomic write of a projection (`board.md`, `reports/phase-1.md`). Not budgeted. */
+    writeRunFile(runId: string, rel: string, text: string): Promise<void>;
+    readRunFile(runId: string, rel: string): Promise<string | null>;
+    listRunDir(runId: string, rel: string): Promise<DirEntry[]>;
+    /**
+     * Write under `artifacts/`, enforcing the per-run byte budget. The budget is a refusal
+     * (never a silent drop): the caller reports `NOT ACCEPTED: run storage budget exhausted`
+     * and the engine escalates the run.
+     */
+    writeArtifactFile(runId: string, rel: string, text: string): Promise<ArtifactWrite>;
+    private measureArtifacts;
+    private get indexPath();
+    private appendIndexUnlocked;
+    private readIndexUnlocked;
+    /** Latest row per run, newest first. */
+    listRuns(): Promise<IndexEntry[]>;
+    /**
+     * Newest run of ANY status for `cwd` whose folder still exists. `/gov report` uses this
+     * rather than `latestResumable`: the report people ask for most is the one of the run
+     * that just closed, and a closed run is by definition not resumable.
+     */
+    latestForCwd(cwd: string): Promise<IndexEntry | null>;
+    /** Newest unfinished run for `cwd` whose folder still exists. */
+    latestResumable(cwd: string): Promise<IndexEntry | null>;
+    /**
+     * Delete closed / abandoned runs older than the retention window. Best effort and
+     * bounded (`pruneMaxPerPass`); a locked run is never touched. Never throws.
+     */
+    pruneOld(): Promise<PruneResult>;
+    private pruneUnlocked;
+    private atomic;
+    private freshCache;
+    private assertWritable;
+    /** Lazily derive the tail seq / byte count from disk, once per run per process. */
+    private ensureCache;
+}
+/** Validate an index row's digest field; anything malformed reads as "no digest". */
+export declare function parseRunDigest(raw: unknown): RunDigest | undefined;