@sun-asterisk/sungen 3.2.35 → 3.3.0-alpha.10

package/dist/contract/trace/collect-trace-evidence.js

@@ -0,0 +1,219 @@
+"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.OVER_BUDGET = exports.MAX_EVIDENCE_JSON_BYTES = void 0;
+exports.collectRuns = collectRuns;
+exports.collectScenarioEvidence = collectScenarioEvidence;
+/**
+ * Which recorded traces speak for which scenario (DOS-14.6): run records → their JSON reports →
+ * each test's final attempt → its trace (zip limits + version gate) → the binding checks.
+ *
+ *   admissible     final attempt passed, trace read, every binding link holds
+ *   inconclusive   final attempt did not pass                                  (warning)
+ *   unproven       no run record, no test, no trace                            (hard for free / impl:code)
+ *   refused        the trace exists but may not speak (swapped, stale, rejected zip…)
+ *   unsupported    the trace's format version is unknown                       (exit ≠ 0)
+ *
+ * Two recorded TESTS claiming one scenario id (#962) make its evidence ambiguous: neither speaks —
+ * `unproven`, both named (scenario-id-claims.ts) — instead of judging two tests' runs as one.
+ *
+ * Only traces of the scenario ids asked for are opened, so a unit pays for its own tests only.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const parse_1 = require("../../harness/parse");
+const render_free_gherkin_1 = require("../render-free-gherkin");
+const read_file_once_1 = require("./read-file-once");
+const scenario_id_claims_1 = require("./scenario-id-claims");
+const trace_binding_1 = require("./trace-binding");
+const trace_file_reader_1 = require("./trace-file-reader");
+const trace_zip_limits_1 = require("./trace-zip-limits");
+const select_final_attempt_1 = require("./select-final-attempt");
+const trace_run_record_1 = require("./trace-run-record");
+/** A run record or JSON report larger than this is refused before a byte is read (fail closed, #926). */
+exports.MAX_EVIDENCE_JSON_BYTES = 64 * 1024 * 1024;
+/** Why an evidence file was not read — `outside the project` covers a link out, a swap and a non-file. */
+function notRead(name, r) {
+    if (r.status === 'too-large')
+        return `${name} is larger than ${exports.MAX_EVIDENCE_JSON_BYTES / 1024 / 1024} MiB — not read`;
+    if (r.status === 'missing')
+        return `${name} is missing — not read`;
+    return `${name} is outside the project (a symlink?) or not a regular file — not read`;
+}
+/** The reason a run is not judged once the verdict's deadline has passed (fail closed). */
+exports.OVER_BUDGET = 'verdict budget exceeded; run `sungen contract check`';
+const NO_RECORD = "no sungen run record under test-results-free/ (or test-results/) — run the free tests with their own config: outputDir 'test-results-free', trace: 'on' and the sungen run-record reporter";
+/** `p` relative to `root` when it lies under it, else null. */
+function under(root, p) {
+    const rel = path.relative(root, p);
+    return rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? rel : null;
+}
+/**
+ * Where a report's trace attachment is: the first candidate that exists (read later, opened once, and
+ * only from inside the project). Playwright writes attachment paths ABSOLUTE, in the checkout that ran;
+ * after a clone or a move that checkout is elsewhere, so a path under the report's own config dir is
+ * first tried at the same place under this project (#967) — the run record's sha256 still binds the bytes.
+ */
+function attachmentPath(projectRoot, test, p) {
+    const moved = path.isAbsolute(p) && test.configRoot && !under(path.resolve(projectRoot), p) ? under(test.configRoot, p) : null;
+    const candidates = path.isAbsolute(p)
+        ? [...(moved ? [path.resolve(projectRoot, moved)] : []), p]
+        : [path.resolve(projectRoot, p), path.resolve(path.dirname(test.report), p)];
+    return candidates.find((c) => fs.existsSync(c)) ?? null;
+}
+function judge(projectRoot, record, test, contract) {
+    const scenarioId = (0, select_final_attempt_1.scenarioIdOfTest)(test.title, test.tags);
+    const base = { scenarioId, test, record };
+    const fin = (0, select_final_attempt_1.finalAttempt)(test);
+    if (fin.admissibility !== 'admissible')
+        return { ...base, result: fin.result, status: fin.admissibility, reason: fin.reason };
+    const missing = { ...base, result: fin.result, status: 'unproven', reason: `no trace at ${fin.result.tracePath} (the report points at a missing file)` };
+    const cand = attachmentPath(projectRoot, test, fin.result.tracePath);
+    if (!cand)
+        return missing;
+    // Opened once, inside the project, and what was opened is what is parsed and hashed (#926).
+    const limits = (0, trace_zip_limits_1.traceZipLimits)();
+    const read = (0, read_file_once_1.readInsideProject)(projectRoot, cand, limits.maxZipBytes);
+    if (read.status === 'missing')
+        return missing;
+    if (read.status === 'outside' || read.status === 'not-a-file') {
+        return { ...base, result: fin.result, status: 'unproven', reason: `the trace ${path.basename(fin.result.tracePath)} is outside the project (or not a file) — not read` };
+    }
+    let trace;
+    try {
+        trace = (0, trace_file_reader_1.traceFromRead)(read, cand, limits);
+    }
+    catch (e) {
+        const unsupported = e instanceof trace_zip_limits_1.TraceRejected && e.code === 'trace.version-unsupported';
+        return { ...base, result: fin.result, status: unsupported ? 'unsupported' : 'refused', reason: `trace refused: ${e.message}` };
+    }
+    const bound = (0, trace_binding_1.bindTrace)({ projectRoot, test, result: fin.result, record, trace, contract });
+    if (bound.ok === false)
+        return { ...base, result: fin.result, trace, status: 'refused', reason: `trace refused: ${bound.reason}` };
+    return { ...base, result: fin.result, trace, status: 'admissible', specFile: bound.specFile };
+}
+/**
+ * Every judged run of the tests `want` accepts (derive: a unit's tests; check: by scenario id). A trace
+ * older than `contract` — the unit's .feature files and lock, by content (#967) — is refused; derive,
+ * which writes the contract from the traces, passes null.
+ */
+function collectRuns(projectRoot, want, contract, deadline = Number.POSITIVE_INFINITY) {
+    const runs = [];
+    const problems = [];
+    const untrusted = [];
+    const inputs = [];
+    const seen = [];
+    const records = (0, trace_run_record_1.findRunRecords)(projectRoot);
+    for (const file of records) {
+        let record;
+        const recordRead = (0, read_file_once_1.readInsideProject)(projectRoot, file, exports.MAX_EVIDENCE_JSON_BYTES);
+        if (recordRead.status !== 'read') {
+            problems.push(notRead(path.basename(file), recordRead));
+            continue;
+        }
+        try {
+            record = (0, trace_run_record_1.readRunRecord)(file, recordRead.bytes.toString('utf8'));
+        }
+        catch (e) {
+            untrusted.push(`${path.basename(file)} is not trusted: ${e.message}`);
+            problems.push(untrusted[untrusted.length - 1]);
+            continue;
+        }
+        if (!record.report) {
+            problems.push(`${path.basename(file)} names no JSON report — add the json reporter to the free-test config`);
+            continue;
+        }
+        const reportRead = (0, read_file_once_1.readInsideProject)(projectRoot, path.resolve(projectRoot, record.report), exports.MAX_EVIDENCE_JSON_BYTES);
+        if (reportRead.status !== 'read') {
+            problems.push(`${path.basename(file)}: ${notRead(`the report ${path.basename(record.report)}`, reportRead)}`);
+            continue;
+        }
+        let tests;
+        try {
+            tests = (0, select_final_attempt_1.readPlaywrightReport)(reportRead.real, reportRead.bytes.toString('utf8'));
+        }
+        catch (e) {
+            problems.push(e.message);
+            continue;
+        }
+        inputs.push(`${record.runId}:${record.report}`);
+        for (const test of tests) {
+            const id = (0, select_final_attempt_1.scenarioIdOfTest)(test.title, test.tags);
+            seen.push({ id, title: test.title });
+            if (!want(id, test))
+                continue;
+            runs.push(Date.now() > deadline ? { scenarioId: id, test, record, status: 'unproven', reason: exports.OVER_BUDGET } : judge(projectRoot, record, test, contract));
+        }
+    }
+    return { runs, problems, untrusted, inputs, records: records.length, seen };
+}
+/** A title without its leading id, for comparing words only: `VP-X-001 Login works` → `login works`. */
+const wordsOf = (title) => {
+    const lead = title.match(/^\s*([A-Za-z][A-Za-z0-9.-]*)/)?.[1];
+    return (lead && (0, parse_1.isIdLike)(lead) ? title.trim().slice(lead.length) : title).replace(render_free_gherkin_1.CONTROL_CHARS, '').replace(/\s+/g, ' ').trim().toLowerCase();
+};
+/**
+ * Why no recorded test speaks for `id` (#943): a recorded test with this scenario's title under
+ * ANOTHER id is the usual cause — the id was renamed in the .free.feature (or in the test) and the
+ * other side was not — so that mismatch is named, with the fix.
+ */
+function noTestFor(id, name, seen) {
+    const words = name ? wordsOf(name) : '';
+    const twin = words ? seen.find((t) => t.id !== id && wordsOf(t.title) === words) : undefined;
+    if (!twin)
+        return `no test for ${id} in the recorded run(s)`;
+    // The title and its id come from the report — untrusted: clipped, control characters dropped.
+    const [title, other] = [(0, render_free_gherkin_1.clip)(twin.title), (0, render_free_gherkin_1.clip)(twin.id, 60)];
+    return `no test for ${id} in the recorded run(s) — the recorded test "${title}" (id ${other}) has this scenario's title, so the scenario id and the test no longer match: `
+        + `give the test the id ${id} (in its title and its @tag), or the scenario the id ${other}, then run it again with trace on`;
+}
+/** The runs of each scenario id; `names` (id → scenario name) lets a missing test be explained. */
+function collectScenarioEvidence(projectRoot, ids, contract, deadline, names) {
+    const found = collectRuns(projectRoot, (id) => ids.has(id), contract, deadline);
+    const runs = new Map([...ids].map((id) => [id, found.runs.filter((r) => r.scenarioId === id)]));
+    // Ambiguous evidence: no run of either test may speak for the id — never one picked arbitrarily.
+    for (const [id, claim] of (0, scenario_id_claims_1.idsClaimedByTwoTests)(projectRoot, found.runs)) {
+        if (runs.has(id))
+            runs.set(id, [{ scenarioId: id, status: 'unproven', reason: (0, scenario_id_claims_1.twoTestsClaim)(id, claim) }]);
+    }
+    for (const [id, list] of runs) {
+        // A record that was not trusted may be why (a newer reporter, a hand edit): the finding says so.
+        const why = found.untrusted.length ? ` — ${found.untrusted.join('; ')}` : '';
+        if (!list.length)
+            list.push({ scenarioId: id, status: 'unproven', reason: found.records ? `${noTestFor(id, names?.get(id), found.seen)}${why}` : NO_RECORD });
+    }
+    return { runs, problems: found.problems, inputs: found.inputs };
+}
+//# sourceMappingURL=collect-trace-evidence.js.map

