@sema-agent/core 5.19.0 → 5.21.0

package/dist/core/memory-engine/file-backend.d.ts

@@ -1,56 +1,211 @@
 import { scopeDirName, type MemoryPartitionIncidentSink } from "./layout.js";
 import type { HarvestRejection, MemoryBackend, MemoryEntry, MemoryEntryHeader, NotePatch, PatchReport, ScoredMemoryEntry } from "./types.js";
+/** Files/dirs the entry scan never treats as entries: the derived index, dotfiles (`.hydrate`,
+ *  transaction staging files), and anything not `.md`. */
 export declare const MEMORY_INDEX_FILENAME = "MEMORY.md";
+/** Default nesting depth cap under a scope dir (CC memory is flat; a small allowance for topic dirs). */
 export declare const DEFAULT_MAX_ENTRY_DEPTH = 3;
+/** One on-disk entry file the scan found. */
 export interface ScannedEntryFile {
+    /** Absolute path. */
     path: string;
+    /** Slug = path relative to the scope dir, without `.md` (may contain `/` for nested topics). */
     slug: string;
 }
+/**
+ * Enumerate a scope dir's entry files (depth-capped, symlinks skipped, dotfiles/index/non-`.md`
+ * ignored, `exclude` dirs — sibling scope homes under the root — skipped). Shared by the backend
+ * and the engine's harvest scan so the two can never disagree on what counts as an entry file.
+ */
 export declare function scanEntryFiles(dir: string, opts?: {
     maxDepth?: number;
     exclude?: ReadonlySet<string>;
+    /** Harvest gate hook: called for every path the scan SKIPS, with why (backend scans ignore it). */
     onSkip?: (path: string, kind: "symlink" | "depth" | "nonmd" | "dotfile" | "unreadable") => void;
 }): ScannedEntryFile[];
+/** Construction options for {@link FileMemoryEngineBackend}. */
 export interface FileMemoryEngineBackendOptions {
+    /** ⚠️ 分家坑(service 报告 2026-07-09):不显式传时,控制平面按无参 `resolveMemoryEngineRoot()`
+     *  派生(env/默认 config 根)——若你的记忆目录带自定义根,控制面会与记忆目录分家。自建 backend 的
+     *  consumer 应显式钉本字段(engine 同参)。 */
     controlDir?: string;
+    /** 注入时钟(determinism,engine 同款);默认 `Date.now`。 */
     now?: () => number;
+    /**
+     * Where mount-time partition-key incidents go. The migration probes promise "never silent", and a
+     * self-constructed backend has no other channel to keep that promise on — the runner-assembled path
+     * bridges its own sink into `RunnerDeps.onError`, and without this seat the identical incident was
+     * unobservable here. Absent ⇒ the probe stays silent (it is advisory; a mount never fails over it).
+     */
     onIncident?: MemoryPartitionIncidentSink;
 }
