eval-quality 0.1.0

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

@@ -0,0 +1,232 @@
+/**
+ * AD-10's three declaration-side witness checks: that every input-bearing
+ * operation declares one, that a declared one is shaped so the plan can
+ * 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
+ * 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 { StructuralFailure } from '../failure-codes.js';
+import { TRANSPORT_CHANNELS, } from '../schemas/pointer.js';
+import { parseEvidenceTarget } from '../seal/plan-index.js';
+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.
+ */
+export function suppliedKeys(inputs, channel) {
+    if (channel !== 'body')
+        return Object.keys(inputs[channel]);
+    const { body } = inputs;
+    if (body.kind !== 'json')
+        return [];
+    const { value } = body;
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return [];
+    return Object.keys(value);
+}
+/**
+ * Every channel of one set of witness inputs against the operation that will
+ * receive them. All four, not only the differential channel: `planPreflight`
+ * copies all four onto the `ProbeRequest` and the port sends them, so a value
+ * on an unselected channel is as much an outbound value as one on the selected
+ * channel.
+ *
+ * The two directions have different standing, and the difference matters
+ * enough to name, because the next reader will diff this against
+ * `checkUndeclaredMandatoryInput` and find the two disagreeing.
+ *
+ * The permitted direction is that function's rule, carried over: it loops the
+ * same four channels and rejects a key the operation declares in neither list.
+ * That is what makes `WitnessInputs`'s AD-18 promise about `header` more than a
+ * comment.
+ *
+ * The required direction is new here, because the two shapes differ. An
+ * `InputBindingChannel` is nullable, and `null` means "this step binds nothing in
+ * this channel", so `checkUndeclaredMandatoryInput` skips an unbound channel and
+ * asks nothing about required keys. `WitnessInputs` has all four channels as
+ * concrete values, so a leg omitting a required key is a request the port cannot
+ * issue. The cost is that a required header forces a literal value into the
+ * contract artifact, the surface AD-18 governs; a placeholder satisfies this
+ * 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];
+        const supplied = suppliedKeys(inputs, channel);
+        for (const key of shape.requiredKeys) {
+            if (supplied.includes(key))
+                continue;
+            throw new StructuralFailure('undeclared-mandatory-input', artifactPath, `${owner} omits "${key}", which operation "${operation.operationId}" declares required in its ${channel} channel (AD-10)`);
+        }
+        const permitted = new Set([...shape.requiredKeys, ...shape.permittedKeys]);
+        for (const key of supplied) {
+            if (permitted.has(key))
+                continue;
+            throw new StructuralFailure('undeclared-mandatory-input', artifactPath, `${owner} supplies "${key}", which operation "${operation.operationId}" declares in neither requiredKeys nor permittedKeys of its ${channel} channel (AD-10, AD-18)`);
+        }
+    }
+}
+const operationPath = (interfaceIndex, operationIndex) => `EvalContract.permittedInterfaces[${interfaceIndex}].operations[${operationIndex}]`;
+function forEachWitness(contract, visit) {
+    contract.permittedInterfaces.forEach((iface, interfaceIndex) => {
+        iface.operations.forEach((operation, operationIndex) => {
+            const witness = operation.sensitivityWitness;
+            if (witness === null)
+                return;
+            visit(witness, operation, operationPath(interfaceIndex, operationIndex));
+        });
+    });
+}
+/**
+ * Strict-gated, alongside `checkUndeclaredMandatoryInput`, whose code this
+ * shares: `compile.ts` already gates that code behind `options.strict`, and one
+ * code with two gating regimes would be worse than one code with two
+ * conditions.
+ */
+export function checkSensitivityWitnessDeclared(contract) {
+    contract.permittedInterfaces.forEach((iface, interfaceIndex) => {
+        iface.operations.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)`);
+            }
+            witness.legs.forEach((leg, legIndex) => {
+                checkInputsAgainstShape(leg.inputs, operation, `leg "${leg.legId}"`, `${path}.sensitivityWitness.legs[${legIndex}]`);
+            });
+        });
+    });
+}
+/** every interaction-rooted step id an expression addresses, in walk order. */
+function addressedStepIds(expression) {
+    const found = new Set();
+    const visitOperand = (operand) => {
+        const { pointer } = operand;
+        if (pointer === undefined || pointer.startsWith('@'))
+            return;
+        found.add(parseEvidenceTarget(pointer).stepId);
+    };
+    const walk = (node) => {
+        switch (node.op) {
+            case 'not':
+            case 'all':
+            case 'any':
+                node.operands.forEach(walk);
+                return;
+            case 'for-all':
+            case 'for-any':
+                visitOperand(node.collection);
+                walk(node.predicate);
+                return;
+            default:
+                for (const operand of node.operands)
+                    visitOperand(operand);
+        }
+    };
+    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'];
+/**
+ * The shape rules: the differential channel agrees with the state-change
+ * marker, the relation reads both legs and nothing else, and a declared
+ * fixture reset names a mutating operation the contract declares. Unconditional,
+ * since none of these fires `undeclared-mandatory-input`.
+ */
+export function checkWitnessLegality(contract) {
+    forEachWitness(contract, (witness, operation, path) => {
+        const legal = legalChannels(operation);
+        if (!legal.includes(witness.channel)) {
+            throw new StructuralFailure('malformed-operator-expression', `${path}.sensitivityWitness`, `channel "${witness.channel}" contradicts stateChangeMarker ${operation.stateChangeMarker} on operation "${operation.operationId}"; AD-10 selects ${legal.map((name) => `"${name}"`).join(' or ')}`);
+        }
+        // AD-10's predicate is a differential. Two legs supplying the same values on
+        // the selected channel establish nothing, and at run time that surfaces as a
+        // `failed` check pointing at the fixture, when the defect is in the
+        // declaration.
+        const [first, second] = witness.legs;
+        if (first !== undefined &&
+            second !== undefined &&
+            JSON.stringify(first.inputs[witness.channel]) ===
+                JSON.stringify(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);
+        const addressed = addressedStepIds(witness.relation);
+        // Reported before the coverage rules: an unknown root is the more
+        // specific diagnosis, and a relation that reads a third step is
+        // unreachable evidence whether or not it also reads both legs.
+        for (const stepId of addressed) {
+            if (legIds.includes(stepId))
+                continue;
+            throw new StructuralFailure('unreachable-check-evidence', `${path}.sensitivityWitness.relation`, `the relation addresses "${stepId}", which is neither leg of witness "${witness.witnessId}" (AD-10)`);
+        }
+        const covered = legIds.filter((legId) => addressed.has(legId));
+        if (covered.length !== legIds.length) {
+            throw new StructuralFailure('malformed-operator-expression', `${path}.sensitivityWitness.relation`, `the relation addresses ${covered.length} of the two legs of witness "${witness.witnessId}"; a differential that reads one leg establishes no sensitivity (AD-10)`);
+        }
+    });
+    const reset = contract.fixtureReset;
+    if (reset === null)
+        return;
+    const iface = contract.permittedInterfaces.find((candidate) => candidate.logicalId === reset.interfaceId);
+    const operation = iface?.operations.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)`);
+    }
+    if (!operation.stateChangeMarker) {
+        throw new StructuralFailure('malformed-operator-expression', 'EvalContract.fixtureReset', `the fixture reset names operation "${reset.operationId}", whose stateChangeMarker is false; an operation that changes no state resets nothing (AD-10)`);
+    }
+    // The reset is one more leg through the same port, so its inputs answer to
+    // the same request shape every witness leg does.
+    checkInputsAgainstShape(reset.inputs, operation, 'the fixture reset', 'EvalContract.fixtureReset.inputs');
+}
+/**
+ * Leg identifiers share one namespace with interaction-plan step identifiers,
+ * because a witness relation is an ordinary AD-4 expression and addresses a leg
+ * as `/interactions/{legId}/…`. A collision would make a relation pointer
+ * resolve against the wrong observation.
+ */
+export function checkWitnessLegIdentifiers(contract) {
+    const stepIds = new Set(contract.interactionPlan.map((step) => step.stepId));
+    const seen = new Map();
+    const claim = (legId, owner, path) => {
+        if (stepIds.has(legId)) {
+            throw new StructuralFailure('malformed-operator-expression', path, `leg id "${legId}" collides with an interaction-plan step id; the two share one pointer namespace (AD-10, AD-26)`);
+        }
+        const previous = seen.get(legId);
+        if (previous !== undefined) {
+            throw new StructuralFailure('malformed-operator-expression', path, `leg id "${legId}" is already claimed by ${previous}; leg ids are unique across the contract (AD-10)`);
+        }
+        seen.set(legId, owner);
+    };
+    forEachWitness(contract, (witness, _operation, path) => {
+        const [first, second] = witness.legs;
+        if (first !== undefined &&
+            second !== undefined &&
+            first.legId === second.legId) {
+            throw new StructuralFailure('malformed-operator-expression', `${path}.sensitivityWitness.legs`, `both legs of witness "${witness.witnessId}" carry the leg id "${first.legId}", so the relation cannot tell them apart (AD-10)`);
+        }
+        witness.legs.forEach((leg, legIndex) => {
+            claim(leg.legId, `witness "${witness.witnessId}"`, `${path}.sensitivityWitness.legs[${legIndex}].legId`);
+        });
+    });
+    // The fixture reset is one more leg through the same port, so its id sits in
+    // the same namespace. AD-10 names no defect for the collision; the check is
+    // added here because two legs sharing a `probeId` would make the reducer read
+    // one leg's observation for the other.
+    const reset = contract.fixtureReset;
+    if (reset !== null)
+        claim(reset.legId, 'the fixture reset', 'EvalContract.fixtureReset.legId');
+}

