eval-quality 1.4.2 → 3.0.0

package/dist/core/schemas/primitives.js

@@ -12,6 +12,17 @@ export const Identifier = z
     .string()
     .regex(IDENTIFIER_PATTERN)
     .describe('A kebab-case slug. Excludes "/" and "~" so an identifier can be embedded in an interaction-rooted pointer without escaping.');
+// A tool name is the ecosystem's own spelling rather than this repository's.
+// MCP servers publish `search_notes` and `searchNotes`, and `Identifier`'s
+// kebab charset would reject both, which would make a contract unable to name
+// the tool it evaluates. The charset admits letters, digits, underscore, and
+// hyphen and nothing else, so an address in any of its three spellings is a
+// parse error.
+export const TOOL_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+export const ToolName = z
+    .string()
+    .regex(TOOL_NAME_PATTERN)
+    .describe('The name the MCP server publishes for one tool, in the server\'s own spelling. AD-35: a logical identifier, never a URL, host, or port. The charset admits no "/", ":", or ".", so an address is unrepresentable rather than refused by a later check, and it excludes "~" so a tool name can be embedded in a pointer without escaping.');
 // All eight Consistency-Conventions prefixes are defined here even though this
 // artifact uses five: the Probe, Evidence Artifact, and finding shapes import
 // P-, D-, and F- rather than re-spelling the quantifier, and a second spelling
