niceeval 0.18.0 → 0.19.0

package/dist/loaders/index.d.ts

@@ -1,95 +1,2 @@
-/**
- * Internal discovery provenance. A shared helper is evaluated only once in a
- * fresh module graph, so discovery uses its source module to copy these paths
- * to every Eval entry that statically imports that helper.
- */
-export interface LoaderCaptureOrigin {
-    readonly sourcePath: string;
-    readonly paths: readonly string[];
-    readonly criteriaPaths: readonly string[];
-    readonly privatePaths: readonly string[];
-}
-export interface LoaderCapturePaths {
-    readonly paths: readonly string[];
-    readonly criteriaPaths: readonly string[];
-    readonly privatePaths: readonly string[];
-}
-/**
- * 发现期包住一个 eval 模块的求值，记录它经公开 loader 读取的数据文件（`paths`）、
- * 经 `loadCriteria` 登记的判据树（`criteriaPaths`）、经 `loadPrivate` 登记的永不上传路径
- * （`privatePaths`）。三格分开是因为指纹与泄题门口径不同:
- * data 哈希已读进内存的内容;criteria / private 按内容流式哈希,且 private 另进泄题门。
- */
-export declare function captureLoadedFiles<T>(load: () => Promise<T>): Promise<{
-    value: T;
-    paths: string[];
-    criteriaPaths: string[];
-    privatePaths: string[];
-    origins: readonly LoaderCaptureOrigin[];
-    unattributed: LoaderCapturePaths;
-}>;
-/**
- * 读入一个 JSON 数据文件并解析。路径写项目根相对的字符串,或 eval 文件相对的
- * `new URL(p, import.meta.url)`。内容哈希进读它的那条 eval 的指纹。`decode` 必须在
- * 这个动态输入边界完成结构验证与归一；不提供「用泛型直接信任文件」的入口。
- */
-type DecodedData<T> = unknown extends T ? never : T;
-/**
- * 动态文件值到领域值的唯一出口。`unknown`（以及会把它吞掉的 `any`）不能成为解码结果；
- * decoder 必须返回一个比动态输入更窄、可供 Eval 定义直接使用的领域类型。
- */
-export type DataDecoder<T> = (value: unknown) => DecodedData<T> | Promise<DecodedData<T>>;
-export declare function loadJson<T>(path: string | URL, decode: DataDecoder<T>): Promise<T>;
-/**
- * 按 utf-8 读入一个文件的原文。判据不是结构化数据时用它:隐藏测试脚本、参考实现、
- * shell 模板都是判据文件。读入即宣告「它参与判定」——文件内容哈希进读它的那条 eval
- * 的指纹,改一字节就重跑那条 eval。用 `fs` 自行读入的文件不进指纹。
- * 路径写项目根相对的字符串,或 eval 文件相对的 `new URL(p, import.meta.url)`。
- */
-export declare function loadText(path: string | URL): Promise<string>;
-/** eval 文件相对的 glob；pattern 与 URL 分开，避免 URL parser 改写 glob 字符。 */
-export interface RelativeCriteriaPattern {
-    readonly pattern: string;
-    readonly relativeTo: URL;
-}
-export type CriteriaPattern = string | RelativeCriteriaPattern;
-/**
- * 登记一棵判据树进这条 eval 的指纹,不把内容读进内存。判分标准是一整棵树(隐藏测试目录、
- * 参考实现、跑测脚本)、内容只经 `t.sandbox.uploadDirectory` 整体送进沙箱时用它:
- * 发现期展开 glob、把每个匹配文件流式哈希进指纹,返回排序后的项目根相对路径清单。
- * 树里改一字节、增一个文件、删一个文件,都作废引用这棵树的那条 eval;权限位与修改时间不进哈希,
- * 重新 clone 一份工作树不作废。单个文件、且内容要写进沙箱时用 `loadText`。
- *
- * pattern 是项目根相对的 glob(`**` 跨层、`*` / `?` 段内、`[...]` 字符类、`{a,b}` 分支),
- * `!` 前缀为排除;按声明顺序求值,后写的覆盖先写的。匹配集按文件系统枚举、不看 git:
- * 新写的判据没 `git add` 也照样进指纹,代价是本地跑测冒出的生成物同样被盖到,用 `!` 排除。
- *
- * 只能在 eval 文件的模块顶层调用(发现期求值那一刻),`test(t)` 运行期调用直接报错——
- * 携带决策发生在任何 attempt 执行之前,那时才登记已经来不及。
- *
- * 两种用法错误直接抛:某个 include pattern 一个文件都没匹配到(或命中的都被 `!` 排除了)——
- * 多半是写错了或文件搬走了,别的 pattern 有命中也不放过,静默放过等于判据悄悄变窄;
- * 以及匹配落到项目根外(符号链接穿出根)。`!` 排除 pattern 不受「必须有命中」这条约束。
- *
- * @param patterns 项目根相对 glob,或 `{ pattern, relativeTo: import.meta.url }`;`!` 排除只收字符串。
- * @returns 匹配集的项目根相对路径,排序后(正斜杠分隔),不含内容。
- */
-export declare function loadCriteria(...patterns: CriteriaPattern[]): Promise<string[]>;
-/**
- * 登记永不上传的 private 路径进这条 eval 的判据指纹与泄题门,不把内容读进内存。
- * solution、生成器、参考答案必须与 eval 共址时用它:发现期与全部 build context /
- * bind mount 交叉检查,任何阶段都不得进入 Agent 可见面(见 docs/feature/sandbox/case.md「泄题门」)。
- *
- * pattern 语法、发现期约束、空匹配与穿出项目根的报错与 `loadCriteria` 同形。
- *
- * @param patterns 一个或多个项目根相对 glob,`!` 前缀为排除。
- * @returns 匹配集的项目根相对路径,排序后(正斜杠分隔),不含内容。
- */
-export declare function loadPrivate(...patterns: string[]): Promise<string[]>;
-/**
- * 读入一个 YAML 数据文件并解析,需要项目里装了 `yaml`。路径写项目根相对的字符串,
- * 或 eval 文件相对的 `new URL(p, import.meta.url)`。内容哈希进读它的那条 eval 的指纹。解析结果与
- * JSON 一样必须立即经 `decode` 验证，不让未证明的动态值进入 Eval 定义。
- */
-export declare function loadYaml<T>(path: string | URL, decode: DataDecoder<T>): Promise<T>;
-export {};
+export { loadJson, loadText, loadYaml, loadCriteria, loadPrivate } from "./runtime.js";
+export type { DataDecoder, RelativeCriteriaPattern, CriteriaPattern } from "./runtime.js";

