@sema-agent/core 7.34.0 → 7.35.0

package/dist/core/sensitive-path-policy.js

@@ -5,6 +5,7 @@ import { compileSegmentPattern, matchSegmentPatterns, READ_FACE_BUILTIN_DENY_TAB
 import { isProtectedWrite, protectivePathTargetOf } from "./tool-registry.js";
 import { pathTargetBaseOf } from "./effective-path-target.js";
 import { symlinkChainHops } from "./path-identity.js";
+import { toolNameSetHas } from "./tool-roster.js";
 export function agentConfigDenyPatterns() {
     return READ_FACE_BUILTIN_DENY_TABLE.filter((row) => row.tier === "agent-config").map((row) => readDenyPatternRun(row.pattern).run);
 }
@@ -146,7 +147,7 @@ export function createSensitivePathPolicy(opts) {
         async check(req, signal) {
             if (compiled.length === 0)
                 return { action: "allow" };
-            if (guardedByName !== undefined ? !guardedByName.has(req.toolName) : !isProtectedWrite(req))
+            if (guardedByName !== undefined ? !toolNameSetHas(guardedByName, req) : !isProtectedWrite(req))
                 return { action: "allow" };
             const protective = protectivePathTargetOf(req);
             const path = writeTargetPath(req, protective);

package/dist/core/store-contracts/checkpoint-store-contract.js

@@ -301,7 +301,7 @@ export async function checkpointStoreContract(make, runAssertion) {
         const stored = (await store.get(bitless.token)).pendingAction;
         assert.equal("hasBidiControls" in stored, false, "projection backfill must not write back to the row");
     });
-    run("design/388 B18 × B6 identity + face group: a row's seven optional members (capabilityId/contractId/shapeDigest/implementationRevision/rosterDigest + family/pathTarget) survive the round-trip verbatim; an absent group stays absent", async () => {
+    run("design/388 B18 × B6 identity + face group: a row's eight optional members (capabilityId/contractId/shapeDigest/implementationRevision/rosterDigest + family/pathTarget/names) survive the round-trip verbatim; an absent group stays absent", async () => {
         const store = make();
         const carried = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "id-carried" });
         const group = {
@@ -312,6 +312,7 @@ export async function checkpointStoreContract(make, runAssertion) {
             rosterDigest: "sha256:fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
             family: "file-write",
             pathTarget: { param: "destination", aliases: ["path"], access: "create", skillScopeEligible: true },
+            names: ["AcmeWrite", "acme_write"],
         };
         Object.assign(carried.pendingAction, group);
         const bare = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "id-bare" });

package/dist/core/tool-policy.d.ts

@@ -1,9 +1,14 @@
-import { type AskOrigin } from "./ask-origin.js";
+import { type AskOrigin, type AssertAllKeysHandled } from "./ask-origin.js";
 import { type ReadRootGrantScreen } from "./read-root-grant-screen.js";
 import { type Settlement } from "./gate-outcome.js";
 /** A tool call presented to a policy before it executes. */
 /** design/388 B6 — the per-call face (see {@link ToolCallRequest.face}). */
 export interface ToolCallFace {
+    /** Every name a tool-name rule may spell this tool by: the tool's wire name first, then each alias that resolves to
+     *  it on the leg's roster (`rosterToolName`). A rule reaches the call iff its tool name is on this list — read it
+     *  through {@link ruleNamesOf}, never off `toolName` alone. Absent on a face rebuilt from a park row that predates it
+     *  (the call's own name is then the list). */
+    names?: readonly string[];
     family: import("./tool-face.js").ToolFamily;
     pathTarget?: import("./tool-face.js").ToolRosterPathTarget;
     capabilityId: string;
@@ -12,6 +17,8 @@ export interface ToolCallFace {
     implementationRevision: string;
 }
 export interface ToolCallRequest {
+    /** The tool's wire name — the Runner's gate resolves a call made under an alias to the wire name of the tool it
+     *  dispatches to before any policy runs (`rosterToolName`); the names a rule may use for it are {@link ruleNamesOf}. */
     toolName: string;
     args: unknown;
     toolCallId: string;
@@ -520,7 +527,28 @@ export interface ToolPolicy {
      *  reaches a person — it is not refused. A PURE judgment: no side effect, no audit record, no hook, no approver; `true`
      *  on a target it cannot judge. Carried through {@link combinePolicies} (any member's `true` is the answer). */
     readonly writeTargetGuard?: (target: string, signal?: AbortSignal) => Promise<boolean>;
+    /** The raw tool-name lists a name-keyed policy was built from — the prepare-time policy-name audit's feed (a retired
+     *  name refuses the run, an unmounted one is advised). Carried through {@link combinePolicies} (the union of the
+     *  members' groups); read with {@link toolPolicyNameSets}. */
+    readonly nameSets?: readonly ToolPolicyNameSets[];
 }
+/**
+ * The members a policy carries beside `check` — one table for every seat that carries them: {@link wrapToolPolicy} reads
+ * each by name off the wrapped policy, {@link combinePolicies} folds each. The fence makes a new {@link ToolPolicy} member
+ * a compile error until the table names it.
+ */
+declare const TOOL_POLICY_CARRIED_MEMBERS: readonly ["projection", "pathDenyRules", "writeTargetGuard", "nameSets"];
+type ToolPolicyCarriedMember = (typeof TOOL_POLICY_CARRIED_MEMBERS)[number];
+export type ToolPolicyCarriesEveryMember = AssertAllKeysHandled<Exclude<Exclude<keyof ToolPolicy, "check">, ToolPolicyCarriedMember>>;
+/**
+ * The ONE way to wrap a policy: the wrapper decides through `check`; every member {@link ToolPolicy} declares beside it
+ * (projection, name sets, path deny rows, write-target guard — the carried-member table) rides as `inner` holds it, read
+ * by name, so a class instance's accessor or a non-enumerable member rides too — a `{ check }` literal drops them, and
+ * engine stations the wrapper never sees read each one. The carried members describe what `inner` refuses, so the wrapper
+ * must refuse at least that (an observer, a tightener); one that releases what `inner` refuses is a policy of its own.
+ * The ask-class brand is not carried: it attests the replaced `check`.
+ */
+export declare function wrapToolPolicy<P extends ToolPolicy>(inner: P, check: ToolPolicy["check"]): Pick<P, ToolPolicyCarriedMember> & ToolPolicy;
 /** Every path deny row the given policies carry (combined policies included), in order — the deny tables' rule rows. */
 export declare function toolPolicyPathDenyRules(policies: readonly (ToolPolicy | undefined)[]): readonly import("../tools/fs/read-deny.js").PathRuleDenyRow[];
 /** The one write-target guard the given policies carry together (combined policies included): `true` when any member
@@ -604,10 +632,7 @@ export declare function namespacedCoveringHit(covering: readonly string[], toolN
  * trusting a re-supplied policy's execution half for the frozen deny data: the projection persisted
  * at suspend is the authority for what the chain refused, whatever a re-supplied closure claims.
  */
-export declare function checkToolPolicyProjection(projection: Pick<ToolPolicyProjection, "components">, req: {
-    toolName: string;
-    args: unknown;
-}): Extract<PermissionResult, {
+export declare function checkToolPolicyProjection(projection: Pick<ToolPolicyProjection, "components">, req: Pick<ToolCallRequest, "toolName" | "args" | "face">): Extract<PermissionResult, {
     action: "deny";
 }> | undefined;
 /**
@@ -781,7 +806,7 @@ export interface ToolPolicyNameSets {
      *  here silently WIDENS (the tool runs without ever asking), so it is audited too. */
     readonly ask?: readonly string[];
 }
-/** A policy that exposes its name lists for the host-side pool audit. Composition-transparent:
+/** A policy that states its name lists ({@link ToolPolicy.nameSets} set). Composition-transparent:
  *  {@link combinePolicies} (and therefore {@link tightenTaskSpec}) unions children's groups onto the
  *  combined policy, so metadata survives the deployment's tighten/compose path. */
 export type NamedToolPolicy = ToolPolicy & {

package/dist/core/tool-policy.js

@@ -8,6 +8,7 @@ import { sanitizeAutoModeArmingRecipe } from "./auto-mode-arming.js";
 import { join, normalize as normalizePath, sep } from "node:path";
 import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
 import { protectivePathTargetOf } from "./tool-registry.js";
+import { ruleNamesOf, toolNameSetHas } from "./tool-roster.js";
 import { boundInputHashOf } from "./canonical-json.js";
 import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY } from "./untrusted-text.js";
 import { describeRejectedValue } from "./tool-search-setting.js";
@@ -122,6 +123,21 @@ export const ASK_EVIDENCE_ABSENCE_VALUES = ["not_wired", "not_adjudicated", "una
 export function decisionText(d) {
     return d.message;
 }
+const TOOL_POLICY_CARRIED_MEMBERS = ["projection", "pathDenyRules", "writeTargetGuard", "nameSets"];
+function carriedMembersOf(p) {
+    const out = {};
+    const carry = (k) => {
+        const v = p[k];
+        if (v !== undefined)
+            out[k] = v;
+    };
+    for (const k of TOOL_POLICY_CARRIED_MEMBERS)
+        carry(k);
+    return out;
+}
+export function wrapToolPolicy(inner, check) {
+    return { ...carriedMembersOf(inner), check };
+}
 export function toolPolicyPathDenyRules(policies) {
     return policies.flatMap((p) => (Array.isArray(p?.pathDenyRules) ? p.pathDenyRules : []));
 }
@@ -149,20 +165,21 @@ export function namespacedCoveringHit(covering, toolName) {
     return covering.length > 0 && covering.some((e) => namespacedRuleNameCovers(e, toolName));
 }
 export function checkToolPolicyProjection(projection, req) {
+    const names = ruleNamesOf(req);
     for (const c of projection.components) {
         if (c.kind === "tool_deny") {
-            if (c.names.includes(req.toolName) || namespacedCoveringHit(namespacedCoveringEntries(c.names), req.toolName)) {
+            if (names.some((n) => c.names.includes(n)) || namespacedCoveringHit(namespacedCoveringEntries(c.names), req.toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" is denied by a frozen inherited policy projection` };
             }
             continue;
         }
         if (c.kind === "tool_allowlist") {
-            if (!c.names.includes(req.toolName) && !namespacedCoveringHit(namespacedCoveringEntries(c.names), req.toolName)) {
+            if (!names.some((n) => c.names.includes(n)) && !namespacedCoveringHit(namespacedCoveringEntries(c.names), req.toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" is not in a frozen inherited policy projection's allowlist` };
             }
             continue;
         }
-        if (!c.tools.includes(req.toolName))
+        if (!names.some((n) => c.tools.includes(n)))
             continue;
         const command = req.args?.command;
         if (typeof command !== "string") {
@@ -371,10 +388,10 @@ export function createAllowDenyPolicy(opts) {
         nameSets: [{ ...(opts.allow ? { allow: [...opts.allow] } : {}), ...(opts.deny ? { deny: [...opts.deny] } : {}) }],
         check(req) {
             const toolName = req.toolName;
-            if (deny.has(toolName) || namespacedCoveringHit(denyCovering, toolName)) {
+            if (toolNameSetHas(deny, req) || namespacedCoveringHit(denyCovering, toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" is denied by policy` };
             }
-            if (allow && !allow.has(toolName) && !namespacedCoveringHit(allowCovering, toolName)) {
+            if (allow && !toolNameSetHas(allow, req) && !namespacedCoveringHit(allowCovering, toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" is not in the allowlist` };
             }
             return ALLOW;
@@ -411,10 +428,10 @@ export function createApprovalPolicy(opts) {
         ],
         async check(req, signal) {
             const toolName = req.toolName;
-            if (deny.has(toolName) || namespacedCoveringHit(denyCovering, toolName)) {
+            if (toolNameSetHas(deny, req) || namespacedCoveringHit(denyCovering, toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" is denied by policy` };
             }
-            if (need.has(toolName) || namespacedCoveringHit(needCovering, toolName)) {
+            if (toolNameSetHas(need, req) || namespacedCoveringHit(needCovering, toolName)) {
                 const attest = (d, settlement) => attestEngineSettlement(d, { settlement, origin: "policy" }, req);
                 if (signal?.aborted) {
                     return attest({ action: "deny", message: `approval aborted for "${req.toolName}" (run or turn interrupted)` }, settledByNobody("task_aborted"));
@@ -464,7 +481,7 @@ export function createApprovalPolicy(opts) {
                 }
                 return attest({ action: "deny", message: `approval denied for "${req.toolName}"` }, settledByPerson("human_refused", undefined));
             }
-            if (opts.denyByDefault && !auto.has(toolName) && !namespacedCoveringHit(autoCovering, toolName)) {
+            if (opts.denyByDefault && !toolNameSetHas(auto, req) && !namespacedCoveringHit(autoCovering, toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" requires explicit allow` };
             }
             return ALLOW;
@@ -492,11 +509,14 @@ export function combinePolicies(...policies) {
     const combinedProjection = childProjections.some((p) => p !== undefined)
         ? { components: projectedComponents, requiresLiveRemainder: combinedRemainder }
         : undefined;
+    const folded = {
+        projection: combinedProjection,
+        nameSets: nameSets.length > 0 ? nameSets : undefined,
+        pathDenyRules: pathDenyRules.length > 0 ? pathDenyRules : undefined,
+        writeTargetGuard,
+    };
     return {
-        ...(combinedProjection !== undefined ? { projection: combinedProjection } : {}),
-        ...(nameSets.length > 0 ? { nameSets } : {}),
-        ...(pathDenyRules.length > 0 ? { pathDenyRules } : {}),
-        ...(writeTargetGuard !== undefined ? { writeTargetGuard } : {}),
+        ...carriedMembersOf(folded),
         async check(req, signal) {
             let asked;
             let current = req;
@@ -601,7 +621,7 @@ export function createCoarseCommandNamePolicy(opts) {
     return brandPolicyAskClass({
         projection,
         check(req) {
-            if (!shellTools.has(req.toolName))
+            if (!toolNameSetHas(shellTools, req))
                 return ALLOW;
             const command = req.args?.command;
             if (typeof command !== "string") {
@@ -855,7 +875,7 @@ export function createUnverifiableDeletePolicy(opts) {
     const shellTools = canonicalToolNameSet(opts?.tools);
     return brandPolicyAskClass({
         check(req) {
-            if (!shellTools.has(req.toolName))
+            if (!toolNameSetHas(shellTools, req))
                 return ALLOW;
             const command = req.args?.command;
             if (typeof command !== "string")
@@ -952,8 +972,7 @@ export function createTranscriptIntegrityPolicy(opts) {
     });
     return brandPolicyAskClass({
         check(req) {
-            const toolName = req.toolName;
-            if (shellTools.has(toolName)) {
+            if (toolNameSetHas(shellTools, req)) {
                 const command = req.args?.command;
                 if (typeof command !== "string")
                     return ALLOW;

package/dist/core/tool-registry.d.ts

@@ -48,9 +48,40 @@ export interface ToolCallLike {
     args: unknown;
     face?: {
         pathTarget?: ToolCallPathTarget;
+        names?: readonly string[];
     } | undefined;
 }
 type CallPathTarget = ToolCallPathTarget;
+/**
+ * The names a tool-name rule may spell this call's tool by — the face's `names` when they include the call's name,
+ * else the call's name alone (a bare request, or a face minted for another name). Every name-keyed matcher and the
+ * protective path floor read a rule's tool name against THIS list, which is the roster's one canonicalization seen
+ * from the call's side: a rule written against an alias and one written against the wire name reach the same calls.
+ */
+export declare function ruleNamesOf(req: Pick<ToolCallLike, "toolName" | "face">): readonly string[];
+/** Does the call answer to `name` — is it one of the call's names ({@link ruleNamesOf})? The engine's TIGHTENS keyed on
+ *  one of its own tool names read this, so a tool that wears the name under any of its names is tightened (the
+ *  fail-safe direction); a grant or a routing keyed on an engine tool name reads the wire name. */
+export declare function callAnswersTo(req: Pick<ToolCallLike, "toolName" | "face">, name: string): boolean;
+/** Does a set of rule tool names name this call's tool ({@link ruleNamesOf})? */
+export declare function toolNameSetHas(set: {
+    has(name: string): boolean;
+}, req: Pick<ToolCallLike, "toolName" | "face">): boolean;
+/** Does `set` hold any of the call's names ({@link ruleNamesOf})? The read of a MEMBERSHIP tighten keyed on the engine's
+ *  own tool names (the egress set, a read station's tools, the compliance veto): a tool is held under every name it
+ *  answers to. A grant or a routing keyed on an engine tool name reads the wire name instead. */
+export declare function anyNamed(set: {
+    has(name: string): boolean;
+}, names: readonly string[]): boolean;
+/** The first of the call's names ({@link ruleNamesOf}, the spelling first) that `map` holds an entry for, with the entry.
+ *  The read of a SEAT keyed on the engine's own tool names (a tier, a mark's sources): every key of one seat is read under
+ *  the ONE name this returns — a seat is never assembled from two names' entries. */
+export declare function firstNamed<V>(map: {
+    get(name: string): V | undefined;
+}, names: readonly string[]): {
+    readonly name: string;
+    readonly value: V;
+} | undefined;
 /**
  * design/388 B6/B17 — the path target a PROTECTIVE fence reads (a deny-list judging a write's target: sensitive paths,
  * frozen paths, write protection, the transcript gate; edit tracking): the object face's own declaration first, the
@@ -58,6 +89,11 @@ type CallPathTarget = ToolCallPathTarget;
  * face that declares none. Reading the catalog for an undeclared same-name tool can only TIGHTEN a deny-list (it adds
  * a slot to judge — the pre-388 posture, never wider), which is exactly why this floor is wrong for a grant.
  *
+ * The floor reads EVERY name the call answers to (`ruleNamesOf`: the face's `names`, else the call's name alone) in
+ * the face's order — the name the call was made under first, then the wire name, then the other aliases — and the
+ * first name the catalog declares a target for wins: a call made under a catalog name and resolved to a tool that
+ * declares none keeps THAT name's slot, also when the tool answers to a second catalog name with another slot.
+ *
  * #635: "can only tighten" is true of the SLOT and false of the RESOLUTION, so the floor hands over the first and
  * defaults the second (`pathTargetSlotOnly`). Telling a fence that a FOREIGN tool of the same name resolves its slot
  * against the project root is a claim about someone else's implementation: get it wrong and the judged path moves to

package/dist/core/tool-registry.js

@@ -51,10 +51,31 @@ export function pathTargetValue(args, pt) {
     }
     return undefined;
 }
+export function ruleNamesOf(req) {
+    const names = req.face?.names;
+    return names !== undefined && names.includes(req.toolName) ? names : [req.toolName];
+}
+export function callAnswersTo(req, name) {
+    return ruleNamesOf(req).includes(name);
+}
+export function toolNameSetHas(set, req) {
+    return anyNamed(set, ruleNamesOf(req));
+}
+export function anyNamed(set, names) {
+    return names.some((n) => set.has(n));
+}
+export function firstNamed(map, names) {
+    for (const name of names) {
+        const value = map.get(name);
+        if (value !== undefined)
+            return { name, value };
+    }
+    return undefined;
+}
 export function protectivePathTargetOf(call) {
     if (call.face?.pathTarget !== undefined)
         return call.face.pathTarget;
-    const floor = pathTargetOf(call.toolName);
+    const floor = ruleNamesOf(call).map((n) => pathTargetOf(n)).find((pt) => pt !== undefined);
     return floor === undefined || call.face === undefined ? floor : pathTargetSlotOnly(floor);
 }
 export const BARE_REQUEST_CODE = "policy.bare_request";

package/dist/core/tool-roster.d.ts

@@ -249,7 +249,19 @@ export type ToolRosterDelta = Static<typeof ToolRosterDelta>;
 /** The ONE name→row resolution every per-call reader shares (the call face, the park identity): the wire name first,
  *  then an alias — the same order the dispatcher resolves a model's call. */
 export declare function rosterEntryNamed(roster: ToolRoster, toolName: string): ToolRosterEntry | undefined;
-/** design/388 B6 — the per-call face a gated request carries, read off a roster snapshot by name (aliases resolve). */
+/**
+ * The ONE tool-name canonicalization: the wire name of the row `name` resolves to on the roster ({@link rosterEntryNamed}
+ * — the wire name first, then an alias, the dispatcher's order), or `name` itself when no row answers to it. The gate
+ * reads a call's name through it before any policy runs, and a rule's tool name reaches a call exactly when it
+ * canonicalizes to the same wire name (`ToolCallFace.names` is that set, minted here) — so a rule written against
+ * an alias and one written against the wire name are one rule.
+ */
+export declare function rosterToolName(roster: ToolRoster | undefined, name: string): string;
+export { anyNamed, callAnswersTo, firstNamed, ruleNamesOf, toolNameSetHas } from "./tool-registry.js";
+/** design/388 B6 — the per-call face a gated request carries, read off a roster snapshot by name (aliases resolve).
+ *  `names` leads with the name the face was minted under (the model's spelling at the gate), then the wire name and the
+ *  other aliases: a reader that must pick ONE of the call's names (the protective path floor) picks the spelling first,
+ *  as the same call was judged before name resolution. */
 export declare function toolCallFaceOf(roster: ToolRoster | undefined, toolName: string): import("./tool-policy.js").ToolCallFace | undefined;
 /** design/388 B18 — the identity members a park row carries, read off a roster snapshot by name; an empty object when
  *  the name is not on the snapshot (the row then reads pre-identity and the resume takes the name-only path). */
@@ -268,6 +280,7 @@ export declare function parkedToolIdentity(roster: ToolRoster | undefined, toolN
 export declare function parkedToolFace(roster: ToolRoster | undefined, toolName: string): {
     family?: ToolFamily;
     pathTarget?: ToolRosterEntry["pathTarget"];
+    names?: readonly string[];
 };
 /** The call face a park row carries — present iff the row was minted with BOTH its face members and its four
  *  identity members (one mint writes all of them; a row missing any is pre-388 and yields undefined, never a
@@ -275,6 +288,7 @@ export declare function parkedToolFace(roster: ToolRoster | undefined, toolName:
 export declare function parkedCallFaceOf(pending: {
     family?: ToolFamily;
     pathTarget?: ToolRosterPathTarget;
+    names?: readonly string[];
     capabilityId?: string;
     contractId?: string;
     shapeDigest?: string;
@@ -321,7 +335,8 @@ export interface RosterBoundMembers {
     cardId?: string;
 }
 /** The typed refusal a member over its bound mints — the door's two codes, and the mint's own for the members no
- *  declaration door names (`modelGate`, the derived `cardId`). */
+ *  declaration door names (`modelGate`, the derived `cardId`). Spelled out as literals (a consumer's tooling reads
+ *  the words); each is a member of {@link ToolDeclarationCode}, which every mint below satisfies. */
 export type RosterBoundCode = "config.tool_name_too_long" | "config.tool_contract_too_long" | "config.tool_roster_bound";
 /**
  * design/388 B20 / #626 ① — the ONE bound judge over a row's identity members: a problem `{ code, message }`, or

package/dist/core/tool-roster.js

@@ -74,13 +74,22 @@ export const ToolRosterDelta = Type.Object({
 export function rosterEntryNamed(roster, toolName) {
     return roster.entries.find((r) => r.name === toolName) ?? roster.entries.find((r) => r.aliases.includes(toolName));
 }
+export function rosterToolName(roster, name) {
+    return (roster === undefined ? undefined : rosterEntryNamed(roster, name)?.name) ?? name;
+}
+function namesResolvingTo(roster, e) {
+    return [e.name, ...e.aliases.filter((a) => a !== e.name && rosterToolName(roster, a) === e.name)];
+}
+export { anyNamed, callAnswersTo, firstNamed, ruleNamesOf, toolNameSetHas } from "./tool-registry.js";
 export function toolCallFaceOf(roster, toolName) {
     if (roster === undefined)
         return undefined;
     const e = rosterEntryNamed(roster, toolName);
     if (e === undefined)
         return undefined;
+    const resolving = namesResolvingTo(roster, e);
     return {
+        names: resolving.includes(toolName) ? [toolName, ...resolving.filter((n) => n !== toolName)] : resolving,
         family: e.family,
         ...(e.pathTarget !== undefined ? { pathTarget: e.pathTarget } : {}),
         capabilityId: e.capabilityId,
@@ -103,12 +112,13 @@ export function parkedToolFace(roster, toolName) {
     const e = rosterEntryNamed(roster, toolName);
     if (e === undefined)
         return {};
-    return { family: e.family, ...(e.pathTarget !== undefined ? { pathTarget: e.pathTarget } : {}) };
+    return { family: e.family, ...(e.pathTarget !== undefined ? { pathTarget: e.pathTarget } : {}), names: namesResolvingTo(roster, e) };
 }
 export function parkedCallFaceOf(pending) {
     if (pending.family === undefined || pending.capabilityId === undefined || pending.contractId === undefined || pending.shapeDigest === undefined || pending.implementationRevision === undefined)
         return undefined;
     return {
+        ...(pending.names !== undefined ? { names: pending.names } : {}),
         family: pending.family,
         ...(pending.pathTarget !== undefined ? { pathTarget: pending.pathTarget } : {}),
         capabilityId: pending.capabilityId,

package/dist/core/trace.d.ts

@@ -857,6 +857,17 @@ export type TraceEvent = {
     /** Image blocks replaced in THIS request. */
     count: number;
     ts: number;
+} | {
+    /** A provider echo field was refused by {@link import("../brain/errors.js").PROVIDER_ECHO_SHAPE} (visible ASCII,
+     *  1–128 characters) and dropped: the response's `request-id` / `x-request-id` header values (`field:
+     *  "requestId"`, read at connect — the id a failure would carry as `apiFailure.requestId`), or the model name
+     *  its frames report (`field: "responseModel"`). One frame per provider response per field; the value itself
+     *  is never carried (metadata-only). A count of these frames is this engine's drop count. */
+    kind: "brain.echo_dropped";
+    version: 1;
+    taskId: string;
+    field: "requestId" | "responseModel";
+    ts: number;
 } | {
     /** C10 — a `preemptSignal` fired on a task that is NOT resource-suspend-eligible: the preempt is a
      *  documented silent no-op, but the SCHEDULER that raised it needs to know it was ignored. */

package/dist/engine/execution-env/node-execution-env.d.ts

@@ -117,7 +117,9 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
         shellEnv?: NodeJS.ProcessEnv;
         /** VENDORED EDIT (D1, security): how much of `process.env` the shell child inherits. Default `"scrub"` =
          *  fail-closed (drop secret-pattern keys, keep PATH/build/locale). `"all"` = full inherit (trusted env);
-         *  `string[]` = strict allowlist. `shellEnv`/per-exec `env` always pass through. */
+         *  `string[]` = strict allowlist. `shellEnv`/per-exec `env` always pass through. Any other value — an unknown
+         *  word, a non-string, a list entry that is not a variable name — throws here (`inheritEnvPolicyProblem`'s
+         *  reason), the same judgment the oracle gate's `inheritEnv` meets. */
         inheritEnv?: "all" | "scrub" | string[];
         /** design/105: inject a resident scheduler daemon backend (the shell daemon). Absent ⇒ scheduling INERT. */
         scheduler?: SchedulerCapability;

package/dist/engine/execution-env/node-execution-env.js

@@ -7,7 +7,7 @@ import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { createInterface } from "node:readline";
 import { ExecutionError, err, FileError, ok, toError, } from "../harness/types.js";
 import { killProcessTree, shutdownDebug } from "./kill-tree.js";
-import { __resetSecretEnvScrubNoticeAnnouncement, announceSecretEnvScrub, inheritedHostEnv, scrubSecretEnv } from "../../core/secret-env.js";
+import { __resetSecretEnvScrubNoticeAnnouncement, announceSecretEnvScrub, inheritEnvPolicyProblem, inheritedHostEnv, scrubSecretEnv } from "../../core/secret-env.js";
 import { physicalPathOfAsync } from "../../core/physical-path.js";
 import { isUncSpelling } from "../../tools/fs/safety.js";
 import { RollingTailBuffer, markTruncated, newStreamCursorState, sliceStreamIncrement, } from "../../core/exec-output-tail.js";
@@ -294,7 +294,10 @@ export class NodeExecutionEnv {
         this.cwd = options.cwd;
         this.shellPath = options.shellPath;
         this.shellEnv = options.shellEnv;
-        this.inheritEnv = options.inheritEnv ?? "scrub";
+        const inheritEnvProblem = inheritEnvPolicyProblem(options.inheritEnv);
+        if (inheritEnvProblem !== undefined)
+            throw new Error(`NodeExecutionEnv: ${inheritEnvProblem}`);
+        this.inheritEnv = Array.isArray(options.inheritEnv) ? [...options.inheritEnv] : (options.inheritEnv ?? "scrub");
         this.scheduler = options.scheduler;
         this.retainBackgroundProcesses = options.retainBackgroundProcesses ?? false;
         this.onSecretEnvScrub = options.onSecretEnvScrub;

package/dist/engine/harness/agent-harness.js

@@ -3,6 +3,7 @@ import { runAgentLoop } from "../loop/agent-loop.js";
 import { resolveAgentCoreStreamFn } from "../loop/runtime-deps.js";
 import { normalizeEngineSegments } from "../../core/untrusted-text.js";
 import { AUTH_CARRIER_NAMES } from "../../brain/request-params.js";
+import { isProviderEchoShape } from "../../brain/errors.js";
 import { convertToLlm } from "./messages.js";
 import { thrownText } from "../../core/thrown-value.js";
 import { AgentHarnessError, CompactionError, SessionError, SYNTHETIC_MESSAGE_MODEL, toError, } from "./types.js";
@@ -783,7 +784,7 @@ export class AgentHarness {
             model: SYNTHETIC_MESSAGE_MODEL,
             isApiErrorMessage: true,
             ...(failure.apiErrorStatus !== undefined ? { apiErrorStatus: failure.apiErrorStatus } : {}),
-            ...(failure.requestId !== undefined ? { requestId: failure.requestId } : {}),
+            ...(typeof failure.requestId === "string" && isProviderEchoShape(failure.requestId) ? { requestId: failure.requestId } : {}),
             usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
             usageMissing: true,
             stopReason: "error",

package/dist/engine/lsp/node-lsp-manager.js

@@ -336,7 +336,7 @@ const lspSpawnWithEnv = (env, onNotice) => (command, args, cwd, signal) => new P
         let scrubbedEnv = env;
         if (scrubbedEnv == null) {
             const findings = [];
-            scrubbedEnv = scrubSecretEnv(process.env, findings, process.platform);
+            scrubbedEnv = scrubSecretEnv(process.env, findings);
             announceSecretEnvScrub(onNotice, findings);
         }
         child = spawn(command, args, { ...lspSpawnOptions(cwd), env: scrubbedEnv });

package/dist/index.d.ts

@@ -42,7 +42,7 @@ export { StdioLspTransport, type LspChildProcess } from "./engine/lsp/stdio-lsp-
 export { encodeFrame, createFrameDecoder } from "./engine/lsp/frame-decoder.js";
 export { resolveModel, resolveTaskModel, parseModelMention, expandTiers, DEFAULT_TIER_ORDER, CC_MODEL_TIER_ALIASES, ROLE_TIER_DEFAULTS, MODEL_ROLES, type ModelRole, type RoleSpec, type ModelRoles, type ResolvedRole, type ModelMention, } from "./core/roles.js";
 export { selectModel, selectModelOrThrow, type ModelCriteria, type ModelTier } from "./core/select-model.js";
-export { BrainError, classifyHttp, type BrainErrorCode } from "./brain/errors.js";
+export { BrainError, classifyHttp, isProviderEchoShape, PROVIDER_ECHO_SHAPE, type BrainErrorCode } from "./brain/errors.js";
 export { looksDegenerate, inspectDegenerate, trimDegenerateTail } from "./brain/repetition.js";
 export type { RepetitionEvent, RepetitionInspection } from "./brain/repetition.js";
 export { computeCostMicroUsd, isModelPriced, modelCostToPricing, type ModelPricing, type TokenCounts, } from "./core/pricing.js";
@@ -78,7 +78,7 @@ export { LOCKED_KEY_REGISTRY, resolveLockedKeys, type LockedKey, type LockedConf
 export { BUILTIN_COMPLIANCE_DENIES, COMPLIANCE_CAPABILITIES, WEB_FETCH_TOOL_NAME, complianceCallDenial, resolveComplianceDenies, type ComplianceCapability, type CompliancePosture, type ComplianceProfile, } from "./core/compliance.js";
 export { admitMemoryScopes, foldAdmissionFreeze, type OwnOrgAdmissionVerdict, type MemoryAdmissionInput, type MemoryAdmissionOutcome, type MemoryAdmissionVerdict, type MemoryScopeAdmission, type MemoryScopeOrigin, type MemoryScopeRequest, } from "./core/memory-admission.js";
 export { assertRetentionCapability, RETENTION_CASCADE_DOMAINS, RETENTION_CASCADE_EXEMPT, type ManagedRetentionCapability, type RetentionDeclaration, type RetentionDeclaring, type RetentionPolicy, type RetentionReceipt, } from "./core/retention.js";
-export { GOVERNANCE_CODES, governanceRetryClass, type GovernanceCode, type GovernanceRetryClass } from "./core/governance-codes.js";
+export { GOVERNANCE_CODES, governanceRetryClass, TOOL_DECLARATION_CODES, type GovernanceCode, type GovernanceRetryClass, type ToolDeclarationCode } from "./core/governance-codes.js";
 export { NOTICE_AUDIENCE, noticeAudienceOf, ENGINE_NOTICE_CODES, type EngineNoticeCode, type NoticeAudience } from "./core/governance-codes.js";
 export { TtlSessionStore, type TtlSessionStoreOptions, type EvictPolicy } from "./core/session-store.js";
 export { reconcileInterruptedSession, findOrphanToolCalls, type OrphanToolCall, type ReconcileReport, } from "./core/session-reconcile.js";
@@ -145,7 +145,7 @@ NOTIFICATION_INJECTION_OUTCOMES, // …and their value half + guard, so a host w
 isNotificationInjectionOutcome, SYSTEM_INJECTION_PRIORITIES, isSystemInjectionPriority, AGENT_MESSAGE_TAG, renderAgentMessageFrame, type SemaProvenance, HANDBACK_STATES, type HandbackState, COMPACTION_KINDS, type CompactionKind, handbackStateOf, terminalFrameFacets, } from "./core/task-notification.js";
 export { TOOL_FAMILIES, TOOL_MOUNT_TAGS, TOOL_APPROVAL_CARDS, TOOL_PATH_ACCESSES, TOOL_PATH_BASES, TOOL_PATH_ABSENCES, TOOL_WIRE_NAME_MAX_CHARS, TOOL_CONTRACT_MAX_CHARS, TOOL_CARD_ID_MAX_CHARS, TOOL_KEY_MAX_CHARS, TOOL_KEYS_MAX, RENDER_HINT_MAX_CHARS, RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_LIST, type ToolFamily, type ToolMountTag, type ToolApprovalCard, type ToolPathAccess, type ToolPathBase, type ToolPathAbsence, type ToolPathTarget, type ToolCallPathTarget, type ToolRosterPathTarget, pathTargetSlotOnly, type ToolRuleFace, type ToolRenderHints, type ToolFaceDeclaration, type ToolCatalogEntry, } from "./core/tool-face.js";
 export { describeToolCatalog, catalogEntriesNamed, catalogToolNames, catalogRuleFaceOf, pathTargetOf, pathTargetValue, protectivePathTargetOf, declaredPathTargetOf, BARE_REQUEST_CODE, isProtectedWrite, isDeclaredWrite, fileOpAccessOf, type ToolCallLike, pathConfinableWriteToolNames, skillScopeWriteToolNames, pathTargetingToolNames, compactableToolNames, budgetExemptToolNames, handBandEffects, engineCardTypes, predictMountedToolNames, HANDS_BAND_TAGS, MOUNT_TAG_IN_HANDS_BAND, } from "./core/tool-registry.js";
-export { ToolRosterEntry, ToolRoster, ToolRosterDelta, ToolRosterRenderHints, ROSTER_SOURCES, type RosterSource, type ToolIdentity, toolIdentityOf, mintCapabilityId, diffToolRoster, judgeParkedToolIdentity, ruleFacesFromRoster, toolCallFaceOf, inputKeysOf, ruleFaceOfInstance, rosterMemberBoundProblem, type RosterBoundMembers, type RosterBoundCode, ToolRosterDeltaSeat, } from "./core/tool-roster.js";
+export { ToolRosterEntry, ToolRoster, ToolRosterDelta, ToolRosterRenderHints, ROSTER_SOURCES, type RosterSource, type ToolIdentity, toolIdentityOf, mintCapabilityId, diffToolRoster, judgeParkedToolIdentity, ruleFacesFromRoster, toolCallFaceOf, rosterToolName, ruleNamesOf, inputKeysOf, ruleFaceOfInstance, rosterMemberBoundProblem, type RosterBoundMembers, type RosterBoundCode, ToolRosterDeltaSeat, } from "./core/tool-roster.js";
 export { type ToolCallFace } from "./core/tool-policy.js";
 export { effectivePathTargetOf, pathTargetBaseOf, type ToolPathBases, type PathTargetReading } from "./core/effective-path-target.js";
 export { pathFamilyOf, isAbsoluteForFamily, pathIdentityOf, win32NamespaceScreen, WIN32_NAMESPACE_REFUSALS, type PathFamily, type PathIdentity, type PathIdentityReading, type Win32NamespaceRefusal } from "./tools/fs/safety.js";
@@ -189,7 +189,7 @@ export { createAllowDenyPolicy, createApprovalPolicy,
  *  members that seat has no lane for (`"unavailable"`, a routing answer; `updatedInput`, an operator edit a
  *  policy verdict cannot get re-adjudicated). Exported so a host can NAME it instead of deriving it through
  *  `Parameters<typeof createApprovalPolicy>[0]["approve"]`. */
-type ApprovalSeatOutcome, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, toolPolicyPathDenyRules, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicyProjection, type ToolPolicyProjectionComponent, type ConstraintChainEntry, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, type OnAsk, type AskOutcome, type ResolvedAsk, type AskRequest, type AskDelegationProvenance, type AskRuleEvidence, type AskEvidenceAbsence, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
+type ApprovalSeatOutcome, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, wrapToolPolicy, decisionText, resolveAsk, toolPolicyNameSets, toolPolicyPathDenyRules, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicyProjection, type ToolPolicyProjectionComponent, type ConstraintChainEntry, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, type OnAsk, type AskOutcome, type ResolvedAsk, type AskRequest, type AskDelegationProvenance, type AskRuleEvidence, type AskEvidenceAbsence, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
 export { type ReadRootGrantScreen } from "./core/read-root-grant-screen.js";
 export { type AskOrigin, ASK_ORIGINS, isAskOrigin, ORIGIN_IMPLIES_REAL_APPROVAL, PERSISTED_RULE_MANDATES, type PersistedRuleMandate, isPersistedRuleMandate } from "./core/ask-origin.js";
 export { PERMISSION_MODES, type PermissionMode, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, type AskClass, isAskClass, MODE_ARBITRATION, type ModeArbitrationRow, RELEASABLE_ASK_CLASSES, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, type AskClassification, type AskClassFacts, type ToolMarkSource, arbitrateByMode, type Arbitration, fileCommandOptionsSentence } from "./core/ask-origin.js";

package/dist/index.js

@@ -29,7 +29,7 @@ export { StdioLspTransport } from "./engine/lsp/stdio-lsp-transport.js";
 export { encodeFrame, createFrameDecoder } from "./engine/lsp/frame-decoder.js";
 export { resolveModel, resolveTaskModel, parseModelMention, expandTiers, DEFAULT_TIER_ORDER, CC_MODEL_TIER_ALIASES, ROLE_TIER_DEFAULTS, MODEL_ROLES, } from "./core/roles.js";
 export { selectModel, selectModelOrThrow } from "./core/select-model.js";
-export { BrainError, classifyHttp } from "./brain/errors.js";
+export { BrainError, classifyHttp, isProviderEchoShape, PROVIDER_ECHO_SHAPE } from "./brain/errors.js";
 export { looksDegenerate, inspectDegenerate, trimDegenerateTail } from "./brain/repetition.js";
 export { computeCostMicroUsd, isModelPriced, modelCostToPricing, } from "./core/pricing.js";
 export { cacheFamilyOf, promptTokensOf, uncachedInputTokensOf } from "./core/runner/usage-accounting.js";
@@ -64,7 +64,7 @@ export { LOCKED_KEY_REGISTRY, resolveLockedKeys } from "./core/locked-config.js"
 export { BUILTIN_COMPLIANCE_DENIES, COMPLIANCE_CAPABILITIES, WEB_FETCH_TOOL_NAME, complianceCallDenial, resolveComplianceDenies, } from "./core/compliance.js";
 export { admitMemoryScopes, foldAdmissionFreeze, } from "./core/memory-admission.js";
 export { assertRetentionCapability, RETENTION_CASCADE_DOMAINS, RETENTION_CASCADE_EXEMPT, } from "./core/retention.js";
-export { GOVERNANCE_CODES, governanceRetryClass } from "./core/governance-codes.js";
+export { GOVERNANCE_CODES, governanceRetryClass, TOOL_DECLARATION_CODES } from "./core/governance-codes.js";
 export { NOTICE_AUDIENCE, noticeAudienceOf, ENGINE_NOTICE_CODES } from "./core/governance-codes.js";
 export { TtlSessionStore } from "./core/session-store.js";
 export { reconcileInterruptedSession, findOrphanToolCalls, } from "./core/session-reconcile.js";
@@ -117,7 +117,7 @@ export { DEFAULT_SUBAGENT_TOOL_NAME } from "./agents/subagent.js";
 export { renderTaskNotificationXml, RESUPPLIED_FRAME_PREAMBLE, taskNotificationDedupKey, isDelegatedAgentTerminal, isTerminalTaskNotification, SystemInjectionQueue, NOTIFICATION_INJECTION_OUTCOMES, isNotificationInjectionOutcome, SYSTEM_INJECTION_PRIORITIES, isSystemInjectionPriority, AGENT_MESSAGE_TAG, renderAgentMessageFrame, HANDBACK_STATES, COMPACTION_KINDS, handbackStateOf, terminalFrameFacets, } from "./core/task-notification.js";
 export { TOOL_FAMILIES, TOOL_MOUNT_TAGS, TOOL_APPROVAL_CARDS, TOOL_PATH_ACCESSES, TOOL_PATH_BASES, TOOL_PATH_ABSENCES, TOOL_WIRE_NAME_MAX_CHARS, TOOL_CONTRACT_MAX_CHARS, TOOL_CARD_ID_MAX_CHARS, TOOL_KEY_MAX_CHARS, TOOL_KEYS_MAX, RENDER_HINT_MAX_CHARS, RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_LIST, pathTargetSlotOnly, } from "./core/tool-face.js";
 export { describeToolCatalog, catalogEntriesNamed, catalogToolNames, catalogRuleFaceOf, pathTargetOf, pathTargetValue, protectivePathTargetOf, declaredPathTargetOf, BARE_REQUEST_CODE, isProtectedWrite, isDeclaredWrite, fileOpAccessOf, pathConfinableWriteToolNames, skillScopeWriteToolNames, pathTargetingToolNames, compactableToolNames, budgetExemptToolNames, handBandEffects, engineCardTypes, predictMountedToolNames, HANDS_BAND_TAGS, MOUNT_TAG_IN_HANDS_BAND, } from "./core/tool-registry.js";
-export { ToolRosterEntry, ToolRoster, ToolRosterDelta, ToolRosterRenderHints, ROSTER_SOURCES, toolIdentityOf, mintCapabilityId, diffToolRoster, judgeParkedToolIdentity, ruleFacesFromRoster, toolCallFaceOf, inputKeysOf, ruleFaceOfInstance, rosterMemberBoundProblem, ToolRosterDeltaSeat, } from "./core/tool-roster.js";
+export { ToolRosterEntry, ToolRoster, ToolRosterDelta, ToolRosterRenderHints, ROSTER_SOURCES, toolIdentityOf, mintCapabilityId, diffToolRoster, judgeParkedToolIdentity, ruleFacesFromRoster, toolCallFaceOf, rosterToolName, ruleNamesOf, inputKeysOf, ruleFaceOfInstance, rosterMemberBoundProblem, ToolRosterDeltaSeat, } from "./core/tool-roster.js";
 export {} from "./core/tool-policy.js";
 export { effectivePathTargetOf, pathTargetBaseOf } from "./core/effective-path-target.js";
 export { pathFamilyOf, isAbsoluteForFamily, pathIdentityOf, win32NamespaceScreen, WIN32_NAMESPACE_REFUSALS } from "./tools/fs/safety.js";
@@ -154,7 +154,7 @@ export { hasScheduler, isValidCronExpr, SchedulerError } from "./core/scheduler.
 export { createSchedulerTools, SCHEDULE_WAKEUP_TOOL_NAME, AUTONOMOUS_LOOP_SENTINEL, AUTONOMOUS_LOOP_DYNAMIC_SENTINEL, } from "./tools/scheduler-tools.js";
 export { resolveAutonomousLoopPrompt, AUTONOMOUS_LOOP_PREAMBLE, AUTONOMOUS_LOOP_PREAMBLE_PERSISTENT, } from "./tools/loop-tick.js";
 export { tightenTaskSpec, TaskSpecTightenError } from "./core/tighten-task-spec.js";
-export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, toolPolicyPathDenyRules, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
+export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, wrapToolPolicy, decisionText, resolveAsk, toolPolicyNameSets, toolPolicyPathDenyRules, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
 export {} from "./core/read-root-grant-screen.js";
 export { ASK_ORIGINS, isAskOrigin, ORIGIN_IMPLIES_REAL_APPROVAL, PERSISTED_RULE_MANDATES, isPersistedRuleMandate } from "./core/ask-origin.js";
 export { PERMISSION_MODES, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, isAskClass, MODE_ARBITRATION, RELEASABLE_ASK_CLASSES, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, arbitrateByMode, fileCommandOptionsSentence } from "./core/ask-origin.js";

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

@@ -96,8 +96,8 @@ export interface FileStorageBackendOptions {
      * grows the seat later is wired here in the same constructor.
      *
      * The payload is the UNION shape ({@link FileStorageCorruptReadInfo}): `path` + `reason` always,
-     * with the session-policy face's `sessionId`/`principal` present only when the reading store keys by
-     * them. One sink for one failure grammar — a host does not register three.
+     * `sessionId` when the disclosure is about one session (the session store and the session-policy face),
+     * `principal` when the read was keyed by one. One sink for one failure grammar — a host does not register three.
      */
     onCorruptRead?: (info: FileStorageCorruptReadInfo) => void;
 }
@@ -110,7 +110,9 @@ export interface FileStorageBackendOptions {
  * that replay's count (`"replay"`) from a disclosure about a file or directory as a whole (`"file"`).
  */
 export type FileStorageCorruptReadInfo = CorruptReadInfo & {
-    /** Present only when the reading store keys by session (the session-policy face). */
+    /** Present when the disclosure is about ONE session: the session-policy face's rows, and the session store's
+     *  log of that session (its skipped records and tally, or the log skipped from a listing). Absent on a
+     *  disclosure about a directory as a whole or about a store not keyed by session. */
     sessionId?: string;
     /** Present only when the read was keyed by a principal. */
     principal?: string;