@sun-asterisk/sungen 3.2.34 → 3.3.0-alpha.2

package/dist/contract/classify-trace-conformance.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOW_IDENTITY_FINDING = void 0;
+exports.notJudged = notJudged;
+exports.classifyTraceRuns = classifyTraceRuns;
+/**
+ * A free / impl:code scenario's traces against its approved lock entry (DOS-14.5 – 14.6) — the SAME
+ * strength ladder as the Gherkin check (DOS-14.4, oracle-strength.ts), fed from the trace fingerprint.
+ *
+ *   free        classifyScenario(lock entry, fingerprint): equal hash → match, else the ladder
+ *   impl:code   group by group: each approved step must be realized inside the `test.step` titled
+ *               with that step — identically (fine), weaker (hard), stronger (strengthened), changed
+ *               (review); an approved check with no group or no check in its group → assertion-lost
+ *   overlays    a step whose target identity is `low` → opaque (review, never match, red-team #4);
+ *               an opaque step → opaque with its verbatim text and file:line (contract.opaque-step)
+ *   runs        no admissible trace → unproven (all inconclusive → inconclusive) when APPROVED, a
+ *               warning while proposed (M5, M6); a trace refused beside an admissible one → a warning;
+ *               several admissible traces that fingerprint differently → nondeterministic (worst wins)
+ */
+const classify_contract_change_1 = require("./classify-contract-change");
+const contract_hash_1 = require("./contract-hash");
+const oracle_strength_1 = require("./oracle-strength");
+/** What an unjudgeable scenario becomes: hard when QA locked it (approved), a warning while it is proposed. */
+function notJudged(id, approved, cls, reasons) {
+    return approved
+        ? { class: cls, findings: reasons.map((r) => (0, classify_contract_change_1.finding)(cls, r)), hashes: [], runs: [], warnings: [] }
+        : { class: 'proposed', findings: [], hashes: [], runs: [], warnings: reasons.map((r) => `${id} (not approved yet, so a warning): ${r}`) };
+}
+/** How a low target identity opens its finding — `next` reads it to offer `contract check --trace`. */
+exports.LOW_IDENTITY_FINDING = 'target identity is low';
+const worstOf = (findings, start = 'match') => findings.reduce((acc, f) => ((0, classify_contract_change_1.severityOf)(f.class) > (0, classify_contract_change_1.severityOf)(acc) ? f.class : acc), start);
+function overlays(fp, used) {
+    const out = [];
+    fp.rendered.forEach((r, i) => {
+        if (used && !used.has(i))
+            return;
+        if (r.opaque)
+            out.push((0, classify_contract_change_1.finding)('opaque', `"${r.opaque.verbatim}"${r.opaque.where ? ` at ${r.opaque.where}` : ''} — ${r.kind === 'assert' ? 'a check' : 'a step'} sungen cannot compare; QA reviews it`, i + 1));
+        else if (r.low)
+            out.push((0, classify_contract_change_1.finding)('opaque', `${exports.LOW_IDENTITY_FINDING} (${r.low}) — cannot prove "${r.sentence}" acts on the approved element`, i + 1));
+    });
+    return out;
+}
+function implCodeFindings(entry, fp) {
+    const findings = [];
+    const used = new Set();
+    const taken = new Set();
+    entry.steps.forEach((locked, i) => {
+        const g = fp.groups.findIndex((x, gi) => !taken.has(gi) && (0, contract_hash_1.sameJson)(x.titleStep, locked));
+        if (g < 0) {
+            findings.push(locked.kind === 'assert'
+                ? (0, classify_contract_change_1.finding)('assertion-lost', `no test.step implements the approved check "${locked.verb}" (step ${i + 1})`)
+                : (0, classify_contract_change_1.finding)('hash-changed', `no test.step implements the approved step "${locked.verb}" (step ${i + 1})`));
+            return;
+        }
+        taken.add(g);
+        const members = fp.groups[g].members;
+        const same = members.find((m) => (0, contract_hash_1.sameJson)(fp.steps[m], locked));
+        if (same !== undefined) {
+            used.add(same);
+            return;
+        }
+        const candidates = members.filter((m) => fp.steps[m].kind === locked.kind);
+        if (!candidates.length) {
+            findings.push(locked.kind === 'assert' ? (0, classify_contract_change_1.finding)('assertion-lost', `the test.step for "${locked.verb}" checks nothing`, i + 1)
+                : (0, classify_contract_change_1.finding)('hash-changed', `the test.step for "${locked.verb}" does nothing on the page`, i + 1));
+            return;
+        }
+        candidates.forEach((m) => used.add(m));
+        if (locked.kind === 'action') {
+            findings.push((0, classify_contract_change_1.finding)('hash-changed', `the code for "${locked.verb}" does something else: "${fp.rendered[candidates[0]].sentence}"`, i + 1));
+            return;
+        }
+        const judged = candidates.map((m) => (0, oracle_strength_1.compareAsserts)(locked, fp.steps[m]));
+        const rank = (k) => (k === 'oracle-weakened' ? 0 : k === 'review' ? 1 : 2);
+        const best = judged.sort((a, b) => rank(b.class) - rank(a.class))[0];
+        findings.push((0, classify_contract_change_1.finding)(best.class === 'review' ? 'hash-changed' : best.class, best.detail, i + 1));
+    });
+    fp.groups.forEach((g, gi) => { if (!taken.has(gi))
+        findings.push((0, classify_contract_change_1.finding)('hash-changed', `test.step "${g.title}" implements no approved step`)); });
+    return { findings, used };
+}
+function classifyOne(id, implementation, entry, fp) {
+    if (implementation === 'impl:code') {
+        const { findings, used } = implCodeFindings(entry, fp);
+        return [...findings, ...overlays(fp, used)];
+    }
+    const ladder = (0, classify_contract_change_1.classifyScenario)(id, entry, {
+        id, implementation, steps: fp.steps, hash: fp.hash, source: { file: '', name: id, hasId: true, lines: [], outline: false },
+    });
+    return [...ladder.findings, ...overlays(fp)];
+}
+const runLabel = (r) => `${r.record?.runId ?? '?'}#${r.result?.retry ?? '?'}`;
+function classifyTraceRuns(id, implementation, entry, runs, fingerprints) {
+    const admissible = runs.filter((r) => r.status === 'admissible' && fingerprints.has(r));
+    const others = runs.filter((r) => !admissible.includes(r));
+    const labels = admissible.map(runLabel);
+    const hashes = admissible.map((r) => fingerprints.get(r).hash);
+    if (!admissible.length) {
+        const allInconclusive = others.length > 0 && others.every((r) => r.status === 'inconclusive');
+        return { ...notJudged(id, !!entry, allInconclusive ? 'inconclusive' : 'unproven', others.map((r) => r.reason ?? r.status)), hashes, runs: labels };
+    }
+    // A trace that may not speak, beside one that may: the admissible one judges, the other is a warning.
+    const warnings = others.map((r) => `${id}: another trace of this scenario was not used — ${r.reason ?? r.status}`);
+    if (!entry)
+        return { class: 'proposed', findings: [], hashes, runs: labels, warnings };
+    const perRun = admissible.map((r) => classifyOne(id, implementation, entry, fingerprints.get(r)));
+    const findings = perRun.flat();
+    let cls = worstOf(perRun.flat());
+    if (new Set(hashes).size > 1) {
+        findings.push((0, classify_contract_change_1.finding)('nondeterministic', `${new Set(hashes).size} different fingerprints across ${admissible.length} runs — the runs took different branches`));
+        if ((0, classify_contract_change_1.severityOf)(cls) <= (0, classify_contract_change_1.severityOf)('strengthened'))
+            cls = 'nondeterministic';
+    }
+    return { class: cls, findings, hashes, runs: labels, warnings };
+}
+//# sourceMappingURL=classify-trace-conformance.js.map

