eval-quality 0.1.0 → 0.3.0

package/dist/core/compile/reachability.js

@@ -7,10 +7,12 @@
  * `evaluatePointerReachability` is exported separately as the non-throwing
  * per-pointer core, for reuse and direct testing.
  */
+import { declaredArtifactsOf, descriptorArtifactOf, descriptorChannelOf, isCommandOperation, requestShapeOf, } from '../declared-inputs.js';
 import { ARRAY_INDEX_PATTERN } from '../evaluate/evidence-resolution.js';
 import { StructuralFailure } from '../failure-codes.js';
+import { operationsOf } from '../schemas/interface.js';
 import { JsonTypeName } from '../schemas/primitives.js';
-import { buildPlanIndex, parseEvidenceTarget, } from '../seal/plan-index.js';
+import { anyOperationOf, buildPlanIndex, parseEvidenceTarget, } from '../seal/plan-index.js';
 function visitOperand(operand, path, insideQuantifier, visit) {
     if ('pointer' in operand)
         visit({ pointer: operand.pointer, path, insideQuantifier });
@@ -52,6 +54,42 @@ function forEachCheckPointer(contract, visit) {
         visitExpression(oracle.check, 'check', false, (site) => visit(site, oracle.id));
     });
 }
+/**
+ * Every interaction-rooted pointer the contract writes down, wherever it sits:
+ * an oracle's check and its direction's evidence targets, a rubric criterion's
+ * evidence, and each operation's sensitivity-witness relation.
+ *
+ * Broader than `forEachCheckPointer`, which walks oracle checks alone, because
+ * an artifact identifier is an authoring fault at every site that names one and
+ * a check that walked only the checks would report half of them.
+ */
+export function forEachArtifactPointer(contract, visit) {
+    const seen = (pointer, artifactPath) => {
+        if (pointer.startsWith('@'))
+            return;
+        visit(pointer, artifactPath);
+    };
+    contract.oracles.forEach((oracle) => {
+        if (oracle.check !== null)
+            visitExpression(oracle.check, 'check', false, (site) => seen(site.pointer, `EvalContract.oracles[id=${oracle.id}].${site.path}`));
+        oracle.direction?.evidenceTargets.forEach((target, index) => {
+            seen(target, `EvalContract.oracles[id=${oracle.id}].direction.evidenceTargets[${index}]`);
+        });
+    });
+    contract.rubrics.forEach((rubric) => {
+        rubric.criteria.forEach((criterion) => {
+            seen(criterion.evidence, `EvalContract.rubrics[id=${rubric.id}].criteria[id=${criterion.id}].evidence`);
+        });
+    });
+    contract.permittedInterfaces.forEach((iface, interfaceIndex) => {
+        operationsOf(iface).forEach((operation, operationIndex) => {
+            const witness = operation.sensitivityWitness;
+            if (witness === null)
+                return;
+            visitExpression(witness.relation, 'relation', false, (site) => seen(site.pointer, `EvalContract.permittedInterfaces[${interfaceIndex}].operations[${operationIndex}].sensitivityWitness.${site.path}`));
+        });
+    });
+}
 // ---- malformed-operator-expression: @/ outside any quantifier -----------
 export function checkBoundElementScope(contract) {
     forEachCheckPointer(contract, (site, oracleId) => {
@@ -60,6 +98,34 @@ export function checkBoundElementScope(contract) {
         }
     });
 }