package/dist/contract/trace/collect-trace-evidence.js.map

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

package/dist/contract/trace/identity-cache.d.ts

@@ -0,0 +1,19 @@
+import { TraceIdentityResult } from './target-identity';
+export declare const IDENTITY_CACHE_SCHEMA = 1;
+/** A driver answer plus the browser build that gave it. */
+export type CachedIdentity = Omit<TraceIdentityResult, 'key'> & {
+    browser: string;
+};
+export interface IdentityCache {
+    resolver: string;
+    entries: Map<string, CachedIdentity>;
+}
+export declare const identityCachePath: (projectRoot: string) => string;
+/** The cache, or an empty one with a reason when there is nothing trustworthy to read. */
+export declare function readIdentityCache(projectRoot: string): {
+    cache: IdentityCache;
+    problem?: string;
+};
+/** Write the cache with exactly `entries` (callers merge; answers are keyed by the HTML they judged). */
+export declare function writeIdentityCache(projectRoot: string, resolver: string, entries: Map<string, CachedIdentity>): string;
+//# sourceMappingURL=identity-cache.d.ts.map

package/dist/contract/trace/identity-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-cache.d.ts","sourceRoot":"","sources":["../../../src/contract/trace/identity-cache.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAyC,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE/F,eAAO,MAAM,qBAAqB,IAAI,CAAC;AACvC,2DAA2D;AAC3D,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,mBAAmB,EAAE,KAAK,CAAC,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AACpF,MAAM,WAAW,aAAa;IAAG,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;CAAE;AAKzF,eAAO,MAAM,iBAAiB,GAAI,aAAa,MAAM,KAAG,MAAgF,CAAC;AAEzI,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAqBjG;AAED,yGAAyG;AACzG,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,MAAM,CAMtH"}

