@sema-agent/core 5.22.0 → 5.24.0

package/dist/stores/file/adoption/marker.d.ts

@@ -0,0 +1,202 @@
+/**
+ * design/183 §3 (F-011) — the ROOT-level adoption marker: the durable phase truth of the data-root
+ * adoption state machine (the design/182 rule-bucket marker, generalized to the whole data root).
+ *
+ * Two shapes live in `<dataRoot>/adoption.json`:
+ *  - the IN-FLIGHT marker (`marker`): a monotonically-advanced `phase` plus per-leg completion bits
+ *    for the one leg class without a self-attesting completion predicate (row rewrites). While this
+ *    shape is on disk the root is FROZEN: every file store constructor refuses to build over it
+ *    ({@link assertAdoptionBootGate} — invariant I6), so no writer can serve a half-migrated root.
+ *  - the PERMANENT terminal record (`adopted`): never deleted. It is the idempotence anchor (a re-run
+ *    with the same (from → toPrincipal) short-circuits to the recorded receipt) and it carries the
+ *    IMMUTABLE report — the byte-stable half of every receipt.
+ *
+ * This module is deliberately tiny and dependency-light (node:fs + the atomic-write primitive): every
+ * file store imports the gate from here, so it must never grow an import back into a store.
+ */
+/** Who the data root belonged to before adoption. Shape-identical to the rule domain's `RuleOwner`
+ *  (design/182): local-single-user identity is a STRUCTURAL ABSENCE, never a sentinel string. */
+export type AdoptionSource = {
+    kind: "local-owner";
+} | {
+    kind: "principal";
+    principal: string;
+};
+/** Typed refusal codes (design/183 §7.3): every adoption refusal is discriminable — from `not_found`,
+ *  from a broken deployment, and from each other. */
+export type AdoptionErrorCode = 
+/** I6 boot gate: a store construction (or engine boot) over a root whose adoption is mid-flight. */
+"adoption_in_flight"
+/** A DIFFERENT adoption is mid-flight in this root — resume the original or repair the marker. */
+ | "adoption_in_flight_mismatch"
+/** The root already completed an adoption toward another principal; a second adoption is a
+ *  multi-tenant transfer, out of this protocol's scope (design/183 §1 non-goals / D7). */
+ | "adoption_retarget"
+/** A live instance (engine or another adoption) owns the data root right now. */
+ | "adoption_locked"
+/** A row-rewrite target exists with DIFFERENT bytes: merging two existing rows is not a rewrite. */
+ | "adoption_row_collision"
+/** The marker exists but cannot be read as a marker. Fail-closed: after phase 4 the marker IS the
+ *  owner-resolution truth, so guessing would fork ownership. Repair by hand, then resume. */
+ | "adoption_marker_corrupt"
+/** A config-witness receipt does not bind (wrong adoption id / value / unknown entry). */
+ | "adoption_witness_mismatch"
+/** A resume supplies LESS than the recorded migration plan (a dropped rules/carriage leg or a
+ *  changed credentials claim) — completing the arc on the thinner plan would terminalize an
+ *  incompletely migrated root, so the mismatch is refused instead. */
+ | "adoption_plan_mismatch"
+/** The nested permission-rule leg refused (its own collision / lock / marker grammar) — surfaced
+ *  under the root arc's typed contract, original reason preserved in the message. */
+ | "adoption_rule_leg_refused"
+/** Malformed request (empty principal, from == to, …). */
+ | "adoption_bad_request";
+export declare class AdoptionError extends Error {
+    readonly code: AdoptionErrorCode;
+    constructor(code: AdoptionErrorCode, message: string);
+}
+/** One deployment-config the adoption obligates (design/183 §6): configs the state machine cannot
+ *  reach carry `migrated: false` and stay on the outstanding account until a consumer WITNESSES them. */
+export interface AffectedDeploymentConfig {
+    /** e.g. "web-client-bff" | "cli" | "env" | "core-decl" | … */
+    deployment: string;
+    key: string;
+    /** The value the consumer must now carry (the new principal, or "withdrawn" for a retired seat). */
+    requiredValue: string;
+    /** true ⇔ the adoption itself changed it; false ⇒ an explicit operator action remains. */
+    migrated: boolean;
+}
+/** Per-store line of the immutable report (design/183 §6 `legs`). */
+export interface AdoptionLegReport {
+    store: string;
+    action: "bucket-rebind" | "row-rewrite" | "carried" | "none" | "reset";
+    rows?: number;
+    quarantined?: number;
+}
+/** The IMMUTABLE half of every receipt (design/183 §6): persisted byte-stable in the terminal record,
+ *  identical on the first success and on every idempotent re-run. Current state (outstanding configs,
+ *  live quarantine count) is NOT in here — it is derived fresh per answer ({@link AdoptionReceipt}). */
+export interface AdoptionReport {
+    /** Minted at phase ② — the binding anchor config-witness receipts must carry. */
+    adoptionId: string;
+    from: AdoptionSource;
+    toPrincipal: string;
+    atMs: number;
+    /** The claim REFERENCE for the new identity's credentials — never the credentials themselves (the
+     *  marker is a plain-text sidecar, not a credential store). The claim must be durable and
+     *  repeatedly redeemable (server obligation, design/183 §4.3). */
+    credentials: {
+        issuedBy: "server";
+        ref: string;
+    };
+    affectedDeploymentConfigs: AffectedDeploymentConfig[];
+    legs: AdoptionLegReport[];
+    /** design/183 §6 (r4) — the machine-readable CLOSED SET of assets not migrated BY DESIGN, each
+     *  naming its ruling. Black-box discriminable from "forgotten": an asset outside this list that
+     *  did not arrive is a defect; the list growing beyond the design's written set is DRIFT (§10.5
+     *  ① — new members enter through a design ruling, never through an implementation). */
+    notMigratedByDesign: Array<{
+        asset: string;
+        ruling: string;
+    }>;
+}
+/** The one receipt envelope (design/183 §6): first success and every idempotent re-run answer with
+ *  this same shape. `immutableReport` is the persisted byte-stable snapshot; `current` is derived. */
+export interface AdoptionReceipt {
+    status: "adopted";
+    immutableReport: AdoptionReport;
+    current: {
+        /** `deployment:key` of every config-account entry not yet WITNESSED (an operator ack does not
+         *  clear the account — only a consumer's bound runtime read-back does; design/183 §3.3). */
+        outstandingConfigs: string[];
+        /** Live quarantine-area row count (local truth = what is actually on disk; design/183 §7.2). */
+        quarantined: number;
+    };
+}
+/** The durable root marker file. */
+export type RootAdoptionFile = {
+    schemaVersion: 1;
+    marker: {
+        adoptionId: string;
+        from: AdoptionSource;
+        toPrincipal: string;
+        phase: 2 | 3 | 4 | 5;
+        /** The migration plan recorded at phase ② and grown MONOTONICALLY across resumes — what a
+         *  resume must (at least) re-supply. Without it, an ordinary restart with thinner options
+         *  would skip a stalled leg and terminalize an incompletely migrated root; the rules leg is
+         *  bound to its canonical DIRECTORY (a boolean would accept a substituted bucket). REQUIRED:
+         *  a marker without a readable plan is corrupt (fail-closed), never re-bound to the caller's
+         *  current options (adversarial-review findings, rounds 1-2). */
+        plan: {
+            rulesDir?: string;
+            carriage: string[];
+            credentialsRef: string;
+        };
+        /** Completion bits for legs without a self-attesting predicate (row rewrites), plus the
+         *  carriage RESULTS folded in at the phase-⑤ publish: the bits (and their counts, which the
+         *  terminal report needs) survive a crash between a stage and the next phase publish — a
+         *  ⑤→⑥ crash must not let the resumed run report a carried store as untouched. */
+        legs?: Record<string, {
+            done: true;
+            rows?: number;
+            quarantined?: number;
+        }>;
+    };
+} | {
+    schemaVersion: 1;
+    adopted: {
+        from: AdoptionSource;
+        toPrincipal: string;
+        atMs: number;
+        immutableReport: AdoptionReport;
+    };
+};
+export declare const ROOT_ADOPTION_FILE = "adoption.json";
+/**
+ * design/183 §6 (r4) — the CLOSED SET of by-design-not-migrated assets, verbatim from the design's
+ * written list. The WRITER emits exactly this list and the drift pin (§10.5 ① — the design-vs-code
+ * two-cell guard) lives in the TEST GRID, where a ruled growth of the set is a deliberate edit.
+ *
+ * #133: the terminal READ validator deliberately does NOT compare a stored report against this
+ * constant. A persisted report is a snapshot of the set AS RULED AT ADOPTION TIME; the set is
+ * allowed to grow by ruling (§10.5 ① names that road), so an exact-equality read check would mark
+ * every already-adopted root corrupt on the release after any growth (and again on rollback) — 13
+ * construction sites all refusing to serve. The read validator checks SHAPE and integrity
+ * (non-empty, well-formed entries, no duplicate assets — what an empty/mangled account rebuild
+ * actually needs), never version-crossed content equality.
+ */
+export declare const NOT_MIGRATED_BY_DESIGN: ReadonlyArray<{
+    asset: string;
+    ruling: string;
+}>;
+/** The five baseline obligation IDENTITIES (design/183 §6 minimum face). Since #133 the terminal READ
+ *  validator deliberately does NOT compare a stored report against this table (the stored report is a
+ *  snapshot of the set as ruled at adoption time; see the validator's own note) — the enforcement that
+ *  the WRITER emits exactly this set lives in the test grid (test/file-adoption-root.test.ts pins the
+ *  fresh report's identities against this constant), where a drift is a deliberate, reviewable edit. */
+export declare const BASELINE_CONFIG_IDENTITIES: ReadonlyArray<{
+    deployment: string;
+    key: string;
+}>;
+/**
+ * Read the root adoption marker; `undefined` when none. A corrupt marker THROWS (typed): after
+ * phase 4 the marker is the resolution truth, so a guessed read could serve a half-migrated root or
+ * invent an adoption that never happened — the same fail-closed stance as the rule-domain marker.
+ */
+export declare function readRootAdoptionFile(root: string): RootAdoptionFile | undefined;
+/** Atomically publish the root marker (write-temp → fsync → rename, same discipline as every store). */
+export declare function writeRootAdoptionFile(root: string, content: RootAdoptionFile): void;
+/**
+ * Invariant I6 (design/183 §3.1) — the adoption BOOT GATE, called by every file store constructor:
+ * an in-flight root marker means the root is mid-adoption (possibly after a crash), and serving a
+ * half-migrated root is refused LOUDLY. The refusal names the in-flight arc and the way forward
+ * (resume `adoptLocalDataRoot` to completion). A terminal record passes: a completed adoption is a
+ * normal, readable root. A corrupt marker throws (fail-closed, see {@link readRootAdoptionFile}).
+ *
+ * This gate is what turns "the engine must be stopped during adoption" from an operational assumption
+ * into a machine-checked invariant across crashes: the adoption's own locks die with its process, but
+ * the marker (and this gate) survive. Boundary, stated honestly: the gate fires at CONSTRUCTION time.
+ * A store instance constructed BEFORE the marker landed in another OS process is outside it — cross-
+ * process sharing of one data dir is the file family's documented UNSUPPORTED shape (task-list F-14,
+ * mailbox RB-249); adoption adds no new promise there.
+ */
+export declare function assertAdoptionBootGate(root: string, storeName: string): void;

