@sema-agent/core 7.48.0 → 7.49.0

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

@@ -107,6 +107,19 @@ export declare function deriveControlPlaneDir(configRoot: string, key: string):
  *  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;
+/**
+ * THE control plane of the memory store at `dir` — the one reading every opener (the file backend, the
+ * engine, the runner's plane assembly) and {@link reanchorMemoryStoreRoot} resolve through, so the plane a
+ * store's root anchor is read from is the plane it was written to. A backend that pins its own control
+ * plane (`pinnedBy.controlPlaneRoot` — the file backend) wins, else the explicit `controlDir`, else the
+ * derivation off the config root ({@link deriveControlPlaneDir}) — preceded by the one-shot move of a plane
+ * minted under the canonical key ({@link adoptCanonicalKeyedControlDir}), which is why that arm is not pure.
+ */
+export declare function effectiveControlRootOf(dir: string, opts?: {
+    controlDir?: string;
+    pinnedBy?: unknown;
+    onIncident?: MemoryPartitionIncidentSink;
+}): 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
@@ -277,11 +290,17 @@ declare const SCOPE_HOME_FORM_PHRASE: {
     readonly other: "a special file";
 };
 export type HomeFormPhraseCoversEveryForm = AssertAllKeysHandled<Exclude<ScopeHomeForm, keyof typeof SCOPE_HOME_FORM_PHRASE>>;
-/** What a store-form refusal carries beside its sentence. The ONE host path lives here and never in the
- *  sentence; `form` is present on {@link SCOPE_HOME_NOT_DIRECTORY} only. */
+/** What a store-form refusal carries beside its sentence. Host paths live here and never in the sentence;
+ *  `form` is present on {@link SCOPE_HOME_NOT_DIRECTORY} only; `controlDir`, `recorded` and `now` are present
+ *  together on a moved store root only ({@link storeRootMovedRefusal}): the control plane whose root anchor
+ *  refused (the `controlDir` to hand {@link reanchorMemoryStoreRoot}), the physical root the anchor records,
+ *  and where the root resolves now. */
 export type StoreFormRefusalDetail = {
     readonly path: string;
     readonly form?: ScopeHomeForm;
+    readonly controlDir?: string;
+    readonly recorded?: string;
+    readonly now?: string;
 };
 /** A refusal the store's physical form earns: a plain `Error` (never the control-plane-damage class —
  *  the engine's own account is intact, the layout it was handed is not the layout it needs) carrying a
@@ -293,14 +312,28 @@ export type StoreFormRefusal = Error & {
 /** Seat 1 — an act the store's physical form refuses: `act` names what was refused (no path), `path` is the
  *  target whose directory resolves outside the store ({@link landsOutsideStore}). */
 export declare function storeActRefusal(act: string, path: string): StoreFormRefusal;
-/** Seat 2 — the store root now resolves to another directory than the one the `holder` first opened; `path` is
- *  the root's spelling. */
-export declare function storeRootMovedRefusal(holder: "backend" | "engine", path: string): StoreFormRefusal;
+/** Seat 2 — the store root no longer resolves to the physical root its control plane's anchor records
+ *  ({@link anchorStoreRoot}); `path` is the root's spelling. The remedy names its arguments by their
+ *  `detail` keys, so the sentence stays path-free and the call is still copyable. */
+export declare function storeRootMovedRefusal(path: string, anchor: {
+    controlDir: string;
+    recorded: string;
+    now: string;
+}): StoreFormRefusal;
+/** Seat 2, the root gone: the anchored root no longer exists while its control plane holds a store's account
+ *  ({@link anchorStoreRoot}). A missing root lands where it would be created — the recorded one — so only
+ *  its absence tells a store moved away (or deleted) from one never opened; the root is not re-created. */
+export declare function storeRootAbsentRefusal(path: string, anchor: {
+    controlDir: string;
+    recorded: string;
+    now: string;
+}): StoreFormRefusal;
 /** Seat 3 — a scope home that is not a real directory. */
 export declare function scopeHomeRefusal(form: ScopeHomeForm, path: string): StoreFormRefusal;
 /** Where an act at `p` lands: the physical path of its normalized spelling (the spelling a child path
  *  joined under it carries), a MISSING tail rejoined under the deepest existing directory (what the act
- *  creates). Any other resolution fault (EACCES, ELOOP, ENOTDIR) is THROWN as itself: an act that
+ *  creates) — a dangling link on that tail followed to where it points (what the act would create through
+ *  it). Any other resolution fault (EACCES, ELOOP, ENOTDIR) is THROWN as itself: an act that
  *  cannot be placed is not performed — a failed resolution never implies the act would fail too
  *  (a link whose own mode refuses `realpath` is still followed by `unlink` and `rename`). */
 export declare function landingPathOf(p: string): string;