package/dist/loaders/index.js

@@ -1,16 +1,14 @@
 import { createRequire as __niceevalCreateRequire } from "node:module";
 const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
 const __niceevalCanonical = __niceevalRequire("./index.cjs");
-const __niceevalExport0 = __niceevalCanonical["captureLoadedFiles"];
-export { __niceevalExport0 as captureLoadedFiles };
-const __niceevalExport1 = __niceevalCanonical["loadCriteria"];
-export { __niceevalExport1 as loadCriteria };
-const __niceevalExport2 = __niceevalCanonical["loadJson"];
-export { __niceevalExport2 as loadJson };
-const __niceevalExport3 = __niceevalCanonical["loadPrivate"];
-export { __niceevalExport3 as loadPrivate };
-const __niceevalExport4 = __niceevalCanonical["loadText"];
-export { __niceevalExport4 as loadText };
-const __niceevalExport5 = __niceevalCanonical["loadYaml"];
-export { __niceevalExport5 as loadYaml };
+const __niceevalExport0 = __niceevalCanonical["loadCriteria"];
+export { __niceevalExport0 as loadCriteria };
+const __niceevalExport1 = __niceevalCanonical["loadJson"];
+export { __niceevalExport1 as loadJson };
+const __niceevalExport2 = __niceevalCanonical["loadPrivate"];
+export { __niceevalExport2 as loadPrivate };
+const __niceevalExport3 = __niceevalCanonical["loadText"];
+export { __niceevalExport3 as loadText };
+const __niceevalExport4 = __niceevalCanonical["loadYaml"];
+export { __niceevalExport4 as loadYaml };
 //# sourceMappingURL=index.js.map

package/dist/loaders/index.mjs

@@ -1,16 +1,14 @@
 import { createRequire as __niceevalCreateRequire } from "node:module";
 const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
 const __niceevalCanonical = __niceevalRequire("./index.cjs");
-const __niceevalExport0 = __niceevalCanonical["captureLoadedFiles"];
-export { __niceevalExport0 as captureLoadedFiles };
-const __niceevalExport1 = __niceevalCanonical["loadCriteria"];
-export { __niceevalExport1 as loadCriteria };
-const __niceevalExport2 = __niceevalCanonical["loadJson"];
-export { __niceevalExport2 as loadJson };
-const __niceevalExport3 = __niceevalCanonical["loadPrivate"];
-export { __niceevalExport3 as loadPrivate };
-const __niceevalExport4 = __niceevalCanonical["loadText"];
-export { __niceevalExport4 as loadText };
-const __niceevalExport5 = __niceevalCanonical["loadYaml"];
-export { __niceevalExport5 as loadYaml };
+const __niceevalExport0 = __niceevalCanonical["loadCriteria"];
+export { __niceevalExport0 as loadCriteria };
+const __niceevalExport1 = __niceevalCanonical["loadJson"];
+export { __niceevalExport1 as loadJson };
+const __niceevalExport2 = __niceevalCanonical["loadPrivate"];
+export { __niceevalExport2 as loadPrivate };
+const __niceevalExport3 = __niceevalCanonical["loadText"];
+export { __niceevalExport3 as loadText };
+const __niceevalExport4 = __niceevalCanonical["loadYaml"];
+export { __niceevalExport4 as loadYaml };
 //# sourceMappingURL=index.mjs.map

package/dist/loaders/runtime.cjs

