@sema-agent/core 7.52.0 → 7.54.0

package/dist/core/mcp-server-spec.d.ts

@@ -1,3 +1,4 @@
+import { type ReceiptFault } from "./mods/kernel/receive.js";
 import type { ToolContentOrigin, ToolEffect } from "./tool-spec.js";
 import type { ToolFamily, ToolPathTarget, ToolRenderHints, ToolRuleFace } from "./tool-face.js";
 /** Definition of an MCP server to connect to for the duration of one task, then discard. */
@@ -54,6 +55,8 @@ export interface McpServerSpec {
      * override is AUTHORITATIVE and may LOWER an effect (vouch a tool is `read`/`idempotent`) as well as raise it
      * (`egress` / irreversible). This is the ONLY trusted way to drop an MCP tool below the fail-closed `write`
      * default (design F). Folds over the server hints in prepare-task (caller > server hint > fail-closed write).
+     * `boundaryFlow: "engine"` vouches that a call's effect stays inside the engine: the tool's roster row states no boundary legs
+     * (`boundaryLegs: []`) instead of the legs its effect implies — it needs `egress: false` beside it (refused otherwise).
      *
      * A DIFFERENT AXIS from {@link contentOrigin}: this one is about what a call DOES (repeat-safety,
      * blast radius, reversibility — it feeds the approval gate); the content class is about what a call
@@ -61,7 +64,7 @@ export interface McpServerSpec {
      * a read-only tool can return third-party text, and a deployment's own writer brings back nothing
      * external — so vouching on one axis never quietly vouches on the other.
      *
-     * THE SHAPE IS JUDGED, NOT TRUSTED: {@link readMcpToolAxes} is the one reader of this declaration. The
+     * THE SHAPE IS JUDGED, NOT TRUSTED: {@link readToolAxes} is the one reader of this declaration (an A2A peer's `toolAxes` is read by it too). The
      * preparation door runs it on every entry, and a declaration it cannot read refuses the whole prepare
      * (`config.invalid_argument`) — one bad tool refuses the entry, a bad key is never dropped and a bad word
      * never defaults, because a caller's safety axis that silently reads as absent is a trust root that is not
@@ -74,16 +77,19 @@ export interface McpServerSpec {
         effect?: ToolEffect;
         egress?: boolean;
         irreversibility?: "always" | "never";
+        boundaryFlow?: "engine";
     }>;
     /**
      * design/388 §1.1 / §2.7 — the OPTIONAL per-tool FACE overlay for this server's tools (keyed by the server's
      * RAW tool name, like {@link allowTools} / {@link toolAxes}): a deployment lets an MCP tool enter a specialised
      * approval card, be confirmed by path, carry a display name / summary, or narrow its rule vocabulary. TRUSTED
-     * (the deployment writes it), but validated against the MATERIALIZED schema at every listing (first mount and
-     * every refresh): a `pathTarget.param` that is not a top-level property, an `approvalCard` whose keys the schema
-     * lacks, a `ruleFace` naming a non-scalar key ⇒ the tool mounts WITHOUT the overlay and the leg announces
-     * `config.tool_face_invalid` once; a key naming a tool the listing does not carry announces
-     * `config.tool_face_undeclared` once. Applied whole or not at all.
+     * (the deployment writes it). It is read once by `readToolFaces` at the preparation door and at `materializeMcpTools`: a
+     * declaration that does not fit on its own (a member the types do not have, a member of the wrong kind, a word outside a
+     * closed table, a reserved approval card, an empty tool name) refuses the entry under `config.tool_face_invalid` — the whole
+     * prepare at the door. What only the schema can say is judged at every listing (first mount and every refresh): a
+     * `pathTarget.param` that is not a top-level property, an `approvalCard` whose keys the schema lacks, a `ruleFace` naming a
+     * non-scalar key ⇒ that tool is NOT mounted and the leg announces `config.tool_face_invalid` once; a key naming a tool the
+     * listing does not carry announces `config.tool_face_undeclared` once. Applied whole or not at all.
      */
     toolFaces?: Record<string, {
         family?: ToolFamily;
@@ -167,31 +173,151 @@ export interface McpServerSpec {
 }
 type ToolAxes = NonNullable<McpServerSpec["toolAxes"]>;
 /**
- * {@link readMcpToolAxes}'s answer. `ok: true` carries the declaration as a PLAIN COPY the reader built from
+ * The surfaces that declare `toolAxes`, which {@link readToolAxes} names its reading by: an MCP server's keys are the server's
+ * remote TOOL names, an A2A peer's keys are the peer's remote SKILL ids.
+ */
+export type ToolAxesSurface = "mcp" | "a2a";
+/**
+ * {@link readToolAxes}'s answer. `ok: true` carries the declaration as a PLAIN COPY the reader built from
  * what it judged (never the caller's own object); `toolAxes` is absent when the entry declares nothing — no
  * key at all, or only empty per-tool objects (which the engine reads the same as no declaration). `ok: false`
- * carries one sentence naming the tool and the member that did not fit, never a value.
+ * carries one sentence naming the tool (or skill) and the member that did not fit, never a value.
  */
-export type McpToolAxesRead = {
+export type ToolAxesRead = {
     ok: true;
     toolAxes?: ToolAxes;
 } | {
     ok: false;
     problem: string;
 };
+/** A name the declarer wrote, quoted and bounded for a sentence (the sentence names; it never carries a value). The bound holds on the
+ *  QUOTED form — escaping a quote, a backslash or a control character lengthens a name — so a sentence's budget is spent the same way
+ *  whatever the name holds. */
+export declare function quotedName(name: string): string;
+/** The kind of a value that is plain data, for a sentence that names what was declared without carrying it. */
+export declare function dataKind(value: unknown): string;
+/**
+ * Where a declaration stops being one: the path from the declaration's root — a list index as a number, a member name as a string — and
+ * the clause that says what is there ("it contains itself; …"): a kind and a remedy, never a value the declarer wrote.
+ */
+export interface DeclarationFault {
+    readonly path: readonly (string | number)[];
+    readonly problem: string;
+}
+/** {@link receiveDeclaration}'s answer: the engine's own frozen copy, or where and why the declaration could not be received. */
+export type DeclarationRead = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly fault: DeclarationFault;
+};
+/**
+ * A receipt's refusal of a declaration (or of the list that carries declarations), said as a declaration refusal says it. The receipt's
+ * path does not say which kind of container each name came from, so a segment of digits alone is read as a list index.
+ */
+export declare function declarationFaultOf(fault: ReceiptFault): DeclarationFault;
+/** What a declaration's own type fixes at one path, beyond being plain data: a string there, or a record of names to strings. */
+export interface DeclarationPathRule {
+    readonly path: readonly string[];
+    readonly holds: "a string" | "names to strings";
+    /** The member must be there (a declaration with no value at the path is refused, as one with a value of another kind is). */
+    readonly required?: true;
+}
+/**
+ * Per surface, every path its declaration's type fixes beyond plain data — the declarer's `name` (a string, always there) and every record
+ * the type writes as `Record<string, string>`: an MCP server's `transport.env` (a stdio server's environment) and `transport.headers` (an
+ * HTTP server's headers); an A2A peer's `headers`. A path that is not its surface's (an A2A peer's `transport`) is not judged by another
+ * surface's row: it is a member the surface does not read.
+ */
+export declare const DECLARATION_PATH_RULES: Readonly<Record<ToolAxesSurface, readonly DeclarationPathRule[]>>;
+/** The rules of a declaration that fixes no path beyond plain data and lists of names (a `toolAxes` record, a lock declaration): the one
+ *  empty table, passed on purpose — {@link receiveDeclaration} takes its rules as an argument and refuses an absent one. */
+export declare const NO_DECLARATION_PATH_RULES: readonly DeclarationPathRule[];
+/**
+ * The one reading of a declaration a caller hands the engine — an MCP server's or an A2A peer's entry (the snapshot), a `toolAxes`
+ * record ({@link readToolAxes}), a lock declaration: the engine's one receipt of a caller's object in its declaration mode, so the
+ * value is plain data held to the engine's one depth ({@link MODS_VALUE_DEPTH} levels below it) and every own member is read once, then, when the copy is a record, the declaration's own
+ * vocabulary over the copy (a list holds names; no member is named `__proto__`; each path `rules` names holds what its rule says — an
+ * entry's rules are its surface's {@link DECLARATION_PATH_RULES}). The copy is the answer — the caller's object is never handed on and
+ * never read again. A copy that is not a record is answered as it is, for the reader that expected a record to word.
+ *
+ * `rules` is required: a surface's {@link DECLARATION_PATH_RULES} row, or an empty list ({@link NO_DECLARATION_PATH_RULES} is the engine's
+ * own) for a declaration that fixes no path. A value that is not a list (an absent one — what an `at` outside the surfaces indexes to — `null`, a string, an inherited
+ * member of the table) is a caller's mistake about which declaration it holds, refused loudly (`config.invalid_argument`) rather than
+ * read as "no path rule", which would judge the declaration by less than its surface fixes.
+ */
+export declare function receiveDeclaration(declared: unknown, rules: readonly DeclarationPathRule[]): DeclarationRead;
+/**
+ * The per-tool declarations a spec carries as ONE record keyed by the remote tool (or skill) name — what each is called in a
+ * sentence about it. Every reader of such a record ({@link readToolAxes}, `readToolFaces`) opens it through
+ * {@link receivePerToolDeclaration} and words a refusal through the two sentence functions below, so the one receipt, the one
+ * fault vocabulary and the one sentence shape are not written twice.
+ */
+declare const PER_TOOL_DECLARATIONS: {
+    readonly toolAxes: {
+        readonly plural: "axes";
+        readonly singular: "axis";
+    };
+    readonly toolFaces: {
+        readonly plural: "faces";
+        readonly singular: "face";
+    };
+};
+type PerToolDeclaration = keyof typeof PER_TOOL_DECLARATIONS;
+/** {@link receivePerToolDeclaration}'s answer: the receipt's copy as a record keyed by name, or the one sentence that says why not. */
+type PerToolDeclarationRead = {
+    readonly ok: true;
+    readonly perTool: Readonly<Record<string, unknown>>;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
 /**
- * The one reader of a raw {@link McpServerSpec.toolAxes} declaration — the engine's preparation door and
- * every host that assembles the field from JSON ask this same function. Absent ⇒ `{ ok: true }` (nothing
- * declared). Anything else must be an object of per-tool objects whose members are exactly `effect` /
- * `egress` / `irreversibility` with legal values; a declaration of any other shape, an empty tool name, an
+ * A per-tool declaration's receipt: {@link receiveDeclaration} (plain data held to the engine's one depth, every own member read once,
+ * lists of names, no `__proto__`), then the copy must be a record of names. A refusal names the tool (or skill) and the member where
+ * reading stopped, never a value. `unit` is what the keys are called (`tool` / `skill`).
+ */
+export declare function receivePerToolDeclaration(declared: unknown, field: PerToolDeclaration, unit: string): PerToolDeclarationRead;
+/** The sentence for one tool's (or skill's) declaration that does not fit: `detail` says which member and why. */
+export declare function perToolEntryRefusal(field: PerToolDeclaration, unit: string, key: string, detail: string): string;
+/** The sentence for a per-tool declaration that names a tool (or skill) with an empty name. */
+export declare function perToolEmptyName(field: PerToolDeclaration, unit: string): string;
+/**
+ * The one reader of a raw `toolAxes` declaration — {@link McpServerSpec.toolAxes} and {@link A2aServerSpec.toolAxes} are the same
+ * declaration, and the engine's preparation door, its materialization of an MCP server and of an A2A peer, and every host that
+ * assembles the field from JSON ask this same function. `at` names the surface the declaration sits on, because that decides what its
+ * keys are called in the sentence: `"mcp"` — the server's remote tools; `"a2a"` — the peer's remote skills. Absent ⇒ `{ ok: true }`
+ * (nothing declared). Anything else must be an object of per-tool objects whose members are exactly `effect` /
+ * `egress` / `irreversibility` / `boundaryFlow` with legal values; a declaration of any other shape, an empty tool name, an
  * unknown member, a word outside the vocabulary or a non-boolean `egress` on ANY one tool refuses the whole
  * declaration (`ok: false`) — the good tools are not kept and nothing is defaulted, since a caller axis is
  * two-way (it can vouch a tool down as well as mark it up) and a silently lost half is a trust root that is
- * not in force. The reader judges SHAPE only; whether the axes contradict each other (`egress` over a
- * non-write effect) is the ingestion's own arithmetic. The reader is total: a getter, a proxy trap or a tag
- * that throws while the declaration is read is a refusal that says so (never the thrown text), not a throw.
+ * not in force. `boundaryFlow: "engine"` (the call's effect stays inside the engine — the tool's roster row states no
+ * boundary legs) needs `egress: false` in the same entry — `egress: true` contradicts it and an absent one leaves a server hint
+ * or the peer default marking it an external write — refused here; whether the other axes contradict each other (`egress`
+ * over a non-write effect) is the ingestion's own arithmetic. The declaration is read once, as plain data, by {@link receiveDeclaration} — a
+ * Proxy, a map, a class instance, a record built on a prototype or in another realm, a getter that throws, a structure that contains
+ * itself, a tool named `__proto__` are refusals that say where they sit (never the thrown text), not a throw — and judged on that copy.
+ * `at` is the caller's own word, not the declarer's: one outside {@link ToolAxesSurface} throws `config.invalid_argument` naming the
+ * surfaces, whatever is declared.
+ */
+export declare function readToolAxes(declared: unknown, at: ToolAxesSurface): ToolAxesRead;
+/** {@link readToolAxes} for an MCP server's declaration — the entry a host that mounts MCP servers asks. */
+export declare function readMcpToolAxes(declared: unknown): ToolAxesRead;
+/**
+ * The word a sentence about one declaration of the surface `at` names the declarer by — `MCP server`, `A2A peer`. The same row the
+ * `toolAxes` refusal below reads, so every sentence the engine writes about a declaration it cannot read calls the declarer one thing.
  */
-export declare function readMcpToolAxes(declared: unknown): McpToolAxesRead;
+export declare function declarerWord(at: ToolAxesSurface): string;
+/**
+ * The refusal an entry's unreadable `toolAxes` becomes (`config.invalid_argument`), ONE sentence for every surface that declares them:
+ * the subject is the surface's declarer word and `name` (already quoted and bounded by the caller: `MCP server "db"`, `A2A peer "agent"`),
+ * `problem` is {@link readToolAxes}'s own sentence.
+ */
+export declare function toolAxesRefusal(at: ToolAxesSurface, name: string, problem: string): Error & {
+    code: "config.invalid_argument";
+};
 /** The identity of one mount of a declared server, as the host minted it ({@link McpServerSpec.fingerprint}). */
 export interface McpMountIdentity {
     readonly fingerprint: string;
@@ -242,11 +368,20 @@ export interface A2aServerSpec {
      * raise it — e.g. `{ egress: false, effect: "read" }` vouches that a skill only reads. Note that
      * lowering `effect` WITHOUT clearing `egress` is a contradiction prepare-task refuses by design (an
      * external write must be repeat-unsafe).
+     *
+     * THE SHAPE IS JUDGED, NOT TRUSTED, by the same reader as {@link McpServerSpec.toolAxes} ({@link readToolAxes} with `at: "a2a"`) and
+     * with the same disposition: a task's preparation door runs it on every peer of `TaskSpec.a2a`, and a declaration it cannot read
+     * refuses the whole prepare (`config.invalid_argument`, subject `A2A peer "<name>"`) before any peer is dialed — one bad skill refuses
+     * the task, a bad key is never dropped and a bad word never defaults. The materialization entrance (`materializeA2aTools`, the library
+     * entrance) asks it once per peer, when it reads that peer's declaration: there a declaration it cannot read fails THAT peer's dial
+     * (never dialed, a warning whose cause is the same refusal), its siblings unaffected; a refresh does not ask again, it dials the copy
+     * that was judged (a peer refused at the entrance is refused again by every refresh, from the stored refusal).
      */
     toolAxes?: Record<string, {
         effect?: ToolEffect;
         egress?: boolean;
         irreversibility?: "always" | "never";
+        boundaryFlow?: "engine";
     }>;
 }
 /**

package/dist/core/mcp-server-spec.js

@@ -1,30 +1,171 @@
 import { SAFETY_AXIS_VOCABULARY } from "./safety-axis-vocab.js";
-const TOOL_AXIS_MEMBERS = { effect: true, egress: true, irreversibility: true };
+import { INLINE_TRUNCATION_MARK, inlineUntrusted } from "./untrusted-text.js";
+import { DECLARATION_RECEIPT_MODE } from "./own-property-receipt.js";
+import { isPlainRecord, receive } from "./mods/kernel/receive.js";
+import { MODS_VALUE_DEPTH } from "./mods/kernel/site-rules.js";
+const TOOL_AXES_SURFACES = {
+    mcp: { key: "tool", declarer: "MCP server" },
+    a2a: { key: "skill", declarer: "A2A peer" },
+};
+function invalidArgument(message) {
+    const refusal = new Error(message);
+    refusal.code = "config.invalid_argument";
+    return refusal;
+}
+function toolAxesSurfaceOf(at) {
+    if (typeof at === "string" && Object.hasOwn(TOOL_AXES_SURFACES, at))
+        return TOOL_AXES_SURFACES[at];
+    throw invalidArgument(`toolAxes is read for a surface, and the surfaces are ${Object.keys(TOOL_AXES_SURFACES).map((s) => JSON.stringify(s)).join(" | ")} ` +
+        `(an MCP server's tools, an A2A peer's skills); the surface named is not one of them.`);
+}
+const TOOL_AXIS_MEMBERS = { effect: true, egress: true, irreversibility: true, boundaryFlow: true };
 const TOOL_AXIS_MEMBER_NAMES = Object.keys(TOOL_AXIS_MEMBERS);
 const TOOL_EFFECT_WORDS = SAFETY_AXIS_VOCABULARY.toolEffect;
 const ENGINE_DERIVED_IRREVERSIBILITY = "maybe";
 const IRREVERSIBILITY_POLE_WORDS = SAFETY_AXIS_VOCABULARY.irreversibility.filter((word) => word !== ENGINE_DERIVED_IRREVERSIBILITY);
 const irreversibilityPolesLockstep = true;
 void irreversibilityPolesLockstep;
-function quotedName(name) {
-    return JSON.stringify(name.length > 80 ? `${name.slice(0, 80)}…` : name);
-}
-function describeKind(value) {
-    return value === null ? "null" : Array.isArray(value) ? "an array" : typeof value === "object" ? "an object that is not a plain data record (a map, a class instance, or members that are inherited or not enumerable)" : `a ${typeof value}`;
-}
-const ROOT_PROTOTYPE_NAMES = Object.getOwnPropertyNames(Object.prototype).sort().join("\n");
-function isRootPrototype(proto) {
-    if (proto === Object.prototype)
-        return true;
-    return Object.getPrototypeOf(proto) === null && Object.getOwnPropertyNames(proto).sort().join("\n") === ROOT_PROTOTYPE_NAMES;
-}
-function isPlainRecord(value) {
-    if (typeof value !== "object" || value === null)
-        return false;
-    const proto = Object.getPrototypeOf(value);
-    if (proto !== null && !isRootPrototype(proto))
-        return false;
-    return Object.getOwnPropertyNames(value).length === Object.keys(value).length;
+const toolAxesDeclarationsAreOne = true;
+void toolAxesDeclarationsAreOne;
+export function quotedName(name) {
+    const whole = JSON.stringify(name);
+    if (name.length <= 80 && whole.length <= QUOTED_NAME_MAX)
+        return whole;
+    let cut = Math.min(name.length, 80);
+    while (cut > 0 && JSON.stringify(`${name.slice(0, cut)}…`).length > QUOTED_NAME_MAX)
+        cut--;
+    return JSON.stringify(`${name.slice(0, cut)}…`);
+}
+const QUOTED_NAME_MAX = 83;
+function memberNames(path) {
+    let rendered = "";
+    for (const [index, name] of path.entries()) {
+        if (rendered.length > 120)
+            return `${rendered}${INLINE_TRUNCATION_MARK}`;
+        rendered += `${index === 0 ? "" : "."}${quotedName(String(name))}`;
+    }
+    return rendered;
+}
+export function dataKind(value) {
+    return value === null ? "null" : value === undefined ? "undefined" : Array.isArray(value) ? "an array" : typeof value === "object" ? "a record" : `a ${typeof value}`;
+}
+const RECEIPT_FAULT_PROBLEMS = {
+    proxy: "it is a Proxy, whose traps would run as it is read; copy it into plain data (a spread or a JSON round trip)",
+    "not-data": "it is not plain data (a function, a bigint, a symbol, or an object whose prototype is neither Object.prototype nor null: a class instance, " +
+        "a map, `process.env`, a record built on a prototype or in another realm — a `vm` context, a worker); copy it into plain data (a spread " +
+        "or a JSON round trip), writing out any member it inherits",
+    "getter-threw": "its getter threw while it was read",
+    "prototype-moved": "its prototype changed while it was read",
+    cycle: "it contains itself; declare it as plain data",
+    "too-deep": `it is nested past ${MODS_VALUE_DEPTH} levels`,
+    uncopyable: "it could not be copied whole",
+    accessor: "it is an accessor",
+    hidden: "it is a member that is not an enumerable data property",
+};
+export function declarationFaultOf(fault) {
+    return { path: fault.path.map((key) => (/^(?:0|[1-9]\d*)$/.test(key) ? Number(key) : key)), problem: RECEIPT_FAULT_PROBLEMS[fault.kind] };
+}
+export const DECLARATION_PATH_RULES = Object.freeze({
+    mcp: Object.freeze([
+        { path: ["name"], holds: "a string", required: true },
+        { path: ["transport", "env"], holds: "names to strings" },
+        { path: ["transport", "headers"], holds: "names to strings" },
+    ].map((rule) => Object.freeze({ ...rule, path: Object.freeze([...rule.path]) }))),
+    a2a: Object.freeze([
+        { path: ["name"], holds: "a string", required: true },
+        { path: ["headers"], holds: "names to strings" },
+    ].map((rule) => Object.freeze({ ...rule, path: Object.freeze([...rule.path]) }))),
+});
+export const NO_DECLARATION_PATH_RULES = Object.freeze([]);
+const PROTO_MEMBER = `it is a member named "__proto__", which a copy by assignment would turn into a prototype — not a name a declaration can carry`;
+function declarationVocabularyFault(root, rules) {
+    const asked = new Set();
+    const path = [];
+    const stack = [];
+    const ruleAt = () => rules.find((rule) => rule.path.length === path.length && rule.path.every((key, i) => key === path[i]));
+    const onRuleRoute = () => rules.some((rule) => rule.path.length > path.length && path.every((key, i) => key === rule.path[i]));
+    const ruleProblem = (rule, value) => {
+        if (rule.holds === "a string")
+            return typeof value === "string" ? undefined : `it is ${dataKind(value)}, not a string`;
+        if (!isPlainRecord(value))
+            return `it is ${dataKind(value)}, not a record of names to strings`;
+        for (const [key, member] of Object.entries(value)) {
+            path.push(key);
+            if (key === "__proto__")
+                return PROTO_MEMBER;
+            if (member !== undefined && typeof member !== "string")
+                return `it is ${dataKind(member)}, not a string: this record maps names to strings`;
+            path.pop();
+        }
+        return undefined;
+    };
+    const meet = (value) => {
+        if (typeof value !== "object" || value === null || (asked.has(value) && !onRuleRoute()))
+            return undefined;
+        asked.add(value);
+        if (Array.isArray(value)) {
+            for (let index = 0; index < value.length; index++) {
+                const own = Object.hasOwn(value, index);
+                if (own && typeof value[index] === "string")
+                    continue;
+                path.push(index);
+                return `it is ${own ? dataKind(value[index]) : "a hole"}, not a string: every list a declaration carries is a list of names`;
+            }
+            const named = Object.keys(value).find((key) => !(/^(?:0|[1-9]\d*)$/.test(key) && Number(key) < value.length));
+            if (named === undefined)
+                return undefined;
+            path.push(named);
+            return "it is a list member that is not an index: a list declares its names at its indices only";
+        }
+        stack.push({ members: Object.entries(value), next: 0 });
+        return undefined;
+    };
+    for (const rule of rules) {
+        if (rule.required !== true)
+            continue;
+        let at = root;
+        for (const key of rule.path)
+            at = isPlainRecord(at) && Object.hasOwn(at, key) ? at[key] : undefined;
+        if (at === undefined)
+            return { path: [...rule.path], problem: `it is missing: a declaration carries ${rule.holds} here` };
+    }
+    let problem = meet(root);
+    while (problem === undefined && stack.length > 0) {
+        const frame = stack[stack.length - 1];
+        if (frame.next === frame.members.length) {
+            stack.pop();
+            if (stack.length > 0)
+                path.pop();
+            continue;
+        }
+        const [key, member] = frame.members[frame.next++];
+        path.push(key);
+        const rule = key === "__proto__" || member === undefined ? undefined : ruleAt();
+        if (key === "__proto__")
+            problem = PROTO_MEMBER;
+        else if (rule !== undefined)
+            problem = ruleProblem(rule, member);
+        else {
+            const depth = stack.length;
+            problem = meet(member);
+            if (problem === undefined && stack.length > depth)
+                continue;
+        }
+        if (problem === undefined)
+            path.pop();
+    }
+    return problem === undefined ? undefined : { path, problem };
+}
+export function receiveDeclaration(declared, rules) {
+    if (!Array.isArray(rules)) {
+        throw invalidArgument(`a declaration is received with the path rules of its surface (${Object.keys(DECLARATION_PATH_RULES).map((s) => `DECLARATION_PATH_RULES[${JSON.stringify(s)}]`).join(" | ")}), ` +
+            `or an empty list when it fixes no path; what was passed is ${dataKind(rules)}, not a list of rules.`);
+    }
+    const received = receive(declared, DECLARATION_RECEIPT_MODE);
+    if (!received.ok)
+        return { ok: false, fault: declarationFaultOf(received.fault) };
+    const fault = isPlainRecord(received.value) ? declarationVocabularyFault(received.value, rules) : undefined;
+    return fault === undefined ? { ok: true, value: received.value } : { ok: false, fault };
 }
 function isToolEffectWord(value) {
     return typeof value === "string" && TOOL_EFFECT_WORDS.includes(value);
@@ -34,40 +175,71 @@ function isIrreversibilityPoleWord(value) {
 }
 function readToolAxisEntry(raw) {
     if (!isPlainRecord(raw))
-        return `the declaration is ${describeKind(raw)}, not an object of axes`;
-    for (const member of Object.keys(raw)) {
-        if (!TOOL_AXIS_MEMBER_NAMES.includes(member))
-            return `unknown member ${quotedName(member)} (the members are ${TOOL_AXIS_MEMBER_NAMES.join(", ")})`;
+        return `the declaration is ${dataKind(raw)}, not an object of axes`;
+    const listed = Object.keys(raw);
+    const unknown = listed.find((member) => !TOOL_AXIS_MEMBER_NAMES.includes(member));
+    if (unknown !== undefined)
+        return `unknown member ${quotedName(unknown)} (the members are ${TOOL_AXIS_MEMBER_NAMES.join(", ")})`;
+    const declared = Object.create(null);
+    for (const member of TOOL_AXIS_MEMBER_NAMES) {
+        const value = raw[member];
+        if (value !== undefined && !listed.includes(member))
+            return `member ${quotedName(member)} is a hidden member: its name answers a value the declaration does not list as its own`;
+        declared[member] = value;
     }
-    const { effect, egress, irreversibility } = raw;
+    const { effect, egress, irreversibility, boundaryFlow } = declared;
     if (effect !== undefined && !isToolEffectWord(effect))
         return `member "effect" is not one of ${TOOL_EFFECT_WORDS.join(" | ")}`;
     if (egress !== undefined && typeof egress !== "boolean")
         return `member "egress" is not a boolean`;
     if (irreversibility !== undefined && !isIrreversibilityPoleWord(irreversibility))
         return `member "irreversibility" is not one of ${IRREVERSIBILITY_POLE_WORDS.join(" | ")}`;
+    if (boundaryFlow !== undefined && boundaryFlow !== "engine")
+        return `member "boundaryFlow" is not "engine"`;
+    if (boundaryFlow === "engine" && egress !== false)
+        return `member "boundaryFlow": "engine" needs "egress": false in the same entry — add it, or drop "boundaryFlow" (${egress === true ? '"egress": true contradicts it' : 'with no "egress", the server hint or the peer default stays in force'})`;
     return {
         ...(effect !== undefined ? { effect } : {}),
         ...(egress !== undefined ? { egress } : {}),
         ...(irreversibility !== undefined ? { irreversibility } : {}),
+        ...(boundaryFlow !== undefined ? { boundaryFlow } : {}),
     };
 }
-export function readMcpToolAxes(declared) {
+const PER_TOOL_DECLARATIONS = {
+    toolAxes: { plural: "axes", singular: "axis" },
+    toolFaces: { plural: "faces", singular: "face" },
+};
+export function receivePerToolDeclaration(declared, field, unit) {
+    const received = receiveDeclaration(declared, NO_DECLARATION_PATH_RULES);
+    if (!received.ok) {
+        const [key, ...member] = received.fault.path;
+        if (key === undefined)
+            return { ok: false, problem: `${field} cannot be read: ${received.fault.problem}` };
+        const where = member.length > 0 ? `member ${memberNames(member)}: ` : "";
+        return { ok: false, problem: perToolEntryRefusal(field, unit, String(key), `${where}${received.fault.problem}`) };
+    }
+    const perTool = received.value;
+    if (!isPlainRecord(perTool))
+        return { ok: false, problem: `${field} is ${dataKind(perTool)}, not an object of per-${unit} ${PER_TOOL_DECLARATIONS[field].singular} declarations` };
+    return { ok: true, perTool };
+}
+export function perToolEntryRefusal(field, unit, key, detail) {
+    return `the ${PER_TOOL_DECLARATIONS[field].plural} declared for ${unit} ${quotedName(key)} do not fit: ${detail}`;
+}
+export function perToolEmptyName(field, unit) {
+    return `${field} has an empty ${unit} name`;
+}
+export function readToolAxes(declared, at) {
+    const unit = toolAxesSurfaceOf(at).key;
     if (declared === undefined)
         return { ok: true };
-    let perTool;
-    try {
-        if (!isPlainRecord(declared))
-            return { ok: false, problem: `toolAxes is ${describeKind(declared)}, not an object of per-tool axis declarations` };
-        perTool = Object.entries(declared);
-    }
-    catch {
-        return { ok: false, problem: "toolAxes could not be read: a property threw while it was read" };
-    }
+    const received = receivePerToolDeclaration(declared, "toolAxes", unit);
+    if (!received.ok)
+        return { ok: false, problem: received.problem };
     const entries = [];
-    for (const [tool, raw] of perTool) {
-        if (tool.length === 0)
-            return { ok: false, problem: "toolAxes has an empty tool name" };
+    for (const [key, raw] of Object.entries(received.perTool)) {
+        if (key.length === 0)
+            return { ok: false, problem: perToolEmptyName("toolAxes", unit) };
         let entry;
         try {
             entry = readToolAxisEntry(raw);
@@ -76,9 +248,20 @@ export function readMcpToolAxes(declared) {
             entry = "a member threw while it was read";
         }
         if (typeof entry === "string")
-            return { ok: false, problem: `the axes declared for tool ${quotedName(tool)} do not fit: ${entry}` };
+            return { ok: false, problem: perToolEntryRefusal("toolAxes", unit, key, entry) };
         if (Object.keys(entry).length > 0)
-            entries.push([tool, entry]);
+            entries.push([key, entry]);
     }
     return entries.length > 0 ? { ok: true, toolAxes: Object.fromEntries(entries) } : { ok: true };
 }
+export function readMcpToolAxes(declared) {
+    return readToolAxes(declared, "mcp");
+}
+export function declarerWord(at) {
+    return toolAxesSurfaceOf(at).declarer;
+}
+export function toolAxesRefusal(at, name, problem) {
+    return invalidArgument(`${toolAxesSurfaceOf(at).declarer} ${name} declares toolAxes the engine cannot read: ${inlineUntrusted(problem, 240)}. A per-tool safety-axis declaration is the ` +
+        `caller's trust root for the approval gate, so it is refused rather than partly applied — dropping one key or defaulting one word ` +
+        `would leave a declaration that reads as in force while it is not.`);
+}

package/dist/core/mcp.d.ts

@@ -110,14 +110,15 @@ export interface MaterializedMcp {
      * G1 通告层续批 (CC `mcp_instructions_delta` parity) — the run-scoped instruction-delta ref the run
      * loop drains at turn boundaries (`spec.attachments.mcpInstructions` opt-in; `newTools` consumption
      * discipline: drained only when the announcement survived the byte cap intact).
-     * - `pendingRemovals`: an INSTRUCTION-BEARING server whose transport closed mid-task (the CC
-     *   "servers have disconnected — their instructions above no longer apply" copy is instruction-scoped,
-     *   so instruction-less servers are not tracked). `dispose()` disarms first: task teardown is not a
-     *   disconnect.
-     * - `pendingAdds`: the CC add lane ("# MCP Server Instructions" reminder). Structurally present for a
-     *   dynamic mid-task connect face; TODAY nothing populates it — sema connects all servers at prepare
-     *   and carries their initial instructions in the stable system prompt (design/64 §17.3, deliberate
-     *   CC deviation: prefix-cache-correct).
+     * - `pendingRemovals`: a server whose instructions are in the model's context and whose transport closed
+     *   mid-task, or whose re-dial failed (the CC "servers have disconnected — their instructions above no
+     *   longer apply" copy names only what the model holds — the lane's ledger, `instructionsTold`).
+     *   `dispose()` disarms first: task teardown is not a disconnect.
+     * - `pendingAdds`: the CC add lane ("# MCP Server Instructions" reminder). A server's INITIAL
+     *   instructions ride the stable system prompt instead (design/64 §17.3, deliberate CC deviation:
+     *   prefix-cache-correct); this lane carries what comes later — a re-dial queues its new
+     *   connection's text here, and a run adds the text of a server it is to teach and has not told.
+     * A materialization alone takes every entry of `serverInstructions` as taught; a run states its block.
      */
     instructionsDelta: {
         pendingAdds: McpInstructionsEntry[];
@@ -163,7 +164,7 @@ export interface MaterializedMcp {
     droppedTools: McpDroppedTool[];
     /**
      * design/99 §E9 — per-server status, a PURE PROJECTION of THIS materialization (no new connection logic).
-     * One entry per declared server. **Semantics = the moment of this task leg's materialize** — core never
+     * One entry per declared server DIALED (none for one `dialable` kept from the dial). **Semantics = the moment of this task leg's materialize** — core never
      * persists MCP connections, so it is "did this leg connect", NOT a live session-health signal between tasks.
      * A consumer (service) surfacing it as session status must understand that. `toolNames` are the namespaced
      * (`<server>__<tool>`) names exposed.
@@ -178,7 +179,7 @@ export interface MaterializedMcp {
     /**
      * RefreshMcpTools (CC 2.1.218 parity, anchored to the CLI form) — re-read the tool list of one server (or
      * every CONNECTED server when `server` is omitted) over the EXISTING connection. NEVER dials or
-     * re-dials: a dead/never-connected server reports `not_connected`; a live listTools failure
+     * re-dials: a dead/never-connected server reports `not_connected` (so does one whose connection closed while the walk was reading); a live listTools failure
      * reports `failed` (the connection is left as-is). A refreshed entry carries the NEW intake
      * result (tools/axes/dropped — the same schema-gate/namespacing/axis pipeline as connect) plus
      * the added/removed namespaced tool names relative to the previous listing; the caller (the
@@ -229,6 +230,7 @@ export interface McpRefreshResult {
      *  contact it (no tools/list round trip; the engine must not hand a severed server a request
      *  channel or splice its post-revocation text into the model catalog). */
     status: "refreshed" | "not_connected" | "failed" | "revoked";
+    /** The same reading as {@link McpReconnectResult.toolCount}: the server's tools the producer holds after the call. */
     toolCount: number;
     added: string[];
     /**
@@ -243,6 +245,9 @@ export interface McpRefreshResult {
     tools?: AgentTool[];
     axes?: McpToolAxis[];
     dropped?: McpDroppedTool[];
+    /** On a `"refreshed"` entry whose connection carries instructions: that connection's entry as its dial disposed of it (`author: "host"` when replaced) —
+     *  a refresh re-reads tools, never instructions; a run whose roster change first leaves something of the server teaches it. */
+    instructions?: McpInstructionsEntry;
     /**
      * Set on `not_connected` / `failed` / `revoked`; ALSO set on a `"refreshed"` entry whose listing walk
      * did not finish (see {@link listingIncomplete}) — a refresh that produced usable tools is not a
@@ -287,12 +292,14 @@ export interface McpReconnectResult {
     /** Why, on every non-`reconnected` outcome (neutralized + bounded when it embeds remote text).
      *  Never the only machine-readable fact: see {@link status}. */
     reason?: string;
+    /** How many of the server's tools the producer holds after the call — its roster: the run's (the valve and the deployment's
+     *  overlay applied) for the run handle's `reconnectMcpServer`, this materialization's own handles for `MaterializedMcp.reconnect`
+     *  (no run). A name no server is declared under holds nothing. Equal to `tools.length` whenever `tools` is present. */
     toolCount: number;
-    /** Namespaced names this re-dial added / took away relative to what the server had mounted a moment
-     *  ago — a first successful dial adds its whole roster, a failed dial removes it. */
+    /** The namespaced names that came onto / left that roster (a first dial adds its whole roster, a failed dial removes it). */
     added: string[];
     removed: string[];
-    /** See the type docstring: present iff this result asserts a roster for `prefix`. */
+    /** See the type docstring: present iff this result asserts a roster for `prefix` — and then it is that roster's tools of the server. */
     tools?: AgentTool[];
     axes?: McpToolAxis[];
     dropped?: McpDroppedTool[];
@@ -609,7 +616,7 @@ reminderDisclosure?: {
 }, poolOpts?: {
     pool: McpConnectionPool;
     ownsPool?: boolean;
-}, promptSections?: PromptSectionDisposer): Promise<MaterializedMcp>;
+}, promptSections?: PromptSectionDisposer, dialable?: (spec: McpServerSpec) => boolean): Promise<MaterializedMcp>;
 /**
  * Fold the caller's AUTHORITATIVE per-tool override (design F: caller = trust root) over the server-hint axis.
  * Unlike server hints, the caller may RAISE or LOWER any axis: `effect` sets the repeat-safety class (lower to