@@ -320,6 +353,103 @@ export declare function landingPathOf(p: string): string;
 export declare function landsOutsideStore(physicalRoot: string, target: string): boolean;
 /** mkdir -p convenience used by the engine/backend (0o700 like the file stores). */
 export declare function ensureDirExists(dir: string): void;
+/** The committed-rev ledger's file name (the file backend's account). Named here because the anchor reads
+ *  its presence as "this control plane already holds a store". */
+export declare const LEDGER_FILE = "revs.json";
+/** The control-plane file recording the store root's physical path ({@link anchorStoreRoot}). */
+export declare const ROOT_ANCHOR_FILE = "root-anchor.json";
+/** What an ABSENT anchor means: a control plane holding nothing records the root (a first open); one already
+ *  holding a store backfills while the arm is open and refuses once it is not. */
+export declare function absentAnchorReading(controlPlaneHoldsStore: boolean, backfillArmOpen?: boolean): "record" | "backfill" | "refuse";
+/** Options of {@link anchorStoreRoot}. */
+export interface AnchorStoreRootOptions {
+    /** Where `memory.root_anchor_backfilled` goes. */
+    onIncident?: MemoryPartitionIncidentSink;
+    /** The clock `recordedAt` reads (the opener's injected clock). */
+    now?: () => number;
+}
+/**
+ * THE store-root check, run by every opener (a file backend's construction, an engine's mount) and at the
+ * head of every face that acts on the store: where the root `dir` physically resolves NOW, against the
+ * anchor its control plane records. Equal ⇒ the anchored root, the one every act at a store path is judged
+ * against. Unequal ⇒ {@link storeRootMovedRefusal}; equal but the root gone while the control plane holds a
+ * store ⇒ {@link storeRootAbsentRefusal} — both thrown before anything in the store is written or the root is
+ * created (only the anchor answers where the root is; a `mkdir` in its place does not). No anchor ⇒ {@link absentAnchorReading}, decided under the anchor's lock (a racing opener
+ * that recorded it first is judged against): a control plane holding nothing creates the root and records
+ * it; one already holding a store backfills it and discloses `memory.root_anchor_backfilled` (its root may
+ * already have been re-pointed — undecidable, said). Nothing is kept between calls: the anchor is read every
+ * time, so a re-anchor ({@link reanchorMemoryStoreRoot}) reaches every live holder at its next face.
+ */
+export declare function anchorStoreRoot(dir: string, controlDir: string, opts?: AnchorStoreRootOptions): string;
+/** The redo journal a File store's transaction writes as its commit marker (control plane). */
+export declare const STORE_JOURNAL_FILE = "journal.json";
+/** The transaction lock's directory in the control plane; `owner` inside holds the holder's token. */
+export declare const STORE_TXN_LOCK_DIR = "txn.lock";
+/** A lock older than this is a crashed holder (stolen; the journal recovery inside the lock makes the steal safe). */
+export declare const TXN_LOCK_STALE_MS = 30000;
+/** Test hook: small constants so a crash-window leg does not really wait 15–30 s. */
+export interface TxnLockTimings {
+    staleMs?: number;
+    waitMs?: number;
+    stealGraceMs?: number;
+}
+/** A held transaction lock: its token, and a release that removes the lock only while the token is still ours. */
+export interface StoreTxnLock {
+    readonly token: string;
+    readonly release: () => void;
+}
+/**
+ * One attempt at the store's transaction lock (synchronous): the lock, or `undefined` while another holder has
+ * it. Only the lock directory's EEXIST is contention; every other failure — the control plane unmakeable, a
+ * probe or steal that faults, an occupant that is not a directory — throws {@link ControlPlaneCorruptError}
+ * (a fault is never read as "busy, retry later"). Every acquisition writes an owner token (crypto-random)
+ * before it returns. A held lock past its stale line (`now` against its mtime) that carries a token is a
+ * crashed holder: stolen single-winner (an atomic rename to a unique tombstone; a racer's lost rename is
+ * ENOENT) and re-attempted through a normal `mkdir` — never a bare rm + mkdir. A tokenless lock is a
+ * mid-acquisition, never stolen. `observed` hears each held lock's mtime (a waiter's deadline extension).
+ */
+export declare function tryStoreTxnLock(controlDir: string, opts: {
+    now: () => number;
+    staleMs?: number;
+    observed?: (mtimeMs: number) => void;
+}): StoreTxnLock | undefined;
+/** The commit boundary of a store transaction: the lock still names `token` — an absent or unreadable owner (a
+ *  stolen, tombstoned lock) is lost too. A holder that stalled past the stale line was stolen from; acting on
+ *  would overwrite the stealer's transaction. */
+export declare function assertStoreTxnLockOwnership(controlDir: string, token: string): void;
+/** Wait for the store's transaction lock: one {@link tryStoreTxnLock} per round, paced 20–60 ms (the wait
+ *  yields the event loop every round), until the deadline — `waitMs`, extended to an observed lock's stale
+ *  line plus the steal grace. Past it: a loud timeout. */
+export declare function acquireStoreTxnLock(controlDir: string, opts: {
+    now: () => number;
+    timings?: TxnLockTimings;
+}): Promise<StoreTxnLock>;
+/** What {@link reanchorMemoryStoreRoot} changed. */
+export interface StoreRootReanchor {
+    /** The physical root the anchor recorded before; absent when no readable anchor stood. */
+    readonly from?: string;
+    /** The physical root it records now. */
+    readonly to: string;
+    /** The control plane the anchor lives in. */
+    readonly controlDir: string;
+}
+/**
+ * The ONE way a recorded root anchor changes: point it at where `dir` resolves now — a store moved on
+ * purpose, or an anchor that is damaged. `opts.controlDir` names the store's control plane exactly as its
+ * opener does (the explicit `controlDir` the backend / engine was given, absent for the derived one) and
+ * resolves through the same reading ({@link effectiveControlRootOf}). Refused (`config.memory_reanchor`) when
+ * `dir` is not an existing directory, and when that control plane holds neither an anchor nor a store — a
+ * mistaken `controlDir` would otherwise record an anchor no opener reads. Moves nothing and says nothing
+ * about whether the directory holds the same store. A re-anchor is a transaction of the store: it holds the
+ * store's transaction lock ({@link acquireStoreTxnLock}; a commit in progress is waited for, never crossed) and
+ * is refused while a committed transaction is pending recovery (its journal names paths under the recorded
+ * root: replayed there first, never carried over). Every live holder judges against the new anchor at its
+ * next face. Discloses `memory.root_reanchored` on `opts.onIncident`.
+ */
+export declare function reanchorMemoryStoreRoot(dir: string, opts?: {
+    controlDir?: string;
+    onIncident?: MemoryPartitionIncidentSink;
+}): Promise<StoreRootReanchor>;
 /** The one remedy every surfaced permission refusal carries — `undefined` unless `err` is a write
  *  the file system refused on PERMISSIONS (`EACCES` / `EPERM`) at a path INSIDE `memoryDir` (a
  *  refusal elsewhere — a control plane kept outside the store — is not this store's to fix). The
@@ -446,9 +576,9 @@ export interface SidecarLockOptions {
  *  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. */
