eval-quality 0.1.0

package/dist/core/canonical/scan-json.js

@@ -0,0 +1,298 @@
+/** reads raw text, catches what JSON.parse hides */
+import { RuntimeFault } from '../schemas/faults.js';
+import { MAX_NESTING_DEPTH } from './value-domain.js';
+// Lexical pre-parse validation (AD-36): hashed-artifact input is scanned from
+// raw text, never handed to bare `JSON.parse`. Domain violations throw
+// `non-canonicalizable-value`; input that does not parse at all (malformed
+// syntax, bytes that fail fatal UTF-8 decoding) throws `schema-parse-failure`.
+export function scanJson(input, artifactPath) {
+    const text = typeof input === 'string' ? input : decodeUtf8(input, artifactPath);
+    return new Scanner(text, artifactPath).scanDocument();
+}
+function decodeUtf8(bytes, artifactPath) {
+    try {
+        // fatal: a non-fatal decode substitutes U+FFFD for invalid sequences (a
+        // producer's WTF-8-encoded lone surrogate would digest cleanly). ignoreBOM
+        // keeps a leading U+FEFF in the text, where it fails JSON syntax below;
+        // silently stripping it would let two implementations disagree on the same bytes.
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch (error) {
+        throw new RuntimeFault('schema-parse-failure', artifactPath, 'input is not valid UTF-8', { cause: error });
+    }
+}
+const SAFE_INTEGER_MAX = 2n ** 53n - 1n;
+const isDigit = (ch) => ch !== undefined && ch >= '0' && ch <= '9';
+const isAlphanumeric = (ch) => ch !== undefined && /[A-Za-z0-9]/.test(ch);
+class Scanner {
+    position = 0;
+    depth = 0;
+    // Assigned in the body: Node's type stripping refuses a constructor
+    // parameter property, and every script importing this module through
+    // `digest.ts` would die at load with `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`.
+    text;
+    artifactPath;
+    constructor(text, artifactPath) {
+        this.text = text;
+        this.artifactPath = artifactPath;
+    }
+    scanDocument() {
+        this.skipWhitespace();
+        const value = this.scanValue();
+        this.skipWhitespace();
+        if (this.position < this.text.length)
+            this.syntax('trailing content after the document');
+        return value;
+    }
+    syntax(detail) {
+        throw new RuntimeFault('schema-parse-failure', this.artifactPath, `${detail} at offset ${this.position}`);
+    }
+    domain(detail) {
+        throw new RuntimeFault('non-canonicalizable-value', this.artifactPath, `${detail} at offset ${this.position}`);
+    }
+    skipWhitespace() {
+        for (;;) {
+            const ch = this.text[this.position];
+            if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r')
+                this.position++;
+            else
+                return;
+        }
+    }
+    scanValue() {
+        const ch = this.text[this.position];
+        switch (ch) {
+            case undefined:
+                this.syntax('unexpected end of input');
+                break;
+            case '{':
+                return this.scanObject();
+            case '[':
+                return this.scanArray();
+            case '"':
+                return this.scanString();
+            case 't':
+                return this.scanLiteral('true', true);
+            case 'f':
+                return this.scanLiteral('false', false);
+            case 'n':
+                return this.scanLiteral('null', null);
+            default:
+                if (ch === '-' || isDigit(ch))
+                    return this.scanNumber();
+                this.syntax(`unexpected character ${JSON.stringify(ch)}`);
+        }
+    }
+    scanLiteral(literal, value) {
+        if (!this.text.startsWith(literal, this.position)) {
+            this.syntax(`invalid literal, expected ${literal}`);
+        }
+        this.position += literal.length;
+        // Rejects "truex" here as an invalid literal, not as a structural error
+        // surfacing later at the next comma or bracket.
+        if (isAlphanumeric(this.text[this.position])) {
+            this.syntax(`invalid literal starting with ${literal}`);
+        }
+        return value;
+    }
+    // See MAX_NESTING_DEPTH in value-domain.ts for why this is bounded.
+    enterNesting() {
+        if (++this.depth > MAX_NESTING_DEPTH) {
+            this.domain(`nesting depth exceeds ${MAX_NESTING_DEPTH}`);
+        }
+    }
+    scanObject() {
+        this.enterNesting();
+        this.position++; // consume {
+        const result = {};
+        const seenKeys = new Set();
+        this.skipWhitespace();
+        if (this.text[this.position] === '}') {
+            this.position++;
+            this.depth--;
+            return result;
+        }
+        for (;;) {
+            this.skipWhitespace();
+            if (this.text[this.position] !== '"')
+                this.syntax('expected a string object key');
+            const key = this.scanString();
+            // Duplicates are compared on unescaped keys: {"A":1,"A":2} is a duplicate.
+            if (seenKeys.has(key))
+                this.domain(`duplicate object key ${JSON.stringify(key)}`);
+            seenKeys.add(key);
+            this.skipWhitespace();
+            if (this.text[this.position] !== ':')
+                this.syntax("expected ':' after object key");
+            this.position++;
+            this.skipWhitespace();
+            const value = this.scanValue();
+            // A "__proto__" key must land as an own property, never a prototype mutation.
+            Object.defineProperty(result, key, {
+                value,
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+            this.skipWhitespace();
+            const next = this.text[this.position];
+            if (next === ',') {
+                this.position++;
+                continue;
+            }
+            if (next === '}') {
+                this.position++;
+                this.depth--;
+                return result;
+            }
+            this.syntax("expected ',' or '}' in object");
+        }
+    }
+    scanArray() {
+        this.enterNesting();
+        this.position++; // consume [
+        const result = [];
+        this.skipWhitespace();
+        if (this.text[this.position] === ']') {
+            this.position++;
+            this.depth--;
+            return result;
+        }
+        for (;;) {
+            this.skipWhitespace();
+            result.push(this.scanValue());
+            this.skipWhitespace();
+            const next = this.text[this.position];
+            if (next === ',') {
+                this.position++;
+                continue;
+            }
+            if (next === ']') {
+                this.position++;
+                this.depth--;
+                return result;
+            }
+            this.syntax("expected ',' or ']' in array");
+        }
+    }
+    scanString() {
+        this.position++; // consume opening quote
+        let result = '';
+        for (;;) {
+            const ch = this.text[this.position];
+            if (ch === undefined)
+                this.syntax('unterminated string');
+            if (ch === '"') {
+                this.position++;
+                break;
+            }
+            if (ch === '\\') {
+                result += this.scanEscape();
+                continue;
+            }
+            if (ch.charCodeAt(0) < 0x20)
+                this.syntax('unescaped control character in string');
+            result += ch;
+            this.position++;
+        }
+        // Covers literal surrogates and escaped ones alike, in values and keys.
+        if (!result.isWellFormed())
+            this.domain('lone surrogate in string');
+        return result;
+    }
+    scanEscape() {
+        this.position++; // consume backslash
+        const ch = this.text[this.position];
+        if (ch === undefined)
+            this.syntax('unterminated escape sequence');
+        this.position++;
+        switch (ch) {
+            case '"':
+                return '"';
+            case '\\':
+                return '\\';
+            case '/':
+                return '/';
+            case 'b':
+                return '\b';
+            case 'f':
+                return '\f';
+            case 'n':
+                return '\n';
+            case 'r':
+                return '\r';
+            case 't':
+                return '\t';
+            case 'u': {
+                const hex = this.text.slice(this.position, this.position + 4);
+                if (!/^[0-9a-fA-F]{4}$/.test(hex))
+                    this.syntax('invalid \\u escape');
+                this.position += 4;
+                return String.fromCharCode(Number.parseInt(hex, 16));
+            }
+            default:
+                this.syntax(`invalid escape character ${JSON.stringify(ch)}`);
+        }
+    }
+    scanNumber() {
+        const start = this.position;
+        if (this.text[this.position] === '-')
+            this.position++;
+        if (this.text[this.position] === '0') {
+            this.position++;
+            if (isDigit(this.text[this.position]))
+                this.syntax('leading zero in number');
+        }
+        else if (isDigit(this.text[this.position])) {
+            while (isDigit(this.text[this.position]))
+                this.position++;
+        }
+        else {
+            this.syntax('invalid number');
+        }
+        let integerSyntax = true;
+        if (this.text[this.position] === '.') {
+            integerSyntax = false;
+            this.position++;
+            if (!isDigit(this.text[this.position]))
+                this.syntax('expected digits after decimal point');
+            while (isDigit(this.text[this.position]))
+                this.position++;
+        }
+        if (this.text[this.position] === 'e' || this.text[this.position] === 'E') {
+            integerSyntax = false;
+            this.position++;
+            if (this.text[this.position] === '+' || this.text[this.position] === '-')
+                this.position++;
+            if (!isDigit(this.text[this.position]))
+                this.syntax('expected digits in exponent');
+            while (isDigit(this.text[this.position]))
+                this.position++;
+        }
+        if (isAlphanumeric(this.text[this.position])) {
+            this.syntax('invalid number');
+        }
+        const literal = this.text.slice(start, this.position);
+        if (integerSyntax) {
+            // Compared on the digits: JSON.parse would round 9007199254740993
+            // invisibly. 2^53 - 1 has 16 digits, so anything longer is unsafe by
+            // inspection. Checked first so a multi-megabyte literal never pays (or
+            // weaponizes) an arbitrary-precision BigInt conversion.
+            const digits = literal[0] === '-' ? literal.slice(1) : literal;
+            if (digits.length > 16 || BigInt(digits) > SAFE_INTEGER_MAX) {
+                this.domain(`integer literal outside the safe range: ${literal}`);
+            }
+        }
+        const value = Number(literal);
+        if (!Number.isFinite(value)) {
+            this.domain(`numeric literal is not finite in binary64: ${literal}`);
+        }
+        // Any literal whose binary64 value is an unsafe integer is rejected
+        // regardless of spelling (9007199254740993.0, 9.007199254740993e15, 1e21):
+        // two producers must not disagree.
+        if (Number.isInteger(value) && !Number.isSafeInteger(value)) {
+            this.domain(`numeric literal is an unsafe integer in binary64: ${literal}`);
+        }
+        return value;
+    }
+}

package/dist/core/canonical/value-domain.d.ts

@@ -0,0 +1,4 @@
+export declare const MAX_NESTING_DEPTH = 1024;
+export declare function assertHashedArtifactValue(value: unknown, artifactPath: string): void;
+export declare function assertDomainNumber(value: number, artifactPath: string, location: string): void;
+export declare function assertDomainString(value: string, artifactPath: string, location: string): void;

package/dist/core/canonical/value-domain.js

@@ -0,0 +1,113 @@
+/** same checks for values already in memory */
+import { RuntimeFault } from '../schemas/faults.js';
+// AD-36: a hashed artifact admits only finite binary64 numbers, integers within
+// the safe range, well-formed strings, and plain acyclic JSON structure. Larger
+// integers and exact decimals travel as strings with the declared formats in
+// `core/schemas/primitives.ts`; this layer enforces the numeric domain.
+// Structure bound, part of the value domain: nesting deeper than this rejects
+// with the typed fault, so pathological input can never escape as a bare
+// RangeError from the recursive walkers.
+export const MAX_NESTING_DEPTH = 1024;
+export function assertHashedArtifactValue(value, artifactPath) {
+    visit(value, artifactPath, '$', new Set(), 0);
+}
+const reject = (artifactPath, detail) => {
+    throw new RuntimeFault('non-canonicalizable-value', artifactPath, detail);
+};
+// Exported so canonicalize.ts can re-run these scalar checks at emit time, in
+// the single traversal that closes the TOCTOU gap described there.
+export function assertDomainNumber(value, artifactPath, location) {
+    if (!Number.isFinite(value)) {
+        reject(artifactPath, `non-finite number at ${location}`);
+    }
+    if (Number.isInteger(value) && !Number.isSafeInteger(value)) {
+        reject(artifactPath, `integer outside the safe range at ${location}: ${value}`);
+    }
+}
+export function assertDomainString(value, artifactPath, location) {
+    if (!value.isWellFormed()) {
+        reject(artifactPath, `lone surrogate in string at ${location}`);
+    }
+}
+function visit(value, artifactPath, location, ancestors, depth) {
+    switch (typeof value) {
+        case 'boolean':
+            return;
+        case 'number':
+            assertDomainNumber(value, artifactPath, location);
+            return;
+        case 'string':
+            assertDomainString(value, artifactPath, location);
+            return;
+        case 'object':
+            break;
+        default:
+            // undefined, function, bigint, symbol: unrepresentable, never coerced silently.
+            throw new RuntimeFault('non-canonicalizable-value', artifactPath, `${typeof value} is not a hashed-artifact value at ${location}`);
+    }
+    if (value === null)
+        return;
+    if (depth >= MAX_NESTING_DEPTH) {
+        reject(artifactPath, `nesting depth exceeds ${MAX_NESTING_DEPTH} at ${location}`);
+    }
+    if (ancestors.has(value)) {
+        reject(artifactPath, `cyclic reference at ${location}`);
+    }
+    ancestors.add(value);
+    if (Array.isArray(value)) {
+        // Arrays get the same plainness discipline as objects: a subclass or a
+        // toJSON carrier serializes differently under a stringify-honouring
+        // implementation, and non-index properties would be silently dropped.
+        if (Object.getPrototypeOf(value) !== Array.prototype) {
+            reject(artifactPath, `non-plain array at ${location}`);
+        }
+        if (typeof value.toJSON === 'function') {
+            reject(artifactPath, `array carrying toJSON at ${location}`);
+        }
+        assertOwnPropertiesArePlainData(value, artifactPath, location);
+        if (Object.keys(value).length !== value.length) {
+            reject(artifactPath, `array with holes or non-index properties at ${location}`);
+        }
+        for (const [index, element] of value.entries()) {
+            visit(element, artifactPath, `${location}[${index}]`, ancestors, depth + 1);
+        }
+    }
+    else {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            reject(artifactPath, `non-plain object at ${location}`);
+        }
+        if (typeof value.toJSON === 'function') {
+            reject(artifactPath, `object carrying toJSON at ${location}`);
+        }
+        assertOwnPropertiesArePlainData(value, artifactPath, location);
+        for (const [key, entry] of Object.entries(value)) {
+            if (!key.isWellFormed()) {
+                reject(artifactPath, `lone surrogate in object key at ${location}`);
+            }
+            visit(entry, artifactPath, `${location}.${key}`, ancestors, depth + 1);
+        }
+    }
+    ancestors.delete(value);
+}
+// Accessors, non-enumerable properties, and symbol-keyed properties are all
+// rejected outright; canonicalize.ts explains why (the TOCTOU channel a
+// second read reopens).
+function assertOwnPropertiesArePlainData(value, artifactPath, location) {
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+        reject(artifactPath, `symbol-keyed property at ${location}`);
+    }
+    for (const key of Object.getOwnPropertyNames(value)) {
+        if (key === 'length' && Array.isArray(value))
+            continue;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined)
+            continue;
+        if (!('value' in descriptor)) {
+            reject(artifactPath, `accessor property ${JSON.stringify(key)} at ${location}`);
+        }
+        if (!descriptor.enumerable) {
+            reject(artifactPath, `non-enumerable property ${JSON.stringify(key)} at ${location}`);
+        }
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * The pure, synchronous, fixed-order compile stage over an already-parsed
+ * `EvalContract`. No I/O, no state; every check throws `StructuralFailure`
+ * straight through to the caller.
+ *
+ * Call order is AD-5's registry order, the only published stable priority: a
+ * contract violating several checks reports whichever runs first. The
+ * `malformed-operator-expression` trio (`checkBoundElementScope`,
+ * `checkOperandLegality`, `checkRegexConstructs`) keeps that suborder so
+ * their shared result stays deterministic. `checkUndeclaredMandatoryInput`
+ * runs only when `options.strict` is true (AD-4), and AD-10's
+ * `checkSensitivityWitnessDeclared` joins it there because it fires the same
+ * code; the other two witness checks fire different codes and run
+ * unconditionally, after the registry order, since AD-5 names no rung for them.
+ *
+ * `checkRubricIdentifiers` fires `rubric-unanchored` but runs ahead of
+ * `checkRubricReasoningProse`, which outranks it in the registry. A duplicated
+ * rubric or criterion id makes every `rubrics[id=...]` path the other three
+ * rubric checks emit address two things, so identifiers are settled before any
+ * of them reports.
+ */
+import type { EvalContract } from '../schemas/eval-contract.ts';
+import type { CompileOptions } from '../stage-contracts.ts';
+export declare function compile(contract: EvalContract, options: CompileOptions): EvalContract;

package/dist/core/compile/compile.js

@@ -0,0 +1,67 @@
+/**
+ * The pure, synchronous, fixed-order compile stage over an already-parsed
+ * `EvalContract`. No I/O, no state; every check throws `StructuralFailure`
+ * straight through to the caller.
+ *
+ * Call order is AD-5's registry order, the only published stable priority: a
+ * contract violating several checks reports whichever runs first. The
+ * `malformed-operator-expression` trio (`checkBoundElementScope`,
+ * `checkOperandLegality`, `checkRegexConstructs`) keeps that suborder so
+ * their shared result stays deterministic. `checkUndeclaredMandatoryInput`
+ * runs only when `options.strict` is true (AD-4), and AD-10's
+ * `checkSensitivityWitnessDeclared` joins it there because it fires the same
+ * code; the other two witness checks fire different codes and run
+ * unconditionally, after the registry order, since AD-5 names no rung for them.
+ *
+ * `checkRubricIdentifiers` fires `rubric-unanchored` but runs ahead of
+ * `checkRubricReasoningProse`, which outranks it in the registry. A duplicated
+ * rubric or criterion id makes every `rubrics[id=...]` path the other three
+ * rubric checks emit address two things, so identifiers are settled before any
+ * of them reports.
+ */
+import { checkObservableSuccessCriterion, checkRequirementLinkage, } from './declarations.js';
+import { checkOperandLegality, checkQuantifierNesting, checkQuantifierOverNonCollection, checkReferenceSetResolution, checkRegexConstructs, } from './expression-legality.js';
+import { checkForbiddenInputFloor, checkScopedResourceReferences, } from './forbidden-inputs.js';
+import { checkDuplicateOperationSignature, checkInterfaceKind, checkUndeclaredMandatoryInput, } from './interface-inventory.js';
+import { checkOracleAlignment, checkOracleChannel } from './oracle-alignment.js';
+import { checkBoundElementScope, checkEvidenceReachability, } from './reachability.js';
+import { checkRubricAnchoring, checkRubricEvidenceReachability, checkRubricIdentifiers, checkRubricReasoningProse, } from './rubrics.js';
+import { checkNestedTemporalClause, checkScriptingBound, } from './scripting-bound.js';
+import { checkSensitivityWitnessDeclared, checkWitnessLegality, checkWitnessLegIdentifiers, } from './sensitivity-witness.js';
+import { checkWaiverCompleteness } from './waivers.js';
+export function compile(contract, options) {
+    checkRequirementLinkage(contract);
+    checkObservableSuccessCriterion(contract);
+    checkEvidenceReachability(contract);
+    checkBoundElementScope(contract);
+    checkOperandLegality(contract);
+    checkRegexConstructs(contract);
+    checkQuantifierOverNonCollection(contract);
+    checkQuantifierNesting(contract);
+    checkReferenceSetResolution(contract);
+    checkDuplicateOperationSignature(contract);
+    if (options.strict) {
+        checkUndeclaredMandatoryInput(contract);
+        checkSensitivityWitnessDeclared(contract);
+    }
+    checkOracleChannel(contract);
+    checkOracleAlignment(contract);
+    checkInterfaceKind(contract);
+    checkNestedTemporalClause(contract);
+    checkScriptingBound(contract);
+    checkRubricIdentifiers(contract);
+    checkRubricReasoningProse(contract);
+    checkRubricAnchoring(contract);
+    checkRubricEvidenceReachability(contract);
+    checkForbiddenInputFloor(contract);
+    checkScopedResourceReferences(contract);
+    checkWaiverCompleteness(contract);
+    // Identifiers before legality. A duplicated or plan-colliding leg id makes
+    // the legality check's question ("does the relation address both legs?")
+    // unanswerable, so legality-first reports an unreachable-evidence failure on
+    // a contract whose actual defect is the collision, and every identifier
+    // fixture would need a second mutation to reach its own code.
+    checkWitnessLegIdentifiers(contract);
+    checkWitnessLegality(contract);
+    return contract;
+}

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

@@ -0,0 +1,5 @@
+import type { EvalContract } from '../schemas/eval-contract.ts';
+/** Rejects a behavior whose requirement and risk link lists are both empty. */
+export declare function checkRequirementLinkage(contract: EvalContract): void;
+/** A null criterion fails. An empty oracle list remains valid. */
+export declare function checkObservableSuccessCriterion(contract: EvalContract): void;

package/dist/core/compile/declarations.js

@@ -0,0 +1,22 @@
+/**
+ * Checks AD-19 behavior declarations for requirement or risk linkage and an
+ * observable success criterion. Each check reports the first violation.
+ */
+import { StructuralFailure } from '../failure-codes.js';
+/** Rejects a behavior whose requirement and risk link lists are both empty. */
+export function checkRequirementLinkage(contract) {
+    for (const behavior of contract.behaviors) {
+        if (behavior.requirementLinks.length === 0 &&
+            behavior.riskLinks.length === 0) {
+            throw new StructuralFailure('missing-requirement-linkage', `EvalContract.behaviors[id=${behavior.id}]`, 'declares neither a requirementLinks nor a riskLinks entry (AD-19)');
+        }
+    }
+}
+/** A null criterion fails. An empty oracle list remains valid. */
+export function checkObservableSuccessCriterion(contract) {
+    for (const behavior of contract.behaviors) {
+        if (behavior.observableSuccessCriterion === null) {
+            throw new StructuralFailure('no-observable-success-criterion', `EvalContract.behaviors[id=${behavior.id}].observableSuccessCriterion`, 'declares no observable success criterion (AD-19)');
+        }
+    }
+}

package/dist/core/compile/expression-legality.d.ts

@@ -0,0 +1,14 @@
+import type { EvalContract } from '../schemas/eval-contract.ts';
+/** Checks each operator's operands against its position-specific constraints. */
+export declare function checkOperandLegality(contract: EvalContract): void;
+/** Rejects invalid regexes, partial anchors, backreferences, and lookbehind. */
+export declare function checkRegexConstructs(contract: EvalContract): void;
+/** Rejects nested quantifiers and covers-by-key inside a quantifier. */
+export declare function checkQuantifierNesting(contract: EvalContract): void;
+/** Checks response-body collection pointers, after bound-element substitution. */
+export declare function checkQuantifierOverNonCollection(contract: EvalContract): void;
+/**
+ * Checks every reference-set operand with an own-property lookup.
+ * This preserves legal identifiers such as `constructor`.
+ */
+export declare function checkReferenceSetResolution(contract: EvalContract): void;