package/dist/contract/classify-trace-conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify-trace-conformance.js","sourceRoot":"","sources":["../../src/contract/classify-trace-conformance.ts"],"names":[],"mappings":"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"}

package/dist/contract/contract-git.d.ts

@@ -0,0 +1,24 @@
+export declare const CLI_GIT_TIMEOUT_MS = 30000;
+export declare const GUARD_GIT_TIMEOUT_MS = 3000;
+export declare class GitUnavailableError extends Error {
+    constructor(detail: string);
+}
+export interface HeadSnapshot {
+    root: string;
+    timeoutMs: number;
+    /** Project-relative path → blob id of each committed lock and decision; null when there is nothing to compare with. */
+    blobs: Map<string, string> | null;
+    /** Set when git FAILED in a checkout that has .git (blobs is then null). */
+    error?: string;
+}
+export declare function headSnapshot(root: string, timeoutMs?: number): HeadSnapshot;
+export declare const gitBlobId: (text: string) => string;
+export declare const posixRel: (root: string, abs: string) => string;
+/**
+ * The committed text of a project-relative path, or null when HEAD does not hold it. `workingText`
+ * (the file as it is on disk, if any) spares the `git show` when it is byte-identical to HEAD.
+ */
+export declare function headFileText(snap: HeadSnapshot, rel: string, workingText: string | null): string | null;
+/** A file's text, or null when it does not exist. */
+export declare function readTextOrNull(file: string): string | null;
+//# sourceMappingURL=contract-git.d.ts.map