+ *  condition that keeps answering the same way spun this synchronous loop at full speed and never
+ *  reached its own cap. Only a held lock (EEXIST) is waited on: a lock directory that cannot be created
+ *  (read-only mount, full volume, revoked permission, a missing parent) throws its own error at once. */
 export declare function acquireSidecarLock(lockDir: string, opts?: SidecarLockOptions): string;
 /** 证伪式复审 L2-analog: re-verify the owner token at the COMMIT POINT — a stolen-from holder
  *  aborts instead of writing over the stealer. A FOREIGN token always aborts (positive proof the

package/dist/core/memory-engine/layout.js

@@ -1,7 +1,7 @@
-import { closeSync, constants as fsConstants, copyFileSync, existsSync, fstatSync, fsyncSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync } from "node:fs";
+import { closeSync, constants as fsConstants, copyFileSync, existsSync, fstatSync, fsyncSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync } from "node:fs";
 const { O_WRONLY, O_RDONLY, O_CREAT, O_NOFOLLOW, O_NONBLOCK, O_EXCL } = fsConstants;
 import { homedir } from "node:os";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { MEMORY_ORIGIN_CAUSES } from "./types.js";
 import { physicalPathOf, physicalPathOfExisting, priorCallerCasedPathOf } from "../physical-path.js";
@@ -187,6 +187,16 @@ export function deriveControlPlaneDir(configRoot, key) {
 export function deriveRepoControlPlaneDir(configRoot, repoRoot) {
     return join(configRoot, deriveRepoKey(repoRoot), CONTROL_PLANE_DIR);
 }
+export function effectiveControlRootOf(dir, opts = {}) {
+    const pinned = opts.pinnedBy?.controlPlaneRoot;
+    if (typeof pinned === "string" && pinned !== "")
+        return pinned;
+    if (opts.controlDir !== undefined)
+        return opts.controlDir;
+    const configRoot = resolveMemoryEngineRoot();
+    adoptCanonicalKeyedControlDir(configRoot, dir, opts.onIncident);
+    return deriveControlPlaneDir(configRoot, dir);
+}
 export function resolveMemoryEngineRoot(explicit) {
     const raw = explicit ?? process.env.AGENT_DATA_DIR ?? join(homedir(), ".ai-agent");
     return isAbsolute(raw) ? raw : resolve(raw);
@@ -749,21 +759,45 @@ function storeFormRefusal(code, sentence, detail) {
 export function storeActRefusal(act, path) {
     return storeFormRefusal(TARGET_OUTSIDE_STORE, `${act} was refused — its directory resolves outside the store root; not performed`, { path });
 }
-export function storeRootMovedRefusal(holder, path) {
-    return storeFormRefusal(TARGET_OUTSIDE_STORE, `the ${holder === "backend" ? "store root" : "memory dir"} now resolves to a different directory than the one this ${holder} ${holder === "backend" ? "opened" : "first mounted"} — refused; open a new ${holder} on the directory you mean`, { path });
+export function storeRootMovedRefusal(path, anchor) {
+    return storeFormRefusal(TARGET_OUTSIDE_STORE, "the store root now resolves to a different directory than the one its control plane records — refused, nothing in the store was written; put the directory back, or, if the store was moved on purpose, call reanchorMemoryStoreRoot(detail.path, { controlDir: detail.controlDir }) and reopen", { path, controlDir: anchor.controlDir, recorded: anchor.recorded, now: anchor.now });
+}
+export function storeRootAbsentRefusal(path, anchor) {
+    return storeFormRefusal(TARGET_OUTSIDE_STORE, "the store root no longer exists where its control plane records it — refused, nothing in the store was written; put the directory back, or, if the store was moved on purpose, call reanchorMemoryStoreRoot with its new directory and { controlDir: detail.controlDir }; to start over in place, create the directory, then call reanchorMemoryStoreRoot(detail.path, { controlDir: detail.controlDir }) and reopen", { path, controlDir: anchor.controlDir, recorded: anchor.recorded, now: anchor.now });
 }
 export function scopeHomeRefusal(form, path) {
     return storeFormRefusal(SCOPE_HOME_NOT_DIRECTORY, `a scope home must be a real directory, but this one is ${SCOPE_HOME_FORM_PHRASE[form]} — refused (fail-closed); put the real directory back`, { path, form });
 }
 export function landingPathOf(p) {
-    const normalized = resolve(p);
+    return landingPathWithin(resolve(p), 0);
+}
+const MAX_LANDING_LINK_HOPS = 40;
+function landingPathWithin(normalized, hops) {
     try {
         return physicalPathOf(normalized);
     }
     catch (err) {
         if (err.code !== "ENOENT")
             throw err;
-        return canonicalize(normalized);
+    }
+    const tail = [];
+    for (let cur = normalized;;) {
+        const st = lstatOrAbsent(cur);
+        if (st?.isSymbolicLink() === true) {
+            if (hops >= MAX_LANDING_LINK_HOPS) {
+                const e = new Error(`ELOOP: too many symbolic links resolving ${normalized}`);
+                e.code = "ELOOP";
+                throw e;
+            }
+            return landingPathWithin(join(resolve(dirname(cur), readlinkSync(cur)), ...[...tail].reverse()), hops + 1);
+        }
+        if (st !== undefined)
+            return canonicalize(normalized);
+        const parent = dirname(cur);
+        if (parent === cur)
+            return normalized;
+        tail.push(basename(cur));
+        cur = parent;
     }
 }
 export function landsOutsideStore(physicalRoot, target) {
@@ -774,6 +808,313 @@ export function ensureDirExists(dir) {
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true, mode: 0o700 });
 }
+export const LEDGER_FILE = "revs.json";
+export const ROOT_ANCHOR_FILE = "root-anchor.json";
+const ANCHOR_BACKFILL_ARM_OPEN = true;
+export function absentAnchorReading(controlPlaneHoldsStore, backfillArmOpen = ANCHOR_BACKFILL_ARM_OPEN) {
+    if (!controlPlaneHoldsStore)
+        return "record";
+    return backfillArmOpen ? "backfill" : "refuse";
+}
+function reanchorRemedy(dir, controlDir) {
+    return `once the store root is where it belongs, call reanchorMemoryStoreRoot(${JSON.stringify(dir)}, { controlDir: ${JSON.stringify(controlDir)} }) and reopen`;
+}
+function damagedAnchorError(controlDir, dir, why, cause) {
+    return new ControlPlaneCorruptError(`memory store root anchor ${join(controlDir, ROOT_ANCHOR_FILE)} is damaged (${why}) — the store root cannot be checked against it, so nothing in the store was opened; ${reanchorRemedy(dir, controlDir)}`, cause !== undefined ? { cause } : undefined);
+}
+function readStoreRootAnchor(controlDir, dir) {
+    let raw;
+    let fd;
+    try {
+        fd = openSync(join(controlDir, ROOT_ANCHOR_FILE), O_RDONLY | O_NOFOLLOW | O_NONBLOCK);
+        if (!fstatSync(fd).isFile())
+            throw damagedAnchorError(controlDir, dir, "not a regular file");
+        raw = readFileSync(fd, "utf8");
+    }
+    catch (err) {
+        if (err instanceof ControlPlaneCorruptError)
+            throw err;
+        const code = err.code;
+        if (code === "ENOENT" && fd === undefined)
+            return undefined;
+        throw damagedAnchorError(controlDir, dir, code === "ELOOP" ? "a symbolic link, not the record" : `unreadable: ${code ?? thrownLabel(err)}`, err);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw damagedAnchorError(controlDir, dir, "not JSON", err);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        throw damagedAnchorError(controlDir, dir, "not an object");
+    const a = parsed;
+    if (a.v !== 1)
+        throw damagedAnchorError(controlDir, dir, `unknown version ${JSON.stringify(a.v) ?? typeof a.v}`);
+    if (typeof a.realpath !== "string" || !isAbsolute(a.realpath))
+        throw damagedAnchorError(controlDir, dir, "realpath is not an absolute path");
+    if (typeof a.spelling !== "string" || typeof a.recordedAt !== "number" || !Number.isFinite(a.recordedAt))
+        throw damagedAnchorError(controlDir, dir, "spelling / recordedAt out of shape");
+    return { v: 1, realpath: a.realpath, spelling: a.spelling, recordedAt: a.recordedAt };
+}
+function controlPlaneHoldsStore(controlDir) {
+    return lstatOrAbsent(join(controlDir, SCOPES_FILE)) !== undefined || lstatOrAbsent(join(controlDir, LEDGER_FILE)) !== undefined;
+}
+function judgeAgainstAnchor(dir, controlDir, anchor) {
+    const now = landingPathOf(dir);
+    if (now !== anchor.realpath)
+        throw storeRootMovedRefusal(dir, { controlDir, recorded: anchor.realpath, now });
+    if (lstatOrAbsent(now) === undefined && controlPlaneHoldsStore(controlDir))
+        throw storeRootAbsentRefusal(dir, { controlDir, recorded: anchor.realpath, now });
+    return now;
+}
+function writeStoreRootAnchor(controlDir, lock, token, anchor) {
+    assertSidecarLockOwnership(lock, token, "memory store root anchor", "strict");
+    atomicWriteFileSync(join(controlDir, ROOT_ANCHOR_FILE), `${JSON.stringify(anchor, null, 2)}\n`);
+}
+export function anchorStoreRoot(dir, controlDir, opts = {}) {
+    const anchor = readStoreRootAnchor(controlDir, dir);
+    if (anchor !== undefined)
+        return judgeAgainstAnchor(dir, controlDir, anchor);
+    ensureDirExists(controlDir);
+    const lock = join(controlDir, `${ROOT_ANCHOR_FILE}.lock`);
+    const token = acquireSidecarLock(lock, { onDeadline: "throw" });
+    try {
+        const raced = readStoreRootAnchor(controlDir, dir);
+        if (raced !== undefined)
+            return judgeAgainstAnchor(dir, controlDir, raced);
+        const reading = absentAnchorReading(controlPlaneHoldsStore(controlDir));
+        if (reading === "refuse")
+            throw damagedAnchorError(controlDir, dir, "absent, while the control plane holds a store");
+        ensureDirExists(dir);
+        const realpath = landingPathOf(dir);
+        writeStoreRootAnchor(controlDir, lock, token, { v: 1, realpath, spelling: dir, recordedAt: (opts.now ?? Date.now)() });
+        if (reading === "backfill") {
+            discloseLayoutIncident(opts.onIncident, "memory.root_anchor_backfilled", `memory store root anchor recorded for a store that had none: ${dir} resolves to ${realpath} (control plane ${controlDir}) — from now on the store opens only there; where the root resolved before this open cannot be told`);
+        }
+        return realpath;
+    }
+    finally {
+        releaseSidecarLock(lock, token);
+    }
+}
+export const STORE_JOURNAL_FILE = "journal.json";
+export const STORE_TXN_LOCK_DIR = "txn.lock";
+export const TXN_LOCK_STALE_MS = 30_000;
+const TXN_LOCK_WAIT_MS = 15_000;
+const TXN_LOCK_STEAL_GRACE_MS = 250;
+export function tryStoreTxnLock(controlDir, opts) {
+    const lockDir = join(controlDir, STORE_TXN_LOCK_DIR);
+    const ownerPath = join(lockDir, "owner");
+    const staleMs = opts.staleMs ?? TXN_LOCK_STALE_MS;
+    const faultText = (err) => err.code ?? "io error";
+    const tryMkdir = () => {
+        try {
+            mkdirSync(controlDir, { recursive: true });
+        }
+        catch (err) {
+            throw new ControlPlaneCorruptError(`memory control-plane root could not be created (${faultText(err)}) at ${controlDir} — a lock-acquisition fault is not contention (fail-closed)`, { cause: err });
+        }
+        try {
+            mkdirSync(lockDir);
+            return true;
+        }
+        catch (err) {
+            if (err.code === "EEXIST")
+                return false;
+            throw new ControlPlaneCorruptError(`memory txn lock could not be created (${faultText(err)}) at ${lockDir} — a lock-acquisition fault is not contention (fail-closed)`, { cause: err });
+        }
+    };
+    let acquired = tryMkdir();
+    if (!acquired) {
+        let mtimeMs;
+        try {
+            mtimeMs = statSync(lockDir).mtimeMs;
+            opts.observed?.(mtimeMs);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                throw new ControlPlaneCorruptError(`memory txn lock state could not be probed (${faultText(err)}) at ${lockDir} — a probe failure is not contention (fail-closed)`, { cause: err });
+            }
+            let occupant;
+            try {
+                occupant = lstatSync(lockDir);
+            }
+            catch (lerr) {
+                if (lerr.code !== "ENOENT") {
+                    throw new ControlPlaneCorruptError(`memory txn lock re-probe failed (${faultText(lerr)}) at ${lockDir} — a probe failure is not contention (fail-closed)`, { cause: lerr });
+                }
+            }
+            if (occupant !== undefined && !occupant.isDirectory()) {
+                throw new ControlPlaneCorruptError(`memory txn lock path is occupied by an invalid node (a dangling symlink?) at ${lockDir} — not contention and not a release race; remove the occupant (fail-closed)`, { cause: err });
+            }
+            mtimeMs = undefined;
+        }
+        if (mtimeMs !== undefined && opts.now() - mtimeMs > staleMs) {
+            let tokenPresent = false;
+            try {
+                statSync(ownerPath);
+                tokenPresent = true;
+            }
+            catch (err) {
+                if (err.code !== "ENOENT") {
+                    throw new ControlPlaneCorruptError(`memory txn lock owner token could not be probed (${faultText(err)}) at ${ownerPath} — a probe failure is not a mid-acquisition (fail-closed)`, { cause: err });
+                }
+            }
+            if (tokenPresent) {
+                const tomb = join(controlDir, `${STORE_TXN_LOCK_DIR}.stale-${randomUUID()}`);
+                let stolen = false;
+                try {
+                    renameSync(lockDir, tomb);
+                    stolen = true;
+                }
+                catch (err) {
+                    if (err.code !== "ENOENT") {
+                        throw new ControlPlaneCorruptError(`memory txn lock stale-steal rename failed (${faultText(err)}) at ${lockDir} — a rename fault is not a lost race (fail-closed)`, { cause: err });
+                    }
+                }
+                if (stolen) {
+                    rmSync(tomb, { recursive: true, force: true });
+                    acquired = tryMkdir();
+                }
+            }
+        }
+        if (!acquired)
+            return undefined;
+    }
+    const token = randomUUID();
+    try {
+        const fd = openSync(ownerPath, "w", 0o600);
+        try {
+            writeAllSync(fd, token);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch (err) {
+        try {
+            rmSync(lockDir, { recursive: true, force: true });
+        }
+        catch {
+        }
+        throw new Error(`memory txn lock owner token could not be written at ${ownerPath}: ${thrownText(err)}`);
+    }
+    return {
+        token,
+        release: () => {
+            try {
+                if (readFileSync(ownerPath, "utf8") !== token)
+                    return;
+            }
+            catch {
+                return;
+            }
+            try {
+                rmSync(lockDir, { recursive: true, force: true });
+            }
+            catch {
+            }
+        },
+    };
+}
+export function assertStoreTxnLockOwnership(controlDir, token) {
+    let held;
+    try {
+        held = readFileSync(join(controlDir, STORE_TXN_LOCK_DIR, "owner"), "utf8");
+    }
+    catch {
+        held = undefined;
+    }
+    if (held !== token) {
+        throw new ControlPlaneCorruptError("txn lock ownership lost before commit (holder stalled past the stale deadline and was stolen from?) — transaction aborted, nothing was committed", { facet: "lock-ownership" });
+    }
+}
+export async function acquireStoreTxnLock(controlDir, opts) {
+    const staleMs = opts.timings?.staleMs ?? TXN_LOCK_STALE_MS;
+    const waitMs = opts.timings?.waitMs ?? TXN_LOCK_WAIT_MS;
+    const stealGraceMs = opts.timings?.stealGraceMs ?? TXN_LOCK_STEAL_GRACE_MS;
+    let deadline = Date.now() + waitMs;
+    for (;;) {
+        const lock = tryStoreTxnLock(controlDir, { now: opts.now, staleMs, observed: (mtimeMs) => (deadline = Math.max(deadline, mtimeMs + staleMs + stealGraceMs)) });
+        if (lock !== undefined)
+            return lock;
+        if (Date.now() > deadline) {
+            throw new Error(`memory txn lock timeout (${waitMs}ms, extended to the lock's stale line) at ${join(controlDir, STORE_TXN_LOCK_DIR)} — another writer is wedged?`);
+        }
+        await new Promise((r) => setTimeout(r, 20 + Math.floor(Math.random() * 40)));
+    }
+}
+function reanchorDestination(dir) {
+    let to;
+    try {
+        to = physicalPathOf(resolve(dir));
+    }
+    catch (err) {
+        throw reanchorRefusal(`the store root ${JSON.stringify(dir)} does not resolve (${err.code ?? thrownLabel(err)}) — put the directory in place first`);
+    }
+    if (lstatOrAbsent(to)?.isDirectory() !== true)
+        throw reanchorRefusal(`the store root ${JSON.stringify(dir)} resolves to ${to}, which is not a directory`);
+    return to;
+}
+function reanchorRefusal(sentence) {
+    const e = new Error(`reanchorMemoryStoreRoot: ${sentence}`);
+    e.code = "config.memory_reanchor";
+    return e;
+}
+export async function reanchorMemoryStoreRoot(dir, opts = {}) {
+    const controlDir = effectiveControlRootOf(dir, { controlDir: opts.controlDir, onIncident: opts.onIncident });
+    const to = reanchorDestination(dir);
+    const lock = join(controlDir, `${ROOT_ANCHOR_FILE}.lock`);
+    if (lstatOrAbsent(join(controlDir, ROOT_ANCHOR_FILE)) === undefined && !controlPlaneHoldsStore(controlDir)) {
+        throw reanchorRefusal(`the control plane ${controlDir} holds no store and no root anchor — nothing to re-anchor; pass the controlDir this store's backend / engine is opened with`);
+    }
+    const txn = await acquireStoreTxnLock(controlDir, { now: Date.now });
+    let from;
+    try {
+        const token = acquireSidecarLock(lock, { onDeadline: "throw" });
+        try {
+            try {
+                from = readStoreRootAnchor(controlDir, dir)?.realpath;
+            }
+            catch {
+                from = undefined;
+            }
+            try {
+                assertStoreTxnLockOwnership(controlDir, txn.token);
+            }
+            catch {
+                throw reanchorRefusal(`the store's transaction lock was lost while re-anchoring (held past its stale line and taken by another writer) — nothing changed; retry (control plane ${controlDir})`);
+            }
+            if (lstatOrAbsent(join(controlDir, STORE_JOURNAL_FILE)) !== undefined) {
+                throw reanchorRefusal(`a committed transaction is still pending recovery at the recorded root — put the store back at ${from ?? "the root it was last opened at"}, open it once so the journal replays, then re-anchor (control plane ${controlDir})`);
+            }
+            let still;
+            try {
+                still = reanchorDestination(dir);
+            }
+            catch {
+                still = undefined;
+            }
+            if (still !== to)
+                throw reanchorRefusal(`the store root ${JSON.stringify(dir)} moved while re-anchoring (it resolved to ${to} when the call began) — nothing changed; retry`);
+            writeStoreRootAnchor(controlDir, lock, token, { v: 1, realpath: to, spelling: dir, recordedAt: Date.now() });
+        }
+        finally {
+            releaseSidecarLock(lock, token);
+        }
+    }
+    finally {
+        txn.release();
+    }
+    discloseLayoutIncident(opts.onIncident, "memory.root_reanchored", `memory store root re-anchored: ${dir} now opens at ${to}${from !== undefined ? ` (was ${from})` : ""} — control plane ${controlDir}`);
+    return from !== undefined ? { from, to, controlDir } : { to, controlDir };
+}
 export function permissionRemedyOf(err, memoryDir) {
     const e = typeof err === "object" && err !== null ? err : undefined;
     if (e === undefined || (e.code !== "EACCES" && e.code !== "EPERM") || typeof e.path !== "string" || !isContainedIn(memoryDir, e.path))
@@ -965,7 +1306,9 @@ export function acquireSidecarLock(lockDir, opts = {}) {
             }
             return token;
         }
-        catch {
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
         }
         try {
             const age = Date.now() - statSync(lockDir).mtimeMs;

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

@@ -48,6 +48,16 @@ export declare function formatUserProjScope(principal: string, projectId: string
  * opaque behavior. NEVER call this on a deployment that has not opted in (see module header).
  */
 export declare function parseScopeKey(key: string): ParsedScopeKey;
