@sema-agent/core 5.22.0 → 5.24.0

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

@@ -0,0 +1,611 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { adoptFilePermissionRuleStore } from "../permission-rule-adopt.js";
+import { BootLock, atomicWriteFile, ensureDir, sanitizeScope } from "../fs-atomic.js";
+import { AdoptionError, NOT_MIGRATED_BY_DESIGN, readRootAdoptionFile, writeRootAdoptionFile, } from "./marker.js";
+const CONFIG_ACCOUNT_FILE = "adoption-configs.json";
+function baselineConfigs(toPrincipal) {
+    return [
+        { deployment: "web-client-bff", key: "injected-principal", requiredValue: toPrincipal, migrated: false },
+        { deployment: "cli", key: "cloud-credentials+profiles", requiredValue: toPrincipal, migrated: false },
+        { deployment: "cli", key: "SEMA_LIVE_PRINCIPAL", requiredValue: toPrincipal, migrated: false },
+        { deployment: "env", key: "REQUIRE_PRINCIPAL", requiredValue: "true", migrated: false },
+        { deployment: "core-decl", key: "localOwnerRules", requiredValue: "withdrawn", migrated: false },
+    ];
+}
+function readConfigAccount(root) {
+    let raw;
+    try {
+        raw = readFileSync(join(root, CONFIG_ACCOUNT_FILE), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new AdoptionError("adoption_marker_corrupt", `the adoption config account in ${root} is not valid JSON (${err.message})`);
+    }
+    if (!isConfigAccountShape(parsed)) {
+        throw new AdoptionError("adoption_marker_corrupt", `the adoption config account in ${root} does not carry a readable shape`);
+    }
+    return parsed;
+}
+function readConfigAccountEvidence(root) {
+    try {
+        return readConfigAccount(root);
+    }
+    catch (err) {
+        if (err instanceof AdoptionError)
+            return undefined;
+        throw err;
+    }
+}
+function isConfigAccountShape(v) {
+    if (v === null || typeof v !== "object")
+        return false;
+    const f = v;
+    if (f.schemaVersion !== 1 || typeof f.adoptionId !== "string" || !Array.isArray(f.configs))
+        return false;
+    const finite = (n) => typeof n === "number" && Number.isFinite(n);
+    return f.configs.every((c) => {
+        if (c === null || typeof c !== "object")
+            return false;
+        const e = c;
+        if (typeof e.deployment !== "string" || typeof e.key !== "string" || typeof e.requiredValue !== "string" || typeof e.migrated !== "boolean") {
+            return false;
+        }
+        if (e.ack !== undefined) {
+            if (e.ack === null || typeof e.ack !== "object" || !finite(e.ack.atMs))
+                return false;
+        }
+        if (e.witnessed !== undefined) {
+            if (e.witnessed === null || typeof e.witnessed !== "object")
+                return false;
+            const w = e.witnessed;
+            if (!finite(w.atMs) || w.receipt === null || typeof w.receipt !== "object")
+                return false;
+            const r = w.receipt;
+            if (r.adoptionId !== f.adoptionId || r.deployment !== e.deployment || r.key !== e.key || r.observedValue !== e.requiredValue || !finite(r.atMs)) {
+                return false;
+            }
+        }
+        return true;
+    });
+}
+function writeConfigAccount(root, account) {
+    atomicWriteFile(join(root, "tmp"), join(root, CONFIG_ACCOUNT_FILE), JSON.stringify(account, null, 2));
+}
+function configIdentity(c) {
+    return JSON.stringify([c.deployment, c.key]);
+}
+function upsertConfigAccount(root, adoptionId, toPrincipal, additional) {
+    const existing = readConfigAccount(root);
+    if (existing !== undefined && existing.adoptionId === adoptionId) {
+        const known = new Set(existing.configs.map(configIdentity));
+        let grew = false;
+        for (const c of additional) {
+            if (!known.has(configIdentity(c))) {
+                existing.configs.push({ ...c });
+                known.add(configIdentity(c));
+                grew = true;
+            }
+        }
+        if (grew)
+            writeConfigAccount(root, existing);
+        return;
+    }
+    const merged = new Map();
+    for (const c of baselineConfigs(toPrincipal))
+        merged.set(configIdentity(c), c);
+    for (const c of additional)
+        merged.set(configIdentity(c), c);
+    writeConfigAccount(root, { schemaVersion: 1, adoptionId, configs: [...merged.values()] });
+}
+function outstandingOf(account) {
+    if (account === undefined)
+        return [];
+    return account.configs.filter((c) => c.witnessed === undefined).map((c) => `${c.deployment}:${c.key}`);
+}
+export function ackAdoptionConfig(root, deployment, key, now) {
+    const account = readConfigAccount(root);
+    const entry = account?.configs.find((c) => c.deployment === deployment && c.key === key);
+    if (account === undefined || entry === undefined) {
+        throw new AdoptionError("adoption_witness_mismatch", `no adoption config account entry for ${deployment}:${key} in ${root}`);
+    }
+    entry.ack = { atMs: (now ?? Date.now)() };
+    writeConfigAccount(root, account);
+}
+export function witnessAdoptionConfig(root, receipt) {
+    const account = readConfigAccount(root);
+    const entry = account?.configs.find((c) => c.deployment === receipt.deployment && c.key === receipt.key);
+    if (account === undefined || entry === undefined) {
+        throw new AdoptionError("adoption_witness_mismatch", `no adoption config account entry for ${receipt.deployment}:${receipt.key} in ${root}`);
+    }
+    if (receipt.adoptionId !== account.adoptionId) {
+        throw new AdoptionError("adoption_witness_mismatch", `the witness receipt names adoption "${receipt.adoptionId}" but this root's adoption is "${account.adoptionId}" — a witness binds to the adoption it observed`);
+    }
+    if (typeof receipt.atMs !== "number" || !Number.isFinite(receipt.atMs)) {
+        throw new AdoptionError("adoption_witness_mismatch", `the witness receipt carries an invalid timestamp (${String(receipt.atMs)}) — refusing to record evidence the account reader would reject`);
+    }
+    if (receipt.observedValue !== entry.requiredValue) {
+        throw new AdoptionError("adoption_witness_mismatch", `the witness for ${receipt.deployment}:${receipt.key} observed "${receipt.observedValue}" but the adoption requires "${entry.requiredValue}" — refusing to clear the account on a value that would leave the consumer locked out`);
+    }
+    entry.witnessed = { atMs: receipt.atMs, receipt };
+    writeConfigAccount(root, account);
+}
+const QUARANTINE_DIR = "adoption-quarantine";
+export function listAdoptionQuarantine(root) {
+    const base = join(root, QUARANTINE_DIR);
+    let stores;
+    try {
+        stores = readdirSync(base);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const store of stores) {
+        let names;
+        try {
+            names = readdirSync(join(base, store));
+        }
+        catch {
+            continue;
+        }
+        for (const name of names)
+            out.push({ store, name, path: join(base, store, name) });
+    }
+    return out;
+}
+function quarantineRow(root, store, name, bytes) {
+    const dir = join(root, QUARANTINE_DIR, sanitizeScope(store));
+    ensureDir(dir);
+    const base = sanitizeScope(name);
+    let target = join(dir, base);
+    for (let i = 2; existsSync(target); i += 1) {
+        if (readFileSync(target, "utf8") === bytes)
+            return;
+        target = join(dir, `${base}.${i}`);
+    }
+    atomicWriteFile(join(root, "tmp"), target, bytes);
+}
+function rewriteSessionPolicyRows(root, fromPrincipal, toPrincipal) {
+    const dir = join(root, "session-policy");
+    let files;
+    try {
+        files = readdirSync(dir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return 0;
+        throw err;
+    }
+    const tmpDir = join(dir, "tmp");
+    let rows = 0;
+    for (const file of files) {
+        if (!file.endsWith(".json"))
+            continue;
+        const source = join(dir, file);
+        let raw;
+        try {
+            raw = readFileSync(source, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw err;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+            continue;
+        const row = parsed;
+        if (row.__principal !== fromPrincipal)
+            continue;
+        if (typeof row.__sid !== "string")
+            continue;
+        const rewritten = JSON.stringify({ ...row, __principal: toPrincipal });
+        const target = join(dir, `${sanitizeScope(JSON.stringify([row.__sid, toPrincipal]))}.json`);
+        if (existsSync(target)) {
+            if (readFileSync(target, "utf8") === rewritten) {
+                removeIfPresent(source);
+                rows += 1;
+                continue;
+            }
+            throw new AdoptionError("adoption_row_collision", `a session-policy row for session "${row.__sid}" already exists under "${toPrincipal}" with different content — ` +
+                `merging two existing rows is a sync join, not a rewrite; the adoption marker is left in place for inspection`);
+        }
+        atomicWriteFile(tmpDir, target, rewritten);
+        removeIfPresent(source);
+        rows += 1;
+    }
+    return rows;
+}
+function removeIfPresent(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+}
+const ZERO_ACTION_STORES = [
+    "session",
+    "checkpoint",
+    "tool-result",
+    "file-snapshot",
+    "memory",
+    "task-list",
+    "mailbox",
+    "workflow-run",
+    "workflow-journal",
+    "background-agent",
+];
+const SESSION_POLICY_LEG = "session-policy";
+const CARRIAGE_BIT_PREFIX = "carriage:";
+function sameSource(a, b) {
+    return a.kind === "principal" ? b.kind === "principal" && a.principal === b.principal : b.kind === "local-owner";
+}
+function sourceText(o) {
+    return o.kind === "principal" ? `principal "${o.principal}"` : "the local owner";
+}
+function receiptFromTerminal(root, adopted) {
+    const account = readConfigAccountEvidence(root);
+    const accountBinds = account !== undefined && account.adoptionId === adopted.immutableReport.adoptionId;
+    return {
+        status: "adopted",
+        immutableReport: adopted.immutableReport,
+        current: {
+            outstandingConfigs: accountBinds
+                ? outstandingOf(account)
+                : adopted.immutableReport.affectedDeploymentConfigs.map((c) => `${c.deployment}:${c.key}`),
+            quarantined: listAdoptionQuarantine(root).length,
+        },
+    };
+}
+function rebuildConfigAccountIfUnbound(root, report) {
+    const account = readConfigAccountEvidence(root);
+    if (account !== undefined && account.adoptionId === report.adoptionId)
+        return;
+    writeConfigAccount(root, {
+        schemaVersion: 1,
+        adoptionId: report.adoptionId,
+        configs: report.affectedDeploymentConfigs.map((c) => ({ ...c })),
+    });
+}
+export function readAdoptionStatus(root) {
+    const f = readRootAdoptionFile(root);
+    if (f === undefined)
+        return { state: "none" };
+    if ("marker" in f) {
+        return { state: "in-flight", from: f.marker.from, toPrincipal: f.marker.toPrincipal, phase: f.marker.phase };
+    }
+    return { state: "adopted", receipt: receiptFromTerminal(root, f.adopted) };
+}
+function answerFromExisting(root, existing, from, toPrincipal) {
+    if (existing === undefined)
+        return undefined;
+    if ("adopted" in existing) {
+        if (existing.adopted.toPrincipal === toPrincipal && sameSource(existing.adopted.from, from)) {
+            return receiptFromTerminal(root, existing.adopted);
+        }
+        throw new AdoptionError("adoption_retarget", `this data root already carries a completed adoption (${sourceText(existing.adopted.from)} → "${existing.adopted.toPrincipal}") — ` +
+            `a second adoption of the same root is a multi-tenant transfer, not a shape this protocol supports`);
+    }
+    if (existing.marker.toPrincipal !== toPrincipal || !sameSource(existing.marker.from, from)) {
+        throw new AdoptionError("adoption_in_flight_mismatch", `an adoption toward "${existing.marker.toPrincipal}" is already in flight in this data root (phase ${existing.marker.phase}) — ` +
+            `refusing to start a different one (resume the original, or repair the marker by hand)`);
+    }
+    return undefined;
+}
+export async function adoptLocalDataRoot(opts) {
+    if (typeof opts.toPrincipal !== "string" || opts.toPrincipal === "") {
+        throw new AdoptionError("adoption_bad_request", "adoptLocalDataRoot requires the adopting principal — adoption is the act of giving this data root an identity");
+    }
+    if (opts.from.kind === "principal" && (typeof opts.from.principal !== "string" || opts.from.principal === "")) {
+        throw new AdoptionError("adoption_bad_request", "a principal-form source requires a non-empty principal — local-single-user identity is the local-owner kind, never an empty string");
+    }
+    if (opts.from.kind === "principal" && opts.from.principal === opts.toPrincipal) {
+        throw new AdoptionError("adoption_bad_request", `the data root already belongs to "${opts.toPrincipal}" — there is nothing to adopt`);
+    }
+    if (typeof opts.credentials.ref !== "string" || opts.credentials.ref === "") {
+        throw new AdoptionError("adoption_bad_request", "the credentials claim ref must be a non-empty reference (the claim is what makes the new identity redeemable)");
+    }
+    if (opts.from === null || typeof opts.from !== "object" || opts.credentials === null || typeof opts.credentials !== "object") {
+        throw new AdoptionError("adoption_bad_request", "adoptLocalDataRoot requires `from` and `credentials` objects");
+    }
+    if (opts.additionalConfigs !== undefined && !Array.isArray(opts.additionalConfigs)) {
+        throw new AdoptionError("adoption_bad_request", "additionalConfigs must be an array when supplied");
+    }
+    if (opts.carriage !== undefined && !Array.isArray(opts.carriage)) {
+        throw new AdoptionError("adoption_bad_request", "carriage must be an array when supplied");
+    }
+    if (opts.rules !== undefined && (opts.rules === null || typeof opts.rules !== "object")) {
+        throw new AdoptionError("adoption_bad_request", "rules must be an object when supplied");
+    }
+    if (opts.now !== undefined && typeof opts.now !== "function") {
+        throw new AdoptionError("adoption_bad_request", "`now` must be callable when supplied — it publishes the terminal timestamp");
+    }
+    if (opts.onError !== undefined && typeof opts.onError !== "function") {
+        throw new AdoptionError("adoption_bad_request", "`onError` must be callable when supplied");
+    }
+    if (opts.from.kind !== "local-owner" && opts.from.kind !== "principal") {
+        throw new AdoptionError("adoption_bad_request", "the adoption source must be the local-owner kind or a named principal");
+    }
+    if (opts.credentials.issuedBy !== "server") {
+        throw new AdoptionError("adoption_bad_request", `the credentials claim must be server-issued (got issuedBy: ${JSON.stringify(opts.credentials.issuedBy)}) — the server mints the new identity`);
+    }
+    for (const c of opts.additionalConfigs ?? []) {
+        if (c === null ||
+            typeof c !== "object" ||
+            typeof c.deployment !== "string" ||
+            c.deployment === "" ||
+            typeof c.key !== "string" ||
+            c.key === "" ||
+            typeof c.requiredValue !== "string" ||
+            typeof c.migrated !== "boolean") {
+            throw new AdoptionError("adoption_bad_request", `a malformed additionalConfigs entry (${JSON.stringify(c)}) — each entry is { deployment, key, requiredValue: strings; migrated: boolean }`);
+        }
+    }
+    if (opts.rules !== undefined && (typeof opts.rules.dir !== "string" || opts.rules.dir === "" || typeof opts.rules.transport !== "function")) {
+        throw new AdoptionError("adoption_bad_request", "a rules leg needs a non-empty bucket directory and a transport function");
+    }
+    {
+        const seen = new Set();
+        for (const leg of opts.carriage ?? []) {
+            if (leg === null || typeof leg !== "object" || typeof leg.store !== "string" || leg.store === "" || typeof leg.run !== "function") {
+                throw new AdoptionError("adoption_bad_request", "a carriage leg is { store: non-empty string; run: function }");
+            }
+            if (seen.has(leg.store)) {
+                throw new AdoptionError("adoption_bad_request", `two carriage legs share the store name "${leg.store}" — a leg's plan identity is its store family, one leg per store`);
+            }
+            seen.add(leg.store);
+        }
+    }
+    ensureDir(opts.root);
+    const pre = answerFromExisting(opts.root, readRootAdoptionFile(opts.root), opts.from, opts.toPrincipal);
+    if (pre !== undefined) {
+        const account = readConfigAccountEvidence(opts.root);
+        if (account !== undefined && account.adoptionId === pre.immutableReport.adoptionId)
+            return pre;
+    }
+    const engineLock = new BootLock(join(opts.root, "LOCK"));
+    try {
+        engineLock.acquire();
+    }
+    catch (err) {
+        throw new AdoptionError("adoption_locked", `a live instance owns this data root — stop the engine before adopting: ${err.message}`);
+    }
+    const adoptionLock = new BootLock(join(opts.root, "ADOPTION-LOCK"));
+    try {
+        adoptionLock.acquire();
+    }
+    catch (err) {
+        engineLock.release();
+        throw new AdoptionError("adoption_locked", `another adoption owns this data root: ${err.message}`);
+    }
+    try {
+        const existing = readRootAdoptionFile(opts.root);
+        const answered = answerFromExisting(opts.root, existing, opts.from, opts.toPrincipal);
+        if (answered !== undefined) {
+            rebuildConfigAccountIfUnbound(opts.root, answered.immutableReport);
+            return receiptFromTerminal(opts.root, {
+                from: answered.immutableReport.from,
+                toPrincipal: answered.immutableReport.toPrincipal,
+                atMs: answered.immutableReport.atMs,
+                immutableReport: answered.immutableReport,
+            });
+        }
+        const now = opts.now ?? Date.now;
+        const offeredRulesDir = opts.rules !== undefined ? resolve(opts.rules.dir) : undefined;
+        const offeredCarriage = (opts.carriage ?? []).map((l) => l.store);
+        let phase;
+        let adoptionId;
+        let legBits;
+        let plan;
+        if (existing !== undefined && "marker" in existing) {
+            phase = existing.marker.phase;
+            adoptionId = existing.marker.adoptionId;
+            legBits = existing.marker.legs ?? {};
+            plan = existing.marker.plan;
+            const missing = [];
+            if (plan.rulesDir !== undefined && offeredRulesDir !== plan.rulesDir) {
+                missing.push(`the permission-rule leg over "${plan.rulesDir}"${offeredRulesDir !== undefined ? ` (offered "${offeredRulesDir}")` : ""}`);
+            }
+            const offered = new Set(offeredCarriage);
+            for (const store of plan.carriage)
+                if (!offered.has(store))
+                    missing.push(`the "${store}" carriage leg`);
+            if (plan.credentialsRef !== opts.credentials.ref)
+                missing.push(`the credentials claim (recorded "${plan.credentialsRef}")`);
+            if (missing.length > 0) {
+                throw new AdoptionError("adoption_plan_mismatch", `this resume supplies less than the adoption's recorded plan — missing: ${missing.join("; ")}. ` +
+                    `Re-run with the original legs (growing the plan is fine, shrinking it is not), or repair the marker by hand.`);
+            }
+            const lateAdds = [];
+            if (plan.rulesDir === undefined && offeredRulesDir !== undefined) {
+                if (phase < 3)
+                    plan = { ...plan, rulesDir: offeredRulesDir };
+                else
+                    lateAdds.push(`the permission-rule leg (stage ③ already completed at phase ${phase})`);
+            }
+            const knownCarriage = new Set(plan.carriage);
+            const newCarriage = offeredCarriage.filter((s) => !knownCarriage.has(s));
+            if (newCarriage.length > 0) {
+                if (phase < 5)
+                    plan = { ...plan, carriage: [...plan.carriage, ...newCarriage] };
+                else
+                    lateAdds.push(`the ${newCarriage.map((s) => `"${s}"`).join("/")} carriage leg(s) (stage ⑤ already completed)`);
+            }
+            if (lateAdds.length > 0) {
+                throw new AdoptionError("adoption_plan_mismatch", `this resume offers legs whose stage has already completed — ${lateAdds.join("; ")}. ` +
+                    `They would never run, and reporting them as done would be a lie; post-adoption carriage rides each store's normal channel.`);
+            }
+            if (plan !== existing.marker.plan) {
+                publishMarker(opts.root, adoptionId, opts.from, opts.toPrincipal, phase, plan, legBits);
+            }
+            const accountInFlight = readConfigAccount(opts.root);
+            if (accountInFlight === undefined || accountInFlight.adoptionId !== adoptionId) {
+                throw new AdoptionError("adoption_marker_corrupt", `the adoption config account is ${accountInFlight === undefined ? "missing" : "bound to a different adoption"} while an adoption is in flight — ` +
+                    `it lands before the marker and never disappears mid-arc; restore it before resuming`);
+            }
+            upsertConfigAccount(opts.root, adoptionId, opts.toPrincipal, opts.additionalConfigs ?? []);
+        }
+        else {
+            adoptionId = `adp_${randomBytes(8).toString("hex")}`;
+            phase = 2;
+            legBits = {};
+            plan = { ...(offeredRulesDir !== undefined ? { rulesDir: offeredRulesDir } : {}), carriage: offeredCarriage, credentialsRef: opts.credentials.ref };
+            upsertConfigAccount(opts.root, adoptionId, opts.toPrincipal, opts.additionalConfigs ?? []);
+            publishMarker(opts.root, adoptionId, opts.from, opts.toPrincipal, 2, plan, legBits);
+        }
+        const legs = [];
+        if (phase < 3) {
+            if (opts.rules !== undefined) {
+                let nested;
+                try {
+                    nested = await adoptFilePermissionRuleStore({
+                        dir: opts.rules.dir,
+                        from: opts.from,
+                        toPrincipal: opts.toPrincipal,
+                        transport: opts.rules.transport,
+                        ...(opts.now !== undefined ? { now: opts.now } : {}),
+                        ...(opts.onError !== undefined ? { onError: opts.onError } : {}),
+                    });
+                }
+                catch (err) {
+                    if (err instanceof AdoptionError)
+                        throw err;
+                    throw new AdoptionError("adoption_rule_leg_refused", `the permission-rule leg refused: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                if (nested.status === "stalled") {
+                    return {
+                        status: "stalled",
+                        phase: 2,
+                        error: `the permission-rule leg stalled (its own marker holds phase ${nested.phase}): ${nested.error}`,
+                    };
+                }
+            }
+            if (legBits[SESSION_POLICY_LEG]?.done !== true) {
+                const rows = rewriteSessionPolicyRows(opts.root, opts.from.kind === "principal" ? opts.from.principal : null, opts.toPrincipal);
+                legBits = { ...legBits, [SESSION_POLICY_LEG]: { done: true, rows } };
+                publishMarker(opts.root, adoptionId, opts.from, opts.toPrincipal, 2, plan, legBits);
+            }
+            publishMarker(opts.root, adoptionId, opts.from, opts.toPrincipal, 3, plan, legBits);
+            phase = 3;
+        }
+        if (phase < 4) {
+            publishMarker(opts.root, adoptionId, opts.from, opts.toPrincipal, 4, plan, legBits);
+            phase = 4;
+        }
+        if (phase < 5) {
+            for (const leg of opts.carriage ?? []) {
+                if (legBits[`${CARRIAGE_BIT_PREFIX}${leg.store}`]?.done === true)
+                    continue;
+                let quarantined = 0;
+                const ctx = {
+                    quarantine: (name, bytes) => {
+                        quarantineRow(opts.root, leg.store, name, bytes);
+                        quarantined += 1;
+                    },
+                };
+                let rows;
+                try {
+                    const res = await leg.run(ctx);
+                    rows = res === undefined ? undefined : res.rows;
+                }
+                catch (err) {
+                    return {
+                        status: "stalled",
+                        phase: 4,
+                        error: `the "${leg.store}" carriage leg failed: ${err instanceof Error ? err.message : String(err)} — resume when it is healthy`,
+                    };
+                }
+                if (rows !== undefined && (!Number.isSafeInteger(rows) || rows < 0)) {
+                    return {
+                        status: "stalled",
+                        phase: 4,
+                        error: `the "${leg.store}" carriage leg reported an invalid row count (${String(rows)}) — a leg reports a non-negative integer or nothing; fix the leg and resume`,
+                    };
+                }
+                legBits = {
+                    ...legBits,
+                    [`${CARRIAGE_BIT_PREFIX}${leg.store}`]: {
+                        done: true,
+                        ...(rows !== undefined ? { rows } : {}),
+                        ...(quarantined > 0 ? { quarantined } : {}),
+                    },
+                };
+                publishMarker(opts.root, adoptionId, opts.from, opts.toPrincipal, 4, plan, legBits);
+            }
+            publishMarker(opts.root, adoptionId, opts.from, opts.toPrincipal, 5, plan, legBits);
+            phase = 5;
+        }
+        if (plan.rulesDir !== undefined)
+            legs.push({ store: "permission-rule", action: "bucket-rebind" });
+        legs.push({ store: SESSION_POLICY_LEG, action: "row-rewrite", rows: legBits[SESSION_POLICY_LEG]?.rows ?? 0 });
+        const carried = Object.entries(legBits)
+            .filter(([k]) => k.startsWith(CARRIAGE_BIT_PREFIX))
+            .map(([k, bit]) => ({
+            store: k.slice(CARRIAGE_BIT_PREFIX.length),
+            action: "carried",
+            ...(bit.rows !== undefined ? { rows: bit.rows } : {}),
+            ...(bit.quarantined !== undefined ? { quarantined: bit.quarantined } : {}),
+        }));
+        legs.push(...carried);
+        const carriedNames = new Set(carried.map((l) => l.store));
+        for (const store of ZERO_ACTION_STORES) {
+            if (!carriedNames.has(store))
+                legs.push({ store, action: "none" });
+        }
+        legs.push({ store: "usage-window", action: "reset" });
+        const account = readConfigAccount(opts.root);
+        const atMs = now();
+        if (!Number.isSafeInteger(atMs) || atMs < 0) {
+            return {
+                status: "stalled",
+                phase: 5,
+                error: `the clock returned an invalid timestamp (${String(atMs)}) — refusing to publish a terminal record the reader would reject; fix the injected clock and resume`,
+            };
+        }
+        const immutableReport = {
+            adoptionId,
+            from: opts.from,
+            toPrincipal: opts.toPrincipal,
+            atMs,
+            credentials: opts.credentials,
+            affectedDeploymentConfigs: (account?.configs ?? []).map(({ deployment, key, requiredValue, migrated }) => ({ deployment, key, requiredValue, migrated })),
+            legs,
+            notMigratedByDesign: NOT_MIGRATED_BY_DESIGN.map((e) => ({ ...e })),
+        };
+        writeRootAdoptionFile(opts.root, {
+            schemaVersion: 1,
+            adopted: { from: opts.from, toPrincipal: opts.toPrincipal, atMs: immutableReport.atMs, immutableReport },
+        });
+        return receiptFromTerminal(opts.root, { from: opts.from, toPrincipal: opts.toPrincipal, atMs: immutableReport.atMs, immutableReport });
+    }
+    finally {
+        adoptionLock.release();
+        engineLock.release();
+    }
+}
+function publishMarker(root, adoptionId, from, toPrincipal, phase, plan, legs) {
+    writeRootAdoptionFile(root, {
+        schemaVersion: 1,
+        marker: { adoptionId, from, toPrincipal, phase, plan, ...(Object.keys(legs).length > 0 ? { legs } : {}) },
+    });
+}