@sema-ai/core 1.275.1

package/dist/core/spec-contract.d.ts

@@ -0,0 +1,147 @@
+/**
+ * design/125 — **SpecContract**:spec→Verifier 闭环的机器可读任务契约(make-real 两周实战纪律的
+ * 一等原语化)。本模块 = 纯 core 零件:契约类型 + 三值 oracle 执行器 + frozenPaths 校验/快照/恢复。
+ * 装配(policy 组合、stop 把关、outcome 发射)在 `orchestration/run-spec.ts`。
+ *
+ * 🔴 **信任声明(fable-M3)**:SpecContract 是 **CODE-tier** 输入 —— `oracle[].cmd` 会被亲跑(execFile,
+ * 任意命令)。它只能来自部署作者/可信代码路径;LLM 生成的 contract 直接喂 runSpec = 不受信输入获得
+ * 命令执行权(越红线),禁止。contract 里的 `spec` **文本**才是 DATA-tier(runSpec 恒围栏置入 objective)。
+ *
+ * 🔴 **oracle 三值(fable-M6)**:每门结果 ∈ {green, red, error} —— 判据不满足 = red;基础设施故障
+ * (ENOENT/timeout/maxBuffer/parse 解析不出)= **error 非 red**。假红防线:error 绝不冒充"曾经红过"
+ * (design/73 红线② 的机器化 —— `oracleHadRedRun` 只由真 red 观察置位)。
+ */
+/** Declarative green criteria for one oracle gate. Absent ⇒ `exitCode === 0`. All declared criteria AND. */
+export interface OracleGreenSpec {
+    /** Expected exit code. Default 0 when no `parse` is declared; with `parse`, exit code is only
+     *  checked when explicitly set here (test runners exit non-zero on failures the counts already judge). */
+    exitCode?: number;
+    /** Regex (source string) that MUST match the combined stdout+stderr. */
+    mustMatch?: string;
+    /** Regex (source string) that MUST NOT match the combined stdout+stderr. */
+    mustNotMatch?: string;
+    /**
+     * Parsing criteria (fable-M5/B1 一体解): extract pass/fail counts from the output. Each regex's FIRST
+     * capture group is the integer count (e.g. `"ℹ pass (\\d+)"`). Either regex failing to match = the gate
+     * is **error** (解析不出 ≠ red — a runner that printed nothing proves nothing).
+     */
+    parse?: {
+        passRe: string;
+        failRe: string;
+    };
+    /**
+     * Lower bound on the parsed pass count (requires `parse`). `"baseline"` = the pass+fail TOTAL this gate
+     * observed at preflight — the anti-「测试消失式走捷径」 gate (the model leaves tests untouched but makes
+     * them undiscovered; harness :114 实战门, fable-B1). Numeric default when absent: 1 (a zero-test green
+     * is vacuous).
+     */
+    minPass?: number | "baseline";
+}
+/** One mechanical adjudicator: a command run via execFile (NO shell) + declarative green criteria. */
+export interface OracleGateSpec {
+    /** Stable gate name (baseline capture and per-gate reporting key on it). */
+    name: string;
+    /** argv — `cmd[0]` is the executable, the rest are arguments. execFile, never a shell. */
+    cmd: string[];
+    /** Working directory, containment-checked against the runSpec root (same rule as frozenPaths). */
+    cwd?: string;
+    /** Per-gate timeout. Default 60s. */
+    timeoutMs?: number;
+    green?: OracleGreenSpec;
+}
+/** design/125 D1 — the machine-readable task contract (CODE-tier input; see module doc). */
+export interface SpecContract {
+    /** Task spec text (or a file reference resolved against the runSpec root). runSpec owns the objective
+     *  framing; the spec text itself is DATA-tier and is ALWAYS fenced before injection. */
+    spec: string | {
+        path: string;
+    };
+    /**
+     * Read-only specification surface. **Validation (fable-M2)**: absolute paths and `..` segments are
+     * rejected; paths resolve against the runSpec root with a containment check; policy matching uses the
+     * RESOLVED path. Exact paths, no globs (v1 收窄).
+     */
+    frozenPaths: string[];
+    /** Mechanical adjudicators (serializable, checkpointable, service-boundary-safe, feed-recordable). */
+    oracle: OracleGateSpec[];
+    /**
+     * 双向验证: preflight runs the full oracle and REQUIRES red (proves the spec has substance), capturing
+     * baseline counts for `minPass:"baseline"` (fable-B1: the red gate and the baseline are two faces of the
+     * same preflight). Default **true** (the discipline is the default; opting out must be explicit).
+     * `{ exempt }` documents WHY this contract legitimately starts green (e.g. pure-refactor spec).
+     */
+    requireRedStart?: boolean | {
+        exempt: string;
+    };
+    /** design/73 aggregation key. Default: `spec:<sha256(specText) first 16 hex>`. */
+    taskSignature?: string;
+}
+/** Three-value gate verdict — `error` = the adjudicator itself failed to run/parse (NEVER counts as red). */
+export type OracleVerdict = "green" | "red" | "error";
+export interface OracleGateResult {
+    name: string;
+    verdict: OracleVerdict;
+    /** Process exit code (null when the process did not run/complete — spawn error or timeout kill). */
+    exitCode: number | null;
+    /** Parsed counts when `green.parse` was declared and both regexes matched. */
+    pass?: number;
+    fail?: number;
+    /** Which criterion failed / what the infrastructure error was (first-party classification string). */
+    reason?: string;
+    /** Tail of the combined stdout+stderr (UNTRUSTED — the model can influence it via the code under test;
+     *  fence with `delimitUntrusted` before any model-facing use). */
+    outputTail: string;
+}
+/** Per-gate preflight counts backing `minPass:"baseline"` (keyed by gate name). */
+export type OracleBaseline = Record<string, {
+    pass: number;
+    fail: number;
+}>;
+export interface OracleRunReport {
+    /** Worst-across-gates: any `error` ⇒ error (fail-loud dominates); else any `red` ⇒ red; else green. */
+    verdict: OracleVerdict;
+    gates: OracleGateResult[];
+}
+/**
+ * Run every gate of the contract's oracle (sequentially — gates commonly share a working tree) and fold
+ * the three-value verdicts: any `error` ⇒ `error` (fail-loud dominates; an unfalsifiable adjudication must
+ * never pass silently), else any `red` ⇒ `red`, else `green`.
+ *
+ * `cwdRoot` is the runSpec root: each gate's `cwd` resolves against it with the same containment rule as
+ * frozenPaths (a contract cannot point its adjudicator outside the workcopy).
+ */
+export declare function runOracle(gates: OracleGateSpec[], cwdRoot: string, opts?: {
+    baseline?: OracleBaseline;
+    signal?: AbortSignal;
+}): Promise<OracleRunReport>;
+/** Extract the per-gate baseline counts from a (preflight) report — only gates whose parse succeeded. */
+export declare function captureBaseline(report: OracleRunReport): OracleBaseline;
+/** A coded error (`config.*` / `spec.*` convention — same shape as goal.ts's reserved-name fail-fast). */
+export declare function specError(code: string, message: string): Error & {
+    code: string;
+};
+/**
+ * Validate and resolve `frozenPaths` against the runSpec root (fable-M2): absolute paths and `..`
+ * segments are rejected outright (`spec.frozen_path_invalid`); the resolved path must stay inside the
+ * root. Returns resolved absolute paths (the ONLY form policy matching and snapshots use).
+ */
+export declare function resolveFrozenPaths(rootDir: string, frozenPaths: string[]): string[];
+/**
+ * Byte-level snapshot of the frozen surface (fable-M1: a hash can only DETECT tampering — restoring needs
+ * the CONTENT, and the snapshot is the restore source; no external seed directory dependency). Missing
+ * file ⇒ `spec.frozen_missing` (a frozen path that doesn't exist can't be a specification).
+ */
+export declare function snapshotFrozenPaths(resolvedPaths: string[]): Map<string, Buffer>;
+/**
+ * Restore any frozen file whose on-disk bytes differ from the snapshot (belt for `echo > test/x`-style
+ * bash writes the Write/Edit deny policy cannot see — fable-MIN2). Returns the number of files restored.
+ *
+ * Symlink-safe (codex 实现审 B2): a tampered entry that is no longer a regular file (the model swapped
+ * it for a symlink pointing outside the root) is REMOVED first — the snapshot bytes are then written to
+ * a fresh regular file, never THROUGH a link. When `rootDir` is given, the parent directory's physical
+ * path is containment-checked too (a symlinked PARENT dir would also carry the write outside); an entry
+ * whose parent escapes is skipped (counted) — the terminal oracle then adjudicates the missing spec
+ * files honestly (fail-safe direction) instead of runSpec writing outside its root.
+ */
+export declare function restoreFrozenPaths(snapshot: Map<string, Buffer>, rootDir?: string): number;
+//# sourceMappingURL=spec-contract.d.ts.map

