eval-quality 0.1.0 → 0.3.0

package/dist/core/seal/derived-reference.js

@@ -1,8 +1,20 @@
-import { parseEvidenceTarget, resolveOperation, resolveStep, } from './plan-index.js';
+/**
+ * The derived-reference vocabulary (AD-16). Renders an evidence-target
+ * pointer, or a temporally-paired pair, as a description of the step's
+ * operation and selection predicate; the step's own identifier never appears.
+ * Resolves pointers through a `PlanIndex` into a phrase, kept apart from
+ * `plan-index.ts`'s resolving and `direction-prose.ts`'s relation templates.
+ */
+import { boundChannelsOf, isCommandOperation } from '../declared-inputs.js';
+import { StructuralFailure } from '../failure-codes.js';
+import { anyOperationOf, parseEvidenceTarget, resolveStep, } from './plan-index.js';
 function resolveEvidenceTarget(pointer, index) {
     const target = parseEvidenceTarget(pointer);
     const step = resolveStep(index, target.stepId);
-    const operation = resolveOperation(index, step.operationId);
+    const operation = anyOperationOf(index, step.operationId);
+    if (operation === undefined) {
+        throw new TypeError(`step names an operation the permitted interfaces do not declare: ${step.operationId}`);
+    }
     return { target, step, operation };
 }
 // ---- joining ---------------------------------------------------------