package/dist/core/compile/waivers.d.ts

@@ -0,0 +1,3 @@
+import type { EvalContract } from '../schemas/eval-contract.ts';
+/** Reports the first missing required field. */
+export declare function checkWaiverCompleteness(contract: EvalContract): void;

package/dist/core/compile/waivers.js

@@ -0,0 +1,21 @@
+/**
+ * Checks each waiver for its rule, rationale, approval, and expiry.
+ * A condition is optional.
+ */
+import { StructuralFailure } from '../failure-codes.js';
+const REQUIRED_WAIVER_PARTS = [
+    'rule',
+    'rationale',
+    'approval',
+    'expiresAt',
+];
+/** Reports the first missing required field. */
+export function checkWaiverCompleteness(contract) {
+    for (const waiver of contract.waivers) {
+        for (const part of REQUIRED_WAIVER_PARTS) {
+            if (waiver[part] === null) {
+                throw new StructuralFailure('waiver-incomplete', `EvalContract.waivers[id=${waiver.id}].${part}`, `a waiver requires ${part}; AD-5 requires the named rule, an explicit rationale, the recorded approval, and an RFC 3339 expiry`);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,18 @@
+/**
+ * AD-31 coverage gaps: relevance fired and satisfaction failed. A satisfied
+ * rule gets no record, since AD-21 reads `coverageGaps` as the gap list.
+ * Nothing throws; AD-5 emits the artifact with the gap recorded, and only a
+ * structural error blocks compilation.
+ */
+import { type EvalContract, type Severity } from '../schemas/eval-contract.ts';
+import type { CoverageGap } from '../schemas/evidence-artifact.ts';
+export type CoverageGapRecord = CoverageGap;
+/**
+ * Highest declared behaviour severity. `behaviors` carries `.min(1)`, so this
+ * is total. The maximum, because the predicates are contract-level and
+ * oracle-blind: a lower reduction lets one trivial behaviour push every gap
+ * under AD-21's severity floor.
+ */
+export declare function coverageSeverity(contract: EvalContract): Severity;
+/** One record per gap, in `DISCIPLINE_RULES` order. Both arrays share it, so the pairing is positional. */
+export declare function evaluateCoverage(contract: EvalContract): readonly CoverageGapRecord[];

package/dist/core/coverage/coverage.js

@@ -0,0 +1,47 @@
+/**
+ * AD-31 coverage gaps: relevance fired and satisfaction failed. A satisfied
+ * rule gets no record, since AD-21 reads `coverageGaps` as the gap list.
+ * Nothing throws; AD-5 emits the artifact with the gap recorded, and only a
+ * structural error blocks compilation.
+ */
+import { SEVERITY_LEVELS, } from '../schemas/eval-contract.js';
+import { evaluateRelevance } from './relevance.js';
+import { evaluateSatisfaction } from './satisfaction.js';
+/**
+ * Highest declared behaviour severity. `behaviors` carries `.min(1)`, so this
+ * is total. The maximum, because the predicates are contract-level and
+ * oracle-blind: a lower reduction lets one trivial behaviour push every gap
+ * under AD-21's severity floor.
+ */
+export function coverageSeverity(contract) {
+    let rank = 0;
+    for (const behavior of contract.behaviors) {
+        rank = Math.max(rank, SEVERITY_LEVELS.indexOf(behavior.severity));
+    }
+    return SEVERITY_LEVELS[rank];
+}
+/** One record per gap, in `DISCIPLINE_RULES` order. Both arrays share it, so the pairing is positional. */
+export function evaluateCoverage(contract) {
+    const relevance = evaluateRelevance(contract);
+    const satisfaction = evaluateSatisfaction(contract);
+    const severity = coverageSeverity(contract);
+    const gaps = [];
+    // `!relevant.relevant` is unfalsifiable today: a rule relevant for no site
+    // answers satisfied vacuously, which fixture 168 pins over 23 contracts. It
+    // stays as the conjunction AD-31 states, so a predicate pair that broke the
+    // invariant cannot record a gap for a rule that never fired.
+    for (const [index, relevant] of relevance.entries()) {
+        const satisfied = satisfaction[index];
+        if (satisfied === undefined || !relevant.relevant || satisfied.satisfied) {
+            continue;
+        }
+        gaps.push({
+            rule: relevant.rule,
+            relevancePredicate: relevant.predicate,
+            satisfactionPredicate: satisfied.predicate,
+            satisfied: false,
+            severity,
+        });
+    }
+    return gaps;
+}

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

@@ -0,0 +1,75 @@
+/**
+ * AD-31's seven relevance predicates: decision procedures over AD-19's
+ * declarations. They read no run record, no probe, no outcome, no oracle.
+ *
+ * Nothing here throws. A coverage gap is recorded and the artifact still ships
+ * (AD-5), so there is no failure code. Failing closed means answering
+ * `relevant` on an absent declaration.
+ */
+import type { EvalContract } from '../schemas/eval-contract.ts';
+import { type DisciplineRule } from './rules.ts';
+export type RelevanceVerdict = {
+    readonly rule: DisciplineRule;
+    readonly predicate: string;
+    readonly relevant: boolean;
+    /** which declaration decided it, so a gap is diagnosable. */
+    readonly reason: string;
+};
+/** A contract declaring no operation leaves six of the rules nothing to read. */
+export declare const NO_OPERATION = "the contract declares no operation, so the declaration this rule reads is absent";
+/**
+ * Rule 1: `successIndicator` declared, and some other pointer carrying a
+ * channel role. An operation nominating no indicator is relevant, since a
+ * nullable pointer has two spellings and `null` is the absent one.
+ * `channelRoles: {}` answers the second conjunct.
+ */
+export declare function successIndicatorSeparationRelevance(contract: EvalContract): RelevanceVerdict;
+/**
+ * Rule 2: the descriptor declares more than one pointer, counted over distinct
+ * `requiredKeys`. That is the set rule 2's satisfaction denominator reads, and
+ * AD-20 keeps permitted keys out of coverage. Distinct, because `requiredKeys`
+ * carries no uniqueness constraint and one key repeated is one pointer.
+ */
+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
+ * `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 declare function malformedInputRelevance(contract: EvalContract): RelevanceVerdict;
+/**
+ * Rule 4: the descriptor declares at least one collection location. `null` is
+ * the absent state and is relevant; `[]` is the explicit empty answer.
+ */
+export declare function perRecordRelevance(contract: EvalContract): RelevanceVerdict;
+/**
+ * Rule 5: a sibling group over operations or parameters is non-empty. The one
+ * contract-level rule of the seven. A group of one cannot exist, since
+ * `SIBLING_GROUP_MINIMUM` is two.
+ */
+export declare function siblingCrossCheckRelevance(contract: EvalContract): RelevanceVerdict;
+/**
+ * Rule 6: a declared collection location names a reference set. The site is
+ * `collectionLocations` alone, so an explicitly empty list stays an answer. A
+ * location naming an identifier the contract does not declare still names one.
+ */
+export declare function omissionAndCompletenessRelevance(contract: EvalContract): RelevanceVerdict;
+/**
+ * Rule 7: some operation declares `stateChangeMarker: true`. The one rule with
+ * no absent state to grade, since the marker is a required boolean and both
+ * values are legal.
+ */
+export declare function stateChangeReadBackRelevance(contract: EvalContract): RelevanceVerdict;
+/**
+ * One predicate per rule. The mapped type fails the typecheck when a member of
+ * `DISCIPLINE_RULES` has no predicate. Same idiom as `operatorHandlers` in
+ * `core/evaluate/resolution.ts`, minus its `Object.hasOwn` guard: these keys
+ * come from a compile-time tuple, so a runtime guard is unreachable.
+ */
+export declare const RELEVANCE_PREDICATES: {
+    readonly [Rule in DisciplineRule]: (contract: EvalContract) => RelevanceVerdict;
+};
+/** All seven verdicts, in `DISCIPLINE_RULES` order, over declarations alone. */
+export declare function evaluateRelevance(contract: EvalContract): readonly RelevanceVerdict[];

package/dist/core/coverage/relevance.js

@@ -0,0 +1,186 @@
+import { TRANSPORT_CHANNELS } from '../schemas/pointer.js';
+import { DISCIPLINE_RULES, relevancePredicateId, } from './rules.js';
+const verdict = (rule, relevant, reason) => ({
+    rule,
+    predicate: relevancePredicateId(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';
+/**
+ * Rule 1: `successIndicator` declared, and some other pointer carrying a
+ * channel role. An operation nominating no indicator is relevant, since a
+ * nullable pointer has two spellings and `null` is the absent one.
+ * `channelRoles: {}` answers the second conjunct.
+ */
+export function successIndicatorSeparationRelevance(contract) {
+    const rule = 'success-indicator-separation';
+    const operations = operationsOf(contract);
+    if (operations.length === 0)
+        return verdict(rule, true, NO_OPERATION);
+    for (const operation of operations) {
+        const { successIndicator, channelRoles } = operation.responseDescriptor;
+        // `=== null`: `DescriptorPointer` admits the empty string, which
+        // nominates the whole response body.
+        if (successIndicator === null) {
+            return verdict(rule, true, `operation ${operation.operationId} nominates no success indicator`);
+        }
+        if (channelRoles === null) {
+            return verdict(rule, true, `operation ${operation.operationId} declares no channel roles`);
+        }
+        const other = Object.keys(channelRoles).find((pointer) => pointer !== successIndicator);
+        if (other !== undefined) {
+            return verdict(rule, true, `operation ${operation.operationId} gives pointer ${other} a channel role beside its success indicator`);
+        }
+    }
+    return verdict(rule, false, 'every operation nominates a success indicator and gives no other pointer a channel role');
+}
+/**
+ * Rule 2: the descriptor declares more than one pointer, counted over distinct
+ * `requiredKeys`. That is the set rule 2's satisfaction denominator reads, and
+ * AD-20 keeps permitted keys out of coverage. Distinct, because `requiredKeys`
+ * carries no uniqueness constraint and one key repeated is one pointer.
+ */
+export function wholeBodyRelevance(contract) {
+    const rule = 'whole-body';
+    const operations = operationsOf(contract);
+    if (operations.length === 0)
+        return verdict(rule, true, NO_OPERATION);
+    for (const operation of operations) {
+        const distinct = new Set(operation.responseDescriptor.requiredKeys);
+        if (distinct.size > 1) {
+            return verdict(rule, true, `operation ${operation.operationId} declares ${plural(distinct.size, 'distinct required response key')}`);
+        }
+    }
+    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
+ * `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);
+    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];
+            // `Object.keys` enumerates own keys only. `KeyName` admits
+            // `constructor`, which a keyed lookup would find on the prototype.
+            const key = shape.requiredKeys[0] ??
+                shape.permittedKeys[0] ??
+                Object.keys(shape.types)[0];
+            if (key !== undefined) {
+                return verdict(rule, true, `operation ${operation.operationId} declares ${channel} key ${key}`);
+            }
+        }
+    }
+    return verdict(rule, false, 'no operation declares a request key on any transport channel');
+}
+/**
+ * Rule 4: the descriptor declares at least one collection location. `null` is
+ * the absent state and is relevant; `[]` is the explicit empty answer.
+ */
+export function perRecordRelevance(contract) {
+    const rule = 'per-record';
+    const operations = operationsOf(contract);
+    if (operations.length === 0)
+        return verdict(rule, true, NO_OPERATION);
+    for (const operation of operations) {
+        const { collectionLocations } = operation.responseDescriptor;
+        if (collectionLocations === null) {
+            return verdict(rule, true, `operation ${operation.operationId} declares no collection-location list, so no collection is declared to range over`);
+        }
+        if (collectionLocations.length > 0) {
+            return verdict(rule, true, `operation ${operation.operationId} declares ${plural(collectionLocations.length, 'collection location')}`);
+        }
+    }
+    return verdict(rule, false, 'every operation declares an explicitly empty collection-location list');
+}
+/**
+ * Rule 5: a sibling group over operations or parameters is non-empty. The one
+ * contract-level rule of the seven. A group of one cannot exist, since
+ * `SIBLING_GROUP_MINIMUM` is two.
+ */
+export function siblingCrossCheckRelevance(contract) {
+    const rule = 'sibling-cross-check';
+    const groups = contract.siblingGroups;
+    if (groups === null) {
+        return verdict(rule, true, 'the contract declares no sibling groups');
+    }
+    if (groups.operations.length > 0) {
+        return verdict(rule, true, `the contract declares ${plural(groups.operations.length, 'operation sibling group')}`);
+    }
+    if (groups.parameters.length > 0) {
+        return verdict(rule, true, `the contract declares ${plural(groups.parameters.length, 'parameter sibling group')}`);
+    }
+    return verdict(rule, false, 'the contract declares explicitly empty operation and parameter sibling groups');
+}
+/**
+ * Rule 6: a declared collection location names a reference set. The site is
+ * `collectionLocations` alone, so an explicitly empty list stays an answer. A
+ * location naming an identifier the contract does not declare still names one.
+ */
+export function omissionAndCompletenessRelevance(contract) {
+    const rule = 'omission-and-completeness';
+    const operations = operationsOf(contract);
+    if (operations.length === 0)
+        return verdict(rule, true, NO_OPERATION);
+    for (const operation of operations) {
+        const { collectionLocations } = operation.responseDescriptor;
+        if (collectionLocations === null) {
+            return verdict(rule, true, `operation ${operation.operationId} declares no collection-location list, so no location can name a reference set`);
+        }
+        for (const location of collectionLocations) {
+            if (location.referenceSet !== null) {
+                return verdict(rule, true, `operation ${operation.operationId} names reference set ${location.referenceSet} for collection ${location.pointer}`);
+            }
+        }
+    }
+    return verdict(rule, false, 'no declared collection location names a reference set');
+}
+/**
+ * Rule 7: some operation declares `stateChangeMarker: true`. The one rule with
+ * no absent state to grade, since the marker is a required boolean and both
+ * values are legal.
+ */
+export function stateChangeReadBackRelevance(contract) {
+    const rule = 'state-change-read-back';
+    const operations = operationsOf(contract);
+    if (operations.length === 0)
+        return verdict(rule, true, NO_OPERATION);
+    for (const operation of operations) {
+        if (operation.stateChangeMarker) {
+            return verdict(rule, true, `operation ${operation.operationId} declares stateChangeMarker: true`);
+        }
+    }
+    return verdict(rule, false, 'no operation declares stateChangeMarker: true');
+}
+/**
+ * One predicate per rule. The mapped type fails the typecheck when a member of
+ * `DISCIPLINE_RULES` has no predicate. Same idiom as `operatorHandlers` in
+ * `core/evaluate/resolution.ts`, minus its `Object.hasOwn` guard: these keys
+ * come from a compile-time tuple, so a runtime guard is unreachable.
+ */
+export const RELEVANCE_PREDICATES = {
+    'success-indicator-separation': successIndicatorSeparationRelevance,
+    'whole-body': wholeBodyRelevance,
+    'malformed-input': malformedInputRelevance,
+    'per-record': perRecordRelevance,
+    'sibling-cross-check': siblingCrossCheckRelevance,
+    'omission-and-completeness': omissionAndCompletenessRelevance,
+    'state-change-read-back': stateChangeReadBackRelevance,
+};
+/** All seven verdicts, in `DISCIPLINE_RULES` order, over declarations alone. */
+export function evaluateRelevance(contract) {
+    return DISCIPLINE_RULES.map((rule) => RELEVANCE_PREDICATES[rule](contract));
+}

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

