@dzhechkov/harness-core 0.8.2 → 0.8.6

package/dist/contract-checklist.js

@@ -0,0 +1,700 @@
+/**
+ * Pure contract-checklist policy for feature-ADR artifacts.
+ *
+ * Markdown/JSON text and injected evidence reads go in; typed decisions come out. Filesystem
+ * discovery, realpath confinement, rendering to a terminal, and process exits belong to the CLI.
+ */
+export const CONTRACT_CHECKLIST_SCHEMA = 'contract-checklist/1';
+export const CONTRACT_VERDICT_SCHEMA = 'contract-checklist-verdict/1';
+const REQUIREMENTS_HEADING = '## Acceptance criteria';
+const CONFIRMATION_HEADING = '## Confirmation';
+const VERDICT_HEADING = '## Contract checklist';
+const REQUIREMENTS_FORMAT_LINE = 'Format: Every acceptance criterion below is exactly one physical line matching `^AC-([1-9][0-9]*): (\\S.*)$`; identifiers are contiguous from `AC-1`, and only the literal H2 `## Acceptance criteria` establishes this source section.';
+const ADR_BASENAME = /^([0-9]{3})-[a-z][a-z0-9]*(?:-[a-z0-9]+)*\.md$/;
+const ACCEPTANCE_ROW = /^AC-([1-9][0-9]*): (\S.*)$/;
+const LOAD_PROPERTY = /^- Load-bearing property:(?: (.*))?$/;
+const REQUIRED_CHECK = /^- Required automated check:(?: (.*))?$/;
+function linesOf(text) {
+    return text.replace(/\r\n?/g, '\n').split('\n');
+}
+function h2Indexes(lines, heading) {
+    const indexes = [];
+    for (let index = 0; index < lines.length; index++) {
+        if (lines[index] === heading)
+            indexes.push(index);
+    }
+    return indexes;
+}
+function h2End(lines, start) {
+    for (let index = start + 1; index < lines.length; index++) {
+        if (/^## (?!#)\S/.test(lines[index] ?? ''))
+            return index;
+    }
+    return lines.length;
+}
+function diagnostic(code, message, fields = {}) {
+    return { code, message, ...fields };
+}
+function acceptanceItems(artifact, diagnostics) {
+    const lines = linesOf(artifact.text);
+    const headings = h2Indexes(lines, REQUIREMENTS_HEADING);
+    if (headings.length !== 1) {
+        diagnostics.push(diagnostic(headings.length === 0 ? 'requirements-section-missing' : 'requirements-section-duplicate', `expected exactly one ${REQUIREMENTS_HEADING} section; found ${headings.length}`, { artifact: artifact.path, section: REQUIREMENTS_HEADING, observed: headings.length }));
+        return [];
+    }
+    const start = headings[0];
+    const end = h2End(lines, start);
+    const out = [];
+    for (let index = start + 1; index < end; index++) {
+        const line = lines[index] ?? '';
+        if (line.trim() === '' || line === REQUIREMENTS_FORMAT_LINE)
+            continue;
+        const match = ACCEPTANCE_ROW.exec(line);
+        if (!match) {
+            diagnostics.push(diagnostic('acceptance-row-malformed', `non-canonical acceptance content at line ${index + 1}`, { artifact: artifact.path, section: REQUIREMENTS_HEADING, observed: line }));
+            continue;
+        }
+        const number = Number(match[1]);
+        out.push({
+            sourceId: `AC-${number}`,
+            sourceKind: 'acceptance-criterion',
+            statement: match[2],
+            sourcePath: artifact.path,
+            sourceLine: index + 1,
+        });
+    }
+    return out;
+}
+function validateAcceptanceIds(items, artifact, diagnostics) {
+    if (items.length === 0) {
+        diagnostics.push(diagnostic('acceptance-items-empty', 'the Acceptance criteria section contains zero canonical rows', { artifact: artifact.path, section: REQUIREMENTS_HEADING, observed: 0 }));
+        return;
+    }
+    const seen = new Set();
+    for (let index = 0; index < items.length; index++) {
+        const item = items[index];
+        if (seen.has(item.sourceId)) {
+            diagnostics.push(diagnostic('acceptance-id-duplicate', `duplicate acceptance identity ${item.sourceId}`, { artifact: artifact.path, section: REQUIREMENTS_HEADING, sourceId: item.sourceId }));
+        }
+        seen.add(item.sourceId);
+        const expected = `AC-${index + 1}`;
+        if (item.sourceId !== expected) {
+            diagnostics.push(diagnostic('acceptance-id-noncontiguous', `expected ${expected} at contract position ${index + 1}; found ${item.sourceId}`, { artifact: artifact.path, section: REQUIREMENTS_HEADING, sourceId: item.sourceId, observed: expected }));
+        }
+    }
+}
+function fieldContinuation(lines, fieldIndex, end) {
+    const nextIndex = fieldIndex + 1;
+    if (nextIndex >= end)
+        return null;
+    const next = lines[nextIndex] ?? '';
+    if (next.trim() === '' || /^- \S/.test(next))
+        return null;
+    return { line: nextIndex + 1, text: next };
+}
+function confirmationItem(artifact, diagnostics) {
+    const basename = artifact.path.replace(/\\/g, '/').split('/').at(-1) ?? '';
+    const filename = ADR_BASENAME.exec(basename);
+    if (!filename) {
+        diagnostics.push(diagnostic('adr-filename-noncanonical', `direct ADR Markdown file ${basename} is not a canonical NNN-lowercase-kebab filename`, { artifact: artifact.path, observed: basename }));
+        return null;
+    }
+    const lines = linesOf(artifact.text);
+    const headings = h2Indexes(lines, CONFIRMATION_HEADING);
+    if (headings.length !== 1) {
+        diagnostics.push(diagnostic(headings.length === 0 ? 'confirmation-section-missing' : 'confirmation-section-duplicate', `expected exactly one ${CONFIRMATION_HEADING} section; found ${headings.length}`, { artifact: artifact.path, section: CONFIRMATION_HEADING, observed: headings.length }));
+        return null;
+    }
+    const start = headings[0];
+    const end = h2End(lines, start);
+    const properties = [];
+    const checks = [];
+    for (let index = start + 1; index < end; index++) {
+        const line = lines[index] ?? '';
+        const property = LOAD_PROPERTY.exec(line);
+        const check = REQUIRED_CHECK.exec(line);
+        if (line.startsWith('- Load-bearing property:'))
+            properties.push({ index, value: property?.[1] ?? '' });
+        if (line.startsWith('- Required automated check:'))
+            checks.push({ index, value: check?.[1] ?? '' });
+    }
+    const propertyValid = properties.length === 1 && /^\S.*$/.test(properties[0]?.value ?? '');
+    const checkValid = checks.length === 1 && /^\S.*$/.test(checks[0]?.value ?? '');
+    if (!propertyValid) {
+        const observed = properties.length === 1 ? 0 : properties.length;
+        diagnostics.push(diagnostic('confirmation-property-count', `expected one non-empty Load-bearing property field; found ${observed}`, { artifact: artifact.path, section: CONFIRMATION_HEADING, observed }));
+    }
+    if (!checkValid) {
+        const observed = checks.length === 1 ? 0 : checks.length;
+        diagnostics.push(diagnostic('confirmation-check-count', `expected one non-empty Required automated check field; found ${observed}`, { artifact: artifact.path, section: CONFIRMATION_HEADING, observed }));
+    }
+    if (!propertyValid || !checkValid)
+        return null;
+    const property = properties[0];
+    const check = checks[0];
+    let wrapped = false;
+    for (const [label, field] of [['Load-bearing property', property], ['Required automated check', check]]) {
+        const continuation = fieldContinuation(lines, field.index, end);
+        if (continuation !== null) {
+            wrapped = true;
+            diagnostics.push(diagnostic('confirmation-field-wrapped', `${label} must occupy one physical line; continuation found at line ${continuation.line}`, {
+                artifact: artifact.path,
+                section: CONFIRMATION_HEADING,
+                sourceId: `ADR-${filename[1]}-CONFIRMATION`,
+                observed: continuation.text,
+            }));
+        }
+    }
+    if (wrapped)
+        return null;
+    return {
+        sourceId: `ADR-${filename[1]}-CONFIRMATION`,
+        sourceKind: 'adr-confirmation',
+        statement: property.value,
+        requiredAutomatedCheck: check.value,
+        sourcePath: artifact.path,
+        sourceLine: property.index + 1,
+    };
+}
+export function extractContractChecklist(input) {
+    const diagnostics = [];
+    const requirements = acceptanceItems(input.requirements, diagnostics);
+    validateAcceptanceIds(requirements, input.requirements, diagnostics);
+    if (input.adrs.length === 0) {
+        diagnostics.push(diagnostic('adr-input-empty', 'at least one direct canonical ADR Markdown file is required', { section: CONFIRMATION_HEADING, observed: 0 }));
+    }
+    const adrBasename = (path) => path.replace(/\\/g, '/').split('/').at(-1) ?? '';
+    const sortedAdrs = [...input.adrs].sort((a, b) => {
+        const aName = adrBasename(a.path);
+        const bName = adrBasename(b.path);
+        if (aName !== bName)
+            return aName < bName ? -1 : 1;
+        return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+    });
+    const confirmations = [];
+    for (const artifact of sortedAdrs) {
+        const item = confirmationItem(artifact, diagnostics);
+        if (item !== null)
+            confirmations.push(item);
+    }
+    const pending = [...requirements, ...confirmations];
+    const seen = new Set();
+    for (const item of pending) {
+        if (seen.has(item.sourceId)) {
+            diagnostics.push(diagnostic('contract-source-id-duplicate', `duplicate emitted source identity ${item.sourceId}`, { artifact: item.sourcePath, sourceId: item.sourceId }));
+        }
+        seen.add(item.sourceId);
+    }
+    if (pending.length === 0) {
+        diagnostics.push(diagnostic('contract-empty', 'the combined contract contains zero items', { observed: 0 }));
+    }
+    if (diagnostics.length > 0)
+        return { ok: false, diagnostics };
+    const items = pending.map((item, index) => ({ id: `CC-${index + 1}`, ...item }));
+    return {
+        ok: true,
+        checklist: { schema: CONTRACT_CHECKLIST_SCHEMA, items },
+        diagnostics: [],
+    };
+}
+export function renderContractChecklist(checklist) {
+    return `\`\`\`contract-checklist\n${JSON.stringify(checklist, null, 2)}\n\`\`\``;
+}
+class JsonDecodeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** Strict JSON decoder whose object parser sees duplicate members before a value can overwrite one. */
+class DuplicateSafeJsonDecoder {
+    text;
+    index = 0;
+    constructor(text) {
+        this.text = text;
+    }
+    decode() {
+        const value = this.value();
+        this.space();
+        if (this.index !== this.text.length)
+            throw new JsonDecodeError('json-trailing-content', `unexpected content at byte ${this.index}`);
+        return value;
+    }
+    space() {
+        while (/[\t\n\r ]/.test(this.text[this.index] ?? ''))
+            this.index++;
+    }
+    value() {
+        this.space();
+        const char = this.text[this.index];
+        if (char === '{')
+            return this.object();
+        if (char === '[')
+            return this.array();
+        if (char === '"')
+            return this.string();
+        if (char === '-' || (char !== undefined && /[0-9]/.test(char)))
+            return this.number();
+        for (const [token, value] of [['true', true], ['false', false], ['null', null]]) {
+            if (this.text.startsWith(token, this.index)) {
+                this.index += token.length;
+                return value;
+            }
+        }
+        throw new JsonDecodeError('json-invalid', `expected a JSON value at byte ${this.index}`);
+    }
+    object() {
+        this.index++;
+        // A null prototype makes decoded member names inert data. Assigning `__proto__` into `{}`
+        // invokes the legacy prototype setter and would hide that member from Object.keys/closed-schema
+        // validation instead of reporting it as unknown.
+        const value = Object.create(null);
+        const keys = new Set();
+        this.space();
+        if (this.text[this.index] === '}') {
+            this.index++;
+            return value;
+        }
+        while (true) {
+            this.space();
+            if (this.text[this.index] !== '"')
+                throw new JsonDecodeError('json-invalid', `expected an object key at byte ${this.index}`);
+            const key = this.string();
+            if (keys.has(key))
+                throw new JsonDecodeError('json-duplicate-member', `duplicate JSON member ${JSON.stringify(key)}`);
+            keys.add(key);
+            this.space();
+            if (this.text[this.index] !== ':')
+                throw new JsonDecodeError('json-invalid', `expected ':' after ${JSON.stringify(key)}`);
+            this.index++;
+            value[key] = this.value();
+            this.space();
+            const delimiter = this.text[this.index];
+            if (delimiter === '}') {
+                this.index++;
+                return value;
+            }
+            if (delimiter !== ',')
+                throw new JsonDecodeError('json-invalid', `expected ',' or '}' at byte ${this.index}`);
+            this.index++;
+        }
+    }
+    array() {
+        this.index++;
+        const value = [];
+        this.space();
+        if (this.text[this.index] === ']') {
+            this.index++;
+            return value;
+        }
+        while (true) {
+            value.push(this.value());
+            this.space();
+            const delimiter = this.text[this.index];
+            if (delimiter === ']') {
+                this.index++;
+                return value;
+            }
+            if (delimiter !== ',')
+                throw new JsonDecodeError('json-invalid', `expected ',' or ']' at byte ${this.index}`);
+            this.index++;
+        }
+    }
+    string() {
+        const start = this.index;
+        this.index++;
+        let escaped = false;
+        while (this.index < this.text.length) {
+            const char = this.text[this.index];
+            if (!escaped && char === '"') {
+                this.index++;
+                try {
+                    return JSON.parse(this.text.slice(start, this.index));
+                }
+                catch {
+                    throw new JsonDecodeError('json-invalid-string', `invalid JSON string at byte ${start}`);
+                }
+            }
+            if (!escaped && char.charCodeAt(0) < 0x20)
+                throw new JsonDecodeError('json-invalid-string', `control character at byte ${this.index}`);
+            if (!escaped && char === '\\')
+                escaped = true;
+            else
+                escaped = false;
+            this.index++;
+        }
+        throw new JsonDecodeError('json-invalid-string', `unterminated JSON string at byte ${start}`);
+    }
+    number() {
+        const match = /-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/.exec(this.text.slice(this.index));
+        if (!match || match.index !== 0)
+            throw new JsonDecodeError('json-invalid-number', `invalid number at byte ${this.index}`);
+        this.index += match[0].length;
+        const value = Number(match[0]);
+        if (!Number.isFinite(value))
+            throw new JsonDecodeError('json-invalid-number', `non-finite number at byte ${this.index}`);
+        return value;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function exactKeys(value, allowed, required, location, diagnostics, fields = {}) {
+    const allowedSet = new Set(allowed);
+    for (const key of Object.keys(value)) {
+        if (!allowedSet.has(key))
+            diagnostics.push(diagnostic('verdict-unknown-member', `${location} contains unknown member ${key}`, { ...fields, observed: key }));
+    }
+    for (const key of required) {
+        if (!Object.prototype.hasOwnProperty.call(value, key)) {
+            diagnostics.push(diagnostic('verdict-member-missing', `${location} is missing required member ${key}`, { ...fields, observed: key }));
+        }
+    }
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+function validateEvidence(value, location, diagnostics, contractId) {
+    const fields = contractId === undefined ? {} : { contractId };
+    if (!isRecord(value)) {
+        diagnostics.push(diagnostic('verdict-evidence-type', `${location}.evidence must be an object`, fields));
+        return null;
+    }
+    exactKeys(value, ['artifact', 'quote', 'observedOutcome'], ['artifact', 'quote', 'observedOutcome'], `${location}.evidence`, diagnostics, fields);
+    if (!nonEmptyString(value['artifact']))
+        diagnostics.push(diagnostic('verdict-artifact-type', `${location}.evidence.artifact must be a non-empty string`, fields));
+    if (!nonEmptyString(value['quote']))
+        diagnostics.push(diagnostic('verdict-quote-type', `${location}.evidence.quote must be a non-empty string`, fields));
+    const observed = value['observedOutcome'];
+    if (observed !== 'pass' && observed !== 'fail' && observed !== 'not-testable') {
+        diagnostics.push(diagnostic('verdict-observed-outcome', `${location}.evidence.observedOutcome is not canonical`, { ...fields, observed: String(observed) }));
+    }
+    if (!nonEmptyString(value['artifact']) || !nonEmptyString(value['quote'])
+        || (observed !== 'pass' && observed !== 'fail' && observed !== 'not-testable'))
+        return null;
+    return { artifact: value['artifact'], quote: value['quote'], observedOutcome: observed };
+}
+function validateVerdictItem(value, index, diagnostics) {
+    const location = `items[${index}]`;
+    if (!isRecord(value)) {
+        diagnostics.push(diagnostic('verdict-row-type', `${location} must be an object`, { observed: Array.isArray(value) ? 'array' : typeof value }));
+        return null;
+    }
+    const contractId = typeof value['id'] === 'string' ? value['id'] : undefined;
+    const fields = contractId === undefined ? {} : { contractId };
+    exactKeys(value, ['id', 'verdict', 'evidence', 'reason'], ['id', 'verdict', 'evidence'], location, diagnostics, fields);
+    if (!nonEmptyString(value['id']))
+        diagnostics.push(diagnostic('verdict-id-type', `${location}.id must be a non-empty string`, fields));
+    const verdict = value['verdict'];
+    if (verdict !== 'met' && verdict !== 'unmet' && verdict !== 'not-testable') {
+        diagnostics.push(diagnostic('verdict-status-invalid', `${location}.verdict is not canonical`, { ...fields, observed: String(verdict) }));
+    }
+    const evidence = validateEvidence(value['evidence'], location, diagnostics, contractId);
+    const reason = value['reason'];
+    if ((verdict === 'unmet' || verdict === 'not-testable') && !nonEmptyString(reason)) {
+        diagnostics.push(diagnostic('verdict-reason-required', `${location}.reason must be non-empty for ${verdict}`, fields));
+    }
+    if (reason !== undefined && !nonEmptyString(reason)) {
+        diagnostics.push(diagnostic('verdict-reason-type', `${location}.reason must be a non-empty string when present`, fields));
+    }
+    if (!nonEmptyString(value['id']) || (verdict !== 'met' && verdict !== 'unmet' && verdict !== 'not-testable') || evidence === null)
+        return null;
+    if ((verdict === 'unmet' || verdict === 'not-testable') && !nonEmptyString(reason))
+        return null;
+    return {
+        id: value['id'],
+        verdict,
+        evidence,
+        ...(nonEmptyString(reason) ? { reason } : {}),
+    };
+}
+function validateVerdictPayload(value) {
+    const diagnostics = [];
+    if (!isRecord(value)) {
+        return { ok: false, diagnostics: [diagnostic('verdict-payload-type', 'the verdict payload must be a JSON object')] };
+    }
+    exactKeys(value, ['schema', 'overallGrade', 'items'], ['schema', 'overallGrade', 'items'], 'payload', diagnostics);
+    if (value['schema'] !== CONTRACT_VERDICT_SCHEMA) {
+        diagnostics.push(diagnostic('verdict-schema-unsupported', `unsupported verdict schema ${String(value['schema'])}`, { observed: String(value['schema']) }));
+    }
+    const grade = value['overallGrade'];
+    if (grade !== 'A' && grade !== 'B' && grade !== 'C' && grade !== 'D') {
+        diagnostics.push(diagnostic('verdict-grade-invalid', 'overallGrade must be A, B, C, or D', { observed: String(grade) }));
+    }
+    const rawItems = value['items'];
+    if (!Array.isArray(rawItems)) {
+        diagnostics.push(diagnostic('verdict-items-type', 'payload.items must be an array'));
+    }
+    const items = [];
+    if (Array.isArray(rawItems)) {
+        for (let index = 0; index < rawItems.length; index++) {
+            const item = validateVerdictItem(rawItems[index], index, diagnostics);
+            if (item !== null)
+                items.push(item);
+        }
+    }
+    if (diagnostics.length > 0 || value['schema'] !== CONTRACT_VERDICT_SCHEMA
+        || (grade !== 'A' && grade !== 'B' && grade !== 'C' && grade !== 'D') || !Array.isArray(rawItems)) {
+        return { ok: false, diagnostics };
+    }
+    return { ok: true, report: { schema: CONTRACT_VERDICT_SCHEMA, overallGrade: grade, items } };
+}
+function parseHumanGrade(text) {
+    const lines = linesOf(text);
+    const grades = [];
+    for (let index = 0; index < lines.length; index++) {
+        const heading = /^## Grade: \*\*([A-D])\*\*$/.exec(lines[index] ?? '');
+        if (heading)
+            grades.push(heading[1]);
+        if (lines[index] === '## Grade') {
+            const end = h2End(lines, index);
+            for (let cursor = index + 1; cursor < end; cursor++) {
+                const field = /^\*\*Grade: ([A-D])\*\*$/.exec(lines[cursor] ?? '');
+                if (field)
+                    grades.push(field[1]);
+            }
+        }
+    }
+    if (grades.length !== 1) {
+        return {
+            ok: false,
+            diagnostic: diagnostic('report-grade-ambiguous', `expected exactly one human Grade A-D value; found ${grades.length}`, { section: '## Grade', observed: grades }),
+        };
+    }
+    return { ok: true, grade: grades[0] };
+}
+export function parseContractVerdictReport(text) {
+    const lines = linesOf(text);
+    const headings = h2Indexes(lines, VERDICT_HEADING);
+    if (headings.length === 0) {
+        return {
+            ok: false,
+            established: false,
+            diagnostics: [diagnostic('verdict-section-missing', `missing canonical ${VERDICT_HEADING} section`, { section: VERDICT_HEADING })],
+        };
+    }
+    if (headings.length !== 1) {
+        return {
+            ok: false,
+            established: true,
+            diagnostics: [diagnostic('verdict-section-duplicate', `expected exactly one ${VERDICT_HEADING} section; found ${headings.length}`, { section: VERDICT_HEADING, observed: headings.length })],
+        };
+    }
+    const start = headings[0];
+    const section = lines.slice(start + 1, h2End(lines, start)).join('\n').trim();
+    const fence = /^```json\n([\s\S]*)\n```$/.exec(section);
+    if (!fence) {
+        return {
+            ok: false,
+            established: true,
+            diagnostics: [diagnostic('verdict-fence-invalid', 'the Contract checklist section must contain exactly one fenced json object and no other content', { section: VERDICT_HEADING })],
+        };
+    }
+    let decoded;
+    try {
+        decoded = new DuplicateSafeJsonDecoder(fence[1]).decode();
+    }
+    catch (error) {
+        const jsonError = error instanceof JsonDecodeError ? error : new JsonDecodeError('json-invalid', String(error));
+        return {
+            ok: false,
+            established: true,
+            diagnostics: [diagnostic(jsonError.code, jsonError.message, { section: VERDICT_HEADING })],
+        };
+    }
+    const payload = validateVerdictPayload(decoded);
+    if (!payload.ok) {
+        return {
+            ok: false,
+            established: true,
+            diagnostics: payload.diagnostics.map((entry) => ({ ...entry, section: entry.section ?? VERDICT_HEADING })),
+        };
+    }
+    const human = parseHumanGrade(text);
+    if (!human.ok)
+        return { ok: false, established: true, diagnostics: [human.diagnostic] };
+    if (human.grade !== payload.report.overallGrade) {
+        return {
+            ok: false,
+            established: true,
+            diagnostics: [diagnostic('report-grade-mismatch', `human Grade ${human.grade} disagrees with payload overallGrade ${payload.report.overallGrade}`, { section: '## Grade', observed: [human.grade, payload.report.overallGrade] })],
+        };
+    }
+    return { ok: true, report: payload.report, humanGrade: human.grade, diagnostics: [] };
+}
+function contractIdNumber(id) {
+    const match = /^CC-([1-9][0-9]*)$/.exec(id);
+    return match ? Number(match[1]) : null;
+}
+function quoteOccurrences(text, quote) {
+    let count = 0;
+    let index = 0;
+    while (index <= text.length - quote.length) {
+        const found = text.indexOf(quote, index);
+        if (found < 0)
+            break;
+        count++;
+        index = found + 1;
+    }
+    return count;
+}
+function safeEvidenceArtifact(artifact) {
+    if (artifact.startsWith('/') || artifact.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(artifact))
+        return 'absolute paths are forbidden';
+    if (artifact.includes('\\'))
+        return 'backslash path separators are forbidden';
+    const parts = artifact.split('/');
+    if (parts.some((part) => part === '' || part === '.' || part === '..'))
+        return 'empty, dot, and traversal path segments are forbidden';
+    return null;
+}
+function baseCounts(checklist, report) {
+    // `verifyContractVerdicts` is a public runtime boundary even though TypeScript callers receive a
+    // typed signature. Count defensively before the closed-schema validator reports malformed rows.
+    const rows = isRecord(report) && Array.isArray(report['items']) ? report['items'] : [];
+    const hasVerdict = (value, verdict) => isRecord(value) && value['verdict'] === verdict;
+    return {
+        contractItems: checklist.items.length,
+        verdictItems: rows.length,
+        met: rows.filter((item) => hasVerdict(item, 'met')).length,
+        unmet: rows.filter((item) => hasVerdict(item, 'unmet')).length,
+        notTestable: rows.filter((item) => hasVerdict(item, 'not-testable')).length,
+        missing: 0,
+        duplicate: 0,
+        orphan: 0,
+        invalidEvidence: 0,
+        gradeConflicts: 0,
+    };
+}
+function failedVerification(checklist, report, diagnostics, counts, items) {
+    return {
+        outcome: 'fail',
+        exitCode: 1,
+        overallGrade: isRecord(report)
+            && (report['overallGrade'] === 'A' || report['overallGrade'] === 'B'
+                || report['overallGrade'] === 'C' || report['overallGrade'] === 'D')
+            ? report['overallGrade']
+            : null,
+        items: items ?? checklist.items.map((item) => ({
+            id: item.id,
+            verdict: null,
+            evidence: 'not-checked',
+            diagnostics: diagnostics.filter((entry) => entry.contractId === item.id),
+        })),
+        counts,
+        diagnostics,
+    };
+}
+export function verifyContractVerdicts(checklist, report, evidence) {
+    const runtime = validateVerdictPayload(report);
+    let counts = baseCounts(checklist, report);
+    if (!runtime.ok)
+        return failedVerification(checklist, report, runtime.diagnostics, counts);
+    report = runtime.report;
+    counts = baseCounts(checklist, report);
+    const diagnostics = [];
+    if (checklist.schema !== CONTRACT_CHECKLIST_SCHEMA || checklist.items.length === 0) {
+        diagnostics.push(diagnostic(checklist.schema !== CONTRACT_CHECKLIST_SCHEMA ? 'contract-schema-unsupported' : 'contract-empty', checklist.schema !== CONTRACT_CHECKLIST_SCHEMA ? `unsupported contract schema ${String(checklist.schema)}` : 'the contract contains zero items'));
+        return failedVerification(checklist, report, diagnostics, counts);
+    }
+    const expectedIds = checklist.items.map((item) => item.id);
+    const reportedIds = report.items.map((item) => item.id);
+    const frequencies = new Map();
+    for (const id of reportedIds)
+        frequencies.set(id, (frequencies.get(id) ?? 0) + 1);
+    let duplicate = 0;
+    for (const [id, frequency] of frequencies) {
+        if (frequency > 1) {
+            duplicate += frequency - 1;
+            diagnostics.push(diagnostic('verdict-id-duplicate', `verdict id ${id} occurs ${frequency} times`, { contractId: id, observed: frequency }));
+        }
+    }
+    const reportedSet = new Set(reportedIds);
+    const expectedSet = new Set(expectedIds);
+    const missing = expectedIds.filter((id) => !reportedSet.has(id));
+    const orphan = [...reportedSet].filter((id) => !expectedSet.has(id));
+    for (const id of missing)
+        diagnostics.push(diagnostic('verdict-id-missing', `contract id ${id} has no verdict`, { contractId: id }));
+    for (const id of orphan)
+        diagnostics.push(diagnostic(contractIdNumber(id) === null ? 'verdict-id-malformed' : 'verdict-id-orphan', `reported verdict id ${id} is not an expected contract id`, { contractId: id }));
+    if (missing.length === 0 && orphan.length === 0 && duplicate === 0
+        && expectedIds.some((id, index) => reportedIds[index] !== id)) {
+        diagnostics.push(diagnostic('verdict-id-order', 'verdict ids contain the expected set but not in contract order', { observed: reportedIds }));
+    }
+    counts = { ...counts, missing: missing.length, duplicate, orphan: orphan.length };
+    if (diagnostics.length > 0)
+        return failedVerification(checklist, report, diagnostics, counts);
+    const itemResults = [];
+    let invalidEvidence = 0;
+    for (let index = 0; index < checklist.items.length; index++) {
+        const contract = checklist.items[index];
+        const verdict = report.items[index];
+        const itemDiagnostics = [];
+        const pathProblem = safeEvidenceArtifact(verdict.evidence.artifact);
+        if (pathProblem !== null) {
+            itemDiagnostics.push(diagnostic('evidence-path-unsafe', `${verdict.evidence.artifact}: ${pathProblem}`, { artifact: verdict.evidence.artifact, contractId: contract.id }));
+        }
+        else if (evidence.reportArtifact !== undefined && verdict.evidence.artifact === evidence.reportArtifact) {
+            itemDiagnostics.push(diagnostic('evidence-self-citation', `${contract.id} cites the QE verdict payload itself`, { artifact: verdict.evidence.artifact, contractId: contract.id }));
+        }
+        else {
+            const read = evidence.read(verdict.evidence.artifact);
+            if (!read.ok) {
+                itemDiagnostics.push(diagnostic(read.code, read.detail, { artifact: verdict.evidence.artifact, contractId: contract.id }));
+            }
+            else {
+                const matches = quoteOccurrences(read.text, verdict.evidence.quote);
+                if (matches !== 1) {
+                    itemDiagnostics.push(diagnostic('evidence-quote-count', `${contract.id} evidence quote occurs ${matches} times; expected exactly once`, { artifact: verdict.evidence.artifact, contractId: contract.id, observed: matches }));
+                }
+            }
+        }
+        const expectedOutcome = {
+            met: 'pass',
+            unmet: 'fail',
+            'not-testable': 'not-testable',
+        };
+        if (verdict.evidence.observedOutcome !== expectedOutcome[verdict.verdict]) {
+            itemDiagnostics.push(diagnostic('evidence-outcome-polarity', `${contract.id} verdict ${verdict.verdict} requires observedOutcome ${expectedOutcome[verdict.verdict]}`, {
+                artifact: verdict.evidence.artifact,
+                contractId: contract.id,
+                observed: verdict.evidence.observedOutcome,
+            }));
+        }
+        if (verdict.verdict === 'unmet') {
+            itemDiagnostics.push(diagnostic('contract-item-unmet', `${contract.id} is unmet: ${verdict.reason ?? 'no reason recorded'}`, { contractId: contract.id }));
+        }
+        else if (verdict.verdict === 'not-testable') {
+            itemDiagnostics.push(diagnostic('contract-item-not-testable', `${contract.id} is not-testable: ${verdict.reason ?? 'no reason recorded'}`, { contractId: contract.id }));
+        }
+        const evidenceErrors = itemDiagnostics.filter((entry) => entry.code.startsWith('evidence-')).length;
+        if (evidenceErrors > 0)
+            invalidEvidence++;
+        diagnostics.push(...itemDiagnostics);
+        itemResults.push({
+            id: contract.id,
+            verdict: verdict.verdict,
+            evidence: evidenceErrors > 0 ? 'invalid' : 'valid',
+            ...(verdict.reason !== undefined ? { reason: verdict.reason } : {}),
+            diagnostics: itemDiagnostics,
+        });
+    }
+    const conflicts = report.items.filter((item) => item.verdict === 'unmet').map((item) => item.id);
+    const gradeConflicts = (report.overallGrade === 'A' || report.overallGrade === 'B') ? conflicts : [];
+    if (gradeConflicts.length > 0) {
+        diagnostics.push(diagnostic('grade-unmet-conflict', `overall grade ${report.overallGrade} cannot coexist with unmet items: ${gradeConflicts.join(', ')}`, { observed: gradeConflicts }));
+    }
+    counts = { ...counts, invalidEvidence, gradeConflicts: gradeConflicts.length };
+    if (diagnostics.length > 0)
+        return failedVerification(checklist, report, diagnostics, counts, itemResults);
+    return {
+        outcome: 'pass',
+        exitCode: 0,
+        overallGrade: report.overallGrade,
+        items: itemResults,
+        counts,
+        diagnostics: [],
+    };
+}
+//# sourceMappingURL=contract-checklist.js.map