@@ -0,0 +1,283 @@
+"use strict";
+const { pathToFileURL: __niceevalPathToFileURL } = require("node:url");
+const __niceevalImportMetaUrl = __niceevalPathToFileURL(__filename).href;
+const __niceevalDynamicImport = (specifier) => import(specifier);
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureLoadedFiles = captureLoadedFiles;
+exports.loadJson = loadJson;
+exports.loadText = loadText;
+exports.loadCriteria = loadCriteria;
+exports.loadPrivate = loadPrivate;
+exports.loadYaml = loadYaml;
+// 数据集加载与发现期捕获共用同一模块状态；公开入口仅导出作者加载函数。
+// 数据集与判据文件加载器:结构化数据读成 YAML / JSON,配 .map(row => defineEval(...)) 扇出;
+// 非结构化的判据文件读成原文;一整棵判据树只登记不读入(loadCriteria,流式哈希)。
+// 经这里读入或登记的文件都进读它那条 eval 的指纹。
+// 单文件路径两种写法等价:项目根相对字符串,或 eval 文件相对的 `file:` URL。
+// glob 不能塞进 URL(`?` 会变 query、`{}` 会编码),所以相对 glob 把 pattern 与基准 URL 分开传。
+// 登记只在发现期的模块求值里成立,所以 capture 不在场时直接报错,不静默漏登记。
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+const glob_ts_1 = require("./glob.cjs");
+let activeCapture;
+/**
+ * 发现期包住一个 eval 模块的求值，记录它经公开 loader 读取的数据文件（`paths`）、
+ * 经 `loadCriteria` 登记的判据树（`criteriaPaths`）、经 `loadPrivate` 登记的永不上传路径
+ * （`privatePaths`）。三格分开是因为指纹与泄题门口径不同:
+ * data 哈希已读进内存的内容;criteria / private 按内容流式哈希,且 private 另进泄题门。
+ */
+async function captureLoadedFiles(load) {
+    const previous = activeCapture;
+    const capture = {
+        data: new Set(),
+        criteria: new Set(),
+        private: new Set(),
+        origins: new Map(),
+        unattributed: newBuckets(),
+    };
+    activeCapture = capture;
+    try {
+        const value = await load();
+        return {
+            value,
+            paths: [...capture.data].sort(),
+            criteriaPaths: [...capture.criteria].sort(),
+            privatePaths: [...capture.private].sort(),
+            origins: Object.freeze([...capture.origins.entries()]
+                .map(([sourcePath, buckets]) => Object.freeze({
+                sourcePath,
+                paths: Object.freeze([...buckets.data].sort()),
+                criteriaPaths: Object.freeze([...buckets.criteria].sort()),
+                privatePaths: Object.freeze([...buckets.private].sort()),
+            }))
+                .sort((left, right) => left.sourcePath.localeCompare(right.sourcePath))),
+            unattributed: Object.freeze({
+                paths: Object.freeze([...capture.unattributed.data].sort()),
+                criteriaPaths: Object.freeze([...capture.unattributed.criteria].sort()),
+                privatePaths: Object.freeze([...capture.unattributed.private].sort()),
+            }),
+        };
+    }
+    finally {
+        activeCapture = previous;
+    }
+}
+function newBuckets() {
+    return {
+        data: new Set(),
+        criteria: new Set(),
+        private: new Set(),
+    };
+}
+/** Best-effort source ownership for a public loader call, without exposing it as an API. */
+function loaderCallerPath() {
+    const stack = new Error().stack;
+    if (stack === undefined)
+        return undefined;
+    const self = (0, node_path_1.resolve)((0, node_url_1.fileURLToPath)(__niceevalImportMetaUrl));
+    for (const line of stack.split("\n").slice(1)) {
+        const match = line.match(/(?:file:\/\/)?(\/.*?):\d+:\d+/);
+        if (match?.[1] === undefined)
+            continue;
+        let candidate;
+        try {
+            candidate = line.includes("file://") ? (0, node_url_1.fileURLToPath)(`file://${match[1]}`) : match[1];
+        }
+        catch {
+            continue;
+        }
+        const absolute = (0, node_path_1.resolve)(candidate);
+        if (absolute !== self)
+            return absolute;
+    }
+    return undefined;
+}
+function registerCapturePath(bucket, absolute) {
+    const capture = activeCapture;
+    if (capture === undefined)
+        return;
+    capture[bucket].add(absolute);
+    const caller = loaderCallerPath();
+    if (caller === undefined) {
+        capture.unattributed[bucket].add(absolute);
+        return;
+    }
+    const buckets = capture.origins.get(caller) ?? newBuckets();
+    capture.origins.set(caller, buckets);
+    buckets[bucket].add(absolute);
+}
+// 两种入参在这里归一成一个绝对路径,登记与指纹因此天然等价:字符串按项目根(进程 cwd)解析,
+// URL 只认 `file:`。fileURLToPath 是 niceeval 内部实现,用户侧写 `new URL(p, import.meta.url)`
+// 就够,不需要 import node:url。
+function resolvedPath(path) {
+    const absolute = typeof path === "string" ? (0, node_path_1.resolve)(process.cwd(), path) : fromFileUrl(path);
+    if (!activeCapture)
+        throw new Error(`Read of "${String(path)}" happened outside discovery: loaders may only be called at the module top level of an eval file (while discovery evaluates that module), which is the only point early enough for the file's content to enter this eval's fingerprint. Move the read to the module top level and keep the result in a constant that test(t) uses; loaders cannot be called at run time from test(t) or from lifecycle hooks.`);
+    registerCapturePath("data", absolute);
+    return absolute;
+}
+function fromFileUrl(url) {
+    if (url.protocol !== "file:")
+        throw new Error(`A URL passed to a loader must use the file: protocol, but got ${url.protocol} (${url.href}). Pass new URL(relativePath, import.meta.url) instead, or use a plain project-root-relative string path.`);
+    return (0, node_url_1.fileURLToPath)(url);
+}
+async function loadJson(path, decode) {
+    const raw = await (0, promises_1.readFile)(resolvedPath(path), "utf-8");
+    const parsed = JSON.parse(raw);
+    return decode(parsed);
+}
+/**
+ * 按 utf-8 读入一个文件的原文。判据不是结构化数据时用它:隐藏测试脚本、参考实现、
+ * shell 模板都是判据文件。读入即宣告「它参与判定」——文件内容哈希进读它的那条 eval
+ * 的指纹,改一字节就重跑那条 eval。用 `fs` 自行读入的文件不进指纹。
+ * 路径写项目根相对的字符串,或 eval 文件相对的 `new URL(p, import.meta.url)`。
+ */
+async function loadText(path) {
+    return (0, promises_1.readFile)(resolvedPath(path), "utf-8");
+}
+/**
+ * 登记一棵判据树进这条 eval 的指纹,不把内容读进内存。判分标准是一整棵树(隐藏测试目录、
+ * 参考实现、跑测脚本)、内容只经 `t.sandbox.uploadDirectory` 整体送进沙箱时用它:
+ * 发现期展开 glob、把每个匹配文件流式哈希进指纹,返回排序后的项目根相对路径清单。
+ * 树里改一字节、增一个文件、删一个文件,都作废引用这棵树的那条 eval;权限位与修改时间不进哈希,
+ * 重新 clone 一份工作树不作废。单个文件、且内容要写进沙箱时用 `loadText`。
+ *
+ * pattern 是项目根相对的 glob(`**` 跨层、`*` / `?` 段内、`[...]` 字符类、`{a,b}` 分支),
+ * `!` 前缀为排除;按声明顺序求值,后写的覆盖先写的。匹配集按文件系统枚举、不看 git:
+ * 新写的判据没 `git add` 也照样进指纹,代价是本地跑测冒出的生成物同样被盖到,用 `!` 排除。
+ *
+ * 只能在 eval 文件的模块顶层调用(发现期求值那一刻),`test(t)` 运行期调用直接报错——
+ * 携带决策发生在任何 attempt 执行之前,那时才登记已经来不及。
+ *
+ * 两种用法错误直接抛:某个 include pattern 一个文件都没匹配到(或命中的都被 `!` 排除了)——
+ * 多半是写错了或文件搬走了,别的 pattern 有命中也不放过,静默放过等于判据悄悄变窄;
+ * 以及匹配落到项目根外(符号链接穿出根)。`!` 排除 pattern 不受「必须有命中」这条约束。
+ *
+ * @param patterns 项目根相对 glob,或 `{ pattern, relativeTo: import.meta.url }`;`!` 排除只收字符串。
+ * @returns 匹配集的项目根相对路径,排序后(正斜杠分隔),不含内容。
+ */
+async function loadCriteria(...patterns) {
+    if (!activeCapture) {
+        const path = patterns
+            .map((pattern) => typeof pattern === "string" ? pattern : `${pattern.pattern} relative to ${pattern.relativeTo.href}`)
+            .join(" ");
+        throw new Error(`Read of "${path}" happened outside discovery: loaders may only be called at the module top level of an eval file (while discovery evaluates that module), which is the only point early enough for the file's content to enter this eval's fingerprint. Move the read to the module top level and keep the result in a constant that test(t) uses; loaders cannot be called at run time from test(t) or from lifecycle hooks.`);
+    }
+    return registerGlobPatterns(patterns.map(normalizeCriteriaPattern), "criteria");
+}
+function normalizeCriteriaPattern(pattern) {
+    if (typeof pattern === "string")
+        return pattern;
+    if (pattern.pattern.startsWith("!")) {
+        throw new Error("loadCriteria exclusions must be project-root-relative strings; " +
+            "put the relative include in { pattern, relativeTo } and pass the exclusion separately");
+    }
+    const baseDir = (0, node_path_1.dirname)(fromFileUrl(pattern.relativeTo));
+    return (0, node_path_1.relative)(process.cwd(), (0, node_path_1.resolve)(baseDir, pattern.pattern)).split(node_path_1.sep).join("/");
+}
+/**
+ * 登记永不上传的 private 路径进这条 eval 的判据指纹与泄题门,不把内容读进内存。
+ * solution、生成器、参考答案必须与 eval 共址时用它:发现期与全部 build context /
+ * bind mount 交叉检查,任何阶段都不得进入 Agent 可见面(见 docs/feature/sandbox/case.md「泄题门」)。
+ *
+ * pattern 语法、发现期约束、空匹配与穿出项目根的报错与 `loadCriteria` 同形。
+ *
+ * @param patterns 一个或多个项目根相对 glob,`!` 前缀为排除。
+ * @returns 匹配集的项目根相对路径,排序后(正斜杠分隔),不含内容。
+ */
+async function loadPrivate(...patterns) {
+    return registerGlobPatterns(patterns, "private");
+}
+async function registerGlobPatterns(patterns, bucket) {
+    const capture = activeCapture;
+    if (!capture)
+        throw new Error(`Read of "${patterns.join(" ")}" happened outside discovery: loaders may only be called at the module top level of an eval file (while discovery evaluates that module), which is the only point early enough for the file's content to enter this eval's fingerprint. Move the read to the module top level and keep the result in a constant that test(t) uses; loaders cannot be called at run time from test(t) or from lifecycle hooks.`);
+    const root = process.cwd();
+    const compiled = (0, glob_ts_1.compilePatterns)(patterns);
+    const matched = new Set();
+    for (const base of (0, glob_ts_1.enumerationBases)(compiled)) {
+        await collectCriteria(root, base, compiled, matched);
+    }
+    const relativePaths = [...matched].sort();
+    // 逐条 include pattern 判空,不是整次调用判空:三条 pattern 里搬走了一条对应的文件时,
+    // 别的两条有命中会让整体放行,判据悄悄变窄——正是「该重跑的没重跑」那个方向。
+    const missing = (0, glob_ts_1.unmatchedIncludes)(compiled, relativePaths);
+    if (missing.length > 0) {
+        const patterns = missing.join(" ");
+        throw new Error(bucket === "private"
+            ? `These loadPrivate patterns matched no files (or everything they matched was excluded by a later \`!\` pattern): ${patterns}. They are most likely misspelled, or the private files moved — patterns expand from the project root ${root}, not from the eval file's directory. Check these against the real paths on disk; letting this pass silently would drop hidden inputs from the leak gate and the fingerprint.`
+            : `These loadCriteria patterns matched no files (or everything they matched was excluded by a later \`!\` pattern): ${patterns}. They are most likely misspelled, or the criteria files moved — patterns expand from the project root ${root}, not from the eval file's directory. Check these against the real paths on disk, and drop the pattern if it is no longer needed; the other patterns having matches is no excuse, because letting this pass silently narrows the criteria, and narrowed criteria let an eval that should re-run keep carrying its old verdict.`);
+    }
+    for (const path of relativePaths)
+        registerCapturePath(bucket, (0, node_path_1.resolve)(root, path));
+    return relativePaths;
+}
+/** 从一个枚举起点往下走,把命中 pattern 集的文件按项目根相对路径收进 out。 */
+async function collectCriteria(root, base, compiled, out) {
+    // pattern 自己就指到根外(`../`、绝对路径)时在起点上先报,不用等枚举。
+    await assertInsideRoot(root, (0, node_path_1.resolve)(root, base), base || ".");
+    // 符号链接可以指回树内,realpath 去重防环。
+    const visited = new Set();
+    const walk = async (dir) => {
+        const real = await (0, promises_1.realpath)(dir).catch(() => undefined);
+        if (real === undefined || visited.has(real))
+            return;
+        visited.add(real);
+        // 起点不存在 / 不是目录时不在这里报:交给「匹配集为空」统一给下一步。
+        const entries = await (0, promises_1.readdir)(dir, { withFileTypes: true }).catch(() => undefined);
+        if (entries === undefined)
+            return;
+        for (const entry of entries) {
+            const absolute = (0, node_path_1.join)(dir, entry.name);
+            let isDirectory = entry.isDirectory();
+            let isFile = entry.isFile();
+            if (entry.isSymbolicLink()) {
+                const target = await (0, promises_1.stat)(absolute).catch(() => undefined);
+                if (target === undefined)
+                    continue; // 断链按不存在处理
+                isDirectory = target.isDirectory();
+                isFile = target.isFile();
+            }
+            if (isDirectory) {
+                await walk(absolute);
+                continue;
+            }
+            if (!isFile)
+                continue;
+            const relativePath = (0, node_path_1.relative)(root, absolute).split(node_path_1.sep).join("/");
+            if (!(0, glob_ts_1.includedByPatterns)(relativePath, compiled))
+                continue;
+            await assertInsideRoot(root, absolute, relativePath);
+            out.add(relativePath);
+        }
+    };
+    await walk((0, node_path_1.resolve)(root, base));
+}
+async function assertInsideRoot(root, absolute, shown) {
+    const real = await (0, promises_1.realpath)(absolute).catch(() => absolute);
+    if (real !== root && !real.startsWith(`${root}${node_path_1.sep}`)) {
+        throw new Error(`loadCriteria matched "${shown}", which lands outside the project root (it resolves to ${real}): a criteria file's project-root-relative path is its fingerprint key, and that key stops being stable once it points out of the root. Move the tree (or the symlink's target) inside the project root ${root}, or exclude that link with a \`!\` pattern.`);
+    }
+}
+/**
+ * 读入一个 YAML 数据文件并解析,需要项目里装了 `yaml`。路径写项目根相对的字符串,
+ * 或 eval 文件相对的 `new URL(p, import.meta.url)`。内容哈希进读它的那条 eval 的指纹。解析结果与
+ * JSON 一样必须立即经 `decode` 验证，不让未证明的动态值进入 Eval 定义。
+ */
+async function loadYaml(path, decode) {
+    const raw = await (0, promises_1.readFile)(resolvedPath(path), "utf-8");
+    // yaml 是可选依赖:用变量 specifier 避免 tsc 静态解析。装了就用真解析器;
+    // 没装直接报错并给出下一步 —— 不再退回手写的「极简 YAML」:它对嵌套 / 多行 /
+    // 锚点会静默解析出错误数据,让 eval 拿着错的 case 跑起来比直接失败更糟。
+    const yamlPkg = "yaml";
+    let parse;
+    try {
+        ({ parse } = (await __niceevalDynamicImport(yamlPkg)));
+    }
+    catch {
+        throw new Error(`loadYaml("${String(path)}") needs a YAML parser: run \`pnpm add yaml\` first (or switch to loadJson with a JSON dataset).`);
+    }
+    return decode(parse(raw));
+}
+//# sourceMappingURL=runtime.cjs.map

