eval-quality 0.1.0

package/dist/core/evaluate/resolution.js

@@ -0,0 +1,336 @@
+import { absence, containment, countTolerance, coversByKey, deepEquality, equality, existence, ordering, regexMatch, setMembership, shape, } from './operators.js';
+import { ABSENT } from './resolved-value.js';
+/**
+ * AD-4's one closed introduction condition, checked per operand and applied
+ * uniformly: the resolved value and its operand are the only inputs.
+ *
+ * Two permanent consequences of that uniform reading, the same class as a
+ * `{ literal: [] }` operand tripping it: a `count-tolerance` node asserting
+ * `expected: 0` over a genuinely empty collection can never resolve `true`,
+ * because this interception fires first; and `existence` over a pointer
+ * resolving to a present-but-empty array resolves `insufficient-evidence`, not
+ * `true`, even though `existence` only asks about presence.
+ */
+function operandDenotesEmptyCollection(resolved, operand, pointerDenotesCollection) {
+    if (Array.isArray(resolved) && resolved.length === 0)
+        return true;
+    if (resolved !== ABSENT)
+        return false;
+    // Only a `{ pointer }` operand can carry a declared collection type.
+    // `{ literal }` never resolves ABSENT, and an ABSENT `{ referenceSet }`
+    // means `unresolved-reference-set` slipped past compilation, which this
+    // module assumes cannot happen.
+    return 'pointer' in operand && pointerDenotesCollection(operand.pointer);
+}
+function emptyCollectionResult() {
+    return {
+        resolution: 'insufficient-evidence',
+        introductionCondition: 'empty-collection',
+        children: [],
+    };
+}
+function booleanResult(result) {
+    return {
+        resolution: result ? 'true' : 'false',
+        introductionCondition: null,
+        children: [],
+    };
+}
+// Checked across every operand before any operator runs, so the interception
+// replaces a leaf's own two-valued answer outright.
+function anyOperandEmpty(pairs, pointerDenotesCollection) {
+    return pairs.some(({ operand, resolved }) => operandDenotesEmptyCollection(resolved, operand, pointerDenotesCollection));
+}
+/** `not(insufficient-evidence)` is terminal under both polarities (AD-4). */
+function notOf(child) {
+    if (child === 'insufficient-evidence')
+        return 'insufficient-evidence';
+    return child === 'true' ? 'false' : 'true';
+}
+/**
+ * A genuine `false` stays decisive beside an `insufficient-evidence` sibling: a
+ * detected defect is information. `CONNECTIVE_MINIMUM_ARITY` (`expression.ts`)
+ * keeps the array from ever being empty, so the vacuous `true` never arises.
+ */
+function allOf(children) {
+    if (children.some((child) => child === 'false'))
+        return 'false';
+    if (children.some((child) => child === 'insufficient-evidence')) {
+        return 'insufficient-evidence';
+    }
+    return 'true';
+}
+/**
+ * Weaker than disjunction on purpose: a sibling resolving `true` never rescues
+ * one that examined nothing. Same arity floor as `allOf`.
+ */
+function anyOf(children) {
+    if (children.some((child) => child === 'insufficient-evidence')) {
+        return 'insufficient-evidence';
+    }
+    if (children.some((child) => child === 'true'))
+        return 'true';
+    return 'false';
+}
+/**
+ * A quantifier's `collection` field resolves through the same
+ * `resolveOperand`/`pointerDenotesCollection` pair as any other operand, with one
+ * exception: `ABSENT` here is unconditionally an empty collection and
+ * `pointerDenotesCollection` is never consulted. A `collection` field is a
+ * collection by definition, so there is nothing to disambiguate.
+ */
+function resolveQuantifier(op, collectionOperand, predicate, boundElement, ctx) {
+    // Resolved once, before the loop, against whatever `boundElement` was
+    // already in scope (an outer quantifier's element if nested, `ABSENT` at
+    // the root): never against an element this quantifier's own loop below
+    // has not bound yet.
+    const collection = ctx.resolveOperand(collectionOperand, boundElement, ctx.artifactPath);
+    if (collection === ABSENT ||
+        !Array.isArray(collection) ||
+        collection.length === 0) {
+        // One guard, three cases: ABSENT, a non-array type mismatch, and a
+        // genuinely empty array. All three collapse onto the same
+        // `empty-collection` value: the evidence artifact cannot tell which of the
+        // three fired. Separating them would need a second introduction-condition
+        // value, a schema change out of scope here.
+        return emptyCollectionResult();
+    }
+    const children = collection.map((element) => resolveNode(predicate, element, ctx));
+    const childResolutions = children.map((child) => child.resolution);
+    return {
+        resolution: op === 'for-all' ? allOf(childResolutions) : anyOf(childResolutions),
+        // Null even when the fold below reads insufficient-evidence. This node did
+        // not trip the empty-collection condition itself; a child did, and still
+        // carries it, reachable through `children`.
+        introductionCondition: null,
+        children,
+    };
+}
+// Shared by the six single-operand leaves: resolve, intercept on the
+// empty-collection condition, otherwise hand the value to the operator.
+function resolveSingleOperand(operand, boundElement, ctx, evaluate) {
+    const resolved = ctx.resolveOperand(operand, boundElement, ctx.artifactPath);
+    if (anyOperandEmpty([{ operand, resolved }], ctx.pointerDenotesCollection)) {
+        return emptyCollectionResult();
+    }
+    return booleanResult(evaluate(resolved));
+}
+// Shared by `equality` and `deep-equality`, which differ only in the operator
+// they call.
+function resolveEqualityLike(operands, evaluate, boundElement, ctx) {
+    const [aOperand, bOperand] = operands;
+    const a = ctx.resolveOperand(aOperand, boundElement, ctx.artifactPath);
+    const b = ctx.resolveOperand(bOperand, boundElement, ctx.artifactPath);
+    if (anyOperandEmpty([
+        { operand: aOperand, resolved: a },
+        { operand: bOperand, resolved: b },
+    ], ctx.pointerDenotesCollection)) {
+        return emptyCollectionResult();
+    }
+    return booleanResult(evaluate(a, b, ctx.artifactPath));
+}
+function resolveNotNode(expression, boundElement, ctx) {
+    const [child] = expression.operands;
+    const resolved = resolveNode(child, boundElement, ctx);
+    return {
+        resolution: notOf(resolved.resolution),
+        // A fold, not a firing. `resolved` still carries the condition if it is
+        // the one that tripped it.
+        introductionCondition: null,
+        children: [resolved],
+    };
+}
+// Shared by `all` and `any`, which differ only in the fold they apply.
+function resolveConnective(expression, fold, boundElement, ctx) {
+    // Total, never short-circuiting, over resolutions: every operand is
+    // recursed into before folding, whatever an earlier one resolved. Not
+    // total over faults (P5): `.map()` still stops at the first operand whose
+    // own resolution throws, so a later operand's fault is never reached.
+    const children = expression.operands.map((operand) => resolveNode(operand, boundElement, ctx));
+    return {
+        resolution: fold(children.map((child) => child.resolution)),
+        // A fold. The tripped child, if any, carries the condition itself, in
+        // `children`.
+        introductionCondition: null,
+        children,
+    };
+}
+function resolveAllNode(expression, boundElement, ctx) {
+    return resolveConnective(expression, allOf, boundElement, ctx);
+}
+function resolveAnyNode(expression, boundElement, ctx) {
+    return resolveConnective(expression, anyOf, boundElement, ctx);
+}
+function resolveQuantifierNode(expression, boundElement, ctx) {
+    return resolveQuantifier(expression.op, expression.collection, expression.predicate, boundElement, ctx);
+}
+function resolveCoversByKeyNode(expression, boundElement, ctx) {
+    const [expectedOperand, actualOperand] = expression.operands;
+    const { expectedKey, actualKey } = expression;
+    const expectedResolved = ctx.resolveOperand(expectedOperand, boundElement, ctx.artifactPath);
+    const actualResolved = ctx.resolveOperand(actualOperand, boundElement, ctx.artifactPath);
+    // Checked first and unconditionally, before anything else looks at
+    // `actual`. A malformed `expected` is a resolver integration bug, never a
+    // data outcome, and must never be masked by whatever `actual` resolved to,
+    // including a benign empty collection.
+    if (expectedResolved !== ABSENT && !Array.isArray(expectedResolved)) {
+        throw new Error("covers-by-key's expected-operand guard: a reference-set operand " +
+            'must resolve to ABSENT or an array, which the schema guarantees. ' +
+            'The injected ResolveOperand returned something else — either a ' +
+            'resolver integration bug, or an unresolved reference set that ' +
+            'slipped past compilation (unresolved-reference-set); this guard ' +
+            'cannot tell the two apart.');
+    }
+    // Genuine emptiness (AD-4's "two empty collections" case, generalized to a
+    // single empty operand) applies only once both operands are confirmed
+    // ordinary, present collections. An ABSENT `actual` is AD-26's decisive
+    // `false` over a pointer that did not resolve; a non-array `actual` is an
+    // operand type `covers-by-key` does not accept, which AD-4 assigns to
+    // `malformed-operator-expression` and which resolves `false` here because
+    // no compile-time check covers this position. Both outrank emptiness.
+    // Delegating to `coversByKey` for those two cases keeps the check
+    // single-sourced: it already implements both as its own top guards.
+    const bothPresentArrays = expectedResolved !== ABSENT &&
+        actualResolved !== ABSENT &&
+        Array.isArray(actualResolved);
+    if (bothPresentArrays &&
+        (expectedResolved.length === 0 || actualResolved.length === 0)) {
+        return emptyCollectionResult();
+    }
+    return booleanResult(coversByKey(expectedResolved, actualResolved, expectedKey, actualKey, ctx.artifactPath));
+}
+function resolveEqualityNode(expression, boundElement, ctx) {
+    return resolveEqualityLike(expression.operands, equality, boundElement, ctx);
+}
+function resolveDeepEqualityNode(expression, boundElement, ctx) {
+    return resolveEqualityLike(expression.operands, deepEquality, boundElement, ctx);
+}
+function resolveContainmentNode(expression, boundElement, ctx) {
+    const [containerOperand, candidateOperand] = expression.operands;
+    const container = ctx.resolveOperand(containerOperand, boundElement, ctx.artifactPath);
+    const candidate = ctx.resolveOperand(candidateOperand, boundElement, ctx.artifactPath);
+    if (anyOperandEmpty([
+        { operand: containerOperand, resolved: container },
+        { operand: candidateOperand, resolved: candidate },
+    ], ctx.pointerDenotesCollection)) {
+        return emptyCollectionResult();
+    }
+    // The array-narrowing guard applies only to a `{ referenceSet }` candidate.
+    // A `{ pointer }` or `{ literal }` candidate legally resolves to a scalar
+    // (the stdout/stderr substring shape), and `containment` already handles
+    // both shapes.
+    if ('referenceSet' in candidateOperand && !Array.isArray(candidate)) {
+        throw new Error("containment's referenceSet-candidate guard: a { referenceSet } " +
+            'operand must resolve to an array, which the schema guarantees. ' +
+            'The injected ResolveOperand returned something else — either a ' +
+            'resolver integration bug, or an unresolved reference set that ' +
+            'slipped past compilation (unresolved-reference-set); this guard ' +
+            'cannot tell the two apart.');
+    }
+    return booleanResult(containment(container, candidate, ctx.artifactPath));
+}
+function resolveExistenceNode(expression, boundElement, ctx) {
+    const [operand] = expression.operands;
+    return resolveSingleOperand(operand, boundElement, ctx, (resolved) => existence(resolved, ctx.artifactPath));
+}
+function resolveAbsenceNode(expression, boundElement, ctx) {
+    const [operand] = expression.operands;
+    return resolveSingleOperand(operand, boundElement, ctx, (resolved) => absence(resolved, ctx.artifactPath));
+}
+function resolveRegexNode(expression, boundElement, ctx) {
+    const [operand] = expression.operands;
+    const { pattern } = expression;
+    return resolveSingleOperand(operand, boundElement, ctx, (resolved) => regexMatch(resolved, pattern, ctx.regexMatchStepBudget, ctx.artifactPath));
+}
+function resolveSetMembershipNode(expression, boundElement, ctx) {
+    const [valueOperand, setOperand] = expression.operands;
+    const value = ctx.resolveOperand(valueOperand, boundElement, ctx.artifactPath);
+    const resolvedSet = ctx.resolveOperand(setOperand, boundElement, ctx.artifactPath);
+    if (anyOperandEmpty([
+        { operand: valueOperand, resolved: value },
+        { operand: setOperand, resolved: resolvedSet },
+    ], ctx.pointerDenotesCollection)) {
+        return emptyCollectionResult();
+    }
+    // The set position needs the `JsonValue[]` the schema already guarantees
+    // here. Narrow at runtime so a broken resolver fails loudly.
+    if (!Array.isArray(resolvedSet)) {
+        throw new Error("set-membership's set-operand guard: its SetOperand position must " +
+            'resolve to an array, which the schema guarantees. The injected ' +
+            'ResolveOperand returned something else — either a resolver ' +
+            'integration bug, or an unresolved reference set that slipped past ' +
+            'compilation (unresolved-reference-set); this guard cannot tell the ' +
+            'two apart.');
+    }
+    return booleanResult(setMembership(value, resolvedSet, ctx.artifactPath));
+}
+function resolveOrderingNode(expression, boundElement, ctx) {
+    const [operand] = expression.operands;
+    const { key, order } = expression;
+    return resolveSingleOperand(operand, boundElement, ctx, (resolved) => ordering(resolved, key, order, ctx.artifactPath));
+}
+function resolveCountToleranceNode(expression, boundElement, ctx) {
+    const [operand] = expression.operands;
+    const { expected, tolerance, relative } = expression;
+    return resolveSingleOperand(operand, boundElement, ctx, (resolved) => countTolerance(resolved, expected, tolerance, relative, ctx.artifactPath));
+}
+function resolveShapeNode(expression, boundElement, ctx) {
+    const [operand] = expression.operands;
+    const { descriptor } = expression;
+    return resolveSingleOperand(operand, boundElement, ctx, (resolved) => shape(resolved, descriptor, ctx.artifactPath));
+}
+// One entry per `Expression['op']`; the mapped type below fails to compile if
+// an op is missing or misassigned, since each key demands the handler typed
+// for exactly that variant. That check covers the closed union at compile
+// time; it cannot see an out-of-union op arriving at runtime, which is what
+// the guard in `resolveNode` is for.
+const operatorHandlers = {
+    not: resolveNotNode,
+    all: resolveAllNode,
+    any: resolveAnyNode,
+    'for-all': resolveQuantifierNode,
+    'for-any': resolveQuantifierNode,
+    'covers-by-key': resolveCoversByKeyNode,
+    equality: resolveEqualityNode,
+    'deep-equality': resolveDeepEqualityNode,
+    containment: resolveContainmentNode,
+    existence: resolveExistenceNode,
+    absence: resolveAbsenceNode,
+    regex: resolveRegexNode,
+    'set-membership': resolveSetMembershipNode,
+    ordering: resolveOrderingNode,
+    'count-tolerance': resolveCountToleranceNode,
+    shape: resolveShapeNode,
+};
+/**
+ * The recursive worker behind `resolveCheck`. Every `RuntimeFault` a leaf
+ * operator throws (only `regexMatch`'s two, currently) propagates undecorated;
+ * no branch here catches one.
+ */
+function resolveNode(expression, boundElement, ctx) {
+    // `operatorHandlers` is keyed by the closed `Expression['op']` union, so
+    // TypeScript sees no `undefined` branch. That does not bind the runtime:
+    // an out-of-union `op` (unvalidated input, or a future schema version) is
+    // what this guard catches. `Object.hasOwn`, not a truthy check: a plain
+    // object literal inherits `Object.prototype`, so `op: 'constructor'` would
+    // otherwise resolve to `Object` itself and slip past silently.
+    if (!Object.hasOwn(operatorHandlers, expression.op)) {
+        throw new Error(`resolveNode: unrecognized expression.op ${JSON.stringify(expression.op)}`);
+    }
+    const handler = operatorHandlers[expression.op];
+    return handler(expression, boundElement, ctx);
+}
+/**
+ * The public entry point. Walks `expression` and produces one
+ * `CheckResolutionValue`, exactly what `Outcome.checkResolution` needs,
+ * unmodified. `boundElement` starts `ABSENT` at the root, where no quantifier
+ * has bound anything yet.
+ */
+export function resolveCheck(expression, resolveOperand, pointerDenotesCollection, regexMatchStepBudget, artifactPath) {
+    return resolveNode(expression, ABSENT, {
+        resolveOperand,
+        pointerDenotesCollection,
+        regexMatchStepBudget,
+        artifactPath,
+    });
+}

