@sema-agent/core 7.48.0 → 7.49.0

package/dist/core/memory-engine/session-incarnation.js

@@ -1,5 +1,8 @@
 import { sessionRecordBindsIncarnation, usableSessionIncarnation } from "./layout.js";
 import { thrownText } from "../thrown-value.js";
+export function sessionIncarnationResolver(sessionId, own, lineage) {
+    return ({ sessionId: asked }) => (asked === sessionId ? own : lineage.get(asked));
+}
 export function createSessionIncarnationSeat(input) {
     const { resolve, onIncident } = input;
     let faultAnnounced = false;
@@ -25,7 +28,7 @@ export function createSessionIncarnationSeat(input) {
         catch (err) {
             if (!faultAnnounced) {
                 faultAnnounced = true;
-                disclose("memory.session_incarnation_unreadable", `the session incarnation resolver threw (${thrownText(err)}) — this run cannot tell one occupant of a session id from the next, so every durable session record binds by id alone (the conservative reading, and the behavior of a deployment that wires no resolver)`);
+                disclose("memory.session_incarnation_unreadable", `the session incarnation read failed (${thrownText(err)}) — this run cannot tell one occupant of a session id from the next, so every durable session record binds by id alone (the conservative reading, and the behavior of a session store that has no incarnation read)`);
             }
             return undefined;
         }
@@ -40,7 +43,7 @@ export function createSessionIncarnationSeat(input) {
                     if (separationAnnounced.has(sessionId))
                         return;
                     separationAnnounced.add(sessionId);
-                    disclose("memory.session_incarnation_mismatch", `a durable record stands for session ${sessionId} but it was minted by a DIFFERENT occupant of that id (recorded incarnation ${JSON.stringify(recorded)}, this run ${JSON.stringify(incarnation)}) — it does not bind this run and the record is kept where it is. Either the id was recycled after its previous session was deleted, or the deployment's incarnation resolver is not stable for the life of one session`);
+                    disclose("memory.session_incarnation_mismatch", `a durable record stands for session ${sessionId} but it was minted by a DIFFERENT occupant of that id (recorded incarnation ${JSON.stringify(recorded)}, this run ${JSON.stringify(incarnation)}) — it does not bind this run and the record is kept where it is. Either the id was recycled after its previous session was deleted, or the session row's incarnation is not stable for the life of one session`);
                 },
             };
         },

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