package/dist/loaders/runtime.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["runtime.ts"],"names":[],"mappings":"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","sourcesContent":["// 数据集加载与发现期捕获共用同一模块状态；公开入口仅导出作者加载函数。\n// 数据集与判据文件加载器:结构化数据读成 YAML / JSON,配 .map(row => defineEval(...)) 扇出;\n// 非结构化的判据文件读成原文;一整棵判据树只登记不读入(loadCriteria,流式哈希)。\n// 经这里读入或登记的文件都进读它那条 eval 的指纹。\n// 单文件路径两种写法等价:项目根相对字符串,或 eval 文件相对的 `file:` URL。\n// glob 不能塞进 URL(`?` 会变 query、`{}` 会编码),所以相对 glob 把 pattern 与基准 URL 分开传。\n// 登记只在发现期的模块求值里成立,所以 capture 不在场时直接报错,不静默漏登记。\nimport { readdir, readFile, realpath, stat } from \"node:fs/promises\";\nimport { dirname, join, relative, resolve, sep } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { compilePatterns, enumerationBases, includedByPatterns, unmatchedIncludes, type CompiledPattern } from \"./glob.ts\";\n/**\n * 一次发现期求值的登记表:\n * - data:读入即登记的数据文件(内容已在内存)\n * - criteria:只登记不读入的判据树(verifier)\n * - private:只登记不读入、永不上传的隐藏文件\n * 三格分开是因为指纹与泄题门口径不同。\n */\ninterface LoaderCapture {\n    readonly data: Set<string>;\n    readonly criteria: Set<string>;\n    readonly private: Set<string>;\n    /** Source module -> registrations made while that module was evaluated. */\n    readonly origins: Map<string, LoaderCaptureBuckets>;\n    /** No usable caller frame: discovery conservatively attributes these to all entries. */\n    readonly unattributed: LoaderCaptureBuckets;\n}\ninterface LoaderCaptureBuckets {\n    readonly data: Set<string>;\n    readonly criteria: Set<string>;\n    readonly private: Set<string>;\n}\ntype LoaderCaptureBucketName = \"data\" | \"criteria\" | \"private\";\n/**\n * Internal discovery provenance. A shared helper is evaluated only once in a\n * fresh module graph, so discovery uses its source module to copy these paths\n * to every Eval entry that statically imports that helper.\n */\nexport interface LoaderCaptureOrigin {\n    readonly sourcePath: string;\n    readonly paths: readonly string[];\n    readonly criteriaPaths: readonly string[];\n    readonly privatePaths: readonly string[];\n}\nexport interface LoaderCapturePaths {\n    readonly paths: readonly string[];\n    readonly criteriaPaths: readonly string[];\n    readonly privatePaths: readonly string[];\n}\nlet activeCapture: LoaderCapture | undefined;\n/**\n * 发现期包住一个 eval 模块的求值，记录它经公开 loader 读取的数据文件（`paths`）、\n * 经 `loadCriteria` 登记的判据树（`criteriaPaths`）、经 `loadPrivate` 登记的永不上传路径\n * （`privatePaths`）。三格分开是因为指纹与泄题门口径不同:\n * data 哈希已读进内存的内容;criteria / private 按内容流式哈希,且 private 另进泄题门。\n */\nexport async function captureLoadedFiles<T>(load: () => Promise<T>): Promise<{\n    value: T;\n    paths: string[];\n    criteriaPaths: string[];\n    privatePaths: string[];\n    origins: readonly LoaderCaptureOrigin[];\n    unattributed: LoaderCapturePaths;\n}> {\n    const previous = activeCapture;\n    const capture: LoaderCapture = {\n        data: new Set<string>(),\n        criteria: new Set<string>(),\n        private: new Set<string>(),\n        origins: new Map<string, LoaderCaptureBuckets>(),\n        unattributed: newBuckets(),\n    };\n    activeCapture = capture;\n    try {\n        const value = await load();\n        return {\n            value,\n            paths: [...capture.data].sort(),\n            criteriaPaths: [...capture.criteria].sort(),\n            privatePaths: [...capture.private].sort(),\n            origins: Object.freeze([...capture.origins.entries()]\n                .map(([sourcePath, buckets]) => Object.freeze({\n                sourcePath,\n                paths: Object.freeze([...buckets.data].sort()),\n                criteriaPaths: Object.freeze([...buckets.criteria].sort()),\n                privatePaths: Object.freeze([...buckets.private].sort()),\n            }))\n                .sort((left, right) => left.sourcePath.localeCompare(right.sourcePath))),\n            unattributed: Object.freeze({\n                paths: Object.freeze([...capture.unattributed.data].sort()),\n                criteriaPaths: Object.freeze([...capture.unattributed.criteria].sort()),\n                privatePaths: Object.freeze([...capture.unattributed.private].sort()),\n            }),\n        };\n    }\n    finally {\n        activeCapture = previous;\n    }\n}\nfunction newBuckets(): LoaderCaptureBuckets {\n    return {\n        data: new Set<string>(),\n        criteria: new Set<string>(),\n        private: new Set<string>(),\n    };\n}\n/** Best-effort source ownership for a public loader call, without exposing it as an API. */\nfunction loaderCallerPath(): string | undefined {\n    const stack = new Error().stack;\n    if (stack === undefined)\n        return undefined;\n    const self = resolve(fileURLToPath(__niceevalImportMetaUrl));\n    for (const line of stack.split(\"\\n\").slice(1)) {\n        const match = line.match(/(?:file:\\/\\/)?(\\/.*?):\\d+:\\d+/);\n        if (match?.[1] === undefined)\n            continue;\n        let candidate: string;\n        try {\n            candidate = line.includes(\"file://\") ? fileURLToPath(`file://${match[1]}`) : match[1];\n        }\n        catch {\n            continue;\n        }\n        const absolute = resolve(candidate);\n        if (absolute !== self)\n            return absolute;\n    }\n    return undefined;\n}\nfunction registerCapturePath(bucket: LoaderCaptureBucketName, absolute: string): void {\n    const capture = activeCapture;\n    if (capture === undefined)\n        return;\n    capture[bucket].add(absolute);\n    const caller = loaderCallerPath();\n    if (caller === undefined) {\n        capture.unattributed[bucket].add(absolute);\n        return;\n    }\n    const buckets = capture.origins.get(caller) ?? newBuckets();\n    capture.origins.set(caller, buckets);\n    buckets[bucket].add(absolute);\n}\n// 两种入参在这里归一成一个绝对路径,登记与指纹因此天然等价:字符串按项目根(进程 cwd)解析,\n// URL 只认 `file:`。fileURLToPath 是 niceeval 内部实现,用户侧写 `new URL(p, import.meta.url)`\n// 就够,不需要 import node:url。\nfunction resolvedPath(path: string | URL): string {\n    const absolute = typeof path === \"string\" ? resolve(process.cwd(), path) : fromFileUrl(path);\n    if (!activeCapture)\n        throw new Error(`Read of \"${String(path)}\" happened outside discovery: loaders may only be called at the module top level of an eval file (while discovery evaluates that module), which is the only point early enough for the file's content to enter this eval's fingerprint. Move the read to the module top level and keep the result in a constant that test(t) uses; loaders cannot be called at run time from test(t) or from lifecycle hooks.`);\n    registerCapturePath(\"data\", absolute);\n    return absolute;\n}\nfunction fromFileUrl(url: URL): string {\n    if (url.protocol !== \"file:\")\n        throw new Error(`A URL passed to a loader must use the file: protocol, but got ${url.protocol} (${url.href}). Pass new URL(relativePath, import.meta.url) instead, or use a plain project-root-relative string path.`);\n    return fileURLToPath(url);\n}\n/**\n * 读入一个 JSON 数据文件并解析。路径写项目根相对的字符串,或 eval 文件相对的\n * `new URL(p, import.meta.url)`。内容哈希进读它的那条 eval 的指纹。`decode` 必须在\n * 这个动态输入边界完成结构验证与归一；不提供「用泛型直接信任文件」的入口。\n */\ntype DecodedData<T> = unknown extends T ? never : T;\n/**\n * 动态文件值到领域值的唯一出口。`unknown`（以及会把它吞掉的 `any`）不能成为解码结果；\n * decoder 必须返回一个比动态输入更窄、可供 Eval 定义直接使用的领域类型。\n */\nexport type DataDecoder<T> = (value: unknown) => DecodedData<T> | Promise<DecodedData<T>>;\nexport async function loadJson<T>(path: string | URL, decode: DataDecoder<T>): Promise<T> {\n    const raw = await readFile(resolvedPath(path), \"utf-8\");\n    const parsed: unknown = JSON.parse(raw);\n    return decode(parsed);\n}\n/**\n * 按 utf-8 读入一个文件的原文。判据不是结构化数据时用它:隐藏测试脚本、参考实现、\n * shell 模板都是判据文件。读入即宣告「它参与判定」——文件内容哈希进读它的那条 eval\n * 的指纹,改一字节就重跑那条 eval。用 `fs` 自行读入的文件不进指纹。\n * 路径写项目根相对的字符串,或 eval 文件相对的 `new URL(p, import.meta.url)`。\n */\nexport async function loadText(path: string | URL): Promise<string> {\n    return readFile(resolvedPath(path), \"utf-8\");\n}\n/** eval 文件相对的 glob；pattern 与 URL 分开，避免 URL parser 改写 glob 字符。 */\nexport interface RelativeCriteriaPattern {\n    readonly pattern: string;\n    readonly relativeTo: URL;\n}\nexport type CriteriaPattern = string | RelativeCriteriaPattern;\n/**\n * 登记一棵判据树进这条 eval 的指纹,不把内容读进内存。判分标准是一整棵树(隐藏测试目录、\n * 参考实现、跑测脚本)、内容只经 `t.sandbox.uploadDirectory` 整体送进沙箱时用它:\n * 发现期展开 glob、把每个匹配文件流式哈希进指纹,返回排序后的项目根相对路径清单。\n * 树里改一字节、增一个文件、删一个文件,都作废引用这棵树的那条 eval;权限位与修改时间不进哈希,\n * 重新 clone 一份工作树不作废。单个文件、且内容要写进沙箱时用 `loadText`。\n *\n * pattern 是项目根相对的 glob(`**` 跨层、`*` / `?` 段内、`[...]` 字符类、`{a,b}` 分支),\n * `!` 前缀为排除;按声明顺序求值,后写的覆盖先写的。匹配集按文件系统枚举、不看 git:\n * 新写的判据没 `git add` 也照样进指纹,代价是本地跑测冒出的生成物同样被盖到,用 `!` 排除。\n *\n * 只能在 eval 文件的模块顶层调用(发现期求值那一刻),`test(t)` 运行期调用直接报错——\n * 携带决策发生在任何 attempt 执行之前,那时才登记已经来不及。\n *\n * 两种用法错误直接抛:某个 include pattern 一个文件都没匹配到(或命中的都被 `!` 排除了)——\n * 多半是写错了或文件搬走了,别的 pattern 有命中也不放过,静默放过等于判据悄悄变窄;\n * 以及匹配落到项目根外(符号链接穿出根)。`!` 排除 pattern 不受「必须有命中」这条约束。\n *\n * @param patterns 项目根相对 glob,或 `{ pattern, relativeTo: import.meta.url }`;`!` 排除只收字符串。\n * @returns 匹配集的项目根相对路径,排序后(正斜杠分隔),不含内容。\n */\nexport async function loadCriteria(...patterns: CriteriaPattern[]): Promise<string[]> {\n    if (!activeCapture) {\n        const path = patterns\n            .map((pattern) => typeof pattern === \"string\" ? pattern : `${pattern.pattern} relative to ${pattern.relativeTo.href}`)\n            .join(\" \");\n        throw new Error(`Read of \"${path}\" happened outside discovery: loaders may only be called at the module top level of an eval file (while discovery evaluates that module), which is the only point early enough for the file's content to enter this eval's fingerprint. Move the read to the module top level and keep the result in a constant that test(t) uses; loaders cannot be called at run time from test(t) or from lifecycle hooks.`);\n    }\n    return registerGlobPatterns(patterns.map(normalizeCriteriaPattern), \"criteria\");\n}\nfunction normalizeCriteriaPattern(pattern: CriteriaPattern): string {\n    if (typeof pattern === \"string\")\n        return pattern;\n    if (pattern.pattern.startsWith(\"!\")) {\n        throw new Error(\"loadCriteria exclusions must be project-root-relative strings; \" +\n            \"put the relative include in { pattern, relativeTo } and pass the exclusion separately\");\n    }\n    const baseDir = dirname(fromFileUrl(pattern.relativeTo));\n    return relative(process.cwd(), resolve(baseDir, pattern.pattern)).split(sep).join(\"/\");\n}\n/**\n * 登记永不上传的 private 路径进这条 eval 的判据指纹与泄题门,不把内容读进内存。\n * solution、生成器、参考答案必须与 eval 共址时用它:发现期与全部 build context /\n * bind mount 交叉检查,任何阶段都不得进入 Agent 可见面(见 docs/feature/sandbox/case.md「泄题门」)。\n *\n * pattern 语法、发现期约束、空匹配与穿出项目根的报错与 `loadCriteria` 同形。\n *\n * @param patterns 一个或多个项目根相对 glob,`!` 前缀为排除。\n * @returns 匹配集的项目根相对路径,排序后(正斜杠分隔),不含内容。\n */\nexport async function loadPrivate(...patterns: string[]): Promise<string[]> {\n    return registerGlobPatterns(patterns, \"private\");\n}\nasync function registerGlobPatterns(patterns: string[], bucket: \"criteria\" | \"private\"): Promise<string[]> {\n    const capture = activeCapture;\n    if (!capture)\n        throw new Error(`Read of \"${patterns.join(\" \")}\" happened outside discovery: loaders may only be called at the module top level of an eval file (while discovery evaluates that module), which is the only point early enough for the file's content to enter this eval's fingerprint. Move the read to the module top level and keep the result in a constant that test(t) uses; loaders cannot be called at run time from test(t) or from lifecycle hooks.`);\n    const root = process.cwd();\n    const compiled = compilePatterns(patterns);\n    const matched = new Set<string>();\n    for (const base of enumerationBases(compiled)) {\n        await collectCriteria(root, base, compiled, matched);\n    }\n    const relativePaths = [...matched].sort();\n    // 逐条 include pattern 判空,不是整次调用判空:三条 pattern 里搬走了一条对应的文件时,\n    // 别的两条有命中会让整体放行,判据悄悄变窄——正是「该重跑的没重跑」那个方向。\n    const missing = unmatchedIncludes(compiled, relativePaths);\n    if (missing.length > 0) {\n        const patterns = missing.join(\" \");\n        throw new Error(bucket === \"private\"\n            ? `These loadPrivate patterns matched no files (or everything they matched was excluded by a later \\`!\\` pattern): ${patterns}. They are most likely misspelled, or the private files moved — patterns expand from the project root ${root}, not from the eval file's directory. Check these against the real paths on disk; letting this pass silently would drop hidden inputs from the leak gate and the fingerprint.`\n            : `These loadCriteria patterns matched no files (or everything they matched was excluded by a later \\`!\\` pattern): ${patterns}. They are most likely misspelled, or the criteria files moved — patterns expand from the project root ${root}, not from the eval file's directory. Check these against the real paths on disk, and drop the pattern if it is no longer needed; the other patterns having matches is no excuse, because letting this pass silently narrows the criteria, and narrowed criteria let an eval that should re-run keep carrying its old verdict.`);\n    }\n    for (const path of relativePaths)\n        registerCapturePath(bucket, resolve(root, path));\n    return relativePaths;\n}\n/** 从一个枚举起点往下走,把命中 pattern 集的文件按项目根相对路径收进 out。 */\nasync function collectCriteria(root: string, base: string, compiled: readonly CompiledPattern[], out: Set<string>): Promise<void> {\n    // pattern 自己就指到根外(`../`、绝对路径)时在起点上先报,不用等枚举。\n    await assertInsideRoot(root, resolve(root, base), base || \".\");\n    // 符号链接可以指回树内,realpath 去重防环。\n    const visited = new Set<string>();\n    const walk = async (dir: string): Promise<void> => {\n        const real = await realpath(dir).catch(() => undefined);\n        if (real === undefined || visited.has(real))\n            return;\n        visited.add(real);\n        // 起点不存在 / 不是目录时不在这里报:交给「匹配集为空」统一给下一步。\n        const entries = await readdir(dir, { withFileTypes: true }).catch(() => undefined);\n        if (entries === undefined)\n            return;\n        for (const entry of entries) {\n            const absolute = join(dir, entry.name);\n            let isDirectory = entry.isDirectory();\n            let isFile = entry.isFile();\n            if (entry.isSymbolicLink()) {\n                const target = await stat(absolute).catch(() => undefined);\n                if (target === undefined)\n                    continue; // 断链按不存在处理\n                isDirectory = target.isDirectory();\n                isFile = target.isFile();\n            }\n            if (isDirectory) {\n                await walk(absolute);\n                continue;\n            }\n            if (!isFile)\n                continue;\n            const relativePath = relative(root, absolute).split(sep).join(\"/\");\n            if (!includedByPatterns(relativePath, compiled))\n                continue;\n            await assertInsideRoot(root, absolute, relativePath);\n            out.add(relativePath);\n        }\n    };\n    await walk(resolve(root, base));\n}\nasync function assertInsideRoot(root: string, absolute: string, shown: string): Promise<void> {\n    const real = await realpath(absolute).catch(() => absolute);\n    if (real !== root && !real.startsWith(`${root}${sep}`)) {\n        throw new Error(`loadCriteria matched \"${shown}\", which lands outside the project root (it resolves to ${real}): a criteria file's project-root-relative path is its fingerprint key, and that key stops being stable once it points out of the root. Move the tree (or the symlink's target) inside the project root ${root}, or exclude that link with a \\`!\\` pattern.`);\n    }\n}\n/**\n * 读入一个 YAML 数据文件并解析,需要项目里装了 `yaml`。路径写项目根相对的字符串,\n * 或 eval 文件相对的 `new URL(p, import.meta.url)`。内容哈希进读它的那条 eval 的指纹。解析结果与\n * JSON 一样必须立即经 `decode` 验证，不让未证明的动态值进入 Eval 定义。\n */\nexport async function loadYaml<T>(path: string | URL, decode: DataDecoder<T>): Promise<T> {\n    const raw = await readFile(resolvedPath(path), \"utf-8\");\n    // yaml 是可选依赖:用变量 specifier 避免 tsc 静态解析。装了就用真解析器;\n    // 没装直接报错并给出下一步 —— 不再退回手写的「极简 YAML」:它对嵌套 / 多行 /\n    // 锚点会静默解析出错误数据,让 eval 拿着错的 case 跑起来比直接失败更糟。\n    const yamlPkg = \"yaml\";\n    let parse: (s: string) => unknown;\n    try {\n        ({ parse } = (await __niceevalDynamicImport(yamlPkg)) as {\n            parse(s: string): unknown;\n        });\n    }\n    catch {\n        throw new Error(`loadYaml(\"${String(path)}\") needs a YAML parser: run \\`pnpm add yaml\\` first (or switch to loadJson with a JSON dataset).`);\n    }\n    return decode(parse(raw));\n}\n"]}

