eval-quality 0.1.0 → 0.3.0

package/dist/core/coverage/operations.d.ts

@@ -0,0 +1,62 @@
+/**
+ * One declared operation joined to the interface that declares it, plus the
+ * two facts the coverage predicates need and neither the operation nor the
+ * interface states: where a response descriptor's pointers resolve, and which
+ * channels a call's inputs may be keyed by.
+ *
+ * `relevance.ts` and `satisfaction.ts` each flattened `permittedInterfaces`
+ * with `flatMap((declared) => declared.operations)` and dropped the interface
+ * one line before every loop that ranges over it, so six of AD-20's seven
+ * rules could not see the kind that declared the operation they were grading.
+ * This is that flattening, written once and keeping the join.
+ *
+ * Nothing here throws, which is the promise both predicate modules make in
+ * their own headers and which `evaluateCoverage`'s callers rely on. Every
+ * field is read off an already-parsed contract, so there is no precondition
+ * left to assert.
+ */
+import { type RequestChannel } from '../declared-inputs.ts';
+import type { EvalContract } from '../schemas/eval-contract.ts';
+import type { AnyOperation, InterfaceKindName, ResponseDescriptor } from '../schemas/interface.ts';
+import type { InputChannelName } from '../schemas/pointer.ts';
+/**
+ * RFC 6901 escaping, `~` before `/`. Lives here rather than beside the
+ * pointer-building helpers that use it, because the descriptor root is built
+ * here and both spellings have to escape the same way.
+ */
+export declare const encodeToken: (token: string) => string;
+export type ResolvedOperation = {
+    readonly operation: AnyOperation;
+    /** the declaring interface's kind. An operation states no kind of its own. */
+    readonly kind: InterfaceKindName;
+    /** the declaring interface. Two interfaces may declare one `operationId`, and this is what separates them. */
+    readonly logicalId: string;
+    readonly descriptor: ResponseDescriptor;
+    /**
+     * The interaction-rooted segment a descriptor pointer hangs off, which is
+     * the channel this operation's own descriptor describes, and on the artifact
+     * channel the file as well. `/artifact` alone is not a root any real
+     * evidence pointer starts with, since an artifact pointer carries its
+     * identifier before its tail, so a root without it matched nothing and made
+     * every pointer-building rule answer against a pointer that cannot exist.
+     */
+    readonly descriptorRoot: string;
+    /**
+     * The channels a call's inputs may be keyed by. Names only: the two sites
+     * that build candidate pointers need the names and never the shapes.
+     */
+    readonly transportChannels: readonly InputChannelName[];
+    /**
+     * The same channels already paired with the shapes they declare. Predicates
+     * that read a declared shape take these rather than indexing the request
+     * shape with a name, because under the operation union TypeScript cannot
+     * prove a name drawn from one kind's tuple is a key of the other's shape.
+     */
+    readonly requestChannels: readonly RequestChannel[];
+};
+/**
+ * Every declared operation, in declaration order, each carrying the interface
+ * that declares it. Six of AD-20's seven rules range over this list; rule 5 is
+ * contract-level and reads the sibling groups instead.
+ */
+export declare function resolveOperations(contract: EvalContract): readonly ResolvedOperation[];

package/dist/core/coverage/operations.js