package/dist/contract/trace/identity-cache.js

@@ -0,0 +1,104 @@
+"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.identityCachePath = exports.IDENTITY_CACHE_SCHEMA = void 0;
+exports.readIdentityCache = readIdentityCache;
+exports.writeIdentityCache = writeIdentityCache;
+/**
+ * The driver's identity answers, memoized per replayed snapshot: `.sungen/trace-identity/identities.json`.
+ *
+ * Core cannot run a browser, but the contract verdict (and the Claude Code guard that rebuilds it)
+ * must be a synchronous function of what is on disk. So `sungen contract check --trace` /
+ * `contract derive` ask `@sungen/driver-ui` once and keep each answer under the sha256 of the EXACT
+ * HTML it judged (target marker included). On read:
+ *
+ *   - a malformed file, an unknown key, an entry that is not well-formed → the whole file is ignored
+ *   - an entry is only ever looked up by the hash of HTML core rendered itself from the trace, so a
+ *     changed snapshot can never inherit an old answer
+ *   - anything not found → core's heuristic, which is `low`, which is never `match`
+ *
+ * This file is derived data, like `.sungen/reports`: deleting it costs a re-resolve, never a pass.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const target_identity_1 = require("./target-identity");
+exports.IDENTITY_CACHE_SCHEMA = 1;
+const FILE_KEYS = new Set(['schema', 'resolver', 'entries']);
+const SHA256 = /^[0-9a-f]{64}$/;
+const identityCachePath = (projectRoot) => path.join(projectRoot, '.sungen', 'trace-identity', 'identities.json');
+exports.identityCachePath = identityCachePath;
+/** The cache, or an empty one with a reason when there is nothing trustworthy to read. */
+function readIdentityCache(projectRoot) {
+    const empty = { resolver: '', entries: new Map() };
+    const file = (0, exports.identityCachePath)(projectRoot);
+    if (!fs.existsSync(file))
+        return { cache: empty };
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return { cache: empty, problem: `${path.basename(file)} is not JSON — ignored` };
+    }
+    const bad = (why) => ({ cache: empty, problem: `${path.basename(file)} ${why} — ignored` });
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return bad('is not an object');
+    const doc = raw;
+    if (Object.keys(doc).some((k) => !FILE_KEYS.has(k)))
+        return bad('has an unknown key');
+    if (doc.schema !== exports.IDENTITY_CACHE_SCHEMA || typeof doc.resolver !== 'string' || !doc.entries || typeof doc.entries !== 'object')
+        return bad('is not schema 1');
+    if (!target_identity_1.TRUSTED_RESOLVER.test(doc.resolver))
+        return bad(`was not written by the driver-ui resolver ("${doc.resolver.slice(0, 40)}")`);
+    const entries = new Map();
+    for (const [sha, value] of Object.entries(doc.entries)) {
+        const { browser, ...answer } = (value && typeof value === 'object' ? value : {});
+        const ok = SHA256.test(sha) && typeof browser === 'string' && browser.length > 0 && browser.length <= 100 ? (0, target_identity_1.validIdentityResult)({ ...answer, key: sha }) : null;
+        if (!ok)
+            return bad(`has a malformed entry (${sha.slice(0, 12)})`);
+        const { key: _key, ...rest } = ok;
+        entries.set(sha, { ...rest, browser: browser });
+    }
+    return { cache: { resolver: doc.resolver, entries } };
+}
+/** Write the cache with exactly `entries` (callers merge; answers are keyed by the HTML they judged). */
+function writeIdentityCache(projectRoot, resolver, entries) {
+    const file = (0, exports.identityCachePath)(projectRoot);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const sorted = Object.fromEntries([...entries.entries()].sort(([a], [b]) => a.localeCompare(b)));
+    fs.writeFileSync(file, `${JSON.stringify({ schema: exports.IDENTITY_CACHE_SCHEMA, resolver, entries: sorted }, null, 2)}\n`);
+    return file;
+}
+//# sourceMappingURL=identity-cache.js.map

