@alisio/core 0.5.2 → 0.7.0

package/dist/eval/export.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The shareable export of one evaluation run (specs/010 5.4, D9): a single JSON bundle
+ * `{ schemaVersion: 1, report, runs[], markdown }` without absolute paths and without secrets.
+ * Pure: the caller reads the files and supplies the roots to hide.
+ *
+ * - Known roots (home, data directory, run directory, temp directories) become placeholders; any
+ *   other absolute path that remains becomes `<path>`. Scrubbing is pattern-based: it is not a
+ *   guarantee against every sensitive string a task prompt, verifier detail or tool output holds.
+ * - The cassette secret scanner runs over every string of the scrubbed bundle. A hit REFUSES the
+ *   export (nothing is stripped) and names the field path, never the matched text.
+ * - A provider id that is not a plain identifier may embed an endpoint host: it is reduced to
+ *   `custom-endpoint` everywhere it appears.
+ */
+import type { EvalReport, EvalRunRecord } from "@alisio/sdk";
+export interface EvalExportBundle {
+    schemaVersion: 1;
+    report: EvalReport;
+    runs: EvalRunRecord[];
+    markdown: string;
+}
+export interface ExportContext {
+    /** Absolute directories to hide, each with the placeholder that replaces it. */
+    roots: Array<{
+        path: string;
+        placeholder: string;
+    }>;
+    /** Exact credential values to look for verbatim (profile and environment). */
+    secrets?: string[];
+}
+/** The export holds something that looks like a secret; `fieldPath` says where, never what. */
+export declare class EvalExportRefusedError extends Error {
+    readonly fieldPath: string;
+    readonly rules: string[];
+    constructor(fieldPath: string, rules: string[]);
+}
+export declare function buildExportBundle(input: {
+    report: EvalReport;
+    runs: EvalRunRecord[];
+    markdown: string;
+}, ctx: ExportContext): EvalExportBundle;

package/dist/eval/export.js

@@ -0,0 +1,90 @@
+/**
+ * The shareable export of one evaluation run (specs/010 5.4, D9): a single JSON bundle
+ * `{ schemaVersion: 1, report, runs[], markdown }` without absolute paths and without secrets.
+ * Pure: the caller reads the files and supplies the roots to hide.
+ *
+ * - Known roots (home, data directory, run directory, temp directories) become placeholders; any
+ *   other absolute path that remains becomes `<path>`. Scrubbing is pattern-based: it is not a
+ *   guarantee against every sensitive string a task prompt, verifier detail or tool output holds.
+ * - The cassette secret scanner runs over every string of the scrubbed bundle. A hit REFUSES the
+ *   export (nothing is stripped) and names the field path, never the matched text.
+ * - A provider id that is not a plain identifier may embed an endpoint host: it is reduced to
+ *   `custom-endpoint` everywhere it appears.
+ */
+import { findSecrets } from "./secrets.js";
+/** The export holds something that looks like a secret; `fieldPath` says where, never what. */
+export class EvalExportRefusedError extends Error {
+    fieldPath;
+    rules;
+    constructor(fieldPath, rules) {
+        super(`Refusing to export: ${fieldPath} looks like it holds a secret (${rules.join(", ")}). Nothing was written. Remove it from the run, or do not share this run.`);
+        this.fieldPath = fieldPath;
+        this.rules = rules;
+        this.name = "EvalExportRefusedError";
+    }
+}
+const SAFE_PROVIDER = /^[A-Za-z0-9_-]+$/;
+const HOST_FREE_PROVIDER = "custom-endpoint";
+const NAME_CHAR = "[\\w.@+~-]";
+const escapeRegex = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const trimSlash = (path) => (path.length > 1 ? path.replace(/[\\/]+$/, "") : path);
+const POSIX_PATH = new RegExp(`(?<![\\w.:/<>~-])/(?:${NAME_CHAR}+/)+${NAME_CHAR}*`, "g");
+const WINDOWS_PATH = /\b[A-Za-z]:[\\/][^\s"'<>|,;]+/g;
+function scrubber(ctx, providers) {
+    const roots = ctx.roots
+        .map((r) => ({ path: trimSlash(r.path), placeholder: r.placeholder }))
+        .filter((r) => r.path.length > 1)
+        .sort((a, b) => b.path.length - a.path.length)
+        .map((r) => ({
+        pattern: new RegExp(`${escapeRegex(r.path)}(?!${NAME_CHAR})`, "g"),
+        placeholder: r.placeholder,
+    }));
+    const hosts = [...providers].sort((a, b) => b.length - a.length);
+    return (text) => {
+        let out = text;
+        for (const provider of hosts)
+            out = out.split(provider).join(HOST_FREE_PROVIDER);
+        for (const root of roots)
+            out = out.replace(root.pattern, root.placeholder);
+        return out.replace(WINDOWS_PATH, "<path>").replace(POSIX_PATH, "<path>");
+    };
+}
+/** Rebuilds `value` with `fn` applied to every string (keys included untouched). */
+function mapStrings(value, fn) {
+    if (typeof value === "string")
+        return fn(value);
+    if (Array.isArray(value))
+        return value.map((item) => mapStrings(item, fn));
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, mapStrings(v, fn)]));
+    return value;
+}
+/** Calls `visit` with the field path of every string in `value`. */
+function walkStrings(value, path, visit) {
+    if (typeof value === "string")
+        visit(value, path);
+    else if (Array.isArray(value))
+        value.forEach((item, index) => walkStrings(item, `${path}[${index}]`, visit));
+    else if (value && typeof value === "object")
+        for (const [key, item] of Object.entries(value))
+            walkStrings(item, path ? `${path}.${key}` : key, visit);
+}
+export function buildExportBundle(input, ctx) {
+    const providers = new Set();
+    for (const value of [input.report.conditions.provider, ...input.runs.map((r) => r.provider)])
+        if (value && !SAFE_PROVIDER.test(value))
+            providers.add(value);
+    const scrub = scrubber(ctx, [...providers]);
+    const bundle = {
+        schemaVersion: 1,
+        report: mapStrings(input.report, scrub),
+        runs: mapStrings(input.runs, scrub),
+        markdown: scrub(input.markdown),
+    };
+    walkStrings(bundle, "", (text, path) => {
+        const rules = findSecrets(text, ctx.secrets ?? []);
+        if (rules.length > 0)
+            throw new EvalExportRefusedError(path, rules);
+    });
+    return bundle;
+}