package/dist/loaders/runtime.d.cts

@@ -0,0 +1,95 @@
+/**
+ * Internal discovery provenance. A shared helper is evaluated only once in a
+ * fresh module graph, so discovery uses its source module to copy these paths
+ * to every Eval entry that statically imports that helper.
+ */
+export interface LoaderCaptureOrigin {
+    readonly sourcePath: string;
+    readonly paths: readonly string[];
+    readonly criteriaPaths: readonly string[];
+    readonly privatePaths: readonly string[];
+}
+export interface LoaderCapturePaths {
+    readonly paths: readonly string[];
+    readonly criteriaPaths: readonly string[];
+    readonly privatePaths: readonly string[];
+}
+/**
+ * 发现期包住一个 eval 模块的求值，记录它经公开 loader 读取的数据文件（`paths`）、
+ * 经 `loadCriteria` 登记的判据树（`criteriaPaths`）、经 `loadPrivate` 登记的永不上传路径
+ * （`privatePaths`）。三格分开是因为指纹与泄题门口径不同:
+ * data 哈希已读进内存的内容;criteria / private 按内容流式哈希,且 private 另进泄题门。
+ */
+export declare function captureLoadedFiles<T>(load: () => Promise<T>): Promise<{
+    value: T;
+    paths: string[];
+    criteriaPaths: string[];
+    privatePaths: string[];
+    origins: readonly LoaderCaptureOrigin[];
+    unattributed: LoaderCapturePaths;
+}>;
+/**
+ * 读入一个 JSON 数据文件并解析。路径写项目根相对的字符串,或 eval 文件相对的
+ * `new URL(p, import.meta.url)`。内容哈希进读它的那条 eval 的指纹。`decode` 必须在
+ * 这个动态输入边界完成结构验证与归一；不提供「用泛型直接信任文件」的入口。
+ */
+type DecodedData<T> = unknown extends T ? never : T;
+/**
+ * 动态文件值到领域值的唯一出口。`unknown`（以及会把它吞掉的 `any`）不能成为解码结果；
+ * decoder 必须返回一个比动态输入更窄、可供 Eval 定义直接使用的领域类型。
+ */
+export type DataDecoder<T> = (value: unknown) => DecodedData<T> | Promise<DecodedData<T>>;
+export declare function loadJson<T>(path: string | URL, decode: DataDecoder<T>): Promise<T>;
+/**
+ * 按 utf-8 读入一个文件的原文。判据不是结构化数据时用它:隐藏测试脚本、参考实现、
+ * shell 模板都是判据文件。读入即宣告「它参与判定」——文件内容哈希进读它的那条 eval
+ * 的指纹,改一字节就重跑那条 eval。用 `fs` 自行读入的文件不进指纹。
+ * 路径写项目根相对的字符串,或 eval 文件相对的 `new URL(p, import.meta.url)`。
+ */
+export declare function loadText(path: string | URL): Promise<string>;
+/** eval 文件相对的 glob；pattern 与 URL 分开，避免 URL parser 改写 glob 字符。 */
+export interface RelativeCriteriaPattern {
+    readonly pattern: string;
+    readonly relativeTo: URL;
+}
+export type CriteriaPattern = string | RelativeCriteriaPattern;
+/**
+ * 登记一棵判据树进这条 eval 的指纹,不把内容读进内存。判分标准是一整棵树(隐藏测试目录、
+ * 参考实现、跑测脚本)、内容只经 `t.sandbox.uploadDirectory` 整体送进沙箱时用它:
+ * 发现期展开 glob、把每个匹配文件流式哈希进指纹,返回排序后的项目根相对路径清单。
+ * 树里改一字节、增一个文件、删一个文件,都作废引用这棵树的那条 eval;权限位与修改时间不进哈希,
+ * 重新 clone 一份工作树不作废。单个文件、且内容要写进沙箱时用 `loadText`。
+ *
+ * pattern 是项目根相对的 glob(`**` 跨层、`*` / `?` 段内、`[...]` 字符类、`{a,b}` 分支),
+ * `!` 前缀为排除;按声明顺序求值,后写的覆盖先写的。匹配集按文件系统枚举、不看 git:
+ * 新写的判据没 `git add` 也照样进指纹,代价是本地跑测冒出的生成物同样被盖到,用 `!` 排除。
+ *
+ * 只能在 eval 文件的模块顶层调用(发现期求值那一刻),`test(t)` 运行期调用直接报错——
+ * 携带决策发生在任何 attempt 执行之前,那时才登记已经来不及。
+ *
+ * 两种用法错误直接抛:某个 include pattern 一个文件都没匹配到(或命中的都被 `!` 排除了)——
+ * 多半是写错了或文件搬走了,别的 pattern 有命中也不放过,静默放过等于判据悄悄变窄;
+ * 以及匹配落到项目根外(符号链接穿出根)。`!` 排除 pattern 不受「必须有命中」这条约束。
+ *
+ * @param patterns 项目根相对 glob,或 `{ pattern, relativeTo: import.meta.url }`;`!` 排除只收字符串。
+ * @returns 匹配集的项目根相对路径,排序后(正斜杠分隔),不含内容。
+ */
+export declare function loadCriteria(...patterns: CriteriaPattern[]): Promise<string[]>;
+/**
+ * 登记永不上传的 private 路径进这条 eval 的判据指纹与泄题门,不把内容读进内存。
+ * solution、生成器、参考答案必须与 eval 共址时用它:发现期与全部 build context /
+ * bind mount 交叉检查,任何阶段都不得进入 Agent 可见面(见 docs/feature/sandbox/case.md「泄题门」)。
+ *
+ * pattern 语法、发现期约束、空匹配与穿出项目根的报错与 `loadCriteria` 同形。
+ *
+ * @param patterns 一个或多个项目根相对 glob,`!` 前缀为排除。
+ * @returns 匹配集的项目根相对路径,排序后(正斜杠分隔),不含内容。
+ */
+export declare function loadPrivate(...patterns: string[]): Promise<string[]>;
+/**
+ * 读入一个 YAML 数据文件并解析,需要项目里装了 `yaml`。路径写项目根相对的字符串,
+ * 或 eval 文件相对的 `new URL(p, import.meta.url)`。内容哈希进读它的那条 eval 的指纹。解析结果与
+ * JSON 一样必须立即经 `decode` 验证，不让未证明的动态值进入 Eval 定义。
+ */
+export declare function loadYaml<T>(path: string | URL, decode: DataDecoder<T>): Promise<T>;
+export {};