package/dist/contract/contract-git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-git.d.ts","sourceRoot":"","sources":["../../src/contract/contract-git.ts"],"names":[],"mappings":"AAkBA,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AAE1C,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,MAAM,EAAE,MAAM;CAI3B;AA2BD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,uHAAuH;IACvH,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAClC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAKD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAqB,GAAG,YAAY,CAYvF;AAED,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,MAGxC,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,EAAE,KAAK,MAAM,KAAG,MAA4D,CAAC;AAElH;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAOvG;AAED,qDAAqD;AACrD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK1D"}

package/dist/contract/contract-git.js

@@ -0,0 +1,144 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.posixRel = exports.gitBlobId = exports.GitUnavailableError = exports.GUARD_GIT_TIMEOUT_MS = exports.CLI_GIT_TIMEOUT_MS = void 0;
+exports.headSnapshot = headSnapshot;
+exports.headFileText = headFileText;
+exports.readTextOrNull = readTextOrNull;
+/**
+ * What git HEAD holds under `qa/`, for the contract (DOS-14.4) — with a timeout the caller picks
+ * (≈3 s inside the Claude Code guard, whose own budget is 5 s; 30 s for the CLI).
+ *
+ * Three answers, never confused:
+ *   blobs          one `git ls-tree -r -z HEAD -- qa`: every committed lock and decision with its blob id
+ *   no git         no `.git` at or above the project, or a repository without a first commit
+ *   git FAILED     `.git` is there but git errors, times out, refuses (dubious ownership) or is not
+ *                  installed — reported as `error`, so the caller can refuse to call a lock "clean"
+ *
+ * A file whose working bytes hash to its HEAD blob id IS its committed version: it is read from disk
+ * and needs no `git show`. git runs with fixed arguments, never through a shell.
+ */
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+exports.CLI_GIT_TIMEOUT_MS = 30000;
+exports.GUARD_GIT_TIMEOUT_MS = 3000;
+class GitUnavailableError extends Error {
+    constructor(detail) {
+        super(`git is unavailable in a checkout that has .git (${detail}) — the contract lock cannot be compared with HEAD`);
+        this.name = 'GitUnavailableError';
+    }
+}
+exports.GitUnavailableError = GitUnavailableError;
+function runGit(cwd, args, timeoutMs) {
+    try {
+        const out = (0, child_process_1.execFileSync)('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024, timeout: timeoutMs }).toString('utf8');
+        return { ok: true, out, timedOut: false, message: '' };
+    }
+    catch (e) {
+        const err = e;
+        const message = (err.stderr?.toString().trim() || err.message || String(e)).split('\n')[0];
+        return { ok: false, out: '', timedOut: err.code === 'ETIMEDOUT' || err.signal === 'SIGTERM', message };
+    }
+}
+function hasDotGit(start) {
+    let dir = path.resolve(start);
+    for (let i = 0; i < 40; i++) {
+        if (fs.existsSync(path.join(dir, '.git')))
+            return true;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+    return false;
+}
+const RECORD = /^\d+ blob ([0-9a-f]+)\t(.+)$/s;
+const KEEP = (p) => p.endsWith('/contracts.lock.yaml') || /\/decisions\/[^/]+\.yaml$/.test(p);
+function headSnapshot(root, timeoutMs = exports.CLI_GIT_TIMEOUT_MS) {
+    const r = runGit(root, ['ls-tree', '-r', '-z', 'HEAD', '--', 'qa'], timeoutMs);
+    if (r.ok) {
+        const blobs = new Map();
+        for (const rec of r.out.split('\0')) {
+            const m = rec.match(RECORD);
+            if (m && KEEP(m[2]))
+                blobs.set(m[2], m[1]);
+        }
+        return { root, timeoutMs, blobs };
+    }
+    if (r.timedOut)
+        return { root, timeoutMs, blobs: null, error: `git timed out after ${timeoutMs} ms` };
+    if (!hasDotGit(root))
+        return { root, timeoutMs, blobs: null };
+    const repo = runGit(root, ['rev-parse', '--git-dir'], timeoutMs);
+    if (repo.ok && !runGit(root, ['rev-parse', '--verify', '-q', 'HEAD'], timeoutMs).ok)
+        return { root, timeoutMs, blobs: null }; // no first commit yet
+    return { root, timeoutMs, blobs: null, error: r.message || 'git failed' };
+}
+const gitBlobId = (text) => {
+    const body = Buffer.from(text, 'utf8');
+    return (0, crypto_1.createHash)('sha1').update(Buffer.concat([Buffer.from(`blob ${body.length}\0`), body])).digest('hex');
+};
+exports.gitBlobId = gitBlobId;
+const posixRel = (root, abs) => path.relative(root, abs).split(path.sep).join('/');
+exports.posixRel = posixRel;
+/**
+ * The committed text of a project-relative path, or null when HEAD does not hold it. `workingText`
+ * (the file as it is on disk, if any) spares the `git show` when it is byte-identical to HEAD.
+ */
+function headFileText(snap, rel, workingText) {
+    const blob = snap.blobs?.get(rel);
+    if (blob === undefined)
+        return null;
+    if (workingText !== null && (0, exports.gitBlobId)(workingText) === blob)
+        return workingText;
+    const r = runGit(snap.root, ['show', `HEAD:./${rel}`], snap.timeoutMs);
+    if (!r.ok)
+        throw new GitUnavailableError(`git show HEAD:${rel}: ${r.timedOut ? 'timed out' : r.message}`);
+    return r.out;
+}
+/** A file's text, or null when it does not exist. */
+function readTextOrNull(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return null;
+        throw e;
+    }
+}
+//# sourceMappingURL=contract-git.js.map

package/dist/contract/contract-git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-git.js","sourceRoot":"","sources":["../../src/contract/contract-git.ts"],"names":[],"mappings":"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"}

package/dist/contract/contract-hash.d.ts

@@ -0,0 +1,7 @@
+import type { ContractStep, Implementation } from './contract-schema';
+export declare const canonicalJson: (v: unknown) => string;
+/** Structural equality, key order ignored. */
+export declare const sameJson: (a: unknown, b: unknown) => boolean;
+export declare const sha256Hex: (s: string) => string;
+export declare function contractHash(implementation: Implementation, steps: ContractStep[]): string;
+//# sourceMappingURL=contract-hash.d.ts.map

package/dist/contract/contract-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-hash.d.ts","sourceRoot":"","sources":["../../src/contract/contract-hash.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAetE,eAAO,MAAM,aAAa,GAAI,GAAG,OAAO,KAAG,MAAsC,CAAC;AAElF,8CAA8C;AAC9C,eAAO,MAAM,QAAQ,GAAI,GAAG,OAAO,EAAE,GAAG,OAAO,KAAG,OAAgD,CAAC;AAEnG,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,KAAG,MAAsD,CAAC;AAE7F,wBAAgB,YAAY,CAAC,cAAc,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,MAAM,CAE1F"}

package/dist/contract/contract-hash.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256Hex = exports.sameJson = exports.canonicalJson = void 0;
+exports.contractHash = contractHash;
+/**
+ * Contract hash (DOS-14.2): `sha256-12` of the normalized steps PLUS the implementation path, so
+ * retagging `@free` → none is a contract change (red-team #5).
+ *
+ * Canonical JSON is keys-sorted with absent fields dropped and NO other rewriting: a literal's
+ * whitespace is part of what the test types or expects, so two values that differ only in spaces
+ * hash apart rather than "matching" by normalization.
+ */
+const crypto_1 = require("crypto");
+function canonical(v) {
+    if (Array.isArray(v))
+        return v.map(canonical);
+    if (v && typeof v === 'object') {
+        const out = {};
+        for (const k of Object.keys(v).sort()) {
+            const x = v[k];
+            if (x !== undefined)
+                out[k] = canonical(x);
+        }
+        return out;
+    }
+    return v;
+}
+const canonicalJson = (v) => JSON.stringify(canonical(v));
+exports.canonicalJson = canonicalJson;
+/** Structural equality, key order ignored. */
+const sameJson = (a, b) => (0, exports.canonicalJson)(a) === (0, exports.canonicalJson)(b);
+exports.sameJson = sameJson;
+const sha256Hex = (s) => (0, crypto_1.createHash)('sha256').update(s).digest('hex');
+exports.sha256Hex = sha256Hex;
+function contractHash(implementation, steps) {
+    return (0, exports.sha256Hex)((0, exports.canonicalJson)({ implementation, steps })).slice(0, 12);
+}
+//# sourceMappingURL=contract-hash.js.map

package/dist/contract/contract-hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-hash.js","sourceRoot":"","sources":["../../src/contract/contract-hash.ts"],"names":[],"mappings":";;;AA+BA,oCAEC;AAjCD;;;;;;;GAOG;AACH,mCAAoC;AAGpC,SAAS,SAAS,CAAC,CAAU;IAC3B,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAC9C,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YACtC,MAAM,CAAC,GAAI,CAA6B,CAAC,CAAC,CAAC,CAAC;YAC5C,IAAI,CAAC,KAAK,SAAS;gBAAE,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAEM,MAAM,aAAa,GAAG,CAAC,CAAU,EAAU,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AAArE,QAAA,aAAa,iBAAwD;AAElF,8CAA8C;AACvC,MAAM,QAAQ,GAAG,CAAC,CAAU,EAAE,CAAU,EAAW,EAAE,CAAC,IAAA,qBAAa,EAAC,CAAC,CAAC,KAAK,IAAA,qBAAa,EAAC,CAAC,CAAC,CAAC;AAAtF,QAAA,QAAQ,YAA8E;AAE5F,MAAM,SAAS,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,IAAA,mBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAAhF,QAAA,SAAS,aAAuE;AAE7F,SAAgB,YAAY,CAAC,cAA8B,EAAE,KAAqB;IAChF,OAAO,IAAA,iBAAS,EAAC,IAAA,qBAAa,EAAC,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC1E,CAAC"}

package/dist/contract/contract-report-file.d.ts

@@ -0,0 +1,4 @@
+import type { ContractVerdict } from './build-contract-verdict';
+export declare const contractReportPath: (projectRoot: string, unit: string) => string;
+export declare function writeContractReport(projectRoot: string, verdict: ContractVerdict): string;
+//# sourceMappingURL=contract-report-file.d.ts.map

package/dist/contract/contract-report-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-report-file.d.ts","sourceRoot":"","sources":["../../src/contract/contract-report-file.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,eAAO,MAAM,kBAAkB,GAAI,aAAa,MAAM,EAAE,MAAM,MAAM,KAAG,MACY,CAAC;AAEpF,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAMzF"}

package/dist/contract/contract-report-file.js

@@ -0,0 +1,60 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contractReportPath = void 0;
+exports.writeContractReport = writeContractReport;
+/**
+ * `.sungen/reports/<slug>-contract.json` — the contract verdict as OUTPUT (DOS-14.0, takumi T3).
+ *
+ * Written by `sungen contract check` from a verdict it just built; never read back as a source of
+ * truth. Anything that needs the verdict calls buildContractVerdict() and rebuilds it from the
+ * `.feature`, the lock and git HEAD — so editing this file to "pass" changes nothing, and the next
+ * check overwrites it. It records `inputsHash` so a reader can see the report is stale, and
+ * `exitCode` next to `verdict` (fail ⇔ exitCode ≠ 0).
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const write_atomic_1 = require("../harness/write-atomic");
+const unit_paths_1 = require("../harness/unit-paths");
+const contractReportPath = (projectRoot, unit) => path.join(projectRoot, '.sungen', 'reports', `${(0, unit_paths_1.reportSlug)(unit)}-contract.json`);
+exports.contractReportPath = contractReportPath;
+function writeContractReport(projectRoot, verdict) {
+    const file = (0, exports.contractReportPath)(projectRoot, verdict.unit);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const doc = { ...verdict, generatedBy: 'sungen contract check', generatedAt: new Date().toISOString() };
+    (0, write_atomic_1.writeFileAtomic)(file, `${JSON.stringify(doc, null, 2)}\n`);
+    return file;
+}
+//# sourceMappingURL=contract-report-file.js.map

package/dist/contract/contract-report-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-report-file.js","sourceRoot":"","sources":["../../src/contract/contract-report-file.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkBA,kDAMC;AAxBD;;;;;;;;GAQG;AACH,uCAAyB;AACzB,2CAA6B;AAC7B,0DAA0D;AAC1D,sDAAmD;AAG5C,MAAM,kBAAkB,GAAG,CAAC,WAAmB,EAAE,IAAY,EAAU,EAAE,CAC9E,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,IAAA,uBAAU,EAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;AADvE,QAAA,kBAAkB,sBACqD;AAEpF,SAAgB,mBAAmB,CAAC,WAAmB,EAAE,OAAwB;IAC/E,MAAM,IAAI,GAAG,IAAA,0BAAkB,EAAC,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,GAAG,GAAG,EAAE,GAAG,OAAO,EAAE,WAAW,EAAE,uBAAuB,EAAE,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;IACxG,IAAA,8BAAe,EAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC3D,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/contract/contract-schema.d.ts

@@ -0,0 +1,71 @@
+export declare const IMPLEMENTATIONS: readonly ["compiled", "impl:code", "free"];
+export type Implementation = typeof IMPLEMENTATIONS[number];
+export interface ContractTarget {
+    /** The first `[Reference]` of the step, or the data path of an `expect {{x}} …` step. */
+    ref: string;
+    /** Further `[References]` in the order written (`drag [A] to [B]`, `all [Card] contain [Child]`). */
+    also?: string[];
+    /** The `in [Parent] <container>` scope, as `<container> [<Parent>]` plus its `with` tail. */
+    parent?: string;
+    nth?: number;
+}
+export interface ContractStep {
+    kind: 'action' | 'assert';
+    /** The sentence with the actor dropped, refs as `[]`, values as `{}`, lowercased — the step's exact form. */
+    verb: string;
+    target?: ContractTarget;
+    /** An action's input: `{{var}}` kept as written, a literal without its quotes; several joined by ` | `. */
+    value?: string;
+    /** An assertion's check, from the closed vocabulary in oracle-strength.ts (`unknown` when it has none). */
+    matcher?: string;
+    /** An assertion's expected value(s), same form as `value`. */
+    expected?: string;
+    negated?: true;
+    /** The step's data table, header row first. */
+    table?: string[][];
+}
+export interface ContractScenario {
+    id: string;
+    implementation: Implementation;
+    steps: ContractStep[];
+    hash: string;
+    /** Where it was read — never hashed. `outline`: a Scenario Outline, which the compiler does not support. */
+    source: {
+        file: string;
+        name: string;
+        hasId: boolean;
+        lines: number[];
+        outline: boolean;
+    };
+}
+export interface LockEntry {
+    hash: string;
+    steps: ContractStep[];
+    implementation: Implementation;
+    approvedAt: string;
+    decisionId: string;
+    humanApproved?: true;
+}
+export declare const LOCK_SCHEMA = 1;
+export interface ContractLock {
+    schema: typeof LOCK_SCHEMA;
+    scenarios: Record<string, LockEntry>;
+}
+export type LadderClass = 'match' | 'strengthened' | 'hash-changed' | 'oracle-weakened' | 'target-changed' | 'assertion-lost';
+/** Classes only a trace can produce (DOS-14.6) — free / impl:code scenarios. */
+export type TraceClass = 'opaque' | 'nondeterministic' | 'inconclusive' | 'unproven';
+export type ScenarioClass = LadderClass | 'proposed' | TraceClass;
+export type FindingClass = Exclude<LadderClass, 'match'> | 'lock-uncommitted' | TraceClass;
+/** Exit ≠ 0 (DOS-14.4, DOS-14.6). `unproven` applies to free / impl:code only. */
+export declare const HARD_CLASSES: ReadonlySet<string>;
+/** Exit 0, but delivery waits for QA (DOS-14.4): changed-not-weaker, checks no code can compare, and an
+ *  approved free scenario whose final attempt did not pass (inconclusive — review decision M6). */
+export declare const REVIEW_CLASSES: ReadonlySet<string>;
+/** The catalog rule each class is reported under (gate-rules.yaml); `strengthened` has none. */
+export declare const RULE_OF: Readonly<Partial<Record<FindingClass, string>>>;
+export declare function stepErrors(s: unknown, at: string): string[];
+/** Errors in one stored lock entry (empty = well-formed). The hash itself is checked by the reader. */
+export declare function lockEntryErrors(raw: unknown, id: string): string[];
+/** Approved by a human on a TTY — and nothing else counts (an absent field is `proposed`, T5). */
+export declare const isHumanApproved: (entry: LockEntry | undefined) => entry is LockEntry;
+//# sourceMappingURL=contract-schema.d.ts.map