@@ -0,0 +1,7 @@
+/** AD-20's seven discipline rules as identifiers, in AD-20's enumeration order. */
+export declare const DISCIPLINE_RULES: readonly ['success-indicator-separation', 'whole-body', 'malformed-input', 'per-record', 'sibling-cross-check', 'omission-and-completeness', 'state-change-read-back'];
+export type DisciplineRule = (typeof DISCIPLINE_RULES)[number];
+/** `relevancePredicate` on a coverage-gap record. Derived, so a new rule arrives with one. */
+export declare const relevancePredicateId: (rule: DisciplineRule) => string;
+/** `satisfactionPredicate` on a coverage-gap record. Derived, like its relevance twin. */
+export declare const satisfactionPredicateId: (rule: DisciplineRule) => string;

package/dist/core/coverage/rules.js

@@ -0,0 +1,18 @@
+/** AD-20's seven discipline rules as identifiers, in AD-20's enumeration order. */
+// AD-20 names its seven rules in prose and gives them no identifiers, which is
+// why `Waiver.rule` and `CoverageGap.rule` are opaque strings. These spellings
+// are the Gate C contract's own `oracles[].rule` values
+// (reviews/gate-c/eval-contract.json:267-446), so a gap joins a waiver.
+export const DISCIPLINE_RULES = [
+    'success-indicator-separation',
+    'whole-body',
+    'malformed-input',
+    'per-record',
+    'sibling-cross-check',
+    'omission-and-completeness',
+    'state-change-read-back',
+];
+/** `relevancePredicate` on a coverage-gap record. Derived, so a new rule arrives with one. */
+export const relevancePredicateId = (rule) => `${rule}-relevance`;
+/** `satisfactionPredicate` on a coverage-gap record. Derived, like its relevance twin. */
+export const satisfactionPredicateId = (rule) => `${rule}-satisfaction`;