eval-quality 0.1.0

package/dist/core/compile/reachability.js

@@ -0,0 +1,177 @@
+/**
+ * Two compile-time checks over an EvalContract's oracle trees:
+ * `malformed-operator-expression` (a `@/` bound-element pointer outside any
+ * quantifier's predicate) and `unreachable-check-evidence` (a pointer the
+ * declared interfaces cannot produce). Both throw `StructuralFailure` on the
+ * first violation, matching `auditBriefScripting`'s fail-fast convention.
+ * `evaluatePointerReachability` is exported separately as the non-throwing
+ * per-pointer core, for reuse and direct testing.
+ */
+import { ARRAY_INDEX_PATTERN } from '../evaluate/evidence-resolution.js';
+import { StructuralFailure } from '../failure-codes.js';
+import { JsonTypeName } from '../schemas/primitives.js';
+import { buildPlanIndex, parseEvidenceTarget, } from '../seal/plan-index.js';
+function visitOperand(operand, path, insideQuantifier, visit) {
+    if ('pointer' in operand)
+        visit({ pointer: operand.pointer, path, insideQuantifier });
+    // `{ literal }` and `{ referenceSet }` address no interaction evidence.
+}
+// `set-membership`'s second operand is a `SetOperand` (`{ referenceSet }` or
+// `{ literal: [...] }`). That type excludes `{ pointer }`, so only its first
+// operand can carry one. Every other tuple-shaped op falls through to the
+// default branch, since each declares `operands: Operand[]`.
+function visitExpression(expression, path, insideQuantifier, visit) {
+    switch (expression.op) {
+        case 'not':
+            visitExpression(expression.operands[0], `${path}.operands[0]`, insideQuantifier, visit);
+            return;
+        case 'all':
+        case 'any':
+            expression.operands.forEach((child, index) => {
+                visitExpression(child, `${path}.operands[${index}]`, insideQuantifier, visit);
+            });
+            return;
+        case 'for-all':
+        case 'for-any':
+            visitOperand(expression.collection, `${path}.collection`, insideQuantifier, visit);
+            visitExpression(expression.predicate, `${path}.predicate`, true, visit);
+            return;
+        case 'set-membership':
+            visitOperand(expression.operands[0], `${path}.operands[0]`, insideQuantifier, visit);
+            return;
+        default:
+            expression.operands.forEach((operand, index) => {
+                visitOperand(operand, `${path}.operands[${index}]`, insideQuantifier, visit);
+            });
+    }
+}
+function forEachCheckPointer(contract, visit) {
+    contract.oracles.forEach((oracle) => {
+        if (oracle.check === null)
+            return;
+        visitExpression(oracle.check, 'check', false, (site) => visit(site, oracle.id));
+    });
+}
+// ---- malformed-operator-expression: @/ outside any quantifier -----------
+export function checkBoundElementScope(contract) {
+    forEachCheckPointer(contract, (site, oracleId) => {
+        if (site.pointer.startsWith('@') && !site.insideQuantifier) {
+            throw new StructuralFailure('malformed-operator-expression', `EvalContract.oracles[id=${oracleId}].${site.path}`, `bound-element pointer "${site.pointer}" appears outside any quantifier's predicate; "@/" binds only inside a quantifier (AD-26)`);
+        }
+    });
+}
+const reachable = () => ({ reachable: true });
+const unreachable = (reason) => ({
+    reachable: false,
+    reason,
+});
+// Every JsonTypeName value except `object` and `array` is scalar. Widened
+// to `ReadonlySet<string>` so `.has(declaredType)` below still typechecks.
+const SCALAR_TYPES = new Set(JsonTypeName.options.filter((name) => name !== 'object' && name !== 'array'));
+// A field blocks further descent only when its declared type is definitely
+// scalar. `undefined` (not declared) and `null` (declared, type not stated)
+// both stay permissive: nothing rules out descent.
+function descendsIntoDeclaredScalar(types, tail, firstToken) {
+    if (tail.length <= 1)
+        return false;
+    const declaredType = types[firstToken];
+    return (declaredType !== undefined &&
+        declaredType !== null &&
+        SCALAR_TYPES.has(declaredType));
+}
+/**
+ * Non-throwing core that `checkEvidenceReachability` wraps; also called
+ * directly by tests.
+ */
+export function evaluatePointerReachability(pointer, index) {
+    // A `@/` pointer is relative to a bound element. Nothing declared to
+    // check reachability against.
+    if (pointer.startsWith('@'))
+        return reachable();
+    const target = parseEvidenceTarget(pointer);
+    const step = index.stepOf(target.stepId);
+    if (step === undefined) {
+        return unreachable('names a step the interaction plan does not declare');
+    }
+    const operation = index.operationOf(step.operationId);
+    if (operation === undefined) {
+        return unreachable(`names step "${target.stepId}", which names operation "${step.operationId}", not declared by any permitted interface`);
+    }
+    if (target.channel === 'stdout' || target.channel === 'stderr') {
+        // stdout/stderr are always bare strings. A non-empty tail proves the
+        // pointer unreachable.
+        if (target.tail.length > 0) {
+            return unreachable(`addresses a field inside ${target.channel}, which never carries structure to descend into`);
+        }
+        return reachable();
+    }
+    if (target.channel === 'response-body') {
+        if (target.tail.length === 0)
+            return reachable();
+        const firstToken = target.tail[0];
+        if (firstToken === undefined) {
+            // Unreachable: the length check above guarantees an element.
+            throw new TypeError('evidence-target tail is non-empty but has no first token');
+        }
+        const { requiredKeys, permittedKeys, types, collectionLocations } = operation.responseDescriptor;
+        // A root-declared collection (`pointer: ''`) indexes directly, bypassing
+        // the key check below. `expectedCardinality` bounds the array size
+        // (`exact` is the true count; `at-most`/`page-bounded` is an upper
+        // bound), so an index at or past it is unreachable.
+        const rootCollection = collectionLocations?.find((location) => location.pointer === '');
+        if (rootCollection !== undefined && ARRAY_INDEX_PATTERN.test(firstToken)) {
+            const { expectedCardinality } = rootCollection;
+            const bound = expectedCardinality.mode === 'exact'
+                ? expectedCardinality.count
+                : expectedCardinality.max;
+            if (Number(firstToken) >= bound) {
+                return unreachable(`addresses response-body index ${firstToken}, out of bounds for the declared root collection's expectedCardinality (${expectedCardinality.mode} ${bound})`);
+            }
+            return reachable();
+        }
+        if (!requiredKeys.includes(firstToken) &&
+            !permittedKeys.includes(firstToken)) {
+            return unreachable(`addresses response-body field "${firstToken}", which operation "${operation.operationId}" declares in neither requiredKeys nor permittedKeys`);
+        }
+        if (descendsIntoDeclaredScalar(types, target.tail, firstToken)) {
+            return unreachable(`descends into response-body field "${firstToken}", which operation "${operation.operationId}" declares a scalar with no further structure`);
+        }
+        return reachable();
+    }
+    if (target.channel === 'call-inputs') {
+        if (target.tail.length === 0)
+            return reachable();
+        const { transportChannel } = target;
+        if (transportChannel === null) {
+            // Unreachable: parseEvidenceTarget's own guarantee.
+            throw new TypeError('call-inputs evidence target carries no transport channel');
+        }
+        const firstToken = target.tail[0];
+        if (firstToken === undefined) {
+            throw new TypeError('evidence-target tail is non-empty but has no first token');
+        }
+        const { requiredKeys, permittedKeys, types } = operation.requestShape[transportChannel];
+        if (!requiredKeys.includes(firstToken) &&
+            !permittedKeys.includes(firstToken)) {
+            return unreachable(`addresses call-inputs ${transportChannel} field "${firstToken}", which operation "${operation.operationId}" declares in neither requiredKeys nor permittedKeys`);
+        }
+        if (descendsIntoDeclaredScalar(types, target.tail, firstToken)) {
+            return unreachable(`descends into call-inputs ${transportChannel} field "${firstToken}", which operation "${operation.operationId}" declares a scalar with no further structure`);
+        }
+        return reachable();
+    }
+    // response-headers, response-status, and exit-code declare no shape, so
+    // a resolving operation is the entire compile-time check available.
+    return reachable();
+}
+/** `unreachable-check-evidence`: an interaction-rooted pointer the declared interfaces cannot produce. */
+export function checkEvidenceReachability(contract) {
+    let index;
+    forEachCheckPointer(contract, (site, oracleId) => {
+        index ??= buildPlanIndex(contract.interactionPlan, contract.permittedInterfaces, { duplicateIds: 'unresolved' });
+        const result = evaluatePointerReachability(site.pointer, index);
+        if (!result.reachable) {
+            throw new StructuralFailure('unreachable-check-evidence', `EvalContract.oracles[id=${oracleId}].${site.path}`, `"${site.pointer}" ${result.reason}`);
+        }
+    });
+}

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

