@sema-agent/core 7.54.1 → 7.55.0

package/dist/orchestration/workflow.js

@@ -12,14 +12,14 @@ import { GENERAL_PURPOSE_SUBAGENT_TYPE, markerFragment } from "../agents/subagen
 import { deploymentSubagentSystemPrompt, runnerRoleMap } from "../agents/child-model-seat.js";
 import { combinePolicies, createAllowDenyPolicy } from "../core/tool-policy.js";
 import { createSafeNotifier } from "../core/safe-notify.js";
-import { callKeyOrdinal, oversizeJournalResult, journalOversizeTombstone, JOURNAL_OVERSIZE_ERROR_CODE, MAX_JOURNAL_RESULT_BYTES } from "../core/workflow-journal-store.js";
+import { callKeyOrdinal, clampRunIdText, oversizeJournalResult, journalOversizeTombstone, readWorkflowJournalEntry, JOURNAL_OVERSIZE_ERROR_CODE, MAX_JOURNAL_RESULT_BYTES, WorkflowJournalIncompatibleError, } from "../core/workflow-journal-store.js";
 import { isWorkflowRunActive, closeWorkflowChannel, markWorkflowActive, publishWorkflowEvent } from "./workflow-observe.js";
 import { isDurablePause } from "../agents/suspend-guard.js";
 import { RUNNING_AGENT_OBSERVE_EVERY_BEATS } from "../config/defaults.js";
 import { boundInputHashOf } from "../core/canonical-json.js";
 import { boundedRedactedSummary, egressThrownText } from "../core/untrusted-egress.js";
 import { delimitUntrusted } from "../core/untrusted-text.js";
-import { OUTPUT_TOOL_NAME } from "../core/runner/synthetic-tools.js";
+import { OUTPUT_TOOL_NAME } from "../core/tool-catalog-entries.js";
 import { deniedToolNamesOf, judgeHostToolCeiling } from "../core/runner/sub-agent-deny-lists.js";
 import { compileOutputSchema } from "../core/runner/strict-output-schema.js";
 import { WorkflowBudgetExceededError, WorkflowNestingError, WorkflowAgentBlockedError, WorkflowAgentParkedError, WorkflowAgentSchemaError, WorkflowAgentStalledError, WorkflowMaxAgentsError, WORKFLOW_SPAWN_BLOCKED_ERROR_CODE } from "./workflow-types.js";
@@ -142,7 +142,7 @@ function withWorkflowChildSeats(typed, inheritedModelSnap, inheritedThinkingSnap
     const statedPersona = deploymentSubagentSystemPrompt(roles);
     return {
         ...typed,
-        modelRole: typed.modelRole ?? "subagent",
+        modelRole: typed.modelRole === undefined ? "subagent" : typed.modelRole,
         ...(typed.model === undefined && inheritedModelSnap !== undefined ? { model: inheritedModelSnap } : {}),
         ...(typed.thinking === undefined && inheritedThinkingSnap !== undefined ? { thinking: inheritedThinkingSnap } : {}),
         ...(typed.systemPrompt === undefined && statedPersona !== undefined ? { systemPrompt: statedPersona } : {}),
@@ -229,17 +229,14 @@ export class WorkflowResultTooLargeError extends Error {
         this.name = "WorkflowResultTooLargeError";
     }
 }
-export class WorkflowJournalIncompatibleError extends Error {
-    fromRunId;
-    ordinal;
-    code = "workflow.journal_incompatible";
-    constructor(fromRunId, ordinal) {
-        super(`startWorkflow: resume from "${fromRunId}" was REFUSED — journal entry #${ordinal} carries no terminal cause (a journal written before TaskResult.terminal, or a malformed entry). ` +
-            "Completed work must not run again; start a fresh run instead of resuming this journal.");
-        this.fromRunId = fromRunId;
-        this.ordinal = ordinal;
-        this.name = "WorkflowJournalIncompatibleError";
-    }
+function judgedJournal(runId, rows) {
+    return rows.map((raw) => {
+        const read = readWorkflowJournalEntry(raw);
+        if (!("corrupt" in read))
+            return read.entry;
+        const callKey = raw?.callKey;
+        throw new WorkflowJournalIncompatibleError(runId, typeof callKey === "string" ? callKeyOrdinal(callKey) : -1, raw);
+    });
 }
 export class WorkflowJournalAppendTimeoutError extends Error {
     runId;
@@ -475,9 +472,6 @@ function createSemaphore(max) {
         }),
     };
 }