package/dist/contract/contract-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-schema.d.ts","sourceRoot":"","sources":["../../src/contract/contract-schema.ts"],"names":[],"mappings":"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"}

package/dist/contract/contract-schema.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHumanApproved = exports.RULE_OF = exports.REVIEW_CLASSES = exports.HARD_CLASSES = exports.LOCK_SCHEMA = exports.IMPLEMENTATIONS = void 0;
+exports.stepErrors = stepErrors;
+exports.lockEntryErrors = lockEntryErrors;
+/**
+ * The Test Contract's data model (DOS-14.1 – 14.4) and the strict check of a stored lock entry.
+ *
+ *   step   {kind: action|assert, verb, target?:{ref, also?, parent?, nth?}, value?, matcher?, expected?, negated?, table?}
+ *   lock   qa/<kind>/<unit>/contracts.lock.yaml → {schema: 1, scenarios: {<scenario id>: LockEntry}}
+ *   entry  {hash, steps, implementation, approvedAt, decisionId, humanApproved?}
+ *
+ * A stored entry is checked the way the decision layer checks its records: a wrong type or an
+ * UNKNOWN key is an error, because a field outside the hash could carry meaning the hash does not
+ * vouch for. `humanApproved` counts only when it is literally `true` (takumi T5).
+ */
+const decision_schema_1 = require("../decisions/decision-schema");
+exports.IMPLEMENTATIONS = ['compiled', 'impl:code', 'free'];
+exports.LOCK_SCHEMA = 1;
+/** Exit ≠ 0 (DOS-14.4, DOS-14.6). `unproven` applies to free / impl:code only. */
+exports.HARD_CLASSES = new Set(['oracle-weakened', 'target-changed', 'assertion-lost', 'lock-uncommitted', 'unproven']);
+/** Exit 0, but delivery waits for QA (DOS-14.4): changed-not-weaker, checks no code can compare, and an
+ *  approved free scenario whose final attempt did not pass (inconclusive — review decision M6). */
+exports.REVIEW_CLASSES = new Set(['hash-changed', 'opaque', 'inconclusive']);
+/** The catalog rule each class is reported under (gate-rules.yaml); `strengthened` has none. */
+exports.RULE_OF = {
+    'hash-changed': 'contract.hash-changed',
+    'oracle-weakened': 'contract.oracle-weakened',
+    'target-changed': 'contract.target-changed',
+    'assertion-lost': 'contract.assertion-lost',
+    'lock-uncommitted': 'contract.lock-uncommitted',
+    opaque: 'contract.opaque-step',
+    nondeterministic: 'contract.nondeterministic',
+    inconclusive: 'contract.inconclusive',
+    unproven: 'contract.unproven',
+};
+const STEP_KEYS = new Set(['kind', 'verb', 'target', 'value', 'matcher', 'expected', 'negated', 'table']);
+const TARGET_KEYS = new Set(['ref', 'also', 'parent', 'nth']);
+const ENTRY_KEYS = new Set(['hash', 'steps', 'implementation', 'approvedAt', 'decisionId', 'humanApproved']);
+const HASH_RE = /^[0-9a-f]{12}$/;
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isStringList = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string');
+const unknownKeys = (o, allowed, at) => Object.keys(o).filter((k) => !allowed.has(k)).map((k) => `${at}: unknown key "${k}"`);
+function targetErrors(t, at) {
+    if (!isObject(t))
+        return [`${at}: target must be a mapping`];
+    const e = unknownKeys(t, TARGET_KEYS, at);
+    if (typeof t.ref !== 'string')
+        e.push(`${at}: target.ref must be a string`);
+    if (t.also !== undefined && !isStringList(t.also))
+        e.push(`${at}: target.also must be a list of strings`);
+    if (t.parent !== undefined && typeof t.parent !== 'string')
+        e.push(`${at}: target.parent must be a string`);
+    if (t.nth !== undefined && !(Number.isInteger(t.nth) && t.nth > 0))
+        e.push(`${at}: target.nth must be a positive integer`);
+    return e;
+}
+function stepErrors(s, at) {
+    if (!isObject(s))
+        return [`${at}: not a mapping`];
+    const e = unknownKeys(s, STEP_KEYS, at);
+    if (s.kind !== 'action' && s.kind !== 'assert')
+        e.push(`${at}: kind must be action|assert`);
+    if (typeof s.verb !== 'string' || !s.verb)
+        e.push(`${at}: verb is required`);
+    if (s.target !== undefined)
+        e.push(...targetErrors(s.target, at));
+    for (const k of ['value', 'matcher', 'expected'])
+        if (s[k] !== undefined && typeof s[k] !== 'string')
+            e.push(`${at}: ${k} must be a string`);
+    if (s.negated !== undefined && s.negated !== true)
+        e.push(`${at}: negated is either true or absent`);
+    if (s.table !== undefined && !(Array.isArray(s.table) && s.table.every(isStringList)))
+        e.push(`${at}: table must be rows of strings`);
+    return e;
+}
+/** Errors in one stored lock entry (empty = well-formed). The hash itself is checked by the reader. */
+function lockEntryErrors(raw, id) {
+    const at = `scenario ${id}`;
+    if (!isObject(raw))
+        return [`${at}: not a mapping`];
+    const e = unknownKeys(raw, ENTRY_KEYS, at);
+    if (typeof raw.hash !== 'string' || !HASH_RE.test(raw.hash))
+        e.push(`${at}: hash must be 12 hex characters`);
+    if (!exports.IMPLEMENTATIONS.includes(raw.implementation))
+        e.push(`${at}: implementation must be ${exports.IMPLEMENTATIONS.join('|')}`);
+    if (typeof raw.approvedAt !== 'string' || Number.isNaN(Date.parse(raw.approvedAt)))
+        e.push(`${at}: approvedAt must be an ISO-8601 timestamp`);
+    if (typeof raw.decisionId !== 'string' || !decision_schema_1.DECISION_ID_RE.test(raw.decisionId))
+        e.push(`${at}: decisionId must be D-<16 hex>`);
+    if (raw.humanApproved !== undefined && raw.humanApproved !== true)
+        e.push(`${at}: humanApproved is either true or absent`);
+    if (!Array.isArray(raw.steps))
+        e.push(`${at}: steps must be a list`);
+    else
+        raw.steps.forEach((s, i) => e.push(...stepErrors(s, `${at} step ${i + 1}`)));
+    return e;
+}
+/** Approved by a human on a TTY — and nothing else counts (an absent field is `proposed`, T5). */
+const isHumanApproved = (entry) => entry?.humanApproved === true;
+exports.isHumanApproved = isHumanApproved;
+//# sourceMappingURL=contract-schema.js.map