@@ -81,6 +92,24 @@ export const JsonTypeName = z.enum([
 // A declared key name: used in a request shape, a response descriptor, or a
 // reference-set key list. Plain caller-supplied text.
 export const KeyName = z.string().min(1);
+/**
+ * An environment variable name, at the port boundary where one becomes a real
+ * variable on a real process. `KeyName` is plain text, and a plain-text key is
+ * a smuggling channel here: `A=B` reaches the child as a variable `A` whose
+ * value carries `B=` in front of the declared one, and a key holding a NUL
+ * fails the spawn itself. The charset is the portable one, which is what a
+ * caller reading a mapping's allowlist assumes it is reading.
+ *
+ * This keys the port message, which every request crosses, and the
+ * authorization allowlist, which only a caller who parses their own mapping
+ * crosses: nothing in this package parses `CommandTargetPolicy`. The contract
+ * side keeps `KeyName`, since AD-19's channel shapes are one grammar across
+ * every channel, so a contract declaring a malformed environment key compiles
+ * and fails at this boundary with `schema-parse-failure`.
+ */
+export const EnvironmentKeyName = z
+    .string()
+    .regex(/^[A-Za-z_][A-Za-z0-9_]*$/, 'an environment key is a letter or underscore followed by letters, digits or underscores');
 // The one shape whose keys belong to the caller, so `additionalProperties` is
 // schema-valued rather than false here alone. Hand-rolled with z.lazy rather
 // than z.json(): the latter exports a generated `$defs` ref name that the

package/dist/core/schemas/probe-policy.d.ts

@@ -91,6 +91,7 @@ export declare const CommandTargetAuthorization: z.ZodObject<{
     executable: z.ZodString;
     target: z.ZodString;
     permittedSubcommandPaths: z.ZodArray<z.ZodArray<z.ZodString>>;
+    permittedEnvironmentKeys: z.ZodArray<z.ZodString>;
     cwd: z.ZodString;
     artifacts: z.ZodRecord<z.ZodString, z.ZodString>;
     maxElapsedMs: z.ZodInt;
@@ -102,6 +103,7 @@ export declare const CommandTargetPolicy: z.ZodObject<{
         executable: z.ZodString;
         target: z.ZodString;
         permittedSubcommandPaths: z.ZodArray<z.ZodArray<z.ZodString>>;
+        permittedEnvironmentKeys: z.ZodArray<z.ZodString>;
         cwd: z.ZodString;
         artifacts: z.ZodRecord<z.ZodString, z.ZodString>;
         maxElapsedMs: z.ZodInt;
@@ -110,3 +112,42 @@ export declare const CommandTargetPolicy: z.ZodObject<{
 }, z.core.$strict>;
 export type CommandTargetAuthorization = z.infer<typeof CommandTargetAuthorization>;
 export type CommandTargetPolicy = z.infer<typeof CommandTargetPolicy>;
+/**
+ * One authorized tool server, AD-35's mapping for the `mcp` mechanism.
+ *
+ * Keyed by `interfaceId` alone. A `cli` authorization is keyed by
+ * `(interfaceId, executable)` because `CommandInvocation` is declared per
+ * operation and one interface may name two executables. A tool session has no
+ * such split: it is opened against one server and every tool it offers belongs
+ * to that server, so the interface identifier is the server identity, which is
+ * how the HTTP authorization is keyed too.
+ *
+ * Two of the eight fields are authorization-scoped, `interfaceId` and `tools`.
+ * The other six are what an authorized call runs with, the way `cwd`,
+ * `artifacts`, and the two caps sit on a command authorization without adding
+ * a denial of their own.
+ */
+export declare const McpTargetAuthorization: z.ZodObject<{
+    interfaceId: z.ZodString;
+    target: z.ZodString;
+    targetArgs: z.ZodArray<z.ZodString>;
+    tools: z.ZodArray<z.ZodString>;
+    cwd: z.ZodString;
+    serverEnvironment: z.ZodRecord<z.ZodString, z.ZodString>;
+    maxElapsedMs: z.ZodInt;
+    maxOutputBytes: z.ZodInt;
+}, z.core.$strict>;
+export declare const McpTargetPolicy: z.ZodObject<{
+    authorizations: z.ZodArray<z.ZodObject<{
+        interfaceId: z.ZodString;
+        target: z.ZodString;
+        targetArgs: z.ZodArray<z.ZodString>;
+        tools: z.ZodArray<z.ZodString>;
+        cwd: z.ZodString;
+        serverEnvironment: z.ZodRecord<z.ZodString, z.ZodString>;
+        maxElapsedMs: z.ZodInt;
+        maxOutputBytes: z.ZodInt;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type McpTargetAuthorization = z.infer<typeof McpTargetAuthorization>;
+export type McpTargetPolicy = z.infer<typeof McpTargetPolicy>;

package/dist/core/schemas/probe-policy.js

@@ -1,7 +1,7 @@
 /** AD-35's default-deny target authorization, as a declared mapping. */
 import { z } from 'zod';
 import { HttpMethod } from './interface.js';
-import { Identifier } from './primitives.js';
+import { EnvironmentKeyName, Identifier, KeyName, ToolName, } from './primitives.js';
 /**
  * One authorized target. AD-35: "An adapter denies by default and permits only
  * what that mapping names." Every field is required and none has a default:
@@ -54,6 +54,12 @@ export const CommandTargetAuthorization = z.strictObject({
         .array(z.array(Identifier))
         .min(1)
         .describe('The exact subcommand paths this authorization allows, compared literally the way AD-40 compares them. An empty inner array authorizes invoking target with no subcommand. A path the request declares that matches none of these is denied before target is ever spawned, the same role methods plays on the HTTP side.'),
+    permittedEnvironmentKeys: z
+        .array(EnvironmentKeyName)
+        .refine((keys) => !keys.some((key) => key.toUpperCase() === 'PATH'), {
+        message: 'PATH cannot be permitted: target may name a bare command, and a declared PATH would then choose which binary runs',
+    })
+        .describe('The environment keys a request may carry into the process. `CommandProbeRequest.channels.environment` is declared by the contract author, and this is where the operator bounds it: a key absent from this list is denied before target is ever spawned, the same role permittedSubcommandPaths plays for a subcommand. An empty array is legal and permits no declared key, which is the default-deny base case. PATH is refused outright, because target may be "a name the adapter resolves through its own PATH" and the child environment is what resolves it: permitting PATH would hand executable selection to the contract author, which is the direction AD-35 exists to prevent. That refusal is narrow and covers executable selection alone. A key such as LD_PRELOAD or NODE_OPTIONS injects into the binary the mapping already chose, and this list is what keeps such a key out: naming one here is a deliberate act. The adapter refuses PATH again at its own boundary, since nothing in this package parses this policy and a refinement leaves no trace in the TypeScript type. The adapter\'s own PATH reaches the child from the process the mapping launched, under AD-18.'),
     cwd: z
         .string()
         .min(1)
@@ -75,3 +81,57 @@ export const CommandTargetPolicy = z.strictObject({
         .array(CommandTargetAuthorization)
         .describe('An empty array is legal and authorizes nothing, the same default-deny base case as ProbeTargetPolicy.'),
 });
+/**
+ * One authorized tool server, AD-35's mapping for the `mcp` mechanism.
+ *
+ * Keyed by `interfaceId` alone. A `cli` authorization is keyed by
+ * `(interfaceId, executable)` because `CommandInvocation` is declared per
+ * operation and one interface may name two executables. A tool session has no
+ * such split: it is opened against one server and every tool it offers belongs
+ * to that server, so the interface identifier is the server identity, which is
+ * how the HTTP authorization is keyed too.
+ *
+ * Two of the eight fields are authorization-scoped, `interfaceId` and `tools`.
+ * The other six are what an authorized call runs with, the way `cwd`,
+ * `artifacts`, and the two caps sit on a command authorization without adding
+ * a denial of their own.
+ */
+export const McpTargetAuthorization = z.strictObject({
+    interfaceId: Identifier.describe('The logical interface identifier the contract names, which for this mechanism is the server identity. This mapping is where it becomes a launchable server, outside the contract.'),
+    target: z
+        .string()
+        .min(1)
+        .describe('The real, spawnable command that starts the server: an absolute path, or a name the adapter resolves through its own PATH. Never taken from the contract, which never carries one (AD-35).'),
+    targetArgs: z
+        .array(z.string())
+        .describe('The argument vector target is launched with, passed as an array so no value is ever concatenated into a shell string. Empty is legal and launches target with no arguments.'),
+    tools: z
+        .array(ToolName)
+        .min(1)
+        .describe("The tools this authorization permits, in the server's own spelling, compared literally. A toolName the request names that is absent from this list is denied before the server process starts, the same role permittedSubcommandPaths plays on the command side. That draws AD-35's disclosure boundary around the tool as well as the server: a tool the list omits is unreachable through this adapter even when the server publishes it."),
+    cwd: z
+        .string()
+        .min(1)
+        .describe('The working directory the server runs from. Declared rather than inherited from the adapter process, so a server resolving a relative fixture path resolves it against a directory the mapping names.'),
+    serverEnvironment: z
+        .record(KeyName, z.string())
+        .describe("The environment the server process is launched with, over a base of the host's own PATH so a target naming a bare command still resolves; a declared PATH key wins over that default. A tool call's only channel is its arguments, so a server needing a credential has nowhere else to receive one, and port-messages.ts places that material here: authorization material is the adapter's, supplied by the same mapping that authorizes the target (AD-18)."),
+    maxElapsedMs: z
+        .int()
+        .min(1)
+        .max(2_147_483_647)
+        .describe('Wall-clock budget for the whole port invocation: server launch, the initialize handshake, the tool call, and teardown. A handshake that never completes and a tool call that never answers are the same event to the caller, and both throw budget-exhausted. Bounded above by the largest delay a timer accepts: a larger value is silently clamped to one millisecond, which turns a generous budget into an immediate cap.'),
+    maxOutputBytes: z
+        .int()
+        .min(1)
+        .describe("Applies independently to the bytes the server writes on stdout, which carry the tool result, and to the bytes it writes on its own stderr, which MCP's stdio transport reserves for logging. The first stream to cross it tears the session down with budget-exhausted."),
+});
+export const McpTargetPolicy = z.strictObject({
+    authorizations: z
+        .array(McpTargetAuthorization)
+        .refine((authorizations) => new Set(authorizations.map((each) => each.interfaceId)).size ===
+        authorizations.length, {
+        message: 'two authorizations name one interfaceId, so which server the interface resolves to would depend on which tool was asked for',
+    })
+        .describe('An empty array is legal and authorizes nothing, the same default-deny base case as ProbeTargetPolicy. One entry per interfaceId: the interface identifier is the server identity for this mechanism, so a second entry naming it could point one logical interface at a second binary. That is the difference from CommandTargetPolicy, whose entries are keyed by (interfaceId, executable) and so cannot disagree about what runs.'),
+});

package/dist/core/schemas/probe.d.ts

@@ -13,7 +13,7 @@ export declare const ProbeClass: z.ZodEnum<{
     gameability: "gameability";
     "zero-action": "zero-action";
 }>;
-/** the prior art's six-field seeded defect, carried unchanged. */
+/** AD-9's seeded defect: the prior art's six fields, plus the nullable `manifestationWitness` a six-field defect round-trips through. */
 export declare const Defect: z.ZodObject<{
     defectId: z.ZodString;
     behaviorId: z.ZodString;
@@ -65,10 +65,53 @@ export declare const Defect: z.ZodObject<{
             }, z.core.$strict>, z.ZodObject<{
                 kind: z.ZodLiteral<"absent">;
             }, z.core.$strict>], "kind">;
+        }, z.core.$strict>, z.ZodObject<{
+            arguments: z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>;
         }, z.core.$strict>]>;
         relation: z.ZodType<import("./expression.ts").Expression, unknown, z.core.$ZodTypeInternals<import("./expression.ts").Expression, unknown>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+/**
+ * The probe's current schema version. `EVAL_CONTRACT_SCHEMA_VERSION` is the
+ * same thing for the eval contract.
+ *
+ * It exists for the reason that one does: `lineage.ts` keeps the field a plain
+ * integer so a stale artifact fails as AD-28's `schema-version-mismatch` rather
+ * than as an anonymous parse error, which puts the comparison on the reader.
+ * `compile` is that reader for a contract. A probe has two in this pipeline and
+ * both compare against this constant: `planPreflight` before it plans a leg,
+ * and `score` before it seals the probe. An unequal stamp leaves by the fault
+ * path rather than being read leniently.
+ *
+ * A third reader exists for a caller outside this package.
+ * `validateLineageChain` takes an `acceptedSchemaVersion` and raises the same
+ * code over a presented chain, and `Probe` carries lineage, so a caller who
+ * presents one gets the comparison there. It words the fault its own way, which
+ * is why the two spellings of `schema-version-mismatch` in this tree are not a
+ * drift.
+ *
+ * It is also the single place the number is written. The committed
+ * worked-example chains build their probes from it and `check:doc-claims` reads
+ * it to hold the published sentence that names it, where the number was a
+ * literal in three places that could disagree in silence.
+ */
+export declare const PROBE_SCHEMA_VERSION = 5;
+/**
+ * Why a stale probe stamp is a rejection, in the words the fault carries.
+ *
+ * One string for both readers. Two copies of a sentence this long disagree in
+ * silence exactly as the number did before `PROBE_SCHEMA_VERSION` existed, and
+ * it lives here because this is where a version bump is one edit.
+ *
+ * It splits the shapes by branch, because a clean control carries neither a
+ * `defectSignature` nor a manifestation witness: the signature is declared on
+ * the seeded branch below and a witness hangs off a `Defect`, which that branch
+ * bounds at zero. What every probe carries is the qualification record, whose
+ * arrival on both branches is what made the 1 to 2 bump breaking. A clean
+ * control is the probe a reader is most likely to meet this message with, so
+ * naming a field it does not have would be the wrong half to lead with.
+ */
+export declare const PROBE_SCHEMA_VERSION_CONSEQUENCE: string;
 /**
  * The prior art's `expectedClean` conditional, re-expressed as a discriminated
  * union per AD-13 (a boolean literal discriminator parses on this pin,
@@ -270,6 +313,8 @@ export declare const Probe: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 }, z.core.$strict>, z.ZodObject<{
                     kind: z.ZodLiteral<"absent">;
                 }, z.core.$strict>], "kind">;
+            }, z.core.$strict>, z.ZodObject<{
+                arguments: z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>;
             }, z.core.$strict>]>;
             relation: z.ZodType<import("./expression.ts").Expression, unknown, z.core.$ZodTypeInternals<import("./expression.ts").Expression, unknown>>;
         }, z.core.$strict>>;
@@ -466,6 +511,8 @@ export declare const Probe: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 }, z.core.$strict>, z.ZodObject<{
                     kind: z.ZodLiteral<"absent">;
                 }, z.core.$strict>], "kind">;
+            }, z.core.$strict>, z.ZodObject<{
+                arguments: z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>;
             }, z.core.$strict>]>;
             relation: z.ZodType<import("./expression.ts").Expression, unknown, z.core.$ZodTypeInternals<import("./expression.ts").Expression, unknown>>;
         }, z.core.$strict>>;
@@ -548,13 +595,20 @@ export declare const Probe: z.ZodDiscriminatedUnion<[z.ZodObject<{
                             "type-violating": "type-violating";
                         }>;
                     }, z.core.$strict>]>>>;
+                    arguments: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        literal: z.ZodType<import("./primitives.ts").JsonValue, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonValue, unknown>>;
+                    }, z.core.$strict>, z.ZodObject<{
+                        matcher: z.ZodEnum<{
+                            any: "any";
+                            "type-violating": "type-violating";
+                        }>;
+                    }, z.core.$strict>]>>>;
                 }, z.core.$strict>;
             }, z.core.$strict>;
             predicate: z.ZodType<import("./expression.ts").Expression, unknown, z.core.$ZodTypeInternals<import("./expression.ts").Expression, unknown>>;
         }, z.core.$strict>;
         interfaceKind: z.ZodEnum<{
             api: "api";
-            mcp: "mcp";
             web: "web";
         }>;
         method: z.ZodEnum<{
@@ -645,6 +699,14 @@ export declare const Probe: z.ZodDiscriminatedUnion<[z.ZodObject<{
                             "type-violating": "type-violating";
                         }>;
                     }, z.core.$strict>]>>>;
+                    arguments: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        literal: z.ZodType<import("./primitives.ts").JsonValue, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonValue, unknown>>;
+                    }, z.core.$strict>, z.ZodObject<{
+                        matcher: z.ZodEnum<{
+                            any: "any";
+                            "type-violating": "type-violating";
+                        }>;
+                    }, z.core.$strict>]>>>;
                 }, z.core.$strict>;
             }, z.core.$strict>;
             predicate: z.ZodType<import("./expression.ts").Expression, unknown, z.core.$ZodTypeInternals<import("./expression.ts").Expression, unknown>>;
@@ -654,6 +716,98 @@ export declare const Probe: z.ZodDiscriminatedUnion<[z.ZodObject<{
             executable: z.ZodString;
             subcommandPath: z.ZodArray<z.ZodString>;
         }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        observableChannel: z.ZodEnum<{
+            artifact: "artifact";
+            "call-inputs": "call-inputs";
+            "exit-code": "exit-code";
+            "response-body": "response-body";
+            "response-headers": "response-headers";
+            "response-status": "response-status";
+            stderr: "stderr";
+            stdout: "stdout";
+        }>;
+        condition: z.ZodObject<{
+            selector: z.ZodObject<{
+                inputBinding: z.ZodObject<{
+                    path: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        literal: z.ZodType<import("./primitives.ts").JsonValue, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonValue, unknown>>;
+                    }, z.core.$strict>, z.ZodObject<{
+                        matcher: z.ZodEnum<{
+                            any: "any";
+                            "type-violating": "type-violating";
+                        }>;
+                    }, z.core.$strict>]>>>;
+                    query: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        literal: z.ZodType<import("./primitives.ts").JsonValue, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonValue, unknown>>;
+                    }, z.core.$strict>, z.ZodObject<{
+                        matcher: z.ZodEnum<{
+                            any: "any";
+                            "type-violating": "type-violating";
+                        }>;
+                    }, z.core.$strict>]>>>;
+                    header: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        literal: z.ZodType<import("./primitives.ts").JsonValue, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonValue, unknown>>;
+                    }, z.core.$strict>, z.ZodObject<{
+                        matcher: z.ZodEnum<{
+                            any: "any";
+                            "type-violating": "type-violating";
+                        }>;
+                    }, z.core.$strict>]>>>;
+                    body: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        literal: z.ZodType<import("./primitives.ts").JsonValue, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonValue, unknown>>;
+                    }, z.core.$strict>, z.ZodObject<{
+                        matcher: z.ZodEnum<{
+                            any: "any";
+                            "type-violating": "type-violating";
+                        }>;
+                    }, z.core.$strict>]>>>;
+                    argument: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        literal: z.ZodType<import("./primitives.ts").JsonValue, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonValue, unknown>>;
+                    }, z.core.$strict>, z.ZodObject<{
+                        matcher: z.ZodEnum<{
+                            any: "any";
+                            "type-violating": "type-violating";
+                        }>;
+                    }, z.core.$strict>]>>>;
+                    option: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        literal: z.ZodType<import("./primitives.ts").JsonValue, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonValue, unknown>>;
+                    }, z.core.$strict>, z.ZodObject<{
+                        matcher: z.ZodEnum<{
+                            any: "any";
+                            "type-violating": "type-violating";
+                        }>;
+                    }, z.core.$strict>]>>>;
+                    environment: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        literal: z.ZodType<import("./primitives.ts").JsonValue, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonValue, unknown>>;
+                    }, z.core.$strict>, z.ZodObject<{
+                        matcher: z.ZodEnum<{
+                            any: "any";
+                            "type-violating": "type-violating";
+                        }>;
+                    }, z.core.$strict>]>>>;
+                    stdin: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        literal: z.ZodType<import("./primitives.ts").JsonValue, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonValue, unknown>>;
+                    }, z.core.$strict>, z.ZodObject<{
+                        matcher: z.ZodEnum<{
+                            any: "any";
+                            "type-violating": "type-violating";
+                        }>;
+                    }, z.core.$strict>]>>>;
+                    arguments: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        literal: z.ZodType<import("./primitives.ts").JsonValue, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonValue, unknown>>;
+                    }, z.core.$strict>, z.ZodObject<{
+                        matcher: z.ZodEnum<{
+                            any: "any";
+                            "type-violating": "type-violating";
+                        }>;
+                    }, z.core.$strict>]>>>;
+                }, z.core.$strict>;
+            }, z.core.$strict>;
+            predicate: z.ZodType<import("./expression.ts").Expression, unknown, z.core.$ZodTypeInternals<import("./expression.ts").Expression, unknown>>;
+        }, z.core.$strict>;
+        interfaceKind: z.ZodLiteral<"mcp">;
+        toolName: z.ZodString;
     }, z.core.$strict>]>>;
 }, z.core.$strict>], "expectedClean">;
 export type Probe = z.infer<typeof Probe>;

package/dist/core/schemas/probe.js

@@ -20,7 +20,7 @@ export const PROBE_CLASSES = [
     'canary',
 ];
 export const ProbeClass = z.enum(PROBE_CLASSES);
-/** the prior art's six-field seeded defect, carried unchanged. */
+/** AD-9's seeded defect: the prior art's six fields, plus the nullable `manifestationWitness` a six-field defect round-trips through. */
 export const Defect = z.strictObject({
     defectId: DefectId,
     behaviorId: BehaviorId.describe('The behaviour this defect breaks. AD-9 also puts a behaviour on the probe itself and this schema carries both; that the two may disagree is a cross-field rule with no AD-5 code and is left unenforced in v0 rather than silently refined here.'),
@@ -48,6 +48,49 @@ const probeCommonFields = {
     rationale: z.string().min(1),
     qualification: ProbeQualification.describe('AD-9\'s qualification record: which of the five routes earned this probe its ground truth, and the evidence that route demands. Required on every branch and on every class, canaries included, because AD-9 closes with "an unqualified probe cannot enter a sealed set" and spells a route for all five kinds. That the route is compatible with this probe\'s class and `expectedClean` flag is a cross-field rule the export cannot carry; the corpus qualification gate enforces it and returns a reason code. Required, not optional, which with `defectSignature` below makes the probe\'s `schemaVersion` 1 -> 2 BREAKING bump under AD-11, whose rule is that "adding an optional field is a `schemaVersion` bump recorded in the field\'s own description; removing or retyping is breaking". This field is on both branches, so it alone is what stops every version-1 probe from parsing.'),
 };
+/**
+ * The probe's current schema version. `EVAL_CONTRACT_SCHEMA_VERSION` is the
+ * same thing for the eval contract.
+ *
+ * It exists for the reason that one does: `lineage.ts` keeps the field a plain
+ * integer so a stale artifact fails as AD-28's `schema-version-mismatch` rather
+ * than as an anonymous parse error, which puts the comparison on the reader.
+ * `compile` is that reader for a contract. A probe has two in this pipeline and
+ * both compare against this constant: `planPreflight` before it plans a leg,
+ * and `score` before it seals the probe. An unequal stamp leaves by the fault
+ * path rather than being read leniently.
+ *
+ * A third reader exists for a caller outside this package.
+ * `validateLineageChain` takes an `acceptedSchemaVersion` and raises the same
+ * code over a presented chain, and `Probe` carries lineage, so a caller who
+ * presents one gets the comparison there. It words the fault its own way, which
+ * is why the two spellings of `schema-version-mismatch` in this tree are not a
+ * drift.
+ *
+ * It is also the single place the number is written. The committed
+ * worked-example chains build their probes from it and `check:doc-claims` reads
+ * it to hold the published sentence that names it, where the number was a
+ * literal in three places that could disagree in silence.
+ */
+export const PROBE_SCHEMA_VERSION = 5;
+/**
+ * Why a stale probe stamp is a rejection, in the words the fault carries.
+ *
+ * One string for both readers. Two copies of a sentence this long disagree in
+ * silence exactly as the number did before `PROBE_SCHEMA_VERSION` existed, and
+ * it lives here because this is where a version bump is one edit.
+ *
+ * It splits the shapes by branch, because a clean control carries neither a
+ * `defectSignature` nor a manifestation witness: the signature is declared on
+ * the seeded branch below and a witness hangs off a `Defect`, which that branch
+ * bounds at zero. What every probe carries is the qualification record, whose
+ * arrival on both branches is what made the 1 to 2 bump breaking. A clean
+ * control is the probe a reader is most likely to meet this message with, so
+ * naming a field it does not have would be the wrong half to lead with.
+ */
+export const PROBE_SCHEMA_VERSION_CONSEQUENCE = 'since the stamp says which shapes the probe was authored against: the ' +
+    'qualification record on every probe, and the witness legs and the defect ' +
+    'signature grammar on a seeded one';
 /**
  * The prior art's `expectedClean` conditional, re-expressed as a discriminated
  * union per AD-13 (a boolean literal discriminator parses on this pin,
@@ -82,5 +125,5 @@ export const Probe = z
 ])
     .meta({
     id: 'Probe',
-    description: "One corpus probe. Succeeds the prior-art `h0-ground-truth` schema per AD-24, carrying its system identifier, implementation digest, `expectedClean` flag, seeded defects, and rationale, and adding AD-9's probe class and AD-9's per-probe artifact and commit digests. Divergences: `implementationSha` becomes `implementationDigest`, `taskId` does not survive because the probe pins what it describes by digest, and `expectedGate` does not survive because AD-40 makes detection a signature match rather than a verdict comparison and AD-7 keeps comparisons inside the dominance vector, so carrying an expected gate would invite a comparison the architecture forbids. Two constructions landed here together under one BREAKING `schemaVersion` bump: AD-9's per-class QUALIFICATION record, as a five-route tagged union required on every branch, and AD-40's machine-readable DEFECT SIGNATURE on the `expectedClean: false` branch, carrying the interface kind, the home operation as a method and a path template, the observable channel, and the discriminating condition. Both are required rather than optional, which is what makes the bump breaking under AD-11: every corpus written against version 1 fails to parse. Version 3 opened the signature to a second interface kind: it is a union on `interfaceKind`, where the `cli` branch declares a logical invocation in place of a method and a path template, and the selector's input binding carries the four command channels beside the four transport ones. What the schema still does not decide is stated rather than hidden. AD-9's \"an unqualified probe cannot enter a sealed set\" is a corpus-construction invariant enforced by the qualification gate in `core/score/qualification.ts`, not by this schema: all eight class-and-`expectedClean` pairings parse, a route incompatible with the pair parses, and a signature-less non-canary parses, each so the gate can return a reason code carrying an artifact path instead of an anonymous parse failure. The constraint ledger carries both gaps.",
+    description: "One corpus probe. Succeeds the prior-art `h0-ground-truth` schema per AD-24, carrying its system identifier, implementation digest, `expectedClean` flag, seeded defects, and rationale, and adding AD-9's probe class and AD-9's per-probe artifact and commit digests. Divergences: `implementationSha` becomes `implementationDigest`, `taskId` does not survive because the probe pins what it describes by digest, and `expectedGate` does not survive because AD-40 makes detection a signature match rather than a verdict comparison and AD-7 keeps comparisons inside the dominance vector, so carrying an expected gate would invite a comparison the architecture forbids. Two constructions landed here together under one BREAKING `schemaVersion` bump: AD-9's per-class QUALIFICATION record, as a five-route tagged union required on every branch, and AD-40's machine-readable DEFECT SIGNATURE on the `expectedClean: false` branch, carrying the interface kind, the home operation by its transport identity, the observable channel, and the discriminating condition. Both are required rather than optional, which is what makes the bump breaking under AD-11: every corpus written against version 1 fails to parse. Version 3 opened the signature to a second interface kind: it is a union on `interfaceKind`, where the `cli` branch declares a logical invocation in place of a method and a path template, and the selector's input binding carries the four command channels beside the four transport ones. Version 4 is a BREAKING bump on the witness side: a manifestation witness's `inputs` gained a third leg shape over a tool call's arguments, so a witness leg against a tool call is expressible; every version-3 probe's own bytes still parse against it. Version 5 opened the signature to a third kind and closed both gaps version 4 left. `DefectSignature` gains a tool-call branch declaring the published tool name, which is the transport identity AD-40 resolves an mcp signature against, and the api-shaped branch narrows to `api` and `web`, so a signature carrying `mcp` beside a method and a path template stops parsing. The selector's input binding gains a ninth `arguments` channel on the same required-and-nullable terms as the other eight, so a version-3 or version-4 probe declaring eight channels stops parsing too. The signature is therefore three branch shapes rather than one, each declaring its own kind's transport identity: a method and a path template, a logical invocation, or a published tool name. What the schema still does not decide is stated rather than hidden. AD-9's \"an unqualified probe cannot enter a sealed set\" is a corpus-construction invariant enforced by the qualification gate in `core/score/qualification.ts`, not by this schema: all eight class-and-`expectedClean` pairings parse, a route incompatible with the pair parses, and a signature-less non-canary parses, each so the gate can return a reason code carrying an artifact path instead of an anonymous parse failure. The constraint ledger carries both gaps.",
 });

package/dist/core/schemas/sealed-run-record.d.ts

@@ -190,10 +190,14 @@ export type OracleDisposition = z.infer<typeof OracleDisposition>;
  * A flat map would break pointer addressing: AD-26 keys `call-inputs` by
  * transport channel, so a pointer like
  * `/interactions/write/call-inputs/body/title` needs that segment to resolve
- * against. A four-key strict object rather than a record over the transport
- * enum, for the same reason as `RequestShape` and `InputBinding`: a record
- * demands every enum member at parse time, but a real observation binds only
- * a subset.
+ * against. A strict object keyed by channel rather than a record over the
+ * channel enum, for the same reason as `RequestShape` and `InputBinding`: a
+ * record demands every enum member at parse time, and a real observation binds
+ * only a subset.
+ *
+ * One key per member of `INPUT_CHANNELS`, in the order the vocabulary spells
+ * them. A loop over that vocabulary indexes this shape directly, so the two
+ * have to stay the same width.
  */
 export declare const ObservedCallInputs: z.ZodObject<{
     path: z.ZodNullable<z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>>;
@@ -204,6 +208,7 @@ export declare const ObservedCallInputs: z.ZodObject<{
     option: z.ZodNullable<z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>>;
     environment: z.ZodNullable<z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>>;
     stdin: z.ZodNullable<z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>>;
+    arguments: z.ZodNullable<z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>>;
 }, z.core.$strict>;
 /** the constraint identifier the ledger carries for the check below. */
 export declare const OBSERVATION_SEQUENCE_UNIQUE = "observation-sequence-unique";
@@ -233,6 +238,7 @@ export declare const Observation: z.ZodObject<{
         option: z.ZodNullable<z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>>;
         environment: z.ZodNullable<z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>>;
         stdin: z.ZodNullable<z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>>;
+        arguments: z.ZodNullable<z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>>;
     }, z.core.$strict>;
     responseBody: z.ZodNullable<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
     responseHeaders: z.ZodNullable<z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>>;
@@ -454,6 +460,7 @@ export declare const SealedRunRecord: z.ZodObject<{
             option: z.ZodNullable<z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>>;
             environment: z.ZodNullable<z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>>;
             stdin: z.ZodNullable<z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>>;
+            arguments: z.ZodNullable<z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>>;
         }, z.core.$strict>;
         responseBody: z.ZodNullable<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
         responseHeaders: z.ZodNullable<z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>>;
@@ -526,6 +533,5 @@ export declare const SealedRunRecord: z.ZodObject<{
         truncationBound: z.ZodNullable<z.ZodInt>;
         reportedIncomplete: z.ZodBoolean;
     }, z.core.$strict>;
-    invalidReason: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
 export type SealedRunRecord = z.infer<typeof SealedRunRecord>;

package/dist/core/schemas/sealed-run-record.js

@@ -135,10 +135,14 @@ export const OracleDisposition = z.strictObject({
  * A flat map would break pointer addressing: AD-26 keys `call-inputs` by
  * transport channel, so a pointer like
  * `/interactions/write/call-inputs/body/title` needs that segment to resolve
- * against. A four-key strict object rather than a record over the transport
- * enum, for the same reason as `RequestShape` and `InputBinding`: a record
- * demands every enum member at parse time, but a real observation binds only
- * a subset.
+ * against. A strict object keyed by channel rather than a record over the
+ * channel enum, for the same reason as `RequestShape` and `InputBinding`: a
+ * record demands every enum member at parse time, and a real observation binds
+ * only a subset.
+ *
+ * One key per member of `INPUT_CHANNELS`, in the order the vocabulary spells
+ * them. A loop over that vocabulary indexes this shape directly, so the two
+ * have to stay the same width.
  */
 export const ObservedCallInputs = z.strictObject({
     path: JsonObjectValue.nullable(),
@@ -149,6 +153,7 @@ export const ObservedCallInputs = z.strictObject({
     option: JsonObjectValue.nullable(),
     environment: JsonObjectValue.nullable(),
     stdin: JsonObjectValue.nullable(),
+    arguments: JsonObjectValue.nullable().describe("AD-26's `arguments` channel, the one channel a tool call accepts input on. Its arrival retypes this shape from eight keys to nine, which AD-11 calls breaking and which moves the Sealed Run Record's `schemaVersion` from 4 to 5: a version-4 record declares no `arguments` key and fails to parse against version 5. A name-to-value map on `responseHeaders`' terms, since a pointer descends INTO the channel to address one argument. `null` on an observation that exercised no tool call, which is what every channel here already spells for a channel nothing was sent on."),
 });
 /** the constraint identifier the ledger carries for the check below. */
 export const OBSERVATION_SEQUENCE_UNIQUE = 'observation-sequence-unique';
@@ -172,13 +177,13 @@ export const Observation = z.strictObject({
         .describe("AD-23: `baseline` for a pre-canned or deterministic test, `evaluator-chosen` for an action the evaluator selected. The distinction is the one the product's central finding rests on: what a sealed evaluator detects beyond the pre-canned baseline. It lives on the observation, never on the finding."),
     principal: Identifier.nullable().describe("The declared principal the harness acted as, or `null` where the run named none. Owed item 3's other half: a `{ principal }` input binding is presence-only by construction, since the contract declares a name and the harness provisions the value, so without this field two steps of one operation binding `owner` and `other-user` both match every observation and both resolve `several`. That is exactly the act-as-A-read-as-B shape the two critical-severity cross-user behaviours need, and it was unscoreable while the record said nothing about which account was used. An opaque label carrying no account identifier or credential, on `testData.principals`' own AD-18 terms."),
     callInputs: ObservedCallInputs,
-    responseBody: JsonValue.nullable().describe('AD-26\'s `response-body` channel. The null branch is redundant against the value container, which already admits `null`; it is kept so all ten observation fields read the same way, and it means "no body observed" and "a body that was JSON null" are indistinguishable here, which is an accepted cost of one uniform spelling.'),
+    responseBody: JsonValue.nullable().describe('AD-26\'s `response-body` channel. The null branch is redundant against the value container, which already admits `null`; it is kept so every observation field reads the same way, and it means "no body observed" and "a body that was JSON null" are indistinguishable here, which is an accepted cost of one uniform spelling.'),
     responseHeaders: JsonObjectValue.nullable().describe('A name-to-value map, not the open value container. AD-26 gives `response-headers` a tail, so a pointer resolves INTO this channel; a scalar here would leave `/interactions/x/response-headers/Content-Type` addressing nothing. That is the difference from `responseBody`, where a scalar or an array is a legitimate body and the open container is correct.'),
     responseStatus: z
         .int()
         .min(0)
         .nullable()
-        .describe('Deliberately not bounded to a protocol range. A negative status is meaningless and excluded, but the upper end is left open: AD-19 declares four interface kinds and v0 rejects three of them at compile time under `unsupported-interface-kind`, so bounding this to HTTP would encode a protocol assumption the artifact outlives. `null` where the channel does not apply.'),
+        .describe('Deliberately not bounded to a protocol range. A negative status is meaningless and excluded, but the upper end is left open: AD-19 declares four interface kinds and not all of them speak HTTP, so bounding this to HTTP would encode a protocol assumption the artifact outlives. `null` where the channel does not apply.'),
     stdout: ProbeObservedBody.describe('AD-26\'s `stdout` channel, tagged rather than a bare string. An operation may nominate standard output as the channel its response descriptor describes, in which case a pointer descends into it, and an untagged string could not tell output that was JSON from output that was only ever text. `{ "kind": "absent" }` is the channel a run did not observe.'),
     stderr: ProbeObservedBody.describe("AD-26's `stderr` channel, tagged on the same terms as `stdout`."),
     exitCode: z
@@ -243,6 +248,14 @@ export const RUN_MODES = ['production', 'contract-scoring'];
 export const RunMode = z.enum(RUN_MODES);
 export const SealedRunRecord = z
     .strictObject({
+    // A record carries lineage fields and nothing here ever puts one in a
+    // chain. `validateLineageChain` has no caller in this package at all: it
+    // is exported for consumers, and `score.ts` carries the reasoning for
+    // why score deliberately does not call it. That is what lets a field be
+    // added or removed here without moving any caller's scoring version,
+    // since a chain digests each member whole. A consumer who chains records
+    // makes that false for themselves, and the version-6 changelog's
+    // comparability claim stops holding for them.
     ...lineageFields,
     runId: z
         .string()
@@ -256,7 +269,7 @@ export const SealedRunRecord = z
     trialIndex: z
         .int()
         .min(1)
-        .describe("Which trial this record is. AD-24 excludes the trial index from the Evaluator Configuration \"so trials pool into one scoring version\", which requires it somewhere else, and a Sealed Run Record is the only artifact carrying exactly one trial. One-based, matching the only instance that exists. AD-6's aggregate of trial count, invalidated attempts, and each attempt's reason is the Evidence Artifact's; asking one run to report its siblings is what no stage signature can do."),
+        .describe("Which trial this record is. AD-24 excludes the trial index from the Evaluator Configuration \"so trials pool into one scoring version\", which requires it somewhere else, and a Sealed Run Record is the only artifact carrying exactly one trial. One-based, matching the only instance that exists. AD-6's aggregate of trial count, invalidated attempts, and each attempt's reason is the Evidence Artifact's, computed by `score` over the trial set a caller assembles. The reducer keys an attempt by its position in that set, so this field is the caller's own bookkeeping and a label for a reader of one record."),
     contractDigest: Digest,
     sealedBriefDigest: Digest,
     evaluatorConfigurationDigest: Digest.describe('A bare digest rather than an `ArtifactReference`, and required on both this record and the isolation manifest. AD-32 requires the two to *agree*, and an `ArtifactReference` on one side against a bare digest on the other makes the comparison lopsided; AD-2 already has ingest receiving the Evaluator Configuration as its own input, so nothing needs resolving through a reference. The agreement itself is a cross-artifact rule no schema can see.'),
@@ -284,9 +297,8 @@ export const SealedRunRecord = z
     isolationManifestArtifact: ArtifactReference,
     resourceUse: ResourceUse,
     evidenceDisclosure: EvidenceDisclosure,
-    invalidReason: z.string().nullable(),
 })
     .meta({
     id: 'SealedRunRecord',
-    description: "One sealed evaluator trial, as the caller presents it. Succeeds the prior-art `h0-run-result` schema per AD-24, keeping its run identifier, condition arm, findings, action-log reference, resource use, invalidation reason, evaluator recommendation as a closed enum, and per-finding confidence on a declared scale. Divergences: `condition` is demoted to the opaque `conditionArm`, `verdict` becomes `evaluatorRecommendation` without `NOT_APPLICABLE`, money is a decimal string, and `taskId`, `note`, and per-finding `actionIds` do not survive: the contract is pinned by `contractDigest`, an unstructured orchestrator annotation is the free-prose channel the Conventions close everywhere else, and two citation vocabularies on one finding is the ambiguity ADR-009 removed. The run MODE landed here as a required field under a BREAKING `schemaVersion` bump, which is where AD-21's \"fixed before ingest\" puts it; owed item 4 is now closed: mode enters AD-11's identity inputs as `ScoringVersionInputs`'s sixth field, and `core/score/ladder.ts` carries `ProductionAssessment`/`ContractAssessment` as the two assessment input types with their own total ladders. Observation ORDERING landed here too, under its own BREAKING `schemaVersion` bump: `sequence` is required and unique per record, closing owed item 2's ADR-006 gap, since array position was never a legal ordering. Version 4 opened the record to a system under test that runs behind a command: `callInputs` carries the four command channels beside the four transport ones, `stdout` and `stderr` are tagged rather than bare strings so a nominated output channel can be descended into, and `artifacts` records the files the run wrote, keyed by the identifier the operation declares.",
+    description: "One sealed evaluator trial, as the caller presents it. Succeeds the prior-art `h0-run-result` schema per AD-24, keeping its run identifier, condition arm, findings, action-log reference, resource use, evaluator recommendation as a closed enum, and per-finding confidence on a declared scale. Divergences: `condition` is demoted to the opaque `conditionArm`, `verdict` becomes `evaluatorRecommendation` without `NOT_APPLICABLE`, money is a decimal string, and `taskId`, `note`, per-finding `actionIds`, and the prior art's `invalidReason` do not survive: the contract is pinned by `contractDigest`, an unstructured orchestrator annotation is the free-prose channel the Conventions close everywhere else, and two citation vocabularies on one finding is the ambiguity ADR-009 removed. The run MODE landed here as a required field under a BREAKING `schemaVersion` bump, which is where AD-21's \"fixed before ingest\" puts it; owed item 4 is now closed: mode enters AD-11's identity inputs as `ScoringVersionInputs`'s sixth field, and `core/score/ladder.ts` carries `ProductionAssessment`/`ContractAssessment` as the two assessment input types with their own total ladders. Observation ORDERING landed here too, under its own BREAKING `schemaVersion` bump: `sequence` is required and unique per record, closing owed item 2's ADR-006 gap, since array position was never a legal ordering. Version 4 opened the record to a system under test that runs behind a command: `callInputs` carries the four command channels beside the four transport ones, `stdout` and `stderr` are tagged rather than bare strings so a nominated output channel can be descended into, and `artifacts` records the files the run wrote, keyed by the identifier the operation declares. Version 5 opened it to a tool call: `callInputs` carries a ninth `arguments` channel beside those eight, so what a tool call supplied has somewhere to live and a defect signature's selector filtering on that channel has something to read. A version-4 record declares eight call-input channels and fails to parse against version 5. Version 6 drops `invalidReason`, the prior art's run-level invalidation reason: nothing in this package ever read it, so a caller attesting that a run was invalid was ignored by every stage while the field looked like a supported channel. The attestation that works is `IsolationManifest.violation`, which `core/ingest` raises as an `isolation-manifest-violation` condition and which reaches the verdict basis, and AD-6's invalidating outcome states carry a failure the run itself produced. A version-5 record carrying `invalidReason` fails to parse against version 6.",
 });