@@ -0,0 +1,55 @@
+import type { EvalContract } from '../schemas/eval-contract.ts';
+/**
+ * Runs ahead of the three checks below, reversing AD-5's registry order for
+ * this one pair. Every other rubric check reports a path shaped
+ * `rubrics[id=...]`, and a duplicated id makes that path address two rubrics,
+ * so identifiers are settled first and every later path is unambiguous by
+ * construction.
+ *
+ * Criterion ids are unique within a rubric and may repeat across rubrics: a
+ * judge-call score cites `rubricId` and `criterionId` together, so the pair is
+ * what has to be unique.
+ */
+export declare function checkRubricIdentifiers(contract: EvalContract): void;
+/** The first forbidden term in `text`, or `undefined`. */
+export declare function findReasoningProseTerm(text: string): string | undefined;
+/**
+ * Criterion text is scanned first: AD-17 and AD-5 both scope this code to a
+ * criterion, so where a rubric carries the defect in more than one place the
+ * in-scope site is the one reported. Anchors and penalties are a deliberate
+ * expansion. An anchor reading "level 3: the reasoning is sound" scores
+ * reasoning through every criterion at once, and a penalty deducting for an
+ * unstated rationale scores it through a deduction. Leave either unscanned and
+ * an author walks around the criterion scan in one edit.
+ */
+export declare function checkRubricReasoningProse(contract: EvalContract): void;
+/**
+ * AD-22's three shapes, spelled out: an unanchored scale (rules 1 to 3), an
+ * unbounded length (rule 4), and missing named failure-mode penalties (rules 5
+ * and 6). Rule 7 applies rule 3's argument to a criterion and is the one rule
+ * that stretches AD-22's wording: a criterion stating no question is
+ * unanswerable in a way `rubric-evidence-unreachable` cannot see, since its
+ * pointer may resolve perfectly.
+ *
+ * A single-level scale, a repeated penalty name, and a rubric with no criteria
+ * are all legal, each with an accept test guarding it. The first two were
+ * proposed and rejected in review; AD-19 settles the third by stating that
+ * AD-17's rules bind only when a rubric names criteria.
+ */
+export declare function checkRubricAnchoring(contract: EvalContract): void;
+/**
+ * `evaluatePointerReachability` is reused, so the two evidence codes give the
+ * same reason for the same broken pointer. Two limits come with it. A `@/`
+ * pointer cannot parse into `criterion.evidence`, an `InteractionPointer`, so
+ * that branch is dead here. And a channel that declares no shape resolves as
+ * soon as its step does, so a criterion rooted at `stdout` compiles on an
+ * `api`-kind contract that can never produce one. That gap belongs to
+ * `unreachable-check-evidence` as well, and a second implementation written to
+ * close it for rubrics alone would leave the two codes disagreeing about the
+ * same pointer.
+ *
+ * `duplicateIds: 'unresolved'` is load-bearing. `buildPlanIndex` otherwise
+ * throws a `TypeError` on a duplicate step or operation id, and a caller has
+ * no way to classify a `TypeError` that escapes a compile check.
+ */
+export declare function checkRubricEvidenceReachability(contract: EvalContract): void;

