@sema-agent/core 5.64.0 → 6.0.0

package/dist/core/file-history-store.d.ts

@@ -0,0 +1,768 @@
+import { type FileHistoryRetentionPolicy } from "./file-history-retention.js";
+import type { ExecutionEnv } from "../internal/harness-types.js";
+/** rel path of `child` under `root` in "/" form (win root) / verbatim form (posix root); null when not under.
+ *  Fold "\" only under a WIN-family root ({@link isWinFormPath}); a POSIX tree may legally contain literal
+ *  backslashes in FILE NAMES, and folding them would corrupt both the track key and the restore target. */
+declare function relUnder(root: string, child: string): string | null;
+/** Join root + a "/"-form relPath using the ROOT's native separator (keys stay family-consistent). */
+declare function joinUnder(root: string, rel: string): string;
+/** The parent directory of an addressed path, as a pure family-aware string op (no host node:path). */
+declare function parentDirOf(absPath: string): string | undefined;
+/** The re-join verdict of {@link resolveTrackKey}: an absolute path to operate on, or a NAMED
+ *  refusal (the fail-closed arm — a recorded key that would escape `root` is never coerced into
+ *  something writable). A-082 idx5: named so the fence can be part of the public surface. */
+export type FileHistoryTrackKeyResolution = {
+    ok: true;
+    abs: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The path family a track key was MINTED under — the half a bare key string cannot carry. */
+export type FileHistoryKeyFamily = "posix" | "win";
+/**
+ * A track key's SELF-DESCRIPTION (design/381 §3 amendment, closing the A-082 r2 registered
+ * residual): a key is a bare string, so it carries the shape it was minted in but never the family
+ * it was minted under. Recorded beside every tracked path and carried by the session-sync envelope,
+ * so a graph that arrives from ANOTHER MACHINE can be judged at the door instead of silently
+ * re-joining under the local root as an oddly-named in-root file.
+ */
+export interface FileHistoryTrackKeyDescriptor {
+    /** `"root-relative"` = re-join against the CURRENT root; `"absolute"` = restore where captured. */
+    kind: "root-relative" | "absolute";
+    family: FileHistoryKeyFamily;
+}
+/** The family of a root — the one place a backend asks "which family am I operating in?". */
+export declare function trackKeyFamilyOf(root: string): FileHistoryKeyFamily;
+/**
+ * {@link trackKeyOf} plus the self-description a backend must record with it. Mint through THIS and
+ * a graph stays judgeable after it crosses machines; mint through the bare key alone and the
+ * provenance is gone for good (the residual this closes).
+ */
+export declare function describeTrackKey(root: string, absPath: string): {
+    key: string;
+} & FileHistoryTrackKeyDescriptor;
+/**
+ * Track-key coordinate (design/381 DV-6, the CC `wZu` relativization ported to the trusted task
+ * root): a path under `root` is recorded root-RELATIVE (worktree/moved-root safe — restore re-joins
+ * it against the CURRENT root), a path outside `root` is recorded verbatim-absolute.
+ *
+ * **Exported as part of the "MUST reuse, NOT re-implement" set** (A-082 idx5, the same §3 分工
+ * clause that governs the two env halves): every backend mints keys from the `(absPath, root)` pair
+ * `trackEdit`/`snapshot` hand it and re-joins them in `restore`, so this pair — not the env halves —
+ * is where a hand-rolled backend re-introduces path escape. The escape check lives INSIDE the pair
+ * (mint refuses to record an ambiguous rel form; {@link resolveTrackKey} refuses an unsafe recorded
+ * one), so a backend that calls them cannot re-open the hole, and one that re-derives them must
+ * re-derive the family-conditional bare-drive rule and the '..' fail-closed arm correctly on its own.
+ */
+export declare function trackKeyOf(root: string, absPath: string): string;
+/**
+ * Re-join a recorded track key against the CURRENT root (identity for absolute keys) — the
+ * {@link trackKeyOf} mirror, exported under the same "MUST reuse" clause. A key that would escape
+ * the root is REFUSED by name, never coerced: `{ok:false}` is the fail-closed arm a backend must
+ * surface as a per-file `refused` row, not silently drop.
+ *
+ * CROSS-FAMILY PROVENANCE (A-082 codex r2, registered in slice 1 — CLOSED here in slice 2 exactly as
+ * that note prescribed). A key is a bare STRING: it carries the shape it was minted in, never the
+ * FAMILY it was minted under. Every key minted against this scope's own root resolves by the mirror
+ * above — but a scope carried in from another machine (the {@link FileHistoryExport} envelope,
+ * `adoptScope` across hosts) can hold a key whose family differs from the current root's, and under
+ * a POSIX root a win-absolute record (`D:\other\x`) used to re-join UNDER the root as an oddly-named
+ * in-root file (contained, never traversal — but not the file the record meant). The closure is the
+ * §3 amendment the note named: a SELF-DESCRIBING key ({@link FileHistoryTrackKeyDescriptor}: kind +
+ * source family) recorded beside every tracked path and carried by the versioned envelope, judged
+ * HERE through the optional `minted` argument. Omit it and this function is byte-identical to
+ * before; pass it and a foreign-family record is refused by name instead of coerced.
+ */
+export declare function resolveTrackKey(root: string, key: string, minted?: FileHistoryTrackKeyDescriptor): FileHistoryTrackKeyResolution;
+export interface FileHistoryError {
+    /** `not_found` = no boundary for that (scope, entryId); `aborted` = the signal fired (or the
+     *  fencing discarded a timed-out attempt); `conflict` = a non-destructive-target law refused
+     *  (adopt/import onto a scope with its own history) — and ONLY that, because a caller decides
+     *  whether to stay quiet on it: the engine's fork-carry seat treats `conflict` as "already carried,
+     *  or grown its own" and says nothing, so an adoption that failed for any OTHER reason (a corrupt
+     *  source graph, a blob it cannot reach, a consumed-id ledger it cannot carry — including the
+     *  tombstones a publish owes for unreadable residue it is about to replace) must NOT wear this
+     *  code or the failure disappears into that silence — those are `adopt_failed`, which the
+     *  ADOPTION FAMILY shares: `importHistory` publishes under the same target law and answers the
+     *  same code for the same non-conflict failures (its `unsupported_format` names a bad ENVELOPE or
+     *  work its shape drove; a fault in the PUBLISH step itself — the disk refusing a good graph —
+     *  answers `adopt_failed`); `unsupported_format`
+     *  = a foreign-epoch or wrong-version envelope; the rest name the verb that failed. */
+    code: "track_failed" | "snapshot_failed" | "restore_failed" | "adopt_failed" | "not_found" | "aborted" | "unsupported_format" | "conflict";
+    message: string;
+}
+export type FileHistoryResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: FileHistoryError;
+};
+/**
+ * {@link FileHistoryStore.trackEdit}'s answer. `minted` is the ANNUL HANDLE in boolean form (#491):
+ * true = THIS call created the first-touch record, so the caller may {@link
+ * FileHistoryStore.annulTrack} it if the edit that record was minted for never lands; false = the
+ * path was already tracked (a cheap no-op), and annulling would destroy a record some EARLIER edit
+ * legitimately owns. A backend that cannot tell answers `false` — the safe side (a stale record is
+ * a cowork hazard, but discarding someone else's pristine baseline is worse).
+ */
+export type FileHistoryTrackResult = {
+    ok: true;
+    minted: boolean;
+} | {
+    ok: false;
+    error: FileHistoryError;
+};
+/**
+ * Three-state discriminant + full per-file ledger on EVERY arm (design/381 DV-15). Refusals are
+ * never folded into benign skips; `base_unavailable` (DV-14) is a refusal reason.
+ */
+export type FileHistoryRestoreResult = {
+    /** `"complete"` = every target applied or identical; `"partial"` = ≥1 refused or failed, others
+     *  applied; `"failed"` = the operation itself could not run (e.g. no such boundary). */
+    outcome: "complete" | "partial" | "failed";
+    /** Track keys written or deleted (the converged set). */
+    filesChanged: string[];
+    /** Track keys already equal to the target (untouched — content-hash proven, never mtime). */
+    identicalSkipped: string[];
+    /** Per-file security/consistency refusals (skipped, counted, never failing the whole restore). */
+    refused: Array<{
+        path: string;
+        reason: string;
+    }>;
+    /** Per-file operational failures (env write/remove errors, aborts after k writes). */
+    failed: Array<{
+        path: string;
+        reason: string;
+    }>;
+    /** Files whose recorded POSIX mode could not be re-applied (env without the optional mode face). */
+    modeNotPreserved?: number;
+    /** Present on outcome:"failed" (operation-level cause) and optionally on "partial". */
+    error?: FileHistoryError;
+};
+export interface FileHistoryDiffStats {
+    filesChanged: string[];
+    insertions: number;
+    deletions: number;
+}
+/** The line-diff bound (see {@link countRestoreLineDiff}): a pair whose edit distance exceeds this
+ *  is counted as a whole-file replacement. Public so a preview UI can state what it is showing. */
+export declare const FILE_HISTORY_DIFF_LINE_BUDGET = 2000;
+/**
+ * The per-file line arithmetic behind {@link FileHistoryStore.diffStats} — ONE rule both bundled
+ * backends use, because "how much will this rewind change" is a claim, and two backends answering it
+ * differently would be two claims.
+ *
+ * `undefined` on either side means "does not exist" (a creation or a deletion), so every arm of the
+ * restore is expressible: bytes → bytes is a line diff, absent → bytes is a pure insertion, bytes →
+ * absent a pure deletion.
+ *
+ * TWO HONESTY BOUNDS, both stated rather than tuned in silence:
+ *  · BINARY content (a NUL byte anywhere) contributes 0/0 while still being reported as CHANGED —
+ *    "lines" is not a fact about a binary file, and printing a number derived from stray `\n` bytes
+ *    would be inventing one.
+ *  · Beyond {@link FILE_HISTORY_DIFF_LINE_BUDGET} the greedy diff STOPS and the pair is counted as a
+ *    whole-file replacement (every current line deleted, every target line inserted). That is not a
+ *    fallback to a worse estimate so much as the shape such a pair actually has — a diff that large
+ *    IS a rewrite — and it keeps a preview from turning into an O(N·M) walk over two big files.
+ */
+export declare function countRestoreLineDiff(current: Uint8Array | undefined, target: Uint8Array | undefined): {
+    insertions: number;
+    deletions: number;
+};
+/**
+ * Versioned session-sync envelope; `formatVersion` is the refuse-not-coerce gate (design/381 §5.3).
+ * COMPLETE-state export: the tracked set and EVERY retained version record travel — including v1
+ * records no surviving boundary references (they are restore()'s pristine fallback and reap()
+ * retains them independently) and the parent-identity guards (root-relative under root) that
+ * restore's preflight needs. An import that received only boundary references could neither run the
+ * parent-chain check nor serve a tracked-later-than-target restore; round-trip-after-reap is a
+ * contract-kit test.
+ */
+export interface FileHistoryExport {
+    formatVersion: "file-history/1";
+    tracked: Array<{
+        /** Root-relative when captured under the task root, verbatim-absolute otherwise. */
+        relOrAbsPath: string;
+        /**
+         * The key's SELF-DESCRIPTION (§3 amendment, A-082 r2). A bare key string cannot say which
+         * family minted it, so a graph that crosses machines was previously re-joined against the local
+         * root on a guess. Both members travel with every path and the import door refuses an envelope
+         * whose values are outside the closed sets (refuse-not-coerce, same posture as `formatVersion`);
+         * {@link resolveTrackKey} then judges each foreign-family key at restore time.
+         */
+        keyKind: FileHistoryTrackKeyDescriptor["kind"];
+        keyFamily: FileHistoryKeyFamily;
+        /**
+         * DV-14: false ⇒ the pristine base could not be captured (durable base-unavailable marker); the
+         * chain then starts above v1 and restore-below-base must keep refusing after import. Travels
+         * with the graph; never inferred.
+         */
+        baseAvailable: boolean;
+        /** Full retained chain (v1 first iff baseAvailable). `blobHash:null` = existed-not marker. */
+        versions: Array<{
+            version: number;
+            blobHash: string | null;
+            mode?: number;
+            parentIdent?: string;
+            backupTime: string;
+        }>;
+    }>;
+    boundaries: Array<{
+        entryId: string;
+        files: Array<{
+            relOrAbsPath: string;
+            version: number;
+        }>;
+    }>;
+}
+/**
+ * The IDENTITY of an envelope — sha256 over its canonical (sorted) form, so the same graph digests
+ * the same however a backend ordered its rows. It is what makes `importHistory`'s idempotent
+ * re-publish decidable WITHOUT extra bookkeeping: a target already holding a graph that digests
+ * equal to the incoming one is the SAME import arriving twice (ok), while any other non-empty target
+ * is locally-grown history the import must never overwrite (typed `conflict`). Exported under the
+ * "MUST reuse" clause: two backends that computed identity differently would disagree about which
+ * retries are safe.
+ */
+export declare function fileHistoryExportDigest(data: FileHistoryExport): string;
+/**
+ * The import DOOR's structural judgment, shared by every backend (a second implementation is a second
+ * opinion about what is safe to accept): the envelope must carry THIS format version and every row
+ * must be shaped and self-described from the closed sets — `unsupported_format` otherwise, never a
+ * coercion. Backends call this BEFORE fetching a single blob, so a foreign-epoch payload costs
+ * nothing and changes nothing.
+ */
+export declare function validateFileHistoryExport(data: FileHistoryExport): FileHistoryResult;
+/**
+ * design/381 §3 — per-edited-file rewind history (CC FileHistory topology).
+ *
+ * Replaces the E19 whole-tree FileSnapshotStore. Three verbs mirror the reference module:
+ * `trackEdit` (backup-before-first-edit), `snapshot` (version the tracked set at a turn boundary),
+ * `restore` (converge ONLY the tracked set to a recorded boundary).
+ *
+ * Store discipline (contract-kit enforced):
+ * - NEVER throw: every failure is encoded in the returned result (FileSystem posture).
+ * - snapshot MUST NOT fail the caller's turn: a failed boundary capture degrades to "no boundary"
+ *   with disclosure (onError phase:"rewind"). trackEdit is DIFFERENT (DV-14): its `{ok:false}`
+ *   means "no durable first-touch state exists" and the CALLER's default policy is to REFUSE the
+ *   edit (typed, loud) — silently proceeding would let a post-recovery retry mint already-modified
+ *   bytes as pristine v1. Any proceed-unprotected policy is an explicit, adjudicated caller arm,
+ *   never the store's own behavior.
+ * - Structurally out of scope: files the agent never edited. No store method may enumerate, read,
+ *   or write ANY path outside the tracked set plus its recorded restore targets. (The cowork
+ *   guarantee lives HERE, as a contract clause.)
+ * - BOUNDED by default: one boundary per turn, forever, is unbounded growth. Both bundled backends
+ *   trim their own scope after each commit (see {@link FileHistoryStore.reap} for the rule, the
+ *   default and the host override); an out-of-tree backend owes its own bound or an explicit
+ *   statement that the host must schedule the GC.
+ */
+export interface FileHistoryStore {
+    /**
+     * Backup `absPath`'s CURRENT state before an agent edit (first touch per scope only; later calls
+     * are cheap no-ops). The first touch is ONE atomic durable record — pristine blob+record,
+     * existence=false marker (rewind of an agent-CREATED file deletes it), or base-unavailable marker
+     * (DV-14). Reads bytes via `env` (remote-safe); stores them host-side. `root` is the trusted task
+     * root: paths under it are recorded root-RELATIVE (worktree/moved-root safe), paths outside it
+     * verbatim-absolute; the parent-identity guard is recorded in the same frame.
+     * `{ok:false}` = NO durable first-touch state was persisted — see the discipline block: the
+     * caller's default is to REFUSE the edit (DV-14), because proceeding leaves the path
+     * indistinguishable from never-touched. `{ok:true, minted}` — see {@link FileHistoryTrackResult}:
+     * `minted:true` means this call created the record, which is what makes {@link annulTrack} legal
+     * for it (#491).
+     */
+    trackEdit(scope: string, absPath: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileHistoryTrackResult>;
+    /**
+     * Discard the first-touch record `trackEdit` MINTED for `absPath` — the compensating verb for the
+     * one ordering the topology cannot avoid (#491): the pre-image capture must run BEFORE the write,
+     * so a write that then fails (a lost create race, ENOSPC, EACCES, a read-only mount) leaves a
+     * record for an edit that never happened. Left standing, an `existed-not` v1 makes an untouched
+     * path a rewind DELETE target: whoever writes those bytes next — the user, a peer process — gets
+     * them removed by a restore that reports `complete`, which is precisely the structural
+     * out-of-scope guarantee this contract opens with. So the record must be retractable.
+     *
+     * Discipline (contract-kit enforced): NEVER-throw like every other verb, and no env IO AT ALL
+     * unless the caller asks for the proof read below. Retraction is legal ONLY while the record is
+     * still exactly what `trackEdit` minted — a record referenced by ANY committed boundary, or one that has grown
+     * past its first version, is REFUSED (typed `conflict`) and left intact, because history that a
+     * boundary already froze is no longer the caller's to withdraw. An absent record is an idempotent
+     * `{ok:true}` (the retry path). Callers annul ONLY what their own `trackEdit` reported as
+     * `minted:true`: a path that was already tracked belongs to the edit that first touched it, and
+     * discarding that baseline would be the fake-pristine hole DV-14 exists to weld shut.
+     *
+     * `verify` is the EVIDENCE arm (adversarial round 2). A caller whose write failed with a code the
+     * FileSystem contract defines as "nothing was written" (`already_exists`, `precondition_failed`)
+     * has proof and passes nothing. Every other failure — a plain write is not contractually atomic,
+     * so ENOSPC, a dying transport or a thrown backend may have TRUNCATED the file before reporting —
+     * must hand an `env` here: the store then re-reads the path ONCE and retracts only if the world
+     * still matches what the mint recorded (bytes still absent for an existed-not mint, still the same
+     * hash for a captured one). A file that changed keeps its record, because the alternative is
+     * deleting the only baseline of a file the agent really did modify — damage rewind could no longer
+     * reach, which is strictly worse than a stale record.
+     */
+    annulTrack(scope: string, absPath: string, root: string, verify?: {
+        env: ExecutionEnv;
+        signal?: AbortSignal;
+    }): Promise<FileHistoryResult>;
+    /**
+     * Record a history boundary keyed by `entryId` — the TURN'S OWN initial session entry, minted
+     * after that entry is appended and BEFORE any tool executes, so the boundary means "file state
+     * when `entryId`'s turn began" (≡ the reference's user-message-uuid snapshot; every turn
+     * incarnation appends a fresh entry, so keys never alias across re-branches from the same fork
+     * point). For each tracked file: re-stat via `env`; unchanged (metadata may prove inequality,
+     * content hash proves equality — DV-13: never mtime) ⇒ reference the prior version; changed ⇒
+     * store a new version; missing ⇒ record a deletion marker. Zero directory-tree traversal, zero
+     * size gate. Idempotent per (scope, entryId) over COMMITTED boundaries.
+     *
+     * Commit visibility + fencing + CAPTURE LEASE (contract-kit enforced): a boundary becomes visible
+     * to canRestore/restore ONLY after its complete version mapping is durable. Each attempt is
+     * FENCED (a timed-out/aborted attempt may never commit — {@link boundaryPublishVerdict}, no grace
+     * threshold), and the boundary's capture window is a LEASE that the caller closes before the
+     * first tool executes: after lease close, a fresh CAPTURE (any env read) for that entryId is
+     * refused — a retry may only PUBLISH a mapping whose bytes were fully captured before close.
+     * The close is NOT persisted and the store has no close verb (design/381 §10 S-6): close is the
+     * calling Runner's in-process discipline; after a crash the new process has no capture path for
+     * the old entryId (its own prepare mints only its own turn's boundary), and abandoned staging is
+     * judged by COMPLETENESS alone — complete ⇒ publishable, incomplete ⇒ abandoned (that turn has no
+     * boundary) — with ZERO env reads on the retry path. A turn whose pre-turn capture failed simply
+     * has no boundary (disclosed; the reference behaves the same) — there is NO mid-turn re-capture,
+     * because re-reading after edits would publish post-turn bytes under a pre-turn key. An entryId
+     * whose boundary was COMMITTED and later REAPED is closed by the same law and for the same reason
+     * (see {@link FileHistoryStore.reap}): it refuses typed with zero env reads rather than
+     * re-capturing a world that has moved on. Retention can therefore make a boundary unavailable,
+     * but never wrong.
+     */
+    snapshot(scope: string, entryId: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileHistoryResult>;
+    /**
+     * Converge ONLY the tracked set to the boundary `entryId`: for each tracked file, target-version
+     * bytes ⇒ write via `env` (the guarded-write arm and the symlink/parent-chain/kind preflights are
+     * the design/381 slice-3 hardening — until then the write is plain and ADVISORY, stated, never
+     * overclaimed); deletion marker ⇒ remove; identical ⇒ untouched; tracked-later-than-target ⇒ fall
+     * back to its v1 (pristine) version, and a base-unavailable path (DV-14) is REFUSED with reason
+     * `base_unavailable` (left at its current state — never overwritten with a fake baseline).
+     * Per-file refusals SKIP that file and are counted, never failing the whole restore (CC form).
+     * Paths recorded relative to `root` re-join against the CURRENT root (worktree/moved-cwd safe).
+     *
+     * Partial outcome is FIRST-CLASS with a three-state discriminant and the per-file ledger always
+     * travels: applied / identicalSkipped / refused / failed are SEPARATE columns (a security refusal
+     * must never hide inside a benign skip count), so a caller can distinguish "nothing was mutated"
+     * from "the env died after k writes". Restore is per-file idempotent (identical files skip), so
+     * the documented recovery for a partial outcome is: re-run the same restore; it converges. There
+     * is NO all-or-nothing guarantee and none is claimed. Task-level policy on `"partial"` lives in
+     * the CALLER (prepare defaults to fail-loud; see DV-15).
+     */
+    restore(scope: string, entryId: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileHistoryRestoreResult>;
+    /** Whether a boundary exists for (scope, entryId). */
+    canRestore(scope: string, entryId: string): Promise<boolean>;
+    /**
+     * Optional dry-run: per-file change stats for a prospective restore (CC diffStats; design/381
+     * slice 3). A-2 two-state law: `null` = preview UNAVAILABLE ≠ an empty stats object = a true
+     * zero-coverage answer — an absent preview must never be rendered as "nothing will change".
+     *
+     * It is an UPPER BOUND on what a restore will touch, and the reason is worth stating rather than
+     * discovering: the preview answers the CONTENT question (which tracked files differ from the
+     * boundary, and by how many lines), while the per-file security preflight — symlink/kind, parent
+     * chain — is decided by `restore` against the world as it stands THEN. A file listed here can
+     * therefore come back refused, and a preview that pre-ran those checks would be making promises
+     * about a world it does not own. Files whose target cannot be resolved at all (a missing version
+     * record or blob, an unsafe key) are left OUT: the restore reports them per file, and a preview
+     * cannot show the size of a change it cannot compute.
+     */
+    diffStats?(scope: string, entryId: string, env: ExecutionEnv, root: string): Promise<FileHistoryDiffStats | null>;
+    /**
+     * GC: drop boundaries in `scope` not in `keepEntryIds`; then drop version records (and content
+     * blobs) referenced by NO surviving boundary — EXCEPT v1 records AND base-unavailable markers
+     * (DV-14), which are retained while the scope lives (the pristine fallback and its explicit
+     * refusal state are both part of the graph). Returns the number of boundaries dropped.
+     *
+     * WHO CALLS IT (design/381 §片2 — the bound is the backend's, not a chore left to the host): both
+     * bundled backends drive this verb THEMSELVES. Every committed boundary is followed by a
+     * retention pass that trims the scope to the newest
+     * {@link import("./file-history-retention.js").DEFAULT_FILE_HISTORY_BOUNDARY_KEEP} boundaries —
+     * an engine default a deployment overrides through the store's own `retention` option, including
+     * `keep: "unbounded"` to switch the self-trim off and take the schedule back. The pass is
+     * best-effort by construction (a GC failure never fails the turn that triggered it) and it only
+     * ever removes boundaries the caller could not name any more anyway.
+     *
+     * A backend outside this repo therefore owes ONE of two things, and silence is neither: its own
+     * bound (this verb, driven from its own commit path), or a documented statement that the host
+     * must schedule `reap`. An unbounded boundary graph is not a tuning choice — one boundary per
+     * turn, forever, is a disk that fills with no line anywhere admitting it would.
+     *
+     * WHAT THE SELF-TRIM DOES NOT COVER, said here rather than left to be discovered: it runs at a
+     * COMMIT, so a graph that arrives whole — `adoptScope`, `importHistory` — is published whole and
+     * comes under the bound at that scope's next commit, not before. That is deliberate rather than
+     * an oversight (round 2 raised it): both verbs promise all-or-nothing visibility of the graph the
+     * caller handed over, and trimming during publication would silently discard history the host
+     * explicitly asked to transfer. The overshoot is bounded by the envelope the host chose, which is
+     * a different thing from the per-turn source this bound exists to stop.
+     *
+     * A REAPED entryId IS SPENT (adversarial review — a law this verb acquired the day anything
+     * started calling it): dropping a boundary must not hand its key back. Until boundaries could be
+     * dropped, the committed mapping was itself the record that an entryId had been consumed, and
+     * `snapshot`'s idempotent short-circuit read it; a store that forgot a reaped id would let a
+     * later `snapshot` for that key take the CAPTURE path and publish post-turn bytes under a
+     * pre-turn key. Both bundled backends therefore tombstone what they reap and refuse a later
+     * capture of it, typed and with zero env reads. The ledger is IDS, not mappings, and it is
+     * unbounded — stated plainly because a bound's own residue growing forever would be a poor joke:
+     * one id string per boundary ever reaped, against the complete tracked-set mapping each of those
+     * boundaries used to carry. It is the cheap part of what the bound throws away, by two orders of
+     * magnitude, and it is what makes the bound safe rather than merely small.
+     *
+     * Concurrency is unchanged and stays the caller's to reason about: a pass that runs while another
+     * entryId's capture is parked at an env read may drop a version that capture staged, and that
+     * capture then refuses TYPED (its turn has no boundary) rather than publishing a dangling
+     * reference — the arm the commit paths already validate for.
+     */
+    reap(scope: string, keepEntryIds: string[]): Promise<number>;
+    /**
+     * Cross-session carry (CC copyFileHistoryForResume): make `toScope` see `fromScope`'s boundaries
+     * + versions (content-addressed backends copy references, zero bytes). Same-scope call is a
+     * no-op. ATOMIC-VISIBILITY, same law as snapshot: the WHOLE adopted graph (tracked set, every
+     * version incl. base-availability state, every referenced blob) is staged and verified, then
+     * published in one step — `toScope` either sees the complete history or none of it. A
+     * failed/partial adopt publishes NOTHING; the resume still proceeds (same availability posture as
+     * the reference's tolerated partial copy, without the half-visible graph) and the failure is
+     * disclosed. EMPTY-TARGET ONLY: adoption is refused (loud, typed `conflict`) once `toScope` has
+     * ANY history of its own — adoption's seat is the fork/resume boundary BEFORE the new session's
+     * first turn; a retry after the target has begun writing would need a destructive merge
+     * (version-number collisions, overwritten target history) that this contract deliberately
+     * forbids. Retry while the target is still empty is idempotent and repairs abandoned staging.
+     *
+     * WHO CALLS IT — THE ENGINE DOES, since design/381 slice 3, and the seat is worth knowing because
+     * it decides WHEN this verb runs against your backend. `prepareTask` carries a forked session's
+     * history on the first turn it prepares for it, keyed on the LINEAGE FACT
+     * (`SessionMetadata.forkedFrom`) rather than on the code path that forked — so the Agent tool's
+     * fork route, `warmResume`, and a deployment that forks a session and then runs a task on it all
+     * reach the same seat. It runs BEFORE the restore seat, so the very first task on a fork may
+     * itself ask to restore files to a pre-fork boundary.
+     *
+     * The empty-target law is what makes that safe to attempt rather than schedule: a scope that
+     * already holds history answers the typed `conflict`, which at that seat MEANS "already carried,
+     * or grown its own" and is treated as a no-op. Only a non-conflict failure is disclosed
+     * (`onError` phase `"rewind"`), because that one is a carry the deployment expected and did not
+     * get. A failed carry never blocks the fork's run.
+     *
+     * A HOST MAY STILL CALL IT — the engine's seat covers sessions the engine prepares, and a
+     * deployment that copies history between scopes for its own reasons (a migration, a scope rename)
+     * is calling the same verb under the same law. What a MISSED carry gets is degraded, not broken,
+     * and it is worth naming precisely: the new scope starts EMPTY, so nothing the old one tracked is
+     * restorable from it. A rewind aimed at a pre-fork boundary answers "no boundary" (honest, typed)
+     * instead of converging those files, and the new lineage's own first touch of a path records THAT
+     * path's then-current bytes as its pristine v1 — a correct baseline for the new lineage, just not
+     * the old one's history. Nothing is silently mis-restored; the carry simply does not happen.
+     */
+    adoptScope(fromScope: string, toScope: string): Promise<FileHistoryResult>;
+    /**
+     * Session-sync export/import (2c), versioned envelope — see {@link FileHistoryExport}. Optional.
+     * importHistory obeys the SAME atomic-visibility + staged-verify law as adoptScope: every
+     * referenced blob fetched and integrity-checked, then the scope's graph published in one step; a
+     * mid-import failure publishes nothing. NON-DESTRUCTIVE TARGET LAW (same family as adoptScope): a
+     * first import requires an EMPTY target graph; a retry is legal only while the target is still
+     * empty OR already holds a graph with the exact same import identity/digest (pure idempotent
+     * re-publish). A non-empty target with any other content ⇒ typed `conflict` refusal — atomic
+     * visibility prevents half-graphs, this law prevents publishing the WRONG complete graph over
+     * locally-grown history.
+     */
+    /**
+     * NO `dispose` / lifecycle verb, and that is a decision rather than an omission (design/381 slice 3,
+     * the R-6 review candidate — recorded here because the next reader will otherwise wonder). The case
+     * for one: a directly-constructed file backend holds no store lock, so the single-writer premise is
+     * enforced only where a deployment assembles the backend (its data-root LOCK), and a `dispose`
+     * would let a store hold a lease and release it. The case against, which won:
+     *  · every verb here is self-contained — a store holds no cross-call resource, so `dispose` would be
+     *    an obligation on EVERY backend (a SQL twin included) in order to serve one backend's optional
+     *    locking;
+     *  · a lock released by a verb nobody is required to call fails WORSE than no lock: a crash leaves a
+     *    stale lease that blocks a store which today simply works, and the recovery is manual;
+     *  · the single-writer premise is the deployment's to make. The assembled backend is where it is
+     *    enforced, and a directly-constructed store is the same "I know what I am doing" path every
+     *    sibling file store in this family offers.
+     * A deployment that needs cross-process exclusion takes the assembled backend, or brings its own.
+     */
+    exportHistory?(scope: string): Promise<FileHistoryExport | null>;
+    importHistory?(scope: string, data: FileHistoryExport, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileHistoryResult>;
+}
+/**
+ * design/381 §3 + §10 T-5 — the FENCING judge for a boundary-capture attempt, exposed as a
+ * direct-callable function (the G6b grey-box seat) and used by every in-tree backend as the single
+ * commit gate: an attempt whose signal fired — timeout or abort, no matter how close to completion
+ * the capture got — may NEVER publish its mapping. ABSOLUTE, no grace threshold (§10 T-5: "无宽限
+ * 期" — the verdict has no time axis at all): a late-completing capture may have read bytes AFTER
+ * the lease closed (post-edit bytes), and publishing them under the pre-turn key is exactly the
+ * poisoning the fence exists to stop.
+ */
+export declare function boundaryPublishVerdict(attempt: {
+    aborted: boolean;
+}): {
+    publish: true;
+} | {
+    publish: false;
+    reason: "aborted";
+};
+/** One captured state of one file, as read through the env (the shared capture half). */
+export type FileBackupCapture = 
+/** `mode` = the env's POSIX permission bits when it HAS that face (design/381 DV-8); absent when
+ *  the env cannot express them — never fabricated, so a restore can tell "this mode was recorded
+ *  and could not be applied" from "there was never a mode to keep". */
+{
+    state: "file";
+    bytes: Uint8Array;
+    hash: string;
+    mode?: number;
+    parentIdent?: string;
+} | {
+    state: "absent";
+    parentIdent?: string;
+} | {
+    state: "aborted";
+}
+/** Non-ENOENT read failure: the file may exist but its bytes are not capturable right now. */
+ | {
+    state: "unreadable";
+    cause: string;
+};
+/**
+ * Capture ONE file's current state through the ExecutionEnv — **the env-operating half every
+ * backend MUST reuse** (design/381 §3 分工, the E19 captureManifest condition carried forward:
+ * re-implementing it per backend is how symlink-escape/fail-closed bugs come back). Used by
+ * `trackEdit` (first-touch pristine) and `snapshot` (per-file re-read). `not_found` is the sole
+ * absent signal (the read itself is the authoritative existence probe — a separate stat would only
+ * re-open the same race one window later). The parent-identity guard rides the same frame:
+ * `canonicalPath(parent)` — root-relativized when under `root` (DV-6: a legal whole-root move must
+ * keep verifying; an in-root parent-chain swap must keep refusing) — recorded best-effort (an env
+ * that cannot canonicalize omits it; the slice-3 preflight then has nothing to compare, which is
+ * the honest degraded form, never a fabricated identity).
+ */
+export declare function captureFileBackupViaEnv(env: ExecutionEnv, absPath: string, root: string, signal?: AbortSignal): Promise<FileBackupCapture>;
+/**
+ * The retraction PROOF READ (design/381 #491 + adversarial round 2), shared by every backend so the
+ * evidence rule cannot drift: does the path still look exactly as the first touch recorded it? An
+ * existed-not mint requires the path to still be absent; a captured mint requires the same content
+ * hash. Anything else — including an unreadable path — leaves the record standing, because the only
+ * failure this arm exists to distinguish is "the write never landed" from "the write may have
+ * changed the file". A base-unavailable marker is REFUSED here rather than waved through
+ * (adversarial round 3): it carries no bytes to compare, but the marker itself is the durable
+ * refusal state that stops a later touch from minting already-modified bytes as pristine — erasing
+ * it on an ambiguous failure re-opens exactly the DV-14 hole it exists to close. It stays
+ * retractable through the `"proven"` path, which needs no evidence read at all.
+ */
+export declare function worldStillMatchesMint(env: ExecutionEnv, absPath: string, root: string, baseAvailable: boolean, mintedBlobHash: string | null, signal?: AbortSignal): Promise<{
+    unchanged: true;
+} | {
+    unchanged: false;
+    reason: string;
+}>;
+/**
+ * DV-13's metadata rule applied to the MODE axis (design/381 slice 3), and it is a rule about
+ * EVIDENCE rather than about equality: metadata may prove two states DIFFERENT, never the same. Two
+ * known-and-unequal modes are a proven difference, so the file is versioned again even though its
+ * bytes are identical (the permission bit is part of the state a rewind restores). An UNKNOWN mode
+ * on either side proves nothing and must not manufacture a version — which is also what keeps a
+ * graph captured before this field existed from re-versioning its whole tracked set on the first
+ * boundary after an upgrade.
+ */
+export declare function modeProvenDifferent(recorded: number | undefined, current: number | undefined): boolean;
+/** The target one file must converge to (bytes+hash, or "must not exist"). */
+export type FileRestoreTarget = {
+    bytes: Uint8Array;
+    hash: string;
+} | {
+    absent: true;
+};
+/**
+ * The recorded facts the slice-3 preflight judges the current world against, plus the abort signal
+ * (design/381 §6 slice 3). Every member is OPTIONAL on purpose: a record captured by an env without
+ * the mode face, or without canonicalization, carries neither — and a guard with nothing recorded to
+ * compare must degrade to "no opinion", never to a fabricated expectation.
+ */
+export interface FileRestoreApplyOptions {
+    /** The task root the recorded key was re-joined against — the coordinate `parentIdent` lives in. */
+    root: string;
+    /** The parent identity recorded WITH the version being restored ({@link parentIdentityViaEnv}). */
+    parentIdent?: string;
+    /** The POSIX mode recorded with the version being restored (design/381 DV-8). */
+    mode?: number;
+    signal?: AbortSignal;
+}
+export type FileRestoreApplyOutcome = 
+/** `modeNotPreserved` rides the two NON-refusal arms: the bytes converged but the recorded mode
+ *  could not be re-applied (no env mode face, or the env refused/failed the change). A disclosure,
+ *  never a failure — the file's CONTENT is what the restore promised. */
+{
+    outcome: "applied";
+    modeNotPreserved?: true;
+} | {
+    outcome: "identical";
+    modeNotPreserved?: true;
+} | {
+    outcome: "refused";
+    reason: string;
+} | {
+    outcome: "failed";
+    reason: string;
+};
+/**
+ * Converge ONE file to `target` through the ExecutionEnv — **the env-operating + security half
+ * every backend MUST reuse** (design/381 §3 分工). skip-if-identical is content-hash proven (DV-13:
+ * metadata may only ever prove INEQUALITY, never equality; mtime is never consulted), so an
+ * identical file is untouched (no write, no mtime churn). Deletion markers remove the current file
+ * (ENOENT tolerated = already converged).
+ *
+ * THE PREFLIGHT FAMILY (design/381 slice 3, DV-6 — the env-level approximation of the reference's
+ * fd-level `O_NOFOLLOW` + dev/ino re-check, ordered cheapest-refusal-first). Every arm SKIPS the
+ * one file and is counted; none of them fails the whole restore:
+ *  · KIND — the addressed object (no-follow `fileInfo`) must be a regular file or absent. A symlink
+ *    at the leaf is refused rather than followed: the recorded bytes belong to the file the agent
+ *    edited, not to whatever a link now points at. A directory/socket/FIFO in its place is the same
+ *    refusal for the same reason.
+ *  · PARENT CHAIN — the current canonical parent identity must equal the one recorded with the
+ *    version ({@link parentIdentityViaEnv}, root-relative under the root). A legal whole-root move
+ *    keeps it equal (E4 passes); an in-root ancestor swapped for a link out of the tree does not
+ *    (E5 refuses, and nothing outside the root is written). BOTH must hold at once — relaxing to
+ *    "moves also refuse" or "swaps also pass" is a mis-fix, not a tuning choice.
+ *  · The guard is EVIDENCE-BASED, not assumption-based: a record with no parent identity (an env
+ *    that cannot canonicalize) and a parent that cannot be canonicalized NOW (the ordinary "the
+ *    directory was deleted and this restore recreates it" case) both mean "nothing to compare", and
+ *    inventing a refusal there would break the recreate arm rather than close a hole.
+ *
+ * THE WRITE uses `env.writeFileGuarded` when the env has it — one atomic verify-and-write whose
+ * expectation names the addressed path and forbids following a leaf link, so the window between
+ * this preflight and the write is closed at the backend. An env WITHOUT it falls back to plain
+ * `env.writeFile` and the convergence is then ADVISORY on the TOCTOU axis: the preflight above is a
+ * check-then-act, and a sufficiently fast racer can still swap the leaf in between. Stated here
+ * because the alternative — a two-step emulation behind an atomic-looking face — is exactly what
+ * that capability's own contract forbids.
+ *
+ * MODE (DV-8): a recorded mode is re-applied through the optional `setFileMode` face after the
+ * bytes land (and on an otherwise-identical file whose mode drifted, which IS a convergence). An env
+ * without the face — or one that refuses the change — yields `modeNotPreserved`, disclosed by the
+ * caller's ledger; it never turns a successful content restore into a failure.
+ */
+export declare function applyFileRestoreViaEnv(env: ExecutionEnv, absPath: string, target: FileRestoreTarget, opts: FileRestoreApplyOptions): Promise<FileRestoreApplyOutcome>;
+/**
+ * ONE file's contribution to {@link FileHistoryStore.diffStats}, shared by both bundled backends:
+ * `undefined` = this file would NOT change (already at the target, or already absent for a deletion
+ * marker), otherwise the line arithmetic of the change. Content-hash proven, exactly like the
+ * restore's own identical-skip — a preview that used a cheaper test than the operation it previews
+ * would disagree with it.
+ */
+export declare function previewFileDelta(env: ExecutionEnv, absPath: string, targetHash: string | null, targetBytes: Uint8Array | undefined, targetMode?: number): Promise<{
+    insertions: number;
+    deletions: number;
+} | undefined>;
+interface FileHistoryVersionRecord {
+    version: number;
+    /** Content-addressed blob hash, or null = "did not exist at this point" (existed-not marker —
+     *  serves both the pre-creation v1 arm and later deletion arms). */
+    blobHash: string | null;
+    mode?: number;
+    parentIdent?: string;
+    backupTime: string;
+}
+interface TrackedFileState {
+    /** DV-14: false ⇒ the pristine base could not be captured; a durable refusal state, not an
+     *  absence — versions then start ABOVE v1 and v1 is never minted later. */
+    baseAvailable: boolean;
+    /** The key's self-description (§3 amendment): recorded at the mint so a graph that later crosses
+     *  machines can be judged instead of guessed. */
+    keyDesc: FileHistoryTrackKeyDescriptor;
+    /** Set when a LATER trackEdit for this path was served (answered `minted:false`) — that lane is
+     *  now relying on this record as its own pre-edit baseline, so the original minter may no longer
+     *  retract it (adversarial round 1: two lanes racing one path, the first failing its write, would
+     *  otherwise delete the baseline the SECOND lane's successful edit depends on). */
+    observedByLaterTouch?: boolean;
+    versions: FileHistoryVersionRecord[];
+}
+/** One staged per-file outcome of a capture attempt (commit assigns version numbers atomically). */
+type StagedFileCapture = {
+    kind: "unchanged";
+    version: number;
+} | {
+    kind: "changed";
+    blobHash: string | null;
+    mode?: number;
+    parentIdent?: string;
+};
+/**
+ * In-memory, content-addressed reference {@link FileHistoryStore}. Blobs are deduplicated by sha256
+ * ACROSS all scopes and versions (a file unchanged between boundaries stores zero new bytes); each
+ * tracked file keeps a version chain, each boundary a complete `trackKey → version` mapping over
+ * the tracked set as of its mint. Single-process (the default-deps reference; the durable
+ * file-backed impl is design/381 slice 2).
+ *
+ * Grey-box fault seams (design/381 §7 C7 / §10 T-4): `persistFirstTouch` and `publishBoundary` are
+ * `protected` COMMIT points — a test subclass overrides one to throw and the public verb answers
+ * the typed `{ok:false}` the contract promises (the store itself still never throws).
+ *
+ * RETENTION is built in (design/381 §片2): each committed boundary is followed by a trim back to
+ * {@link import("./file-history-retention.js").DEFAULT_FILE_HISTORY_BOUNDARY_KEEP} newest boundaries per scope, overridable through
+ * {@link InMemoryFileHistoryStoreOptions.retention}. Even a single-process reference store needs
+ * it — a long-lived process IS the unbounded case.
+ */
+export interface InMemoryFileHistoryStoreOptions {
+    /** design/381 §片2 — the built-in boundary bound and its override. Omitted ⇒ the engine default
+     *  ({@link import("./file-history-retention.js").DEFAULT_FILE_HISTORY_BOUNDARY_KEEP}); a malformed policy is REFUSED here, at the wiring
+     *  site, rather than silently becoming a different policy inside a GC pass nobody watches. */
+    retention?: FileHistoryRetentionPolicy;
+}
+export declare class InMemoryFileHistoryStore implements FileHistoryStore {
+    private readonly scopes;
+    /** Resolved boundary cap, or `null` for the explicit `"unbounded"` opt-out (host owns the GC). */
+    private readonly boundaryKeep;
+    private readonly blobs;
+    /** Blob hashes written by an in-flight capture BEFORE its commit — a racing reap must treat them
+     *  as live (same MAJOR-1 posture as the retired whole-tree store). REFCOUNTED, not a set
+     *  (adversarial round): two concurrent captures can lease the same new hash, and the first
+     *  attempt's release must not strip the second attempt's liveness. */
+    private readonly inFlightBlobs;
+    constructor(opts?: InMemoryFileHistoryStoreOptions);
+    /**
+     * The RETENTION pass, run after a boundary commits (design/381 §片2 — see {@link FileHistoryStore.reap}
+     * for why the backend owns this rather than the host). Boundaries are an insertion-ordered map
+     * here, so commit order is exact and the selection needs no clock.
+     *
+     * Never throws and never fails the commit that triggered it: the boundary is already published and
+     * a GC that could not run is a graph that is merely larger than its bound — the strictly safer of
+     * the two failure directions, and the same posture the reference implementation's own eviction has.
+     */
+    private applyBoundaryRetention;
+    private leaseBlob;
+    private releaseBlob;
+    private scope;
+    /** PROTECTED COMMIT SEAM (fault-injectable): durably record one path's first-touch state.
+     *  Synchronous single assignment = the "ONE atomic durable record" of DV-14 for this backend. */
+    protected persistFirstTouch(scope: string, key: string, state: TrackedFileState): void;
+    /** PROTECTED COMMIT SEAM (fault-injectable): publish a captured boundary in ONE synchronous step
+     *  — version records + mapping become visible together or not at all (atomic visibility). */
+    protected publishBoundary(scope: string, entryId: string, staged: Map<string, StagedFileCapture>): void;
+    trackEdit(scope: string, absPath: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileHistoryTrackResult>;
+    annulTrack(scope: string, absPath: string, root: string, verify?: {
+        env: ExecutionEnv;
+        signal?: AbortSignal;
+    }): Promise<FileHistoryResult>;
+    snapshot(scope: string, entryId: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileHistoryResult>;
+    restore(scope: string, entryId: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileHistoryRestoreResult>;
+    canRestore(scope: string, entryId: string): Promise<boolean>;
+    diffStats(scope: string, entryId: string, env: ExecutionEnv, root: string): Promise<FileHistoryDiffStats | null>;
+    reap(scope: string, keepEntryIds: string[]): Promise<number>;
+    adoptScope(fromScope: string, toScope: string): Promise<FileHistoryResult>;
+    exportHistory(scope: string): Promise<FileHistoryExport | null>;
+    /** The export projection as a SYNCHRONOUS function — the import's final claim needs to compare a
+     *  target's identity without yielding (see the publish step). */
+    private exportOf;
+    importHistory(scope: string, data: FileHistoryExport, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileHistoryResult>;
+    /** The import body inside the blob lease (see {@link importHistory}). */
+    private importStaged;
+}
+/** Test-only window (family-aware path-coordinate pins + the DV-6 track-key coordinate): pure
+ *  helpers whose behavior carries a fence/restore invariant. Not re-exported from src/index.ts. */
+export declare const __testables: {
+    joinUnder: typeof joinUnder;
+    relUnder: typeof relUnder;
+    stripTrailSep: (p: string) => string;
+    trackKeyOf: typeof trackKeyOf;
+    resolveTrackKey: typeof resolveTrackKey;
+    parentDirOf: typeof parentDirOf;
+};
+export {};