+/** `checkBoundElementScope` over one bare `Expression`. */
+export function checkExpressionBoundElementScope(expression, artifactPath) {
+    visitExpression(expression, '', false, (site) => {
+        if (site.pointer.startsWith('@') && !site.insideQuantifier) {
+            throw new StructuralFailure('malformed-operator-expression', `${artifactPath}${site.path}`, `bound-element pointer "${site.pointer}" appears outside any quantifier's predicate; "@/" binds only inside a quantifier (AD-26)`);
+        }
+    });
+}
+/**
+ * Visits every `{ pointer }` operand of one bare `Expression`, which a
+ * probe-side legality pass needs for the rules a contract has no equivalent of:
+ * that every pointer roots at the reserved step identifier, and which evidence
+ * channels the condition actually names.
+ */
+export function forEachExpressionPointer(expression, visit) {
+    visitExpression(expression, '', false, (site) => {
+        visit(site.pointer, site.path);
+    });
+}
+/** `checkEvidenceReachability` over one bare `Expression` and one operation. */
+export function checkExpressionEvidenceReachability(expression, artifactPath, operation) {
+    visitExpression(expression, '', false, (site) => {
+        const result = evaluateReachabilityAgainstOperation(site.pointer, operation);
+        if (!result.reachable) {
+            throw new StructuralFailure('unreachable-check-evidence', `${artifactPath}${site.path}`, `"${site.pointer}" ${result.reason}`);
+        }
+    });
+}
 const reachable = () => ({ reachable: true });
 const unreachable = (reason) => ({
     reachable: false,
@@ -81,7 +147,11 @@ function descendsIntoDeclaredScalar(types, tail, firstToken) {
 }
 /**
  * Non-throwing core that `checkEvidenceReachability` wraps; also called
- * directly by tests.
+ * directly by tests. The two lines below are the whole of what ties this to a
+ * declared interaction plan; everything past them reads the operation alone,
+ * which is what `evaluateReachabilityAgainstOperation` exposes for a probe-side
+ * condition, whose one step identifier is reserved and resolves to the
+ * signature's home operation with no plan in sight.
  */
 export function evaluatePointerReachability(pointer, index) {
     // A `@/` pointer is relative to a bound element. Nothing declared to
@@ -93,51 +163,109 @@ export function evaluatePointerReachability(pointer, index) {
     if (step === undefined) {
         return unreachable('names a step the interaction plan does not declare');
     }
-    const operation = index.operationOf(step.operationId);
+    const operation = anyOperationOf(index, step.operationId);
     if (operation === undefined) {
         return unreachable(`names step "${target.stepId}", which names operation "${step.operationId}", not declared by any permitted interface`);
     }
-    if (target.channel === 'stdout' || target.channel === 'stderr') {
-        // stdout/stderr are always bare strings. A non-empty tail proves the
-        // pointer unreachable.
-        if (target.tail.length > 0) {
-            return unreachable(`addresses a field inside ${target.channel}, which never carries structure to descend into`);
+    return evaluateReachabilityAgainstOperation(pointer, operation);
+}
+/**
+ * Descent through the operation's response descriptor, from whichever channel
+ * that descriptor describes. `channel` is carried only so the reason names the
+ * pointer's own root back to the author.
+ */
+function descendThroughDescriptor(descriptor, target, operationId, channel) {
+    if (target.tail.length === 0)
+        return reachable();
+    const firstToken = target.tail[0];
+    if (firstToken === undefined) {
+        // Unreachable: the length check above guarantees an element.
+        throw new TypeError('evidence-target tail is non-empty but has no first token');
+    }
+    const { requiredKeys, permittedKeys, types, collectionLocations } = descriptor;
+    // A root-declared collection (`pointer: ''`) indexes directly, bypassing
+    // the key check below. `expectedCardinality` bounds the array size
+    // (`exact` is the true count; `at-most`/`page-bounded` is an upper
+    // bound), so an index at or past it is unreachable.
+    const rootCollection = collectionLocations?.find((location) => location.pointer === '');
+    if (rootCollection !== undefined && ARRAY_INDEX_PATTERN.test(firstToken)) {
+        const { expectedCardinality } = rootCollection;
+        const bound = expectedCardinality.mode === 'exact'
+            ? expectedCardinality.count
+            : expectedCardinality.max;
+        if (Number(firstToken) >= bound) {
+            return unreachable(`addresses ${channel} index ${firstToken}, out of bounds for the declared root collection's expectedCardinality (${expectedCardinality.mode} ${bound})`);
         }
         return reachable();
     }
-    if (target.channel === 'response-body') {
-        if (target.tail.length === 0)
-            return reachable();
-        const firstToken = target.tail[0];
-        if (firstToken === undefined) {
-            // Unreachable: the length check above guarantees an element.
-            throw new TypeError('evidence-target tail is non-empty but has no first token');
+    if (!requiredKeys.includes(firstToken) &&
+        !permittedKeys.includes(firstToken)) {
+        return unreachable(`addresses ${channel} field "${firstToken}", which operation "${operationId}" declares in neither requiredKeys nor permittedKeys`);
+    }
+    if (descendsIntoDeclaredScalar(types, target.tail, firstToken)) {
+        return unreachable(`descends into ${channel} field "${firstToken}", which operation "${operationId}" declares a scalar with no further structure`);
+    }
+    return reachable();
+}
+/**
+ * The same rules, against an operation the caller already resolved. Without
+ * this check a probe-side condition addressing an undeclared channel or key
+ * resolves absent, every comparison over it resolves `false`, and the probe
+ * reports its defect as never triggered — a silently passing run on a signature
+ * that was never writable.
+ */
+function evaluateReachabilityAgainstOperation(pointer, operation) {
+    if (pointer.startsWith('@'))
+        return reachable();
+    const target = parseEvidenceTarget(pointer);
+    const descriptorChannel = descriptorChannelOf(operation);
+    const command = isCommandOperation(operation);
+    if (target.channel === 'artifact') {
+        const { artifactId } = target;
+        if (artifactId === null) {
+            // Unreachable: parseEvidenceTarget's own guarantee.
+            throw new TypeError('artifact evidence target names no artifact');
         }
-        const { requiredKeys, permittedKeys, types, collectionLocations } = operation.responseDescriptor;
-        // A root-declared collection (`pointer: ''`) indexes directly, bypassing
-        // the key check below. `expectedCardinality` bounds the array size
-        // (`exact` is the true count; `at-most`/`page-bounded` is an upper
-        // bound), so an index at or past it is unreachable.
-        const rootCollection = collectionLocations?.find((location) => location.pointer === '');
-        if (rootCollection !== undefined && ARRAY_INDEX_PATTERN.test(firstToken)) {
-            const { expectedCardinality } = rootCollection;
-            const bound = expectedCardinality.mode === 'exact'
-                ? expectedCardinality.count
-                : expectedCardinality.max;
-            if (Number(firstToken) >= bound) {
-                return unreachable(`addresses response-body index ${firstToken}, out of bounds for the declared root collection's expectedCardinality (${expectedCardinality.mode} ${bound})`);
+        // An identifier the operation does not declare produces no evidence, so
+        // it is unreachable and this says so. `checkArtifactReferences` runs
+        // earlier in `compile` and reports the more specific
+        // `unresolved-artifact-reference` for a contract, so the two never race
+        // there; this answer is the only one on the probe side, where that check
+        // does not run because it walks a contract rather than a signature.
+        if (!declaredArtifactsOf(operation).includes(artifactId)) {
+            return unreachable(`names the "${artifactId}" artifact, which operation "${operation.operationId}" does not declare it writes`);
+        }
+        if (artifactId !== descriptorArtifactOf(operation)) {
+            // Declared to exist, and nothing declares its structure: the
+            // operation's one descriptor describes a different channel.
+            if (target.tail.length > 0) {
+                return unreachable(`addresses a field inside the "${artifactId}" artifact, which operation "${operation.operationId}" declares it writes but declares no structure for`);
             }
             return reachable();
         }
-        if (!requiredKeys.includes(firstToken) &&
-            !permittedKeys.includes(firstToken)) {
-            return unreachable(`addresses response-body field "${firstToken}", which operation "${operation.operationId}" declares in neither requiredKeys nor permittedKeys`);
-        }
-        if (descendsIntoDeclaredScalar(types, target.tail, firstToken)) {
-            return unreachable(`descends into response-body field "${firstToken}", which operation "${operation.operationId}" declares a scalar with no further structure`);
+        return descendThroughDescriptor(operation.responseDescriptor, target, operation.operationId, `the "${artifactId}" artifact`);
+    }
+    // The declared output channel descends through the descriptor whatever it
+    // is called. This is the one rule; the channels below are the cases where
+    // no descriptor applies.
+    if (target.channel === descriptorChannel) {
+        return descendThroughDescriptor(operation.responseDescriptor, target, operation.operationId, target.channel);
+    }
+    if (target.channel === 'stdout' || target.channel === 'stderr') {
+        // The stream this operation's descriptor does not describe carries no
+        // declared structure, so a non-empty tail proves the pointer
+        // unreachable.
+        if (target.tail.length > 0) {
+            return unreachable(`addresses a field inside ${target.channel}, which operation "${operation.operationId}" declares no structure for`);
         }
         return reachable();
     }
+    if (command &&
+        (target.channel === 'response-body' ||
+            target.channel === 'response-headers' ||
+            target.channel === 'response-status')) {
+        return unreachable(`addresses ${target.channel} on operation "${operation.operationId}", which runs behind a command and produces no HTTP response`);
+    }
     if (target.channel === 'call-inputs') {
         if (target.tail.length === 0)
             return reachable();
@@ -150,7 +278,11 @@ export function evaluatePointerReachability(pointer, index) {
         if (firstToken === undefined) {
             throw new TypeError('evidence-target tail is non-empty but has no first token');
         }
-        const { requiredKeys, permittedKeys, types } = operation.requestShape[transportChannel];
+        const shape = requestShapeOf(operation, transportChannel);
+        if (shape === undefined) {
+            return unreachable(`addresses call-inputs ${transportChannel}, a channel operation "${operation.operationId}" does not accept input on`);
+        }
+        const { requiredKeys, permittedKeys, types } = shape;
         if (!requiredKeys.includes(firstToken) &&
             !permittedKeys.includes(firstToken)) {
             return unreachable(`addresses call-inputs ${transportChannel} field "${firstToken}", which operation "${operation.operationId}" declares in neither requiredKeys nor permittedKeys`);

package/dist/core/compile/schema-version.d.ts

@@ -0,0 +1,2 @@
+/** `schema-version-mismatch`: the stamp is not the version this build reads. */
+export declare function checkSchemaVersion(stamped: number, accepted: number, artifactPath: string): void;

package/dist/core/compile/schema-version.js

@@ -0,0 +1,25 @@
+/**
+ * AD-11's version equality, performed by the one reader that has the contract.
+ *
+ * AD-11's rule is that "readers accept an equal `schemaVersion` only and throw
+ * `schema-version-mismatch` outside that". `lineage.ts` deliberately keeps the
+ * field a plain integer rather than a literal, so that a wrong version arrives
+ * as AD-28's named fault instead of an anonymous parse failure, which puts the
+ * comparison on whoever reads the artifact. For the eval contract nobody did:
+ * a contract stamped 3 parsed, compiled, sealed, and put its stale version into
+ * the scoring version digest, and AD-11 exists to keep that number comparable.
+ *
+ * `RuntimeFault` rather than `StructuralFailure`, against the grain of every
+ * other check in this directory. The two registries are disjoint by the
+ * Consistency Conventions, AD-5 has no version code, and AD-11 names
+ * `schema-version-mismatch` literally. Minting an AD-5 twin would give one
+ * condition two codes and make a caller's handler depend on which reader
+ * happened to notice first.
+ */
+import { RuntimeFault } from '../schemas/faults.js';
+/** `schema-version-mismatch`: the stamp is not the version this build reads. */
+export function checkSchemaVersion(stamped, accepted, artifactPath) {
+    if (stamped === accepted)
+        return;
+    throw new RuntimeFault('schema-version-mismatch', artifactPath, `carries "schemaVersion" ${stamped} where this build reads ${accepted}; a contract written for another version is not read leniently, since its stale version would travel into the scoring version (AD-11)`);
+}

package/dist/core/compile/sensitivity-witness.d.ts

@@ -4,26 +4,45 @@
  * execute it, and that its leg identifiers are distinct from each other and
  * from every interaction-plan step.
  *
- * No new AD-5 code is minted. The registry is closed at twenty-one and
- * `check:ad5-registry` pins it against the spine, so each defect below takes the
- * code that already names it. Two rows stretch that reading: a leg-id equality
+ * No new AD-5 code is minted here. `check:ad5-registry` pins the registry
+ * against the spine's own table, so each defect below takes the code that
+ * already names it. Two rows stretch that reading: a leg-id equality
  * and a leg-id/step-id collision are identifier collisions, and
  * `malformed-operator-expression` is the closest available code because the
  * relation is illegal in its position once its operands cannot be told apart.
  */
 import { declaresNoRequestKeys } from '../declared-inputs.ts';
 import type { EvalContract } from '../schemas/eval-contract.ts';
-import type { Operation } from '../schemas/interface.ts';
-import { type TransportChannelName } from '../schemas/pointer.ts';
-import type { WitnessInputs } from '../schemas/sensitivity-witness.ts';
+import type { AnyOperation } from '../schemas/interface.ts';
+import type { InputChannelName } from '../schemas/pointer.ts';
+import { type ApiWitnessInputs, type WitnessChannel, type WitnessInputs } from '../schemas/sensitivity-witness.ts';
 export { declaresNoRequestKeys };
 /**
- * The keys one set of witness inputs supplies on one channel. A body that is
- * absent, or JSON that is not an object, supplies no keys: the channel is
- * declared as a keyed shape, so such a leg omits every required key rather
- * than being exempt from the comparison.
+ * The transport spelling, for the consumers that can only send one: the probe
+ * port carries a method, a path template, and the four transport channels.
  */
-export declare function suppliedKeys(inputs: WitnessInputs, channel: TransportChannelName): readonly string[];
+export declare const isApiWitnessInputs: (inputs: WitnessInputs) => inputs is ApiWitnessInputs;
+/**
+ * Whether the leg supplies this channel as an undifferentiated stream.
+ *
+ * Standard input written as text is one such stream. A `KeyedShapeDescriptor`
+ * can say what keys a channel carries and cannot say "one opaque stream", so a
+ * command that reads a prompt is declared by naming the one thing the stream
+ * carries, and the leg supplies that thing as the text it actually is.
+ */
+export declare function suppliesOpaquely(inputs: WitnessInputs, channel: InputChannelName): boolean;
+/**
+ * The keys one set of witness inputs supplies on one channel, or none where
+ * the leg's spelling has no such channel.
+ *
+ * `body` and `stdin` are the two channels a leg supplies as a tagged value
+ * rather than as a key map, because a leg has to tell an absent value from one
+ * carrying JSON null. This function is the bridge between that spelling and
+ * the keyed shape the request declares.
+ */
+export declare function suppliedKeys(inputs: WitnessInputs, channel: InputChannelName): readonly string[];
+/** One channel's supplied value, for the differential comparison. */
+export declare function suppliedValue(inputs: WitnessInputs, channel: WitnessChannel): unknown;
 /**
  * Every channel of one set of witness inputs against the operation that will
  * receive them. All four, not only the differential channel: `planPreflight`
@@ -49,7 +68,7 @@ export declare function suppliedKeys(inputs: WitnessInputs, channel: TransportCh
  * contract artifact, the surface AD-18 governs; a placeholder satisfies this
  * check, and what pre-flight probes is a fixture.
  */
-export declare function checkInputsAgainstShape(inputs: WitnessInputs, operation: Operation, owner: string, artifactPath: string): void;
+export declare function checkInputsAgainstShape(inputs: WitnessInputs, operation: AnyOperation, owner: string, artifactPath: string): void;
 /**
  * Strict-gated, alongside `checkUndeclaredMandatoryInput`, whose code this
  * shares: `compile.ts` already gates that code behind `options.strict`, and one

package/dist/core/compile/sensitivity-witness.js

@@ -4,28 +4,65 @@
  * execute it, and that its leg identifiers are distinct from each other and
  * from every interaction-plan step.
  *
- * No new AD-5 code is minted. The registry is closed at twenty-one and
- * `check:ad5-registry` pins it against the spine, so each defect below takes the
- * code that already names it. Two rows stretch that reading: a leg-id equality
+ * No new AD-5 code is minted here. `check:ad5-registry` pins the registry
+ * against the spine's own table, so each defect below takes the code that
+ * already names it. Two rows stretch that reading: a leg-id equality
  * and a leg-id/step-id collision are identifier collisions, and
  * `malformed-operator-expression` is the closest available code because the
  * relation is illegal in its position once its operands cannot be told apart.
  */
-import { declaresNoRequestKeys } from '../declared-inputs.js';
+import { declaresNoRequestKeys, isCommandOperation, requestChannelsOf, } from '../declared-inputs.js';
 import { StructuralFailure } from '../failure-codes.js';
-import { TRANSPORT_CHANNELS, } from '../schemas/pointer.js';
+import { operationsOf } from '../schemas/interface.js';
+import { COMMAND_WITNESS_CHANNELS, } from '../schemas/sensitivity-witness.js';
 import { parseEvidenceTarget } from '../seal/plan-index.js';
 export { declaresNoRequestKeys };
+/** Which spelling this leg uses. `stdin` is the command shape's own key. */
+const isCommandWitnessInputs = (inputs) => 'stdin' in inputs;
 /**
- * The keys one set of witness inputs supplies on one channel. A body that is
- * absent, or JSON that is not an object, supplies no keys: the channel is
- * declared as a keyed shape, so such a leg omits every required key rather
- * than being exempt from the comparison.
+ * The transport spelling, for the consumers that can only send one: the probe
+ * port carries a method, a path template, and the four transport channels.
  */
-export function suppliedKeys(inputs, channel) {
-    if (channel !== 'body')
-        return Object.keys(inputs[channel]);
-    const { body } = inputs;
+export const isApiWitnessInputs = (inputs) => 'body' in inputs;
+/**
+ * Whether the leg supplies this channel as an undifferentiated stream.
+ *
+ * Standard input written as text is one such stream. A `KeyedShapeDescriptor`
+ * can say what keys a channel carries and cannot say "one opaque stream", so a
+ * command that reads a prompt is declared by naming the one thing the stream
+ * carries, and the leg supplies that thing as the text it actually is.
+ */
+export function suppliesOpaquely(inputs, channel) {
+    return (isCommandWitnessInputs(inputs) &&
+        channel === 'stdin' &&
+        inputs.stdin.kind === 'text');
+}
+/**
+ * What an opaque stream fills, and when it cannot say.
+ *
+ * A text leg supplies the channel's ONE declared key: the stream is the value
+ * of the single thing the operation says it reads. Where the channel declares
+ * no required key there is nothing for the text to be, and where it declares
+ * more than one there is no way to say which the text fills, so both are the
+ * authoring fault this reports rather than a comparison that quietly abstains.
+ *
+ * That is what a keyed `stdin` means for a command that reads text, and it is
+ * the reason the declaration stays keyed: an operation that genuinely parses a
+ * structured document off standard input declares several keys and supplies
+ * them through the leg's `json` arm, and the same descriptor serves both.
+ */
+function checkOpaqueStream(shape, channel, operationId, owner, artifactPath) {
+    if (shape.requiredKeys.length === 1)
+        return;
+    throw new StructuralFailure('undeclared-mandatory-input', artifactPath, `${owner} supplies its ${channel} channel as text, which fills the one key the channel declares, but operation "${operationId}" declares ${shape.requiredKeys.length === 0 ? 'no required key there, so the text fills nothing' : `${shape.requiredKeys.length} required keys there, so nothing says which the text fills`} (AD-10, AD-19)`);
+}
+/**
+ * The keys a tagged body value supplies. A body that is absent, or JSON that
+ * is not an object, supplies no keys: the channel is declared as a keyed
+ * shape, so such a leg omits every required key rather than being exempt from
+ * the comparison.
+ */
+function bodyKeys(body) {
     if (body.kind !== 'json')
         return [];
     const { value } = body;
@@ -33,6 +70,37 @@ export function suppliedKeys(inputs, channel) {
         return [];
     return Object.keys(value);
 }
+/**
+ * The keys one set of witness inputs supplies on one channel, or none where
+ * the leg's spelling has no such channel.
+ *
+ * `body` and `stdin` are the two channels a leg supplies as a tagged value
+ * rather than as a key map, because a leg has to tell an absent value from one
+ * carrying JSON null. This function is the bridge between that spelling and
+ * the keyed shape the request declares.
+ */
+export function suppliedKeys(inputs, channel) {
+    if (isCommandWitnessInputs(inputs)) {
+        if (channel === 'stdin')
+            return bodyKeys(inputs.stdin);
+        if (channel === 'argument' || channel === 'option')
+            return Object.keys(inputs[channel]);
+        if (channel === 'environment')
+            return Object.keys(inputs.environment);
+        return [];
+    }
+    if (channel === 'body')
+        return bodyKeys(inputs.body);
+    if (channel === 'path' || channel === 'query')
+        return Object.keys(inputs[channel]);
+    if (channel === 'header')
+        return Object.keys(inputs.header);
+    return [];
+}
+/** One channel's supplied value, for the differential comparison. */
+export function suppliedValue(inputs, channel) {
+    return inputs[channel];
+}
 /**
  * Every channel of one set of witness inputs against the operation that will
  * receive them. All four, not only the differential channel: `planPreflight`
@@ -59,8 +127,11 @@ export function suppliedKeys(inputs, channel) {
  * check, and what pre-flight probes is a fixture.
  */
 export function checkInputsAgainstShape(inputs, operation, owner, artifactPath) {
-    for (const channel of TRANSPORT_CHANNELS) {
-        const shape = operation.requestShape[channel];
+    for (const { channel, shape } of requestChannelsOf(operation)) {
+        if (suppliesOpaquely(inputs, channel)) {
+            checkOpaqueStream(shape, channel, operation.operationId, owner, artifactPath);
+            continue;
+        }
         const supplied = suppliedKeys(inputs, channel);
         for (const key of shape.requiredKeys) {
             if (supplied.includes(key))
@@ -78,7 +149,7 @@ export function checkInputsAgainstShape(inputs, operation, owner, artifactPath)
 const operationPath = (interfaceIndex, operationIndex) => `EvalContract.permittedInterfaces[${interfaceIndex}].operations[${operationIndex}]`;
 function forEachWitness(contract, visit) {
     contract.permittedInterfaces.forEach((iface, interfaceIndex) => {
-        iface.operations.forEach((operation, operationIndex) => {
+        operationsOf(iface).forEach((operation, operationIndex) => {
             const witness = operation.sensitivityWitness;
             if (witness === null)
                 return;
@@ -94,13 +165,13 @@ function forEachWitness(contract, visit) {
  */
 export function checkSensitivityWitnessDeclared(contract) {
     contract.permittedInterfaces.forEach((iface, interfaceIndex) => {
-        iface.operations.forEach((operation, operationIndex) => {
+        operationsOf(iface).forEach((operation, operationIndex) => {
             const path = operationPath(interfaceIndex, operationIndex);
             const witness = operation.sensitivityWitness;
             if (witness === null) {
                 if (declaresNoRequestKeys(operation))
                     return;
-                throw new StructuralFailure('undeclared-mandatory-input', path, `operation "${operation.operationId}" declares request keys but no sensitivity witness; only an operation declaring no keys in any channel is exempt (AD-10)`);
+                throw new StructuralFailure('undeclared-mandatory-input', path, `operation "${operation.operationId}" declares request keys but no sensitivity witness; only an operation declaring no keys in any channel is exempt (AD-10). The relation is the author's to choose and need not assert the two legs differ: an operation that is insensitive to its declared inputs by design declares a witness whose relation says so, which is a true and checkable claim about it, and gets the weaker guarantee that follows`);
             }
             witness.legs.forEach((leg, legIndex) => {
                 checkInputsAgainstShape(leg.inputs, operation, `leg "${leg.legId}"`, `${path}.sensitivityWitness.legs[${legIndex}]`);
@@ -137,8 +208,22 @@ function addressedStepIds(expression) {
     walk(expression);
     return found;
 }
-/** the channel AD-10 selects for an operation, by its state-change marker. */
-const legalChannels = (operation) => operation.stateChangeMarker ? ['body'] : ['path', 'query'];
+const MUTATING_CHANNELS = ['body'];
+const READ_CHANNELS = ['path', 'query'];
+/**
+ * The channels AD-10 admits for an operation's witness.
+ *
+ * Off an interface that speaks HTTP the state-change marker selects one, since
+ * a read carries its identifier in the URL and a write carries it in the body.
+ * A command carries its inputs the same way whether or not it changes state,
+ * so the marker selects nothing there and all four command channels are
+ * admitted. The author picks the one their operation is actually sensitive on.
+ */
+const legalChannels = (operation) => {
+    if (isCommandOperation(operation))
+        return COMMAND_WITNESS_CHANNELS;
+    return operation.stateChangeMarker ? MUTATING_CHANNELS : READ_CHANNELS;
+};
 /**
  * The shape rules: the differential channel agrees with the state-change
  * marker, the relation reads both legs and nothing else, and a declared
@@ -158,8 +243,8 @@ export function checkWitnessLegality(contract) {
         const [first, second] = witness.legs;
         if (first !== undefined &&
             second !== undefined &&
-            JSON.stringify(first.inputs[witness.channel]) ===
-                JSON.stringify(second.inputs[witness.channel])) {
+            JSON.stringify(suppliedValue(first.inputs, witness.channel)) ===
+                JSON.stringify(suppliedValue(second.inputs, witness.channel))) {
             throw new StructuralFailure('malformed-operator-expression', `${path}.sensitivityWitness.legs`, `both legs of witness "${witness.witnessId}" supply the same ${witness.channel} value, so the pair is not a differential (AD-10)`);
         }
         const legIds = witness.legs.map((leg) => leg.legId);
@@ -181,7 +266,9 @@ export function checkWitnessLegality(contract) {
     if (reset === null)
         return;
     const iface = contract.permittedInterfaces.find((candidate) => candidate.logicalId === reset.interfaceId);
-    const operation = iface?.operations.find((candidate) => candidate.operationId === reset.operationId);
+    const operation = iface === undefined
+        ? undefined
+        : operationsOf(iface).find((candidate) => candidate.operationId === reset.operationId);
     if (operation === undefined) {
         throw new StructuralFailure('unreachable-check-evidence', 'EvalContract.fixtureReset', `the fixture reset names operation "${reset.operationId}" on interface "${reset.interfaceId}", which the contract does not declare (AD-10)`);
     }

package/dist/core/compile/step-reference.d.ts

@@ -0,0 +1,2 @@
+import type { EvalContract } from '../schemas/eval-contract.ts';
+export declare function checkStepReferenceReducibility(contract: EvalContract): void;

package/dist/core/compile/step-reference.js

@@ -0,0 +1,49 @@
+/**
+ * `irreducible-step-reference`: two steps one direction references render to
+ * the same derived reference even after full escalation.
+ *
+ * AD-16 keeps step identifiers out of the sealed brief, so a direction names
+ * each step it references by a phrase derived from what the contract declares
+ * about it. Where two steps of one operation declare nothing that tells them
+ * apart, the escalation ladder runs out and the renderer has no way to name one
+ * without naming the other.
+ *
+ * The check runs the seal-side renderer rather than reimplementing its ladder.
+ * A second implementation of a three-rung escalation with a budget would be a
+ * second thing to keep in step with the first, and the failure this reports is
+ * defined as "what that renderer cannot do" rather than as a rule of its own.
+ * That is the same reasoning `checkEvidenceReachability` follows in reusing
+ * `evaluatePointerReachability`.
+ *
+ * Without it a contract passes every other check and then fails inside `seal`,
+ * which is the one authoring fault in the tree that reached a caller as a
+ * stack trace instead of a code and a path.
+ */
+import { StructuralFailure } from '../failure-codes.js';
+import { renderEvidenceReferences } from '../seal/derived-reference.js';
+import { buildPlanIndex } from '../seal/plan-index.js';
+export function checkStepReferenceReducibility(contract) {
+    let index;
+    for (const oracle of contract.oracles) {
+        const { direction } = oracle;
+        if (direction === null || direction.evidenceTargets.length === 0)
+            continue;
+        index ??= buildPlanIndex(contract.interactionPlan, contract.permittedInterfaces, { duplicateIds: 'unresolved' });
+        try {
+            renderEvidenceReferences(direction.evidenceTargets, index);
+        }
+        catch (error) {
+            if (!(error instanceof StructuralFailure)) {
+                // Every other way this renderer fails is a precondition violation
+                // on input `compile` has already checked, so it is a fault rather
+                // than an authoring fault and propagates unchanged.
+                throw error;
+            }
+            // Re-thrown with the contract-side address. `StructuralFailure`
+            // carries the code and the path and folds the detail into its
+            // message, so the detail is recovered from the message rather than
+            // from a field the class does not expose.
+            throw new StructuralFailure(error.code, `EvalContract.oracles[id=${oracle.id}].direction.evidenceTargets`, error.message.slice(`${error.code} in ${error.artifactPath}: `.length));
+        }
+    }
+}