package/dist/stores/file/adoption/marker.js

@@ -0,0 +1,205 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFile, ensureDir } from "../fs-atomic.js";
+export class AdoptionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "AdoptionError";
+    }
+}
+export const ROOT_ADOPTION_FILE = "adoption.json";
+export const NOT_MIGRATED_BY_DESIGN = [
+    { asset: "usage-window", ruling: "183-D1" },
+    { asset: "approval-history-fields", ruling: "183-D2" },
+    { asset: "sessions/<pid>.json", ruling: "3356-cli-enum" },
+    { asset: "session-env/<sessionId>/*.sh", ruling: "3356-cli-enum" },
+    { asset: "sema-ca.crt", ruling: "3356-cli-enum" },
+    { asset: "backups/", ruling: "3356-cli-enum" },
+    { asset: "config-lkg-*", ruling: "3356-cli-enum" },
+];
+export const BASELINE_CONFIG_IDENTITIES = [
+    { deployment: "web-client-bff", key: "injected-principal" },
+    { deployment: "cli", key: "cloud-credentials+profiles" },
+    { deployment: "cli", key: "SEMA_LIVE_PRINCIPAL" },
+    { deployment: "env", key: "REQUIRE_PRINCIPAL" },
+    { deployment: "core-decl", key: "localOwnerRules" },
+];
+function isSource(v) {
+    if (v === null || typeof v !== "object")
+        return false;
+    const s = v;
+    if (s.kind === "local-owner")
+        return true;
+    return s.kind === "principal" && typeof s.principal === "string" && s.principal !== "";
+}
+function isRootAdoptionFileShape(v) {
+    if (v === null || typeof v !== "object")
+        return false;
+    const f = v;
+    if (f.schemaVersion !== 1)
+        return false;
+    if ("marker" in f && !("adopted" in f)) {
+        const m = f.marker;
+        if (m === null ||
+            typeof m !== "object" ||
+            typeof m.adoptionId !== "string" ||
+            !isSource(m.from) ||
+            typeof m.toPrincipal !== "string" ||
+            typeof m.phase !== "number" ||
+            ![2, 3, 4, 5].includes(m.phase)) {
+            return false;
+        }
+        const p = m.plan;
+        if (p === null ||
+            p === undefined ||
+            typeof p !== "object" ||
+            (p.rulesDir !== undefined && typeof p.rulesDir !== "string") ||
+            !Array.isArray(p.carriage) ||
+            !p.carriage.every((s) => typeof s === "string") ||
+            typeof p.credentialsRef !== "string") {
+            return false;
+        }
+        if (m.legs !== undefined) {
+            if (m.legs === null || typeof m.legs !== "object" || Array.isArray(m.legs))
+                return false;
+            const okCount = (n) => n === undefined || (typeof n === "number" && Number.isSafeInteger(n) && n >= 0);
+            for (const bit of Object.values(m.legs)) {
+                if (bit === null || typeof bit !== "object")
+                    return false;
+                const b = bit;
+                if (b.done !== true || !okCount(b.rows) || !okCount(b.quarantined))
+                    return false;
+            }
+        }
+        const legs = (m.legs ?? {});
+        if (m.phase >= 3 && legs["session-policy"]?.done !== true)
+            return false;
+        if (m.phase === 5) {
+            for (const store of p.carriage) {
+                if (legs[`carriage:${store}`]?.done !== true)
+                    return false;
+            }
+        }
+        const planned = new Set(p.carriage);
+        for (const key of Object.keys(legs)) {
+            if (key.startsWith("carriage:") && !planned.has(key.slice("carriage:".length)))
+                return false;
+        }
+        return true;
+    }
+    if ("adopted" in f && !("marker" in f)) {
+        const a = f.adopted;
+        if (a === null ||
+            typeof a !== "object" ||
+            !isSource(a.from) ||
+            typeof a.toPrincipal !== "string" ||
+            typeof a.atMs !== "number" ||
+            a.immutableReport === null ||
+            typeof a.immutableReport !== "object") {
+            return false;
+        }
+        const r = a.immutableReport;
+        const sameFrom = isSource(r.from) &&
+            (r.from.kind === "local-owner"
+                ? a.from.kind === "local-owner"
+                : a.from.kind === "principal" &&
+                    r.from.principal === a.from.principal);
+        const okCount = (n) => n === undefined || (typeof n === "number" && Number.isSafeInteger(n) && n >= 0);
+        const configIds = new Set();
+        const configsOk = Array.isArray(r.affectedDeploymentConfigs) &&
+            r.affectedDeploymentConfigs.length > 0 &&
+            r.affectedDeploymentConfigs.every((c) => {
+                if (c === null || typeof c !== "object")
+                    return false;
+                const e = c;
+                if (typeof e.deployment !== "string" || e.deployment === "" || typeof e.key !== "string" || e.key === "")
+                    return false;
+                if (typeof e.requiredValue !== "string" || typeof e.migrated !== "boolean")
+                    return false;
+                const id = JSON.stringify([e.deployment, e.key]);
+                if (configIds.has(id))
+                    return false;
+                configIds.add(id);
+                return true;
+            });
+        const nmd = r.notMigratedByDesign;
+        const nmdAssets = new Set();
+        const closedSetOk = Array.isArray(nmd) &&
+            nmd.length > 0 &&
+            nmd.every((e) => {
+                if (e === null || typeof e !== "object")
+                    return false;
+                const m = e;
+                if (typeof m.asset !== "string" || m.asset === "" || typeof m.ruling !== "string" || m.ruling === "")
+                    return false;
+                if (nmdAssets.has(m.asset))
+                    return false;
+                nmdAssets.add(m.asset);
+                return true;
+            });
+        const legsOk = Array.isArray(r.legs) &&
+            r.legs.every((l) => {
+                if (l === null || typeof l !== "object")
+                    return false;
+                const e = l;
+                return (typeof e.store === "string" &&
+                    typeof e.action === "string" &&
+                    ["bucket-rebind", "row-rewrite", "carried", "none", "reset"].includes(e.action) &&
+                    okCount(e.rows) &&
+                    okCount(e.quarantined));
+            });
+        const credsOk = r.credentials !== null &&
+            typeof r.credentials === "object" &&
+            r.credentials.issuedBy === "server" &&
+            typeof r.credentials.ref === "string" &&
+            r.credentials.ref !== "";
+        return (typeof r.adoptionId === "string" &&
+            r.toPrincipal === a.toPrincipal &&
+            r.atMs === a.atMs &&
+            Number.isSafeInteger(a.atMs) &&
+            a.atMs >= 0 &&
+            sameFrom &&
+            closedSetOk &&
+            configsOk &&
+            legsOk &&
+            credsOk);
+    }
+    return false;
+}
+export function readRootAdoptionFile(root) {
+    let raw;
+    try {
+        raw = readFileSync(join(root, ROOT_ADOPTION_FILE), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw new AdoptionError("adoption_marker_corrupt", `could not read the adoption marker in ${root}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new AdoptionError("adoption_marker_corrupt", `the adoption marker in ${root} is not valid JSON (${err.message}) — refusing to serve this data root until it is repaired`);
+    }
+    if (!isRootAdoptionFileShape(parsed)) {
+        throw new AdoptionError("adoption_marker_corrupt", `the adoption marker in ${root} does not carry a readable shape — refusing to serve this data root until it is repaired`);
+    }
+    return parsed;
+}
+export function writeRootAdoptionFile(root, content) {
+    ensureDir(root);
+    atomicWriteFile(join(root, "tmp"), join(root, ROOT_ADOPTION_FILE), JSON.stringify(content, null, 2));
+}
+export function assertAdoptionBootGate(root, storeName) {
+    const f = readRootAdoptionFile(root);
+    if (f !== undefined && "marker" in f) {
+        const from = f.marker.from.kind === "principal" ? `principal "${f.marker.from.principal}"` : "the local owner";
+        throw new AdoptionError("adoption_in_flight", `${storeName}: an adoption of this data root (${from} → "${f.marker.toPrincipal}", phase ${f.marker.phase}) is in flight — ` +
+            `resume adoptLocalDataRoot to completion (or repair ${join(root, ROOT_ADOPTION_FILE)}) before constructing stores over it; ` +
+            `serving a half-migrated root is refused`);
+    }
+}

package/dist/stores/file/background-agent-store.js

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import { BackgroundAgentStoreError, STALE_RUNNING_REAP_ATTRIBUTION, assertBackgroundAgentReapOptions, queryBackgroundAgents, } from "../../core/background-agent-store.js";
 import { SharedLedgerTable } from "./shared-ledger.js";
+import { assertAdoptionBootGate } from "./adoption/marker.js";
 const agentLedgers = new SharedLedgerTable({
     keyOf: (r) => FileBackgroundAgentStore.key(r.handle, r.scope),
     apply: (rows, ev) => {
@@ -20,6 +21,7 @@ export class FileBackgroundAgentStore {
         return this.ledger.rows;
     }
     constructor(root, opts = {}) {
+        assertAdoptionBootGate(root, "FileBackgroundAgentStore");
         this.fsyncEnabled = opts.fsync !== false;
         this.compactEvery = opts.compactEvery ?? 1000;
         const dir = join(root, "background-agents");

package/dist/stores/file/checkpoint-store.js

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { assertAdoptionBootGate } from "./adoption/marker.js";
 import { appendPendingSteer, CheckpointError, checkpointOccMatches, checkpointRowMatches, summarizeCheckpoint, validatePendingSteer, winnerFromOutcome, } from "../../core/checkpoint-store.js";
 import { SharedLedgerTable } from "./shared-ledger.js";
 const CHECKPOINT_LEDGER_EVENT_REGISTRY = {
@@ -71,6 +72,7 @@ export class FileCheckpointStore {
     }
     fault = null;
     constructor(root, opts = {}) {
+        assertAdoptionBootGate(root, "FileCheckpointStore");
         this.fsyncEnabled = opts.fsync !== false;
         this.compactEvery = opts.compactEvery ?? 1000;
         const dir = join(root, "checkpoints");

package/dist/stores/file/file-snapshot-store.js

@@ -3,6 +3,7 @@ import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { applyManifest, captureManifest, DEFAULT_SNAPSHOT_BOUNDS, } from "../../core/file-snapshot-store.js";
 import { canonicalStoreKey, ensureDir, sanitizePathComponent, sanitizeScope, writeThenLink } from "./fs-atomic.js";
+import { assertAdoptionBootGate } from "./adoption/marker.js";
 const sharedInFlight = new Map();
 export class FileFileSnapshotStore {
     base;
@@ -20,6 +21,7 @@ export class FileFileSnapshotStore {
     bounds;
     onCorruptRead;
     constructor(root, bounds, opts) {
+        assertAdoptionBootGate(root, "FileFileSnapshotStore");
         this.base = join(root, "file-snapshots");
         this.blobsDir = join(this.base, "blobs");
         this.manifestsDir = join(this.base, "manifests");

package/dist/stores/file/index.d.ts

@@ -18,6 +18,8 @@ export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResu
 export { FileUsageWindowStore } from "./usage-window-store.js";
 export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
 export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
+export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, type AdoptionErrorCode, type AdoptionSource, type AdoptionReport, type AdoptionReceipt, type AdoptionLegReport, type AffectedDeploymentConfig, type RootAdoptionFile, } from "./adoption/marker.js";
+export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, type AdoptionStatus, type AdoptLocalDataRootOptions, type AdoptLocalDataRootResult, type AdoptionCarriageLeg, type AdoptionCarriageLegContext, type AdoptionConfigWitnessReceipt, } from "./adoption/adopt.js";
 /**
  * design/80 — the file-backed `StorageBackend` for the local (TOC) single-user binary: the 3rd store impl
  * alongside `InMemory*` and `Pg*`, selected purely by what the embedder injects into `RunnerDeps` (no engine

package/dist/stores/file/index.js

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import { guardedMemoryStore } from "../../core/memory.js";
 import { TtlSessionStore } from "../../core/session-store.js";
 import { BootLock, createFileConsolidationLock, resolveDataRoot } from "./fs-atomic.js";
+import { assertAdoptionBootGate } from "./adoption/marker.js";
 import { FileCheckpointStore } from "./checkpoint-store.js";
 import { FileMemoryStore } from "./memory-store.js";
 import { FileSessionRepo } from "./session-store.js";
@@ -20,6 +21,8 @@ export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResu
 export { FileUsageWindowStore } from "./usage-window-store.js";
 export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
 export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
+export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, } from "./adoption/marker.js";
+export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, } from "./adoption/adopt.js";
 export class FileStorageBackend {
     root;
     sessionStore;
@@ -39,6 +42,7 @@ export class FileStorageBackend {
     fileWorkflowJournal;
     constructor(opts = {}) {
         this.root = resolveDataRoot(opts.root);
+        assertAdoptionBootGate(this.root, "FileStorageBackend");
         this.lock = new BootLock(join(this.root, "LOCK"));
         this.lock.acquire();
         try {

package/dist/stores/file/mailbox-store.js

@@ -3,6 +3,7 @@ import { assertRetentionPolicy } from "../../core/retention-policy.js";
 import { existsSync, readdirSync, realpathSync } from "node:fs";
 import { newestSentAt, } from "../../core/mailbox-store.js";
 import { AppendLog, atomicWriteFile, canonicalStoreKey, ensureDir, readJsonlRecords, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
+import { assertAdoptionBootGate } from "./adoption/marker.js";
 function realpathSyncSafe(p) {
     try {
         return realpathSync(p);
@@ -42,6 +43,7 @@ export class FileMailboxStore {
     touched = new Map();
     discloseCorrupt;
     constructor(root, opts = {}) {
+        assertAdoptionBootGate(root, "FileMailboxStore");
         this.fsyncEnabled = opts.fsync !== false;
         this.compactEvery = opts.compactEvery ?? 500;
         const sink = opts.onCorruptRead;

package/dist/stores/file/memory-store.js

@@ -3,6 +3,7 @@ import { uuidv7 } from "../../internal/harness.js";
 import { firstSentence, lexicalSearchMatch, parseNoteTimestamp, } from "../../core/memory.js";
 import { cosineDistance, jaccardDistance, termSet } from "../../core/memory-vector.js";
 import { canonicalStoreKey, AppendLog, atomicWriteFile, ensureDir, readJsonlRecords, sanitizeScope, } from "./fs-atomic.js";
+import { assertAdoptionBootGate } from "./adoption/marker.js";
 const MAX_OPEN_MEMORY_SCOPES = 64;
 const sharedMemoryDirs = new Map();
 export class FileMemoryStore {
@@ -18,6 +19,7 @@ export class FileMemoryStore {
     scopeKey;
     closed = false;
     constructor(root, opts = {}) {
+        assertAdoptionBootGate(root, "FileMemoryStore");
         this.root = join(root, "memory");
         this.scopeKey = canonicalStoreKey(this.root);
         const live = sharedMemoryDirs.get(this.scopeKey);

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

@@ -31,6 +31,15 @@ export interface FileSessionPolicyStoreOptions {
 export declare class FileSessionPolicyStore implements SessionPolicyStore {
     private readonly dir;
     private readonly onCorruptRead;
+    /** #132 — the ADOPTED identity of a local-owner root's anonymous lane, or undefined on an
+     *  unadopted (or principal-adopted) root. A local-owner adoption rebinds the anonymous
+     *  `[sid,null]` estate rows to `toPrincipal`; until the deployment's principal wiring lands
+     *  (`REQUIRE_PRINCIPAL` et al. — recorded `migrated:false` in the config account, an operator
+     *  action), the runtime still queries anonymously, and ENOENT there would silently drop the very
+     *  tighten-only deny rules the rebind moved. Adoption is a transfer of the whole anonymous
+     *  identity, so on such a root the anonymous key IS the adopted principal — reads and writes
+     *  alike (a window-era anonymous write must not mint a fresh orphan row). */
+    private readonly anonymousAlias;
     constructor(root: string, opts?: FileSessionPolicyStoreOptions);
     /** The one delivery point for {@link onCorruptRead}. Swallow-guarded here so no caller has to remember. */
     private disclose;
@@ -41,7 +50,8 @@ export declare class FileSessionPolicyStore implements SessionPolicyStore {
      *  (swallow-guarded; never on a plain ENOENT, which really is absence). */
     private discloseCorrupt;
     /** `(sessionId, principal)` → a safe, INJECTIVE filename (sanitizeScope appends the full sha256 of the raw
-     *  composite key, so distinct keys never collide on disk). */
+     *  composite key, so distinct keys never collide on disk). On a local-owner-adopted root the
+     *  anonymous lane resolves to the adopted principal's key (#132 — see {@link anonymousAlias}). */
     private pathFor;
     private read;
     getRules(sessionId: string, principal?: string): Promise<StoredSessionRules | null>;

package/dist/stores/file/session-policy-store.js

@@ -2,13 +2,19 @@ import { readFileSync, readdirSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { loosenReasons, normalizeRules, stripRev, SessionPolicyError, } from "../../core/session-policy-store.js";
 import { atomicWriteFile, ensureDir, sanitizeScope } from "./fs-atomic.js";
+import { assertAdoptionBootGate, readRootAdoptionFile } from "./adoption/marker.js";
 export class FileSessionPolicyStore {
     dir;
     onCorruptRead;
+    anonymousAlias;
     constructor(root, opts) {
+        assertAdoptionBootGate(root, "FileSessionPolicyStore");
         this.dir = join(root, "session-policy");
         ensureDir(this.dir);
         this.onCorruptRead = opts?.onCorruptRead;
+        const adoption = readRootAdoptionFile(root);
+        this.anonymousAlias =
+            adoption !== undefined && "adopted" in adoption && adoption.adopted.from.kind === "local-owner" ? adoption.adopted.toPrincipal : undefined;
     }
     disclose(info) {
         try {
@@ -21,7 +27,8 @@ export class FileSessionPolicyStore {
         this.disclose({ sessionId, ...(principal !== undefined ? { principal } : {}), path: this.pathFor(sessionId, principal), reason });
     }
     pathFor(sessionId, principal) {
-        const composite = JSON.stringify([sessionId, principal ?? null]);
+        const effective = principal ?? this.anonymousAlias;
+        const composite = JSON.stringify([sessionId, effective ?? null]);
         return join(this.dir, `${sanitizeScope(composite)}.json`);
     }
     read(sessionId, principal) {
@@ -76,7 +83,7 @@ export class FileSessionPolicyStore {
             }
         }
         const next = { ...clean, rev: (prior?.rev ?? 0) + 1 };
-        atomicWriteFile(join(this.dir, "tmp"), this.pathFor(sessionId, principal), JSON.stringify({ ...next, __sid: sessionId, __principal: principal ?? null }));
+        atomicWriteFile(join(this.dir, "tmp"), this.pathFor(sessionId, principal), JSON.stringify({ ...next, __sid: sessionId, __principal: (principal ?? this.anonymousAlias) ?? null }));
         return next;
     }
     async listBySession(sessionId) {

package/dist/stores/file/session-store.js

@@ -2,6 +2,7 @@ import { existsSync, readdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { BaseSessionStorage, StoredSession, SessionError, getEntriesToFork, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
 import { canonicalStoreKey, AppendLog, atomicWriteFile, ensureDir, readJsonlRecords, sanitizePathComponent } from "./fs-atomic.js";
+import { assertAdoptionBootGate } from "./adoption/marker.js";
 const SUFFIX = ".jsonl";
 const sharedSessionStorages = new Map();
 const sessionStorageFinalizer = new FinalizationRegistry(({ canonical, log }) => {
@@ -57,6 +58,7 @@ export class FileSessionRepo {
     onCorruptRead;
     joined = new Map();
     constructor(root, opts) {
+        assertAdoptionBootGate(root, "FileSessionRepo");
         this.dir = join(root, "sessions");
         this.tmpDir = join(root, "tmp");
         ensureDir(this.dir);

package/dist/stores/file/task-list-store.js

@@ -2,9 +2,11 @@ import { join, resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { assertJsonMetadata, normalizeTaskShape } from "../../tools/task-list.js";
 import { canonicalStoreKey, atomicWriteFile, ensureDir } from "./fs-atomic.js";
+import { assertAdoptionBootGate } from "./adoption/marker.js";
 const dirLocks = new Map();
 export function createFileTaskListStore(root) {
     const dir = resolve(root);
+    assertAdoptionBootGate(dir, "createFileTaskListStore");
     const tmpDir = join(dir, "tmp");
     const path = join(dir, "task-list.json");
     ensureDir(dir);

package/dist/stores/file/tool-result-store.js

@@ -3,9 +3,11 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { assertSafeToolResultRef } from "../../core/tool-result-store.js";
 import { ensureDir, sanitizePathComponent, writeThenLink } from "./fs-atomic.js";
+import { assertAdoptionBootGate } from "./adoption/marker.js";
 export class FileToolResultStore {
     dir;
     constructor(root) {
+        assertAdoptionBootGate(root, "FileToolResultStore");
         this.dir = join(root, "tool-results");
         ensureDir(this.dir);
     }

package/dist/stores/file/usage-window-store.js

@@ -2,9 +2,11 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { chargeUsageRecord, readUsageRecord, EMPTY_USAGE_WINDOW_RECORD, } from "../../core/usage-window-store.js";
 import { atomicWriteFile, ensureDir, sanitizeScope } from "./fs-atomic.js";
+import { assertAdoptionBootGate } from "./adoption/marker.js";
 export class FileUsageWindowStore {
     dir;
     constructor(root) {
+        assertAdoptionBootGate(root, "FileUsageWindowStore");
         this.dir = join(root, "usage-windows");
         ensureDir(this.dir);
     }