-function clampRunIdText(raw) {
-    return raw.replace(/[^A-Za-z0-9_.:-]/g, "").slice(0, 64);
-}
 const fallbackResumeClaimTables = new WeakMap();
 function fallbackResumeClaimKey(scope, sourceRunId) {
     return JSON.stringify([scope, sourceRunId]);
@@ -933,7 +927,9 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         if (key.originRunId === opts.resumeFromRunId)
             entry = replayByOrdinal[ordinal];
         else if (journalStore) {
-            const loaded = await finalizeWithin(timers, new Promise((resolve) => resolve(journalStore.load(key.originRunId, scope))).then((entries) => ({ entries }), (err) => ({ err })), "timeout");
+            const loaded = await finalizeWithin(timers, new Promise((resolve) => resolve(journalStore.load(key.originRunId, scope)))
+                .then((rows) => ({ entries: judgedJournal(key.originRunId, rows) }))
+                .catch((err) => ({ err })), "timeout");
             if (loaded === "timeout" || "err" in loaded) {
                 emitRunLog(`resume: the journal of run "${clampRunIdText(key.originRunId)}" (the origin of the park at ordinal ${ordinal}) could not be read (${loaded === "timeout" ? `the load did not settle within ${WORKFLOW_RESUME_CLAIM_FINALIZE_TIMEOUT_MS}ms` : withoutToken(errText(loaded.err), key.token)}).`);
             }
@@ -2299,22 +2295,16 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                             "re-run the whole suffix live, duplicating every side effect. Wait for the holder to reach a terminal " +
                             "state (or stop it) and resume again.");
                     }