package/dist/core/evaluate/resolved-value.d.ts

@@ -0,0 +1,9 @@
+/** the value domain every AD-4 operator resolves over. */
+import type { JsonValue } from '../schemas/primitives.ts';
+/**
+ * AD-26: a pointer that fails to resolve yields the symbol `ABSENT`, not
+ * `null` or a string literal, since `null` is itself a valid `JsonValue` and
+ * must stay distinguishable from a value that never resolved.
+ */
+export declare const ABSENT: unique symbol;
+export type ResolvedValue = JsonValue | typeof ABSENT;

package/dist/core/evaluate/resolved-value.js

@@ -0,0 +1,6 @@
+/**
+ * AD-26: a pointer that fails to resolve yields the symbol `ABSENT`, not
+ * `null` or a string literal, since `null` is itself a valid `JsonValue` and
+ * must stay distinguishable from a value that never resolved.
+ */
+export const ABSENT = Symbol('absent');

package/dist/core/failure-codes.d.ts

@@ -0,0 +1,18 @@
+/** AD-5's twenty-one compile-time failure codes, as data, in the table's order. */
+export declare const FAILURE_CODES: readonly ['missing-requirement-linkage', 'no-observable-success-criterion', 'unreachable-check-evidence', 'malformed-operator-expression', 'quantifier-over-non-collection', 'quantifier-nesting-exceeded', 'unresolved-reference-set', 'duplicate-operation-signature', 'undeclared-mandatory-input', 'oracle-missing-channel', 'direction-check-misaligned', 'unsupported-interface-kind', 'nested-temporal-clause', 'plan-exceeds-scripting-bound', 'rubric-scores-reasoning-prose', 'rubric-unanchored', 'rubric-evidence-unreachable', 'forbidden-input-floor-incomplete', 'scoped-reference-resolves-forbidden', 'waiver-incomplete', 'brief-exceeds-scripting-bound'];
+export type FailureCode = (typeof FAILURE_CODES)[number];
+/**
+ * AD-5's compile-time failure registry: thrown when a structural error fails
+ * compilation (or, for this code, the post-generation brief audit), since no
+ * artifact is emitted. Mirrors AD-28's `RuntimeFault` shape (`code`,
+ * `artifactPath`) without subclassing it, per the Consistency Conventions'
+ * Errors row keeping the two registries disjoint. Lives beside `FAILURE_CODES`
+ * because every code in that registry is thrown through it.
+ */
+export declare class StructuralFailure extends Error {
+    readonly code: FailureCode;
+    readonly artifactPath: string;
+    constructor(code: FailureCode, artifactPath: string, detail: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/core/failure-codes.js

@@ -0,0 +1,50 @@
+/** AD-5's twenty-one compile-time failure codes, as data, in the table's order. */
+// This lives in `core/`, since it's a plain data tuple and `core/schemas/`
+// is reserved for Zod definitions. The compiler that emits these codes lives
+// in `core/compile/`, one directory over.
+//
+// `scripts/check-ad5-registry.ts` checks this tuple against AD-5's own
+// registry table under `npm run validate`; the tuple's own invariants
+// (twenty-one members, unique, kebab-case) are locked in
+// tests/schemas/failure-codes.test.ts.
+export const FAILURE_CODES = [
+    'missing-requirement-linkage',
+    'no-observable-success-criterion',
+    'unreachable-check-evidence',
+    'malformed-operator-expression',
+    'quantifier-over-non-collection',
+    'quantifier-nesting-exceeded',
+    'unresolved-reference-set',
+    'duplicate-operation-signature',
+    'undeclared-mandatory-input',
+    'oracle-missing-channel',
+    'direction-check-misaligned',
+    'unsupported-interface-kind',
+    'nested-temporal-clause',
+    'plan-exceeds-scripting-bound',
+    'rubric-scores-reasoning-prose',
+    'rubric-unanchored',
+    'rubric-evidence-unreachable',
+    'forbidden-input-floor-incomplete',
+    'scoped-reference-resolves-forbidden',
+    'waiver-incomplete',
+    'brief-exceeds-scripting-bound',
+];
+/**
+ * AD-5's compile-time failure registry: thrown when a structural error fails
+ * compilation (or, for this code, the post-generation brief audit), since no
+ * artifact is emitted. Mirrors AD-28's `RuntimeFault` shape (`code`,
+ * `artifactPath`) without subclassing it, per the Consistency Conventions'
+ * Errors row keeping the two registries disjoint. Lives beside `FAILURE_CODES`
+ * because every code in that registry is thrown through it.
+ */
+export class StructuralFailure extends Error {
+    code;
+    artifactPath;
+    constructor(code, artifactPath, detail, options) {
+        super(`${code} in ${artifactPath}: ${detail}`, options);
+        this.name = 'StructuralFailure';
+        this.code = code;
+        this.artifactPath = artifactPath;
+    }
+}

package/dist/core/lineage/chain.d.ts

@@ -0,0 +1,49 @@
+import type { LineageChain } from '../schemas/evidence-artifact.ts';
+export declare const LINEAGE_DEFECT_CODES: readonly ['lineage-root-invalid', 'lineage-duplicate-artifact', 'lineage-no-root', 'lineage-multiple-roots', 'lineage-parent-absent', 'lineage-revision-not-successor', 'lineage-revision-conflict', 'lineage-length-inconsistent', 'lineage-remediation-cap-exceeded'];
+export type LineageDefectCode = (typeof LINEAGE_DEFECT_CODES)[number];
+/** The three fields `lineage.ts` spreads, as the shape this module reads. */
+export type LineageFields = {
+    readonly schemaVersion: number;
+    readonly parentDigest: string | null;
+    readonly revisionCount: number;
+};
+export type LineageFinding = {
+    readonly code: LineageDefectCode;
+    readonly artifactPath: string;
+    readonly detail: string;
+};
+export type LineageChainOptions = {
+    readonly artifactPath: string;
+    /** AD-11: a member outside this version throws `schema-version-mismatch`. */
+    readonly acceptedSchemaVersion: number;
+    /** AD-12's declared revision; the chain's length must be one greater. */
+    readonly declaredRevisionCount: number;
+    /** AD-12's remediation cap from the scoring policy, or null when none is presented. */
+    readonly remediationCap: number | null;
+};
+export type LineageChainReport = {
+    readonly artifactPath: string;
+    readonly findings: readonly LineageFinding[];
+    readonly checks: LineageChain;
+    readonly passed: boolean;
+};
+/**
+ * Which of AD-12's three booleans each code clears. A `Record` over the code
+ * union, so a tenth code is a compile error here before it can reach a report
+ * with no boolean to affect. The cap maps to null; AD-12 records it in
+ * `Remediation.cap`, beside `lineageChain`.
+ */
+export declare const CHECK_PROJECTION: Record<LineageDefectCode, keyof LineageChain | null>;
+/**
+ * Validates one presented chain of revisions of a single artifact type
+ * (AD-12, AD-29). Every defect is collected, so a chain with three problems
+ * reports three findings.
+ */
+export declare function validateLineageChain<T extends LineageFields>(artifacts: readonly T[], options: LineageChainOptions): LineageChainReport;
+/**
+ * Mints the next revision of `parent`: a new artifact carrying the parent's
+ * digest and a revision count one greater (AD-29). The clone is load-bearing.
+ * `{ ...body }` shares its subtrees with the caller and `freezeArtifact`
+ * freezes in place, so without it this call would freeze the caller's `body`.
+ */
+export declare function reviseArtifact<T extends LineageFields>(parent: T, body: Omit<T, 'parentDigest' | 'revisionCount'>, artifactPath: string): T;