package/dist/contract/trace/identity-cache.js.map

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

package/dist/contract/trace/read-file-once.d.ts

@@ -0,0 +1,20 @@
+export type FileRead = {
+    status: 'read';
+    real: string;
+    bytes: Buffer;
+} | {
+    status: 'missing';
+} | {
+    status: 'outside';
+    why: string;
+} | {
+    status: 'not-a-file';
+} | {
+    status: 'too-large';
+    size: number;
+};
+/** A regular file, opened once and read from that descriptor. */
+export declare const readFileOnce: (file: string, maxBytes?: number) => FileRead;
+/** A regular file INSIDE the project (symlinks resolved), opened once; see the header for the checks. */
+export declare function readInsideProject(projectRoot: string, file: string, maxBytes?: number): FileRead;
+//# sourceMappingURL=read-file-once.d.ts.map

package/dist/contract/trace/read-file-once.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-file-once.d.ts","sourceRoot":"","sources":["../../../src/contract/trace/read-file-once.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,QAAQ,GAChB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GACxB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAsC1C,iEAAiE;AACjE,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,EAAE,iBAAmC,KAAG,QAC7B,CAAC;AAErD,yGAAyG;AACzG,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,SAA2B,GAAG,QAAQ,CAqBlH"}

package/dist/contract/trace/read-file-once.js