package/dist/core/compile/rubrics.js

@@ -0,0 +1,198 @@
+/**
+ * AD-22's compile-time rubric checks. `checkRubricIdentifiers` runs first and
+ * fires `rubric-unanchored`; the other three follow AD-5's registry order,
+ * `rubric-scores-reasoning-prose`, `rubric-unanchored`, then
+ * `rubric-evidence-unreachable`. Each throws `StructuralFailure` on the first
+ * violation, the convention every `core/compile/` module keeps. An empty
+ * `rubrics` array is a no-op in all four, which is what makes a zero-rubric
+ * contract compile clean.
+ */
+import { StructuralFailure } from '../failure-codes.js';
+import { buildPlanIndex } from '../seal/plan-index.js';
+import { evaluatePointerReachability } from './reachability.js';
+const rubricPath = (rubric) => `EvalContract.rubrics[id=${rubric.id}]`;
+// `trim()` leaves U+200B through U+200D and U+FEFF standing, and a zero-width
+// space states no observable condition either.
+const INVISIBLE = /[\u200b-\u200d\ufeff]/g;
+const blank = (value) => value.replace(INVISIBLE, '').trim().length === 0;
+// Function declarations, so TypeScript narrows control flow through the
+// `never` return type: a guard below reads a nullable field straight after the
+// call that rejects its null case.
+function unanchored(path, detail) {
+    throw new StructuralFailure('rubric-unanchored', path, detail);
+}
+function scoresReasoning(path, term) {
+    throw new StructuralFailure('rubric-scores-reasoning-prose', path, `scores stated-reasoning prose: matched "${term}" (AD-17, AD-22)`);
+}
+// ---- rubric-unanchored: addressable identifiers ---------------------------
+/**
+ * Runs ahead of the three checks below, reversing AD-5's registry order for
+ * this one pair. Every other rubric check reports a path shaped
+ * `rubrics[id=...]`, and a duplicated id makes that path address two rubrics,
+ * so identifiers are settled first and every later path is unambiguous by
+ * construction.
+ *
+ * Criterion ids are unique within a rubric and may repeat across rubrics: a
+ * judge-call score cites `rubricId` and `criterionId` together, so the pair is
+ * what has to be unique.
+ */
+export function checkRubricIdentifiers(contract) {
+    const seenRubricIds = new Set();
+    contract.rubrics.forEach((rubric, index) => {
+        if (seenRubricIds.has(rubric.id)) {
+            unanchored(`EvalContract.rubrics[${index}].id`, `repeats rubric id "${rubric.id}", which a finding could then cite ambiguously (AD-22)`);
+        }
+        seenRubricIds.add(rubric.id);
+    });
+    // Second pass, so no `rubrics[id=...]` path is emitted while a rubric id
+    // could still address two rubrics.
+    for (const rubric of contract.rubrics) {
+        const seenCriterionIds = new Set();
+        rubric.criteria.forEach((criterion, index) => {
+            if (seenCriterionIds.has(criterion.id)) {
+                unanchored(`${rubricPath(rubric)}.criteria[${index}].id`, `repeats criterion id "${criterion.id}" inside one rubric (AD-22)`);
+            }
+            seenCriterionIds.add(criterion.id);
+        });
+    }
+}
+// ---- rubric-scores-reasoning-prose ---------------------------------------
+// AD-17 forbids scoring chain-of-thought or stated-reasoning prose. Nothing in
+// the schema declares which channel carries reasoning, so this check reads
+// wording, the same trade `auditBriefScripting` makes. The alternative was a
+// rung with no throw site.
+//
+// A term earns a place only when it has no ordinary sense in an API contract.
+// A compile-time code has no waiver path, so a term that fires on legal
+// authoring gets reworded around. Review dropped `scratchpad` (a file),
+// `deliberation` (an endpoint), the `justif-` family (an error body justifies
+// a 409), `explanation` (an error message explains what went wrong), bare
+// `thinking` (a measurement, as in thinking time), bare `CoT` (an ordinary
+// English noun), and `explain why` (a criterion can ask why an observable
+// status was returned).
+//
+// `reasoning` and `rationale` stay despite their field-name senses. AD-17's
+// own words are "stated-reasoning prose", and a criterion carries an
+// `evidence` pointer so its text never has to name a field. Plurals and
+// `-ing` are covered because one letter would otherwise walk past the check.
+// ASCII hyphen, U+2010 hyphen, U+2011 non-breaking hyphen, or whitespace, one
+// or more. A paste out of a styled document carries the two non-ASCII forms,
+// and a single-character class made a doubled separator an evasion.
+const SEPARATOR = '[-\\u2010\\u2011\\s]+';
+// Built from fragments the way `pointer.ts` builds its pointer grammar, so the
+// separator is stated once. The pattern is not global, so no `lastIndex`
+// carries between calls. The first match is the whole answer.
+const REASONING_PROSE_PATTERN = new RegExp(`\\b(?:chains?${SEPARATOR}of${SEPARATOR}thoughts?|trains?${SEPARATOR}of${SEPARATOR}thoughts?|thought${SEPARATOR}process(?:es|ing)?|thinking${SEPARATOR}process(?:es)?|(?:internal|inner)${SEPARATOR}monologues?|self${SEPARATOR}explanations?|reasonings?|rationales?)\\b`, 'i');
+/** The first forbidden term in `text`, or `undefined`. */
+export function findReasoningProseTerm(text) {
+    return REASONING_PROSE_PATTERN.exec(text)?.[0];
+}
+/**
+ * Criterion text is scanned first: AD-17 and AD-5 both scope this code to a
+ * criterion, so where a rubric carries the defect in more than one place the
+ * in-scope site is the one reported. Anchors and penalties are a deliberate
+ * expansion. An anchor reading "level 3: the reasoning is sound" scores
+ * reasoning through every criterion at once, and a penalty deducting for an
+ * unstated rationale scores it through a deduction. Leave either unscanned and
+ * an author walks around the criterion scan in one edit.
+ */
+export function checkRubricReasoningProse(contract) {
+    for (const rubric of contract.rubrics) {
+        const path = rubricPath(rubric);
+        for (const criterion of rubric.criteria) {
+            const term = findReasoningProseTerm(criterion.text);
+            if (term !== undefined)
+                scoresReasoning(`${path}.criteria[id=${criterion.id}].text`, term);
+        }
+        rubric.scaleLevels?.forEach((level, index) => {
+            const term = findReasoningProseTerm(level.anchor);
+            if (term !== undefined)
+                scoresReasoning(`${path}.scaleLevels[${index}].anchor`, term);
+        });
+        rubric.failureModePenalties?.forEach((penalty, index) => {
+            const penaltyPath = `${path}.failureModePenalties[${index}]`;
+            const nameTerm = findReasoningProseTerm(penalty.name);
+            if (nameTerm !== undefined)
+                scoresReasoning(`${penaltyPath}.name`, nameTerm);
+            const descriptionTerm = findReasoningProseTerm(penalty.description);
+            if (descriptionTerm !== undefined)
+                scoresReasoning(`${penaltyPath}.description`, descriptionTerm);
+        });
+    }
+}
+// ---- rubric-unanchored: the scoring instrument ---------------------------
+/**
+ * AD-22's three shapes, spelled out: an unanchored scale (rules 1 to 3), an
+ * unbounded length (rule 4), and missing named failure-mode penalties (rules 5
+ * and 6). Rule 7 applies rule 3's argument to a criterion and is the one rule
+ * that stretches AD-22's wording: a criterion stating no question is
+ * unanswerable in a way `rubric-evidence-unreachable` cannot see, since its
+ * pointer may resolve perfectly.
+ *
+ * A single-level scale, a repeated penalty name, and a rubric with no criteria
+ * are all legal, each with an accept test guarding it. The first two were
+ * proposed and rejected in review; AD-19 settles the third by stating that
+ * AD-17's rules bind only when a rubric names criteria.
+ */
+export function checkRubricAnchoring(contract) {
+    for (const rubric of contract.rubrics) {
+        const path = rubricPath(rubric);
+        const { scaleLevels, failureModePenalties } = rubric;
+        if (scaleLevels === null || scaleLevels.length === 0)
+            unanchored(`${path}.scaleLevels`, 'declares no anchored scale levels (AD-22)');
+        const seenOrdinals = new Set();
+        scaleLevels.forEach((level, index) => {
+            if (seenOrdinals.has(level.level)) {
+                unanchored(`${path}.scaleLevels[${index}].level`, `repeats scale-level ordinal ${level.level}, so the ordinal addresses two anchors (AD-22)`);
+            }
+            seenOrdinals.add(level.level);
+        });
+        scaleLevels.forEach((level, index) => {
+            if (blank(level.anchor)) {
+                unanchored(`${path}.scaleLevels[${index}].anchor`, 'states no observable condition, so the level is unanchored (AD-22)');
+            }
+        });
+        if (rubric.maxLength === null)
+            unanchored(`${path}.maxLength`, 'declares no bounded length (AD-22)');
+        if (failureModePenalties === null || failureModePenalties.length === 0)
+            unanchored(`${path}.failureModePenalties`, 'names no failure-mode penalties (AD-22)');
+        failureModePenalties.forEach((penalty, index) => {
+            if (blank(penalty.name)) {
+                unanchored(`${path}.failureModePenalties[${index}].name`, 'is blank, so the penalty is unnamed (AD-22)');
+            }
+        });
+        for (const criterion of rubric.criteria) {
+            if (blank(criterion.text)) {
+                unanchored(`${path}.criteria[id=${criterion.id}].text`, 'states no question, so the criterion is unanchored (AD-22)');
+            }
+        }
+    }
+}
+// ---- rubric-evidence-unreachable -----------------------------------------
+/**
+ * `evaluatePointerReachability` is reused, so the two evidence codes give the
+ * same reason for the same broken pointer. Two limits come with it. A `@/`
+ * pointer cannot parse into `criterion.evidence`, an `InteractionPointer`, so
+ * that branch is dead here. And a channel that declares no shape resolves as
+ * soon as its step does, so a criterion rooted at `stdout` compiles on an
+ * `api`-kind contract that can never produce one. That gap belongs to
+ * `unreachable-check-evidence` as well, and a second implementation written to
+ * close it for rubrics alone would leave the two codes disagreeing about the
+ * same pointer.
+ *
+ * `duplicateIds: 'unresolved'` is load-bearing. `buildPlanIndex` otherwise
+ * throws a `TypeError` on a duplicate step or operation id, and a caller has
+ * no way to classify a `TypeError` that escapes a compile check.
+ */
+export function checkRubricEvidenceReachability(contract) {
+    let index;
+    for (const rubric of contract.rubrics) {
+        for (const criterion of rubric.criteria) {
+            index ??= buildPlanIndex(contract.interactionPlan, contract.permittedInterfaces, { duplicateIds: 'unresolved' });
+            const result = evaluatePointerReachability(criterion.evidence, index);
+            if (!result.reachable) {
+                throw new StructuralFailure('rubric-evidence-unreachable', `${rubricPath(rubric)}.criteria[id=${criterion.id}].evidence`, `"${criterion.evidence}" ${result.reason}`);
+            }
+        }
+    }
+}

