@sema-agent/core 7.17.7 → 7.19.0

package/dist/tools/artifact/artifact-tool.js

@@ -1,11 +1,13 @@
 import { createHash } from "node:crypto";
 import { Type } from "typebox";
-import { ARTIFACT_FAILURE_RESULT_CODE, ARTIFACT_HOST_ERROR_CODE, ARTIFACT_LIST_SCOPES, ARTIFACT_PLANE_CONTENT_ORIGIN, ARTIFACT_PUBLISH_CONTEXTS, } from "../../core/artifact-host.js";
+import { ARTIFACT_ACTION_CONCURRENCY_SAFE, ARTIFACT_COMMIT_THROW_OUTCOME, ARTIFACT_FAILURE_RESULT_CODE, ARTIFACT_HOST_ERROR_CODE, ARTIFACT_LIST_SCOPES, ARTIFACT_PLANE_CONTENT_ORIGIN, ARTIFACT_PUBLISH_CONTEXTS, } from "../../core/artifact-host.js";
 import { ARTIFACT_TOOL_NAME, toolFace } from "../../core/tool-catalog-entries.js";
+import { resolveAsk } from "../../core/tool-policy.js";
 import { errorResult } from "../../core/tools.js";
 import { inlineUntrusted } from "../../core/untrusted-text.js";
 import { actionDescription, artifactDescription, PARAM_TEXT, urlDescription } from "./artifact-text.js";
-const MAX_FILES_PER_PUBLISH = 255;
+import { ARTIFACT_REJECT_BREAKER_THRESHOLD, artifactRejectBannerFor, artifactRejectKeyOf, createArtifactRejectBreaker } from "./reject-breaker.js";
+export const MAX_FILES_PER_PUBLISH = 255;
 const LIST_LIMIT_DEFAULT = 25;
 const LIST_LIMIT_MAX = 100;
 const BINARY_NOTE_MEDIA = new Set(["application/json", "application/javascript", "text/javascript", "image/svg+xml", "application/xml"]);