@@ -0,0 +1,135 @@
+"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.readFileOnce = void 0;
+exports.readInsideProject = readInsideProject;
+/**
+ * Read trace evidence (a run record, a JSON report, a trace.zip) by opening it ONCE and checking what
+ * was opened (#926) — never "check the path, then read the path", which leaves a window in which the
+ * file can be swapped for a link to anything outside the project.
+ *
+ *   readFileOnce(file)                     a regular file, read from its descriptor; O_NONBLOCK so a
+ *                                          FIFO swapped in cannot hang the guard; size checked on the
+ *                                          descriptor before a byte is read
+ *   readInsideProject(root, file)          the same for a path from untrusted input:
+ *                                            1. its real path must sit inside the project's real root
+ *                                            2. that real path is opened with O_NOFOLLOW (a link put
+ *                                               there in the meantime fails the open)
+ *                                            3. AFTER the open the path is resolved again: still inside,
+ *                                               and the same file (device + inode) as the descriptor —
+ *                                               a swap made before the open and undone after it is caught
+ *
+ * A file truncated or grown while it is read gives the bytes the descriptor had; the caller hashes
+ * those bytes, so nothing unread is ever vouched for.
+ *
+ * Windows has no O_NOFOLLOW (the constant is 0 there): the open follows a link swapped in, and the
+ * device + inode re-check after the open is what refuses it.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const { O_RDONLY } = fs.constants;
+const O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+const O_NONBLOCK = fs.constants.O_NONBLOCK ?? 0;
+function readFd(fd, size) {
+    const buf = Buffer.alloc(size);
+    let off = 0;
+    while (off < size) {
+        const n = fs.readSync(fd, buf, off, size - off, off);
+        if (n === 0)
+            break;
+        off += n;
+    }
+    return off === size ? buf : buf.subarray(0, off);
+}
+function openAndRead(file, flags, maxBytes, recheck) {
+    let fd;
+    try {
+        fd = fs.openSync(file, flags);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'ENOENT')
+            return { status: 'missing' };
+        // O_NOFOLLOW on a link: ELOOP (Linux, macOS) or EMLINK (FreeBSD).
+        if (code === 'ELOOP' || code === 'EMLINK')
+            return { status: 'outside', why: 'it became a link while it was opened' };
+        throw e;
+    }
+    try {
+        const st = fs.fstatSync(fd);
+        if (!st.isFile())
+            return { status: 'not-a-file' };
+        if (st.size > maxBytes)
+            return { status: 'too-large', size: st.size };
+        const moved = recheck?.(st);
+        if (moved)
+            return { status: 'outside', why: moved };
+        return { status: 'read', real: file, bytes: readFd(fd, st.size) };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** A regular file, opened once and read from that descriptor. */
+const readFileOnce = (file, maxBytes = Number.POSITIVE_INFINITY) => openAndRead(file, O_RDONLY | O_NONBLOCK, maxBytes);
+exports.readFileOnce = readFileOnce;
+/** A regular file INSIDE the project (symlinks resolved), opened once; see the header for the checks. */
+function readInsideProject(projectRoot, file, maxBytes = Number.POSITIVE_INFINITY) {
+    let root;
+    let real;
+    try {
+        root = fs.realpathSync(projectRoot);
+        real = fs.realpathSync(file);
+    }
+    catch (e) {
+        return e.code === 'ENOENT' ? { status: 'missing' } : { status: 'outside', why: 'its real path cannot be resolved' };
+    }
+    const within = (p) => p.startsWith(root + path.sep);
+    if (!within(real))
+        return { status: 'outside', why: 'its real path is outside the project' };
+    return openAndRead(real, O_RDONLY | O_NOFOLLOW | O_NONBLOCK, maxBytes, (opened) => {
+        try {
+            const again = fs.realpathSync(file);
+            if (!within(again))
+                return 'it was swapped for a link outside the project while it was opened';
+            const now = fs.statSync(again);
+            return now.dev === opened.dev && now.ino === opened.ino ? null : 'it was swapped for another file while it was opened';
+        }
+        catch {
+            return 'it moved while it was opened';
+        }
+    });
+}
+//# sourceMappingURL=read-file-once.js.map

package/dist/contract/trace/read-file-once.js.map

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

package/dist/contract/trace/scenario-id-claims.d.ts

@@ -0,0 +1,11 @@
+import type { TraceRun } from './collect-trace-evidence';
+export interface IdClaim {
+    /** `file:line "title" (run record <path>)` per claiming test, sorted. */
+    tests: string[];
+    /** Project-relative records under test-results/ that are a claim's only source, next to a test-results-free/ claim. */
+    staleRecords: string[];
+}
+export declare function idsClaimedByTwoTests(projectRoot: string, runs: readonly TraceRun[]): Map<string, IdClaim>;
+/** What to tell the user when several tests claim one id — check and derive say it the same way. */
+export declare function twoTestsClaim(id: string, claim: IdClaim): string;
+//# sourceMappingURL=scenario-id-claims.d.ts.map

package/dist/contract/trace/scenario-id-claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario-id-claims.d.ts","sourceRoot":"","sources":["../../../src/contract/trace/scenario-id-claims.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAGzD,MAAM,WAAW,OAAO;IACtB,yEAAyE;IACzE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,uHAAuH;IACvH,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAQD,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,QAAQ,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBzG;AAED,oGAAoG;AACpG,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAKhE"}