package/dist/core/compile/scripting-bound.d.ts

@@ -0,0 +1,5 @@
+import type { EvalContract } from '../schemas/eval-contract.ts';
+/** `nested-temporal-clause`: a step's declared parent itself carries a temporal clause. */
+export declare function checkNestedTemporalClause(contract: EvalContract): void;
+/** `plan-exceeds-scripting-bound`: the graph predicate over the whole plan. */
+export declare function checkScriptingBound(contract: EvalContract): void;

package/dist/core/compile/scripting-bound.js

@@ -0,0 +1,151 @@
+/**
+ * AD-39's two interaction-plan graph checks: `nested-temporal-clause` and
+ * `plan-exceeds-scripting-bound`, each walking `contract.interactionPlan`
+ * once. Both throw `StructuralFailure` on the first violation, matching
+ * every other `core/compile/` module's fail-fast convention.
+ */
+import { StructuralFailure } from '../failure-codes.js';
+import { buildPlanIndex } from '../seal/plan-index.js';
+/**
+ * A dangling `after` (naming no declared step, including one made
+ * unresolvable by a duplicate id) resolves to `undefined`, the same as a
+ * genuinely absent clause.
+ */
+function parentOf(step, index) {
+    if (step.after === null)
+        return undefined;
+    return index.stepOf(step.after);
+}
+function planIndexOf(contract) {
+    return buildPlanIndex(contract.interactionPlan, contract.permittedInterfaces, { duplicateIds: 'unresolved' });
+}
+// ---- nested-temporal-clause ------------------------------------------------
+/** `nested-temporal-clause`: a step's declared parent itself carries a temporal clause. */
+export function checkNestedTemporalClause(contract) {
+    const index = planIndexOf(contract);
+    for (const step of contract.interactionPlan) {
+        const parent = parentOf(step, index);
+        if (parent !== undefined && parentOf(parent, index) !== undefined) {
+            throw new StructuralFailure('nested-temporal-clause', `EvalContract.interactionPlan[stepId=${step.stepId}].after`, `names step "${parent.stepId}", which itself carries a temporal clause; a chain may not nest more than one level (AD-39)`);
+        }
+    }
+}
+// ---- plan-exceeds-scripting-bound ------------------------------------------
+/**
+ * Bounds are exclusive ceilings: a metric sitting exactly at its bound is
+ * legal. Each is set against this codebase's own two whole-contract
+ * fixtures as the accept floor and AD-39's two counterexample plans as the
+ * reject ceiling: the eight-step single-root chain and the sixty-four
+ * independent `write-N`/`read-N` pairs, which AD-39 records as passing a
+ * depth bound alone. AD-5 mandates one authored reject fixture per shape
+ * this predicate rejects, and `tests/compile/scripting-bound.test.ts`
+ * carries them.
+ */
+const WIDTH_MAX = 2; // gateCContract's own submit -> {poll, first-page} sits exactly here.
+const SHARED_ANCHOR_MAX = 2; // twice gateCContract's own shared-anchor count of 1 (no real fixture reaches 2).
+const DISJOINT_PAIR_MAX = 4; // populatedContract's own create -> list pair is 1.
+const STEP_COUNT_MAX = 16; // gateCContract is 6, populatedContract is 2; roughly 2.7x the larger.
+/**
+ * One pass over the plan's `after` edges, building three views at once: the
+ * one-hop nesting test (shared with `checkNestedTemporalClause`), each
+ * anchor's child count (width, shared anchors), and an undirected adjacency
+ * map for the connected-component scan below (disjoint pairs). O(n) in the
+ * step count.
+ *
+ * Every internal map is keyed by each step's array position. `stepId` is
+ * schema-legal to duplicate, so keying on it would merge two distinct
+ * steps sharing an id into one adjacency entry and corrupt
+ * `maxWidth`/`sharedAnchorCount`/`disjointPairCount`.
+ */
+function computeGraphMetrics(plan, index) {
+    const positionOf = new Map();
+    for (const [position, step] of plan.entries())
+        positionOf.set(step, position);
+    const children = new Map();
+    const adjacency = new Map();
+    for (const [position] of plan.entries())
+        adjacency.set(position, new Set());
+    let hasNestedChain = false;
+    for (const [position, step] of plan.entries()) {
+        const parent = parentOf(step, index);
+        if (parent === undefined)
+            continue;
+        if (parentOf(parent, index) !== undefined)
+            hasNestedChain = true;
+        const parentPosition = positionOf.get(parent);
+        if (parentPosition === undefined) {
+            // Should-never-happen precondition violation, matching `resolveStep`'s
+            // convention (`plan-index.ts`): `index` is always built from this same
+            // `plan` array, so a resolved parent is always one of its elements.
+            throw new TypeError(`scripting-bound: resolved parent for step "${step.stepId}" is not present in the plan passed to computeGraphMetrics`);
+        }
+        const siblings = children.get(parentPosition);
+        if (siblings === undefined)
+            children.set(parentPosition, [position]);
+        else
+            siblings.push(position);
+        adjacency.get(position)?.add(parentPosition);
+        adjacency.get(parentPosition)?.add(position);
+    }
+    let maxWidth = 0;
+    let sharedAnchorCount = 0;
+    for (const siblings of children.values()) {
+        if (siblings.length > maxWidth)
+            maxWidth = siblings.length;
+        if (siblings.length >= 2)
+            sharedAnchorCount += 1;
+    }
+    // Connected components over the undirected `after` graph; a component of
+    // exactly two nodes is one disjoint witness pair (the 64-pair fixture's
+    // own shape). A plain stack (`.pop()`) is enough for an unordered scan;
+    // `.shift()` would cost O(n) per call.
+    let disjointPairCount = 0;
+    const visited = new Set();
+    for (const [position] of plan.entries()) {
+        if (visited.has(position))
+            continue;
+        let size = 0;
+        const stack = [position];
+        visited.add(position);
+        while (stack.length > 0) {
+            const id = stack.pop();
+            if (id === undefined)
+                continue;
+            size += 1;
+            for (const neighbor of adjacency.get(id) ?? []) {
+                if (!visited.has(neighbor)) {
+                    visited.add(neighbor);
+                    stack.push(neighbor);
+                }
+            }
+        }
+        if (size === 2)
+            disjointPairCount += 1;
+    }
+    return {
+        hasNestedChain,
+        maxWidth,
+        sharedAnchorCount,
+        disjointPairCount,
+        stepCount: plan.length,
+    };
+}
+/** `plan-exceeds-scripting-bound`: the graph predicate over the whole plan. */
+export function checkScriptingBound(contract) {
+    const index = planIndexOf(contract);
+    const metrics = computeGraphMetrics(contract.interactionPlan, index);
+    const violation = metrics.hasNestedChain
+        ? 'its deepest temporal chain exceeds the published one-level bound'
+        : metrics.maxWidth > WIDTH_MAX
+            ? `one step anchors ${metrics.maxWidth} other steps, past the published width bound of ${WIDTH_MAX}`
+            : metrics.sharedAnchorCount > SHARED_ANCHOR_MAX
+                ? `${metrics.sharedAnchorCount} steps each anchor more than one other step, past the published bound of ${SHARED_ANCHOR_MAX} shared anchors`
+                : metrics.disjointPairCount > DISJOINT_PAIR_MAX
+                    ? `${metrics.disjointPairCount} mutually disjoint two-step witness pairs appear in one plan, past the published bound of ${DISJOINT_PAIR_MAX}`
+                    : metrics.stepCount > STEP_COUNT_MAX
+                        ? `the plan declares ${metrics.stepCount} steps, past the published bound of ${STEP_COUNT_MAX}: an exhaustive operation inventory rather than a bounded set of witness relations`
+                        : undefined;
+    if (violation !== undefined) {
+        throw new StructuralFailure('plan-exceeds-scripting-bound', 'EvalContract.interactionPlan', `${violation} (AD-5, AD-39)`);
+    }
+}

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

@@ -0,0 +1,73 @@
+/**
+ * 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.ts';
+import type { EvalContract } from '../schemas/eval-contract.ts';
+import type { Operation } from '../schemas/interface.ts';
+import { type TransportChannelName } from '../schemas/pointer.ts';
+import type { WitnessInputs } from '../schemas/sensitivity-witness.ts';
+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 declare function suppliedKeys(inputs: WitnessInputs, channel: TransportChannelName): readonly string[];
+/**
+ * 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 declare function checkInputsAgainstShape(inputs: WitnessInputs, operation: Operation, owner: string, artifactPath: string): void;
+/**
+ * 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 declare function checkSensitivityWitnessDeclared(contract: EvalContract): void;
+/**
+ * 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 declare function checkWitnessLegality(contract: EvalContract): void;
+/**
+ * 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 declare function checkWitnessLegIdentifiers(contract: EvalContract): void;