+/**
+ * ⚠️ DEPLOYMENT BOUNDARY (N0 定谳,channel 给service-AI.md [412],2026-07-09):this backend — and the
+ * file memory engine's materialize/harvest — operates on the WORKER-HOST fs plane (node:fs), matching
+ * CC's `~/.claude` host-plane memory (the only behavior anchor). It is NOT ExecutionEnv-aware: when a
+ * deployment routes the model's file tools to a REMOTE sandbox (e2b/k8s/ssh/adb/local-docker), the two
+ * planes do not intersect — the model cannot see the memory dir and harvest cannot see sandbox writes.
+ * Remote-hands deployments MUST gate the engine off for non-host lanes (reference: service
+ * `memoryEngineBackendFor` lane gate, fail-closed + `MEMORY_ENGINE_REMOTE_LANE=allow` override for
+ * lanes that genuinely share the worker fs, e.g. ssh+NFS). A future "remote-memory-materialize" design
+ * (ExecutionEnv-seam placement/harvest with sandbox-lifecycle contracts) is demand-triggered — do not
+ * bolt it on here.
+ */
 export declare class FileMemoryEngineBackend implements MemoryBackend {
+    /** The repo-level memory dir this backend is the authority for (engine reads it for zero-copy). */
     readonly directoryRoot: string;
+    /** B3 — the engine control plane home (ledger/scopes/shadow/quarantine/journal). Model-invisible:
+     *  NEVER under {@link directoryRoot}, always on the config-root side even for an in-repo memory dir.
+     *  The engine picks this up (like `directoryRoot`) so both sides share ONE control plane. */
     readonly controlPlaneRoot: string;
+    /** Injected clock (opus 1.258 LOW: match the engine's `this.now` determinism discipline). */
     private readonly now;
+    /**
+     * The COMMITTED-rev ledger (`revs.json`, id → rev). Zero-copy makes it load-bearing for CAS: the
+     * entry files are the SAME files the session edits, so "read the current rev from the file" would
+     * make every legitimate update self-conflict (the file already holds the new content). The ledger
+     * records the rev as of the last COMMIT (applyPatches) — a CAS compares against IT, so an in-session
+     * edit passes (baseRev == ledger) while a concurrently-committed change conflicts (ledger advanced).
+     * Read-side (`listHeaders`/`getByIds`/`search`) SYNCS the ledger to disk THROUGH the inbound gate
+     * (B2 — out-of-session edits, e.g. a git pull into an in-repo memory dir, are secret/cap-scanned;
+     * rejects are quarantined + shadow-restored, never adopted); the applyPatches lookup does NOT sync
+     * (that would erase the very baseline CAS needs). B3: corrupt ⇒ {@link ControlPlaneCorruptError}
+     * (fail-closed), never a silent empty-ledger downgrade.
+     */
     private ledger;
+    /** B2 — inbound-gate findings accumulated by read-side syncs; the engine drains them into
+     *  `HarvestReport.inboundFindings` at harvest. */
     private inboundFindings;
+    /** Batch-planning scan memo (applyPatchesLocked only): planning reads pre-batch disk exclusively,
+     *  so one `readScope(scope, false)` per scope serves every patch of the batch. Set for the planning
+     *  loop, cleared before EXECUTE mutates the disk. Never caches `sync:true` reads. */
     private batchScan;
     constructor(dir: string, opts?: FileMemoryEngineBackendOptions);
+    /** B3 fail-closed preflight (engine harvest duck-types this): force-reload every load-bearing
+     *  sidecar from disk; throws {@link ControlPlaneCorruptError} when one is corrupt. Also completes
+     *  any interrupted transaction (H4 recovery). */
     checkControlPlane(): void;
+    /** B2 — drain the accumulated inbound-gate findings (engine harvest reporting). */
     drainInboundFindings(): HarvestRejection[];
+    /** B1 — read an entry's COMMITTED content copy from the control-plane shadow (undefined = none).
+     *  The engine's missing-file recovery reads this (zero-copy: a deleted file is gone from the
+     *  directory scan, so the shadow is the only committed copy left). */
     readCommittedShadow(id: string): string | undefined;
     private shadowPath;
     private loadLedger;
+    /** B3: atomic + fail-closed — a ledger that cannot be persisted throws (the commit is incomplete
+     *  and the caller must know), never a silent swallow. */
     private saveLedger;
+    /**
+     * @param opts.unlocked RB-447 (2026-07-31, hardening review) — set by the two callers that run
+     * WITHOUT the txn mutex (the constructor and {@link checkControlPlane}). `applyPatches` serializes
+     * reload→plan→journal→execute→ledger behind a cross-process lock precisely because two writers over
+     * one root would otherwise interleave; these two ran the recovery and the staged sweep with no lock
+     * at all, and both are DESTRUCTIVE. A second process merely CONSTRUCTING a backend on the same
+     * memory dir — which happens at every task start — while process A sat between STAGE and EXECUTE
+     * removed A's `.stage-*` tmps, so A's `renameSync(op.staged, op.target)` threw ENOENT and the engine
+     * converted a healthy transaction into a `sidecar_corrupt` incident. Dropping A's journal has the
+     * worse shape: if A then crashed, its roll-forward record is gone.
+     *
+     * The gate is the txn mutex ITSELF, not a heuristic: an unlocked caller stands down only while
+     * someone else is holding a LIVE lock (present and not past its stale line), because that is
+     * precisely the window in which the journal and the `.stage-*` files belong to a transaction in
+     * flight. With no live holder — a genuine crash, or the ordinary cold start these two callers were
+     * written for — recovery and the sweep run exactly as before, so the documented "a crash is rolled
+     * forward/back on the next construction" behavior is unchanged. A live holder's own transaction
+     * finishes its journal itself; if that holder dies, the lock goes stale and the next construction or
+     * the next locked `applyPatches` recovers it. Nothing is deferred indefinitely.
+     */
     private recoverJournal;
+    /** RB-447 — is another writer mid-transaction right now? True while the txn lock dir exists and is
+     *  not past its stale line (a stale lock is a crashed holder: its artifacts ARE ours to recover).
+     *  Only consulted by the two UNLOCKED callers — inside `applyPatches` the lock is ours by
+     *  construction. Cheap: one `stat` on the lock dir, no lock acquisition, never blocks. */
     private txnInFlight;
+    /** Remove orphaned `.stage-*` files (a crash BEFORE the journal rename = clean rollback: nothing
+     *  was committed, the staged tmps are litter). Dotfiles are invisible to entry scans regardless. */
     private sweepStagedFiles;
+    /** The names of sibling scope subdirs to exclude when scanning the ROOT scope's own nested content. */
     private excludedSubdirNames;
     private scopeDir;
+    /** B2 inbound gate for content that did NOT come through applyPatches (git pull / hand edits /
+     *  a hand-seeded file): secret + cap + structure. Returns the rejection, or undefined (clean). */
     private inboundGate;
+    /** Read every COMMITTED entry of `scope` — a file must carry a valid `id:` to count. An id-less
+     *  file is UNCOMMITTED session material: it becomes an entry only through the engine's harvest
+     *  gates (which mint the id on commit). Reading it as an entry here would let gate-rejected files
+     *  (secret / cap / quarantine) leak into the authoritative set through the zero-copy disk scan.
+     *  `sync` (read-side callers) adopts a committed file's CURRENT disk rev into the committed-rev
+     *  ledger ONLY through the inbound gate (B2: out-of-session edits, e.g. git-pull, are scanned;
+     *  a reject is moved to control-plane quarantine and the committed shadow content is restored to
+     *  disk). The applyPatches lookup passes false (the ledger must keep the baseline for CAS). */
     private readScope;
     listHeaders(scopes: readonly string[]): Promise<MemoryEntryHeader[]>;
     private listHeadersWith;
     getByIds(ids: readonly string[]): Promise<MemoryEntry[]>;
     private getByIdsWith;
+    /**
+     * design/178 §3 (ruled 2026-08-08) — a SIDE-EFFECT-FREE projection of this backend for the session's
+     * RETRIEVAL face (`memory_search` / `memory_get`).
+     *
+     * The ordinary read path carries the inbound-adoption channel: a disk revision that disagrees with
+     * the ledger is judged an out-of-session change, gated, and — when it passes — adopted as the new
+     * COMMITTED baseline (ledger + shadow rewritten). That is a deliberate lifecycle synchronization
+     * point, and it belongs to the engine's own moments (materialize / harvest), not to every model
+     * lookup: a retrieval landing between them would otherwise COMMIT the session's own in-flight edits
+     * with no harvest gate and no pollution discipline in the way. Reads through this view resolve
+     * entries from disk without touching the ledger, the shadow, or the quarantine.
+     *
+     * Not running the inbound gate on this path is the point, not a concession: the view reports what
+     * is on the plane, and admitting anything stays the harvest's job.
+     *
+     * WRITES ARE REFUSED, loudly — a view handed to a write path is a defect, not a fallback.
+     */
     retrievalView(): MemoryBackend;
+    /** Lexical floor (design/138 §2.1): `1 - Jaccard` distance over name+description+body, ascending. */
     search(query: string, scopes: readonly string[], opts?: {
         limit?: number;
     }): Promise<ScoredMemoryEntry[]>;
     private searchWith;
+    /**
+     * H4 — the entry transaction, staged and journaled:
+     *  1. RELOAD the ledger from disk (验收 M2: a concurrently-committed transaction from another
+     *     process becomes a CAS conflict here, never a blind write over it) + finish any interrupted
+     *     transaction (redo journal).
+     *  2. PLAN every patch against current state (CAS/conflicts decided now; no disk writes yet).
+     *  3. STAGE: write each new file content to a same-directory `.stage-*` tmp (fsync'd).
+     *  4. JOURNAL: atomically write the full redo log (ops with content + the post-txn ledger snapshot).
+     *     ← the commit point: a crash after this rolls FORWARD (recovery redoes the journal); a crash
+     *     before it rolls BACK (staged tmps are swept, nothing was committed).
+     *  5. EXECUTE: atomic renames / deletes / shadow updates.
+     *  6. Persist the ledger (atomic, fail-closed) and drop the journal.
+     */
     applyPatches(patches: readonly NotePatch[]): Promise<PatchReport>;
     private txnLockDir;
+    /**
+     * 对抗复审 L1/L2/L3 — the mkdir mutex, hardened (same shape as layout.ts' acquireSidecarLock, but
+     * fail-closed timings and an async wait):
+     *  - L2: every acquisition writes an OWNER TOKEN (`<lock>/owner`, crypto-random — never a
+     *    timestamp) immediately after mkdir. Release only removes the lock while the token is still
+     *    ours; {@link assertTxnLockOwnership} re-verifies it at the commit point.
+     *  - L1: the stale steal is SINGLE-WINNER — atomic rename of the stale lock dir to a unique
+     *    tombstone (exactly one racer's rename succeeds; losers ENOENT back into the wait loop), then
+     *    the winner removes the tombstone and re-acquires through a NORMAL mkdir. Never a bare
+     *    rmSync+mkdir (two same-window stealers would force-rm each other's FRESH lock = double hold).
+     *  - L2 (steal side): only a lock that is BOTH past its stale line AND carries an owner token is
+     *    stealable (a tokenless dir is a mid-acquisition, not a crashed holder).
+     *  - L3: the wait deadline is `max(waitMs, observed lock's stale line + grace)` — a holder that
+     *    crashed with `remaining stale > waitMs` no longer strands every waiter in an all-throw window.
+     */
     private acquireTxnLock;
+    /** 对抗复审 L2 — 提交点归属复验: called immediately before the JOURNAL write (the persistent commit
+     *  point). A holder that stalled past the stale deadline (slow disk / GC pause / long txn) and was
+     *  stolen from must ABORT — its staged tmps carry no committed state and the stealer's journal
+     *  recovery is now authoritative; committing anyway would overwrite the stealer's transaction. */
     private assertTxnLockOwnership;
     private applyPatchesLocked;
+    /** Plan one patch: decide CAS/conflicts against CURRENT state, emit journal ops (no entry-file
+     *  writes here — staging/execution happen in {@link applyPatches}). */
     private planOne;
     private locateById;
     getConsolidationCursor(scope: string): Promise<string | undefined>;

package/dist/core/memory-engine/frontmatter.d.ts

@@ -1,12 +1,28 @@
 import type { MemoryEntry, MemoryEntryFrontmatter } from "./types.js";
+/** A parsed entry file: frontmatter (may be absent — CC allows bare files; harvest mints them) + body. */
 export interface ParsedEntryFile {
+    /** The hidden immutable id (`id:` frontmatter line), when present. */
     id?: string;
     frontmatter: MemoryEntryFrontmatter;
     body: string;
+    /** True when the file had a well-formed `---` frontmatter block at all. */
     hadFrontmatter: boolean;
 }
+/** The id-shape contract, shared with the WRITE path (KNOWN-ISSUES 幽灵行加固): the File backend's
+ *  applyPatches refuses any patch whose id this rejects — such an entry would be applied + ledgered,
+ *  yet THIS parser drops the id on read (a fresh one gets minted), leaving the file on disk but the
+ *  id permanently invisible. Read gate and write gate must stay one predicate. */
 export declare function isValidEntryId(value: string): boolean;
+/** Parse one memory file's text into frontmatter + body. Never throws — an unfenced file is all-body. */
 export declare function parseEntryFile(text: string): ParsedEntryFile;
+/** Serialize an entry to its canonical file projection (id FIRST — the hidden immutable field). */
 export declare function serializeEntryFile(entry: Pick<MemoryEntry, "id" | "frontmatter" | "body">): string;
+/**
+ * Content-hash rev (the CAS baseline). Computed over the SEMANTIC content — id, structured
+ * frontmatter fields, preserved extra lines, and body — via a canonical JSON tuple, NOT raw file
+ * bytes: engine (parsing disk files) and backend (storing entries) must agree on the rev regardless
+ * of incidental serialization formatting, or every materialize would see a phantom diff.
+ */
 export declare function computeEntryRev(entry: Pick<MemoryEntry, "id" | "frontmatter" | "body">): string;
+/** Parse a file's text directly into a full MemoryEntry (id must already be present/decided). */
 export declare function entryFromFile(text: string, id: string, slug: string, scope: string): MemoryEntry;

package/dist/core/memory-engine/layout.d.ts

@@ -1,79 +1,296 @@
 import type { MemoryAnnouncement } from "./types.js";
+/** Cursor sidecar for the design/84 Seam B pair on the FileBackend (`{ [scope]: cursor }`). B3: control plane. */
 export declare const CURSORS_FILE = "cursors.json";
+/** The control-plane subdir name under a key dir — ONE spelling for every derivation and for the
+ *  migration probes that move a control plane between key dirs. Exported for the sibling planes
+ *  (dual-root's personal plane) so no second literal exists; not part of the package surface. */
 export declare const CONTROL_PLANE_DIR = ".engine";
+/** B3 fail-closed: a control-plane sidecar exists but cannot be trusted (unparseable / wrong shape).
+ *  Read paths propagate it (materialize fails ⇒ the runner falls open to a memory-less session with
+ *  onError); harvest converts it into a refused report (incident `sidecar_corrupt`). It is NEVER
+ *  silently degraded to an empty ledger / unclaimed root — that would let a corrupted (or truncated)
+ *  sidecar erase CAS baselines and re-open the root claim. */
 export declare class ControlPlaneCorruptError extends Error {
     constructor(message: string, opts?: {
         cause?: unknown;
     });
 }
+/**
+ * CC-style repo PARTITION key: the repo root path, canonicalized, then slugged. Collisions across
+ * repos require pathological sibling names and only merge their memory dirs (never corrupt them).
+ *
+ * RB-472 (design/161, four-repo receipts on record): the key CANONICALIZES first — without
+ * realpath, the same repo reached through a symlink alias and through its physical path minted two
+ * different partition keys = two memory dirs, silently splitting memory. `canonicalize` degrades to
+ * plain resolve semantics for a not-yet-existing path (nearest existing ancestor + remainder).
+ * Its input is the HOST-declared repo root; a model-reachable directory is keyed by
+ * {@link deriveDirKey} instead, and that asymmetry is deliberate (see there).
+ *
+ * Known limit, registered rather than fixed (ruled 2026-08-03): on a case-INSENSITIVE volume two
+ * spellings that differ only in case still mint two keys — realpath does not case-fold, and folding
+ * here would MERGE two genuinely distinct repos on a case-SENSITIVE volume. This round closes the
+ * symlink axis only; the case axis predates it and is unchanged.
+ */
 export declare function deriveRepoKey(repoRoot: string): string;
+/** Sink for the mount-time partition-key incidents (`memory.partition_split` /
+ *  `memory.partition_adopt_failed`). ONE shape for every host that can receive them — the runner's
+ *  onError bridge, the engine, and the file backend. */
 export type MemoryPartitionIncidentSink = (err: Error & {
     code?: string;
 }) => void;
+/** RB-472 adoption leg: a pre-5.x deployment keyed its repo partition by the resolve-only path, so
+ *  when the two mints differ its `memory/` + `.engine/` + siblings live under {@link deriveDirKey}'s
+ *  dir. Move the whole partition onto the canonical key (see {@link migrateKeyedPartition}). */
 export declare function adoptLegacyRepoDirs(configRoot: string, repoRoot: string, onIncident?: MemoryPartitionIncidentSink): void;
+/**
+ * The REVERSE one-shot migration (ruled 2026-08-03): for the width of ONE release the control-plane
+ * key canonicalized like the repo key does, which put a directory-pinned mount's `.engine` under the
+ * canonical key. {@link deriveDirKey} is the control-plane mint again (that ruling's security half),
+ * so such a control plane sits at an address this build no longer reads — move it back, once.
+ *
+ * Scoped to the `.engine` subtree on purpose: the canonical-key dir may host unrelated siblings.
+ *
+ * Known limit, registered rather than fixed: when the SAME physical directory is ALSO mounted under
+ * its physical spelling, that mount's own resolve-keyed plane IS this migration's source dir, and the
+ * probe cannot tell the two apart (both are `<key>/.engine`). Concurrently mounting one directory
+ * under two spellings is outside what this probe can discriminate; the window it recovers from is one
+ * release wide.
+ */
 export declare function adoptCanonicalKeyedControlDir(configRoot: string, dir: string, onIncident?: MemoryPartitionIncidentSink): void;
+/**
+ * `<configRoot>/<repoKey>/memory` — the repo-level stable mount (§2.7: taskRoot 外, worktree-shared).
+ *
+ * Worktree note (验收 L5, documented behavior): the KEY must be the BASE repo root. The runner passes
+ * `deps.rootPath ?? taskRootPath` — when `rootPath` is configured, every derived worktree of that repo
+ * shares ONE memory dir (a worktree moves the task cwd, never the memory mount); when `rootPath` is
+ * NOT configured the taskRootPath fallback keys memory to the task's own checkout path, so an
+ * isolated-worktree task without `rootPath` gets a worktree-private memory dir. That fallback is the
+ * accepted degraded behavior (no silent cross-repo mixing; configure `rootPath` for worktree sharing).
+ */
 export declare function deriveRepoMemoryDir(configRoot: string, repoRoot: string): string;
+/** design/142 §1.5 — the IDENTITY-keyed mount (v2 scope contract + a resolved project marker):
+ *  `<configRoot>/proj-<projectId>/memory`. Unlike the path-derived {@link deriveRepoMemoryDir},
+ *  this key survives rename/move/re-clone/container remounts — identity lives in the repo's marker,
+ *  the mount stops referencing the path entirely. */
 export declare function deriveProjectMemoryDir(configRoot: string, projectId: string): string;
+/** Control-plane sibling of {@link deriveProjectMemoryDir} (B3: always on the config-root side). */
 export declare function deriveProjectControlDir(configRoot: string, projectId: string): string;
+/** design/142 §1.5 — the path→projectId HINT CACHE (`<configRoot>/project-id-hints.json`). NOT an
+ *  identity source (the marker is the single truth source); purely the recovery breadcrumb for a
+ *  deleted/lost marker: materialize can tell "this path used to carry marker X" and prompt a
+ *  restore instead of silently minting a fresh identity. Best-effort on both faces (a corrupt hint
+ *  file degrades to "no hints", never blocks a session). */
 export declare const PROJECT_ID_HINTS_FILE = "project-id-hints.json";
 export declare function recordProjectIdHint(configRoot: string, repoRoot: string, projectId: string): void;
 export declare function lookupProjectIdHint(configRoot: string, repoRoot: string): string | undefined;
+/** B3 — `<configRoot>/<dirKey>/.engine`: the engine CONTROL PLANE for a DIRECTORY-pinned mount (the
+ *  memory dir itself is the key). ALWAYS on the config-root side — when the memory dir is configured
+ *  in-repo, the control plane still lives here (model-invisible, not injected, not in-repo) — and
+ *  keyed RESOLVE-ONLY, because the key input is a directory the model's file channel may be able to
+ *  replace: see {@link deriveDirKey} for why canonicalizing it is a redirect handle.
+ *  The repo-partition face has its own sibling mint, {@link deriveRepoControlPlaneDir}. */
 export declare function deriveControlPlaneDir(configRoot: string, key: string): string;
+/** B3 — the REPO-partition control plane: the sibling of {@link deriveRepoMemoryDir} under the SAME
+ *  canonical repo key. Paired on purpose: {@link adoptLegacyRepoDirs} adopts the repo partition as ONE
+ *  directory (`memory/` and `.engine/` inside it), so keying its control plane differently from its
+ *  memory dir would strand one of the two on every alias-reached mount. Safe to canonicalize here —
+ *  the key input is the host-declared repo root, not a directory the model can replace. */
 export declare function deriveRepoControlPlaneDir(configRoot: string, repoRoot: string): string;
+/**
+ * Resolve the memory-engine config root: explicit (`RunnerDeps.memoryEngineDir`) → `AGENT_DATA_DIR`
+ * env → `~/.ai-agent` (the same default family as the file stores' `resolveDataRoot`; re-stated here
+ * so core/memory-engine does not import from src/stores).
+ */
 export declare function resolveMemoryEngineRoot(explicit?: string): string;
+/**
+ * Filesystem-safe scope dir label. 评审 H5 (唯一映射): the cleaned slug alone is LOSSY
+ * (`org:7` and `org/7` both fold to `org-7` — two tenants, one directory = cross-scope bleed), so any
+ * scope whose cleaned form differs from the original gets a short content-hash suffix
+ * (`org-7-a1b2c3`), making the mapping injective for all practical inputs; an already-safe scope maps
+ * to itself (stable, human-readable). {@link registerScope} additionally FAIL-CLOSES on a registry
+ * collision (two distinct scopes → one dir name), so even a hash collision cannot silently merge scopes.
+ */
 export declare function scopeDirName(scope: string): string;
+/** Which scope owns the memory dir ROOT (undefined = unclaimed). */
 export declare function rootScopeOf(controlDir: string): string | undefined;
+/**
+ * Claim the memory dir root for `scope` iff unclaimed (idempotent, first-writer-wins, durable).
+ * Returns the (possibly pre-existing) root owner. Lock-serialized (独立轨 F5): two first-users of a
+ * shared mount race the claim under the sidecar lock — exactly one wins, the other SEES the winner.
+ */
 export declare function claimRootScope(controlDir: string, scope: string): string;
+/** Register `scope` in the durable registry (idempotent) and return its home dir under `memoryDir`.
+ *  H5 fail-closed: a dir-name collision with a DIFFERENT registered scope throws — two scopes must
+ *  never share one directory (silent cross-scope merge). Lock-serialized (独立轨 F5). */
 export declare function registerScope(memoryDir: string, controlDir: string, scope: string): string;
+/** All registered scopes → home dir name (`""` = the root). */
 export declare function registeredScopes(controlDir: string): Record<string, string>;
+/** The stable home directory of `scope`'s entry files: the root when it owns the root, else the
+ *  REGISTERED subdir (falls back to the {@link scopeDirName} formula for a never-registered scope). */
 export declare function scopeDirFor(memoryDir: string, controlDir: string, scope: string): string;
+/** Canonicalize a path for containment checks (resolves symlinks on the EXISTING prefix). */
 export declare function canonicalize(p: string): string;
+/** True iff `child` (canonicalized) is `root` or inside it. */
 export declare function isContainedIn(root: string, child: string): boolean;
+/** mkdir -p convenience used by the engine/backend (0o700 like the file stores). */
 export declare function ensureDirExists(dir: string): void;
+/** B2/L4 — the control-plane subdir holding gate-rejected originals. ONE name for all three writers
+ *  (engine harvest, engine derived-index rung, backend inbound gate): they write the same directory,
+ *  so its name and its permissions must not depend on which of them ran first. */
 export declare const QUARANTINE_DIR = "quarantine";
+/** REF-A9 — what {@link quarantineAndTombstone} reports back; both hosts escalate `detail` into
+ *  their report channel (harvest `quarantineFailures` / inbound `quarantine_failed` findings). */
 export interface QuarantineOutcome {
+    /** The captured copy under the quarantine dir. Absent ⇔ the capture itself failed. */
     dest?: string;
+    /** True ⇔ the model-visible file no longer holds the suspect content (deleted, or tombstoned). */
     removed: boolean;
+    /** Set on ANY deviation from the clean capture+delete path — never a silent best-effort downgrade. */
     detail?: string;
 }
+/**
+ * B2/L4 + C-F9 (S2-0) — capture a gate-rejected file into control-plane quarantine FROM THE
+ * ALREADY-READ `content` (never re-reading `path`: the disk bytes may have been swapped since the
+ * gate scanned them — TOCTOU), then remove the suspect from the model-visible plane: delete, and if
+ * that fails overwrite in place with {@link DELETED_TOMBSTONE}.
+ *
+ * REF-A9: ONE implementation for the engine's harvest rung and the backend's inbound-gate rung.
+ * They were line-for-line twins carrying the same historical fix ("mirrors the engine-side fix",
+ * opus review 1.257.2) and had already drifted twice — the backend minted its quarantine filename
+ * off `Date.now()` instead of its own injected clock, and the two created the SHARED quarantine dir
+ * with different permissions (whoever ran first decided how readable the captured secrets were).
+ *
+ * NOT to be reused for the derived-index rung (`MemoryEngine.gateDerivedIndex`): that one CLEARS the
+ * file (the index is derived and is rebuilt from entry frontmatter), which is the opposite of a
+ * tombstone — folding them would launder that distinction away.
+ */
+/**
+ * Write `content` to `path`, refusing to follow a symlink at the FINAL component (`O_NOFOLLOW`).
+ *
+ * Every containment write in this domain is a check-then-use: the path was judged in-root when the
+ * scan read it, and the write happens later. A symlink dropped in that window turns a containment
+ * response — the thing whose job is removing suspect bytes — into a write through the link, i.e.
+ * this process putting its own committed memory content wherever the link points. Re-checking
+ * before writing cannot close a race; the kernel resolving and rejecting in one step can.
+ *
+ * SCOPE, stated exactly because the difference matters: `O_NOFOLLOW` constrains the LAST component
+ * only. An ANCESTOR directory swapped for a symlink in the same window still redirects the write,
+ * and closing that needs per-component `openat`-style traversal from a pinned root descriptor —
+ * which Node's `fs` does not expose (there is no relative-open API), so it is not reachable here
+ * without native bindings. What this buys is the leaf variant, which is the cheap one; the ancestor
+ * variant stays open and is recorded with the rest of the family rather than papered over.
+ *
+ * Throws like `writeFileSync`, including ELOOP when the final component IS a symlink. The write
+ * itself goes through `writeFileSync` on the open descriptor, which writes every byte or throws —
+ * a bare `writeSync` may short-write, and reporting a truncated restore as contained (after
+ * `O_TRUNC` already destroyed the destination) is the failure this guard exists to prevent.
+ */
 export declare function writeFileNoFollow(path: string, content: string): void;
 export declare function quarantineAndTombstone(path: string, content: string, quarantineDir: string, now: () => number): QuarantineOutcome;
+/** S2-B — the queued memory-change announcements (control plane; drained at session-first inject). */
 export declare const ANNOUNCEMENTS_FILE = "announcements.json";
+/** S2-B — bounded queue: overflow FOLDS (oldest dropped, counted) instead of growing unbounded. */
 export declare const MEMORY_ANNOUNCEMENTS_MAX = 20;
+/** S2-C — per-file write-rejection counts (the beforeWrite silent-reject fuse; O-F9/C-F7: scoped
+ *  state in `.engine/`, so the count survives suspend/resume and backend re-construction). */
 export declare const SCAN_FUSE_FILE = "scan-fuse.json";
+/** Rejections at which the write-time feedback mutes (S2-C: 拒 ≥3 次熔断为静默拒). */
 export declare const SCAN_FUSE_THRESHOLD = 3;
+/** Options of {@link acquireSidecarLock}. `waitCapMs` exists FOR the wait-bound pins (same hook shape
+ *  as the file backend's txn-lock timings) — production callers leave it at {@link LOCK_WAIT_CAP_MS}. */
 export interface SidecarLockOptions {
     onDeadline?: "proceed" | "throw";
     waitCapMs?: number;
 }
+/** Cross-process mutex via mkdir (atomic on POSIX). A lock older than {@link LOCK_STALE_MS} is
+ *  presumed crashed and stolen; after the wait cap we proceed anyway (fail-open — these sidecars are
+ *  not CAS-load-bearing, and wedging a session start on a lock would be worse).
+ *
+ *  opus 1.258 review (MED, steal TOCTOU): a bare rmSync+mkdir steal lets TWO stealers both win (B's
+ *  force-rm deletes A's FRESH lock). The steal is made single-winner by an atomic `renameSync` of the
+ *  stale lock dir to a unique tombstone first — rename is atomic, exactly one racer succeeds; the
+ *  loser's rename throws ENOENT and it loops back to a normal mkdir wait. The deadline branch keeps
+ *  the documented proceed-anyway semantics but steals through the same single-winner gate.
+ *
+ *  Wait-bound (ruled 2026-08-04): EVERY round runs the same three steps — attempt, diagnose, then
+ *  the deadline check and the pause. The two "retry immediately" shortcuts this loop used to take
+ *  (holder released between mkdir and stat; steal attempted) skipped both of the last two, so a
+ *  condition that keeps answering the same way — an unwritable control dir (read-only mount, full
+ *  volume, revoked permission) makes mkdir fail forever while the lock dir it would stat never
+ *  exists — spun this synchronous loop at full speed and never reached its own cap. */
 export declare function acquireSidecarLock(lockDir: string, opts?: SidecarLockOptions): string;
 interface AnnouncementsRecord {
+    /** How many announcements were dropped by the bounded-queue fold (disclosed at render). */
     folded: number;
     queue: MemoryAnnouncement[];
 }
+/** S2-B — enqueue one announcement (journaled + locked; bounded with overflow folding). */
 export declare function enqueueMemoryAnnouncement(controlDir: string, ann: MemoryAnnouncement): void;
+/** S2-B — drain the queue (session-first inject, 时机①). Returns what was queued and resets it. */
 export declare function drainMemoryAnnouncements(controlDir: string): AnnouncementsRecord;
+/** Test/observability peek (journal-aware, non-destructive). */
 export declare function peekMemoryAnnouncements(controlDir: string): AnnouncementsRecord;
+/** S2-C — record one write-time scan rejection for `key` (canonical file path); returns the count
+ *  BEFORE this bump (callers mute the feedback when it is already ≥ {@link SCAN_FUSE_THRESHOLD}). */
 export declare function bumpScanFuse(controlDir: string, key: string): number;
 export declare function readIndexRevs(controlDir: string): Record<string, string>;
 export declare function writeIndexRevs(controlDir: string, revs: Record<string, string>): void;
 export declare function scanFuseCount(controlDir: string, key: string): number;
+/** Directory (under the control plane) holding one marker file per polluted session. */
 export declare const SESSION_POLLUTION_DIR = "session-pollution";
 export interface SessionPollutionRecord {
     at: number;
     reason: string;
 }
+/**
+ * Mark `sessionId` polluted (idempotent; the FIRST record wins — `wx` create refuses overwrite).
+ * Returns true when a durable marker exists after the call (created now or already present);
+ * false ⇔ the marker could not be persisted — the caller must keep its own in-memory mark and
+ * disclose (the session stays polluted for this process either way).
+ */
 export declare function markSessionPolluted(controlDir: string, sessionId: string, reason: string, now: () => number): boolean;
+/** Read the durable pollution record for `sessionId` (undefined = no marker).
+ *  A marker that EXISTS still reads as polluted whether or not its bytes can be read or parsed
+ *  (fail-closed: neither corruption nor an unreadable node may launder the state) — a synthesized
+ *  record stands in. Only ABSENCE is clean, so a control plane that cannot be stat'ed at all reads
+ *  clean for every session rather than disabling memory deployment-wide. */
 export declare function readSessionPollution(controlDir: string, sessionId: string): SessionPollutionRecord | undefined;
+/** The retrieved-account sidecar (control plane): entry id → { count, lastAt }. */
 export declare const USAGE_RETRIEVED_FILE = "usage-retrieved.json";
+/** Bound on tracked ids — over the cap, the entries with the OLDEST `lastAt` are evicted first
+ *  (a popularity account tolerates forgetting cold ids; unbounded growth does not tolerate itself). */
 export declare const USAGE_RETRIEVED_MAX_IDS = 4096;
+/** One retrieved-account row. */
 export interface RetrievedAccountRow {
     count: number;
     lastAt: number;
 }
+/** Record one retrieval (a search/get hit actually RETURNED to the model) for each id. Journaled +
+ *  locked like every sidecar; throws propagate to the caller, which treats them fail-open. */
 export declare function recordRetrievedAccount(controlDir: string, ids: readonly string[], now: () => number): void;
+/** Journal-aware read of the retrieved account (observability/tests; nothing in the engine's
+ *  retention/ranking paths consumes it — see the section note). */
 export declare function readRetrievedAccount(controlDir: string): Record<string, RetrievedAccountRow>;
+/** S2-C — clear the fuse for files harvest just ACCEPTED (a committed write resets the strike count). */
 export declare function clearScanFuse(controlDir: string, keys: Iterable<string>): void;
+/**
+ * REF-C6 — write EVERY byte of `data` to `fd`, looping until the OS has taken all of them.
+ *
+ * A bare `writeSync(fd, data)` issues ONE write(2) and may legally SHORT-WRITE (POSIX): it returns
+ * how many bytes it took and silently drops the rest. `src/stores/file/fs-atomic.ts` already
+ * documents and fixes this defect class twice (`writeThenLink`'s "silently SHORT-WRITES" note and
+ * `AppendLog.append`'s RB-66 loop) — it was never propagated to the memory-engine control plane,
+ * where a short write would fsync+rename a TRUNCATED sidecar/entry into place while every
+ * fail-closed check upstream still reported success. Zero progress throws instead of spinning.
+ */
 export declare function writeAllSync(fd: number, data: string): void;
+/** B3/H4 — TORN-WRITE-safe atomic replace (R5, ruling 2026-08-02: wording narrowed, no dirsync
+ *  added): tmp file in the SAME directory (rename atomicity needs one fs), content fsync'd, then
+ *  renamed over the target. A crash can leave the OLD content or the NEW content, never a torn
+ *  file. What this does NOT promise: the rename itself surviving a power loss — the directory entry
+ *  is not fsync'd (stores/file/fs-atomic.ts has the dir-fsync variant for stores that need it), so
+ *  a crash in that window can resurface the old content. Sidecars tolerate that (they are rebuilt
+ *  or re-derived); do not route data that can't through here. Throws on failure (fail-closed: a
+ *  sidecar that cannot be written must not be silently skipped). */
 export declare function atomicWriteFileSync(path: string, data: string): void;
 export {};

package/dist/core/memory-engine/memory-backend-contract.d.ts

@@ -1,9 +1,21 @@
 import type { MemoryBackend } from "./types.js";
 export interface MemoryBackendContractHooks {
     make: () => Promise<MemoryBackend> | MemoryBackend;
+    /** A second backend instance over the SAME storage as the given one (cross-instance CAS cases). */
     makeSibling?: (of: MemoryBackend) => Promise<MemoryBackend> | MemoryBackend;
+    /**
+     * design/142 §6.3: the ONLY way to run the suite without `makeSibling`. State WHY this store has no
+     * shared-storage second instance (e.g. "process-exclusive single-writer file store; cross-process CAS
+     * covered by <suite>"). Runs as a named, visible case (a LOUD skip) — never a silent 16/17 pass.
+     * Authoritative-backend certification (§6.1 (a)) must provide `makeSibling` instead.
+     */
     skipCrossInstanceCas?: string;
+    /** Wrap each case (vitest `it`, sequential SQL chaining, …). Default: run sequentially. */
     runAssertion?: (name: string, fn: () => Promise<void>) => void | Promise<void>;
 }
+/** Run the full conformance suite. Throws (assert) on the first violated contract clause. */
 export declare function memoryBackendContract(hooks: MemoryBackendContractHooks): Promise<void>;
+/** Cross-backend value equivalence: same fixture ⇒ IDENTICAL (id, slug, score) search projections on
+ *  two backends (File vs Pg lexical floor must not drift — assertMemoryValueEquivalence precedent).
+ *  mtimeMs/sizeBytes are backend-native (fs stat vs column) and deliberately not compared. */
 export declare function assertMemoryBackendSearchEquivalence(a: MemoryBackend, b: MemoryBackend): Promise<void>;

package/dist/core/memory-engine/migrate.d.ts

@@ -1,7 +1,16 @@
 import type { MemoryBackend, PatchReport } from "./types.js";
 export interface MigrateScopeReport {
+    /** Entries moved to the new scope (CAS-clean). */
     moved: number;
+    /** Entries that hit a CAS conflict (concurrently edited during migration) — re-run to retry. */
     conflicts: PatchReport["conflicts"];
+    /** Whether the consolidation cursor was carried over (only when the old scope had one). */
     cursorMoved: boolean;
 }
+/**
+ * Move EVERY entry from `fromScope` to `toScope` on one backend (id-preserving, rev-recomputed via
+ * the cross-scope move contract), then carry the consolidation cursor. NOT transactional across
+ * entries (the contract's per-patch independence): a conflict leaves that entry in place — the
+ * report says so and a re-run picks it up. Refuses same-key no-ops.
+ */
 export declare function migrateScope(backend: MemoryBackend, fromScope: string, toScope: string): Promise<MigrateScopeReport>;

package/dist/core/memory-engine/scan.d.ts

@@ -1,7 +1,19 @@
 import type { ScanFinding } from "./types.js";
+/** S2-B 判决四 — the per-path-segment whitelist for memory-domain file names. */
 export declare const MEMORY_FILENAME_SEGMENT_RE: RegExp;
+/**
+ * Scan a memory-domain file NAME (a path relative to the writable root, `/`-separated). Returns the
+ * finding or undefined (clean). Rejected names quarantine at harvest and hard-reject at write time —
+ * a name like `foo</system-reminder>bar.md` is an injection payload wherever the path is echoed.
+ */
 export declare function scanMemoryFileName(relPath: string): ScanFinding | undefined;
+/**
+ * Scan memory-domain file CONTENT. Returns every finding (empty = clean). `maxBytes` (when given)
+ * adds the per-file cap rung — harvest passes it via its own pre-check today, the write-time hook
+ * passes the engine's `perFileBytes` so the model gets the feedback BEFORE the bytes ever land.
+ */
 export declare function scanMemoryWrite(text: string, opts?: {
     maxBytes?: number;
 }): ScanFinding[];
+/** Model-facing remediation line per scan code (S2-C: 拒写+结构化错误含整改指引). */
 export declare function scanRemediation(code: ScanFinding["code"]): string;