@@ -125,36 +127,42 @@ function buildSchema(caps) {
 const invalid = (text) => errorResult(`Error (Artifact): ${text}`, { type: "artifact", invalidArguments: true });
 const typed = (code, text, extra = {}) => errorResult(`Error (Artifact): ${text}`, { type: "artifact", code: ARTIFACT_FAILURE_RESULT_CODE[code], ...extra });
 export function createArtifactTool(opts) {
-    const { host, capabilities: caps, runId, taskId, sessionId, agentName, readLocalFile } = opts;
+    const { host, capabilities: caps, runId, taskId, sessionId, agentName, readLocalFile, onAsk } = opts;
     const versions = new Map();
     const bindings = new Map();
     const occurrences = new Map();
+    const breaker = createArtifactRejectBreaker();
+    const ownUrls = new Set();
+    const sharedUrls = new Set();
+    const sharedReadApproved = new Set();
+    const consentInFlight = new Map();
+    const activeTargets = new Map();
     const hasAction = (a) => caps.actions.includes(a);
     const rememberRef = (ref) => {
         versions.set(ref.url, ref.version);
     };
-    const attemptIdOf = (ctx) => {
+    const rememberOwner = (url, owner) => {
+        (owner === "mine" ? ownUrls : sharedUrls).add(url);
+    };
+    const nextContext = (ctx) => {
         const n = occurrences.get(ctx.toolCallId) ?? 0;
         occurrences.set(ctx.toolCallId, n + 1);
-        return artifactAttemptId(runId, ctx.toolCallId, n);
+        return {
+            taskId,
+            ...(sessionId !== undefined ? { sessionId } : {}),
+            ...(agentName !== undefined ? { agentName } : {}),
+            runId,
+            attemptId: artifactAttemptId(runId, ctx.toolCallId, n),
+        };
     };
-    const contextFor = (attemptId) => ({
-        taskId,
-        ...(sessionId !== undefined ? { sessionId } : {}),
-        ...(agentName !== undefined ? { agentName } : {}),
-        runId,
-        attemptId,
-    });
     const hostError = (verb, fault, url) => {
-        if (caps.plane === "local-stub" && fault.kind === "threw") {
-            return errorResult(`Error (Artifact): the local artifact stub failed before committing (${inlineUntrusted(fault.message, 200)}). Nothing was published; the call can be repeated.`, {
-                type: "artifact", code: ARTIFACT_HOST_ERROR_CODE, outcome: "not_executed", plane: caps.plane,
-            });
+        const outcome = fault.kind === "threw" ? ARTIFACT_COMMIT_THROW_OUTCOME[caps.commit] : "unknown";
+        const details = { type: "artifact", code: ARTIFACT_HOST_ERROR_CODE, outcome, plane: caps.plane, commit: caps.commit };
+        if (outcome === "not_executed") {
+            return errorResult(`Error (Artifact): the artifact host failed before committing (${inlineUntrusted(fault.message, 200)}). Nothing was published; the call can be repeated.`, details);
         }
         const verifiable = hasAction("read") && url !== "";
-        return errorResult(`Error (Artifact): the artifact host did not answer the ${verb.slice(0, 20)} (${inlineUntrusted(fault.message, 200)}). Whether it was applied is not known.${verifiable ? ` Verify with action: "read" on ${url.slice(0, 200)} before repeating the call.` : ""}`, {
-            type: "artifact", code: ARTIFACT_HOST_ERROR_CODE, outcome: "unknown", plane: caps.plane,
-        });
+        return errorResult(`Error (Artifact): the artifact host did not answer the ${verb.slice(0, 20)} (${inlineUntrusted(fault.message, 200)}). Whether it was applied is not known: it may already have been committed, so do not simply repeat the call.${verifiable ? ` Verify with action: "read" on ${url.slice(0, 200)} first.` : ""}`, details);
     };
     const notFoundOrForbidden = (code, url, message) => code === "not_found"
         ? typed(code, `no artifact at ${inlineUntrusted(url, 200)} (${inlineUntrusted(message, 200)}).`, { url })
@@ -173,42 +181,60 @@ export function createArtifactTool(opts) {
             }
         }
     };
+    const manifestOf = (a) => {
+        const mainNorm = normalizePublishedPath(basenameOf(a.file_path));
+        if (!mainNorm.ok)
+            return { ok: false, result: invalid(`the published name of ${inlineUntrusted(a.file_path, 200)} ${mainNorm.reason.slice(0, 80)}.`) };
+        const entries = [];
+        if (a.files === undefined || (Array.isArray(a.files) && a.files.length === 0))
+            return { ok: true, main: mainNorm.path, entries };
+        if (!caps.multiFile)
+            return { ok: false, result: invalid("this artifact host publishes single files only; `files` is not accepted.") };
+        if (!Array.isArray(a.files))
+            return { ok: false, result: invalid("`files` must be an array of { path, file_path } entries.") };
+        if (a.files.length > MAX_FILES_PER_PUBLISH)
+            return { ok: false, result: invalid(`\`files\` carries ${String(a.files.length).slice(0, 20)} entries; at most ${MAX_FILES_PER_PUBLISH} supporting files are accepted per publish.`) };
+        const seen = new Set([mainNorm.path.toLowerCase()]);
+        for (const entry of a.files) {
+            if (!isRecord(entry) || typeof entry["path"] !== "string" || typeof entry["file_path"] !== "string")
+                return { ok: false, result: invalid("every `files` entry must carry a string `path` and a string `file_path`.") };
+            const norm = normalizePublishedPath(entry["path"]);
+            if (!norm.ok)
+                return { ok: false, result: invalid(`files entry ${inlineUntrusted(entry["path"], 120)} ${norm.reason.slice(0, 80)}.`) };
+            const fold = norm.path.toLowerCase();
+            if (seen.has(fold))
+                return { ok: false, result: invalid(`files entry ${inlineUntrusted(norm.path, 120)} collides with another published path.`) };
+            seen.add(fold);
+            entries.push({ path: norm.path, file_path: entry["file_path"] });
+        }
+        return { ok: true, main: mainNorm.path, entries };
+    };
     async function publish(a, ctx) {
-        const attemptId = attemptIdOf(ctx);
-        if (a.file_path === undefined)
+        if (typeof a.file_path !== "string")
             return invalid("`file_path` is required to publish.");
+        const manifest = manifestOf(a);
+        if (!manifest.ok)
+            return manifest.result;
         const files = [];
         const budget = Math.min(caps.maxFileBytes, caps.maxTotalBytes);
         const first = await readLocalFile(a.file_path, budget, ctx.signal);
         if (!first.ok)
             return readRefusal(a.file_path, first);
-        files.push({ path: basenameOf(a.file_path), content: first.bytes, mediaType: mediaTypeOf(a.file_path) });
+        files.push({ path: manifest.main, content: first.bytes, mediaType: mediaTypeOf(manifest.main) });
         let total = first.bytes.byteLength;
         const url = a.url ?? bindings.get(first.key);
         if (url === undefined && (a.force === true || a.baseVersion !== undefined)) {
             return invalid("`force` and `baseVersion` only apply to an update — pass `url`, or republish the same file path this session already published.");
         }
-        if (a.files !== undefined && a.files.length > 0) {
-            if (!caps.multiFile)
-                return invalid("this artifact host publishes single files only; `files` is not accepted.");
-            const seen = new Set([files[0].path.normalize("NFC").toLowerCase()]);
-            for (const entry of a.files) {
-                const norm = normalizePublishedPath(entry.path);
-                if (!norm.ok)
-                    return invalid(`files entry ${inlineUntrusted(entry.path, 120)} ${norm.reason.slice(0, 80)}.`);
-                const fold = norm.path.toLowerCase();
-                if (seen.has(fold))
-                    return invalid(`files entry ${inlineUntrusted(norm.path, 120)} collides with another published path.`);
-                seen.add(fold);
-                const left = caps.maxTotalBytes - total;
-                if (left <= 0)
-                    return typed("payload_too_large", `the files already total ${String(total).slice(0, 20)} bytes; this host accepts at most ${String(caps.maxTotalBytes).slice(0, 20)} bytes per version.`, { limit: caps.maxTotalBytes, measured: total });
-                const r = await readLocalFile(entry.file_path, Math.min(caps.maxFileBytes, left), ctx.signal);
-                if (!r.ok)
-                    return readRefusal(entry.file_path, r);
-                total += r.bytes.byteLength;
-                files.push({ path: norm.path, content: r.bytes, mediaType: mediaTypeOf(norm.path) });
-            }
+        for (const entry of manifest.entries) {
+            const left = caps.maxTotalBytes - total;
+            if (left <= 0)
+                return typed("payload_too_large", `the files already total ${String(total).slice(0, 20)} bytes; this host accepts at most ${String(caps.maxTotalBytes).slice(0, 20)} bytes per version.`, { limit: caps.maxTotalBytes, measured: total });
+            const r = await readLocalFile(entry.file_path, Math.min(caps.maxFileBytes, left), ctx.signal);
+            if (!r.ok)
+                return readRefusal(entry.file_path, r);
+            total += r.bytes.byteLength;
+            files.push({ path: entry.path, content: r.bytes, mediaType: mediaTypeOf(entry.path) });
         }
         const baseVersion = a.baseVersion ?? (url !== undefined ? versions.get(url) : undefined);
         const req = {
@@ -222,12 +248,13 @@ export function createArtifactTool(opts) {
             ...(a.force === true ? { force: true } : {}),
             publishContext: a.publishContext ?? "plain",
         };
-        const call = await callHost("publish", () => host.publish(req, contextFor(attemptId)), ctx.signal);
+        const call = await callHost("publish", () => host.publish(req, nextContext(ctx)), ctx.signal);
         if (!call.ok)
             return hostError("publish", call, inlineUntrusted(url ?? "", 200));
         const out = call.value;
         if (out.ok) {
             rememberRef(out.ref);
+            rememberOwner(out.ref.url, "mine");
             bindings.set(first.key, out.ref.url);
             const title = out.ref.title !== undefined ? ` — ${inlineUntrusted(out.ref.title, 120)}` : "";
             return {
@@ -236,7 +263,12 @@ export function createArtifactTool(opts) {
             };
         }
         if (out.code === "conflict") {
-            const snapshot = out.current;
+            let snapshot = out.current;
+            if (snapshot !== "reread") {
+                const withheld = url === undefined || (await filesOwnership(url, ctx)) !== undefined;
+                if (withheld || (url !== undefined && sharedUrls.has(url) && !sharedReadApproved.has(url)))
+                    snapshot = "reread";
+            }
             if (snapshot !== "reread" && url !== undefined)
                 versions.set(url, out.currentVersion);
             const handedBack = snapshot === "reread"
@@ -266,56 +298,125 @@ export function createArtifactTool(opts) {
         }
     }
     async function list(a, ctx) {
-        const attemptId = attemptIdOf(ctx);
         const scope = a.scope ?? "mine";
         const limit = a.limit ?? LIST_LIMIT_DEFAULT;
-        const call = await callHost("list", () => host.list({ scope, limit }, contextFor(attemptId)), ctx.signal);
+        const call = await callHost("list", () => host.list({ scope, limit }, nextContext(ctx)), ctx.signal);
         if (!call.ok)
             return hostError("list", call, "");
         const out = call.value;
         if (!out.ok)
             return typed("refused", `the host refused the listing (${inlineUntrusted(out.message, 200)}).`);
+        for (const r of out.rows)
+            rememberOwner(r.url, r.owner);
         const lines = out.rows.map((r) => `${inlineUntrusted(r.url, 300)}  v${inlineUntrusted(r.version, 40)}  ${inlineUntrusted(r.updatedAt, 40)}  (${r.owner})${r.title !== undefined ? `  ${inlineUntrusted(r.title, 120)}` : ""}`);
         const body = lines.length === 0 ? "nothing listed" : lines.join("\n");
         return { content: `${body}${out.truncated ? "\n(more artifacts exist; raise `limit` to see them)" : ""}`, details: { type: "artifact", action: "list", plane: caps.plane, scope, rows: out.rows, truncated: out.truncated } };
     }
+    const sharedReadConsent = (url, ref, ctx) => {
+        if (sharedReadApproved.has(url))
+            return Promise.resolve({ ok: true });
+        const pending = consentInFlight.get(url);
+        if (pending !== undefined)
+            return pending;
+        const ask = (async () => {
+            const title = ref?.title !== undefined ? ` (${inlineUntrusted(ref.title, 120)})` : "";
+            const version = ref !== undefined ? `, version ${inlineUntrusted(ref.version, 60)}` : "";
+            const resolved = await resolveAsk({
+                toolName: ARTIFACT_TOOL_NAME,
+                toolCallId: ctx.toolCallId,
+                args: { action: "read", url },
+                message: `Read a shared artifact: ${inlineUntrusted(url, 300)}${title}${version} — an artifact another person shared with this user; approving covers re-reads of it for the rest of this run.`,
+                requiresRealApproval: true,
+            }, onAsk, ctx.signal);
+            if (resolved.action !== "allow")
+                return { ok: false, reason: resolved.message ?? "not approved" };
+            if (resolved.updatedInput !== undefined)
+                return { ok: false, reason: "the approval edited the request; an edited approval does not authorize the original target" };
+            sharedReadApproved.add(url);
+            return { ok: true };
+        })().finally(() => {
+            if (!activeTargets.has(url))
+                consentInFlight.delete(url);
+        });
+        consentInFlight.set(url, ask);
+        return ask;
+    };
+    const filesOwnership = async (url, ctx) => {
+        if (!ownUrls.has(url) && !sharedUrls.has(url)) {
+            if (!hasAction("read"))
+                return typed("refused", `${inlineUntrusted(url, 200)} is not an artifact this run published or listed as its own, and this host declares no read to establish who owns it; its files were not delivered.`, { url, sharedRead: "ownership_unknown" });
+            const probe = await callHost("read", () => host.read({ url }, nextContext(ctx)), ctx.signal);
+            if (!probe.ok)
+                return hostError("read", probe, inlineUntrusted(url, 200));
+            if (!probe.value.ok)
+                return notFoundOrForbidden(probe.value.code, url, probe.value.message);
+            if (probe.value.ref.url !== url)
+                return hostError("read", { kind: "malformed", message: "read.ref.url does not match the requested target" }, inlineUntrusted(url, 200));
+            rememberOwner(url, probe.value.isolatedSummary ? "shared" : "mine");
+        }
+        if (!sharedUrls.has(url))
+            return undefined;
+        const consent = await sharedReadConsent(url, undefined, ctx);
+        return consent.ok ? undefined : typed("refused", `reading the shared artifact ${inlineUntrusted(url, 200)} was not approved (${inlineUntrusted(consent.reason, 200)}); its files were not delivered.`, { url, sharedRead: "not_approved" });
+    };
     async function read(a, ctx) {
-        const attemptId = attemptIdOf(ctx);
         if (a.url === undefined)
             return invalid("`url` is required to read an artifact.");
-        const call = await callHost("read", () => host.read({ url: a.url }, contextFor(attemptId)), ctx.signal);
+        const call = await callHost("read", () => host.read({ url: a.url }, nextContext(ctx)), ctx.signal);
         if (!call.ok)
             return hostError("read", call, inlineUntrusted(a.url, 200));
         const out = call.value;
         if (!out.ok)
             return notFoundOrForbidden(out.code, a.url, out.message);
+        if (out.ref.url !== a.url)
+            return hostError("read", { kind: "malformed", message: "read.ref.url does not match the requested target" }, inlineUntrusted(a.url, 200));
+        rememberOwner(a.url, out.isolatedSummary ? "shared" : "mine");
+        if (sharedUrls.has(a.url)) {
+            const consent = await sharedReadConsent(a.url, out.ref, ctx);
+            if (!consent.ok)
+                return typed("refused", `reading the shared artifact ${inlineUntrusted(a.url, 200)} was not approved (${inlineUntrusted(consent.reason, 200)}); its content was not delivered.`, { url: a.url, sharedRead: "not_approved" });
+        }
         rememberRef(out.ref);
         const head = out.isolatedSummary ? `[isolated summary of a shared artifact — ${inlineUntrusted(out.ref.url, 300)}, version ${inlineUntrusted(out.ref.version, 60)}]\n` : "";
         return { content: `${head}${out.content}`, details: { type: "artifact", action: "read", plane: caps.plane, ref: out.ref, isolatedSummary: out.isolatedSummary } };
     }
     async function listFiles(a, ctx) {
-        const attemptId = attemptIdOf(ctx);
         if (a.url === undefined)
             return invalid("`url` is required to list an artifact's files.");
-        const call = await callHost("list_files", () => host.listFiles({ url: a.url }, contextFor(attemptId)), ctx.signal);
+        const gated = await filesOwnership(a.url, ctx);
+        if (gated !== undefined)
+            return gated;
+        const call = await callHost("list_files", () => host.listFiles({ url: a.url }, nextContext(ctx)), ctx.signal);
         if (!call.ok)
             return hostError("list_files", call, inlineUntrusted(a.url, 200));
         const out = call.value;
         if (!out.ok)
             return notFoundOrForbidden(out.code, a.url, out.message);
+        if (sharedUrls.has(a.url)) {
+            const denied = await filesOwnership(a.url, ctx);
+            if (denied !== undefined)
+                return denied;
+        }
         const lines = out.entries.map((e) => `${inlineUntrusted(e.path, 200)}  ${String(e.bytes).slice(0, 20)} bytes${e.mediaType !== undefined ? `  ${inlineUntrusted(e.mediaType, 80)}` : ""}`);
         return { content: lines.length === 0 ? "no files" : lines.join("\n"), details: { type: "artifact", action: "list_files", plane: caps.plane, url: a.url, entries: out.entries } };
     }
     async function readFile(a, ctx) {
-        const attemptId = attemptIdOf(ctx);
         if (a.url === undefined || a.path === undefined)
             return invalid("`url` and `path` are required to read a published file.");
-        const call = await callHost("read_file", () => host.readFile({ url: a.url, path: a.path }, contextFor(attemptId)), ctx.signal);
+        const gated = await filesOwnership(a.url, ctx);
+        if (gated !== undefined)
+            return gated;
+        const call = await callHost("read_file", () => host.readFile({ url: a.url, path: a.path }, nextContext(ctx)), ctx.signal);
         if (!call.ok)
             return hostError("read_file", call, inlineUntrusted(a.url, 200));
         const out = call.value;
         if (!out.ok)
             return notFoundOrForbidden(out.code, a.url, out.message);
+        if (sharedUrls.has(a.url)) {
+            const denied = await filesOwnership(a.url, ctx);
+            if (denied !== undefined)
+                return denied;
+        }
         return { content: renderFile(out.file), details: { type: "artifact", action: "read_file", plane: caps.plane, url: a.url, path: out.file.path, bytes: out.file.content.byteLength, mediaType: out.file.mediaType } };
     }
     return {
@@ -325,27 +426,59 @@ export function createArtifactTool(opts) {
         description: artifactDescription(caps.plane, caps.actions),
         parameters: buildSchema(caps),
         prepareArguments: (args) => (isRecord(args) && args["action"] === undefined ? { ...args, action: "publish" } : args),
-        execute: (args, ctx) => {
+        isConcurrencySafe: (args) => isRecord(args) && typeof args["action"] === "string" && ARTIFACT_ACTION_CONCURRENCY_SAFE[args["action"]] === true,
+        execute: async (args, ctx) => {
             const a = args;
             const action = a.action ?? "publish";
-            if (!hasAction(action))
-                return invalid(`action ${inlineUntrusted(String(action), 40)} is not available on this artifact host.`);
-            switch (action) {
-                case "publish":
-                    return publish(a, ctx);
-                case "list":
-                    return list(a, ctx);
-                case "read":
-                    return read(a, ctx);
-                case "list_files":
-                    return listFiles(a, ctx);
-                case "read_file":
-                    return readFile(a, ctx);
-                default: {
-                    const _exhaustive = action;
-                    return _exhaustive;
+            const target = typeof a.url === "string" ? a.url : undefined;
+            if (target !== undefined)
+                activeTargets.set(target, (activeTargets.get(target) ?? 0) + 1);
+            let result;
+            try {
+                result = await dispatch(action, a, ctx);
+            }
+            finally {
+                if (target !== undefined) {
+                    const left = activeTargets.get(target) - 1;
+                    if (left > 0)
+                        activeTargets.set(target, left);
+                    else {
+                        activeTargets.delete(target);
+                        consentInFlight.delete(target);
+                    }
                 }
             }
+            if (typeof result === "string" || result.isError !== true) {
+                breaker.clear();
+                return result;
+            }
+            const details = isRecord(result.details) ? result.details : {};
+            const reason = typeof details["code"] === "string" ? details["code"] : details["invalidArguments"] === true ? "invalid_arguments" : "error";
+            const text = typeof result.content === "string" ? result.content : "";
+            const count = breaker.hit(artifactRejectKeyOf(a), reason, text);
+            if (count < ARTIFACT_REJECT_BREAKER_THRESHOLD || typeof result.content !== "string")
+                return result;
+            return { ...result, content: `${artifactRejectBannerFor(reason)}\n\n${result.content}`, details: { ...details, rejectStreak: count } };
         },
     };
+    function dispatch(action, a, ctx) {
+        if (!hasAction(action))
+            return invalid(`action ${inlineUntrusted(String(action), 40)} is not available on this artifact host.`);
+        switch (action) {
+            case "publish":
+                return publish(a, ctx);
+            case "list":
+                return list(a, ctx);
+            case "read":
+                return read(a, ctx);
+            case "list_files":
+                return listFiles(a, ctx);
+            case "read_file":
+                return readFile(a, ctx);
+            default: {
+                const _exhaustive = action;
+                return _exhaustive;
+            }
+        }
+    }
 }

package/dist/tools/artifact/conformance.d.ts

@@ -0,0 +1,56 @@
+import { type ArtifactAction, type ArtifactHost, type ArtifactHostCapabilities, type ArtifactRef } from "../../core/artifact-host.js";
+export interface ArtifactConformanceHooks {
+    /** Make the host's NEXT write fail BEFORE its commit point (`arm`), then restore it (`disarm`). The atomicity vector
+     *  runs only with this hook: the kit cannot reach inside an arbitrary host. */
+    precommitFault?: {
+        arm: () => void | Promise<void>;
+        disarm: () => void | Promise<void>;
+    };
+    /** Save a new version of `ref`'s page from INSIDE the page — the version a plain `force` must not discard
+     *  (`force_refused`). The force-refusal vector runs only with this hook. */
+    pageSavedVersion?: (ref: ArtifactRef) => void | Promise<void>;
+}
+export interface ArtifactConformanceOptions {
+    hooks?: ArtifactConformanceHooks;
+    /** Run the at-limit POSITIVE arms of the byte-limit vector: they allocate and publish payloads of the declared
+     *  sizes. Default `false` — reported `skipped`, named. The over-limit refusal arms always run. */
+    largePayloads?: boolean;
+    /** The run id the kit mounts (`onMount`) and calls under; default a fresh uuid. */
+    runId?: string;
+}
+export type ArtifactConformanceStatus = "pass" | "fail" | "not_applicable" | "skipped";
+export interface ArtifactConformanceVector {
+    /** Stable id: a host's own conformance test keys on it. */
+    id: string;
+    describe: string;
+    /** Every listed action must be declared for the vector to apply. */
+    requiresActions: readonly ArtifactAction[];
+    requiresMultiFile?: true;
+    requiresHook?: keyof ArtifactConformanceHooks;
+    requiresLargePayloads?: true;
+}
+export interface ArtifactConformanceResult {
+    id: string;
+    status: ArtifactConformanceStatus;
+    /** What passed, what failed (the first violated expectation), or why the vector did not run. */
+    detail: string;
+}
+export interface ArtifactConformanceReport {
+    capabilities: ArtifactHostCapabilities;
+    runId: string;
+    results: readonly ArtifactConformanceResult[];
+    passed: number;
+    failed: number;
+    notApplicable: number;
+    skipped: number;
+}
+/** The full vector matrix (data; ids are stable). */
+export declare const ARTIFACT_CONFORMANCE_VECTORS: readonly ArtifactConformanceVector[];
+/** The vectors a host's DECLARATION covers (hook- and payload-gated vectors included: their gating is reported at run time). */
+export declare function artifactConformanceVectors(host: ArtifactHost): ArtifactConformanceVector[];
+/**
+ * Drive `host` through every vector its declaration covers, sequentially, under one fresh run id (the host's
+ * `onMount` is called first). Throws only when the declaration itself is invalid — every vector outcome, a thrown
+ * host method included, is a row of the report.
+ */
+export declare function runArtifactConformance(host: ArtifactHost, opts?: ArtifactConformanceOptions): Promise<ArtifactConformanceReport>;