eval-quality 0.2.0 → 0.3.0

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 };

package/dist/core/declared-inputs.js

@@ -1,18 +1,115 @@
-import { TRANSPORT_CHANNELS } from './schemas/pointer.js';
+import { COMMAND_CHANNELS, INPUT_CHANNELS, TRANSPORT_CHANNELS, } from './schemas/pointer.js';
+/**
+ * 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 const descriptorChannelOf = (operation) => {
+    if (!isCommandOperation(operation))
+        return 'response-body';
+    const { descriptorChannel } = operation;
+    return descriptorChannel.kind === 'stream'
+        ? descriptorChannel.channel
+        : 'artifact';
+};
+/**
+ * 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 const descriptorArtifactOf = (operation) => {
+    if (!isCommandOperation(operation))
+        return null;
+    const { descriptorChannel } = operation;
+    return descriptorChannel.kind === 'artifact'
+        ? descriptorChannel.artifactId
+        : 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 const targetsDescribedChannel = (operation, target) => {
+    if (target.channel !== descriptorChannelOf(operation))
+        return false;
+    if (target.channel !== 'artifact')
+        return true;
+    return target.artifactId === descriptorArtifactOf(operation);
+};
+/** Every artifact identifier the operation declares it writes. */
+export const declaredArtifactsOf = (operation) => isCommandOperation(operation) ? operation.artifacts : [];
+/**
+ * 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 const isCommandOperation = (operation) => 'invocation' in operation;
+/** The same question the other way round, for the callers that filter. */
+export const isApiOperation = (operation) => !isCommandOperation(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 function requestChannelsOf(operation) {
+    if (isCommandOperation(operation)) {
+        return COMMAND_CHANNELS.map((channel) => ({
+            channel,
+            shape: operation.requestShape[channel],
+        }));
+    }
+    return TRANSPORT_CHANNELS.map((channel) => ({
+        channel,
+        shape: operation.requestShape[channel],
+    }));
+}
+/** The shape one named channel declares, or `undefined` off this kind. */
+export function requestShapeOf(operation, channel) {
+    return requestChannelsOf(operation).find((entry) => entry.channel === channel)
+        ?.shape;
+}
+/** The channel names an operation of this kind may declare inputs on. */
+export const inputChannelsOf = (operation) => isCommandOperation(operation) ? COMMAND_CHANNELS : TRANSPORT_CHANNELS;
+/**
+ * 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 function boundChannelsOf(binding) {
+    const present = binding;
+    return INPUT_CHANNELS.filter((channel) => channel in binding).map((channel) => ({ channel, bound: present[channel] ?? null }));
+}
 /**
  * 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 function declaresNoRequestKeys(operation) {
-    return TRANSPORT_CHANNELS.every((channel) => {
-        const shape = operation.requestShape[channel];
-        return (shape.requiredKeys.length === 0 &&
-            shape.permittedKeys.length === 0 &&
-            Object.keys(shape.types).length === 0);
-    });
+    return requestChannelsOf(operation).every(({ shape }) => shape.requiredKeys.length === 0 &&
+        shape.permittedKeys.length === 0 &&
+        Object.keys(shape.types).length === 0);
 }
 /** Whether no channel declares a required key. */
 export function declaresNoRequiredKeys(operation) {
-    return TRANSPORT_CHANNELS.every((channel) => operation.requestShape[channel].requiredKeys.length === 0);
+    return requestChannelsOf(operation).every(({ shape }) => shape.requiredKeys.length === 0);
 }

package/dist/core/evaluate/evidence-resolution.d.ts

@@ -9,7 +9,7 @@ import type { EvalContract } from '../schemas/eval-contract.ts';
 import type { JsonValue } from '../schemas/primitives.ts';
 import type { Observation } from '../schemas/sealed-run-record.ts';
 import { type EvidenceTarget, type PlanIndex } from '../seal/plan-index.ts';
-import type { PointerDenotesCollection, ResolveOperand } from './resolution.ts';
+import type { PointerDenotesCollection, ReferenceSetKeys, ResolveOperand } from './resolution.ts';
 import { type ResolvedValue } from './resolved-value.ts';
 /**
  * A canonical RFC 6901 array-index token: no leading zero except "0" itself,
@@ -26,7 +26,7 @@ export declare const ARRAY_INDEX_PATTERN: RegExp;
  * falls through to `Object.prototype`. Any miss, type mismatch, or tail
  * running past a scalar collapses to `ABSENT` uniformly (AD-26).
  */
-export declare function walkTail(root: JsonValue, tail: readonly string[]): ResolvedValue;
+export declare function walkTail(root: ResolvedValue, tail: readonly string[]): ResolvedValue;
 /**
  * Decodes `BoundElementPointer`'s tail. "@/" is the shortest legal pointer
  * form and denotes the element itself. `decodeTail` special-cases only a
@@ -34,16 +34,7 @@ export declare function walkTail(root: JsonValue, tail: readonly string[]): Reso
  * calling it.
  */
 export declare function decodeBoundElementTail(pointer: string): readonly string[];
-/**
- * Selects the channel `target` names off one `Observation`. `stdout`/`stderr`
- * can carry a tail even though they're bare strings; `walkTail` already
- * resolves any non-empty tail against a string to `ABSENT`, so no special
- * case is needed here.
- *
- * Exported so `core/score/bindings.ts` reads a captured pointer's channel off
- * an observation through this one spelling, keeping the switch in one place.
- */
-export declare function channelRoot(observation: Observation, target: EvidenceTarget): JsonValue;
+export declare function channelRoot(observation: Observation, target: EvidenceTarget): ResolvedValue;
 /**
  * The `ResolveOperand`. `stepObservations` holds one already-selected
  * `Observation` per interaction step; `referenceSets` mirrors the contract's
@@ -52,6 +43,12 @@ export declare function channelRoot(observation: Observation, target: EvidenceTa
  * prototype-chain gotcha `walkTail` guards against.
  */
 export declare function makeResolveOperand(stepObservations: Readonly<Record<string, Observation>>, referenceSets: Readonly<Record<string, JsonValue[]>>): ResolveOperand;
+/**
+ * The `keys` a contract's reference sets declare. Built from the same
+ * `contract.referenceSets` the members map handed to `makeResolveOperand` is
+ * built from, so a set that resolves to members always has its keys here.
+ */
+export declare function referenceSetKeysOf(contract: EvalContract): ReferenceSetKeys;
 /**
  * Only `response-body` can ever answer `true` (AD-19: `collectionLocations`
  * is the only declared-collection surface, scoped to the body alone). The

package/dist/core/evaluate/evidence-resolution.js

@@ -5,7 +5,8 @@
  * bound-element `@/` form, and walk it into an already-selected
  * `Observation`.
  */
-import { buildPlanIndex, decodeTail, parseEvidenceTarget, } from '../seal/plan-index.js';
+import { targetsDescribedChannel } from '../declared-inputs.js';
+import { anyOperationOf, buildPlanIndex, decodeTail, parseEvidenceTarget, } from '../seal/plan-index.js';
 import { ABSENT } from './resolved-value.js';
 /**
  * A canonical RFC 6901 array-index token: no leading zero except "0" itself,
@@ -23,6 +24,12 @@ export const ARRAY_INDEX_PATTERN = /^(?:0|[1-9][0-9]*)$/;
  * running past a scalar collapses to `ABSENT` uniformly (AD-26).
  */
 export function walkTail(root, tail) {
+    // A root that did not resolve stays unresolved however short the tail is.
+    // The bare-pointer case is the one that matters: without this, an absent
+    // channel with no tail returned its own root and a caller could not tell it
+    // from a resolved value.
+    if (root === ABSENT)
+        return ABSENT;
     let current = root;
     for (const token of tail) {
         if (current === null || typeof current !== 'object')
@@ -53,14 +60,29 @@ export function decodeBoundElementTail(pointer) {
     return tailSource === '/' ? [] : decodeTail(tailSource);
 }
 /**
- * Selects the channel `target` names off one `Observation`. `stdout`/`stderr`
- * can carry a tail even though they're bare strings; `walkTail` already
- * resolves any non-empty tail against a string to `ABSENT`, so no special
- * case is needed here.
+ * Selects the channel `target` names off one `Observation`.
+ *
+ * `stdout`, `stderr`, and each written artifact are tagged, so a channel a
+ * harness captured as JSON resolves to the value and a tail walks into it,
+ * while one captured as text resolves to the string and a tail over it
+ * resolves `ABSENT`. That is what makes a command operation's nominated output
+ * channel resolvable at score time on the same terms as a response body.
  *
  * Exported so `core/score/bindings.ts` reads a captured pointer's channel off
  * an observation through this one spelling, keeping the switch in one place.
  */
+/**
+ * The value a tagged observed channel resolves to.
+ *
+ * A JSON body resolves to the value itself, so a tail walks into it; text
+ * resolves to the string, so a tail over it resolves `ABSENT` through
+ * `walkTail`, which is the truthful answer for output nothing parsed. An absent
+ * channel resolves to `ABSENT` and never to `null`: the tag exists precisely to
+ * tell "nothing was observed here" from "a value that was JSON null", and
+ * collapsing the two would make `existence` answer true for a file the run
+ * never wrote, since AD-26 counts `null` as present.
+ */
+const observedValue = (body) => body.kind === 'absent' ? ABSENT : body.value;
 export function channelRoot(observation, target) {
     switch (target.channel) {
         case 'response-body':
@@ -70,9 +92,9 @@ export function channelRoot(observation, target) {
         case 'response-status':
             return observation.responseStatus;
         case 'stdout':
-            return observation.stdout;
+            return observedValue(observation.stdout);
         case 'stderr':
-            return observation.stderr;
+            return observedValue(observation.stderr);
         case 'exit-code':
             return observation.exitCode;
         case 'call-inputs': {
@@ -84,6 +106,27 @@ export function channelRoot(observation, target) {
             }
             return observation.callInputs[transportChannel];
         }
+        case 'artifact': {
+            const { artifactId } = target;
+            if (artifactId === null) {
+                // parseEvidenceTarget sets artifactId exactly when the channel
+                // is 'artifact', so this throw should never fire.
+                throw new TypeError('artifact evidence target names no artifact');
+            }
+            // `Object.hasOwn` for the reason this module's header gives for
+            // `stepObservations` and `referenceSets`: `Identifier` admits
+            // `constructor`, `toString` and `valueOf`, so a bare index on an
+            // unwritten file of one of those names resolves to an inherited
+            // function rather than to nothing.
+            //
+            // A file the run did not write is absent evidence, not a `null`
+            // value. `null` would read as present under AD-26 and invert every
+            // oracle asserting the file exists or does not.
+            if (!Object.hasOwn(observation.artifacts, artifactId))
+                return ABSENT;
+            const written = observation.artifacts[artifactId];
+            return written === undefined ? ABSENT : observedValue(written);
+        }
     }
 }
 /**
@@ -118,6 +161,17 @@ export function makeResolveOperand(stepObservations, referenceSets) {
         return walkTail(channelRoot(observation, target), target.tail);
     };
 }
+/**
+ * The `keys` a contract's reference sets declare. Built from the same
+ * `contract.referenceSets` the members map handed to `makeResolveOperand` is
+ * built from, so a set that resolves to members always has its keys here.
+ */
+export function referenceSetKeysOf(contract) {
+    return Object.fromEntries(Object.entries(contract.referenceSets ?? {}).map(([id, set]) => [
+        id,
+        set.keys,
+    ]));
+}
 function tokensEqual(a, b) {
     return a.length === b.length && a.every((token, index) => token === b[index]);
 }
@@ -140,14 +194,20 @@ export function makePointerDenotesCollection(contract, providedIndex) {
         if (pointer.startsWith('@'))
             return false;
         const target = parseEvidenceTarget(pointer);
-        if (target.channel !== 'response-body')
-            return false;
         const step = getIndex().stepOf(target.stepId);
         if (step === undefined)
             return false;
-        const operation = getIndex().operationOf(step.operationId);
+        const operation = anyOperationOf(getIndex(), step.operationId);
         if (operation === undefined)
             return false;
+        // The channel is tested against the operation's own descriptor rather
+        // than against `response-body`. AD-4's empty-collection resolution
+        // applies to whichever channel an operation says carries its declared
+        // collections, and hard-coding the body left it inapplicable to every
+        // command contract: a quantifier over an empty declared collection
+        // resolved `false` instead of `insufficient-evidence`.
+        if (!targetsDescribedChannel(operation, target))
+            return false;
         const { collectionLocations } = operation.responseDescriptor;
         if (collectionLocations === null)
             return false;