package/dist/eval/fingerprint.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The request fingerprint of the cassettes (specs/010 D10) and its structured divergence diff.
+ *
+ * What is hashed (after run-scoped normalization, see `normalize.ts`): `instructions`, every
+ * message, the tools reduced to `{name, description, inputSchema}` (sorted by name),
+ * `maxOutputTokens`, `model`, `nativeTools` and `reasoningEffort`. The spec's field list omitted
+ * the last two, but they change what the provider receives. Excluded on purpose: `signal` and
+ * `sessionId` (a per-run identity, not part of the request's meaning).
+ *
+ * The fingerprint is the hash of a PARTS record (one short hash per part), and the cassette stores
+ * those parts per call, so a divergence can be explained part by part. The texts needed to show
+ * what the recording had (instructions, tool descriptions and schemas, messages) are stored once,
+ * capped, in a `CassetteTexts` store.
+ */
+import type { ModelProvider } from "@alisio/sdk";
+import type { Normalizer } from "./normalize.ts";
+export type StreamRequest = Parameters<ModelProvider["stream"]>[0];
+/** Characters of a stored text (message parts, tool descriptions and schemas). */
+export declare const TEXT_CAP = 4096;
+/** Instructions are stored longer: they are the largest single part and are stored once. */
+export declare const INSTRUCTIONS_CAP = 49152;
+export interface FingerprintParts {
+    instructions: string;
+    messages: string[];
+    /** Hash of the tool set (see `CassetteTexts.toolSets`). */
+    tools: string;
+    maxOutputTokens: number;
+    model: string | null;
+    reasoningEffort: string | null;
+    /** Hash of the native tools, `null` when there are none. */
+    nativeTools: string | null;
+}
+/** What is stored about one message so a divergence can say which of its parts changed. */
+export interface MessageView {
+    role: string;
+    text?: string;
+    calls?: string;
+    result?: string;
+    callId?: string;
+}
+export interface CassetteTexts {
+    /** Capped normalized texts by part hash: instructions, tool descriptions, tool schemas, native tools. */
+    texts: Record<string, string>;
+    /** Tool sets by hash: tool name to the hashes of its description and schema. */
+    toolSets: Record<string, Record<string, {
+        description: string;
+        inputSchema: string;
+    }>>;
+    /** Message views by message hash. */
+    messages: Record<string, MessageView>;
+}
+export declare const emptyStore: () => CassetteTexts;
+export interface FingerprintMaterial {
+    fingerprint: string;
+    parts: FingerprintParts;
+    texts: Record<string, string>;
+    toolSet: Record<string, {
+        description: string;
+        inputSchema: string;
+    }>;
+    messages: Array<{
+        hash: string;
+        view: MessageView;
+    }>;
+}
+/** Fingerprints a provider request after normalizing it with `normalizer`. */
+export declare function computeFingerprint(request: StreamRequest, normalizer: Normalizer): FingerprintMaterial;
+/** Adds what `material` knows to `store`; returns the message views the store did not have yet. */
+export declare function absorb(store: CassetteTexts, material: FingerprintMaterial): Record<string, MessageView>;
+export interface FingerprintDiffEntry {
+    call: number;
+    field: string;
+    excerpt: {
+        before: string;
+        after: string;
+    };
+}
+export type FingerprintDiff = FingerprintDiffEntry[];
+/** `radius` characters around the first offset where the texts differ. */
+export declare function excerptAround(before: string, after: string): {
+    before: string;
+    after: string;
+};
+/**
+ * What differs between the recorded parts of call `call` and the request actually made, in a fixed
+ * order (instructions, messages, tools, scalars), at most 10 entries, excerpts redacted.
+ */
+export declare function diffFingerprints(call: number, recorded: FingerprintParts, store: CassetteTexts, actual: FingerprintMaterial): FingerprintDiff;

package/dist/eval/fingerprint.js

@@ -0,0 +1,186 @@
+/**
+ * The request fingerprint of the cassettes (specs/010 D10) and its structured divergence diff.
+ *
+ * What is hashed (after run-scoped normalization, see `normalize.ts`): `instructions`, every
+ * message, the tools reduced to `{name, description, inputSchema}` (sorted by name),
+ * `maxOutputTokens`, `model`, `nativeTools` and `reasoningEffort`. The spec's field list omitted
+ * the last two, but they change what the provider receives. Excluded on purpose: `signal` and
+ * `sessionId` (a per-run identity, not part of the request's meaning).
+ *
+ * The fingerprint is the hash of a PARTS record (one short hash per part), and the cassette stores
+ * those parts per call, so a divergence can be explained part by part. The texts needed to show
+ * what the recording had (instructions, tool descriptions and schemas, messages) are stored once,
+ * capped, in a `CassetteTexts` store.
+ */
+import { canonicalJson, hashCanonical, sha256Hex } from "./canonical.js";
+import { redactSecrets } from "./secrets.js";
+/** Characters of a stored text (message parts, tool descriptions and schemas). */
+export const TEXT_CAP = 4096;
+/** Instructions are stored longer: they are the largest single part and are stored once. */
+export const INSTRUCTIONS_CAP = 49_152;
+const EXCERPT_RADIUS = 120;
+const MAX_DIFF_ENTRIES = 10;
+/** 64 bits of sha256: enough to tell two versions of a part apart (the fingerprint is a full hash). */
+const shortHash = (text) => sha256Hex(text).slice(0, 16);
+const cap = (text, limit) => (text.length > limit ? text.slice(0, limit) : text);
+export const emptyStore = () => ({ texts: {}, toolSets: {}, messages: {} });
+function viewOf(message) {
+    switch (message.role) {
+        case "user":
+            return { role: "user", text: cap(message.text, TEXT_CAP) };
+        case "assistant":
+            return {
+                role: "assistant",
+                text: cap(message.text, TEXT_CAP),
+                calls: cap(canonicalJson(message.calls), TEXT_CAP),
+            };
+        default:
+            return {
+                role: "tool",
+                callId: message.callId,
+                result: cap(canonicalJson(message.result), TEXT_CAP),
+            };
+    }
+}
+/** Fingerprints a provider request after normalizing it with `normalizer`. */
+export function computeFingerprint(request, normalizer) {
+    const texts = {};
+    const keep = (text, limit = TEXT_CAP) => {
+        const hash = shortHash(text);
+        texts[hash] = cap(text, limit);
+        return hash;
+    };
+    const instructionsText = normalizer.text(request.instructions);
+    const instructions = keep(instructionsText, INSTRUCTIONS_CAP);
+    const messages = request.messages.map((raw) => {
+        const message = normalizer.value(raw);
+        return { hash: shortHash(canonicalJson(message)), view: viewOf(message) };
+    });
+    const toolSet = {};
+    for (const tool of request.tools) {
+        const description = normalizer.text(tool.description ?? "");
+        const schema = canonicalJson(normalizer.value(tool.inputSchema));
+        toolSet[tool.name] = { description: keep(description), inputSchema: keep(schema) };
+    }
+    const tools = shortHash(canonicalJson(toolSet));
+    let nativeTools = null;
+    if (request.nativeTools?.length)
+        nativeTools = keep(canonicalJson(normalizer.value(request.nativeTools)));
+    const parts = {
+        instructions,
+        messages: messages.map((m) => m.hash),
+        tools,
+        maxOutputTokens: request.maxOutputTokens,
+        model: request.model ?? null,
+        reasoningEffort: request.reasoningEffort ?? null,
+        nativeTools,
+    };
+    return { fingerprint: hashCanonical(parts), parts, texts, toolSet, messages };
+}
+/** Adds what `material` knows to `store`; returns the message views the store did not have yet. */
+export function absorb(store, material) {
+    Object.assign(store.texts, material.texts);
+    store.toolSets[material.parts.tools] = material.toolSet;
+    const added = {};
+    for (const { hash, view } of material.messages) {
+        if (!store.messages[hash]) {
+            store.messages[hash] = view;
+            added[hash] = view;
+        }
+    }
+    return added;
+}
+/** `radius` characters around the first offset where the texts differ. */
+export function excerptAround(before, after) {
+    const limit = Math.min(before.length, after.length);
+    let at = 0;
+    while (at < limit && before[at] === after[at])
+        at++;
+    const start = Math.max(0, at - EXCERPT_RADIUS);
+    const cut = (text) => {
+        const end = at + EXCERPT_RADIUS;
+        return `${start > 0 ? "…" : ""}${text.slice(start, end)}${text.length > end ? "…" : ""}`;
+    };
+    return { before: cut(before), after: cut(after) };
+}
+/**
+ * What differs between the recorded parts of call `call` and the request actually made, in a fixed
+ * order (instructions, messages, tools, scalars), at most 10 entries, excerpts redacted.
+ */
+export function diffFingerprints(call, recorded, store, actual) {
+    const entries = [];
+    const push = (field, before, after, whole = false) => {
+        entries.push({
+            call,
+            field,
+            excerpt: whole ? { before, after } : excerptAround(before, after),
+        });
+    };
+    const text = (hash, source) => hash == null ? "" : (source[hash] ?? "(text not stored)");
+    const now = actual.parts;
+    if (recorded.instructions !== now.instructions)
+        push("instructions", text(recorded.instructions, store.texts), text(now.instructions, actual.texts));
+    const shared = Math.min(recorded.messages.length, now.messages.length);
+    for (let i = 0; i < shared; i++) {
+        const was = recorded.messages[i];
+        const is = actual.messages[i];
+        if (was === undefined || is === undefined || was === is.hash)
+            continue;
+        const before = store.messages[was];
+        const view = is.view;
+        if (!before) {
+            push(`messages[${i}].${view.role}.other`, "(message not stored)", "(changed)", true);
+            continue;
+        }
+        if (before.role !== view.role) {
+            push(`messages[${i}].role`, before.role, view.role, true);
+            continue;
+        }
+        let named = false;
+        for (const key of ["text", "calls", "result", "callId"]) {
+            if ((before[key] ?? "") !== (view[key] ?? "")) {
+                push(`messages[${i}].${view.role}.${key}`, before[key] ?? "", view[key] ?? "");
+                named = true;
+            }
+        }
+        if (!named)
+            push(`messages[${i}].${view.role}.other`, "(a part beyond the stored prefix or outside text/calls/result changed)", "(see the request)", true);
+    }
+    if (recorded.messages.length !== now.messages.length)
+        push("messages.length", String(recorded.messages.length), String(now.messages.length), true);
+    if (recorded.tools !== now.tools) {
+        const was = store.toolSets[recorded.tools] ?? {};
+        const is = actual.toolSet;
+        const added = Object.keys(is).filter((name) => !(name in was));
+        const removed = Object.keys(was).filter((name) => !(name in is));
+        if (added.length > 0)
+            push("tools.added", "", added.join(", "), true);
+        if (removed.length > 0)
+            push("tools.removed", removed.join(", "), "", true);
+        for (const name of Object.keys(is)) {
+            const before = was[name];
+            const after = is[name];
+            if (!before || !after)
+                continue;
+            if (before.description !== after.description)
+                push(`tools[${name}].description`, text(before.description, store.texts), text(after.description, actual.texts));
+            if (before.inputSchema !== after.inputSchema)
+                push(`tools[${name}].inputSchema`, text(before.inputSchema, store.texts), text(after.inputSchema, actual.texts));
+        }
+    }
+    if (recorded.maxOutputTokens !== now.maxOutputTokens)
+        push("maxOutputTokens", String(recorded.maxOutputTokens), String(now.maxOutputTokens), true);
+    if (recorded.model !== now.model)
+        push("model", String(recorded.model), String(now.model), true);
+    if (recorded.reasoningEffort !== now.reasoningEffort)
+        push("reasoningEffort", String(recorded.reasoningEffort), String(now.reasoningEffort), true);
+    if (recorded.nativeTools !== now.nativeTools)
+        push("nativeTools", text(recorded.nativeTools, store.texts), text(now.nativeTools, actual.texts));
+    return entries.slice(0, MAX_DIFF_ENTRIES).map((entry) => ({
+        ...entry,
+        excerpt: {
+            before: redactSecrets(entry.excerpt.before),
+            after: redactSecrets(entry.excerpt.after),
+        },
+    }));
+}

package/dist/eval/normalize.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Run-scoped normalization of what a request carries (specs/010 D10), so the same logical request
+ * hashes the same in two fresh run directories, sessions and processes while a real regression
+ * (a relative path becoming absolute, an extra or missing id) still changes the hash.
+ *
+ * It rewrites string LEAVES only, never object keys, in three passes:
+ *  1. literal replacements computed by the engine at run start (run directory, workspace, slug,
+ *     workspace key, per-user scratch folder, home, tmp) and the known session/run ids, longest
+ *     literal first, each with a typed placeholder (`<WS>`, `<RUN>`, `<SESSION#1>`...);
+ *  2. generated ids found by pattern (`task_<ULID>`, `fx_<uuid>`, bare UUIDs...) become
+ *     `<id:kind#n>` where n is the order of first appearance of that exact id;
+ *  3. the suite's own `replayNormalize` rules (fixture output noise), versioned with the suite.
+ *
+ * Tool-call ids and token counts are NOT normalized: the cassette supplies them verbatim.
+ */
+export interface ReplayNormalizeRule {
+    pattern: string;
+    replace: string;
+}
+export interface NormalizerOptions {
+    literals?: Array<{
+        literal: string;
+        placeholder: string;
+    }>;
+    replay?: ReplayNormalizeRule[];
+}
+export declare class Normalizer {
+    private literals;
+    /** One alternation of every literal (longest first): a single pass never rescans a placeholder. */
+    private literalRegex;
+    private readonly sessions;
+    private readonly runs;
+    private readonly generated;
+    private readonly counters;
+    private readonly rules;
+    constructor(options?: NormalizerOptions);
+    private addLiteral;
+    /** `<SESSION#n>`, numbered in order of registration. */
+    registerSession(id: string): string;
+    registerRun(id: string): string;
+    /** The placeholder of a REGISTERED session id (child sessions are not registered). */
+    sessionLabel(id: string | undefined): string | undefined;
+    text(input: string): string;
+    private generatedId;
+    /** A copy of `value` with every string leaf normalized (keys untouched). */
+    value<T>(value: T): T;
+    private walk;
+}
+export interface RunLiteralsInput {
+    /** Real path of the run directory (the engine realpaths it). */
+    runDir: string;
+    /** The workspace copy (`<runDir>/ws`). */
+    workspace: string;
+    home: string;
+    osTmp: string;
+    /** `process.getuid()`; absent where the platform has none. */
+    uid?: number;
+    /** Defaults to the runtime's `workspaceKey(workspace)`. */
+    workspaceKey?: string;
+}
+/**
+ * The literal replacements of one run: everything whose value depends on where or as whom the run
+ * happens. Typed placeholders keep different kinds of path apart (see the module comment).
+ */
+export declare function runLiterals(input: RunLiteralsInput): Array<{
+    literal: string;
+    placeholder: string;
+}>;

package/dist/eval/normalize.js

@@ -0,0 +1,138 @@
+/**
+ * Run-scoped normalization of what a request carries (specs/010 D10), so the same logical request
+ * hashes the same in two fresh run directories, sessions and processes while a real regression
+ * (a relative path becoming absolute, an extra or missing id) still changes the hash.
+ *
+ * It rewrites string LEAVES only, never object keys, in three passes:
+ *  1. literal replacements computed by the engine at run start (run directory, workspace, slug,
+ *     workspace key, per-user scratch folder, home, tmp) and the known session/run ids, longest
+ *     literal first, each with a typed placeholder (`<WS>`, `<RUN>`, `<SESSION#1>`...);
+ *  2. generated ids found by pattern (`task_<ULID>`, `fx_<uuid>`, bare UUIDs...) become
+ *     `<id:kind#n>` where n is the order of first appearance of that exact id;
+ *  3. the suite's own `replayNormalize` rules (fixture output noise), versioned with the suite.
+ *
+ * Tool-call ids and token counts are NOT normalized: the cassette supplies them verbatim.
+ */
+import { workspaceSlug } from "../forge/session-path.js";
+import { workspaceKey as keyOf } from "../runtime/paths.js";
+const ULID_PREFIXED = "[a-z][a-z0-9]{1,9}_[0-9A-HJKMNP-TV-Z]{26}";
+const UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+const GENERATED = new RegExp(`\\b(?:${ULID_PREFIXED}|fx_${UUID}|${UUID})\\b`, "gi");
+/** Smallest literal worth replacing: a one- or two-character literal would corrupt unrelated text. */
+const MIN_LITERAL = 3;
+export class Normalizer {
+    literals = [];
+    /** One alternation of every literal (longest first): a single pass never rescans a placeholder. */
+    literalRegex;
+    sessions = new Map();
+    runs = new Map();
+    generated = new Map();
+    counters = new Map();
+    rules;
+    constructor(options = {}) {
+        for (const entry of options.literals ?? [])
+            this.addLiteral(entry.literal, entry.placeholder);
+        this.rules = (options.replay ?? []).map((rule, index) => {
+            try {
+                return { regex: new RegExp(rule.pattern, "g"), replace: rule.replace };
+            }
+            catch (error) {
+                throw new Error(`replayNormalize rule ${index} has an invalid pattern "${rule.pattern}": ${error instanceof Error ? error.message : String(error)}`);
+            }
+        });
+    }
+    addLiteral(literal, placeholder) {
+        if (literal.length < MIN_LITERAL)
+            return;
+        if (this.literals.some((l) => l.literal === literal))
+            return;
+        this.literals.push({ literal, placeholder });
+        this.literals.sort((a, b) => b.literal.length - a.literal.length);
+        this.literalRegex = new RegExp(this.literals.map((l) => l.literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|"), "g");
+    }
+    /** `<SESSION#n>`, numbered in order of registration. */
+    registerSession(id) {
+        let placeholder = this.sessions.get(id);
+        if (!placeholder) {
+            placeholder = `<SESSION#${this.sessions.size + 1}>`;
+            this.sessions.set(id, placeholder);
+            this.addLiteral(id, placeholder);
+        }
+        return placeholder;
+    }
+    registerRun(id) {
+        let placeholder = this.runs.get(id);
+        if (!placeholder) {
+            placeholder = `<RUN#${this.runs.size + 1}>`;
+            this.runs.set(id, placeholder);
+            this.addLiteral(id, placeholder);
+        }
+        return placeholder;
+    }
+    /** The placeholder of a REGISTERED session id (child sessions are not registered). */
+    sessionLabel(id) {
+        return id === undefined ? undefined : this.sessions.get(id);
+    }
+    text(input) {
+        let out = input;
+        if (this.literalRegex) {
+            const byLiteral = new Map(this.literals.map((l) => [l.literal, l.placeholder]));
+            out = out.replace(this.literalRegex, (match) => byLiteral.get(match) ?? match);
+        }
+        out = out.replace(GENERATED, (match) => this.generatedId(match));
+        for (const { regex, replace } of this.rules)
+            out = out.replace(regex, replace);
+        return out;
+    }
+    generatedId(match) {
+        const known = this.generated.get(match);
+        if (known)
+            return known;
+        const kind = match.startsWith("fx_")
+            ? "fx"
+            : match.includes("-") && !match.includes("_")
+                ? "uuid"
+                : match.slice(0, match.indexOf("_"));
+        const n = (this.counters.get(kind) ?? 0) + 1;
+        this.counters.set(kind, n);
+        const placeholder = `<id:${kind}#${n}>`;
+        this.generated.set(match, placeholder);
+        return placeholder;
+    }
+    /** A copy of `value` with every string leaf normalized (keys untouched). */
+    value(value) {
+        return this.walk(value);
+    }
+    walk(value) {
+        if (typeof value === "string")
+            return this.text(value);
+        if (Array.isArray(value))
+            return value.map((item) => this.walk(item));
+        if (value && typeof value === "object") {
+            const out = {};
+            for (const [key, member] of Object.entries(value))
+                out[key] = this.walk(member);
+            return out;
+        }
+        return value;
+    }
+}
+/**
+ * The literal replacements of one run: everything whose value depends on where or as whom the run
+ * happens. Typed placeholders keep different kinds of path apart (see the module comment).
+ */
+export function runLiterals(input) {
+    const key = input.workspaceKey ?? keyOf(input.workspace);
+    const literals = [
+        { literal: input.workspace, placeholder: "<WS>" },
+        { literal: input.runDir, placeholder: "<RUN>" },
+        { literal: workspaceSlug(input.workspace, key), placeholder: "<WS_SLUG>" },
+        { literal: key, placeholder: "<WS_KEY>" },
+        { literal: key.slice(0, 8), placeholder: "<WS_KEY8>" },
+        { literal: input.home, placeholder: "<HOME>" },
+        { literal: input.osTmp, placeholder: "<TMP>" },
+    ];
+    if (input.uid !== undefined)
+        literals.push({ literal: `alisio-${input.uid}`, placeholder: "alisio-<UID>" });
+    return literals;
+}

package/dist/eval/paths.d.ts

@@ -0,0 +1,11 @@
+/** Path confinement shared by the suite loader and the verifiers (specs/010 D1, D4). */
+export declare class EvalPathError extends Error {
+    constructor(message: string);
+}
+/** Reason a path string is not a plain relative path inside a directory, or undefined if it is. */
+export declare function unsafeRelativeReason(path: string): string | undefined;
+/**
+ * Resolves `rel` under `root` and proves, symlinks included, that the result stays inside `root`.
+ * The target does not have to exist. Throws `EvalPathError` otherwise.
+ */
+export declare function resolveInside(root: string, rel: string, what?: string): string;

package/dist/eval/paths.js

@@ -0,0 +1,50 @@
+/** Path confinement shared by the suite loader and the verifiers (specs/010 D1, D4). */
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+export class EvalPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EvalPathError";
+    }
+}
+/** Reason a path string is not a plain relative path inside a directory, or undefined if it is. */
+export function unsafeRelativeReason(path) {
+    if (path.length === 0)
+        return "is empty";
+    if (path.includes("\0"))
+        return "contains a NUL byte";
+    if (isAbsolute(path) || /^[a-zA-Z]:/.test(path) || path.startsWith("\\\\"))
+        return "must be relative, not absolute";
+    if (path.split(/[\\/]+/).includes(".."))
+        return "must not contain '..' segments";
+    return undefined;
+}
+/** True when `child` is `parent` or lies below it. */
+function within(parent, child) {
+    const rel = relative(parent, child);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/** Real path of the nearest existing ancestor of `path` (symlinks resolved). */
+function realAncestor(path) {
+    let current = path;
+    while (!existsSync(current)) {
+        const parent = dirname(current);
+        if (parent === current)
+            return current;
+        current = parent;
+    }
+    return realpathSync(current);
+}
+/**
+ * Resolves `rel` under `root` and proves, symlinks included, that the result stays inside `root`.
+ * The target does not have to exist. Throws `EvalPathError` otherwise.
+ */
+export function resolveInside(root, rel, what = "path") {
+    const reason = unsafeRelativeReason(rel);
+    if (reason)
+        throw new EvalPathError(`${what} "${rel}" ${reason}.`);
+    const absolute = resolve(root, rel);
+    if (!within(realpathSync(root), realAncestor(absolute)))
+        throw new EvalPathError(`${what} "${rel}" resolves outside the directory (symlink escape).`);
+    return absolute;
+}