@sema-agent/core 7.17.6 → 7.18.0

package/dist/tools/artifact/conformance.js

@@ -0,0 +1,349 @@
+import { randomUUID } from "node:crypto";
+import { readArtifactHostCapabilities, } from "../../core/artifact-host.js";
+class Violation extends Error {
+}
+const fail = (detail) => {
+    throw new Violation(detail);
+};
+const check = (cond, detail) => {
+    if (!cond)
+        fail(detail);
+};
+const enc = new TextEncoder();
+const FOREIGN_URL = "https://conformance.invalid/artifact/none";
+const HTML_MEDIA = "text/html";
+const ctxOf = (h, attemptId) => ({ taskId: `conformance-${h.runId}`, runId: h.runId, attemptId: attemptId ?? `${h.runId}-${++h.seq}` });
+const fixtureBudget = (h) => Math.max(1, Math.min(h.caps.maxFileBytes, Math.floor(h.caps.maxTotalBytes / 2)));
+const fit = (h, text) => enc.encode(text).slice(0, fixtureBudget(h));
+const el = (tag, inner) => `<${tag}>${inner}</${tag}>`;
+const page = (h, n, extraFiles = []) => [{ path: "index.html", content: fit(h, `${n}${el("title", `C${n}`)}${el("p", String(n))}`), mediaType: HTML_MEDIA }, ...extraFiles];
+const script = (h, n) => ({ path: "assets/app.js", content: fit(h, `${n};console.log(${n})`).slice(0, Math.floor(h.caps.maxTotalBytes / 2)), mediaType: "text/javascript" });
+const req = (files, over = {}) => ({ files, publishContext: "plain", ...over });
+const same = (a, b) => a.byteLength === b.byteLength && a.every((x, i) => x === b[i]);
+async function publish(h, r, attemptId) {
+    try {
+        return await h.host.publish(r, ctxOf(h, attemptId));
+    }
+    catch (err) {
+        return fail(`publish threw: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+async function publishOk(h, r, what, attemptId) {
+    const out = await publish(h, r, attemptId);
+    if (!out.ok)
+        return fail(`${what}: expected ok, got ${out.code}${"message" in out ? ` (${out.message})` : ""}`);
+    check(typeof out.ref.url === "string" && out.ref.url.length > 0 && typeof out.ref.slug === "string" && typeof out.ref.version === "string", `${what}: the ref must carry url, slug and version strings`);
+    return out.ref;
+}
+async function listMine(h) {
+    const out = await h.host.list({ scope: "mine", limit: 1000 }, ctxOf(h));
+    if (!out.ok)
+        return fail(`list mine refused: ${out.message}`);
+    return out.rows;
+}
+const vectorTable = [];
+const define = (v, run) => void vectorTable.push({ ...v, run });
+define({ id: "publish.fresh_mints_distinct_pages", describe: "two publishes without `url` mint two pages with distinct urls (fresh never touches an existing page)", requiresActions: ["publish"] }, async (h) => {
+    const a = await publishOk(h, req(page(h, 1)), "first fresh");
+    const b = await publishOk(h, req(page(h, 2)), "second fresh");
+    check(a.url !== b.url, `both fresh publishes answered the same url ${a.url}`);
+    return `two pages: ${a.url}, ${b.url}`;
+});
+define({ id: "publish.update_by_url_advances_same_page", describe: "a publish with `url` and the current `baseVersion` advances that page's version on the same url and slug (update never mints a page); where read / read_file are declared, the NEW bytes are what reads back", requiresActions: ["publish"] }, async (h) => {
+    const a = await publishOk(h, req(page(h, 1)), "fresh");
+    const next = page(h, 2);
+    const b = await publishOk(h, req(next, { url: a.url, baseVersion: a.version }), "update");
+    check(b.url === a.url && b.slug === a.slug, `the update answered url ${b.url} / slug ${b.slug}, expected ${a.url} / ${a.slug}`);
+    check(b.version !== a.version, `the update left the version at ${a.version}`);
+    const persisted = [];
+    if (h.caps.actions.includes("read")) {
+        const r = await h.host.read({ url: a.url }, ctxOf(h));
+        check(r.ok && r.content === new TextDecoder().decode(next[0].content) && r.ref.version === b.version, "read after the update returns the PREVIOUS content or version: the update was acknowledged but not persisted");
+        persisted.push("read");
+    }
+    if (h.caps.actions.includes("read_file")) {
+        const f = await h.host.readFile({ url: a.url, path: next[0].path }, ctxOf(h));
+        check(f.ok && same(f.file.content, next[0].content), "read_file after the update returns the PREVIOUS bytes: the update was acknowledged but not persisted");
+        persisted.push("read_file");
+    }
+    return `version ${a.version} → ${b.version} on ${a.url}${persisted.length > 0 ? `; new bytes read back via ${persisted.join(", ")}` : ""}`;
+});
+define({ id: "publish.no_base_version_is_last_write_wins", describe: "`url` present and `baseVersion` absent ⇒ the write applies (last-write-wins is a defined behaviour, never a conflict)", requiresActions: ["publish"] }, async (h) => {
+    const a = await publishOk(h, req(page(h, 1)), "fresh");
+    const b = await publishOk(h, req(page(h, 2), { url: a.url }), "first update without baseVersion");
+    const c = await publishOk(h, req(page(h, 3), { url: a.url }), "second update without baseVersion");
+    check(b.version !== a.version && c.version !== b.version, `versions did not advance: ${a.version}, ${b.version}, ${c.version}`);
+    return `three versions on ${a.url}`;
+});
+define({ id: "publish.stale_base_conflicts", describe: "a stale `baseVersion` ⇒ `conflict` carrying the CURRENT version and either a full snapshot or the explicit `\"reread\"` word; nothing is written", requiresActions: ["publish"] }, async (h) => {
+    const a = await publishOk(h, req(page(h, 1)), "fresh");
+    const b = await publishOk(h, req(page(h, 2), { url: a.url, baseVersion: a.version }), "update to v2");
+    const out = await publish(h, req(page(h, 3), { url: a.url, baseVersion: a.version }));
+    check(!out.ok && out.code === "conflict", `a stale base answered ${out.ok ? "ok" : out.code}, expected conflict`);
+    if (out.ok || out.code !== "conflict")
+        return "";
+    check(out.currentVersion === b.version, `conflict names currentVersion ${out.currentVersion}, expected ${b.version}`);
+    check(out.current === "reread" || (typeof out.current === "object" && Array.isArray(out.current.files)), "conflict.current must be a snapshot object or the string \"reread\"");
+    const after = await publishOk(h, req(page(h, 4), { url: a.url, baseVersion: b.version }), "update on the true current version after the conflict");
+    check(after.version !== b.version, "the conflict wrote a version: the base the host itself named was stale one call later");
+    return `conflict at ${b.version}, current: ${out.current === "reread" ? "reread" : "snapshot"}`;
+});
+for (const action of ["read", "read_file"]) {
+    define({ id: `publish.conflict_preserves_${action}`, describe: `a stale-base rejection leaves readable bytes unchanged through ${action}, even if the host preserves the version number and returns a correct pre-write snapshot`, requiresActions: ["publish", action] }, async (h) => {
+        const a = await publishOk(h, req(page(h, 1)), "fresh");
+        const b = await publishOk(h, req(page(h, 2), { url: a.url, baseVersion: a.version }), "update");
+        const observe = async () => {
+            if (action === "read") {
+                const out = await h.host.read({ url: a.url }, ctxOf(h));
+                if (!out.ok)
+                    return fail(`read refused: ${out.code}`);
+                return JSON.stringify([out.ref.url, out.ref.slug, out.ref.version, out.ref.title, out.content, out.isolatedSummary]);
+            }
+            const out = await h.host.readFile({ url: a.url, path: "index.html" }, ctxOf(h));
+            if (!out.ok)
+                return fail(`read_file refused: ${out.code}`);
+            return JSON.stringify([out.file.path, out.file.mediaType, Array.from(out.file.content)]);
+        };
+        const before = await observe();
+        const rejected = await publish(h, req(page(h, 3), { url: a.url, baseVersion: a.version }));
+        check(!rejected.ok && rejected.code === "conflict" && rejected.currentVersion === b.version, "a stale base must conflict at the current version");
+        check(await observe() === before, `${action} changed after a rejected publish`);
+        return `${action} unchanged after conflict`;
+    });
+}
+define({ id: "publish.conflict_snapshot_is_complete", describe: "when the conflict hands back a snapshot it is the WHOLE current version: every published path with its bytes and the media type sent, plus the metadata", requiresActions: ["publish"] }, async (h) => {
+    const extra = h.caps.multiFile ? [script(h, 1)] : [];
+    const a = await publishOk(h, req(page(h, 1, extra), { title: "Conformance title" }), "fresh");
+    const current = page(h, 2, extra);
+    const b = await publishOk(h, req(current, { url: a.url, baseVersion: a.version, title: "Conformance title" }), "update to v2");
+    const out = await publish(h, req(page(h, 3, extra), { url: a.url, baseVersion: a.version }));
+    check(!out.ok && out.code === "conflict", "a stale base must conflict");
+    if (out.ok || out.code !== "conflict")
+        return "";
+    if (out.current === "reread")
+        return `host answers "reread" (explicit; snapshot completeness not claimed) at ${b.version}`;
+    for (const f of current) {
+        const got = out.current.files.find((x) => x.path === f.path);
+        check(got !== undefined, `snapshot lacks published path ${f.path}`);
+        check(got !== undefined && same(got.content, f.content), `snapshot bytes differ for ${f.path}`);
+        check(got !== undefined && got.mediaType === f.mediaType, `snapshot media type for ${f.path} is ${got?.mediaType}, expected ${f.mediaType}`);
+    }
+    check(out.current.files.length === current.length, `snapshot carries ${out.current.files.length} files, the current version has ${current.length}`);
+    check(out.current.title === "Conformance title", `snapshot title is ${out.current.title}, expected the current title`);
+    return `snapshot complete: ${current.length} file(s) + metadata`;
+});
+define({ id: "publish.force_overrides_stale_base", describe: "`force: true` over a stale `baseVersion` applies (a plain published version is overwritable)", requiresActions: ["publish"] }, async (h) => {
+    const a = await publishOk(h, req(page(h, 1)), "fresh");
+    const b = await publishOk(h, req(page(h, 2), { url: a.url, baseVersion: a.version }), "update to v2");
+    const forced = await publishOk(h, req(page(h, 3), { url: a.url, baseVersion: a.version, force: true }), "forced publish over a stale base");
+    check(forced.version !== b.version, "force answered ok but the version did not advance");
+    return `forced ${b.version} → ${forced.version}`;
+});
+define({ id: "publish.force_refused_over_page_saved_version", describe: "`force: true` over a version saved from inside the page ⇒ `force_refused` (the one version force must not discard)", requiresActions: ["publish"], requiresHook: "pageSavedVersion" }, async (h) => {
+    const a = await publishOk(h, req(page(h, 1)), "fresh");
+    await h.hooks.pageSavedVersion(a);
+    const out = await publish(h, req(page(h, 2), { url: a.url, baseVersion: a.version, force: true }));
+    check(!out.ok && out.code === "force_refused", `force over a page-saved version answered ${out.ok ? "ok" : out.code}, expected force_refused`);
+    return "force_refused";
+});
+define({ id: "publish.attempt_replay_is_idempotent", describe: "the same `attemptId` replays the first outcome: a fresh publish never mints a second page, an update never advances twice", requiresActions: ["publish"] }, async (h) => {
+    const before = h.caps.actions.includes("list") ? (await listMine(h)).length : undefined;
+    const key = `${h.runId}-replay-fresh`;
+    const a = await publishOk(h, req(page(h, 1), { title: "first" }), "fresh under key", key);
+    const again = await publishOk(h, req(page(h, 9), { title: "changed" }), "replay under the same key", key);
+    check(again.url === a.url && again.version === a.version, `the replay answered ${again.url} @ ${again.version}, expected ${a.url} @ ${a.version}`);
+    if (before !== undefined) {
+        const after = (await listMine(h)).length;
+        check(after === before + 1, `two fresh calls under one key left ${after - before} new page(s) in the listing, expected 1`);
+    }
+    const key2 = `${h.runId}-replay-update`;
+    const u1 = await publishOk(h, req(page(h, 2), { url: a.url, baseVersion: a.version }), "update under key2", key2);
+    const u2 = await publishOk(h, req(page(h, 3), { url: a.url, baseVersion: a.version }), "replayed update under key2", key2);
+    check(u2.version === u1.version, `the replayed update answered version ${u2.version}, expected ${u1.version}`);
+    await publishOk(h, req(page(h, 4), { url: a.url, baseVersion: u1.version }), "an update on the replayed version (proves the version did not advance twice)");
+    return `fresh and update each replayed once on ${a.url}`;
+});
+define({ id: "publish.attempt_replay_of_refusal", describe: "a typed refusal is replayed under the same `attemptId` too: a later call under that key with a request that would otherwise SUCCEED still gets the first refusal (the host does not re-decide)", requiresActions: ["publish"] }, async (h) => {
+    const key = `${h.runId}-replay-refusal`;
+    const a = await publish(h, req(page(h, 1), { url: FOREIGN_URL }), key);
+    check(!a.ok && a.code === "url_foreign", `a foreign url answered ${a.ok ? "ok" : a.code}, expected url_foreign`);
+    const b = await publish(h, req(page(h, 2)), key);
+    check(!b.ok && b.code === "url_foreign", `the replay re-decided: a fresh request under the refused key answered ${b.ok ? "ok" : b.code}, expected the replayed url_foreign`);
+    return "the refusal replayed over a request that would otherwise succeed";
+});
+define({ id: "publish.url_foreign_refused", describe: "a `url` this host never minted ⇒ `url_foreign` (a typed refusal, never a throw, never a page)", requiresActions: ["publish"] }, async (h) => {
+    const out = await publish(h, req(page(h, 1), { url: FOREIGN_URL }));
+    check(!out.ok && out.code === "url_foreign", `a foreign url answered ${out.ok ? "ok" : out.code}, expected url_foreign`);
+    return "url_foreign";
+});
+define({ id: "publish.atomic_under_precommit_fault", describe: "a failure injected BEFORE the commit point leaves no observable change: no phantom version (the same base still applies) and, when list is declared, no new page", requiresActions: ["publish"], requiresHook: "precommitFault" }, async (h) => {
+    const a = await publishOk(h, req(page(h, 1)), "fresh");
+    const before = h.caps.actions.includes("list") ? (await listMine(h)).length : undefined;
+    const contentBefore = h.caps.actions.includes("read") ? await h.host.read({ url: a.url }, ctxOf(h)) : undefined;
+    await h.hooks.precommitFault.arm();
+    let faulted;
+    try {
+        const out = await h.host.publish(req(page(h, 2), { url: a.url, baseVersion: a.version }), ctxOf(h));
+        faulted = out.ok ? "ok" : "typed";
+    }
+    catch {
+        faulted = "threw";
+    }
+    finally {
+        await h.hooks.precommitFault.disarm();
+    }
+    check(faulted !== "ok", "the armed fault did not fail the publish — the hook is not reaching the host's write path");
+    if (contentBefore !== undefined) {
+        const contentAfter = await h.host.read({ url: a.url }, ctxOf(h));
+        check(contentBefore.ok && contentAfter.ok && contentAfter.content === contentBefore.content && contentAfter.ref.version === contentBefore.ref.version, "the faulted publish changed the readable content or version before any commit");
+    }
+    const after = await publishOk(h, req(page(h, 3), { url: a.url, baseVersion: a.version }), "update on the pre-fault base");
+    check(after.version !== a.version, "the update after the fault did not advance");
+    if (before !== undefined)
+        check((await listMine(h)).length === before, "the faulted publish left a new page in the listing");
+    return `fault ${faulted}; base ${a.version} still applied → ${after.version}`;
+});
+define({ id: "publish.byte_limits_enforced", describe: "one file over `maxFileBytes` ⇒ `payload_too_large`; with multiFile, files each within the per-file limit but summing past `maxTotalBytes` ⇒ `payload_too_large`", requiresActions: ["publish"] }, async (h) => {
+    const big = await publish(h, req([{ path: "index.html", content: new Uint8Array(h.caps.maxFileBytes + 1), mediaType: HTML_MEDIA }]));
+    check(!big.ok && big.code === "payload_too_large", `a file of maxFileBytes+1 answered ${big.ok ? "ok" : big.code}`);
+    if (!h.caps.multiFile)
+        return "per-file limit enforced (single-file host)";
+    const files = [];
+    let left = h.caps.maxTotalBytes + 1;
+    for (let i = 0; left > 0; i++) {
+        const size = Math.min(left, h.caps.maxFileBytes);
+        files.push({ path: i === 0 ? "index.html" : `part${i}.bin`, content: new Uint8Array(size), mediaType: i === 0 ? HTML_MEDIA : "application/octet-stream" });
+        left -= size;
+    }
+    const total = await publish(h, req(files));
+    check(!total.ok && total.code === "payload_too_large", `${files.length} files summing to maxTotalBytes+1 answered ${total.ok ? "ok" : total.code}`);
+    return `per-file and total limits enforced (${files.length} files)`;
+});
+define({ id: "publish.at_limit_accepted", describe: "a file of exactly `maxFileBytes` (within the total) is accepted; with multiFile, files summing to exactly `maxTotalBytes` are accepted", requiresActions: ["publish"], requiresLargePayloads: true }, async (h) => {
+    const fileSize = Math.min(h.caps.maxFileBytes, h.caps.maxTotalBytes);
+    await publishOk(h, req([{ path: "index.html", content: new Uint8Array(fileSize), mediaType: HTML_MEDIA }]), `a file of exactly ${fileSize} bytes`);
+    if (!h.caps.multiFile)
+        return `${fileSize} bytes accepted`;
+    const files = [];
+    let left = h.caps.maxTotalBytes;
+    for (let i = 0; left > 0; i++) {
+        const size = Math.min(left, h.caps.maxFileBytes);
+        files.push({ path: i === 0 ? "index.html" : `part${i}.bin`, content: new Uint8Array(size), mediaType: i === 0 ? HTML_MEDIA : "application/octet-stream" });
+        left -= size;
+    }
+    await publishOk(h, req(files), `${files.length} files summing to exactly maxTotalBytes`);
+    return `at-limit file and at-limit total accepted`;
+});
+define({ id: "list.scope_words", describe: "`mine` lists only the caller's pages (including the ones just published), `shared` only others', `all` both; `truncated` is a boolean on every answer", requiresActions: ["publish", "list"] }, async (h) => {
+    const a = await publishOk(h, req(page(h, 1)), "fresh");
+    const b = await publishOk(h, req(page(h, 2)), "fresh");
+    const mine = await h.host.list({ scope: "mine", limit: 1000 }, ctxOf(h));
+    const shared = await h.host.list({ scope: "shared", limit: 1000 }, ctxOf(h));
+    const all = await h.host.list({ scope: "all", limit: 1000 }, ctxOf(h));
+    for (const [scope, out] of [["mine", mine], ["shared", shared], ["all", all]]) {
+        check(out.ok, `list ${scope} refused`);
+        check(out.ok && typeof out.truncated === "boolean", `list ${scope}: truncated is not a boolean`);
+    }
+    if (!mine.ok || !shared.ok || !all.ok)
+        return "";
+    check(mine.rows.every((r) => r.owner === "mine"), "a `mine` row is not owned by the caller");
+    check(shared.rows.every((r) => r.owner === "shared"), "a `shared` row is owned by the caller");
+    check([a.url, b.url].every((u) => mine.rows.some((r) => r.url === u)), "the pages just published are missing from `mine`");
+    check([a.url, b.url].every((u) => all.rows.some((r) => r.url === u)), "the pages just published are missing from `all`");
+    check(all.rows.length >= mine.rows.length, "`all` lists fewer rows than `mine`");
+    return `mine ${mine.rows.length}, shared ${shared.rows.length}, all ${all.rows.length}`;
+});
+define({ id: "list.limit_and_truncated", describe: "`limit` bounds the rows and `truncated` says so when more exist", requiresActions: ["publish", "list"] }, async (h) => {
+    await publishOk(h, req(page(h, 1)), "fresh");
+    await publishOk(h, req(page(h, 2)), "fresh");
+    const out = await h.host.list({ scope: "mine", limit: 1 }, ctxOf(h));
+    check(out.ok, "list refused");
+    if (!out.ok)
+        return "";
+    check(out.rows.length <= 1, `limit 1 answered ${out.rows.length} rows`);
+    check(out.truncated === true, "two pages exist but `truncated` is not true at limit 1");
+    return "limit honoured, truncated true";
+});
+define({ id: "read.own_page_full_content", describe: "`read` of the caller's own single-file page returns its full text with `isolatedSummary: false` and the page's ref", requiresActions: ["publish", "read"] }, async (h) => {
+    const files = page(h, 1);
+    const a = await publishOk(h, req(files), "fresh");
+    const out = await h.host.read({ url: a.url }, ctxOf(h));
+    check(out.ok, `read refused: ${out.ok ? "" : out.code}`);
+    if (!out.ok)
+        return "";
+    check(out.isolatedSummary === false, "the caller's own page came back as an isolated summary");
+    check(out.content === new TextDecoder().decode(files[0].content), "the content differs from the published text");
+    check(out.ref.url === a.url, `read.ref.url is ${out.ref.url}, expected ${a.url}`);
+    return "full text, own page";
+});
+define({ id: "read.unknown_url_typed", describe: "`read` of a url this host never minted ⇒ a typed `not_found` / `forbidden`, never a throw", requiresActions: ["read"] }, async (h) => {
+    let out;
+    try {
+        out = await h.host.read({ url: FOREIGN_URL }, ctxOf(h));
+    }
+    catch (err) {
+        return fail(`read threw: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    check(!out.ok && (out.code === "not_found" || out.code === "forbidden"), `an unknown url answered ${out.ok ? "ok" : out.code}`);
+    return out.ok ? "" : out.code;
+});
+define({ id: "files.list_and_read_file", describe: "`list_files` names every published path with its byte count; `read_file` returns each file's bytes and media type; an unknown path ⇒ `not_found`", requiresActions: ["publish", "list_files", "read_file"] }, async (h) => {
+    const files = page(h, 1, h.caps.multiFile ? [script(h, 2)] : []);
+    const a = await publishOk(h, req(files), "fresh");
+    const listed = await h.host.listFiles({ url: a.url }, ctxOf(h));
+    check(listed.ok, `list_files refused: ${listed.ok ? "" : listed.code}`);
+    if (!listed.ok)
+        return "";
+    for (const f of files) {
+        const e = listed.entries.find((x) => x.path === f.path);
+        check(e !== undefined && e.bytes === f.content.byteLength, `list_files lacks ${f.path} at ${f.content.byteLength} bytes`);
+        const got = await h.host.readFile({ url: a.url, path: f.path }, ctxOf(h));
+        check(got.ok, `read_file ${f.path} refused: ${got.ok ? "" : got.code}`);
+        if (!got.ok)
+            return "";
+        check(same(got.file.content, f.content) && got.file.mediaType === f.mediaType, `read_file ${f.path}: bytes or media type differ`);
+    }
+    const missing = await h.host.readFile({ url: a.url, path: "no/such/file.txt" }, ctxOf(h));
+    check(!missing.ok && missing.code === "not_found", `an unknown path answered ${missing.ok ? "ok" : missing.code}`);
+    return `${files.length} file(s) listed and read`;
+});
+export const ARTIFACT_CONFORMANCE_VECTORS = vectorTable.map(({ run: _run, ...v }) => Object.freeze(v));
+const applies = (v, caps) => v.requiresActions.every((a) => caps.actions.includes(a)) && (v.requiresMultiFile !== true || caps.multiFile);
+export function artifactConformanceVectors(host) {
+    const verdict = readArtifactHostCapabilities(host);
+    if (!verdict.ok)
+        throw new Error(`artifactConformanceVectors: the host's declaration is invalid — ${verdict.problem}`);
+    return ARTIFACT_CONFORMANCE_VECTORS.filter((v) => applies(v, verdict.capabilities));
+}
+export async function runArtifactConformance(host, opts = {}) {
+    const verdict = readArtifactHostCapabilities(host);
+    if (!verdict.ok)
+        throw new Error(`runArtifactConformance: the host's declaration is invalid — ${verdict.problem}`);
+    const h = { host, caps: verdict.capabilities, runId: opts.runId ?? randomUUID(), hooks: opts.hooks ?? {}, largePayloads: opts.largePayloads === true, seq: 0 };
+    host.onMount?.(h.runId);
+    const results = [];
+    for (const v of vectorTable) {
+        if (!applies(v, h.caps)) {
+            results.push({ id: v.id, status: "not_applicable", detail: `requires ${[...v.requiresActions, ...(v.requiresMultiFile ? ["multiFile"] : [])].join(" + ")}; not declared` });
+            continue;
+        }
+        if (v.requiresHook !== undefined && h.hooks[v.requiresHook] === undefined) {
+            results.push({ id: v.id, status: "skipped", detail: `hook ${v.requiresHook} not supplied` });
+            continue;
+        }
+        if (v.requiresLargePayloads === true && !h.largePayloads) {
+            results.push({ id: v.id, status: "skipped", detail: "largePayloads not enabled" });
+            continue;
+        }
+        let row;
+        try {
+            row = { id: v.id, status: "pass", detail: await v.run(h) };
+        }
+        catch (err) {
+            row = { id: v.id, status: "fail", detail: err instanceof Violation ? err.message : `threw: ${err instanceof Error ? err.message : String(err)}` };
+        }
+        results.push(row);
+    }
+    const count = (s) => results.filter((r) => r.status === s).length;
+    return { capabilities: h.caps, runId: h.runId, results, passed: count("pass"), failed: count("fail"), notApplicable: count("not_applicable"), skipped: count("skipped") };
+}

package/dist/tools/artifact/local-stub.js

@@ -86,7 +86,7 @@ export class LocalArtifactStub {
         this.dir = resolve(opts.dir);
     }
     capabilities() {
-        return { plane: "local-stub", actions: ["publish"], defaultVisibility: "private", maxFileBytes: LOCAL_STUB_MAX_FILE_BYTES, maxTotalBytes: LOCAL_STUB_MAX_TOTAL_BYTES, multiFile: false, storageDir: this.dir };
+        return { plane: "local-stub", actions: ["publish"], commit: "throw_means_uncommitted", defaultVisibility: "private", maxFileBytes: LOCAL_STUB_MAX_FILE_BYTES, maxTotalBytes: LOCAL_STUB_MAX_TOTAL_BYTES, multiFile: false, storageDir: this.dir };
     }
     onMount(runId) {
         this.#mint.set(runId, new Set());

package/dist/tools/artifact/reject-breaker.d.ts

@@ -0,0 +1,28 @@
+import type { ArtifactResultCode } from "../../core/artifact-host.js";
+/** Rejections of one key/reason/message before the banner rides (upstream `E = 3`). */
+export declare const ARTIFACT_REJECT_BREAKER_THRESHOLD = 3;
+/** Each key component is read at most this long (upstream `I = 1024`). */
+export declare const ARTIFACT_REJECT_KEY_COMPONENT_MAX = 1024;
+/** The banner for a rejection the model can act on (fix the arguments, or stop and tell the user). */
+export declare const ARTIFACT_REJECT_BANNER_RETRYABLE = "IMPORTANT: Artifact calls for this target have now been rejected 3 or more times in this session for the same reason. Do not send the same call again: either make the specific change the error describes, or stop calling Artifact for this target and tell the user what is failing and why.";
+/** The banner for a host-authority refusal that no argument change can get past. */
+export declare const ARTIFACT_REJECT_BANNER_REFUSAL = "IMPORTANT: Artifact calls for this target have now been rejected 3 or more times in this session for the same reason. Stop calling Artifact for this target and tell the user the artifact could not be published and why \u2014 do not try to work around this refusal.";
+/** The result codes whose banner is the refusal form: the host's authority said no, and "work around it" is not an option. */
+export declare const ARTIFACT_REJECT_REFUSAL_CODES: ReadonlySet<ArtifactResultCode>;
+/** The target key of a call: action (omitted ⇒ publish), file_path and url, NUL-joined. */
+export declare function artifactRejectKeyOf(args: unknown): string;
+/** A rejection text with a banner this module put in front of it stripped, so the fingerprint of the third rejection equals the first's. */
+export declare function stripArtifactRejectBanner(text: string): string;
+export declare function artifactRejectBannerFor(reason: string): string;
+export interface ArtifactRejectBreaker {
+    /** Record a rejection; the count of consecutive same-key/same-reason/same-message rejections including this one. */
+    hit(key: string, reason: string, text: string): number;
+    /** A successful call: forget every streak. */
+    clear(): void;
+    /** Inspection: the live streak of a key, if any. */
+    streakOf(key: string): {
+        reason: string;
+        count: number;
+    } | undefined;
+}
+export declare function createArtifactRejectBreaker(): ArtifactRejectBreaker;

package/dist/tools/artifact/reject-breaker.js

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+export const ARTIFACT_REJECT_BREAKER_THRESHOLD = 3;
+export const ARTIFACT_REJECT_KEY_COMPONENT_MAX = 1024;
+const HEAD = `IMPORTANT: Artifact calls for this target have now been rejected ${ARTIFACT_REJECT_BREAKER_THRESHOLD} or more times in this session for the same reason.`;
+export const ARTIFACT_REJECT_BANNER_RETRYABLE = `${HEAD} Do not send the same call again: either make the specific change the error describes, or stop calling Artifact for this target and tell the user what is failing and why.`;
+export const ARTIFACT_REJECT_BANNER_REFUSAL = `${HEAD} Stop calling Artifact for this target and tell the user the artifact could not be published and why — do not try to work around this refusal.`;
+export const ARTIFACT_REJECT_REFUSAL_CODES = new Set(["artifact.force_refused", "artifact.forbidden"]);
+const clip = (v) => (typeof v === "string" ? v.slice(0, ARTIFACT_REJECT_KEY_COMPONENT_MAX) : "");
+export function artifactRejectKeyOf(args) {
+    if (args === null || typeof args !== "object")
+        return "publish\0\0";
+    const a = args;
+    return `${clip(a["action"]) || "publish"}\0${clip(a["file_path"])}\0${clip(a["url"])}`;
+}
+export function stripArtifactRejectBanner(text) {
+    for (const banner of [ARTIFACT_REJECT_BANNER_RETRYABLE, ARTIFACT_REJECT_BANNER_REFUSAL])
+        if (text.startsWith(`${banner}\n\n`))
+            return text.slice(banner.length + 2);
+    return text;
+}
+export function artifactRejectBannerFor(reason) {
+    return ARTIFACT_REJECT_REFUSAL_CODES.has(reason) ? ARTIFACT_REJECT_BANNER_REFUSAL : ARTIFACT_REJECT_BANNER_RETRYABLE;
+}
+export function createArtifactRejectBreaker() {
+    const table = new Map();
+    return {
+        hit(key, reason, text) {
+            const fingerprint = createHash("sha256").update(stripArtifactRejectBanner(text)).digest("hex");
+            const prior = table.get(key);
+            const count = prior !== undefined && prior.reason === reason && prior.fingerprint === fingerprint ? prior.count + 1 : 1;
+            table.set(key, { reason, fingerprint, count });
+            return count;
+        },
+        clear() {
+            table.clear();
+        },
+        streakOf(key) {
+            const s = table.get(key);
+            return s === undefined ? undefined : { reason: s.reason, count: s.count };
+        },
+    };
+}

package/dist/tools/fs/bash-lexer.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The ONE shell lexer of the read faces, in two modes.
+ *
+ * STRICT is the residual space the classify faces live in: the caller has hard-rejected `< > $ ( ) \` \n \r \\`
+ * (or, under the rule lane's tolerate option, passes `<`/`>` through as ordinary text), so the whole of bash's
+ * word grammar left to model is quote pairing, the four connectors and whitespace. LENIENT is the space the
+ * refused-command whitelist reads — everything the strict gate refused, RECORDED instead of refused: heredoc
+ * bodies, substitution bodies, redirections, comments, escapes, line continuations, subshell groups,
+ * backgrounding, line breaks.
+ *
+ * One walker serves both. The lenient-only constructs are branches the strict caller can never reach (their
+ * characters are gone before it calls), so for every strict-accepted input the two modes produce the same words
+ * and the same connectors — up to the strict mode's own two residuals (a `#` is a word there, and JS whitespace
+ * rather than bash's blanks bounds a word); the whitelist stopped being a second parser the day it read this stream.
+ *
+ * Quoting. A quote character opens a region, the matching one closes it, and a quote of the OTHER kind inside an
+ * open region is ordinary text. When a region is still open at the end of the input the pass is re-run with
+ * quotes as ordinary characters — the QUOTE-BLIND reading, which yields strictly more words and more segments
+ * (the fail-closed direction every consumer here errs in). {@link quoteMask} is the positional projection of the
+ * same rule, for the callers that need "is this character quoted" rather than tokens.
+ *
+ * Line continuations. Bash removes a `\<newline>` pair from its input before it recognises anything — except
+ * inside single quotes, inside a comment (the newline ends the comment) and inside a QUOTED here-document body.
+ * The walker does the same at the point of reading: every lookahead below reads the next LOGICAL character, past
+ * any continuation, so a pair can stand inside a construct's spelling (`$\<newline>(…)` opens a substitution)
+ * and never inside the three places bash keeps it.
+ */
+export type LexMode = "strict" | "lenient";
+export interface LexOptions {
+    readonly mode: LexMode;
+    /** `"split"` (default): the connectors bound segments. `"text"`: a single segment is being tokenized and an
+     *  unquoted connector character is a word character — what a caller handing over one already-split segment
+     *  expects. */
+    readonly connectors?: "split" | "text";
+}
+/** An argv word in BOTH spellings. `raw` is what the SHELL sees (quotes, escapes and substitution text
+ *  retained) — the only spelling in which "is this metacharacter quoted?" is still answerable; `folded` is what
+ *  the PROGRAM receives after quote removal, with every substitution replaced by {@link SUBSTITUTION_PLACEHOLDER}
+ *  and a literal leading tilde spelled `./~…` (see {@link literalTildeSpelling}). */
+export interface LexedWord {
+    readonly kind: "word";
+    readonly raw: string;
+    readonly folded: string;
+}
+/** A redirection and the word it takes. A descriptor duplication (`>&2`, `<&0`, `>&-`, `>&1-`) takes none. */
+export interface LexedRedirect {
+    readonly kind: "redirect";
+    readonly op: "<" | ">" | ">>" | "<<<" | "&>" | "&>>" | ">&" | "<&";
+    readonly target?: LexedWord;
+}
+/** A here-document: the body is DATA the program reads on stdin, never command text. `quoted` records whether
+ *  the delimiter word carried a quote or an escape, which is bash's rule for "the body does not expand". */
+export interface LexedHeredoc {
+    readonly kind: "heredoc";
+    readonly delimiter: string;
+    readonly quoted: boolean;
+    readonly body: string;
+}
+/** A subshell parenthesis, standing alone: structure, not a word. */
+export interface LexedGroup {
+    readonly kind: "group";
+    readonly op: "(" | ")";
+}
+export type LexedToken = LexedWord | LexedRedirect | LexedHeredoc | LexedGroup;
+/** The connector bash ran a segment through — `"start"` for the first one. A closed set, because the read
+ *  boundary distinguishes all four: `&&` is the only one under which the previous segment is known to have
+ *  exited ZERO, `||` is the only one under which the previous segment may have been SKIPPED ENTIRELY, `|`
+ *  puts the segment in a subshell whose directory changes never reach the parent, and `;` is plain sequence. */
+export type ShellSegmentConnector = "start" | ";" | "&&" | "||" | "|";
+/** The lenient mode's two extra boundaries: a backgrounding `&` and a line break. */
+export type LenientConnector = ShellSegmentConnector | "&" | "\n";
+export interface LexedSegment {
+    /** The segment's text exactly as written (surrounding whitespace included) — what a caller that wants the
+     *  string rather than the tokens reads. Here-document bodies are not part of any segment's text. */
+    readonly text: string;
+    readonly connector: LenientConnector;
+    readonly tokens: readonly LexedToken[];
+    /** The bodies of the substitutions found in THIS segment (its words and its redirection targets), in order. */
+    readonly substitutions: readonly string[];
+}
+export interface LexedCommand {
+    readonly segments: readonly LexedSegment[];
+    /** Every substitution body of the command, in order (the per-segment lists concatenated). */
+    readonly substitutions: readonly string[];
+}
+/** One segment's argv words in both spellings, index-aligned by construction (folding is strictly per word — it
+ *  never splits or joins). The one shape every downstream arm of the classifier reads. */
+export interface SegmentTokens {
+    readonly folded: readonly string[];
+    readonly raw: readonly string[];
+}
+/** What a substitution leaves in a word's FOLDED spelling: a marker no argv word can spell, so a consumer that
+ *  judges words sees "this word carries text the shell computes" rather than the computing text itself. */
+export declare const SUBSTITUTION_PLACEHOLDER = " subst";
+/**
+ * Which characters of `s` sit inside a QUOTED region, by the same pairing rule the lexer walks with. The pairing
+ * quote characters themselves are reported as quoted — they are not operators either way.
+ *
+ * `balanced` is false when a region is still open at the end of the string. Callers must then NOT use the mask:
+ * an unterminated quote is a string bash itself cannot parse, and every consumer falls back to the quote-BLIND
+ * reading, which is the stricter one.
+ *
+ * EXACTNESS. This models bash only for the residual character space the strict faces operate in, where backslash
+ * escapes, `$`, backticks, and subshells are rejected outright — there `'` and `"` pairing is the whole of
+ * quoting, so a region computed here is exactly a region bash quotes. It is NOT a general shell quoting parser
+ * and must not be used before those characters are excluded.
+ */
+export declare function quoteMask(s: string): {
+    quoted: readonly boolean[];
+    balanced: boolean;
+};
+/** The ONE spelling of a LITERAL leading tilde — `./~…`, the relative path it is — for every position bash does not
+ *  expand it in (a quoted tilde-prefix, an option payload); a word without a leading tilde is returned as is. */
+export declare function literalTildeSpelling(word: string): string;
+/** The argv-word projection of a segment: redirections, here-documents and groups are not words the program
+ *  receives (bash removes them before exec). */
+export declare function wordsOf(segment: LexedSegment): SegmentTokens;
+/** The substitution bodies of an UNQUOTED here-document body: `$(…)` and backticks are live there, quotes are
+ *  ordinary characters, a backslash protects the next character. `undefined` when a substitution never closes. */
+export declare function substitutionsInHeredocBody(body: string): string[] | undefined;
+/**
+ * Lex a command. The honoured pass is authoritative when every quote closes; otherwise the quote-blind pass is
+ * the answer — the fail-closed fallback every face here has always taken for a string bash itself cannot parse.
+ * In STRICT mode that fallback is two-level, as the faces have always read it: the segments are split blind, and
+ * each segment's words are then read on their own balance (`echo "a b"; echo '` keeps `a b` one word in the first
+ * segment). The lenient face reads an unbalanced command blind throughout. `{ reject }` names a construct the
+ * lenient mode cannot read (an unterminated substitution or here-document, an operator with no operand, a
+ * substitution this lexer cannot delimit) or, in strict mode, a backgrounding `&`.
+ */
+export declare function lexShellText(source: string, opts: LexOptions): LexedCommand | {
+    reject: string;
+};