@@ -21,30 +33,31 @@ function joinWithAnd(items) {
 // ---- operation identity -----------------------------------------------
 // Humanizing a kebab-case operationId is injective on distinct ids, and
 // `buildPlanIndex` already rejects a duplicate `operationId` across
-// interfaces, so two resolved operations never share this phrase. `method`
-// and `pathTemplate` are never printed here: AD-16 withholds the operation
-// inventory from the brief.
+// interfaces, so two resolved operations never share this phrase. The
+// transport identity is never printed here, whichever kind it is: AD-16
+// withholds the operation inventory from the brief, so neither a method and a
+// path template nor an executable and a subcommand path reach an evaluator.
+//
+// The noun follows the kind. Calling a command an endpoint told the evaluator
+// something false about what it was reading, and the word is the only thing
+// this phrase says beyond the operation's own name.
 function operationReference(operation) {
-    return `the ${operation.operationId.split('-').join(' ')} endpoint`;
+    const name = operation.operationId.split('-').join(' ');
+    return isCommandOperation(operation)
+        ? `the ${name} command`
+        : `the ${name} endpoint`;
 }
 const ESCALATION_LEVELS = [
     'generic',
     'kind',
     'literal',
 ];
-const TRANSPORT_ORDER = [
-    'path',
-    'query',
-    'header',
-    'body',
-];
-// Sorted by transport channel in fixed order, then by key name, so this
+// Sorted by input channel in `INPUT_CHANNELS` order, then by key name, so this
 // never depends on a binding map's insertion order and the rendered prose
-// stays permutation-invariant.
+// stays permutation-invariant. `boundChannelsOf` supplies the channel order.
 function bindingEntries(step) {
     const entries = [];
-    for (const transportChannel of TRANSPORT_ORDER) {
-        const map = step.inputBinding[transportChannel];
+    for (const { channel: transportChannel, bound: map } of boundChannelsOf(step.inputBinding)) {
         if (map === null)
             continue;
         for (const key of Object.keys(map).sort()) {
@@ -83,22 +96,171 @@ function canonicalizeForDisplay(value) {
 function formatLiteral(literal) {
     return JSON.stringify(canonicalizeForDisplay(literal));
 }
-// Base rendering: `type-violating` always names the input malformed.
-// `any` and, at the 'generic' level, `literal` share the same generic wording
-// on purpose; the escalation ladder below tells them apart once two steps
-// would otherwise collide.
+// Base rendering, one arm per tagged form. `type-violating` always names the
+// input malformed. `any` and, at the 'generic' level, every other form share
+// the same generic wording on purpose; the escalation ladder below tells them
+// apart once two steps would otherwise collide.
+//
+// `captured` escalates to a real derived reference at the 'literal' rung: the
+// local phrase for the pointer's channel and tail, then the referenced step
+// rendered through `stepReferenceAtLevel`, which is the same phrase
+// `fullTargetPhrase` already prints for an evidence target. Naming the
+// referenced OPERATION alone was tried and dropped: two predecessors sharing
+// one operation and one body key then render identically, so two siblings
+// capturing from them collide at every rung and `renderStepReference` throws
+// out of `seal()` on a contract that compiles clean. Recursing into the
+// predecessor separates them by its own binding clause. Two predecessors that
+// are themselves irreducible still tie, and the throw there is correct: the
+// declared structure does not distinguish them, which is the same answer
+// `irreducibleCollisionPair` already gets. That throw is a coded
+// `StructuralFailure` under `irreducible-step-reference`, and it is
+// hoisted to compile time by `checkStepReferenceReducibility`, which runs this
+// same ladder and reports the same code before `seal` is ever called.
+//
+// It does NOT call `renderStepReference`, so none of that function's
+// constraints apply: no direction-scoped sibling list is consulted, so AD-16's
+// scoping stays intact, and there is no tie to throw on. A step identifier
+// never appears, which is the property AD-16 actually requires.
+//
+// `rendering` holds the steps already on the render path, and a capture back
+// into one of them falls back to the level-independent phrase. A fixed depth
+// bound was tried and dropped: at depth one, a two-link chain whose every link
+// is genuinely distinguishable still collides, because only the immediate
+// predecessor's binding shows and that is the half the two siblings share.
+// Following the chain as far as it goes is what separates them, and the
+// on-path set is what makes that terminate. Each recursion adds one step id, so
+// the depth is bounded by the plan; `plan-exceeds-scripting-bound` bounds that
+// too. Same guard the score module uses for an `after` chain, for the same
+// reason: `binding-cycle` rejects a capture cycle at compile time, so this only
+// covers a plan driven straight into the renderer.
+//
+// A pointer whose step or operation the index cannot resolve falls back to the
+// 'kind' phrase. `seal()` runs after `compile`, which rejects such a pointer
+// under `unreachable-check-evidence`, so this is a fallback for a
+// directly-driven caller and adds no throw path.
+//
+// One thing a grep for step identifiers will find and should not be surprised
+// by: `localTargetPhrase` prints the pointer's tail, and a response-body key
+// the author happened to name the same as a step prints with it. That is the
+// author's own declared key rather than a plan identifier, and it is what every
+// ordinary evidence target has always printed.
+//
+// `principal` tops out at the declared name, which AD-18 keeps an opaque label
+// and is therefore safe on the brief.
+// One or more entries of a step's clause that capture from the same earlier
+// step, rendered together so that step's phrase is expanded once. Expanding it
+// per entry made the clause's size multiply down a capture chain: a step with k
+// entries pointing at its predecessor expanded that predecessor k times, and the
+// predecessor did the same to its own, so a sixteen-step chain with four keys a
+// link produced a phrase past V8's maximum string length. Grouping makes the
+// clause linear in keys and reads better besides.
+//
+// Grouping alone bounds one axis of three, and the size is their product. The
+// other two are the number of DISTINCT predecessors a step references, which
+// doubles per level on a complete capture DAG, and the length of one step's own
+// clause text, which nothing bounds: `formatLiteral` prints a `JsonValue` with
+// no length cap and a binding channel is a record with a minimum of one entry
+// and no maximum. Measured on a sixteen-step complete DAG that passes every
+// plan-side check, the multiplier is 8,192, so a single 65,536-character
+// literal on the seed step, or two hundred ordinary forty-character ones,
+// reaches `RangeError: Invalid string length`.
+//
+// `budget` is what bounds all three at once. Each expansion spends the
+// characters it produced, and once the budget is gone a capture renders as the
+// level-independent phrase it already had. Every `stepReferenceAtLevel` call
+// from `renderStepReference` starts a fresh budget, so one sibling's expansion
+// never degrades another's and the distinctness test stays order-independent.
+//
+// The budget is charged after an expansion rather than before, so the bound is
+// the budget plus whatever one step's own clause text costs; a step binding a
+// single 200,000-character literal renders about 204,000. That is the point of
+// charging late: an expansion cannot be priced before its nested expansions are
+// known, and stopping the NEXT one is what keeps the product finite. Measured
+// on the sixteen-step complete DAG that reached `RangeError` before: 36 KB with
+// a minimal seed, 75 KB with two hundred forty-character literals, 135 KB with
+// a 65,536-character one, and, with a one-million-character literal on every one
+// of its fourteen nodes, 1,000,564. All in single-digit milliseconds. That last
+// row is the one that pins the bound: one literal's worth of overshoot rather
+// than fourteen, which is why the exhaustion test sits in the render pass below
+// rather than where the slots are built.
+//
+// A budget alone would couple things that have nothing to do with each other:
+// growing a literal on a step neither sibling references can starve the
+// expansion that separates them, so an unrelated field decides whether a
+// contract seals. `renderStepReference`'s retry at the ceiling is what removes
+// that, and it fires only when a collision came of a suppressed expansion. What
+// remains is the honest case: siblings the declared structure does not
+// distinguish still throw the precondition `TypeError`, which is the
+// pre-existing failure mode `deferred-work.md` already carries.
+// The ordinary limit, then the ceiling a starved render retries at. No
+// realistic contract reaches the first; only one that would otherwise fail to
+// render at all pays for the second.
+const RENDER_BUDGET_LIMITS = [100_000, 4_000_000];
+const newBudget = (limit) => ({
+    remaining: limit,
+    spent: false,
+});
+const unexpandedGroup = (group) => `the ${joinWithAnd(group.entries.map(entryName))} you obtained earlier`;
+function renderCaptureGroup(group, level, index, rendering, budget) {
+    const names = joinWithAnd(group.entries.map(entryName));
+    const locals = joinWithAnd(group.targets.map(localTargetPhrase));
+    const step = index.stepOf(group.stepId);
+    const operation = step === undefined ? undefined : anyOperationOf(index, step.operationId);
+    if (step === undefined || operation === undefined) {
+        return unexpandedGroup(group);
+    }
+    const source = stepReferenceAtLevel(step, operation, level, index, rendering, budget);
+    // Charged after the fact, so a nested expansion pays before its parent does
+    // and an inner blowup is what stops the outer one.
+    budget.remaining -= source.length;
+    return `the ${names} you obtained as ${locals} from ${source}`;
+}
+// Records that an expansion was suppressed, which is what `renderStepReference`
+// reads before deciding whether a collision is worth retrying at the ceiling.
+function exhausted(budget) {
+    if (budget.remaining > 0)
+        return false;
+    budget.spent = true;
+    return true;
+}
+// Whether this entry expands into a group, or renders as the level-independent
+// phrase on its own.
+function expandableCapture(entry, level, index, rendering, budget) {
+    if (level !== 'literal' || !('captured' in entry.value))
+        return null;
+    if (exhausted(budget))
+        return null;
+    const target = parseEvidenceTarget(entry.value.captured);
+    if (rendering.has(target.stepId))
+        return null;
+    const step = index.stepOf(target.stepId);
+    if (step === undefined)
+        return null;
+    return anyOperationOf(index, step.operationId) === undefined ? null : target;
+}
+// Renders one entry on its own. Every captured entry that expands lands in a
+// group instead, so the arm here is the level-independent fallback.
 function renderBindingValue(entry, level) {
     const name = entryName(entry);
-    if (isTypeViolating(entry.value)) {
-        return `a malformed ${name} value`;
+    const { value } = entry;
+    if ('matcher' in value) {
+        return value.matcher === 'type-violating'
+            ? `a malformed ${name} value`
+            : `the supplied ${name}`;
     }
-    if (level === 'generic' || 'matcher' in entry.value) {
+    if (level === 'generic') {
         return `the supplied ${name}`;
     }
+    if ('principal' in value) {
+        return `the ${name} of the ${value.principal} account`;
+    }
+    if ('captured' in value) {
+        return `the ${name} you obtained earlier`;
+    }
     if (level === 'kind') {
         return `the stated ${name}`;
     }
-    return `the ${name} ${formatLiteral(entry.value.literal)}`;
+    return `the ${name} ${formatLiteral(value.literal)}`;
 }
 // Every declared binding key escalates together: narrowing to only the
 // discriminating key would make one step's shown detail depend on which
@@ -108,13 +270,49 @@ function renderBindingValue(entry, level) {
 //
 // When a type-violating binding is present, the clause names only that one:
 // it is the semantically salient binding, matching AD-16's worked example.
-function bindingClause(step, level) {
+function bindingClause(step, level, index, rendering, budget) {
     const entries = bindingEntries(step);
     if (entries.length === 0)
         return null;
     const malformed = entries.filter((entry) => isTypeViolating(entry.value));
     const chosen = malformed.length > 0 ? malformed : entries;
-    return `with ${joinWithAnd(chosen.map((entry) => renderBindingValue(entry, level)))}`;
+    // Each expandable capture joins the group for the step it references, held
+    // at the position that step was first referenced from, so the clause's order
+    // still comes from `bindingEntries`'s sort rather than from a map's keys.
+    const slots = [];
+    const groups = new Map();
+    for (const entry of chosen) {
+        const target = expandableCapture(entry, level, index, rendering, budget);
+        if (target === null) {
+            slots.push(entry);
+            continue;
+        }
+        const existing = groups.get(target.stepId);
+        if (existing !== undefined) {
+            existing.entries.push(entry);
+            existing.targets.push(target);
+            continue;
+        }
+        const group = {
+            stepId: target.stepId,
+            entries: [entry],
+            targets: [target],
+        };
+        groups.set(target.stepId, group);
+        slots.push(group);
+    }
+    // Tested here rather than while the slots are built: a clause commits to its
+    // groups in one pass and renders them in the next, so an entry-time test let
+    // every group of an already-committed clause render in full, and the bound
+    // grew by the group count rather than by one expansion.
+    const phrases = slots.map((slot) => {
+        if (!('stepId' in slot))
+            return renderBindingValue(slot, level);
+        return exhausted(budget)
+            ? unexpandedGroup(slot)
+            : renderCaptureGroup(slot, level, index, rendering, budget);
+    });
+    return `with ${joinWithAnd(phrases)}`;
 }
 // Parenthesized rather than comma-joined onto the operation reference: a
 // step reference can itself be joined with other phrases at a higher level
@@ -122,9 +320,11 @@ function bindingClause(step, level) {
 // already carries its own internal ", and" separators. A second comma layer
 // on top would produce indistinguishable comma soup once two or more
 // phrases are joined.
-function stepReferenceAtLevel(step, operation, level) {
+function stepReferenceAtLevel(step, operation, level, index, rendering = new Set(), budget = newBudget(RENDER_BUDGET_LIMITS[0])) {
     const base = operationReference(operation);
-    const clause = bindingClause(step, level);
+    // The step being rendered joins the path before its own clause is built, so
+    // a self-capture falls back on the first hop.
+    const clause = bindingClause(step, level, index, new Set([...rendering, step.stepId]), budget);
     return clause === null ? base : `${base} (${clause})`;
 }
 /**
@@ -140,14 +340,42 @@ function stepReferenceAtLevel(step, operation, level) {
  * duplicate `stepId` check if two siblings still collide after full
  * escalation.
  */
-export function renderStepReference(step, operation, siblings) {
-    for (const level of ESCALATION_LEVELS) {
-        const phrases = siblings.map((sibling) => stepReferenceAtLevel(sibling, operation, level));
-        if (new Set(phrases).size === phrases.length) {
-            return stepReferenceAtLevel(step, operation, level);
+export function renderStepReference(step, operation, siblings, index) {
+    // Two passes over the ladder, at the ordinary budget and then at the ceiling.
+    // The retry fires only when every level collided AND some render had an
+    // expansion suppressed, which is what breaks the coupling the budget would
+    // otherwise introduce: without it, growing a literal on a step unrelated to
+    // either sibling can starve the expansion that separates them and make an
+    // otherwise-sealable contract throw. A collision with nothing suppressed is
+    // the declared structure's own tie, and a larger budget renders the same
+    // text, so that case leaves the loop rather than paying for a second pass.
+    for (const limit of RENDER_BUDGET_LIMITS) {
+        let starved = false;
+        for (const level of ESCALATION_LEVELS) {
+            const rendered = siblings.map((sibling) => {
+                const budget = newBudget(limit);
+                return {
+                    phrase: stepReferenceAtLevel(sibling, operation, level, index, new Set(), budget),
+                    spent: budget.spent,
+                };
+            });
+            const phrases = rendered.map((entry) => entry.phrase);
+            if (new Set(phrases).size === phrases.length) {
+                return stepReferenceAtLevel(step, operation, level, index, new Set(), newBudget(limit));
+            }
+            if (rendered.some((entry) => entry.spent))
+                starved = true;
         }
+        if (!starved)
+            break;
     }
-    throw new TypeError(`two or more steps invoking operation "${operation.operationId}" that this direction references render to the same derived reference even fully escalated; the declared structure does not distinguish them`);
+    // Coded rather than a bare `TypeError`. A contract reaching here passed
+    // every compile check and then failed at seal time with a stack trace, and
+    // the defect is an ordinary authoring fault: two steps the declared
+    // structure does not tell apart. `checkStepReferenceReducibility` runs this
+    // same ladder at compile time so the fault is reported before seal, and
+    // this throw is what it catches.
+    throw new StructuralFailure('irreducible-step-reference', `EvalContract.interactionPlan[operationId=${operation.operationId}]`, `two or more steps invoking operation "${operation.operationId}" that one direction references render to the same derived reference even fully escalated; the declared structure does not distinguish them (AD-16, AD-3)`);
 }
 function siblingsByOperation(resolved) {
     const map = new Map();
@@ -214,11 +442,25 @@ function localTargetPhrase(target) {
             return field !== null
                 ? `the ${field} field of its standard error`
                 : 'the standard error you obtained';
+        case 'artifact': {
+            if (target.artifactId === null) {
+                // Unreachable: `parseEvidenceTarget` sets this exactly when the
+                // channel is 'artifact'.
+                throw new TypeError('artifact evidence target names no artifact');
+            }
+            // The artifact is named for the same reason the transport channel
+            // is: two files can carry the same field name, and an evaluator
+            // reading "its findings field" twice cannot tell which file it
+            // means.
+            return field !== null
+                ? `the ${field} field of the ${target.artifactId} it wrote`
+                : `the ${target.artifactId} it wrote`;
+        }
     }
 }
-function fullTargetPhrase(resolved, siblingsOf) {
+function fullTargetPhrase(resolved, siblingsOf, index) {
     const local = localTargetPhrase(resolved.target);
-    const stepRef = renderStepReference(resolved.step, resolved.operation, siblingsOf(resolved.operation.operationId));
+    const stepRef = renderStepReference(resolved.step, resolved.operation, siblingsOf(resolved.operation.operationId), index);
     const preposition = resolved.target.channel === 'call-inputs' ? 'to' : 'from';
     return `${local} ${preposition} ${stepRef}`;
 }
@@ -228,7 +470,12 @@ function fullTargetPhrase(resolved, siblingsOf) {
 // 'b']`). Both would join to the same `".../a/b"` string, producing a false
 // tie in `sentFirstOrder` below.
 function channelSignature(target) {
-    return JSON.stringify([target.channel, target.transportChannel, target.tail]);
+    return JSON.stringify([
+        target.channel,
+        target.transportChannel,
+        target.artifactId,
+        target.tail,
+    ]);
 }
 // A total order over one pair, independent of argument order. The final
 // reference-comparison rung fires only on a genuine tie, such as the same
@@ -236,7 +483,7 @@ function channelSignature(target) {
 // never degenerates to argument order, since colliding same-operation
 // siblings already throw in `renderStepReference`, and different operations
 // always humanize to different names.
-function sentFirstOrder(a, b, siblingsOf) {
+function sentFirstOrder(a, b, siblingsOf, index) {
     const rank = (r) => r.target.channel === 'call-inputs' ? 0 : 1;
     const rankA = rank(a);
     const rankB = rank(b);
@@ -246,8 +493,8 @@ function sentFirstOrder(a, b, siblingsOf) {
     const signatureB = channelSignature(b.target);
     if (signatureA !== signatureB)
         return signatureA < signatureB ? [a, b] : [b, a];
-    const referenceA = renderStepReference(a.step, a.operation, siblingsOf(a.operation.operationId));
-    const referenceB = renderStepReference(b.step, b.operation, siblingsOf(b.operation.operationId));
+    const referenceA = renderStepReference(a.step, a.operation, siblingsOf(a.operation.operationId), index);
+    const referenceB = renderStepReference(b.step, b.operation, siblingsOf(b.operation.operationId), index);
     return referenceA <= referenceB ? [a, b] : [b, a];
 }
 // Two evidence targets whose steps are declared in an `after` relationship
@@ -340,19 +587,19 @@ function groupResolvedTargets(resolved) {
     }
     return groups;
 }
-function renderPhraseGroup(group, siblingsOf) {
+function renderPhraseGroup(group, siblingsOf, index) {
     if (group.kind === 'temporal-pair') {
-        const [first, second] = sentFirstOrder(group.a, group.b, siblingsOf);
-        return `${fullTargetPhrase(first, siblingsOf)}, compared with ${fullTargetPhrase(second, siblingsOf)}`;
+        const [first, second] = sentFirstOrder(group.a, group.b, siblingsOf, index);
+        return `${fullTargetPhrase(first, siblingsOf, index)}, compared with ${fullTargetPhrase(second, siblingsOf, index)}`;
     }
     const first = group.resolved[0];
     if (first === undefined) {
         throw new TypeError('evidence-target group is empty');
     }
     if (group.resolved.length === 1) {
-        return fullTargetPhrase(first, siblingsOf);
+        return fullTargetPhrase(first, siblingsOf, index);
     }
-    const stepRef = renderStepReference(first.step, first.operation, siblingsOf(first.operation.operationId));
+    const stepRef = renderStepReference(first.step, first.operation, siblingsOf(first.operation.operationId), index);
     // Sorted, so a same-step group's field order is permutation-invariant like
     // the top-level join below; in declaration order, permuting
     // `evidenceTargets` would change which field is named first here.
@@ -378,6 +625,6 @@ export function renderEvidenceReferences(pointers, index) {
     const siblings = siblingsByOperation(resolved);
     const siblingsOf = (operationId) => siblings.get(operationId) ?? [];
     const groups = groupResolvedTargets(resolved);
-    const phrases = groups.map((group) => renderPhraseGroup(group, siblingsOf));
+    const phrases = groups.map((group) => renderPhraseGroup(group, siblingsOf, index));
     return joinWithAnd([...phrases].sort());
 }

package/dist/core/seal/plan-index.d.ts

@@ -1,7 +1,7 @@
 /** resolves a pointer to its step and operation; nothing about reachability. */
-import type { Operation, PermittedInterface } from '../schemas/interface.ts';
+import type { AnyOperation, CommandOperation, InterfaceKindName, Operation, PermittedInterface } from '../schemas/interface.ts';
 import type { InteractionStep } from '../schemas/plan.ts';
-import { type EvidenceChannelName, type TransportChannelName } from '../schemas/pointer.ts';
+import { type EvidenceChannelName, type InputChannelName } from '../schemas/pointer.ts';
 /**
  * Exported so `core/evaluate/evidence-resolution.ts` decodes pointer tails
  * with these same two functions, avoiding a second private copy (the drift
@@ -17,7 +17,8 @@ export declare const decodeTail: (tailSource: string) => readonly string[];
 export type EvidenceTarget = {
     stepId: string;
     channel: EvidenceChannelName;
-    transportChannel: TransportChannelName | null;
+    transportChannel: InputChannelName | null;
+    artifactId: string | null;
     tail: readonly string[];
 };
 /**
@@ -34,10 +35,18 @@ export declare function parseEvidenceTarget(pointer: string): EvidenceTarget;
  * about reachability or channel typing; the general addressing-grammar
  * resolver lives in `core/evaluate/evidence-resolution.ts` and reachability
  * in `core/compile/reachability.ts`.
+ *
+ * `operationOf` stays narrow on purpose. It hands a resolved `Operation` to
+ * every downstream consumer, so widening its return type to the operation
+ * union would retype seventeen files at once. A command operation resolves to
+ * `undefined` from it and to a value from `commandOperationOf`, and each
+ * caller that has to branch reads the declaring kind first.
  */
 export type PlanIndex = {
     stepOf: (stepId: string) => InteractionStep | undefined;
     operationOf: (operationId: string) => Operation | undefined;
+    commandOperationOf: (operationId: string) => CommandOperation | undefined;
+    interfaceKindOf: (operationId: string) => InterfaceKindName | undefined;
     stepsUsing: (operationId: string) => readonly InteractionStep[];
 };
 export type PlanIndexOptions = {
@@ -59,5 +68,11 @@ export declare function buildPlanIndex(interactionPlan: readonly InteractionStep
  * `RuntimeFault`.
  */
 export declare function resolveStep(index: PlanIndex, stepId: string): InteractionStep;
+/**
+ * The declared operation of whichever kind, for the callers that read only
+ * fields both shapes carry. Callers reading a kind-specific field ask
+ * `interfaceKindOf` first and then take the matching accessor.
+ */
+export declare const anyOperationOf: (index: PlanIndex, operationId: string) => AnyOperation | undefined;
 /** Resolves an operation id through the index or throws. See `resolveStep`. */
 export declare function resolveOperation(index: PlanIndex, operationId: string): Operation;

package/dist/core/seal/plan-index.js

@@ -1,4 +1,5 @@
-import { SCALAR_CHANNELS, TAIL_BEARING_CHANNELS, TRANSPORT_CHANNELS, TRANSPORT_ROOTED_CHANNEL, } from '../schemas/pointer.js';
+import { operationsOf } from '../schemas/interface.js';
+import { IDENTIFIER_ROOTED_CHANNEL, INPUT_CHANNELS, SCALAR_CHANNELS, TAIL_BEARING_CHANNELS, TRANSPORT_ROOTED_CHANNEL, } from '../schemas/pointer.js';
 import { IDENTIFIER_CHARSET_SOURCE } from '../schemas/primitives.js';
 // An RFC 6901 reference token, respelled here because pointer.ts keeps its
 // own TOKEN/TAIL fragments private. IDENTIFIER_CHARSET_SOURCE and the channel
@@ -14,10 +15,10 @@ const alternation = (members) => members.join('|');
 // Named capture groups replace positional indices, avoiding a fragile
 // dependency on `IDENTIFIER_CHARSET_SOURCE` staying free of its own capturing
 // groups.
-const EVIDENCE_TARGET_PATTERN = new RegExp(`^/interactions/(?<stepId>${IDENTIFIER_CHARSET_SOURCE})/(?:(?<tailBearingChannel>${alternation(TAIL_BEARING_CHANNELS)})(?<tailBearingTail>${TAIL_SOURCE})|(?<scalarChannel>${alternation(SCALAR_CHANNELS)})|${TRANSPORT_ROOTED_CHANNEL}/(?<transportChannel>${alternation(TRANSPORT_CHANNELS)})(?<callInputsTail>${TAIL_SOURCE}))$`);
+const EVIDENCE_TARGET_PATTERN = new RegExp(`^/interactions/(?<stepId>${IDENTIFIER_CHARSET_SOURCE})/(?:(?<tailBearingChannel>${alternation(TAIL_BEARING_CHANNELS)})(?<tailBearingTail>${TAIL_SOURCE})|(?<scalarChannel>${alternation(SCALAR_CHANNELS)})|${TRANSPORT_ROOTED_CHANNEL}/(?<transportChannel>${alternation(INPUT_CHANNELS)})(?<callInputsTail>${TAIL_SOURCE})|${IDENTIFIER_ROOTED_CHANNEL}/(?<artifactId>${IDENTIFIER_CHARSET_SOURCE})(?<artifactTail>${TAIL_SOURCE}))$`);
 const isEvidenceChannel = (value) => TAIL_BEARING_CHANNELS.includes(value) ||
     SCALAR_CHANNELS.includes(value);
-const isTransportChannel = (value) => TRANSPORT_CHANNELS.includes(value);
+const isInputChannel = (value) => INPUT_CHANNELS.includes(value);
 /**
  * Exported so `core/evaluate/evidence-resolution.ts` decodes pointer tails
  * with these same two functions, avoiding a second private copy (the drift
@@ -47,6 +48,7 @@ export function parseEvidenceTarget(pointer) {
             stepId,
             channel: groups.scalarChannel,
             transportChannel: null,
+            artifactId: null,
             tail: [],
         };
     }
@@ -59,21 +61,32 @@ export function parseEvidenceTarget(pointer) {
             stepId,
             channel: groups.tailBearingChannel,
             transportChannel: null,
+            artifactId: null,
             tail: decodeTail(groups.tailBearingTail ?? ''),
         };
     }
     if (groups.transportChannel !== undefined) {
-        if (!isTransportChannel(groups.transportChannel)) {
-            // Unreachable: TRANSPORT_CHANNELS is exactly what this group can match.
+        if (!isInputChannel(groups.transportChannel)) {
+            // Unreachable: INPUT_CHANNELS is exactly what this group can match.
             throw new TypeError(`call-inputs evidence target names no transport channel: ${pointer}`);
         }
         return {
             stepId,
             channel: 'call-inputs',
             transportChannel: groups.transportChannel,
+            artifactId: null,
             tail: decodeTail(groups.callInputsTail ?? ''),
         };
     }
+    if (groups.artifactId !== undefined) {
+        return {
+            stepId,
+            channel: IDENTIFIER_ROOTED_CHANNEL,
+            transportChannel: null,
+            artifactId: groups.artifactId,
+            tail: decodeTail(groups.artifactTail ?? ''),
+        };
+    }
     // Unreachable: the pattern's three branches are exhaustive once stepId matched.
     throw new TypeError(`not an interaction-rooted evidence pointer of a recognized channel: ${pointer}`);
 }
@@ -109,25 +122,42 @@ export function buildPlanIndex(interactionPlan, permittedInterfaces, options = {
         }
     }
     const operations = new Map();
+    const commandOperations = new Map();
+    const kinds = new Map();
     const duplicateOperationIds = new Set();
     for (const iface of permittedInterfaces) {
-        for (const operation of iface.operations) {
-            if (operations.has(operation.operationId) ||
+        for (const operation of operationsOf(iface)) {
+            if (kinds.has(operation.operationId) ||
                 duplicateOperationIds.has(operation.operationId)) {
                 if (duplicateIds === 'throw') {
                     throw new TypeError(`duplicate operation id across permitted interfaces: ${operation.operationId}`);
                 }
                 operations.delete(operation.operationId);
+                commandOperations.delete(operation.operationId);
+                kinds.delete(operation.operationId);
                 duplicateOperationIds.add(operation.operationId);
             }
             else {
-                operations.set(operation.operationId, operation);
+                kinds.set(operation.operationId, iface.kind);
+                // Sorted into the two maps by the interface's own kind rather
+                // than by probing the operation for a field: `web` and `mcp`
+                // carry the api operation shape and belong in the same map as
+                // `api`, since every consumer of a resolved operation reads
+                // the same declared fields off all three.
+                if (iface.kind === 'cli') {
+                    commandOperations.set(operation.operationId, operation);
+                }
+                else {
+                    operations.set(operation.operationId, operation);
+                }
             }
         }
     }
     return {
         stepOf: (stepId) => steps.get(stepId),
         operationOf: (operationId) => operations.get(operationId),
+        commandOperationOf: (operationId) => commandOperations.get(operationId),
+        interfaceKindOf: (operationId) => kinds.get(operationId),
         stepsUsing: (operationId) => stepsByOperation.get(operationId) ?? [],
     };
 }
@@ -145,6 +175,12 @@ export function resolveStep(index, stepId) {
     }
     return step;
 }
+/**
+ * The declared operation of whichever kind, for the callers that read only
+ * fields both shapes carry. Callers reading a kind-specific field ask
+ * `interfaceKindOf` first and then take the matching accessor.
+ */
+export const anyOperationOf = (index, operationId) => index.operationOf(operationId) ?? index.commandOperationOf(operationId);
 /** Resolves an operation id through the index or throws. See `resolveStep`. */
 export function resolveOperation(index, operationId) {
     const operation = index.operationOf(operationId);

package/dist/core/seal/seal.js

@@ -75,8 +75,10 @@ export function seal(contract) {
         // and stateless with no "prior brief" argument (AD-12), so the only
         // honest artifact is a lineage root: `parentDigest` null,
         // `revisionCount` 0, independent of the contract's own lineage.
-        // `schemaVersion` is the brief schema's current version.
-        schemaVersion: 1,
+        // `schemaVersion` is the brief schema's current version; 2 since owed
+        // item 3 added `principals` as a required field, which AD-11 counts as
+        // a breaking change.
+        schemaVersion: 2,
         parentDigest: null,
         revisionCount: 0,
         // A plain digest of the literal input: two differently-ordered
@@ -98,8 +100,11 @@ export function seal(contract) {
         // Copied rather than aliased, for the same reason as `behaviors` above.
         budgets: { ...contract.budgets },
         // Sorted lexicographically; sort-key duplicates are impossible here
-        // since equal strings are interchangeable, so no duplicate guard.
+        // since equal strings are interchangeable, so no duplicate guard. The
+        // principal names are sorted the same way rather than through
+        // `sortedByKey`, for the same reason: there is no key to guard.
         safetyLimits: [...contract.safetyLimits].sort(),
+        principals: Object.keys(contract.testData.principals ?? {}).sort(),
         probeStepBound: contract.probeStepBound,
     };
     // The parse returns Zod's own deep clone, so the freeze lands on the