@@ -0,0 +1,57 @@
+/**
+ * One declared operation joined to the interface that declares it, plus the
+ * two facts the coverage predicates need and neither the operation nor the
+ * interface states: where a response descriptor's pointers resolve, and which
+ * channels a call's inputs may be keyed by.
+ *
+ * `relevance.ts` and `satisfaction.ts` each flattened `permittedInterfaces`
+ * with `flatMap((declared) => declared.operations)` and dropped the interface
+ * one line before every loop that ranges over it, so six of AD-20's seven
+ * rules could not see the kind that declared the operation they were grading.
+ * This is that flattening, written once and keeping the join.
+ *
+ * Nothing here throws, which is the promise both predicate modules make in
+ * their own headers and which `evaluateCoverage`'s callers rely on. Every
+ * field is read off an already-parsed contract, so there is no precondition
+ * left to assert.
+ */
+import { descriptorArtifactOf, descriptorChannelOf, inputChannelsOf, requestChannelsOf, } from '../declared-inputs.js';
+import { operationsOf } from '../schemas/interface.js';
+/**
+ * RFC 6901 escaping, `~` before `/`. Lives here rather than beside the
+ * pointer-building helpers that use it, because the descriptor root is built
+ * here and both spellings have to escape the same way.
+ */
+export const encodeToken = (token) => token.replace(/~/g, '~0').replace(/\//g, '~1');
+/**
+ * Where a descriptor-relative pointer hangs off an interaction root for this
+ * operation. Two segments on the artifact channel, one everywhere else.
+ */
+const descriptorRootOf = (operation) => {
+    const channel = descriptorChannelOf(operation);
+    if (channel !== 'artifact')
+        return `/${channel}`;
+    const artifactId = descriptorArtifactOf(operation);
+    // Unreachable: `descriptorChannelOf` answers `artifact` only for the arm
+    // that carries an identifier.
+    if (artifactId === null) {
+        throw new TypeError(`operation "${operation.operationId}" describes an artifact and names none`);
+    }
+    return `/${channel}/${encodeToken(artifactId)}`;
+};
+/**
+ * Every declared operation, in declaration order, each carrying the interface
+ * that declares it. Six of AD-20's seven rules range over this list; rule 5 is
+ * contract-level and reads the sibling groups instead.
+ */
+export function resolveOperations(contract) {
+    return contract.permittedInterfaces.flatMap((declared) => operationsOf(declared).map((operation) => ({
+        operation,
+        kind: declared.kind,
+        logicalId: declared.logicalId,
+        descriptor: operation.responseDescriptor,
+        descriptorRoot: descriptorRootOf(operation),
+        transportChannels: inputChannelsOf(operation),
+        requestChannels: requestChannelsOf(operation),
+    })));
+}

package/dist/core/coverage/relevance.d.ts

@@ -32,8 +32,10 @@ export declare function successIndicatorSeparationRelevance(contract: EvalContra
  */
 export declare function wholeBodyRelevance(contract: EvalContract): RelevanceVerdict;
 /**
- * Rule 3: some operation declares a request key on any of AD-19's four
- * transport channels. The site is the whole channel triple. A key with no
+ * Rule 3: some operation declares a request key on any of its own input
+ * channels, AD-19's four transport channels off an interface that speaks HTTP
+ * and the four command channels off one that does not. The site is the whole
+ * channel triple. A key with no
  * `types` entry has an absent type, a key typed `null` has AD-31's
  * indeterminate one, and both are relevant, so declaring an input and leaving
  * it untyped buys no irrelevance.

package/dist/core/coverage/relevance.js

@@ -1,4 +1,4 @@
-import { TRANSPORT_CHANNELS } from '../schemas/pointer.js';
+import { resolveOperations } from './operations.js';
 import { DISCIPLINE_RULES, relevancePredicateId, } from './rules.js';
 const verdict = (rule, relevant, reason) => ({
     rule,
@@ -8,8 +8,6 @@ const verdict = (rule, relevant, reason) => ({
 });
 /** `1 collection location`, `2 collection locations`. A reason is read by people. */
 const plural = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
-/** Every declared operation, flattened. Six of the seven rules range over this list. */
-const operationsOf = (contract) => contract.permittedInterfaces.flatMap((declared) => declared.operations);
 /** A contract declaring no operation leaves six of the rules nothing to read. */
 export const NO_OPERATION = 'the contract declares no operation, so the declaration this rule reads is absent';
 /**
@@ -20,11 +18,11 @@ export const NO_OPERATION = 'the contract declares no operation, so the declarat
  */
 export function successIndicatorSeparationRelevance(contract) {
     const rule = 'success-indicator-separation';
-    const operations = operationsOf(contract);
+    const operations = resolveOperations(contract);
     if (operations.length === 0)
         return verdict(rule, true, NO_OPERATION);
-    for (const operation of operations) {
-        const { successIndicator, channelRoles } = operation.responseDescriptor;
+    for (const { operation, descriptor } of operations) {
+        const { successIndicator, channelRoles } = descriptor;
         // `=== null`: `DescriptorPointer` admits the empty string, which
         // nominates the whole response body.
         if (successIndicator === null) {
@@ -48,11 +46,11 @@ export function successIndicatorSeparationRelevance(contract) {
  */
 export function wholeBodyRelevance(contract) {
     const rule = 'whole-body';
-    const operations = operationsOf(contract);
+    const operations = resolveOperations(contract);
     if (operations.length === 0)
         return verdict(rule, true, NO_OPERATION);
-    for (const operation of operations) {
-        const distinct = new Set(operation.responseDescriptor.requiredKeys);
+    for (const { operation, descriptor } of operations) {
+        const distinct = new Set(descriptor.requiredKeys);
         if (distinct.size > 1) {
             return verdict(rule, true, `operation ${operation.operationId} declares ${plural(distinct.size, 'distinct required response key')}`);
         }
@@ -60,20 +58,21 @@ export function wholeBodyRelevance(contract) {
     return verdict(rule, false, 'no operation declares more than one distinct required response key');
 }
 /**
- * Rule 3: some operation declares a request key on any of AD-19's four
- * transport channels. The site is the whole channel triple. A key with no
+ * Rule 3: some operation declares a request key on any of its own input
+ * channels, AD-19's four transport channels off an interface that speaks HTTP
+ * and the four command channels off one that does not. The site is the whole
+ * channel triple. A key with no
  * `types` entry has an absent type, a key typed `null` has AD-31's
  * indeterminate one, and both are relevant, so declaring an input and leaving
  * it untyped buys no irrelevance.
  */
 export function malformedInputRelevance(contract) {
     const rule = 'malformed-input';
-    const operations = operationsOf(contract);
+    const operations = resolveOperations(contract);
     if (operations.length === 0)
         return verdict(rule, true, NO_OPERATION);
-    for (const operation of operations) {
-        for (const channel of TRANSPORT_CHANNELS) {
-            const shape = operation.requestShape[channel];
+    for (const { operation, requestChannels } of operations) {
+        for (const { channel, shape } of requestChannels) {
             // `Object.keys` enumerates own keys only. `KeyName` admits
             // `constructor`, which a keyed lookup would find on the prototype.
             const key = shape.requiredKeys[0] ??
@@ -92,11 +91,11 @@ export function malformedInputRelevance(contract) {
  */
 export function perRecordRelevance(contract) {
     const rule = 'per-record';
-    const operations = operationsOf(contract);
+    const operations = resolveOperations(contract);
     if (operations.length === 0)
         return verdict(rule, true, NO_OPERATION);
-    for (const operation of operations) {
-        const { collectionLocations } = operation.responseDescriptor;
+    for (const { operation, descriptor } of operations) {
+        const { collectionLocations } = descriptor;
         if (collectionLocations === null) {
             return verdict(rule, true, `operation ${operation.operationId} declares no collection-location list, so no collection is declared to range over`);
         }
@@ -132,11 +131,11 @@ export function siblingCrossCheckRelevance(contract) {
  */
 export function omissionAndCompletenessRelevance(contract) {
     const rule = 'omission-and-completeness';
-    const operations = operationsOf(contract);
+    const operations = resolveOperations(contract);
     if (operations.length === 0)
         return verdict(rule, true, NO_OPERATION);
-    for (const operation of operations) {
-        const { collectionLocations } = operation.responseDescriptor;
+    for (const { operation, descriptor } of operations) {
+        const { collectionLocations } = descriptor;
         if (collectionLocations === null) {
             return verdict(rule, true, `operation ${operation.operationId} declares no collection-location list, so no location can name a reference set`);
         }
@@ -155,10 +154,10 @@ export function omissionAndCompletenessRelevance(contract) {
  */
 export function stateChangeReadBackRelevance(contract) {
     const rule = 'state-change-read-back';
-    const operations = operationsOf(contract);
+    const operations = resolveOperations(contract);
     if (operations.length === 0)
         return verdict(rule, true, NO_OPERATION);
-    for (const operation of operations) {
+    for (const { operation } of operations) {
         if (operation.stateChangeMarker) {
             return verdict(rule, true, `operation ${operation.operationId} declares stateChangeMarker: true`);
         }

package/dist/core/coverage/satisfaction.d.ts

@@ -1,7 +1,7 @@
 import { type EvalContract } from '../schemas/eval-contract.ts';
 import type { Expression } from '../schemas/expression.ts';
-import type { Operation } from '../schemas/interface.ts';
 import { type PlanIndex } from '../seal/plan-index.ts';
+import { type ResolvedOperation } from './operations.ts';
 import { type DisciplineRule } from './rules.ts';
 export type SatisfactionVerdict = {
     readonly rule: DisciplineRule;
@@ -40,7 +40,7 @@ type OracleView = {
  * own, which is what every per-rule fixture does.
  */
 export type SatisfactionContext = {
-    readonly operations: readonly Operation[];
+    readonly operations: readonly ResolvedOperation[];
     readonly index: PlanIndex;
     readonly oracles: readonly OracleView[];
 };

package/dist/core/coverage/satisfaction.js

@@ -12,9 +12,11 @@
  * the artifact still ships (AD-5), so there is no failure code.
  */
 import { substitutePointer } from '../compile/oracle-alignment.js';
+import { boundChannelsOf } from '../declared-inputs.js';
 import { SIBLING_GROUP_MINIMUM, } from '../schemas/eval-contract.js';
-import { TRANSPORT_CHANNELS } from '../schemas/pointer.js';
-import { buildPlanIndex } from '../seal/plan-index.js';
+import { INPUT_CHANNELS } from '../schemas/pointer.js';
+import { anyOperationOf, buildPlanIndex, } from '../seal/plan-index.js';
+import { encodeToken, resolveOperations, } from './operations.js';
 import { DISCIPLINE_RULES, satisfactionPredicateId, } from './rules.js';
 const verdict = (rule, satisfied, reason) => ({
     rule,
@@ -26,21 +28,22 @@ const verdict = (rule, satisfied, reason) => ({
 export const NO_RELEVANT_SITE = 'the rule is relevant for no site, so satisfaction holds vacuously';
 /** A contract declaring no operation leaves six of the rules an absent site. */
 export const NO_OPERATION_WITNESS = 'the contract declares no operation, so the site this rule fires on has no declaration to witness';
-/** Every declared operation, flattened. `relevance.ts` keeps its own copy. */
-const operationsOf = (contract) => contract.permittedInterfaces.flatMap((declared) => declared.operations);
 /** `unresolved` never throws; a duplicate identifier resolves to nothing. */
 const planIndexOf = (contract) => buildPlanIndex(contract.interactionPlan, contract.permittedInterfaces, {
     duplicateIds: 'unresolved',
 });
 // ---- the join between the two pointer spellings -------------------------
-/** RFC 6901 escaping, `~` before `/`. */
-const encodeToken = (token) => token.replace(/~/g, '~0').replace(/\//g, '~1');
 /** Everything one step produced or was given. */
 const stepRoot = (stepId) => `/interactions/${stepId}`;
-/** A descriptor pointer read at one step, spelled interaction-rooted. */
-const bodyPointer = (stepId, descriptorPointer) => `/interactions/${stepId}/response-body${descriptorPointer}`;
-/** One declared response key at one step. */
-const keyPointer = (stepId, key) => `/interactions/${stepId}/response-body/${encodeToken(key)}`;
+/**
+ * A descriptor pointer read at one step, spelled interaction-rooted. The root
+ * travels on the resolved operation, so an interface kind whose response
+ * arrives on another channel is one change in `operations.ts` and none at the
+ * five call sites below.
+ */
+const bodyPointer = (resolved, stepId, descriptorPointer) => `${stepRoot(stepId)}${resolved.descriptorRoot}${descriptorPointer}`;
+/** One declared response key at one step, rooted the way `bodyPointer` is. */
+const keyPointer = (resolved, stepId, key) => `${stepRoot(stepId)}${resolved.descriptorRoot}/${encodeToken(key)}`;
 /** One declared parameter on one transport channel at one step. */
 const parameterPointer = (stepId, channel, key) => `/interactions/${stepId}/call-inputs/${channel}/${encodeToken(key)}`;
 /** A pointer addresses a root when it names it or descends into it. */
@@ -113,7 +116,7 @@ const bothChannelsAddress = (oracle, root) => someAddresses(oracle.directionTarg
     someAddresses(oracle.checkPointers, root);
 const definedPointers = (node) => node.operandPointers.filter((pointer) => pointer !== null);
 const contextOf = (contract) => ({
-    operations: operationsOf(contract),
+    operations: resolveOperations(contract),
     index: planIndexOf(contract),
     oracles: oracleViewsOf(contract),
 });
@@ -130,8 +133,9 @@ export function successIndicatorSeparationSatisfaction(contract, context = conte
     if (operations.length === 0)
         return verdict(rule, false, NO_OPERATION_WITNESS);
     let sites = 0;
-    for (const operation of operations) {
-        const { successIndicator, channelRoles } = operation.responseDescriptor;
+    for (const resolved of operations) {
+        const { operation, descriptor } = resolved;
+        const { successIndicator, channelRoles } = descriptor;
         if (successIndicator === null) {
             return verdict(rule, false, `operation ${operation.operationId} nominates no success indicator, so no oracle can separate one from the body`);
         }
@@ -147,8 +151,8 @@ export function successIndicatorSeparationSatisfaction(contract, context = conte
             .map(([pointer]) => pointer);
         const witnessed = index
             .stepsUsing(operation.operationId)
-            .some((step) => oracles.some((oracle) => bothChannelsAddress(oracle, bodyPointer(step.stepId, successIndicator)) &&
-            others.some((pointer) => bothChannelsAddress(oracle, bodyPointer(step.stepId, pointer)))));
+            .some((step) => oracles.some((oracle) => bothChannelsAddress(oracle, bodyPointer(resolved, step.stepId, successIndicator)) &&
+            others.some((pointer) => bothChannelsAddress(oracle, bodyPointer(resolved, step.stepId, pointer)))));
         if (!witnessed) {
             return verdict(rule, false, `no oracle addresses operation ${operation.operationId}'s success indicator beside another roled pointer at one step, in both channels`);
         }
@@ -169,14 +173,15 @@ export function wholeBodySatisfaction(contract, context = contextOf(contract)) {
     if (operations.length === 0)
         return verdict(rule, false, NO_OPERATION_WITNESS);
     let sites = 0;
-    for (const operation of operations) {
-        const required = [...new Set(operation.responseDescriptor.requiredKeys)];
+    for (const resolved of operations) {
+        const { operation, descriptor } = resolved;
+        const required = [...new Set(descriptor.requiredKeys)];
         if (required.length <= 1)
             continue;
         sites += 1;
         const witnessed = index
             .stepsUsing(operation.operationId)
-            .some((step) => oracles.some((oracle) => required.every((key) => bothChannelsAddress(oracle, keyPointer(step.stepId, key)))));
+            .some((step) => oracles.some((oracle) => required.every((key) => bothChannelsAddress(oracle, keyPointer(resolved, step.stepId, key)))));
         if (!witnessed) {
             return verdict(rule, false, `no oracle covers every required response key of operation ${operation.operationId} at one addressed step, in both channels`);
         }
@@ -185,19 +190,19 @@ export function wholeBodySatisfaction(contract, context = contextOf(contract)) {
         ? NO_RELEVANT_SITE
         : 'every operation declaring more than one required response key has an oracle covering all of them at one step');
 }
-/** The site condition rule 3 relevance reads: a key on any of the four channels. */
-const declaresRequestKey = (operation) => TRANSPORT_CHANNELS.some((channel) => {
-    const shape = operation.requestShape[channel];
-    return (shape.requiredKeys.length > 0 ||
-        shape.permittedKeys.length > 0 ||
-        Object.keys(shape.types).length > 0);
-});
-/** AD-39's matcher, on any transport channel of one step. */
-const bindsTypeViolating = (step) => TRANSPORT_CHANNELS.some((channel) => {
-    const binding = step.inputBinding[channel];
-    if (binding === null)
+/** The site condition rule 3 relevance reads: a key on any input channel. */
+const declaresRequestKey = (resolved) => resolved.requestChannels.some(({ shape }) => shape.requiredKeys.length > 0 ||
+    shape.permittedKeys.length > 0 ||
+    Object.keys(shape.types).length > 0);
+/**
+ * AD-39's matcher, on any input channel of one step. The step carries no
+ * operation, so the bound channels are read off the binding itself rather than
+ * off a channel tuple that would name four channels the binding does not have.
+ */
+const bindsTypeViolating = (step) => boundChannelsOf(step.inputBinding).some(({ bound }) => {
+    if (bound === null)
         return false;
-    return Object.values(binding).some((value) => 'matcher' in value && value.matcher === 'type-violating');
+    return Object.values(bound).some((value) => 'matcher' in value && value.matcher === 'type-violating');
 });
 /**
  * Rule 3: for every operation declaring a request key, some step invoking it
@@ -211,8 +216,9 @@ export function malformedInputSatisfaction(contract, context = contextOf(contrac
     if (operations.length === 0)
         return verdict(rule, false, NO_OPERATION_WITNESS);
     let sites = 0;
-    for (const operation of operations) {
-        if (!declaresRequestKey(operation))
+    for (const resolved of operations) {
+        const { operation } = resolved;
+        if (!declaresRequestKey(resolved))
             continue;
         sites += 1;
         const witnessed = index
@@ -240,8 +246,9 @@ export function perRecordSatisfaction(contract, context = contextOf(contract)) {
     if (operations.length === 0)
         return verdict(rule, false, NO_OPERATION_WITNESS);
     let sites = 0;
-    for (const operation of operations) {
-        const { collectionLocations } = operation.responseDescriptor;
+    for (const resolved of operations) {
+        const { operation, descriptor } = resolved;
+        const { collectionLocations } = descriptor;
         if (collectionLocations === null) {
             return verdict(rule, false, `operation ${operation.operationId} declares no collection-location list, so no quantifier can range over a declared collection`);
         }
@@ -249,7 +256,7 @@ export function perRecordSatisfaction(contract, context = contextOf(contract)) {
         for (const location of collectionLocations) {
             sites += 1;
             const witnessed = steps.some((step) => {
-                const collection = bodyPointer(step.stepId, location.pointer);
+                const collection = bodyPointer(resolved, step.stepId, location.pointer);
                 return oracles.some((oracle) => oracle.nodes.some((node) => node.collection === collection));
             });
             if (!witnessed) {
@@ -289,7 +296,13 @@ export function siblingCrossCheckSatisfaction(contract, context = contextOf(cont
     for (const group of groups.parameters) {
         sites += 1;
         const members = [...new Set(group)];
-        const witnessed = oracles.some((oracle) => members.filter((parameter) => contract.interactionPlan.some((step) => TRANSPORT_CHANNELS.some((channel) => bothChannelsAddress(oracle, parameterPointer(step.stepId, channel, parameter))))).length >= SIBLING_GROUP_MINIMUM);
+        const witnessed = oracles.some((oracle) => members.filter((parameter) => contract.interactionPlan.some((step) => 
+        // Building candidate pointers, not reading a declared
+        // shape: `groups.parameters` carries no operation, so
+        // every input channel is tried and whichever one the
+        // oracle actually addresses is the match. It looks
+        // identical to `declaresRequestKey` above and is not.
+        INPUT_CHANNELS.some((channel) => bothChannelsAddress(oracle, parameterPointer(step.stepId, channel, parameter))))).length >= SIBLING_GROUP_MINIMUM);
         if (!witnessed) {
             return verdict(rule, false, `no oracle addresses two members of the parameter sibling group ${members.join(' and ')} in both channels`);
         }
@@ -330,8 +343,9 @@ export function omissionAndCompletenessSatisfaction(contract, context = contextO
     if (operations.length === 0)
         return verdict(rule, false, NO_OPERATION_WITNESS);
     let sites = 0;
-    for (const operation of operations) {
-        const { collectionLocations } = operation.responseDescriptor;
+    for (const resolved of operations) {
+        const { operation, descriptor } = resolved;
+        const { collectionLocations } = descriptor;
         if (collectionLocations === null) {
             return verdict(rule, false, `operation ${operation.operationId} declares no collection-location list, so no location can be reconciled against a reference set`);
         }
@@ -342,7 +356,7 @@ export function omissionAndCompletenessSatisfaction(contract, context = contextO
                 continue;
             sites += 1;
             const witnessed = steps.some((step) => {
-                const collection = bodyPointer(step.stepId, location.pointer);
+                const collection = bodyPointer(resolved, step.stepId, location.pointer);
                 return oracles.some((oracle) => oracle.nodes.some((node) => reconciles(node, collection, location, referenceSet)));
             });
             if (!witnessed) {
@@ -355,17 +369,28 @@ export function omissionAndCompletenessSatisfaction(contract, context = contextO
         : 'every collection location naming a reference set is reconciled against it in the declared form');
 }
 /** AD-39: a read-back step names the write in its temporal clause and changes no state itself. */
-const readBackStepsFor = (contract, index, writeStepId) => contract.interactionPlan.filter((step) => {
+const readBackStepsFor = (contract, context, writeStepId) => contract.interactionPlan.flatMap((step) => {
     if (step.stepId === writeStepId || step.after !== writeStepId)
-        return false;
-    const operation = index.operationOf(step.operationId);
-    return operation !== undefined && !operation.stateChangeMarker;
+        return [];
+    const operation = anyOperationOf(context.index, step.operationId);
+    if (operation === undefined || operation.stateChangeMarker)
+        return [];
+    // The index and the resolver both read `permittedInterfaces`, so the
+    // index answers with the very object the resolver carries. Matching on
+    // identity leaves the index's duplicate-identifier rule as the one
+    // thing deciding which operations resolve.
+    return context.operations
+        .filter((resolved) => resolved.operation === operation)
+        .map((resolved) => ({ step, resolved }));
 });
 /** One node holding a pointer into each side of the read-back relation. */
-const relates = (node, writeStepId, readStepId) => {
+const relates = (node, writeStepId, readBack) => {
     const pointers = definedPointers(node);
-    return (someAddresses(pointers, `${stepRoot(writeStepId)}/call-inputs`) &&
-        someAddresses(pointers, `${stepRoot(readStepId)}/response-body`));
+    return (
+    // `call-inputs` is the same segment for every interface kind, so the
+    // write side takes no root from its operation.
+    someAddresses(pointers, `${stepRoot(writeStepId)}/call-inputs`) &&
+        someAddresses(pointers, `${stepRoot(readBack.step.stepId)}${readBack.resolved.descriptorRoot}`));
 };
 /**
  * Rule 7: for every operation declaring `stateChangeMarker: true`, some check
@@ -380,13 +405,13 @@ export function stateChangeReadBackSatisfaction(contract, context = contextOf(co
     if (operations.length === 0)
         return verdict(rule, false, NO_OPERATION_WITNESS);
     let sites = 0;
-    for (const operation of operations) {
+    for (const { operation } of operations) {
         if (!operation.stateChangeMarker)
             continue;
         sites += 1;
         const witnessed = index
             .stepsUsing(operation.operationId)
-            .some((writeStep) => readBackStepsFor(contract, index, writeStep.stepId).some((readStep) => oracles.some((oracle) => oracle.nodes.some((node) => relates(node, writeStep.stepId, readStep.stepId)))));
+            .some((writeStep) => readBackStepsFor(contract, context, writeStep.stepId).some((readBack) => oracles.some((oracle) => oracle.nodes.some((node) => relates(node, writeStep.stepId, readBack)))));
         if (!witnessed) {
             return verdict(rule, false, `no check relates operation ${operation.operationId}'s call inputs to the response body of a later step that changes no state`);
         }

package/dist/core/declared-inputs.d.ts

@@ -1,16 +1,95 @@
 /**
- * What an operation declares it accepts, as predicates over `RequestShape`.
+ * What an operation declares it accepts, as predicates over a request shape,
+ * plus the resolution that lets a caller read one without knowing its kind.
  *
  * At the `core/` root because `core/schemas/` holds Zod definitions only, and
  * because AD-10's exemption is read by two modules: the compile check that
  * enforces it and the reducer that records it.
  */
-import type { Operation } from './schemas/interface.ts';
+import type { AnyOperation, CommandOperation, Operation } from './schemas/interface.ts';
+import type { BindingChannel, InputBinding } from './schemas/plan.ts';
+import { type EvidenceChannelName, type InputChannelName } from './schemas/pointer.ts';
+import type { KeyedShapeDescriptor } from './schemas/primitives.ts';
+/**
+ * Which output channel the operation's one response descriptor describes.
+ *
+ * AD-19 gives every operation exactly one descriptor, and the channel that
+ * descriptor describes is what makes its keys addressable. For an interface
+ * that speaks HTTP that channel is the response body; a command operation
+ * declares its own. One rule, three roots: every consumer that used to hard-code
+ * `response-body` asks this instead.
+ */
+export declare const descriptorChannelOf: (operation: AnyOperation) => EvidenceChannelName;
+/**
+ * Which artifact the descriptor describes, or `null` when it describes a
+ * stream. An artifact pointer descends through the descriptor only when it
+ * names this one; every other declared artifact is known to exist and declares
+ * no structure.
+ */
+export declare const descriptorArtifactOf: (operation: AnyOperation) => string | null;
+/**
+ * Whether an evidence target addresses the channel this operation's response
+ * descriptor describes.
+ *
+ * The channel name alone is not the answer on the artifact channel: an
+ * operation may declare several files while its one descriptor describes one of
+ * them, so a pointer at a different file names a channel with no declared
+ * structure. Every consumer asks this rather than comparing the channel itself,
+ * because comparing only the channel was a defect at three separate sites and a
+ * fourth site would have made the same mistake for the same reason.
+ */
+export declare const targetsDescribedChannel: (operation: AnyOperation, target: {
+    readonly channel: EvidenceChannelName;
+    readonly artifactId: string | null;
+}) => boolean;
+/** Every artifact identifier the operation declares it writes. */
+export declare const declaredArtifactsOf: (operation: AnyOperation) => readonly string[];
+/** One declared input channel with the shape it declares, already paired. */
+export type RequestChannel = {
+    readonly channel: InputChannelName;
+    readonly shape: KeyedShapeDescriptor;
+};
+/**
+ * Which operation shape this is. Reads `invocation` rather than a kind field,
+ * because an operation does not carry its interface's kind; the two shapes are
+ * distinguished by a required field only one of them declares.
+ */
+export declare const isCommandOperation: (operation: AnyOperation) => operation is CommandOperation;
+/** The same question the other way round, for the callers that filter. */
+export declare const isApiOperation: (operation: AnyOperation) => operation is Operation;
+/**
+ * The operation's input channels paired with the shapes they declare.
+ *
+ * Callers take the pairs rather than a channel list they then index the
+ * request shape with. Indexing is what breaks under the operation union:
+ * TypeScript cannot prove that a channel name drawn from one kind's tuple is a
+ * key of the other kind's shape, and both ways around that are casts. Pairing
+ * dereferences the union once, here.
+ */
+export declare function requestChannelsOf(operation: AnyOperation): readonly RequestChannel[];
+/** The shape one named channel declares, or `undefined` off this kind. */
+export declare function requestShapeOf(operation: AnyOperation, channel: InputChannelName): KeyedShapeDescriptor | undefined;
+/** The channel names an operation of this kind may declare inputs on. */
+export declare const inputChannelsOf: (operation: AnyOperation) => readonly InputChannelName[];
+/**
+ * A step's bound channels paired with what each binds, for the same reason
+ * `requestChannelsOf` pairs: `InputBinding` is a union and a channel name
+ * drawn from one branch is not a key of the other.
+ *
+ * Ordered by `INPUT_CHANNELS` rather than by the parsed object's own key
+ * order, so which binding a check reports never depends on how the document
+ * happened to be written.
+ */
+export declare function boundChannelsOf(binding: InputBinding): readonly {
+    readonly channel: InputChannelName;
+    readonly bound: BindingChannel;
+}[];
 /**
  * AD-10's exemption predicate. Any of a channel's three lists naming a key
  * counts: a permitted-only or types-only channel is still a surface a witness
  * can vary.
  */
-export declare function declaresNoRequestKeys(operation: Operation): boolean;
+export declare function declaresNoRequestKeys(operation: AnyOperation): boolean;
 /** Whether no channel declares a required key. */
-export declare function declaresNoRequiredKeys(operation: Operation): boolean;
+export declare function declaresNoRequiredKeys(operation: AnyOperation): boolean;
+export type { AnyOperation, CommandOperation, Operation };