@sema-agent/core 5.20.0 → 5.21.0

package/dist/stores/file/memory-store.d.ts

@@ -2,38 +2,120 @@ import { type Embedder, type MemoryNoteHeader, type MemoryNoteRecord, type Memor
 export declare class FileMemoryStore implements MemoryStore {
     private readonly root;
     private readonly tmpDir;
+    /** Optional injected embedder (design/81 Slice 5). When present, note bodies are embedded (in the background,
+     *  after the durable note write) into a rebuildable sidecar index and `searchScored` ranks by cosine distance
+     *  (portable / in-process, mirrors PgMemoryStore's jsonb mode). Absent ⇒ lexical, byte-identical to before. */
     private readonly embedder?;
+    /** ms budget for a background embed; a slower/stuck endpoint yields no vector (row stays lexical), never
+     *  blocking the durable note write (which already completed). */
     private readonly embedTimeoutMs;
+    /** In-flight background embeds (so tests can flush + `close` can drain). */
     private readonly pending;
+    /**
+     * RB-146 (2026-07-25, 按面收口): scope state is shared per PHYSICAL directory, like every other file
+     * backend. This was the last store on this surface still caching replayed state on the INSTANCE: a second
+     * `FileMemoryStore` over one directory replayed its own view on first touch and then served it forever,
+     * so a note durably committed through one instance was invisible to the other — the same shape as RB-73
+     * (session), RB-55 (agent), RB-59 (run) and RB-134 (checkpoint). Refcounted, and the last holder closes
+     * the logs; the `closed` latch below already existed for the fd-recycle guard.
+     */
     private get scopes();
     private readonly sharedScopes;
     private readonly scopeKey;
+    /** Set by {@link close}: a background embed that resolves AFTER close must NOT writeSync to the (now closed)
+     *  vlog fd — a stray write on a recycled fd could corrupt an unrelated file. */
     private closed;
     constructor(root: string, opts?: {
         embedder?: Embedder;
         embedTimeoutMs?: number;
     });
+    /** design/81 Slice 5 rung: `portable` (in-process cosine over the sidecar) when an embedder is injected,
+     *  else `lexical`. File never reaches `native` (no backend index). */
     get vectorMode(): MemoryVectorMode;
+    /** True when an embedder was injected. Exposed so a consumer/test can confirm it was accepted. */
     get hasEmbedder(): boolean;
+    /** Await all in-flight background embeds (tests / `close`). */
     flushEmbeds(): Promise<void>;
+    /** Open (replay) a scope's notes + sidecar vectors once and cache it. */
     private scopeState;
+    /**
+     * RB-267 — record that `scope` holds live descriptors, and evict the coldest scopes past
+     * {@link MAX_OPEN_MEMORY_SCOPES}. Eviction releases the handles ONLY (`closeForSwap`, the RB-167 lazy
+     * reopen); the replayed `ScopeState` stays in the map, so nothing about the authority — the entry
+     * list, the cursor, the vector cache — is rebuilt or lost, and a later write to an evicted scope
+     * reopens its log transparently.
+     */
     private touchOpenLogs;
+    /** RB-267 — the notes log for a WRITE. Every durable append goes through here so the LRU sees the
+     *  access: a write is also the only thing that can (re)open a descriptor (`AppendLog.append` reopens
+     *  a swap-closed log lazily), so touching here is what keeps "has an open handle ⇒ tracked" true.
+     *  Reads never open anything and deliberately do not touch. */
     private writeLog;
+    /** RB-267 — the sidecar vector log, opened on FIRST WRITE. Only {@link queueEmbed} writes vectors, so
+     *  a store with no embedder never opens this file at all (it used to take a descriptor per scope for
+     *  a file it would never touch). Replay reads the path directly and needs no handle. */
     private vectorLog;
+    /** Queue a background embed of `body` → sidecar vector for `id` (best-effort, timeout-bounded, non-blocking).
+     *  Only when an embedder is injected; a failure/timeout leaves the row lexical (fail-open). The durable note
+     *  write has ALREADY happened before this is called, so this never gates durability. */
     private queueEmbed;
+    /** Rewrite the derived `MEMORY.md` projection atomically (CC markdown parity). */
     private writeProjection;
     read(scope: string): string | null;
     append(scope: string, note: string): string | void;
     appendStructured(scope: string, note: StructuredNoteInput): string;
+    /** Append + fsync the note event BEFORE updating the in-memory list, then refresh the projection. */
     private commit;
     clear(scope: string): void;
+    /** design/84 Seam B: read the cached periodic-consolidation cursor (replayed from the last `op:cursor`). */
     getConsolidationCursor(scope: string): string | undefined;
+    /** design/84 Seam B: persist the periodic-consolidation cursor via a durable `op:cursor` append-log event,
+     *  then update the cached state (durable FIRST, like `commit`). */
     setConsolidationCursor(scope: string, cursor: string): void;
+    /**
+     * Keyword search backing the `recall` tool. design/81 Slice 2b — uses the SHARED synonym/stem-aware
+     * {@link import("../../core/memory.js").lexicalSearchMatch} (the SAME matcher as
+     * {@link import("../../core/memory.js").InMemoryMemoryStore.search}, ZERO model/native/embedder dep) so
+     * "auth token" matches a note saying "credentials" / "bearer", and the `recall` tool returns IDENTICAL
+     * results across the File and InMemory backends. A bullet matches a query term iff it contains ANY of that
+     * term's expansions, and must match EVERY query term (AND across terms, OR within a term's synonyms). With
+     * no synonym/stem hit this is byte-identical to the plain substring filter.
+     */
     search(scope: string, query: string, limit?: number): string[];
+    /** Manifest (design/65 §2.2): a header per note, body excluded — in-memory parity. */
     listStructuredNotes(scope: string): MemoryNoteHeader[];
     getByIds(scope: string, ids: string[]): MemoryNoteRecord[];
+    /**
+     * Id-addressable similarity retrieval (design/81 Slice 2 — the consolidation candidate source). The
+     * `score` is a cosine **DISTANCE** ∈ [0,2], **0 = identical** ({@link ScoredMemory} contract): it is the
+     * lexical `1 - Jaccard(terms)` ∈ [0,1] ⊂ [0,2] stand-in (byte-identical to
+     * {@link InMemoryMemoryStore.searchScored} / the lexical {@link import("../pg.js").PgMemoryStore} fallback),
+     * so the `{0.05, 0.3}` consolidation band needs no retune. An injected embedder is ACCEPTED but vector
+     * ranking is the DEFERRED Slice 5 — so this method ALWAYS uses the lexical distance for now (an injected
+     * embedder is harmless, NOT a throw). Excludes the query's own id (a note must not self-match — see below)
+     * and zero-overlap entries; returns the `limit` nearest, ascending by distance.
+     *
+     * **Self-id exclusion:** byte-identical to {@link InMemoryMemoryStore.searchScored} / the lexical
+     * {@link import("../pg.js").PgMemoryStore} fallback, the SOLE consumer (consolidation) excludes the
+     * query note's own id (and its sibling this-task ids) by filtering the returned `ScoredMemory[]` on its
+     * `thisTaskIds` set — keeping the store's ranking pure and the cross-backend contract identical.
+     */
     searchScored(scope: string, query: string, limit?: number): ScoredMemory[] | Promise<ScoredMemory[]>;
+    /**
+     * Consolidation UPDATE (design/81 Slice 2): replace a note's body by id, keeping the id stable. Appends a
+     * durable `update` event FIRST, then mutates the in-memory replay + refreshes the projection — same
+     * durable-before-visible order as {@link commit}. An auto-derived description is re-derived from the new
+     * body (so the manifest doesn't drift); an explicit one is preserved (design/65 [79], in-memory parity).
+     * Unknown id → no-op (defensive). NB: no `sanitizeUntrustedText` here — the fence lives at the
+     * inlets/recall, NOT in `update` (design/81 §1; in-memory `update` only trims).
+     */
     update(scope: string, id: string, text: string): void;
+    /**
+     * Consolidation DELETE (design/81 Slice 2): remove a note by id (id never reused afterward). Appends a
+     * durable `delete` tombstone FIRST, then drops it from the in-memory replay + refreshes the projection.
+     * Unknown id → no-op.
+     */
     delete(scope: string, id: string): void;
+    /** Release all open scope handles (best-effort). */
     close(): void;
 }

package/dist/stores/file/permission-rule-store.d.ts

@@ -1,6 +1,51 @@
+/**
+ * design/179 §5/§8 — the file backend for persisted allow rules.
+ *
+ * ## Why this store builds its own symlink refusal
+ *
+ * The other file stores canonicalize with `realpath`, which RESOLVES a symlink rather than refusing one —
+ * the right answer for a data directory, the wrong one for a file that decides what runs without asking.
+ * So the refusal is assembled here from the pieces this repository already uses elsewhere: the directory
+ * is `lstat`ed and refused if it is a symlink, not a directory, or owned by another user; the temp file is
+ * opened `O_EXCL | O_NOFOLLOW` so no planted link is ever traversed; the publish is the standard
+ * write-temp → fsync → rename → fsync-dir sequence; and the READ side `lstat`s too, because `readFileSync`
+ * follows a link happily.
+ *
+ * ## One writer, enforced — reading is unrestricted
+ *
+ * Atomic rename keeps a file from tearing; it does not make "read the revision, decide, write" atomic. Two
+ * processes can each read revision N, and the second rename discards the first one's add — or its
+ * TOMBSTONE, leaving a rule somebody deleted standing.
+ *
+ * Three attempts at solving that inside the file established what does NOT work. Declaring single-process
+ * use does not hold when the provider is independently constructible. A hand-rolled advisory lock brings
+ * its own ownership bugs: pruning an abandoned lock races the next holder for the same path, and expiring
+ * by age kills a live-but-slow writer. Write-then-read-back does not close it either — two writers can
+ * each rename and each verify before the other renames, so both report success and one write is gone.
+ * That last one is the instructive failure: no scheme that reasons only about the FILE can serialize
+ * transactions, because the window opens before the first byte is written.
+ *
+ * So the boundary is enforced where it can be. Obtaining the WRITE face acquires the same process-level
+ * lock the rest of this file-store family uses — write-then-link acquisition, no expiry by age, and a
+ * prune only for a definitively dead owner — and a second holder, in this process or another, is refused
+ * loudly instead of interleaving. Inside the one process that holds it, transactions are serialized and
+ * the existing revision check is then a true compare-and-set.
+ *
+ * READING takes nothing. The gate reads on every shell call and must never be able to fail on a lock, so
+ * the lock rides on the write face alone. A deployment that genuinely needs concurrent writers wants a
+ * backend with real atomic compare-and-set, which is what the store seam exists for.
+ *
+ * ## Corruption is a whole-file refusal
+ *
+ * A file that does not parse, or whose checksum does not match its contents, yields ZERO rules and a loud
+ * disclosure — never a partial load. Half a rule set is a set nobody reviewed. Note what the checksum is
+ * and is not: it detects corruption, and it does not detect an editor, because an editor recomputes it.
+ * For this backend the trust is host = user, exactly as for the settings file it mirrors.
+ */
 import type { PermissionRuleStore, PermissionRuleStoreProvider, PermissionRuleWriter, StoredAllowRules, WritablePermissionRuleStore } from "../../core/permission-rule-store.js";
 import { PERMISSION_RULE_WRITER } from "../../core/permission-rule-store.js";
 import type { StoreDurability, StoreFidelity } from "../../core/checkpoint-store.js";
+/** One principal's rule file. */
 declare class FilePermissionRuleStore implements WritablePermissionRuleStore {
     private readonly dir;
     private readonly file;
@@ -9,24 +54,58 @@ declare class FilePermissionRuleStore implements WritablePermissionRuleStore {
     readonly durability: StoreDurability;
     readonly fidelity: StoreFidelity;
     constructor(dir: string, file: string, acquireWriteLock: () => void, onError?: ((message: string) => void) | undefined);
+    /** Read and validate. Any refusal answers with an empty set AND says so — never a silent empty store. */
     private read;
     private disclose;
     private write;
     list(): Promise<StoredAllowRules>;
+    /**
+     * The current file, for a WRITE.
+     *
+     * Only genuine absence initializes a fresh one. An unreadable file — bad JSON, a failed checksum, an
+     * unexpected shape, a planted symlink — makes every write throw, and the original bytes are left exactly
+     * where they are. Treating corruption as emptiness here is what turns a recoverable incident into an
+     * unrecoverable one: the next redemption would write a fresh file over the damaged one, discarding every
+     * standing rule, every tombstone, the revision and the replica identity, along with the evidence of what
+     * went wrong. Reads already answer zero rules for the same condition, so the lane stays fail-closed
+     * while a person looks at the file.
+     */
     private current;
+    /**
+     * Publish `next` and confirm it is readable and is the version just written.
+     *
+     * This is an integrity check, not concurrency control — a write lock is what makes the transaction
+     * atomic (see the module doc). What it catches is the write that did not survive its own round trip:
+     * a filesystem that reordered, a partial device failure, or a hand edit landing at exactly the wrong
+     * moment. Failing here is loud rather than a reported conflict, because under the lock there is no
+     * legitimate writer to have lost a race to.
+     */
     private writeAndVerify;
+    /** Serializes this process's transactions. With the write lock held, this is the whole of the
+     *  serialization the revision check needs. */
     private writeChain;
     private serialize;
+    /** Acquiring the write face takes the process lock; reading never does. */
     get [PERMISSION_RULE_WRITER](): PermissionRuleWriter;
     private readonly writer;
 }
+/**
+ * The file-backed provider. One file per principal, named by a digest of the principal so no identity
+ * string ever becomes a path component.
+ *
+ * An absent principal resolves to a store that reads zero rules and refuses to write — an unauthenticated
+ * task does not share anyone's bucket.
+ */
 export declare class FilePermissionRuleStoreProvider implements PermissionRuleStoreProvider {
     private readonly dir;
     private readonly onError?;
     private lock;
     constructor(dir: string, onError?: ((message: string) => void) | undefined);
+    /** Take the writer lock, once, on first use of a write face. Reading never calls this. */
     private acquireWriteLock;
     forPrincipal(principal: string | undefined): PermissionRuleStore;
+    /** Release the writer lock. A long-lived deployment holds it for its lifetime; a test or a short-lived
+     *  tool releases so the next holder is not told a live process owns the directory. */
     dispose(): void;
 }
 export type { FilePermissionRuleStore };

package/dist/stores/file/session-policy-store.d.ts

@@ -1,19 +1,47 @@
 import { type PutRulesOptions, type SessionPermissionRules, type SessionPolicyStore, type SessionRulesRecord, type StoredSessionRules } from "../../core/session-policy-store.js";
+/**
+ * design/99 §E6 — file-backed {@link SessionPolicyStore} for the local (TOC) backend: ONE JSON file per
+ * `(sessionId, principal)`, semantics **byte-for-byte identical to `InMemorySessionPolicyStore`** (the
+ * cross-backend equivalence contract). CAS-rev OCC + tighten-only reuse the SAME pure helpers
+ * (`loosenReasons`/`normalizeRules`/`stripRev`) as core — no re-implemented rule logic that could drift.
+ *
+ * Atomicity: the file backend is single-process (the `FileStorageBackend` boot lock guarantees ONE writer per
+ * data dir), and `getRules`/`putRules` read-check-write SYNCHRONOUSLY (no await between the rev read and the
+ * atomic write), so the read-modify-write is atomic in the one event loop — exactly the InMemory store's premise.
+ * Cross-process CORRECT concurrency is the Pg/TiDB backend's job (a CAS WHERE clause), by design.
+ */
+/** Coordinates of one corrupt-treated-as-absent policy read (the {@link FileSessionPolicyStoreOptions.onCorruptRead}
+ *  payload). Named rather than inline so the backend option that forwards it names the SAME shape. */
 export interface SessionPolicyCorruptReadInfo {
+    /** The session whose read observed the corrupt row. On the enumeration face this is the session being
+     *  ENUMERATED — a corrupt row's own `__sid` is by definition unreadable, so it cannot be attributed. */
     sessionId: string;
+    /** Present only when the read was keyed by a principal (the enumeration face has none). */
     principal?: string;
+    /** Absolute path of the offending file. */
     path: string;
+    /** Which corruption grade was observed (unparseable / bad shape / unreadable). */
     reason: string;
 }
 export interface FileSessionPolicyStoreOptions {
+    /** Disclosure sink for the corrupt-read fail-open (see {@link FileSessionPolicyStore.discloseCorrupt}).
+     *  Never fires on plain ENOENT. Swallow-guarded: a throwing sink cannot re-introduce the fault. */
     onCorruptRead?: (info: SessionPolicyCorruptReadInfo) => void;
 }
 export declare class FileSessionPolicyStore implements SessionPolicyStore {
     private readonly dir;
     private readonly onCorruptRead;
     constructor(root: string, opts?: FileSessionPolicyStoreOptions);
+    /** The one delivery point for {@link onCorruptRead}. Swallow-guarded here so no caller has to remember. */
     private disclose;
+    /** RB-482 top item (baggage class-4 ruling): corrupt-read fail-open is a DOCUMENTED compromise (a throwing
+     *  getRules fails the whole task; a throwing putRules self-locks the repair write) — but it must not
+     *  be a SILENT one: a deployment whose policy file was corrupted was getting an apparently normal
+     *  UNCONSTRAINED task with zero signal. Every corrupt-treated-as-absent branch discloses here
+     *  (swallow-guarded; never on a plain ENOENT, which really is absence). */
     private discloseCorrupt;
+    /** `(sessionId, principal)` → a safe, INJECTIVE filename (sanitizeScope appends the full sha256 of the raw
+     *  composite key, so distinct keys never collide on disk). */
     private pathFor;
     private read;
     getRules(sessionId: string, principal?: string): Promise<StoredSessionRules | null>;

package/dist/stores/file/session-store.d.ts

@@ -1,5 +1,18 @@
 import type { Session, SessionForkOptions, SessionMetadata, SessionRepo, SessionTreeEntry } from "../../internal/harness.js";
 export interface FileSessionRepoOptions {
+    /**
+     * Disclosure sink for a durable read this repo treats as ABSENT (ruled 2026-08-03). Same name and
+     * same `{path, reason}` shape as the sibling file stores' seat — "unreadable read as missing" and
+     * "corrupt read as missing" are one failure grammar, so they get one seat name.
+     *
+     * Fires for: an unreadable sessions DIRECTORY (the listing degrades to "no sessions"), a session log
+     * that could not be replayed during a listing (skipped from the result), and a corrupt interior JSONL
+     * record dropped on replay (turns silently missing from an otherwise healthy session).
+     *
+     * Never fires on plain ENOENT / `not_found` — that is honest absence, and the torn TAIL stays silent
+     * too (dying mid-write is the append log's documented crash-recovery shape, not corruption).
+     * Swallow-guarded: a throwing sink cannot re-introduce the fault the fail-open avoids.
+     */
     onCorruptRead?: (info: {
         path: string;
         reason: string;
@@ -9,12 +22,30 @@ export declare class FileSessionRepo implements SessionRepo {
     private readonly dir;
     private readonly tmpDir;
     private readonly onCorruptRead;
+    /** RB-437 — the shared authorities THIS repo has joined, weakly (canonical key → the joined storage).
+     *  `dispose()` walks it and releases each holder share; the weak value is what makes the identity
+     *  check on the way out possible without pinning a storage the table itself only holds weakly. */
     private readonly joined;
     constructor(root: string, opts?: FileSessionRepoOptions);
+    /** The one delivery point for {@link FileSessionRepoOptions.onCorruptRead}; swallow-guarded here so
+     *  no call site has to remember. */
     private disclose;
     private pathFor;
+    /** Read + torn-tail-recover a session file into (meta, entries); a missing file → not_found. */
     private read;
     private storage;
+    /**
+     * RB-437 — release every shared authority this repo joined (LAST holder ⇒ evict + close the append fd).
+     *
+     * This is the lifecycle-tied half of the eviction rule the four file-REPLACING operations already
+     * cover: after it, a NEW repo/backend over the same root replays each session from disk instead of
+     * serving this process's pre-dispose in-memory leaf, and a Session handle held across the teardown
+     * is refused with `code=log_closed` rather than writing onto a data root the process has released.
+     *
+     * Idempotent; safe to call on a repo that never opened anything. A repo whose authority was replaced
+     * meanwhile (delete/fork/import/create-over-absent) releases NOTHING for that key — the identity check
+     * means a stale holder can never revoke the rebuilt entry.
+     */
     dispose(): Promise<void>;
     create(options?: {
         id?: string;
@@ -23,7 +54,16 @@ export declare class FileSessionRepo implements SessionRepo {
     list(): Promise<SessionMetadata[]>;
     delete(metadata: SessionMetadata): Promise<void>;
     fork(sourceMetadata: SessionMetadata, options?: SessionForkOptions): Promise<Session>;
+    /** 2c session-sync ([275], the FILE half of [266]②): the FULL oldest-first log for export. The file backend
+     *  has NO F3 floor — `read` returns EVERY persisted entry (`id`/`parentId` verbatim) — so this is the complete
+     *  log, BYPASSing any bounded tail (matches `InMemorySessionRepo.exportEntries`). Missing file → not_found. */
     exportEntries(sessionId: string): Promise<SessionTreeEntry[]>;
+    /** 2c session-sync ([275]): import a verbatim log into `sessionId`. The single fail-closed invariant gate runs
+     *  FIRST ({@link validateEntriesForImport}); `owner` is a durable multi-tenant concept the local file backend
+     *  has no field for (accepted, unused — same as `InMemorySessionRepo`). Writes the WHOLE file (meta + entries)
+     *  atomically via tmp→fsync→rename — the rename is the commit point, so a crash leaves either nothing or an
+     *  orphan temp, never a partially-imported session (mirrors `fork`). An existing session is REPLACED (the
+     *  orchestrator's importSession owns the already-exists policy, same as InMemory's overwrite). */
     importEntries(sessionId: string, owner: string | undefined, entries: SessionTreeEntry[], options?: {
         preserveActorAssertions?: boolean;
     }): Promise<void>;

package/dist/stores/file/shared-ledger.d.ts

@@ -1,35 +1,118 @@
+/**
+ * design/157 A9 — the SHARED substrate under the three snapshot+ledger file stores
+ * ({@link import("./background-agent-store.js").FileBackgroundAgentStore},
+ * {@link import("./checkpoint-store.js").FileCheckpointStore},
+ * {@link import("./workflow-run-store.js").FileWorkflowRunStore}).
+ *
+ * Each of them carried its own copy of the SAME three mechanisms: a per-directory refcounted
+ * authority table, the snapshot+ledger replay/commit skeleton, and `compact()`'s
+ * close → rewrite → reopen swap. What stays in the stores is what genuinely differs — the ledger
+ * EVENT model (`applyEvent`) and the domain predicates (CAS / reap / query projections). The stores
+ * COMPOSE this (they hold a {@link LedgerCore}); nothing here is inherited or subclassed.
+ *
+ * ── CLASS-FIX LEDGER ────────────────────────────────────────────────────────────────────────────
+ * Every entry below was first fixed on ONE file and then had to be re-fixed on the siblings, some of
+ * them twice. They now live here once, and the old addresses are named so the考据 is not lost with
+ * the code that carried it:
+ *
+ *  · **RB-55 / RB-59 / RB-134 — one authority per DIRECTORY, not per instance.** Two stores over one
+ *    directory each replayed a PRIVATE view, so two concurrent same-rev CASes BOTH won: a double
+ *    claim (background-agent, RB-55), a double-won run update (workflow-run, RB-59 — the 1.408.0
+ *    sweep covered the agent store and not this one, whose cross-instance test only exercised `put`),
+ *    and a human approval consumed twice (checkpoint, RB-134, in the file whose own header calls
+ *    itself "THE LOAD-BEARING file store"). Now: {@link SharedLedgerTable}.
+ *  · **RB-144 — the table KEY is `canonicalStoreKey` (realpath + case fold).** Three stores were
+ *    still keying on a lexical `resolve()` while two of them cited the mailbox as the precedent they
+ *    copied. Now one call site, in {@link SharedLedgerTable.acquire}.
+ *  · **RB-145 — `close()` is IDEMPOTENT per INSTANCE; the refcount belongs to the DIRECTORY.** A
+ *    second `close()` on the same object used to decrement again and tear the shared log out from
+ *    under a live sibling — `log_closed` on its every later write. The per-instance latch stays in
+ *    each store (it is per-object state); the refcount, the identity-checked eviction and the fd
+ *    teardown are {@link LedgerCore.release}.
+ *  · **RB-149 / RB-167 — the compaction swap must be `closeForSwap()`, never `close()`.** `close()`
+ *    means "finished", so a failed rewrite left the log permanently unusable — one transient I/O
+ *    fault bricking every instance on that directory. The mailbox's `finally { new AppendLog(path) }`
+ *    compensation was the closest of the four and still wrong twice: it does not cover an unwritable
+ *    FILE (the reopen throws too), and its reopen error REPLACES the fault that caused the swap. The
+ *    answer is AppendLog's lazy reopen — {@link LedgerCore.compact}.
+ *  · **RB-150 / RB-167 — compaction is HOUSEKEEPING.** It runs after the operation is durable AND
+ *    applied, so its failure must never be reported as the operation's failure: a committed
+ *    once-only CAS surfaced as "this did not happen" is the worst possible direction (the caller
+ *    retries, hits the new rev, and fails again — one success reported as two failures). The swallow
+ *    is safe ONLY because of the lazy reopen above — {@link LedgerCore.commit}.
+ *
+ * DELIBERATELY NOT FOLDED IN: `mailbox-store.ts` (refcount is per-BOX with a per-instance dedup, and
+ * its compaction rewrites the LIVE log as a replay-equivalent event stream instead of a separate
+ * snapshot) and `workflow-journal-store.ts` (one ledger per RUN, no snapshot, no row map). Their
+ * tables are the same SHAPE, not the same MECHANISM; both keep their own, with a pointer to this
+ * ledger for the shared half of the history.
+ */
+/** The paths one ledger authority owns. `dir` is also what the authority is keyed on. */
 export interface LedgerPaths {
     readonly dir: string;
+    /** Scratch dir for {@link atomicWriteFile} (same filesystem as the targets → rename is atomic). */
     readonly tmpDir: string;
     readonly ledgerPath: string;
     readonly snapshotPath: string;
 }
+/** The per-store half: how a SNAPSHOT row is keyed, and how one LEDGER event folds into the map. */
 export interface LedgerModel<Row, Ev> {
     keyOf(row: Row): string;
     apply(rows: Map<string, Row>, ev: Ev): void;
 }
+/**
+ * One directory's authority: the replayed row map, the per-key async mutex, the append log and the
+ * event counter. Created and owned by {@link SharedLedgerTable}; every store instance over the
+ * directory holds a reference to the SAME object.
+ */
 export declare class LedgerCore<Row, Ev> {
     private readonly key;
     private readonly paths;
     private readonly model;
     private readonly table;
+    /** The authoritative replayed state — domain queries read it directly. */
     readonly rows: Map<string, Row>;
+    /** How many store instances hold this authority (RB-145: it belongs to the directory). */
     refs: number;
     private readonly locks;
     private events;
     private handle;
     constructor(key: string, paths: LedgerPaths, model: LedgerModel<Row, Ev>, table: Map<string, LedgerCore<Row, Ev>>);
+    /** Rebuild the authority: the snapshot (the compacted base) first, then the live ledger's events in
+     *  order (last-writer-wins), then open the append handle. Only the FIRST instance runs it. */
     bootstrap(): void;
+    /**
+     * Serialize an op behind any in-flight op on the same key — the in-process per-key async mutex (the
+     * SAME `Map<key, Promise>` chain shape as `TtlSessionStore.pending`). Each call appends a new tail;
+     * the next caller awaits THIS op before running. A prior op's rejection never blocks the chain (we
+     * await it `.catch`-guarded). The entry is pruned once it is the settled tail with nothing queued.
+     */
     withLock<T>(key: string, fn: () => Promise<T> | T): Promise<T>;
+    /**
+     * Commit one ledger event: fsync'd append FIRST, in-memory flip AFTER — so a crash can never leave
+     * memory and disk disagreeing. Then the best-effort housekeeping compaction (RB-150/RB-167).
+     */
     commit(ev: Ev, fsync: boolean, compactEvery: number): void;
+    /** Rewrite the snapshot from the authoritative map (atomic) and truncate the live ledger. After
+     *  this a replay reads the whole state from the snapshot alone — the round-trip is identical. */
     compact(): void;
+    /** Drop one instance's share. The LAST holder evicts the authority — identity-checked, so a stale
+     *  holder can never revoke a REBUILT entry — and closes the append fd. */
     release(): void;
+    /** Test/inspection: events appended since the last compaction. */
     get pendingEvents(): number;
     private get log();
 }
+/**
+ * The module-level authority table one store family keeps: ONE entry per canonical directory, with
+ * eviction (RB-134 — a table without invalidation is RB-73's mistake again: after a `close()` the
+ * next store over that root would join a table whose log was already closed and every write would
+ * throw `log_closed`, instead of replaying the on-disk truth into a fresh authority).
+ */
 export declare class SharedLedgerTable<Row, Ev> {
     private readonly model;
     private readonly live;
     constructor(model: LedgerModel<Row, Ev>);
+    /** Join the live authority for this directory, or create + replay a fresh one. */
     acquire(paths: LedgerPaths): LedgerCore<Row, Ev>;
 }

package/dist/stores/file/tool-result-store.d.ts

@@ -1,4 +1,15 @@
 import type { ToolResultSlice, ToolResultStore } from "../../core/tool-result-store.js";
+/**
+ * design/80 §2.5 — file {@link ToolResultStore}: write-once-idempotent, ONE file per ref.
+ *
+ * `ref = tr_<sessionId>_<toolCallId>` (engine-minted, already globally unique). `put` is an
+ * `O_CREAT|O_EXCL` create (`"wx"`) → on `EEXIST` it SILENTLY no-ops (write-once-idempotent; never
+ * re-writes — a re-write risks a non-identical preview and breaks the prompt cache, §2.5 / the in-memory
+ * store's `if (!map.has(ref))`). Content is fsync'd before return. `get` slices the file by `{offset,
+ * limit}` over CHARS to match `ToolResultSlice.totalChars` semantics; an unknown ref → `undefined` (the
+ * model is told it's gone — degrades, never crashes). `withToolResultOffload` joins text with `\n` and
+ * stores the joined string verbatim, so the char-offset slice here is exactly the in-memory store's slice.
+ */
 export declare class FileToolResultStore implements ToolResultStore {
     private readonly dir;
     constructor(root: string);

package/dist/stores/file/usage-window-store.d.ts

@@ -1,7 +1,25 @@
 import { type UsageWindow, type UsageWindowReading, type UsageWindowStore } from "../../core/usage-window-store.js";
+/**
+ * design/164 件五 — file-backed {@link UsageWindowStore}: ONE JSON record per governed key, semantics
+ * identical to `InMemoryUsageWindowStore` BY CONSTRUCTION (both are shells around the same pure
+ * `chargeUsageRecord` / `readUsageRecord`; neither re-implements window arithmetic).
+ *
+ * Atomicity: the file backend is single-process (the `FileStorageBackend` boot lock guarantees ONE writer
+ * per data dir) and `charge` reads-modifies-writes SYNCHRONOUSLY (no await between the read and the
+ * atomic replace), so the update is atomic within the one event loop — the in-memory store's premise.
+ * Cross-process governance belongs to a database backend with a real transaction.
+ *
+ * **Corrupt records FAIL CLOSED** — deliberately the OPPOSITE of `FileSessionPolicyStore`'s fail-open. A
+ * policy file is a DENY list, where absence is the safe direction; a usage window is a CEILING, where
+ * absence is the unsafe direction: treating an unreadable ledger as "no usage yet" would hand the key an
+ * unlimited, silent allowance — precisely what the operator wired this to prevent. A corrupt record
+ * therefore refuses with `usage_window.store_corrupt` until it is repaired or removed.
+ */
 export declare class FileUsageWindowStore implements UsageWindowStore {
     private readonly dir;
     constructor(root: string);
+    /** key → a safe, INJECTIVE filename (`sanitizeScope` appends the full sha256 of the raw key, so two
+     *  distinct principals can never share a ledger file). */
     private pathFor;
     private loadRecord;
     charge(key: string, tokens: number, at: number, windows: readonly UsageWindow[]): Promise<void>;