+/**
+ * THE org-scope judge for a host that admits, stores or routes org keys: is `key` a well-formed v2 org
+ * scope — `org:` followed by ONE encoded segment ({@link encodeScopeSegment}'s alphabet, at most
+ * {@link SCOPE_SEGMENT_MAX_ENCODED} encoded characters, canonical spelling)? It is {@link parseScopeKey}'s own
+ * reading, asked as a yes/no: a malformed `org:` key (an unencoded non-ASCII character, an over-long
+ * segment, a non-canonical escape) answers `false` here where `parseScopeKey` would throw, and a key of any
+ * other kind (`user:`, `proj:`, an unprefixed opaque string) answers `false` too. A prefix-plus-any-non-space
+ * pattern restated outside core answers a different question and disagrees on exactly those inputs.
+ */
+export declare function isOrgScopeKey(key: string): boolean;
 /** True when a v2-parsed key belongs to a PERSONAL plane (`user:` / `userproj:`). */
 export declare function isPersonalScope(parsed: ParsedScopeKey): boolean;
 /** True when the key's AUTHORITY is central (design/142 §2 表: user/userproj/org rows) — these keys

package/dist/core/memory-engine/scope-contract.js

@@ -111,6 +111,14 @@ export function parseScopeKey(key) {
     }
     return { kind: "legacy", raw: key };
 }
+export function isOrgScopeKey(key) {
+    try {
+        return parseScopeKey(key).kind === "org";
+    }
+    catch {
+        return false;
+    }
+}
 export function isPersonalScope(parsed) {
     return parsed.kind === "user" || parsed.kind === "userproj";
 }

package/dist/core/memory-engine/session-incarnation.d.ts

@@ -1,16 +1,26 @@
 import { type MemoryPartitionIncidentSink, type SessionIdentityRead } from "./layout.js";
+/** The seat's resolver shape ({@link createSessionIncarnationSeat}). */
+export type SessionIncarnationResolver = (session: {
+    sessionId: string;
+}) => string | undefined;
+/**
+ * The resolver a Runner hands its engines, built from the ACQUIRED session's own row cells — the object
+ * the run's transcript lives in, so the seat and the transcript never name two occupants (a second
+ * lookup by id can answer a row that replaced it). `own` = that session's `incarnation`; a LINEAGE id
+ * answers the occupant recorded with the lineage (`lineage`, e.g. the fork's `forkedFromIncarnation`),
+ * never whoever holds that id now. Everything else, and an absent own token, is unknown (binds).
+ */
+export declare function sessionIncarnationResolver(sessionId: string, own: string | undefined, lineage: ReadonlyMap<string, string>): SessionIncarnationResolver;
 /** The current occupant's token, and the identity seat a per-session record read is made under. */
 export interface SessionIncarnationSeat {
     incarnationOf(sessionId: string): string | undefined;
     identityRead(sessionId: string): SessionIdentityRead;
 }
-/** Build the seat over a host resolver (absent ⇒ nothing stamped, nothing asked, every record binds
+/** Build the seat over a resolver (absent ⇒ nothing stamped, nothing asked, every record binds
  *  by id — the pre-incarnation answer). Both disclosures are DEDUPED on the axis their fact belongs to: the resolver
  *  fault once per engine (a wiring fact), a separation once per session id (a fact about that id). */
 export declare function createSessionIncarnationSeat(input: {
-    resolve: ((session: {
-        sessionId: string;
-    }) => string | undefined) | undefined;
+    resolve: SessionIncarnationResolver | undefined;
     onIncident: MemoryPartitionIncidentSink | undefined;
 }): SessionIncarnationSeat;
 /** Remember an in-process record under its session id, FIRST-WINS PER IDENTITY: this map is the