-                    const entries = await journalStore.load(opts.resumeFromRunId, scope);
+                    const entries = judgedJournal(opts.resumeFromRunId, await journalStore.load(opts.resumeFromRunId, scope));
                     for (const e of entries) {
-                        const parked = e.parked;
-                        if (parked !== undefined) {
-                            const pt = parked?.terminal;
-                            if (pt === null || typeof pt !== "object" || pt.kind !== "paused" || typeof pt.token !== "string" || pt.token.length === 0) {
-                                throw new WorkflowJournalIncompatibleError(clampRunIdText(opts.resumeFromRunId), callKeyOrdinal(e.callKey));
+                        const ordinal = callKeyOrdinal(e.callKey);
+                        if (e.parked === undefined) {
+                            const t = e.result.terminal;
+                            if (t === null || typeof t !== "object" || !isTerminalCauseKind(t.kind)) {
+                                throw new WorkflowJournalIncompatibleError(opts.resumeFromRunId, ordinal);
                             }
-                            replayByOrdinal[callKeyOrdinal(e.callKey)] = e;
-                            continue;
-                        }
-                        const t = e.result?.terminal;
-                        if (t === null || typeof t !== "object" || !isTerminalCauseKind(t.kind)) {
-                            throw new WorkflowJournalIncompatibleError(clampRunIdText(opts.resumeFromRunId), callKeyOrdinal(e.callKey));
                         }
-                        replayByOrdinal[callKeyOrdinal(e.callKey)] = e;
+                        replayByOrdinal[ordinal] = e;
                     }
                     const fromRunId = clampRunIdText(opts.resumeFromRunId);
                     let prior = null;

package/dist/prompt-assembly/event-registry.js

@@ -20,6 +20,7 @@ export const EVENT_PROMPT_REGISTRY = new Map([
     { kind: "limit_approach_converge", carrier: "message.user-prefix", trust: "operator", dedupe: "once-per-run", defaultPolicy: "always", rendererRef: "run-turn-boundary.ts#limitApproachFrames" },
     { kind: "limit_approach_deliver", carrier: "message.user-prefix", trust: "operator", dedupe: "once-per-run", defaultPolicy: "always", rendererRef: "run-turn-boundary.ts#limitApproachFrames" },
     { kind: "final_verification", carrier: "message.user-prefix", trust: "operator", dedupe: "once-per-run", defaultPolicy: "always", rendererRef: "runtask.ts#final-verification" },
+    { kind: "advisor_tool", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "always", rendererRef: "advisor-instructions.ts#advisorInstructionFrame" },
 ].map((e) => [e.kind, e]));
 export function eventDefaultOn(kind) {
     return EVENT_PROMPT_REGISTRY.get(kind)?.defaultPolicy === "on";

package/dist/prompt-assembly/tool-catalog.d.ts

@@ -4,6 +4,9 @@ import type { ProtocolId } from "../core/protocol-table.js";
 /** The protocol slice comes from the protocol table — adding a protocol extends ProtocolId and this
  *  union follows automatically (the origin projection is table-driven, prepare-task). */
 export type ToolOrigin = "core" | "caller" | "synthetic" | ProtocolId;
+/** The origin a declared contract id names: a `core.` id is one of the engine's own contracts, any other id a caller's. The one
+ *  reading of the prefix — the definition factory attaches by it, and the caller-tool door refuses a caller spec that declares one. */
+export declare function contractOriginOf(contractId: string): "core" | "caller";
 export interface ToolContractDescriptor {
     /** Stable contract identity, e.g. `core.read@2`. Versioned independently of the wire name. */
     contractId: string;

package/dist/prompt-assembly/tool-catalog.js

@@ -1,4 +1,7 @@
 import { createHash } from "node:crypto";
+export function contractOriginOf(contractId) {
+    return contractId.startsWith("core.") ? "core" : "caller";
+}
 const PRESENTATION_KEYWORDS = new Set(["description", "title", "examples", "$id"]);
 const SCHEMA_NAME_MAPS = new Set([
     "properties",

package/dist/prompts/default.d.ts

@@ -17,7 +17,7 @@ export declare const SUBAGENT_DELIVERY_NOTES: string;
 /**
  * Memory **safety** rules — a STANDALONE prompt asset, NOT injected by core. The flag-driven injection
  * (`memoryEnabled`/`consolidationEnabled` → a `memory.safety` constitution block) was retired in
- * RB-482 #16 along with both flags; the engine now injects the CC-verbatim `# Memory` instruction via
+ * RB-482 #16 along with both flags; the engine now injects the `# Memory` instruction via
  * the memory engine's `injection.block` instead. A deployment composing its own prompt is responsible
  * for including this block, and should treat it as non-suppressible: it carries the load-bearing
  * constraints (declarative-fact-not-command + the no-secrets rule + the
@@ -71,8 +71,8 @@ export declare const EXECUTION_ENVIRONMENT_OPEN_READS: string;
 /** The isolated-worktree notice, composed only when the task really runs in an isolated git worktree. */
 export declare const WORKTREE_NOTICE: string;
 /**
- * RB-314 — CC 2.1.220 `atp` (@597127 (cli250.js:44534)) VERBATIM. Rides the variable `# Environment` tail (see
- * {@link buildEnvironmentContext}), which is exactly where 220 emits it: both env-block assemblers
+ * RB-314 — Rides the variable `# Environment` tail (see
+ * {@link buildEnvironmentContext}), which is exactly where the reference emits it: both env-block assemblers
  * (@596927 `IMy`, @596976 `OMy`) push `worktree ? atp : null` directly after the isolated-copy
  * directive. Deliberately NOT folded into {@link WORKTREE_NOTICE}: that block is composed only for
  * `isolation: "worktree"` spawns, while the hazard belongs to ANY run whose cwd is a linked worktree
@@ -120,7 +120,7 @@ export interface EnvironmentFacts {
     /** design/99 §E14 — the working tree's toplevel (`git rev-parse --show-toplevel`). Lets the agent/shell know
      *  it may be in a linked worktree rather than the main checkout. */
     gitWorktreeRoot?: string;
-    /** design/119 (CC 198): cwd is a LINKED git worktree (git-dir ≠ git-common-dir) — an isolated copy. */
+    /** design/119: cwd is a LINKED git worktree (git-dir ≠ git-common-dir) — an isolated copy. */
     isLinkedWorktree?: boolean;
     /** design/119 (CC --add-dir parity): extra directories the file tools may access (canonical). */
     additionalDirectories?: readonly string[];
@@ -164,7 +164,7 @@ export interface EnvironmentFacts {
     /** A1 — outbound-network posture; `none` renders an explicit downloads-will-fail caveat (TB
      *  autopsy 2026-07-05: agents burned budget retrying downloads in a no-egress sandbox). */
     sandboxEgress?: "none" | "allowlist" | "full";
-    /** H4 (CC 2.1.198 git snapshot) — the pre-rendered {@link buildGitSnapshot} block. env-tail
+    /** H4 — the pre-rendered {@link buildGitSnapshot} block. env-tail
      *  migration (#254 shape): NO LONGER RENDERED by {@link buildEnvironmentContext} — the snapshot is
      *  the turn-dynamic git view and rides the `git_status` frame (re-sent only when the rendered view
      *  changes); the field remains as a structured data carrier for callers that assembled it. */
@@ -185,17 +185,17 @@ export interface EnvironmentFacts {
      * it twice could drift). Renders ONE neutral declarative line; absent ⇒ nothing renders.
      */
     externalContentTarget?: boolean;
-    /** CC 2.1.198 `MZn` Scratchpad port (system-prompt diff 档 2026-07-08 §13, 活体逐字双证) — the
+    /** Scratchpad port — the
      *  session-scoped temp directory the agent should use instead of `/tmp` (parallel tasks/multi-tenant
      *  deployments clobber each other's `/tmp`; project checkouts collect stray temp files without it).
      *  DEPLOYMENT-supplied, and only injected when set — the deployment MUST have created (or be about to
-     *  create) the directory; core renders the CC-verbatim section with this path interpolated (§6.3:
+     *  create) the directory; core renders the section with this path interpolated (§6.3:
      *  never advertise a directory the task doesn't have). */
     scratchpadDir?: string;
 }
 /**
- * CC 2.1.198 `# Scratchpad Directory` section (bundle `MZn`, L590674; 活体 2026-07-08 byte-match) with the
- * path parameterized for the deployment. Wording is verbatim CC — including the closing permission-prompts
+ * The `# Scratchpad Directory` section with the
+ * path parameterized for the deployment. Wording as in the reference — including the closing permission-prompts
  * sentence, which holds for sema too (an approval-gated deployment normally allowlists its own scratchpad) —
  * PLUS one sema-added ephemerality sentence (ruled 2026-08-05): sema deployments run under durable suspend /
  * multi-replica serving where the scratchpad is a local-disk copy that does NOT survive a cross-replica
@@ -204,22 +204,22 @@ export interface EnvironmentFacts {
  * in a directory that can vanish mid-task. Volatility magnitude only — no serving-layer mechanism names.
  */
 export declare function buildScratchpadSection(scratchpadDir: string): string;
-/** CC 2.1.198 `Juo` — the git status truncation bound (chars) for {@link buildGitSnapshot}. */
+/** The git status truncation bound (chars) for {@link buildGitSnapshot}. */
 export declare const GIT_STATUS_MAX_CHARS = 2000;
-/** The CC-verbatim first paragraph of the git snapshot (CC 2.1.198 `Quo` head sentence). Kept as a
+/** The first paragraph of the git snapshot. Kept as a
  *  named constant so the git-status FRAME renderer (the snapshot's carrier since the env-tail
  *  migration) can swap exactly this paragraph for its own update-semantics preamble — under the
  *  frame protocol the snapshot IS re-sent when the visible view changes, so the "will not update"
  *  claim would be false there. {@link buildGitSnapshot} itself still renders it byte-exact. */
 export declare const GIT_SNAPSHOT_CC_PREAMBLE = "This is the git status at the start of the conversation. Note that this status is a snapshot in time, and will not update during the conversation.";
 /**
- * H4 — the CC 2.1.198 ENV git snapshot block (B1/B2; template + truncation copy verified against
- * observed Claude Code v2.1.198 behavior). Pure renderer — the Runner gathers the raw values through the
+ * H4 — the ENV git snapshot block (B1/B2).
+ * Pure renderer — the Runner gathers the raw values through the
  * ExecutionEnv seam (remote = the container's repo) and calls this once per prepareTask (a durable
  * resume re-prepares → re-snapshots, CC new-session 同型). env-tail migration (#254 shape): the
  * rendered block now feeds the `git_status` TURN FRAME (src/core/runner/git-status-frame.ts, which
  * swaps the {@link GIT_SNAPSHOT_CC_PREAMBLE} for an update-semantics preamble) instead of the
- * `# Environment` system-prompt section — the template body itself stays CC-verbatim.
+ * `# Environment` system-prompt section — the template body itself is unchanged.
  *
  * Sanitization (deliberate CC deviation — CC injects raw): status/log/branch/user are REPO-controlled
  * text (filenames, commit subjects, an untrusted clone's config) landing in the TRUSTED prompt region →

package/dist/scenarios/full-body.d.ts

@@ -27,7 +27,7 @@ export interface CodeToolsConfig {
      *  general-purpose delegation). Pass an explicit `systemPrompt` here to override. */
     subagent?: SubagentToolOptions;
     /**
-     * TodoWrite (CONTEXT leg). Default true, BUT mutually exclusive with the task-list family (CC 209
+     * TodoWrite (CONTEXT leg). Default true, BUT mutually exclusive with the task-list family (
      * parity: TodoWrite is enabled only when the task list is off). With `taskList` on (the default),
      * TodoWrite is NOT mounted even when `todoWrite: true` is set explicitly — the exclusion gate wins;
      * pass `taskList: false` to get TodoWrite back. `todoWrite: false` always drops it.
@@ -36,8 +36,8 @@ export interface CodeToolsConfig {
      */
     todoWrite?: boolean;
     /**
-     * design/119 → CC209 对齐批B B3: the structured task-list family (TaskCreate/TaskGet/TaskUpdate/
-     * TaskList — stable ids, status transitions, dependencies). Default TRUE (CC 209 alignment: the task
+     * design/119 → B3: the structured task-list family (TaskCreate/TaskGet/TaskUpdate/
+     * TaskList — stable ids, status transitions, dependencies). Default TRUE (the task
      * list is on unless explicitly disabled, and TodoWrite is its off-state fallback — the two families
      * are mutually exclusive, never co-mounted). Only an explicit `taskList: false` reverts to the
      * TodoWrite shape.
@@ -47,7 +47,7 @@ export interface CodeToolsConfig {
      */
     taskList?: boolean;
     /**
-     * design/147 §6 D2 (CC 2.1.216 shared team task list): a shared {@link TaskListStore} for the
+     * design/147 §6 D2 (shared team task list): a shared {@link TaskListStore} for the
      * task-list family. Mount the SAME instance into each teammate's bundle to share one team task
      * list (the `owner` claim semantics come alive); absent ⇒ the private per-run list (unchanged
      * default). Ignored when `taskList: false`. This bundle's own Agent children share it by inheritance.

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

@@ -56,7 +56,8 @@
  * file half ships the freeze face, the acceptance face and the rebind legs.
  */
 import type { PermissionRuleSyncTransport } from "../../../core/permission-rule-sync.js";
-import { type AdoptionReceipt, type AdoptionSource, type AffectedDeploymentConfig } from "./marker.js";
+import { type AdoptionReceipt, type AffectedDeploymentConfig } from "./marker.js";
+import { type RuleOwner } from "../../../core/rule-owner.js";
 /** The per-leg context handed to a carriage leg: rows the far side REFUSES go here — preserved and
  *  disclosed, never deleted (design/183 §7.2). Quarantining never fails the leg. */
 export interface AdoptionCarriageLegContext {
@@ -79,7 +80,7 @@ export interface AdoptionCarriageLeg {
 export interface AdoptLocalDataRootOptions {
     /** The data root (the directory `FileStorageBackend` and the independent file stores build over). */
     root: string;
-    from: AdoptionSource;
+    from: RuleOwner;
     toPrincipal: string;
     /** The claim REFERENCE for the new identity's credentials (minted by the server; design/183 §4.3).
      *  A reference, never the credential bytes — the marker file is a plain-text sidecar. */
@@ -141,7 +142,7 @@ export type AdoptionStatus = {
     state: "none";
 } | {
     state: "in-flight";
-    from: AdoptionSource;
+    from: RuleOwner;
     toPrincipal: string;
     phase: 2 | 3 | 4 | 5;
 } | {

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

@@ -7,6 +7,7 @@ import { SESSION_POLICY_MARK_SUFFIX, attributeSessionPolicyRow, judgeSessionPoli
 import { SessionPolicyError } from "../../../core/session-policy-store.js";
 import { thrownText } from "../../../core/thrown-value.js";
 import { AdoptionError, NOT_MIGRATED_BY_DESIGN, readRootAdoptionFile, writeRootAdoptionFile, } from "./marker.js";
+import { readRuleOwner, ruleOwnerText, sameRuleOwner } from "../../../core/rule-owner.js";
 const CONFIG_ACCOUNT_FILE = "adoption-configs.json";
 function baselineConfigs(toPrincipal) {
     return [
@@ -282,12 +283,6 @@ const ZERO_ACTION_STORES = [
 ];
 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;
@@ -325,13 +320,13 @@ 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)) {
+        if (existing.adopted.toPrincipal === toPrincipal && sameRuleOwner(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}") — ` +
+        throw new AdoptionError("adoption_retarget", `this data root already carries a completed adoption (${ruleOwnerText(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)) {
+    if (existing.marker.toPrincipal !== toPrincipal || !sameRuleOwner(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)`);
     }
@@ -341,17 +336,18 @@ 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");
+    const from = readRuleOwner(opts.from);
+    if (from === undefined) {
+        throw new AdoptionError("adoption_bad_request", "the adoption source must be the local-owner kind or a principal with a non-blank name — local-single-user identity is the local-owner kind, never a blank string");
     }
-    if (opts.from.kind === "principal" && opts.from.principal === opts.toPrincipal) {
+    if (from.kind === "principal" && 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.credentials === null || typeof opts.credentials !== "object") {
+        throw new AdoptionError("adoption_bad_request", "adoptLocalDataRoot requires a `credentials` object");
     }
     if (opts.additionalConfigs !== undefined && !Array.isArray(opts.additionalConfigs)) {
         throw new AdoptionError("adoption_bad_request", "additionalConfigs must be an array when supplied");
@@ -368,9 +364,6 @@ export async function adoptLocalDataRoot(opts) {
     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`);
     }
@@ -402,7 +395,7 @@ export async function adoptLocalDataRoot(opts) {
         }
     }
     ensureDir(opts.root);
-    const pre = answerFromExisting(opts.root, readRootAdoptionFile(opts.root), opts.from, opts.toPrincipal);
+    const pre = answerFromExisting(opts.root, readRootAdoptionFile(opts.root), from, opts.toPrincipal);
     if (pre !== undefined) {
         const account = readConfigAccountEvidence(opts.root);
         if (account !== undefined && account.adoptionId === pre.immutableReport.adoptionId)
@@ -425,7 +418,7 @@ export async function adoptLocalDataRoot(opts) {
     }
     try {
         const existing = readRootAdoptionFile(opts.root);
-        const answered = answerFromExisting(opts.root, existing, opts.from, opts.toPrincipal);
+        const answered = answerFromExisting(opts.root, existing, from, opts.toPrincipal);
         if (answered !== undefined) {
             rebuildConfigAccountIfUnbound(opts.root, answered.immutableReport);
             return receiptFromTerminal(opts.root, {
@@ -481,7 +474,7 @@ export async function adoptLocalDataRoot(opts) {
                     `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);
+                publishMarker(opts.root, adoptionId, from, opts.toPrincipal, phase, plan, legBits);
             }
             const accountInFlight = readConfigAccount(opts.root);
             if (accountInFlight === undefined || accountInFlight.adoptionId !== adoptionId) {
@@ -496,7 +489,7 @@ export async function adoptLocalDataRoot(opts) {
             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);
+            publishMarker(opts.root, adoptionId, from, opts.toPrincipal, 2, plan, legBits);
         }
         const legs = [];
         if (phase < 3) {
@@ -505,7 +498,7 @@ export async function adoptLocalDataRoot(opts) {
                 try {
                     nested = await adoptFilePermissionRuleStore({
                         dir: opts.rules.dir,
-                        from: opts.from,
+                        from,
                         toPrincipal: opts.toPrincipal,
                         transport: opts.rules.transport,
                         ...(opts.now !== undefined ? { now: opts.now } : {}),
@@ -526,15 +519,15 @@ export async function adoptLocalDataRoot(opts) {
                 }
             }
             if (legBits[SESSION_POLICY_LEG]?.done !== true) {
-                const rows = rewriteSessionPolicyRows(opts.root, opts.from.kind === "principal" ? opts.from.principal : null, opts.toPrincipal);
+                const rows = rewriteSessionPolicyRows(opts.root, from.kind === "principal" ? 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, from, opts.toPrincipal, 2, plan, legBits);
             }
-            publishMarker(opts.root, adoptionId, opts.from, opts.toPrincipal, 3, plan, legBits);
+            publishMarker(opts.root, adoptionId, from, opts.toPrincipal, 3, plan, legBits);
             phase = 3;
         }
         if (phase < 4) {
-            publishMarker(opts.root, adoptionId, opts.from, opts.toPrincipal, 4, plan, legBits);
+            publishMarker(opts.root, adoptionId, from, opts.toPrincipal, 4, plan, legBits);
             phase = 4;
         }
         if (phase < 5) {
@@ -575,9 +568,9 @@ export async function adoptLocalDataRoot(opts) {
                         ...(quarantined > 0 ? { quarantined } : {}),
                     },
                 };
-                publishMarker(opts.root, adoptionId, opts.from, opts.toPrincipal, 4, plan, legBits);
+                publishMarker(opts.root, adoptionId, from, opts.toPrincipal, 4, plan, legBits);
             }
-            publishMarker(opts.root, adoptionId, opts.from, opts.toPrincipal, 5, plan, legBits);
+            publishMarker(opts.root, adoptionId, from, opts.toPrincipal, 5, plan, legBits);
             phase = 5;
         }
         if (plan.rulesDir !== undefined)
@@ -609,7 +602,7 @@ export async function adoptLocalDataRoot(opts) {
         }
         const immutableReport = {
             adoptionId,
-            from: opts.from,
+            from,
             toPrincipal: opts.toPrincipal,
             atMs,
             credentials: opts.credentials,
@@ -619,9 +612,9 @@ export async function adoptLocalDataRoot(opts) {
         };
         writeRootAdoptionFile(opts.root, {
             schemaVersion: 1,
-            adopted: { from: opts.from, toPrincipal: opts.toPrincipal, atMs: immutableReport.atMs, immutableReport },
+            adopted: { from, toPrincipal: opts.toPrincipal, atMs: immutableReport.atMs, immutableReport },
         });
-        return receiptFromTerminal(opts.root, { from: opts.from, toPrincipal: opts.toPrincipal, atMs: immutableReport.atMs, immutableReport });
+        return receiptFromTerminal(opts.root, { from, toPrincipal: opts.toPrincipal, atMs: immutableReport.atMs, immutableReport });
     }
     finally {
         adoptionLock.release();

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

@@ -14,17 +14,10 @@
  *    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.
+ * This module is deliberately tiny and dependency-light (node:fs, the atomic-write primitive, the import-free owner
+ * reading): 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;
-};
+import { type RuleOwner } from "../../../core/rule-owner.js";
 /** 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 = 
@@ -81,7 +74,7 @@ export interface AdoptionLegReport {
 export interface AdoptionReport {
     /** Minted at phase ② — the binding anchor config-witness receipts must carry. */
     adoptionId: string;
-    from: AdoptionSource;
+    from: RuleOwner;
     toPrincipal: string;
     atMs: number;
     /** The claim REFERENCE for the new identity's credentials — never the credentials themselves (the
@@ -120,7 +113,7 @@ export type RootAdoptionFile = {
     schemaVersion: 1;
     marker: {
         adoptionId: string;
-        from: AdoptionSource;
+        from: RuleOwner;
         toPrincipal: string;
         phase: 2 | 3 | 4 | 5;
         /** The migration plan recorded at phase ② and grown MONOTONICALLY across resumes — what a
@@ -147,7 +140,7 @@ export type RootAdoptionFile = {
 } | {
     schemaVersion: 1;
     adopted: {
-        from: AdoptionSource;
+        from: RuleOwner;
         toPrincipal: string;
         atMs: number;
         immutableReport: AdoptionReport;

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

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { readRuleOwner, sameRuleOwner } from "../../../core/rule-owner.js";
 import { atomicWriteFile, ensureDir } from "../fs-atomic.js";
 export class AdoptionError extends Error {
     code;
@@ -26,14 +27,6 @@ export const BASELINE_CONFIG_IDENTITIES = [
     { 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;
@@ -45,7 +38,7 @@ function isRootAdoptionFileShape(v) {
         if (m === null ||
             typeof m !== "object" ||
             typeof m.adoptionId !== "string" ||
-            !isSource(m.from) ||
+            readRuleOwner(m.from) === undefined ||
             typeof m.toPrincipal !== "string" ||
             typeof m.phase !== "number" ||
             ![2, 3, 4, 5].includes(m.phase)) {
@@ -91,9 +84,10 @@ function isRootAdoptionFileShape(v) {
     }
     if ("adopted" in f && !("marker" in f)) {
         const a = f.adopted;
+        const from = readRuleOwner(a?.from);
         if (a === null ||
             typeof a !== "object" ||
-            !isSource(a.from) ||
+            from === undefined ||
             typeof a.toPrincipal !== "string" ||
             typeof a.atMs !== "number" ||
             a.immutableReport === null ||
@@ -101,11 +95,8 @@ function isRootAdoptionFileShape(v) {
             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 reportFrom = readRuleOwner(r.from);
+        const sameFrom = reportFrom !== undefined && sameRuleOwner(reportFrom, from);
         const okCount = (n) => n === undefined || (typeof n === "number" && Number.isSafeInteger(n) && n >= 0);
         const configIds = new Set();
         const configsOk = Array.isArray(r.affectedDeploymentConfigs) &&

package/dist/stores/file/checkpoint-store.d.ts

@@ -42,6 +42,9 @@ export declare class FileCheckpointStore implements CheckpointStore {
     private get cps();
     /** One-shot crash fault (mirrors `InMemoryCheckpointStore.testInjectFault`). */
     private fault;
+    /** The guarded {@link FileCheckpointStoreOptions.onCorruptRead} seat (the ledger's replay and this store's projection share it). */
+    private readonly discloseCorrupt;
+    private readonly ledgerPath;
     constructor(root: string, opts?: FileCheckpointStoreOptions);
     /** Serialize an op behind any in-flight op on the same token (the in-process per-token async mutex). */
     private withLock;

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

@@ -92,16 +92,20 @@ export class FileCheckpointStore {
         return this.ledger.rows;
     }
     fault = null;
+    discloseCorrupt;
+    ledgerPath;
     constructor(root, opts = {}) {
         assertAdoptionBootGate(root, "FileCheckpointStore");
         this.fsyncEnabled = opts.fsync !== false;
         this.compactEvery = opts.compactEvery ?? 1000;
+        this.discloseCorrupt = guardCorruptSink(opts.onCorruptRead);
         const dir = join(root, "checkpoints");
+        this.ledgerPath = join(dir, "checkpoints.jsonl");
         this.ledger = checkpointLedgers.acquire({
             dir,
             tmpDir: join(root, "tmp"),
-            ...(opts.onCorruptRead !== undefined ? { onCorruptRead: guardCorruptSink(opts.onCorruptRead) } : {}),
-            ledgerPath: join(dir, "checkpoints.jsonl"),
+            ...(this.discloseCorrupt !== undefined ? { onCorruptRead: this.discloseCorrupt } : {}),
+            ledgerPath: this.ledgerPath,
             snapshotPath: join(dir, "checkpoints.snapshot.jsonl"),
         });
     }
@@ -218,10 +222,12 @@ export class FileCheckpointStore {
         return n;
     }
     async listByScope(scope) {
+        const sink = this.discloseCorrupt;
+        const disclose = sink === undefined ? undefined : (sentence) => sink({ kind: "file", path: this.ledgerPath, reason: sentence });
         const out = [];
         for (const cp of this.cps.values()) {
             if (cp.scope === scope && cp.status === "pending")
-                out.push(summarizeCheckpoint(cp));
+                out.push(summarizeCheckpoint(cp, disclose));
         }
         return out;
     }