@@ -372,8 +372,17 @@ export interface MemoryBackend {
      *   crash-idempotent retry reads the optional committed-snapshot face (post-update rev + bound
      *   projection) — all asserted by the suite's two hold-protocol cases;
      * - conflicts are per-patch and non-fatal: the rest of the batch still applies.
+     *
+     * `opts.anchoredRoot` is the physical store root the calling session is mounted on (its handle's
+     * `memoryDir`; absent for a caller with no session). A backend that anchors its own root reads that
+     * anchor inside the transaction's lock, at every act of the batch up to its commit marker, and refuses
+     * the whole batch with `memory.target_outside_store` when the anchor is another root (`detail.recorded`
+     * = the anchor, `detail.now` = `anchoredRoot`): a session mounted before a re-anchor commits nothing
+     * into the re-anchored store. A backend without a directory ignores it.
      */
-    applyPatches(patches: readonly NotePatch[]): Promise<PatchReport>;
+    applyPatches(patches: readonly NotePatch[], opts?: {
+        readonly anchoredRoot?: string;
+    }): Promise<PatchReport>;
     /** design/84 Seam B cursor pair, migrated verbatim onto the entry-id plane (S2 rewires consolidation). */
     getConsolidationCursor(scope: string): Promise<string | undefined>;
     setConsolidationCursor(scope: string, cursor: string): Promise<void>;

package/dist/core/memory.js

@@ -4,6 +4,7 @@ import { termSet } from "./memory-vector.js";
 import { attrEscape } from "./task-notification.js";
 import { sanitizeUntrustedText, ENGINE_AUTHORITY_ENVELOPE_TAGS } from "./untrusted-text.js";
 import { thrownText } from "./thrown-value.js";
+import { CREDENTIAL_VOCABULARY, refuseWriteView } from "./credential-vocabulary.js";
 export function supportsConsolidation(store) {
     return (typeof store.searchScored === "function" &&
         typeof store.update === "function" &&
@@ -38,26 +39,13 @@ export class MemoryProjectionError extends Error {
 function hasPromotableMarker(note) {
     return note.outcomeStats !== undefined;
 }
-const SECRET_PATTERNS = [
-    { label: "aws_access_key_id", re: /\bAKIA[0-9A-Z]{16}\b/ },
-    { label: "github_token", re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b/ },
-    { label: "github_fine_grained_pat", re: /\bgithub_pat_[A-Za-z0-9_]{60,}\b/ },
-    { label: "openai_api_key", re: /\bsk-(?:ant-(?:api03-)?|proj-)?[A-Za-z0-9_]{20,}\b/ },
-    { label: "stripe_secret_key", re: /\b[sr]k_(?:live|test)_[A-Za-z0-9]{24,}\b/ },
-    { label: "slack_token", re: /\bxox[baprs]-(?:[A-Za-z0-9]+-){1,3}[A-Za-z0-9]{16,}\b/ },
-    { label: "google_api_key", re: /\bAIza[0-9A-Za-z_-]{35}\b/ },
-    { label: "huggingface_token", re: /\bhf_(?=[A-Za-z0-9]*[0-9])[A-Za-z0-9]{20,}\b/ },
-    { label: "private_key", re: /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----/ },
-    { label: "jwt", re: /\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{16,}\b/ },
-    { label: "azure_storage_account_key", re: /AccountKey=[A-Za-z0-9+/]{40,}={0,2}/ },
-    { label: "bearer_token", re: /\bAuthorization:\s*Bearer\s+(?=[A-Za-z0-9._~+/-]*[0-9])[A-Za-z0-9._~+/-]{20,}=*/ },
-];
+const REFUSE_WRITE_FORMS = refuseWriteView(CREDENTIAL_VOCABULARY);
 export function detectSecret(text) {
     if (!text)
         return null;
-    for (const p of SECRET_PATTERNS) {
-        if (p.re.test(text))
-            return p.label;
+    for (const form of REFUSE_WRITE_FORMS) {
+        if (form.re.test(text))
+            return form.label;
     }
     return null;
 }

package/dist/core/model-seat.d.ts

@@ -11,7 +11,8 @@ export type ModelRef = string | Model;
 /**
  * Logical model roles, so a deployment declares its models once and every subsystem asks for its
  * role instead of repeating a model name. Resolved against `RunnerDeps.roles` / `TaskSpec.roles`
- * with a fallback chain (e.g. `summarize → default`, `synthesize → team → default`).
+ * with a fallback chain (e.g. `summarize → default`, `classifier → summarize → default`). A key or a
+ * `modelRole` value outside this vocabulary is refused by name (`config.unknown_role`), never ignored.
  * - `default` — the main task model when `TaskSpec.model` is omitted.
  * - `summarize` — between-turn compaction/summarization. Absent = the MAIN task model, which is the
  *   correct default baseline: the summary request FORKS the main conversation's already-paid
@@ -21,8 +22,7 @@ export type ModelRef = string | Model;
  *   tradeoff (quality for price): an independent model cannot share the main prefix, so it pays the
  *   full independent-request serialization every boundary AND summarizes with a weaker model.
  * - `subagent` — delegated sub-runs (`createSubagentTool` without an explicit model).
- * - `team` / `synthesize` — team members / the neutral synthesizer.
- * - `advisor` — the strong "teacher" a cheap student escalates to (`runWithTeacher`).
+ * - `verifier` — the verification gate's verifier leg (falls back to `default`).
  * - `classifier` — the auto-mode permission classifier (a roster-cheap tier; falls back
  *   `summarize → default`, tier default `flash` on tier-expanded catalogs).
  * - `consolidate` — the memory-consolidation distillation driver (design/376). Falls back to
@@ -36,7 +36,7 @@ export type ModelRef = string | Model;
  *   this role wants (note the summarize DEFAULT rationale — prompt-cache forking — does not
  *   apply here: consolidation is an offline independent request with no shared prefix).
  */
-export declare const MODEL_ROLES: readonly ["default", "summarize", "subagent", "team", "synthesize", "advisor", "verifier", "classifier", "consolidate"];
+export declare const MODEL_ROLES: readonly ["default", "summarize", "subagent", "verifier", "classifier", "consolidate"];
 /** The role vocabulary, derived from {@link MODEL_ROLES} — one source; a consumer that needs the members at
  *  runtime (a settings schema, a parity pin, a doctor line) reads the tuple instead of transcribing it. */
 export type ModelRole = (typeof MODEL_ROLES)[number];

package/dist/core/model-seat.js

@@ -1 +1 @@
-export const MODEL_ROLES = Object.freeze(["default", "summarize", "subagent", "team", "synthesize", "advisor", "verifier", "classifier", "consolidate"]);
+export const MODEL_ROLES = Object.freeze(["default", "summarize", "subagent", "verifier", "classifier", "consolidate"]);

package/dist/core/mounted-mcp.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The MCP surface a run mounts, as a delegation tool reads it at spawn: per declared server, the tools of it that are mounted
+ * right now (the wire name and the name the server itself knows the tool by), and the names of the aggregate tools no server
+ * owns (the cross-server resource readers). Read off the run's LIVE roster, so a refresh that added or removed a server's
+ * tools is what a child spawned after it inherits.
+ *
+ * The run fills it on `ToolExecuteContext.mountedMcp`; the delegation tool puts the same universe through the child's lists
+ * and declares the child the servers they leave.
+ */
+import type { McpServerSpec } from "./mcp-server-spec.js";
+import type { ToolContentOrigin } from "./tool-spec.js";
+import type { McpConnectionPool } from "./mcp-connection-pool.js";
+/** The two names a server's `allowTools` carries to let the cross-server resource readers reach its resources (a server whose allowlist omits one is left out of that reader). */
+export declare const MCP_RESOURCE_LIST_ALLOW = "list_resources";
+export declare const MCP_RESOURCE_READ_ALLOW = "read_resource";
+/** One declared MCP server and its mounted tools. */
+export interface MountedMcpServer {
+    readonly server: McpServerSpec;
+    readonly tools: ReadonlyArray<{
+        readonly name: string;
+        readonly remoteName: string;
+    }>;
+}
+/** What a run mounts of MCP: its servers, and the aggregate tool names that belong to none of them. */
+export interface MountedMcp {
+    readonly servers: ReadonlyArray<MountedMcpServer>;
+    readonly aggregate: ReadonlyArray<string>;
+    /** The run tree's connection pool: a child that inherits the mount leases its connections from it. */
+    readonly pool?: McpConnectionPool;
+}
+/** A roster entry as far as this reading goes. */
+interface RosterEntry {
+    readonly name: string;
+    readonly mcpRemoteName?: string;
+}
+/**
+ * Read the run's MCP surface off its roster. `declared` is the run's frozen server declarations; `aggregateNames` the names of the
+ * tools its materialization minted that no server owns. A tool is a server's when its wire name sits under the server's prefix
+ * domain and carries the remote name the mint recorded on it; a tool of a server that failed to connect is simply not mounted,
+ * so that server has no tools here and a child is not declared it.
+ */
+export declare function mountedMcpOf(input: {
+    readonly declared: ReadonlyArray<McpServerSpec> | undefined;
+    readonly roster: ReadonlyArray<RosterEntry>;
+    readonly aggregateNames: ReadonlySet<string>;
+    readonly pool?: McpConnectionPool;
+}): MountedMcp;
+/**
+ * The MCP tools of a mount as pool rows (name and the server's declared content class) — what the memory content-origin face adds to
+ * a delegation tool's pool when its children inherit the mount. The rows are the universe the spawn's lists are read over, so
+ * "can the child reach an MCP tool" has one answer.
+ */
+export declare function mountedMcpPoolRows(mounted: MountedMcp): Array<{
+    name: string;
+    contentOrigin?: ToolContentOrigin;
+}>;
+export {};

package/dist/core/mounted-mcp.js

@@ -0,0 +1,19 @@
+import { mintNamespacePrefix } from "./protocol-naming.js";
+import { MCP_NAMESPACE } from "./protocol-table.js";
+export const MCP_RESOURCE_LIST_ALLOW = "list_resources";
+export const MCP_RESOURCE_READ_ALLOW = "read_resource";
+export function mountedMcpOf(input) {
+    const servers = (input.declared ?? []).map((server) => {
+        const prefix = mintNamespacePrefix(MCP_NAMESPACE, server.name);
+        const tools = input.roster.flatMap((t) => (t.name.startsWith(prefix) && typeof t.mcpRemoteName === "string" ? [{ name: t.name, remoteName: t.mcpRemoteName }] : []));
+        return { server, tools };
+    });
+    const aggregate = input.roster.filter((t) => input.aggregateNames.has(t.name)).map((t) => t.name);
+    return { servers, aggregate, ...(input.pool !== undefined ? { pool: input.pool } : {}) };
+}
+export function mountedMcpPoolRows(mounted) {
+    return [
+        ...mounted.servers.flatMap((m) => m.tools.map((t) => ({ name: t.name, ...(m.server.contentOrigin !== undefined ? { contentOrigin: m.server.contentOrigin } : {}) }))),
+        ...mounted.aggregate.map((name) => ({ name })),
+    ];
+}

package/dist/core/namespaced-rule-name.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Linear-time `*` glob match (design/127 M6: NOT a RegExp — patterns may come from tenant-supplied
+ * Settings layers; the classic two-pointer walk has zero ReDoS surface and the same semantics as CC's
+ * anchored `^…$`+dotAll construction: every non-`*` char is literal, `*` spans anything incl. newlines).
+ */
+export declare function wildcardMatch(pattern: string, value: string): boolean;
+/**
+ * Does a namespaced RULE name cover `toolName`? — the tail branch of CC's rule matcher `VRp`
+ * (:595780), which is UNCONDITIONAL there (its `globMatching` option gates only the whole-name glob
+ * branch, so CC's allow lane — `mVo` :595803, which passes no options — matches MCP segments too).
+ * Three covering forms, matching CC's three disjuncts (`<ns>` = any protocol-table prefix):
+ *   · `<ns>__<peer>`           — every tool of that peer (rule tool segment absent);
+ *   · `<ns>__<peer>__*`        — the same set, spelled with the star CC's own settings validator
+ *                                recommends (`"MCP rules do not support patterns in parentheses …
+ *                                use mcp__srv__*"`);
+ *   · `<ns>__<peer>__get_*`    — a glob over the tool segment.
+ * A LITERAL tool segment is deliberately NOT covered here: it is an exact tool name, and the exact
+ * table already answers it — the same split CC makes with its leading `ruleName === toolName`.
+ *
+ * Rule and target must be in the SAME namespace, and peer segments compare EXACTLY (CC
+ * `s.serverName === a.serverName`). A rule must therefore spell the peer the way the mint does; that
+ * is the same string an operator reads off any mounted tool name, and inventing a fuzzier comparison
+ * here would let one rule reach a peer — or a protocol — it does not name.
+ */
+export declare function namespacedRuleNameCovers(ruleName: string, toolName: string): boolean;
+/** True ⇔ this rule name is a namespaced name whose reach is a SET of tools rather than one exact tool
+ *  — i.e. the shapes {@link namespacedRuleNameCovers} answers and an exact name table cannot. Every
+ *  lane that keys rules by exact tool name needs this to know which entries it must NOT key that way. */
+export declare function isNamespacedCoveringRuleName(name: string): boolean;

package/dist/core/namespaced-rule-name.js

@@ -0,0 +1,52 @@
+import { splitNamespacedName } from "./tool-name-aliases.js";
+export function wildcardMatch(pattern, value) {
+    let p = 0;
+    let v = 0;
+    let star = -1;
+    let mark = 0;
+    while (v < value.length) {
+        if (p < pattern.length && pattern[p] === value[v] && pattern[p] !== "*") {
+            p++;
+            v++;
+        }
+        else if (p < pattern.length && pattern[p] === "*") {
+            star = p++;
+            mark = v;
+        }
+        else if (star >= 0) {
+            p = star + 1;
+            v = ++mark;
+        }
+        else {
+            return false;
+        }
+    }
+    while (p < pattern.length && pattern[p] === "*")
+        p++;
+    return p === pattern.length;
+}
+function parseNamespacedRuleName(name) {
+    const split = splitNamespacedName(name);
+    if (split === undefined || split.peer === "")
+        return undefined;
+    return split.tool !== undefined ? { protocol: split.ns.id, peer: split.peer, tool: split.tool } : { protocol: split.ns.id, peer: split.peer };
+}
+export function namespacedRuleNameCovers(ruleName, toolName) {
+    const rule = parseNamespacedRuleName(ruleName);
+    if (rule === undefined)
+        return false;
+    const target = parseNamespacedRuleName(toolName);
+    if (target === undefined)
+        return false;
+    if (rule.protocol !== target.protocol)
+        return false;
+    if (rule.peer !== target.peer)
+        return false;
+    if (rule.tool === undefined || rule.tool === "*")
+        return true;
+    return target.tool !== undefined && rule.tool.includes("*") && wildcardMatch(rule.tool, target.tool);
+}
+export function isNamespacedCoveringRuleName(name) {
+    const parsed = parseNamespacedRuleName(name);
+    return parsed !== undefined && (parsed.tool === undefined || parsed.tool.includes("*"));
+}

package/dist/core/park-selfcheck.d.ts

@@ -72,7 +72,7 @@ export type ParkProbeFindingCode =
 "put_failed"
 /** `get` threw, or answered `null` for a token the store had just accepted. */
  | "row_not_readable"
-/** The row came back, but a load-bearing field did not survive the round trip (see `detail` for which). */
+/** The row came back, but a load-bearing field did not survive the round-trip (see `detail` for which). */
  | "row_not_faithful"
 /** The row came back with a status other than `pending` — a park nobody can resolve. */
  | "row_not_pending"

package/dist/core/park-selfcheck.js

@@ -1,5 +1,6 @@
 import { boundInputHashOf, canonicalize } from "./canonical-json.js";
-import { MAX_SUPPORTED_CHECKPOINT_VERSION, mintCheckpointId, mintCheckpointToken, resolveCheckpointStore } from "./checkpoint-store.js";
+import { mintCheckpointId, mintCheckpointToken, resolveCheckpointStore, resolveDeclaredFidelity } from "./checkpoint-store.js";
+import { stampCheckpointRequirements } from "./checkpoint-requirements.js";
 import { resolveDeclaredDurability } from "./wiring-manifest.js";
 export const PARK_SELFCHECK_SCOPE_PREFIX = "sema:park-selfcheck:";
 export const PARK_SELFCHECK_STEP_TIMEOUT_MS = 10_000;
@@ -56,8 +57,8 @@ export function durableParkGapFor(deps, spec = {}) {
         sessionDurable: declaresDurable(deps.sessionStore, "sessionStore"),
     });
 }
-function syntheticCheckpoint(scope) {
-    return {
+function syntheticCheckpoint(scope, fidelity) {
+    return stampCheckpointRequirements({
         token: mintCheckpointToken(),
         checkpointId: mintCheckpointId(),
         scope,
@@ -85,7 +86,6 @@ function syntheticCheckpoint(scope) {
         state: { activeTools: ["SelfCheck"], nestedStats: { tokens: 0, turns: 0, tasks: 0, costMicroUsd: 0, anyUnpriced: false } },
         status: "pending",
         createdAt: Date.now(),
-        version: MAX_SUPPORTED_CHECKPOINT_VERSION,
         suspendCount: 1,
         suspendedAt: Date.now(),
         resourceLedger: { spentMicroUsd: 0, spentTokens: 0, spentTurns: 0, sliceCount: 1 },
@@ -94,7 +94,7 @@ function syntheticCheckpoint(scope) {
         principal: `${scope}:principal`,
         durableApproval: { scope, ttlMs: PARK_SELFCHECK_ROW_TTL_MS },
         deadline: Date.now() + PARK_SELFCHECK_ROW_TTL_MS,
-    };
+    }, fidelity);
 }
 function faithfulnessDelta(sent, got) {
     const project = (cp) => ({
@@ -109,6 +109,8 @@ function faithfulnessDelta(sent, got) {
         deadline: cp.deadline,
         createdAt: cp.createdAt,
         version: cp.version,
+        requires: cp.requires,
+        requirementsDigest: cp.requirementsDigest,
         suspendCount: cp.suspendCount,
         suspendedAt: cp.suspendedAt,
         resourceLedger: cp.resourceLedger,
@@ -134,7 +136,15 @@ export async function probeParkRoundTrip(deps, spec = {}) {
         };
     }
     const scope = `${PARK_SELFCHECK_SCOPE_PREFIX}${mintCheckpointToken()}`;
-    const cp = syntheticCheckpoint(scope);
+    let fidelity;
+    try {
+        fidelity = resolveDeclaredFidelity(store, "checkpointStore");
+    }
+    catch {
+        const detail = "the checkpoint backend declares an unrecognized encoding fidelity — a park refuses rather than guess which values survive it";
+        return { verdict: "failed", findings: [{ code: "put_failed", detail }], scope, summary: `the park lane failed its round-trip self-check at "put_failed": ${detail}`, ...gapCell };
+    }
+    const cp = syntheticCheckpoint(scope, fidelity);
     const said = (err) => {
         try {
             const m = err instanceof Error ? err.message : undefined;

package/dist/core/path-guard-rows.d.ts

@@ -0,0 +1,99 @@
+import type { DenyFace, PathRowReach } from "../tools/fs/read-deny.js";
+/** Which reading of a target one view is: the placed spelling, the environment's canonical answer, a hop of the leaf's
+ *  symlink chain, or the home's own spelling of a canonical key (read-deny-home.ts). */
+export type GuardViewKind = "lexical" | "canonical" | "hop" | "home";
+/** ONE view of a target as the judgment reads it. */
+export interface GuardView {
+    /** The view's spelling — absolute, or (for an operand a station could not place) as spelled. */
+    readonly path: string;
+    readonly kind: GuardViewKind;
+    /** The canonical key's minter reports the real filesystem already collapsed any win32 component alias in it. */
+    readonly aliasResolved?: true;
+    /** The view's remainder below an exempt root (`""` = the root itself), computed by the reading's owner. */
+    readonly exemptRemainder?: string;
+}
+/** A target as a judgment reads it: its present views, and `unreadable` — the call names a target this reading cannot
+ *  locate, or where the target really lands (its canonical view, its link chain) could not be determined (the reason).
+ *  `identityExempt`: the reading's OWN canonical key lies inside an exempt root. */
+export interface TargetViews {
+    readonly views: readonly GuardView[];
+    readonly unreadable?: string;
+    readonly identityExempt?: true;
+}
+/** The views' spellings, in order, without repeats — what a reader that only needs the strings reads. */
+export declare function viewSpellings(views: TargetViews): readonly string[];
+/** Views from bare spellings (each read as the kind given, the first as `lexical` when no kind is given). */
+export declare function spelledViews(spellings: readonly string[], kind?: GuardViewKind): TargetViews;
+/** The language a row is written in — a column, not a judgment: every grammar is judged by {@link judgePathRows}. */
+export type PathGuardGrammar = 
+/** A literal name (the write-protection table): the target's last segment, any segment, or a consecutive run. */
+{
+    readonly kind: "literal-name";
+    readonly match: "basename" | "segment" | "segment-run";
+    readonly name: string;
+}
+/** A `/`-separated segment glob (`*` the one metacharacter) matched as a contiguous run (the sensitive list, the read
+ *  deny set's segment rows). */
+ | {
+    readonly kind: "segment-glob";
+    readonly run: string;
+}
+/** A permission rule's path pattern, judged by its own reach (the rule DSL's rows and their twins). */
+ | {
+    readonly kind: "rule";
+    readonly rule: string;
+}
+/** The directories a write may land in, from one SOURCE (the write domains — an ALLOW row): the run's advertised writable
+ *  roots (frozen canonical keys), the deployment's configured structural domains, the person's session-won grants, a
+ *  session rule's `allowDirs` confinement. */
+ | {
+    readonly kind: "domain";
+    readonly dirs: readonly string[];
+    readonly source: "advertised" | "configured" | "accepted" | "session";
+};
+/** Where a row is placed: anywhere its grammar matches; at a home; at the filesystem root; below a declared root. A placed
+ *  row is judged in a ROOTED view only, except that a home row in a view that cannot be placed holds wider. */
+export type PathGuardPlacement = "anywhere" | "home" | "rooted" | {
+    readonly below: string;
+};
+/** How a row folds case: `protective` (the built-in tables: case, the two confusable letters, the invisible format
+ *  characters, across every platform reading), `ascii` (the read deny set's contract), `host` (case-insensitive exactly
+ *  where the host's filesystem is), `exact`. A fold only ever WIDENS what a tightening row matches; no exemption folds. */
+export type PathGuardFold = "protective" | "ascii" | "host" | "exact";
+/** The minimum a row offers the judgment: its reach over one view, and whether the data-root exemption applies to it. */
+export interface GuardRowReach {
+    readonly reach: (view: GuardView) => PathRowReach;
+    readonly exemptible?: boolean;
+}
+/** ONE guarded path. */
+export interface PathGuardRow extends GuardRowReach {
+    /** The row's name wherever a refusal, a card or the classifier cites it (the table name, the glob, the rule text). */
+    readonly name: string;
+    readonly grammar: PathGuardGrammar;
+    readonly polarity: "deny" | "ask" | "allow";
+    readonly faces: readonly DenyFace[];
+    readonly placement: PathGuardPlacement;
+    readonly fold: PathGuardFold;
+    readonly exemptible: boolean;
+    /** The built-in tier that activates the row (absent on a row no tier selects). */
+    readonly tier?: string;
+    /** Where the row came from: a built-in default, a deployment REPLACEMENT of a default table, an ADDITION to one, a rule. */
+    readonly origin: "builtin" | "replacement" | "addition" | "rule";
+}
+/** What {@link judgePathRows} found: the row, the view it met there (its spelling and kind; absent on an unreadable hold),
+ *  and — when nothing was reached and some row could not be judged — the reason of the first such row. */
+export interface PathRowsHit<R> {
+    readonly row: R;
+    readonly view?: string;
+    readonly viewKind?: GuardViewKind;
+    readonly unreadable?: string;
+}
+/**
+ * THE one judgment of guarded rows over a target's views, for every table and every lane: rows outer, views inner — the
+ * first row (in the caller's order) that some view reaches is the answer. `tighten` (deny / ask): any present view reaching
+ * the row reaches it; a row that cannot be judged (or a target that cannot be read) is held and answered only when no row
+ * reaches. `allow`: a row admits the target only when it admits EVERY view (a link out of an allowed directory is not
+ * admitted through its spelling); an unreadable target is admitted by nothing. An exemptible row reads each view through
+ * the exemption law (the module header).
+ */
+export declare function judgePathRows<R extends GuardRowReach>(rows: readonly R[], views: TargetViews, direction: "tighten" | "allow"): PathRowsHit<R> | undefined;

package/dist/core/path-guard-rows.js

@@ -0,0 +1,45 @@
+export function viewSpellings(views) {
+    const out = [];
+    for (const v of views.views)
+        if (!out.includes(v.path))
+            out.push(v.path);
+    return out;
+}
+export function spelledViews(spellings, kind) {
+    return { views: spellings.map((path, i) => ({ path, kind: kind ?? (i === 0 ? "lexical" : "canonical") })) };
+}
+export function judgePathRows(rows, views, direction) {
+    if (direction === "allow") {
+        if (views.unreadable !== undefined || views.views.length === 0)
+            return undefined;
+        for (const row of rows)
+            if (views.views.every((v) => row.reach(v).reach === "reached"))
+                return { row };
+        return undefined;
+    }
+    let held;
+    for (const row of rows) {
+        if (views.unreadable !== undefined)
+            held ??= { row, unreadable: views.unreadable };
+        for (const view of views.views) {
+            const judged = row.exemptible === true ? exemptReading(view, views) : view;
+            if (judged === undefined)
+                continue;
+            const r = row.reach(judged);
+            if (r.reach === "reached")
+                return { row, view: view.path, viewKind: view.kind };
+            if (r.reach === "unreadable")
+                held ??= { row, unreadable: r.reason };
+        }
+    }
+    return held;
+}
+function exemptReading(view, views) {
+    if (views.identityExempt === true && view.kind !== "canonical")
+        return undefined;
+    if (view.exemptRemainder === undefined)
+        return view;
+    if (view.exemptRemainder === "")
+        return undefined;
+    return { path: view.exemptRemainder, kind: view.kind, ...(view.aliasResolved === true ? { aliasResolved: true } : {}) };
+}

package/dist/core/path-identity.d.ts

@@ -1,20 +1,26 @@
 import type { ExecutionEnv } from "../internal/harness-types.js";
 import { type PathFamily } from "../tools/fs/safety.js";
 /**
- * Every spelling the leaf symlink chain of `path` passes through, or `[]`.
- *
- * `[]` has ONE reading for the VERDICT — nothing to judge beyond the spelling and the terminal — reached four
- * ways that are deliberately the same word: no `canonicalChain` declared, a refused namespace spelling, an
- * empty chain, and the environment answering `ok: false`. An unanswerable chain is never a refusal: this
- * reader's callers are path guards whose own absence law says a view that cannot answer does not vote, and a
- * second refusal law over one target would be a second rule. The spelling is anchored as the canonicalizer
- * anchors it (`baseCwd`). A refused namespace spelling and a win-form UNC spelling are not walked (the reference
- * CLI's variant set stops at a network spelling); the share is recognized by the throat's own `isUncSpelling`.
- *
- * `onUnanswerable` separates ONE of those four from the rest for a caller that DISCLOSES its absent views: the
- * environment was ASKED and could not answer (`ok: false`), which is a fact about that environment. The other
- * three are not failures — nothing was asked, or the answer was genuinely "no hops" — so they stay silent. The
- * verdict is `[]` either way; this sink changes nothing about what is judged, only what is said out loud. A
- * throwing sink is the caller's bug and is not caught here.
+ * What the reader learned of a leaf symlink chain: the hops (`ok` — `[]` only when the environment was asked and
+ * answered that there are none), or that no hop could be read (`ok: false`). `asked` separates a fact about the
+ * environment (it was asked and could not answer) from a chain nobody asked about (no `canonicalChain` declared, or a
+ * spelling it does not walk).
  */
-export declare function symlinkChainHops(env: ExecutionEnv, path: string, signal: AbortSignal | undefined, family: PathFamily, baseCwd?: string, onUnanswerable?: (cause: string) => void): Promise<readonly string[]>;
+export type ChainHopsReading = {
+    readonly ok: true;
+    readonly hops: readonly string[];
+} | {
+    readonly ok: false;
+    readonly cause: string;
+    readonly asked: boolean;
+};
+/**
+ * The leaf symlink chain of `path` — the ONE place where a chain read becomes "read" or "not read". The spelling is
+ * anchored as the canonicalizer anchors it (`baseCwd`). A refused namespace spelling and a win-form UNC spelling are
+ * not walked (the reference CLI's variant set stops at a network spelling); the share is recognized by the throat's
+ * own `isUncSpelling`. Each caller holds its own posture on `ok: false`: a path guard (deny side) lets a view that
+ * cannot answer not vote ({@link chainHopsOrNone}), an allow admits nothing it could not see.
+ */
+export declare function symlinkChainHops(env: ExecutionEnv, path: string, signal: AbortSignal | undefined, family: PathFamily, baseCwd?: string): Promise<ChainHopsReading>;
+/** A path guard's reading of a chain: the hops, or none — a view that cannot answer does not vote (its absence law). */
+export declare function chainHopsOrNone(reading: ChainHopsReading): readonly string[];

package/dist/core/path-identity.js

@@ -1,17 +1,17 @@
-import { isAbsoluteForFamily, isUncSpelling, joinForFamily, win32NamespaceScreen } from "../tools/fs/safety.js";
-export async function symlinkChainHops(env, path, signal, family, baseCwd, onUnanswerable) {
+import { anchorSpelling, isUncSpelling, win32NamespaceScreen } from "../tools/fs/safety.js";
+export async function symlinkChainHops(env, path, signal, family, baseCwd) {
     if (typeof env.canonicalChain !== "function")
-        return [];
+        return { ok: false, cause: "the environment declares no symlink-chain reader", asked: false };
     const screened = win32NamespaceScreen(path, family);
     if (!screened.ok)
-        return [];
+        return { ok: false, cause: "a namespace spelling the chain reader does not walk", asked: false };
     const spelled = screened.spelled;
     if (family === "win" && isUncSpelling(spelled))
-        return [];
-    const target = baseCwd !== undefined && baseCwd.length > 0 && !isAbsoluteForFamily(family, spelled) ? joinForFamily(family, baseCwd, spelled) : spelled;
+        return { ok: false, cause: "a network share spelling the chain reader does not walk", asked: false };
+    const target = baseCwd !== undefined && baseCwd.length > 0 ? anchorSpelling(family, baseCwd, spelled) : spelled;
     const chain = await env.canonicalChain(target, signal);
-    if (chain.ok)
-        return chain.value.hops;
-    onUnanswerable?.(chain.error.message);
-    return [];
+    return chain.ok ? { ok: true, hops: chain.value.hops } : { ok: false, cause: chain.error.message, asked: true };
+}
+export function chainHopsOrNone(reading) {
+    return reading.ok ? reading.hops : [];
 }

package/dist/core/path-rule-binding.d.ts

@@ -1,7 +1,8 @@
 import { type PathRuleBase, type PathRuleBases, type PersistedRule, type RuleBehavior, type RuleScope, type ScopeRootIdentity } from "./permission-rule-model.js";
 import { type DenyFace, type JudgedPathRow, type PathRowReach } from "../tools/fs/read-deny.js";
 import { type ToolPolicy } from "./tool-policy.js";
-export { pathRowsReach, rowsWhereTheyLead, type PathRowsHit, type TargetViews } from "../tools/fs/read-deny.js";
+export { judgeRuleRows, rowsWhereTheyLead } from "../tools/fs/read-deny.js";
+export type { PathRowsHit, TargetViews } from "./path-guard-rows.js";
 /** One path rule as a binding reads it: the parsed rule, its text, and — for a deny rule that guards a face of the
  *  engine's deny tables — those faces (absent: the rule is judged on its own tool's calls only). */
 export interface PathRuleSpec {

package/dist/core/path-rule-binding.js

@@ -4,7 +4,8 @@ import { pathFamilyOf, spellingOfIdentity } from "../tools/fs/safety.js";
 import { absoluteTargetIdentityOf } from "./effective-path-target.js";
 import { locationLeadsTo, ruleHeadParts } from "../tools/fs/read-deny.js";
 import { carriedMembersOf } from "./tool-policy.js";
-export { pathRowsReach, rowsWhereTheyLead } from "../tools/fs/read-deny.js";
+import { assertNoRetiredToolPolicyKeys } from "./retired-keys.js";
+export { judgeRuleRows, rowsWhereTheyLead } from "../tools/fs/read-deny.js";
 const NOT_REACHED = { reach: "not_reached" };
 export function bindPathRules(specs, anchors) {
     return specs.map((spec) => {
@@ -71,6 +72,7 @@ const INSTALLATIONS = new WeakMap();
 export function installPolicyAnchors(policy, anchors) {
     if (policy === undefined)
         return undefined;
+    assertNoRetiredToolPolicyKeys(policy);
     const from = INSTALLED.get(policy)?.from ?? policy;
     const rules = from.pathRules;
     if (rules === undefined)