package/dist/core/spec-contract.d.ts.map

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

package/dist/core/spec-contract.js

@@ -0,0 +1,340 @@
+/**
+ * design/125 — **SpecContract**:spec→Verifier 闭环的机器可读任务契约(make-real 两周实战纪律的
+ * 一等原语化)。本模块 = 纯 core 零件:契约类型 + 三值 oracle 执行器 + frozenPaths 校验/快照/恢复。
+ * 装配(policy 组合、stop 把关、outcome 发射)在 `orchestration/run-spec.ts`。
+ *
+ * 🔴 **信任声明(fable-M3)**:SpecContract 是 **CODE-tier** 输入 —— `oracle[].cmd` 会被亲跑(execFile,
+ * 任意命令)。它只能来自部署作者/可信代码路径;LLM 生成的 contract 直接喂 runSpec = 不受信输入获得
+ * 命令执行权(越红线),禁止。contract 里的 `spec` **文本**才是 DATA-tier(runSpec 恒围栏置入 objective)。
+ *
+ * 🔴 **oracle 三值(fable-M6)**:每门结果 ∈ {green, red, error} —— 判据不满足 = red;基础设施故障
+ * (ENOENT/timeout/maxBuffer/parse 解析不出)= **error 非 red**。假红防线:error 绝不冒充"曾经红过"
+ * (design/73 红线② 的机器化 —— `oracleHadRedRun` 只由真 red 观察置位)。
+ */
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { lstatSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+const DEFAULT_GATE_TIMEOUT_MS = 60_000;
+/** 16MB — an ENOBUFS kill on a chatty test runner must classify as `error`, never fake-red (fable-M5). */
+const GATE_MAX_BUFFER = 16 * 1024 * 1024;
+const OUTPUT_TAIL_CHARS = 1500;
+/** Opus 复审 m — cap on the output window contract regexes evaluate against (head+tail halves). */
+const REGEX_SCAN_CAP = 2 * 1024 * 1024;
+function execGate(gate, cwd, signal) {
+    return new Promise((resolvePromise) => {
+        execFile(gate.cmd[0], gate.cmd.slice(1), {
+            cwd,
+            timeout: gate.timeoutMs ?? DEFAULT_GATE_TIMEOUT_MS,
+            maxBuffer: GATE_MAX_BUFFER,
+            encoding: "utf8",
+            signal,
+        }, (err, stdout, stderr) => {
+            const output = (stdout ?? "") + (stderr ?? "");
+            if (!err)
+                return resolvePromise({ exitCode: 0, output });
+            const e = err;
+            // Numeric code = the process RAN and exited non-zero — normal red territory, not an infra error.
+            if (typeof e.code === "number")
+                return resolvePromise({ exitCode: e.code, output });
+            if (e.killed || e.signal) {
+                return resolvePromise({ exitCode: null, output, infraError: `timeout/killed (${e.signal ?? "timeout"})` });
+            }
+            // ENOENT / EACCES / maxBuffer exceeded / abort — the adjudicator itself failed to run.
+            return resolvePromise({ exitCode: null, output, infraError: String(e.code ?? e.message ?? "spawn error") });
+        });
+    });
+}
+/** `undefined` = the pattern itself is invalid (⇒ error verdict); boolean = the test outcome. */
+function safeTest(re, output) {
+    try {
+        return new RegExp(re).test(output);
+    }
+    catch {
+        return undefined;
+    }
+}
+function firstCount(re, output) {
+    let m;
+    try {
+        m = new RegExp(re).exec(output);
+    }
+    catch {
+        return undefined; // invalid regex in the contract → parse error (error verdict, fail-loud posture)
+    }
+    if (!m)
+        return undefined;
+    const n = Number(m[1] ?? m[0]);
+    return Number.isFinite(n) ? n : undefined;
+}
+function evaluateGate(gate, exec, baseline) {
+    const base = {
+        name: gate.name,
+        exitCode: exec.exitCode,
+        outputTail: exec.output.slice(-OUTPUT_TAIL_CHARS),
+    };
+    if (exec.infraError)
+        return { ...base, verdict: "error", reason: exec.infraError };
+    const green = gate.green ?? {};
+    // Opus 复审 m: the output is model-influenceable (≤16MB) and contract regexes run in the MAIN thread
+    // AFTER the child exits — the gate timeout does not cover an accidentally-backtracking trusted regex.
+    // Bound what the regexes see: head+tail halves (test-runner summaries live at the tail; banners at the
+    // head). Criteria semantics are documented as "within the scanned window".
+    const scanned = exec.output.length > REGEX_SCAN_CAP
+        ? `${exec.output.slice(0, REGEX_SCAN_CAP / 2)}\n…[${exec.output.length - REGEX_SCAN_CAP} bytes elided]…\n${exec.output.slice(-REGEX_SCAN_CAP / 2)}`
+        : exec.output;
+    const green_output = scanned;
+    let pass;
+    let fail;
+    if (green.parse) {
+        pass = firstCount(green.parse.passRe, green_output);
+        fail = firstCount(green.parse.failRe, green_output);
+        if (pass === undefined || fail === undefined) {
+            return { ...base, verdict: "error", reason: "parse: pass/fail counts not extractable from output" };
+        }
+    }
+    const failures = [];
+    // Exit code: default criterion 0 only when no parse is declared; with parse, only if explicitly set.
+    const expectedExit = green.exitCode ?? (green.parse ? undefined : 0);
+    if (expectedExit !== undefined && exec.exitCode !== expectedExit) {
+        failures.push(`exitCode ${exec.exitCode} !== ${expectedExit}`);
+    }
+    // Invalid contract regexes classify as `error` (an unadjudicable criterion must never pass/fail
+    // silently or throw out of the three-value lane — codex 实现审 M/镜头7).
+    if (green.mustMatch !== undefined) {
+        const m = safeTest(green.mustMatch, green_output);
+        if (m === undefined)
+            return { ...base, pass, fail, verdict: "error", reason: `mustMatch is not a valid regex: /${green.mustMatch}/` };
+        if (!m)
+            failures.push(`mustMatch /${green.mustMatch}/ not found`);
+    }
+    if (green.mustNotMatch !== undefined) {
+        const m = safeTest(green.mustNotMatch, green_output);
+        if (m === undefined)
+            return { ...base, pass, fail, verdict: "error", reason: `mustNotMatch is not a valid regex: /${green.mustNotMatch}/` };
+        if (m)
+            failures.push(`mustNotMatch /${green.mustNotMatch}/ matched`);
+    }
+    if (green.parse) {
+        if (fail !== 0)
+            failures.push(`fail count ${fail} !== 0`);
+        let minPass;
+        if (green.minPass === "baseline") {
+            if (baseline === undefined) {
+                // PREFLIGHT lane: the baseline is captured FROM this very run — the criterion only binds later
+                // runs (stop gate / terminal), so it is skipped here (no chicken-and-egg self-reference).
+                minPass = undefined;
+            }
+            else {
+                const b = baseline[gate.name];
+                if (!b) {
+                    // A baseline map exists but this gate has no entry (its preflight parse never succeeded) — an
+                    // unreachable bound is a gate-infrastructure problem, not a red observation.
+                    return { ...base, pass, fail, verdict: "error", reason: `minPass:"baseline" but no baseline captured for gate "${gate.name}"` };
+                }
+                minPass = b.pass + b.fail;
+            }
+        }
+        else {
+            minPass = green.minPass ?? 1;
+        }
+        if (minPass !== undefined && (pass ?? 0) < minPass)
+            failures.push(`pass count ${pass} < minPass ${minPass}`);
+    }
+    if (failures.length > 0)
+        return { ...base, pass, fail, verdict: "red", reason: failures.join("; ") };
+    return { ...base, pass, fail, verdict: "green" };
+}
+/**
+ * Run every gate of the contract's oracle (sequentially — gates commonly share a working tree) and fold
+ * the three-value verdicts: any `error` ⇒ `error` (fail-loud dominates; an unfalsifiable adjudication must
+ * never pass silently), else any `red` ⇒ `red`, else `green`.
+ *
+ * `cwdRoot` is the runSpec root: each gate's `cwd` resolves against it with the same containment rule as
+ * frozenPaths (a contract cannot point its adjudicator outside the workcopy).
+ */
+export async function runOracle(gates, cwdRoot, opts) {
+    const root = resolve(cwdRoot);
+    const results = [];
+    const err = (gate, reason) => ({
+        name: gate.name,
+        verdict: "error",
+        exitCode: null,
+        reason,
+        outputTail: "",
+    });
+    for (const gate of gates) {
+        if (!Array.isArray(gate.cmd) || gate.cmd.length === 0 || typeof gate.cmd[0] !== "string" || gate.cmd[0].length === 0) {
+            results.push(err(gate, "gate cmd is empty — no executable to run")); // codex 镜头7: never escape the three-value lane
+            continue;
+        }
+        let cwd = root;
+        if (gate.cwd !== undefined) {
+            const candidate = resolve(root, gate.cwd);
+            if (candidate !== root && !candidate.startsWith(root + sep)) {
+                results.push(err(gate, `gate cwd escapes the spec root: ${gate.cwd}`));
+                continue;
+            }
+            // Physical containment (codex 镜头5): a symlinked dir INSIDE the root can point outside it — the
+            // lexical startsWith above cannot see that. Compare realpaths when the dir exists (a missing cwd
+            // fails the spawn below and classifies as `error` anyway).
+            try {
+                const physRoot = realpathSync(root);
+                const phys = realpathSync(candidate);
+                if (phys !== physRoot && !phys.startsWith(physRoot + sep)) {
+                    results.push(err(gate, `gate cwd physically escapes the spec root (symlink): ${gate.cwd}`));
+                    continue;
+                }
+            }
+            catch {
+                // nonexistent cwd → let execFile fail → infra error verdict (honest classification)
+            }
+            cwd = candidate;
+        }
+        const exec = await execGate(gate, cwd, opts?.signal);
+        results.push(evaluateGate(gate, exec, opts?.baseline));
+    }
+    const verdict = results.some((r) => r.verdict === "error")
+        ? "error"
+        : results.some((r) => r.verdict === "red")
+            ? "red"
+            : "green";
+    return { verdict, gates: results };
+}
+/** Extract the per-gate baseline counts from a (preflight) report — only gates whose parse succeeded. */
+export function captureBaseline(report) {
+    const baseline = {};
+    for (const g of report.gates) {
+        if (g.pass !== undefined && g.fail !== undefined)
+            baseline[g.name] = { pass: g.pass, fail: g.fail };
+    }
+    return baseline;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// frozenPaths: validation + byte snapshot + restore (fable-M1/M2)
+// ─────────────────────────────────────────────────────────────────────────────
+/** A coded error (`config.*` / `spec.*` convention — same shape as goal.ts's reserved-name fail-fast). */
+export function specError(code, message) {
+    const e = new Error(message);
+    e.code = code;
+    return e;
+}
+/**
+ * Validate and resolve `frozenPaths` against the runSpec root (fable-M2): absolute paths and `..`
+ * segments are rejected outright (`spec.frozen_path_invalid`); the resolved path must stay inside the
+ * root. Returns resolved absolute paths (the ONLY form policy matching and snapshots use).
+ */
+export function resolveFrozenPaths(rootDir, frozenPaths) {
+    const root = resolve(rootDir);
+    return frozenPaths.map((p) => {
+        if (isAbsolute(p) || p.split(/[\\/]/).includes("..")) {
+            throw specError("spec.frozen_path_invalid", `frozenPaths entries must be relative and ..-free: ${p}`);
+        }
+        const abs = resolve(root, p);
+        if (abs !== root && !abs.startsWith(root + sep)) {
+            throw specError("spec.frozen_path_invalid", `frozenPaths entry escapes the root after resolution: ${p}`);
+        }
+        return abs;
+    });
+}
+/**
+ * Byte-level snapshot of the frozen surface (fable-M1: a hash can only DETECT tampering — restoring needs
+ * the CONTENT, and the snapshot is the restore source; no external seed directory dependency). Missing
+ * file ⇒ `spec.frozen_missing` (a frozen path that doesn't exist can't be a specification).
+ */
+export function snapshotFrozenPaths(resolvedPaths) {
+    const snap = new Map();
+    for (const p of resolvedPaths) {
+        try {
+            // lstat, not stat: a frozen path must be a REGULAR FILE at contract time — a symlink here would
+            // make every later restore write through to wherever it points (codex 实现审 B2).
+            if (!lstatSync(p).isFile()) {
+                throw specError("spec.frozen_path_invalid", `frozen path must be a regular file (no symlinks/dirs): ${p}`);
+            }
+            snap.set(p, readFileSync(p));
+        }
+        catch (e) {
+            if (e.code === "spec.frozen_path_invalid")
+                throw e;
+            throw specError("spec.frozen_missing", `frozen path does not exist or is unreadable: ${p}`);
+        }
+    }
+    return snap;
+}
+/**
+ * Restore any frozen file whose on-disk bytes differ from the snapshot (belt for `echo > test/x`-style
+ * bash writes the Write/Edit deny policy cannot see — fable-MIN2). Returns the number of files restored.
+ *
+ * Symlink-safe (codex 实现审 B2): a tampered entry that is no longer a regular file (the model swapped
+ * it for a symlink pointing outside the root) is REMOVED first — the snapshot bytes are then written to
+ * a fresh regular file, never THROUGH a link. When `rootDir` is given, the parent directory's physical
+ * path is containment-checked too (a symlinked PARENT dir would also carry the write outside); an entry
+ * whose parent escapes is skipped (counted) — the terminal oracle then adjudicates the missing spec
+ * files honestly (fail-safe direction) instead of runSpec writing outside its root.
+ */
+export function restoreFrozenPaths(snapshot, rootDir) {
+    const physRoot = rootDir !== undefined ? safeRealpath(resolve(rootDir)) : undefined;
+    let restored = 0;
+    for (const [p, bytes] of snapshot) {
+        let isRegular = false;
+        let current;
+        try {
+            isRegular = lstatSync(p).isFile();
+            current = isRegular ? readFileSync(p) : undefined;
+        }
+        catch {
+            current = undefined; // deleted counts as tampered
+        }
+        if (isRegular && current !== undefined && current.equals(bytes))
+            continue;
+        // 复审 r2:每条目独立 try/catch —— a squatted temp / unwritable dir on ONE entry must NOT abort the
+        // rest of the restore, and must NOT throw out of restoreFrozenPaths (called from run-spec.ts terminal
+        // where a throw would drop the outcome emission). Same fail-safe direction as the parent-escape skip.
+        try {
+            if (physRoot !== undefined) {
+                const physParent = safeRealpath(dirname(p));
+                if (physParent === undefined || (physParent !== physRoot && !physParent.startsWith(physRoot + sep))) {
+                    continue; // parent dir escaped/vanished — do NOT write outside the root; oracle will judge
+                }
+            }
+            if (!isRegular)
+                rmSync(p, { recursive: true, force: true }); // symlink/dir squatting on the path
+            restoreOneAtomic(p, bytes);
+            restored++;
+        }
+        catch {
+            // this entry couldn't be restored (temp squatted, dir unwritable, …) — leave it for the oracle to judge.
+        }
+    }
+    return restored;
+}
+/**
+ * Write `bytes` to `p` atomically via a temp sibling + rename, closing the symlink-follow surface the
+ * review flagged (the previous temp+rename left a larger gap than it closed):
+ *  - the temp name is RANDOM (not `${p}.${pid}`, whose name is inferable from $PPID, so the path could be
+ *    replaced with a symlink beforehand);
+ *  - the temp is created with `flag:"wx"` (O_EXCL — an already-present entry ⇒ EEXIST, never followed);
+ *  - the temp is ALWAYS unlinked in `finally` (no throwaway leaked into the model-visible workspace).
+ * A parent-directory swap between the containment check and the syscalls is a residual window Node cannot
+ * close without openat/O_NOFOLLOW dir fds (documented, not claimed shut); the byte-snapshot restore is a
+ * belt over the Write/Edit deny policy, not the sole guard.
+ */
+function restoreOneAtomic(p, bytes) {
+    const tmp = `${p}.sema-restore-${randomBytes(9).toString("hex")}`;
+    try {
+        writeFileSync(tmp, bytes, { flag: "wx" }); // O_EXCL: refuse (not follow) a placed-in-advance/raced entry
+        renameSync(tmp, p);
+    }
+    finally {
+        rmSync(tmp, { force: true }); // no-op after a successful rename; clears the temp on any failure
+    }
+}
+function safeRealpath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=spec-contract.js.map

package/dist/core/spec-contract.js.map

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

package/dist/core/strategy-store.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Teacher-mode strategy repository (design/14). Stores the *generalized* strategies a teacher gave
+ * that actually worked, so a later similar problem can be solved without re-consulting the teacher
+ * (Inter-Cascade cross-session reuse). Retrieval is deliberately **high-precision / low-recall**: a
+ * wrong strategy injected into a student costs wasted turns + a likely escalation (net negative),
+ * while a missed strategy just falls back to asking the teacher (baseline). `scope` is a **mandatory
+ * isolation boundary** (multi-tenant: one user's strategies must never leak to another).
+ */
+export interface StoredStrategy {
+    /** Stable id. */
+    id: string;
+    /** The raw task objective that triggered the teacher's help — matched against future objectives. */
+    problem: string;
+    /** The teacher's generalized approach (1-2 sentences). */
+    strategy: string;
+    /** The teacher's confidence (0-3) when it gave this. */
+    confidence: number;
+    /** Tenant/isolation scope (e.g. "user:42"). Strategies are only ever retrieved within their scope. */
+    scope: string;
+    /** ISO timestamp stored. */
+    ts: string;
+    /** Teacher model id, for future staleness handling. */
+    teacherModel?: string;
+    /** Reserved for a future generalized signature (v3 semantic matching). */
+    signature?: string;
+}
+export interface StrategyStore {
+    /** Persist a strategy (implementations may merge an exact near-duplicate and cap per-scope size). */
+    save(s: StoredStrategy): Promise<void> | void;
+    /** The most relevant strategies for `query`, within `scope`, at most `limit`. */
+    find(scope: string, query: string, limit: number): Promise<StoredStrategy[]> | StoredStrategy[];
+    /** Optional: trim a scope to `maxSize` (evicting the least useful). */
+    prune?(scope: string, maxSize: number): Promise<void> | void;
+}
+/**
+ * Default in-memory store. Retrieval: a stored problem must contain **every significant** query token
+ * (and there must be ≥1) — near-exact on the meaningful words, ignoring stopword noise. High precision
+ * by design. Ranked by `confidence × recency`. Per-scope capacity cap with eviction on save.
+ */
+export declare class InMemoryStrategyStore implements StrategyStore {
+    private readonly maxPerScope;
+    private byScope;
+    constructor(maxPerScope?: number);
+    save(s: StoredStrategy): void;
+    find(scope: string, query: string, limit: number): StoredStrategy[];
+    prune(scope: string, maxSize: number): void;
+    /** Total stored strategies (across scopes); for tests/observability. */
+    get size(): number;
+}
+//# sourceMappingURL=strategy-store.d.ts.map

package/dist/core/strategy-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy-store.d.ts","sourceRoot":"","sources":["../../src/core/strategy-store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,cAAc;IAC7B,iBAAiB;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,oGAAoG;IACpG,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,sGAAsG;IACtG,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,qGAAqG;IACrG,IAAI,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9C,iFAAiF;IACjF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,GAAG,cAAc,EAAE,CAAC;IAChG,uEAAuE;IACvE,KAAK,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC9D;AAgCD;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IAE7C,OAAO,CAAC,QAAQ,CAAC,WAAW;IADxC,OAAO,CAAC,OAAO,CAAuC;gBACzB,WAAW,SAAM;IAE9C,IAAI,CAAC,CAAC,EAAE,cAAc,GAAG,IAAI;IAqB7B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE;IAgBnE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAS3C,wEAAwE;IACxE,IAAI,IAAI,IAAI,MAAM,CAIjB;CACF"}