@ai-agent-forge/plugin-sdk 0.85.0

package/dist/context-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget.d.ts","sourceRoot":"","sources":["../src/context-budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,yFAAyF;AACzF,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,8BAA8B;IAC9C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uFAAuF;IACvF,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IACrC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,SAAS,SAAS,EAAE,CAAC;IAC3C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,QAAA,MAAM,gCAAgC,EAAE,qBAItC,CAAC;AA+EH;;;GAGG;AACH,wBAAgB,sBAAsB,CACrC,KAAK,EAAE,8BAA8B,EACrC,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,GACrC,yBAAyB,CAuC3B;AAED,OAAO,EAAE,gCAAgC,EAAE,CAAC","sourcesContent":["import type { JsonValue } from \"./common.ts\";\nimport type { PluginErrorV1 } from \"./operation.ts\";\n\n/** Shared egress budget for every plugin result that is projected into model context. */\nexport interface PluginContextBudgetV1 {\n\treadonly maxOutputBytes: number;\n\treadonly maxInlineItems: number;\n\treadonly maxCellChars: number;\n}\n\nexport interface PluginContextProjectionInputV1 {\n\treadonly version: 1;\n\treadonly operationId: string;\n\t/** Already summarized values only. Raw rows/payloads are rejected at this boundary. */\n\treadonly items: readonly JsonValue[];\n\treadonly outputArtifactRef?: string;\n\treadonly truncated?: boolean;\n}\n\nexport interface PluginContextProjectionV1 {\n\treadonly version: 1;\n\treadonly operationId: string;\n\treadonly status: \"succeeded\" | \"failed\";\n\treadonly inlineItems: readonly JsonValue[];\n\treadonly truncated: boolean;\n\treadonly outputArtifactRef?: string;\n\treadonly error?: PluginErrorV1;\n}\n\nconst DEFAULT_PLUGIN_CONTEXT_BUDGET_V1: PluginContextBudgetV1 = Object.freeze({\n\tmaxOutputBytes: 64 * 1024,\n\tmaxInlineItems: 20,\n\tmaxCellChars: 256,\n});\n\nfunction error(code: string, message: string): PluginErrorV1 {\n\treturn { version: 1, code, message };\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction assertPositiveInteger(value: unknown, label: string): asserts value is number {\n\tif (!Number.isSafeInteger(value) || (value as number) <= 0)\n\t\tthrow new Error(`${label} must be a positive safe integer`);\n}\n\nfunction assertNonNegativeInteger(value: unknown, label: string): asserts value is number {\n\tif (!Number.isSafeInteger(value) || (value as number) < 0)\n\t\tthrow new Error(`${label} must be a non-negative safe integer`);\n}\n\nfunction isJsonValue(value: unknown): value is JsonValue {\n\tif (value === null || typeof value === \"string\" || typeof value === \"boolean\") return true;\n\tif (typeof value === \"number\") return Number.isFinite(value);\n\tif (Array.isArray(value)) return value.every(isJsonValue);\n\tif (isRecord(value)) return Object.values(value).every(isJsonValue);\n\treturn false;\n}\n\nfunction containsRawPayload(value: unknown, seen = new Set<object>()): boolean {\n\tif (!isRecord(value) && !Array.isArray(value)) return false;\n\tif (seen.has(value)) return false;\n\tseen.add(value);\n\tif (isRecord(value)) {\n\t\tfor (const [key, child] of Object.entries(value)) {\n\t\t\tif ((key === \"rows\" || key === \"rawRows\" || key === \"rawPayload\" || key === \"payload\") && child !== undefined)\n\t\t\t\treturn true;\n\t\t\tif (containsRawPayload(child, seen)) return true;\n\t\t}\n\t\treturn false;\n\t}\n\treturn value.some((child) => containsRawPayload(child, seen));\n}\n\nfunction validateBudget(input: Partial<PluginContextBudgetV1> | undefined): PluginContextBudgetV1 {\n\tconst budget = { ...DEFAULT_PLUGIN_CONTEXT_BUDGET_V1, ...(input ?? {}) };\n\tassertPositiveInteger(budget.maxOutputBytes, \"maxOutputBytes\");\n\tassertNonNegativeInteger(budget.maxInlineItems, \"maxInlineItems\");\n\tassertPositiveInteger(budget.maxCellChars, \"maxCellChars\");\n\treturn Object.freeze(budget);\n}\n\nfunction boundStrings(value: JsonValue, maxCellChars: number): JsonValue {\n\tif (typeof value === \"string\") {\n\t\tif ([...value].length > maxCellChars) throw new Error(\"context string exceeds maxCellChars\");\n\t\treturn value;\n\t}\n\tif (Array.isArray(value))\n\t\treturn Object.freeze(value.map((child) => boundStrings(child, maxCellChars))) as unknown as JsonValue;\n\tif (isRecord(value)) {\n\t\treturn Object.freeze(\n\t\t\tObject.fromEntries(\n\t\t\t\tObject.entries(value).map(([key, child]) => [key, boundStrings(child as JsonValue, maxCellChars)]),\n\t\t\t),\n\t\t);\n\t}\n\treturn value;\n}\n\nfunction invalid(operationId: string, code: string, message: string): PluginContextProjectionV1 {\n\treturn Object.freeze({\n\t\tversion: 1,\n\t\toperationId,\n\t\tstatus: \"failed\",\n\t\tinlineItems: Object.freeze([]),\n\t\ttruncated: false,\n\t\terror: error(code, message),\n\t});\n}\n\n/**\n * Projects plugin summaries into the model-visible context envelope. This is an\n * egress boundary: it never accepts raw rows or silently exceeds a byte budget.\n */\nexport function projectPluginContextV1(\n\tinput: PluginContextProjectionInputV1,\n\tlimits?: Partial<PluginContextBudgetV1>,\n): PluginContextProjectionV1 {\n\tconst operationId = isRecord(input) && typeof input.operationId === \"string\" ? input.operationId : \"invalid\";\n\ttry {\n\t\tif (!isRecord(input) || input.version !== 1) throw new Error(\"input must have version 1\");\n\t\tif (typeof input.operationId !== \"string\" || input.operationId.trim() === \"\")\n\t\t\tthrow new Error(\"operationId must be a non-empty string\");\n\t\tif (!Array.isArray(input.items)) throw new Error(\"items must be an array\");\n\t\tconst budget = validateBudget(limits);\n\t\tif (containsRawPayload(input.items)) throw new Error(\"raw payloads are not allowed in plugin context\");\n\t\tif (input.outputArtifactRef !== undefined) {\n\t\t\tif (typeof input.outputArtifactRef !== \"string\" || input.outputArtifactRef.trim() === \"\")\n\t\t\t\tthrow new Error(\"outputArtifactRef must be a non-empty string\");\n\t\t\tif (/^(?:[a-zA-Z]:[\\\\/]|[\\\\/]{1,2}|\\\\\\\\)/.test(input.outputArtifactRef))\n\t\t\t\tthrow new Error(\"outputArtifactRef must be opaque\");\n\t\t}\n\t\tconst items = input.items.map((item, index) => {\n\t\t\tif (!isJsonValue(item)) throw new Error(`items[${index}] must be JSON-safe`);\n\t\t\treturn boundStrings(item, budget.maxCellChars);\n\t\t});\n\t\tconst truncated = input.truncated === true || items.length > budget.maxInlineItems;\n\t\tconst inlineItems = Object.freeze(items.slice(0, budget.maxInlineItems));\n\t\tconst result = Object.freeze({\n\t\t\tversion: 1 as const,\n\t\t\toperationId: input.operationId,\n\t\t\tstatus: \"succeeded\" as const,\n\t\t\tinlineItems,\n\t\t\ttruncated,\n\t\t\t...(input.outputArtifactRef === undefined ? {} : { outputArtifactRef: input.outputArtifactRef }),\n\t\t});\n\t\tif (new TextEncoder().encode(JSON.stringify(result)).byteLength > budget.maxOutputBytes)\n\t\t\tthrow new Error(\"projected context exceeds maxOutputBytes\");\n\t\treturn result;\n\t} catch (cause) {\n\t\treturn invalid(\n\t\t\toperationId,\n\t\t\t\"context_projection_rejected\",\n\t\t\tcause instanceof Error ? cause.message : \"Context projection rejected\",\n\t\t);\n\t}\n}\n\nexport { DEFAULT_PLUGIN_CONTEXT_BUDGET_V1 };\n"]}

package/dist/context-budget.js

@@ -0,0 +1,124 @@
+const DEFAULT_PLUGIN_CONTEXT_BUDGET_V1 = Object.freeze({
+    maxOutputBytes: 64 * 1024,
+    maxInlineItems: 20,
+    maxCellChars: 256,
+});
+function error(code, message) {
+    return { version: 1, code, message };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertPositiveInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new Error(`${label} must be a positive safe integer`);
+}
+function assertNonNegativeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new Error(`${label} must be a non-negative safe integer`);
+}
+function isJsonValue(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    if (isRecord(value))
+        return Object.values(value).every(isJsonValue);
+    return false;
+}
+function containsRawPayload(value, seen = new Set()) {
+    if (!isRecord(value) && !Array.isArray(value))
+        return false;
+    if (seen.has(value))
+        return false;
+    seen.add(value);
+    if (isRecord(value)) {
+        for (const [key, child] of Object.entries(value)) {
+            if ((key === "rows" || key === "rawRows" || key === "rawPayload" || key === "payload") && child !== undefined)
+                return true;
+            if (containsRawPayload(child, seen))
+                return true;
+        }
+        return false;
+    }
+    return value.some((child) => containsRawPayload(child, seen));
+}
+function validateBudget(input) {
+    const budget = { ...DEFAULT_PLUGIN_CONTEXT_BUDGET_V1, ...(input ?? {}) };
+    assertPositiveInteger(budget.maxOutputBytes, "maxOutputBytes");
+    assertNonNegativeInteger(budget.maxInlineItems, "maxInlineItems");
+    assertPositiveInteger(budget.maxCellChars, "maxCellChars");
+    return Object.freeze(budget);
+}
+function boundStrings(value, maxCellChars) {
+    if (typeof value === "string") {
+        if ([...value].length > maxCellChars)
+            throw new Error("context string exceeds maxCellChars");
+        return value;
+    }
+    if (Array.isArray(value))
+        return Object.freeze(value.map((child) => boundStrings(child, maxCellChars)));
+    if (isRecord(value)) {
+        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, child]) => [key, boundStrings(child, maxCellChars)])));
+    }
+    return value;
+}
+function invalid(operationId, code, message) {
+    return Object.freeze({
+        version: 1,
+        operationId,
+        status: "failed",
+        inlineItems: Object.freeze([]),
+        truncated: false,
+        error: error(code, message),
+    });
+}
+/**
+ * Projects plugin summaries into the model-visible context envelope. This is an
+ * egress boundary: it never accepts raw rows or silently exceeds a byte budget.
+ */
+export function projectPluginContextV1(input, limits) {
+    const operationId = isRecord(input) && typeof input.operationId === "string" ? input.operationId : "invalid";
+    try {
+        if (!isRecord(input) || input.version !== 1)
+            throw new Error("input must have version 1");
+        if (typeof input.operationId !== "string" || input.operationId.trim() === "")
+            throw new Error("operationId must be a non-empty string");
+        if (!Array.isArray(input.items))
+            throw new Error("items must be an array");
+        const budget = validateBudget(limits);
+        if (containsRawPayload(input.items))
+            throw new Error("raw payloads are not allowed in plugin context");
+        if (input.outputArtifactRef !== undefined) {
+            if (typeof input.outputArtifactRef !== "string" || input.outputArtifactRef.trim() === "")
+                throw new Error("outputArtifactRef must be a non-empty string");
+            if (/^(?:[a-zA-Z]:[\\/]|[\\/]{1,2}|\\\\)/.test(input.outputArtifactRef))
+                throw new Error("outputArtifactRef must be opaque");
+        }
+        const items = input.items.map((item, index) => {
+            if (!isJsonValue(item))
+                throw new Error(`items[${index}] must be JSON-safe`);
+            return boundStrings(item, budget.maxCellChars);
+        });
+        const truncated = input.truncated === true || items.length > budget.maxInlineItems;
+        const inlineItems = Object.freeze(items.slice(0, budget.maxInlineItems));
+        const result = Object.freeze({
+            version: 1,
+            operationId: input.operationId,
+            status: "succeeded",
+            inlineItems,
+            truncated,
+            ...(input.outputArtifactRef === undefined ? {} : { outputArtifactRef: input.outputArtifactRef }),
+        });
+        if (new TextEncoder().encode(JSON.stringify(result)).byteLength > budget.maxOutputBytes)
+            throw new Error("projected context exceeds maxOutputBytes");
+        return result;
+    }
+    catch (cause) {
+        return invalid(operationId, "context_projection_rejected", cause instanceof Error ? cause.message : "Context projection rejected");
+    }
+}
+export { DEFAULT_PLUGIN_CONTEXT_BUDGET_V1 };
+//# sourceMappingURL=context-budget.js.map

package/dist/context-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget.js","sourceRoot":"","sources":["../src/context-budget.ts"],"names":[],"mappings":"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","sourcesContent":["import type { JsonValue } from \"./common.ts\";\nimport type { PluginErrorV1 } from \"./operation.ts\";\n\n/** Shared egress budget for every plugin result that is projected into model context. */\nexport interface PluginContextBudgetV1 {\n\treadonly maxOutputBytes: number;\n\treadonly maxInlineItems: number;\n\treadonly maxCellChars: number;\n}\n\nexport interface PluginContextProjectionInputV1 {\n\treadonly version: 1;\n\treadonly operationId: string;\n\t/** Already summarized values only. Raw rows/payloads are rejected at this boundary. */\n\treadonly items: readonly JsonValue[];\n\treadonly outputArtifactRef?: string;\n\treadonly truncated?: boolean;\n}\n\nexport interface PluginContextProjectionV1 {\n\treadonly version: 1;\n\treadonly operationId: string;\n\treadonly status: \"succeeded\" | \"failed\";\n\treadonly inlineItems: readonly JsonValue[];\n\treadonly truncated: boolean;\n\treadonly outputArtifactRef?: string;\n\treadonly error?: PluginErrorV1;\n}\n\nconst DEFAULT_PLUGIN_CONTEXT_BUDGET_V1: PluginContextBudgetV1 = Object.freeze({\n\tmaxOutputBytes: 64 * 1024,\n\tmaxInlineItems: 20,\n\tmaxCellChars: 256,\n});\n\nfunction error(code: string, message: string): PluginErrorV1 {\n\treturn { version: 1, code, message };\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction assertPositiveInteger(value: unknown, label: string): asserts value is number {\n\tif (!Number.isSafeInteger(value) || (value as number) <= 0)\n\t\tthrow new Error(`${label} must be a positive safe integer`);\n}\n\nfunction assertNonNegativeInteger(value: unknown, label: string): asserts value is number {\n\tif (!Number.isSafeInteger(value) || (value as number) < 0)\n\t\tthrow new Error(`${label} must be a non-negative safe integer`);\n}\n\nfunction isJsonValue(value: unknown): value is JsonValue {\n\tif (value === null || typeof value === \"string\" || typeof value === \"boolean\") return true;\n\tif (typeof value === \"number\") return Number.isFinite(value);\n\tif (Array.isArray(value)) return value.every(isJsonValue);\n\tif (isRecord(value)) return Object.values(value).every(isJsonValue);\n\treturn false;\n}\n\nfunction containsRawPayload(value: unknown, seen = new Set<object>()): boolean {\n\tif (!isRecord(value) && !Array.isArray(value)) return false;\n\tif (seen.has(value)) return false;\n\tseen.add(value);\n\tif (isRecord(value)) {\n\t\tfor (const [key, child] of Object.entries(value)) {\n\t\t\tif ((key === \"rows\" || key === \"rawRows\" || key === \"rawPayload\" || key === \"payload\") && child !== undefined)\n\t\t\t\treturn true;\n\t\t\tif (containsRawPayload(child, seen)) return true;\n\t\t}\n\t\treturn false;\n\t}\n\treturn value.some((child) => containsRawPayload(child, seen));\n}\n\nfunction validateBudget(input: Partial<PluginContextBudgetV1> | undefined): PluginContextBudgetV1 {\n\tconst budget = { ...DEFAULT_PLUGIN_CONTEXT_BUDGET_V1, ...(input ?? {}) };\n\tassertPositiveInteger(budget.maxOutputBytes, \"maxOutputBytes\");\n\tassertNonNegativeInteger(budget.maxInlineItems, \"maxInlineItems\");\n\tassertPositiveInteger(budget.maxCellChars, \"maxCellChars\");\n\treturn Object.freeze(budget);\n}\n\nfunction boundStrings(value: JsonValue, maxCellChars: number): JsonValue {\n\tif (typeof value === \"string\") {\n\t\tif ([...value].length > maxCellChars) throw new Error(\"context string exceeds maxCellChars\");\n\t\treturn value;\n\t}\n\tif (Array.isArray(value))\n\t\treturn Object.freeze(value.map((child) => boundStrings(child, maxCellChars))) as unknown as JsonValue;\n\tif (isRecord(value)) {\n\t\treturn Object.freeze(\n\t\t\tObject.fromEntries(\n\t\t\t\tObject.entries(value).map(([key, child]) => [key, boundStrings(child as JsonValue, maxCellChars)]),\n\t\t\t),\n\t\t);\n\t}\n\treturn value;\n}\n\nfunction invalid(operationId: string, code: string, message: string): PluginContextProjectionV1 {\n\treturn Object.freeze({\n\t\tversion: 1,\n\t\toperationId,\n\t\tstatus: \"failed\",\n\t\tinlineItems: Object.freeze([]),\n\t\ttruncated: false,\n\t\terror: error(code, message),\n\t});\n}\n\n/**\n * Projects plugin summaries into the model-visible context envelope. This is an\n * egress boundary: it never accepts raw rows or silently exceeds a byte budget.\n */\nexport function projectPluginContextV1(\n\tinput: PluginContextProjectionInputV1,\n\tlimits?: Partial<PluginContextBudgetV1>,\n): PluginContextProjectionV1 {\n\tconst operationId = isRecord(input) && typeof input.operationId === \"string\" ? input.operationId : \"invalid\";\n\ttry {\n\t\tif (!isRecord(input) || input.version !== 1) throw new Error(\"input must have version 1\");\n\t\tif (typeof input.operationId !== \"string\" || input.operationId.trim() === \"\")\n\t\t\tthrow new Error(\"operationId must be a non-empty string\");\n\t\tif (!Array.isArray(input.items)) throw new Error(\"items must be an array\");\n\t\tconst budget = validateBudget(limits);\n\t\tif (containsRawPayload(input.items)) throw new Error(\"raw payloads are not allowed in plugin context\");\n\t\tif (input.outputArtifactRef !== undefined) {\n\t\t\tif (typeof input.outputArtifactRef !== \"string\" || input.outputArtifactRef.trim() === \"\")\n\t\t\t\tthrow new Error(\"outputArtifactRef must be a non-empty string\");\n\t\t\tif (/^(?:[a-zA-Z]:[\\\\/]|[\\\\/]{1,2}|\\\\\\\\)/.test(input.outputArtifactRef))\n\t\t\t\tthrow new Error(\"outputArtifactRef must be opaque\");\n\t\t}\n\t\tconst items = input.items.map((item, index) => {\n\t\t\tif (!isJsonValue(item)) throw new Error(`items[${index}] must be JSON-safe`);\n\t\t\treturn boundStrings(item, budget.maxCellChars);\n\t\t});\n\t\tconst truncated = input.truncated === true || items.length > budget.maxInlineItems;\n\t\tconst inlineItems = Object.freeze(items.slice(0, budget.maxInlineItems));\n\t\tconst result = Object.freeze({\n\t\t\tversion: 1 as const,\n\t\t\toperationId: input.operationId,\n\t\t\tstatus: \"succeeded\" as const,\n\t\t\tinlineItems,\n\t\t\ttruncated,\n\t\t\t...(input.outputArtifactRef === undefined ? {} : { outputArtifactRef: input.outputArtifactRef }),\n\t\t});\n\t\tif (new TextEncoder().encode(JSON.stringify(result)).byteLength > budget.maxOutputBytes)\n\t\t\tthrow new Error(\"projected context exceeds maxOutputBytes\");\n\t\treturn result;\n\t} catch (cause) {\n\t\treturn invalid(\n\t\t\toperationId,\n\t\t\t\"context_projection_rejected\",\n\t\t\tcause instanceof Error ? cause.message : \"Context projection rejected\",\n\t\t);\n\t}\n}\n\nexport { DEFAULT_PLUGIN_CONTEXT_BUDGET_V1 };\n"]}

package/dist/diff.d.ts

@@ -0,0 +1,38 @@
+import { type ArtifactRefV1 } from "./artifact.ts";
+import { type EvidenceRefV1, type PluginErrorV1, type PluginResultStatusV1, type VerificationV1 } from "./operation.ts";
+export type DiffKindV1 = "text" | "dom" | "structure" | "pixel" | "style";
+export interface DiffThresholdV1 {
+    readonly maxChangedPixels?: number;
+    readonly maxChangedRatio?: number;
+    readonly allowedSelectors?: readonly string[];
+}
+export interface DiffRequestV1 {
+    readonly version: 1;
+    readonly operationId: string;
+    readonly kind: DiffKindV1;
+    readonly before: ArtifactRefV1;
+    readonly after: ArtifactRefV1;
+    readonly threshold?: DiffThresholdV1;
+}
+export interface DiffResultV1 {
+    readonly version: 1;
+    readonly operationId: string;
+    readonly status: PluginResultStatusV1;
+    readonly kind: DiffKindV1;
+    readonly summary: string;
+    readonly metrics?: DiffMetricsV1;
+    readonly diffArtifact?: ArtifactRefV1;
+    readonly evidence: readonly EvidenceRefV1[];
+    readonly verification?: VerificationV1;
+    readonly error?: PluginErrorV1;
+}
+export interface DiffMetricsV1 {
+    readonly changedPixels?: number;
+    readonly changedRatio?: number;
+    readonly selector?: string;
+}
+export declare function validateDiffRequestV1(value: unknown, label?: string): DiffRequestV1;
+export declare function buildDiffRequestV1(input: DiffRequestV1): DiffRequestV1;
+export declare function validateDiffResultV1(value: unknown, label?: string): DiffResultV1;
+export declare function buildDiffResultV1(input: DiffResultV1): DiffResultV1;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAyB,MAAM,eAAe,CAAC;AAQ1E,OAAO,EACN,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EAInB,MAAM,gBAAgB,CAAC;AAExB,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,WAAW,GAAG,OAAO,GAAG,OAAO,CAAC;AAE1E,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;CACrC;AAED,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IAC5C,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AA4FD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAiB,GAAG,aAAa,CAmB3F;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAEtE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAgB,GAAG,YAAY,CAuDxF;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAEnE","sourcesContent":["import { type ArtifactRefV1, validateArtifactRefV1 } from \"./artifact.ts\";\nimport {\n\tassertExactKeys,\n\tassertNonEmptyString,\n\tassertNonNegativeNumber,\n\tassertPlainRecord,\n\tdetachedFreeze,\n} from \"./common.ts\";\nimport {\n\ttype EvidenceRefV1,\n\ttype PluginErrorV1,\n\ttype PluginResultStatusV1,\n\ttype VerificationV1,\n\tvalidateEvidenceRefV1,\n\tvalidatePluginErrorV1,\n\tvalidateVerificationV1,\n} from \"./operation.ts\";\n\nexport type DiffKindV1 = \"text\" | \"dom\" | \"structure\" | \"pixel\" | \"style\";\n\nexport interface DiffThresholdV1 {\n\treadonly maxChangedPixels?: number;\n\treadonly maxChangedRatio?: number;\n\treadonly allowedSelectors?: readonly string[];\n}\n\nexport interface DiffRequestV1 {\n\treadonly version: 1;\n\treadonly operationId: string;\n\treadonly kind: DiffKindV1;\n\treadonly before: ArtifactRefV1;\n\treadonly after: ArtifactRefV1;\n\treadonly threshold?: DiffThresholdV1;\n}\n\nexport interface DiffResultV1 {\n\treadonly version: 1;\n\treadonly operationId: string;\n\treadonly status: PluginResultStatusV1;\n\treadonly kind: DiffKindV1;\n\treadonly summary: string;\n\treadonly metrics?: DiffMetricsV1;\n\treadonly diffArtifact?: ArtifactRefV1;\n\treadonly evidence: readonly EvidenceRefV1[];\n\treadonly verification?: VerificationV1;\n\treadonly error?: PluginErrorV1;\n}\n\nexport interface DiffMetricsV1 {\n\treadonly changedPixels?: number;\n\treadonly changedRatio?: number;\n\treadonly selector?: string;\n}\n\nconst DIFF_MAX_ITEMS_V1 = 64;\nconst DIFF_MAX_STRING_CHARS_V1 = 2048;\nconst DIFF_MAX_RESULT_BYTES_V1 = 64 * 1024;\n\nfunction validateBoundedString(value: unknown, label: string): asserts value is string {\n\tassertNonEmptyString(value, label);\n\tif (value.length > DIFF_MAX_STRING_CHARS_V1) throw new Error(`${label} exceeds the context budget`);\n}\n\nconst DIFF_KINDS_V1: readonly DiffKindV1[] = [\"text\", \"dom\", \"structure\", \"pixel\", \"style\"];\nconst RESULT_STATUSES_V1: readonly PluginResultStatusV1[] = [\n\t\"succeeded\",\n\t\"failed\",\n\t\"cancelled\",\n\t\"needs_user\",\n\t\"unsupported\",\n];\n\nfunction validateKind(value: unknown, label: string): DiffKindV1 {\n\tif (typeof value !== \"string\" || !DIFF_KINDS_V1.includes(value as DiffKindV1))\n\t\tthrow new Error(`${label} is invalid`);\n\treturn value as DiffKindV1;\n}\n\nfunction validateStatus(value: unknown, label: string): PluginResultStatusV1 {\n\tif (typeof value !== \"string\" || !RESULT_STATUSES_V1.includes(value as PluginResultStatusV1))\n\t\tthrow new Error(`${label} is invalid`);\n\treturn value as PluginResultStatusV1;\n}\n\nfunction validateMetrics(value: unknown, label: string): DiffMetricsV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(value, [], [\"changedPixels\", \"changedRatio\", \"selector\"], label);\n\tif (value.changedPixels !== undefined) {\n\t\tif (\n\t\t\ttypeof value.changedPixels !== \"number\" ||\n\t\t\t!Number.isSafeInteger(value.changedPixels) ||\n\t\t\tvalue.changedPixels < 0\n\t\t)\n\t\t\tthrow new Error(`${label}.changedPixels must be a non-negative safe integer`);\n\t}\n\tif (value.changedRatio !== undefined) {\n\t\tassertNonNegativeNumber(value.changedRatio, `${label}.changedRatio`);\n\t\tif (value.changedRatio > 1) throw new Error(`${label}.changedRatio must be at most 1`);\n\t}\n\tif (value.selector !== undefined) validateBoundedString(value.selector, `${label}.selector`);\n\treturn detachedFreeze({\n\t\t...(value.changedPixels === undefined ? {} : { changedPixels: value.changedPixels }),\n\t\t...(value.changedRatio === undefined ? {} : { changedRatio: value.changedRatio }),\n\t\t...(value.selector === undefined ? {} : { selector: value.selector }),\n\t});\n}\n\nfunction validateThreshold(value: unknown, label: string): DiffThresholdV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(value, [], [\"maxChangedPixels\", \"maxChangedRatio\", \"allowedSelectors\"], label);\n\tif (value.maxChangedPixels !== undefined) {\n\t\tif (\n\t\t\ttypeof value.maxChangedPixels !== \"number\" ||\n\t\t\t!Number.isSafeInteger(value.maxChangedPixels) ||\n\t\t\tvalue.maxChangedPixels < 0\n\t\t) {\n\t\t\tthrow new Error(`${label}.maxChangedPixels must be a non-negative safe integer`);\n\t\t}\n\t}\n\tif (value.maxChangedRatio !== undefined) {\n\t\tassertNonNegativeNumber(value.maxChangedRatio, `${label}.maxChangedRatio`);\n\t\tif (value.maxChangedRatio > 1) throw new Error(`${label}.maxChangedRatio must be at most 1`);\n\t}\n\tif (value.allowedSelectors !== undefined) {\n\t\tif (\n\t\t\t!Array.isArray(value.allowedSelectors) ||\n\t\t\tvalue.allowedSelectors.some((item) => typeof item !== \"string\" || item.trim() === \"\")\n\t\t) {\n\t\t\tthrow new Error(`${label}.allowedSelectors must contain non-empty strings`);\n\t\t}\n\t\tif (new Set(value.allowedSelectors).size !== value.allowedSelectors.length)\n\t\t\tthrow new Error(`${label}.allowedSelectors must not contain duplicates`);\n\t\tif (value.allowedSelectors.length > DIFF_MAX_ITEMS_V1)\n\t\t\tthrow new Error(`${label}.allowedSelectors must contain at most ${DIFF_MAX_ITEMS_V1} items`);\n\t\tfor (const [index, selector] of value.allowedSelectors.entries())\n\t\t\tvalidateBoundedString(selector, `${label}.allowedSelectors[${index}]`);\n\t}\n\treturn detachedFreeze({\n\t\t...(value.maxChangedPixels === undefined ? {} : { maxChangedPixels: value.maxChangedPixels }),\n\t\t...(value.maxChangedRatio === undefined ? {} : { maxChangedRatio: value.maxChangedRatio }),\n\t\t...(value.allowedSelectors === undefined ? {} : { allowedSelectors: [...value.allowedSelectors].sort() }),\n\t});\n}\n\nexport function validateDiffRequestV1(value: unknown, label = \"Diff request\"): DiffRequestV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(value, [\"version\", \"operationId\", \"kind\", \"before\", \"after\"], [\"threshold\"], label);\n\tif (value.version !== 1) throw new Error(`${label}.version must be 1`);\n\tassertNonEmptyString(value.operationId, `${label}.operationId`);\n\tconst kind = validateKind(value.kind, `${label}.kind`);\n\tconst before = validateArtifactRefV1(value.before, `${label}.before`);\n\tconst after = validateArtifactRefV1(value.after, `${label}.after`);\n\tif (before.artifactRef === after.artifactRef) throw new Error(`${label}.before and after must differ`);\n\tconst threshold =\n\t\tvalue.threshold === undefined ? undefined : validateThreshold(value.threshold, `${label}.threshold`);\n\treturn detachedFreeze({\n\t\tversion: 1 as const,\n\t\toperationId: value.operationId,\n\t\tkind,\n\t\tbefore,\n\t\tafter,\n\t\t...(threshold === undefined ? {} : { threshold }),\n\t});\n}\n\nexport function buildDiffRequestV1(input: DiffRequestV1): DiffRequestV1 {\n\treturn validateDiffRequestV1(input);\n}\n\nexport function validateDiffResultV1(value: unknown, label = \"Diff result\"): DiffResultV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(\n\t\tvalue,\n\t\t[\"version\", \"operationId\", \"status\", \"kind\", \"summary\", \"evidence\"],\n\t\t[\"diffArtifact\", \"metrics\", \"verification\", \"error\"],\n\t\tlabel,\n\t);\n\tif (value.version !== 1) throw new Error(`${label}.version must be 1`);\n\tassertNonEmptyString(value.operationId, `${label}.operationId`);\n\tconst resultStatus = validateStatus(value.status, `${label}.status`);\n\tconst kind = validateKind(value.kind, `${label}.kind`);\n\tvalidateBoundedString(value.summary, `${label}.summary`);\n\tconst metrics = value.metrics === undefined ? undefined : validateMetrics(value.metrics, `${label}.metrics`);\n\tconst diffArtifact =\n\t\tvalue.diffArtifact === undefined ? undefined : validateArtifactRefV1(value.diffArtifact, `${label}.diffArtifact`);\n\tif (!Array.isArray(value.evidence)) throw new Error(`${label}.evidence must be an array`);\n\tif (value.evidence.length > DIFF_MAX_ITEMS_V1)\n\t\tthrow new Error(`${label}.evidence must contain at most ${DIFF_MAX_ITEMS_V1} items`);\n\tconst evidence = value.evidence.map((item, index) => validateEvidenceRefV1(item, `${label}.evidence[${index}]`));\n\tif (new Set(evidence.map((item) => item.evidenceId)).size !== evidence.length)\n\t\tthrow new Error(`${label}.evidence must not contain duplicate evidenceId values`);\n\tfor (const [index, item] of evidence.entries()) {\n\t\tvalidateBoundedString(item.evidenceId, `${label}.evidence[${index}].evidenceId`);\n\t\tif (item.summary !== undefined) validateBoundedString(item.summary, `${label}.evidence[${index}].summary`);\n\t\tif (item.observedAt !== undefined)\n\t\t\tvalidateBoundedString(item.observedAt, `${label}.evidence[${index}].observedAt`);\n\t}\n\tconst orderedEvidence = Object.freeze([...evidence].sort((a, b) => a.evidenceId.localeCompare(b.evidenceId)));\n\tconst verification =\n\t\tvalue.verification === undefined\n\t\t\t? undefined\n\t\t\t: validateVerificationV1(value.verification, `${label}.verification`);\n\tconst error = value.error === undefined ? undefined : validatePluginErrorV1(value.error, `${label}.error`);\n\tif (resultStatus !== \"succeeded\" && error === undefined)\n\t\tthrow new Error(`${label}.error is required for status ${resultStatus}`);\n\tif (resultStatus === \"succeeded\" && error !== undefined)\n\t\tthrow new Error(`${label}.succeeded must not include error`);\n\tif (resultStatus === \"succeeded\" && verification?.status === \"failed\")\n\t\tthrow new Error(`${label}.succeeded cannot have failed verification`);\n\tconst result = {\n\t\tversion: 1 as const,\n\t\toperationId: value.operationId,\n\t\tstatus: resultStatus,\n\t\tkind,\n\t\tsummary: value.summary,\n\t\t...(metrics === undefined ? {} : { metrics }),\n\t\t...(diffArtifact === undefined ? {} : { diffArtifact }),\n\t\tevidence: orderedEvidence,\n\t\t...(verification === undefined ? {} : { verification }),\n\t\t...(error === undefined ? {} : { error }),\n\t};\n\tif (new TextEncoder().encode(JSON.stringify(result)).byteLength > DIFF_MAX_RESULT_BYTES_V1)\n\t\tthrow new Error(`${label} exceeds the context budget`);\n\treturn detachedFreeze(result);\n}\n\nexport function buildDiffResultV1(input: DiffResultV1): DiffResultV1 {\n\treturn validateDiffResultV1(input);\n}\n"]}

package/dist/diff.js

@@ -0,0 +1,164 @@
+import { validateArtifactRefV1 } from "./artifact.js";
+import { assertExactKeys, assertNonEmptyString, assertNonNegativeNumber, assertPlainRecord, detachedFreeze, } from "./common.js";
+import { validateEvidenceRefV1, validatePluginErrorV1, validateVerificationV1, } from "./operation.js";
+const DIFF_MAX_ITEMS_V1 = 64;
+const DIFF_MAX_STRING_CHARS_V1 = 2048;
+const DIFF_MAX_RESULT_BYTES_V1 = 64 * 1024;
+function validateBoundedString(value, label) {
+    assertNonEmptyString(value, label);
+    if (value.length > DIFF_MAX_STRING_CHARS_V1)
+        throw new Error(`${label} exceeds the context budget`);
+}
+const DIFF_KINDS_V1 = ["text", "dom", "structure", "pixel", "style"];
+const RESULT_STATUSES_V1 = [
+    "succeeded",
+    "failed",
+    "cancelled",
+    "needs_user",
+    "unsupported",
+];
+function validateKind(value, label) {
+    if (typeof value !== "string" || !DIFF_KINDS_V1.includes(value))
+        throw new Error(`${label} is invalid`);
+    return value;
+}
+function validateStatus(value, label) {
+    if (typeof value !== "string" || !RESULT_STATUSES_V1.includes(value))
+        throw new Error(`${label} is invalid`);
+    return value;
+}
+function validateMetrics(value, label) {
+    assertPlainRecord(value, label);
+    assertExactKeys(value, [], ["changedPixels", "changedRatio", "selector"], label);
+    if (value.changedPixels !== undefined) {
+        if (typeof value.changedPixels !== "number" ||
+            !Number.isSafeInteger(value.changedPixels) ||
+            value.changedPixels < 0)
+            throw new Error(`${label}.changedPixels must be a non-negative safe integer`);
+    }
+    if (value.changedRatio !== undefined) {
+        assertNonNegativeNumber(value.changedRatio, `${label}.changedRatio`);
+        if (value.changedRatio > 1)
+            throw new Error(`${label}.changedRatio must be at most 1`);
+    }
+    if (value.selector !== undefined)
+        validateBoundedString(value.selector, `${label}.selector`);
+    return detachedFreeze({
+        ...(value.changedPixels === undefined ? {} : { changedPixels: value.changedPixels }),
+        ...(value.changedRatio === undefined ? {} : { changedRatio: value.changedRatio }),
+        ...(value.selector === undefined ? {} : { selector: value.selector }),
+    });
+}
+function validateThreshold(value, label) {
+    assertPlainRecord(value, label);
+    assertExactKeys(value, [], ["maxChangedPixels", "maxChangedRatio", "allowedSelectors"], label);
+    if (value.maxChangedPixels !== undefined) {
+        if (typeof value.maxChangedPixels !== "number" ||
+            !Number.isSafeInteger(value.maxChangedPixels) ||
+            value.maxChangedPixels < 0) {
+            throw new Error(`${label}.maxChangedPixels must be a non-negative safe integer`);
+        }
+    }
+    if (value.maxChangedRatio !== undefined) {
+        assertNonNegativeNumber(value.maxChangedRatio, `${label}.maxChangedRatio`);
+        if (value.maxChangedRatio > 1)
+            throw new Error(`${label}.maxChangedRatio must be at most 1`);
+    }
+    if (value.allowedSelectors !== undefined) {
+        if (!Array.isArray(value.allowedSelectors) ||
+            value.allowedSelectors.some((item) => typeof item !== "string" || item.trim() === "")) {
+            throw new Error(`${label}.allowedSelectors must contain non-empty strings`);
+        }
+        if (new Set(value.allowedSelectors).size !== value.allowedSelectors.length)
+            throw new Error(`${label}.allowedSelectors must not contain duplicates`);
+        if (value.allowedSelectors.length > DIFF_MAX_ITEMS_V1)
+            throw new Error(`${label}.allowedSelectors must contain at most ${DIFF_MAX_ITEMS_V1} items`);
+        for (const [index, selector] of value.allowedSelectors.entries())
+            validateBoundedString(selector, `${label}.allowedSelectors[${index}]`);
+    }
+    return detachedFreeze({
+        ...(value.maxChangedPixels === undefined ? {} : { maxChangedPixels: value.maxChangedPixels }),
+        ...(value.maxChangedRatio === undefined ? {} : { maxChangedRatio: value.maxChangedRatio }),
+        ...(value.allowedSelectors === undefined ? {} : { allowedSelectors: [...value.allowedSelectors].sort() }),
+    });
+}
+export function validateDiffRequestV1(value, label = "Diff request") {
+    assertPlainRecord(value, label);
+    assertExactKeys(value, ["version", "operationId", "kind", "before", "after"], ["threshold"], label);
+    if (value.version !== 1)
+        throw new Error(`${label}.version must be 1`);
+    assertNonEmptyString(value.operationId, `${label}.operationId`);
+    const kind = validateKind(value.kind, `${label}.kind`);
+    const before = validateArtifactRefV1(value.before, `${label}.before`);
+    const after = validateArtifactRefV1(value.after, `${label}.after`);
+    if (before.artifactRef === after.artifactRef)
+        throw new Error(`${label}.before and after must differ`);
+    const threshold = value.threshold === undefined ? undefined : validateThreshold(value.threshold, `${label}.threshold`);
+    return detachedFreeze({
+        version: 1,
+        operationId: value.operationId,
+        kind,
+        before,
+        after,
+        ...(threshold === undefined ? {} : { threshold }),
+    });
+}
+export function buildDiffRequestV1(input) {
+    return validateDiffRequestV1(input);
+}
+export function validateDiffResultV1(value, label = "Diff result") {
+    assertPlainRecord(value, label);
+    assertExactKeys(value, ["version", "operationId", "status", "kind", "summary", "evidence"], ["diffArtifact", "metrics", "verification", "error"], label);
+    if (value.version !== 1)
+        throw new Error(`${label}.version must be 1`);
+    assertNonEmptyString(value.operationId, `${label}.operationId`);
+    const resultStatus = validateStatus(value.status, `${label}.status`);
+    const kind = validateKind(value.kind, `${label}.kind`);
+    validateBoundedString(value.summary, `${label}.summary`);
+    const metrics = value.metrics === undefined ? undefined : validateMetrics(value.metrics, `${label}.metrics`);
+    const diffArtifact = value.diffArtifact === undefined ? undefined : validateArtifactRefV1(value.diffArtifact, `${label}.diffArtifact`);
+    if (!Array.isArray(value.evidence))
+        throw new Error(`${label}.evidence must be an array`);
+    if (value.evidence.length > DIFF_MAX_ITEMS_V1)
+        throw new Error(`${label}.evidence must contain at most ${DIFF_MAX_ITEMS_V1} items`);
+    const evidence = value.evidence.map((item, index) => validateEvidenceRefV1(item, `${label}.evidence[${index}]`));
+    if (new Set(evidence.map((item) => item.evidenceId)).size !== evidence.length)
+        throw new Error(`${label}.evidence must not contain duplicate evidenceId values`);
+    for (const [index, item] of evidence.entries()) {
+        validateBoundedString(item.evidenceId, `${label}.evidence[${index}].evidenceId`);
+        if (item.summary !== undefined)
+            validateBoundedString(item.summary, `${label}.evidence[${index}].summary`);
+        if (item.observedAt !== undefined)
+            validateBoundedString(item.observedAt, `${label}.evidence[${index}].observedAt`);
+    }
+    const orderedEvidence = Object.freeze([...evidence].sort((a, b) => a.evidenceId.localeCompare(b.evidenceId)));
+    const verification = value.verification === undefined
+        ? undefined
+        : validateVerificationV1(value.verification, `${label}.verification`);
+    const error = value.error === undefined ? undefined : validatePluginErrorV1(value.error, `${label}.error`);
+    if (resultStatus !== "succeeded" && error === undefined)
+        throw new Error(`${label}.error is required for status ${resultStatus}`);
+    if (resultStatus === "succeeded" && error !== undefined)
+        throw new Error(`${label}.succeeded must not include error`);
+    if (resultStatus === "succeeded" && verification?.status === "failed")
+        throw new Error(`${label}.succeeded cannot have failed verification`);
+    const result = {
+        version: 1,
+        operationId: value.operationId,
+        status: resultStatus,
+        kind,
+        summary: value.summary,
+        ...(metrics === undefined ? {} : { metrics }),
+        ...(diffArtifact === undefined ? {} : { diffArtifact }),
+        evidence: orderedEvidence,
+        ...(verification === undefined ? {} : { verification }),
+        ...(error === undefined ? {} : { error }),
+    };
+    if (new TextEncoder().encode(JSON.stringify(result)).byteLength > DIFF_MAX_RESULT_BYTES_V1)
+        throw new Error(`${label} exceeds the context budget`);
+    return detachedFreeze(result);
+}
+export function buildDiffResultV1(input) {
+    return validateDiffResultV1(input);
+}
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"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","sourcesContent":["import { type ArtifactRefV1, validateArtifactRefV1 } from \"./artifact.ts\";\nimport {\n\tassertExactKeys,\n\tassertNonEmptyString,\n\tassertNonNegativeNumber,\n\tassertPlainRecord,\n\tdetachedFreeze,\n} from \"./common.ts\";\nimport {\n\ttype EvidenceRefV1,\n\ttype PluginErrorV1,\n\ttype PluginResultStatusV1,\n\ttype VerificationV1,\n\tvalidateEvidenceRefV1,\n\tvalidatePluginErrorV1,\n\tvalidateVerificationV1,\n} from \"./operation.ts\";\n\nexport type DiffKindV1 = \"text\" | \"dom\" | \"structure\" | \"pixel\" | \"style\";\n\nexport interface DiffThresholdV1 {\n\treadonly maxChangedPixels?: number;\n\treadonly maxChangedRatio?: number;\n\treadonly allowedSelectors?: readonly string[];\n}\n\nexport interface DiffRequestV1 {\n\treadonly version: 1;\n\treadonly operationId: string;\n\treadonly kind: DiffKindV1;\n\treadonly before: ArtifactRefV1;\n\treadonly after: ArtifactRefV1;\n\treadonly threshold?: DiffThresholdV1;\n}\n\nexport interface DiffResultV1 {\n\treadonly version: 1;\n\treadonly operationId: string;\n\treadonly status: PluginResultStatusV1;\n\treadonly kind: DiffKindV1;\n\treadonly summary: string;\n\treadonly metrics?: DiffMetricsV1;\n\treadonly diffArtifact?: ArtifactRefV1;\n\treadonly evidence: readonly EvidenceRefV1[];\n\treadonly verification?: VerificationV1;\n\treadonly error?: PluginErrorV1;\n}\n\nexport interface DiffMetricsV1 {\n\treadonly changedPixels?: number;\n\treadonly changedRatio?: number;\n\treadonly selector?: string;\n}\n\nconst DIFF_MAX_ITEMS_V1 = 64;\nconst DIFF_MAX_STRING_CHARS_V1 = 2048;\nconst DIFF_MAX_RESULT_BYTES_V1 = 64 * 1024;\n\nfunction validateBoundedString(value: unknown, label: string): asserts value is string {\n\tassertNonEmptyString(value, label);\n\tif (value.length > DIFF_MAX_STRING_CHARS_V1) throw new Error(`${label} exceeds the context budget`);\n}\n\nconst DIFF_KINDS_V1: readonly DiffKindV1[] = [\"text\", \"dom\", \"structure\", \"pixel\", \"style\"];\nconst RESULT_STATUSES_V1: readonly PluginResultStatusV1[] = [\n\t\"succeeded\",\n\t\"failed\",\n\t\"cancelled\",\n\t\"needs_user\",\n\t\"unsupported\",\n];\n\nfunction validateKind(value: unknown, label: string): DiffKindV1 {\n\tif (typeof value !== \"string\" || !DIFF_KINDS_V1.includes(value as DiffKindV1))\n\t\tthrow new Error(`${label} is invalid`);\n\treturn value as DiffKindV1;\n}\n\nfunction validateStatus(value: unknown, label: string): PluginResultStatusV1 {\n\tif (typeof value !== \"string\" || !RESULT_STATUSES_V1.includes(value as PluginResultStatusV1))\n\t\tthrow new Error(`${label} is invalid`);\n\treturn value as PluginResultStatusV1;\n}\n\nfunction validateMetrics(value: unknown, label: string): DiffMetricsV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(value, [], [\"changedPixels\", \"changedRatio\", \"selector\"], label);\n\tif (value.changedPixels !== undefined) {\n\t\tif (\n\t\t\ttypeof value.changedPixels !== \"number\" ||\n\t\t\t!Number.isSafeInteger(value.changedPixels) ||\n\t\t\tvalue.changedPixels < 0\n\t\t)\n\t\t\tthrow new Error(`${label}.changedPixels must be a non-negative safe integer`);\n\t}\n\tif (value.changedRatio !== undefined) {\n\t\tassertNonNegativeNumber(value.changedRatio, `${label}.changedRatio`);\n\t\tif (value.changedRatio > 1) throw new Error(`${label}.changedRatio must be at most 1`);\n\t}\n\tif (value.selector !== undefined) validateBoundedString(value.selector, `${label}.selector`);\n\treturn detachedFreeze({\n\t\t...(value.changedPixels === undefined ? {} : { changedPixels: value.changedPixels }),\n\t\t...(value.changedRatio === undefined ? {} : { changedRatio: value.changedRatio }),\n\t\t...(value.selector === undefined ? {} : { selector: value.selector }),\n\t});\n}\n\nfunction validateThreshold(value: unknown, label: string): DiffThresholdV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(value, [], [\"maxChangedPixels\", \"maxChangedRatio\", \"allowedSelectors\"], label);\n\tif (value.maxChangedPixels !== undefined) {\n\t\tif (\n\t\t\ttypeof value.maxChangedPixels !== \"number\" ||\n\t\t\t!Number.isSafeInteger(value.maxChangedPixels) ||\n\t\t\tvalue.maxChangedPixels < 0\n\t\t) {\n\t\t\tthrow new Error(`${label}.maxChangedPixels must be a non-negative safe integer`);\n\t\t}\n\t}\n\tif (value.maxChangedRatio !== undefined) {\n\t\tassertNonNegativeNumber(value.maxChangedRatio, `${label}.maxChangedRatio`);\n\t\tif (value.maxChangedRatio > 1) throw new Error(`${label}.maxChangedRatio must be at most 1`);\n\t}\n\tif (value.allowedSelectors !== undefined) {\n\t\tif (\n\t\t\t!Array.isArray(value.allowedSelectors) ||\n\t\t\tvalue.allowedSelectors.some((item) => typeof item !== \"string\" || item.trim() === \"\")\n\t\t) {\n\t\t\tthrow new Error(`${label}.allowedSelectors must contain non-empty strings`);\n\t\t}\n\t\tif (new Set(value.allowedSelectors).size !== value.allowedSelectors.length)\n\t\t\tthrow new Error(`${label}.allowedSelectors must not contain duplicates`);\n\t\tif (value.allowedSelectors.length > DIFF_MAX_ITEMS_V1)\n\t\t\tthrow new Error(`${label}.allowedSelectors must contain at most ${DIFF_MAX_ITEMS_V1} items`);\n\t\tfor (const [index, selector] of value.allowedSelectors.entries())\n\t\t\tvalidateBoundedString(selector, `${label}.allowedSelectors[${index}]`);\n\t}\n\treturn detachedFreeze({\n\t\t...(value.maxChangedPixels === undefined ? {} : { maxChangedPixels: value.maxChangedPixels }),\n\t\t...(value.maxChangedRatio === undefined ? {} : { maxChangedRatio: value.maxChangedRatio }),\n\t\t...(value.allowedSelectors === undefined ? {} : { allowedSelectors: [...value.allowedSelectors].sort() }),\n\t});\n}\n\nexport function validateDiffRequestV1(value: unknown, label = \"Diff request\"): DiffRequestV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(value, [\"version\", \"operationId\", \"kind\", \"before\", \"after\"], [\"threshold\"], label);\n\tif (value.version !== 1) throw new Error(`${label}.version must be 1`);\n\tassertNonEmptyString(value.operationId, `${label}.operationId`);\n\tconst kind = validateKind(value.kind, `${label}.kind`);\n\tconst before = validateArtifactRefV1(value.before, `${label}.before`);\n\tconst after = validateArtifactRefV1(value.after, `${label}.after`);\n\tif (before.artifactRef === after.artifactRef) throw new Error(`${label}.before and after must differ`);\n\tconst threshold =\n\t\tvalue.threshold === undefined ? undefined : validateThreshold(value.threshold, `${label}.threshold`);\n\treturn detachedFreeze({\n\t\tversion: 1 as const,\n\t\toperationId: value.operationId,\n\t\tkind,\n\t\tbefore,\n\t\tafter,\n\t\t...(threshold === undefined ? {} : { threshold }),\n\t});\n}\n\nexport function buildDiffRequestV1(input: DiffRequestV1): DiffRequestV1 {\n\treturn validateDiffRequestV1(input);\n}\n\nexport function validateDiffResultV1(value: unknown, label = \"Diff result\"): DiffResultV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(\n\t\tvalue,\n\t\t[\"version\", \"operationId\", \"status\", \"kind\", \"summary\", \"evidence\"],\n\t\t[\"diffArtifact\", \"metrics\", \"verification\", \"error\"],\n\t\tlabel,\n\t);\n\tif (value.version !== 1) throw new Error(`${label}.version must be 1`);\n\tassertNonEmptyString(value.operationId, `${label}.operationId`);\n\tconst resultStatus = validateStatus(value.status, `${label}.status`);\n\tconst kind = validateKind(value.kind, `${label}.kind`);\n\tvalidateBoundedString(value.summary, `${label}.summary`);\n\tconst metrics = value.metrics === undefined ? undefined : validateMetrics(value.metrics, `${label}.metrics`);\n\tconst diffArtifact =\n\t\tvalue.diffArtifact === undefined ? undefined : validateArtifactRefV1(value.diffArtifact, `${label}.diffArtifact`);\n\tif (!Array.isArray(value.evidence)) throw new Error(`${label}.evidence must be an array`);\n\tif (value.evidence.length > DIFF_MAX_ITEMS_V1)\n\t\tthrow new Error(`${label}.evidence must contain at most ${DIFF_MAX_ITEMS_V1} items`);\n\tconst evidence = value.evidence.map((item, index) => validateEvidenceRefV1(item, `${label}.evidence[${index}]`));\n\tif (new Set(evidence.map((item) => item.evidenceId)).size !== evidence.length)\n\t\tthrow new Error(`${label}.evidence must not contain duplicate evidenceId values`);\n\tfor (const [index, item] of evidence.entries()) {\n\t\tvalidateBoundedString(item.evidenceId, `${label}.evidence[${index}].evidenceId`);\n\t\tif (item.summary !== undefined) validateBoundedString(item.summary, `${label}.evidence[${index}].summary`);\n\t\tif (item.observedAt !== undefined)\n\t\t\tvalidateBoundedString(item.observedAt, `${label}.evidence[${index}].observedAt`);\n\t}\n\tconst orderedEvidence = Object.freeze([...evidence].sort((a, b) => a.evidenceId.localeCompare(b.evidenceId)));\n\tconst verification =\n\t\tvalue.verification === undefined\n\t\t\t? undefined\n\t\t\t: validateVerificationV1(value.verification, `${label}.verification`);\n\tconst error = value.error === undefined ? undefined : validatePluginErrorV1(value.error, `${label}.error`);\n\tif (resultStatus !== \"succeeded\" && error === undefined)\n\t\tthrow new Error(`${label}.error is required for status ${resultStatus}`);\n\tif (resultStatus === \"succeeded\" && error !== undefined)\n\t\tthrow new Error(`${label}.succeeded must not include error`);\n\tif (resultStatus === \"succeeded\" && verification?.status === \"failed\")\n\t\tthrow new Error(`${label}.succeeded cannot have failed verification`);\n\tconst result = {\n\t\tversion: 1 as const,\n\t\toperationId: value.operationId,\n\t\tstatus: resultStatus,\n\t\tkind,\n\t\tsummary: value.summary,\n\t\t...(metrics === undefined ? {} : { metrics }),\n\t\t...(diffArtifact === undefined ? {} : { diffArtifact }),\n\t\tevidence: orderedEvidence,\n\t\t...(verification === undefined ? {} : { verification }),\n\t\t...(error === undefined ? {} : { error }),\n\t};\n\tif (new TextEncoder().encode(JSON.stringify(result)).byteLength > DIFF_MAX_RESULT_BYTES_V1)\n\t\tthrow new Error(`${label} exceeds the context budget`);\n\treturn detachedFreeze(result);\n}\n\nexport function buildDiffResultV1(input: DiffResultV1): DiffResultV1 {\n\treturn validateDiffResultV1(input);\n}\n"]}

package/dist/durable.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Durable service contract types (7.4b) — the plugin-facing persistence
+ * surface of the host's durable store.
+ *
+ * Authority: `@agent-forge/plugin-sdk` (D-075 S4 third batch, type-only
+ * migration from the host's `src/durable/durable-service.ts`). The host keeps
+ * the implementation (`createDurableService`, writer lease, backends) and its
+ * historical module exports; these pure type definitions are the contract a
+ * capability plugin programs against (e.g. the first-party subagent-delegate
+ * plugin's scheduler persists terminal records through `results.store`).
+ * No runtime behavior lives here — importing this module never pulls in
+ * `node:fs`.
+ */
+export interface DurableSessionRecordV1 {
+    readonly sessionId: string;
+    readonly data: unknown;
+    readonly persistedAt: number;
+}
+export interface DurableOperationRecordV1 {
+    readonly operationId: string;
+    readonly sessionId: string;
+    readonly data: unknown;
+    readonly persistedAt: number;
+}
+export interface DurableArtifactRecordV1 {
+    readonly artifactId: string;
+    readonly sessionId: string;
+    readonly data: unknown;
+    readonly persistedAt: number;
+}
+export interface DurableSnapshotV1 {
+    readonly version: 1;
+    readonly exportedAt: number;
+    readonly sessions: readonly DurableSessionRecordV1[];
+    readonly operations: readonly DurableOperationRecordV1[];
+    readonly artifacts: readonly DurableArtifactRecordV1[];
+    readonly writer: {
+        readonly holder: string | null;
+        readonly crashPending: string | null;
+    };
+}
+export type DurableWriterClaimV1 = {
+    readonly status: "claimed";
+} | {
+    readonly status: "held";
+    readonly by: string;
+};
+export type DurableWriterRecoveryV1 = {
+    readonly status: "recovered";
+    readonly previousWriter?: string;
+} | {
+    readonly status: "held";
+};
+export interface DurableReadinessV1 {
+    readonly ready: boolean;
+    readonly reason?: string;
+}
+/** Diagnostics from the startup log replay of a backend-backed service. */
+export interface DurableReplayDiagnosticsV1 {
+    /** Malformed log lines skipped while replaying. */
+    readonly corruptedLines: number;
+    /** True when the log existed but could not be read. */
+    readonly unreadable: boolean;
+}
+export interface DurableServiceV1 {
+    persistSession(input: {
+        readonly writerId: string;
+        readonly sessionId: string;
+        readonly data: unknown;
+    }): DurableSessionRecordV1;
+    loadSession(input: {
+        readonly sessionId: string;
+    }): DurableSessionRecordV1 | undefined;
+    persistOperation(input: {
+        readonly writerId: string;
+        readonly operationId: string;
+        readonly sessionId: string;
+        readonly data: unknown;
+    }): DurableOperationRecordV1;
+    loadOperation(input: {
+        readonly operationId: string;
+    }): DurableOperationRecordV1 | undefined;
+    persistArtifact(input: {
+        readonly writerId: string;
+        readonly artifactId: string;
+        readonly sessionId: string;
+        readonly data: unknown;
+    }): DurableArtifactRecordV1;
+    loadArtifact(input: {
+        readonly artifactId: string;
+    }): DurableArtifactRecordV1 | undefined;
+    /** All session records, ordered by sessionId for stable output. */
+    listSessions(): readonly DurableSessionRecordV1[];
+    claimWriter(writerId: string): DurableWriterClaimV1;
+    releaseWriter(writerId: string): {
+        readonly status: "released";
+    };
+    recoverWriter(writerId: string): DurableWriterRecoveryV1;
+    readiness(): DurableReadinessV1;
+    exportState(): DurableSnapshotV1;
+    importState(snapshot: unknown): void;
+    /**
+     * Diagnostics from the startup log replay of the backend (zeros/false
+     * without a backend). Corrupted lines were skipped, not fatal.
+     */
+    replayDiagnostics(): DurableReplayDiagnosticsV1;
+}
+//# sourceMappingURL=durable.d.ts.map

package/dist/durable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable.d.ts","sourceRoot":"","sources":["../src/durable.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Durable service contract types (7.4b) — the plugin-facing persistence\n * surface of the host's durable store.\n *\n * Authority: `@agent-forge/plugin-sdk` (D-075 S4 third batch, type-only\n * migration from the host's `src/durable/durable-service.ts`). The host keeps\n * the implementation (`createDurableService`, writer lease, backends) and its\n * historical module exports; these pure type definitions are the contract a\n * capability plugin programs against (e.g. the first-party subagent-delegate\n * plugin's scheduler persists terminal records through `results.store`).\n * No runtime behavior lives here — importing this module never pulls in\n * `node:fs`.\n */\n\nexport interface DurableSessionRecordV1 {\n\treadonly sessionId: string;\n\treadonly data: unknown;\n\treadonly persistedAt: number;\n}\n\nexport interface DurableOperationRecordV1 {\n\treadonly operationId: string;\n\treadonly sessionId: string;\n\treadonly data: unknown;\n\treadonly persistedAt: number;\n}\n\nexport interface DurableArtifactRecordV1 {\n\treadonly artifactId: string;\n\treadonly sessionId: string;\n\treadonly data: unknown;\n\treadonly persistedAt: number;\n}\n\nexport interface DurableSnapshotV1 {\n\treadonly version: 1;\n\treadonly exportedAt: number;\n\treadonly sessions: readonly DurableSessionRecordV1[];\n\treadonly operations: readonly DurableOperationRecordV1[];\n\treadonly artifacts: readonly DurableArtifactRecordV1[];\n\treadonly writer: { readonly holder: string | null; readonly crashPending: string | null };\n}\n\nexport type DurableWriterClaimV1 = { readonly status: \"claimed\" } | { readonly status: \"held\"; readonly by: string };\n\nexport type DurableWriterRecoveryV1 =\n\t| { readonly status: \"recovered\"; readonly previousWriter?: string }\n\t| { readonly status: \"held\" };\n\nexport interface DurableReadinessV1 {\n\treadonly ready: boolean;\n\treadonly reason?: string;\n}\n\n/** Diagnostics from the startup log replay of a backend-backed service. */\nexport interface DurableReplayDiagnosticsV1 {\n\t/** Malformed log lines skipped while replaying. */\n\treadonly corruptedLines: number;\n\t/** True when the log existed but could not be read. */\n\treadonly unreadable: boolean;\n}\n\nexport interface DurableServiceV1 {\n\tpersistSession(input: {\n\t\treadonly writerId: string;\n\t\treadonly sessionId: string;\n\t\treadonly data: unknown;\n\t}): DurableSessionRecordV1;\n\tloadSession(input: { readonly sessionId: string }): DurableSessionRecordV1 | undefined;\n\tpersistOperation(input: {\n\t\treadonly writerId: string;\n\t\treadonly operationId: string;\n\t\treadonly sessionId: string;\n\t\treadonly data: unknown;\n\t}): DurableOperationRecordV1;\n\tloadOperation(input: { readonly operationId: string }): DurableOperationRecordV1 | undefined;\n\tpersistArtifact(input: {\n\t\treadonly writerId: string;\n\t\treadonly artifactId: string;\n\t\treadonly sessionId: string;\n\t\treadonly data: unknown;\n\t}): DurableArtifactRecordV1;\n\tloadArtifact(input: { readonly artifactId: string }): DurableArtifactRecordV1 | undefined;\n\t/** All session records, ordered by sessionId for stable output. */\n\tlistSessions(): readonly DurableSessionRecordV1[];\n\tclaimWriter(writerId: string): DurableWriterClaimV1;\n\treleaseWriter(writerId: string): { readonly status: \"released\" };\n\trecoverWriter(writerId: string): DurableWriterRecoveryV1;\n\treadiness(): DurableReadinessV1;\n\texportState(): DurableSnapshotV1;\n\timportState(snapshot: unknown): void;\n\t/**\n\t * Diagnostics from the startup log replay of the backend (zeros/false\n\t * without a backend). Corrupted lines were skipped, not fatal.\n\t */\n\treplayDiagnostics(): DurableReplayDiagnosticsV1;\n}\n"]}

package/dist/durable.js

@@ -0,0 +1,15 @@
+/**
+ * Durable service contract types (7.4b) — the plugin-facing persistence
+ * surface of the host's durable store.
+ *
+ * Authority: `@agent-forge/plugin-sdk` (D-075 S4 third batch, type-only
+ * migration from the host's `src/durable/durable-service.ts`). The host keeps
+ * the implementation (`createDurableService`, writer lease, backends) and its
+ * historical module exports; these pure type definitions are the contract a
+ * capability plugin programs against (e.g. the first-party subagent-delegate
+ * plugin's scheduler persists terminal records through `results.store`).
+ * No runtime behavior lives here — importing this module never pulls in
+ * `node:fs`.
+ */
+export {};
+//# sourceMappingURL=durable.js.map

package/dist/durable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable.js","sourceRoot":"","sources":["../src/durable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG","sourcesContent":["/**\n * Durable service contract types (7.4b) — the plugin-facing persistence\n * surface of the host's durable store.\n *\n * Authority: `@agent-forge/plugin-sdk` (D-075 S4 third batch, type-only\n * migration from the host's `src/durable/durable-service.ts`). The host keeps\n * the implementation (`createDurableService`, writer lease, backends) and its\n * historical module exports; these pure type definitions are the contract a\n * capability plugin programs against (e.g. the first-party subagent-delegate\n * plugin's scheduler persists terminal records through `results.store`).\n * No runtime behavior lives here — importing this module never pulls in\n * `node:fs`.\n */\n\nexport interface DurableSessionRecordV1 {\n\treadonly sessionId: string;\n\treadonly data: unknown;\n\treadonly persistedAt: number;\n}\n\nexport interface DurableOperationRecordV1 {\n\treadonly operationId: string;\n\treadonly sessionId: string;\n\treadonly data: unknown;\n\treadonly persistedAt: number;\n}\n\nexport interface DurableArtifactRecordV1 {\n\treadonly artifactId: string;\n\treadonly sessionId: string;\n\treadonly data: unknown;\n\treadonly persistedAt: number;\n}\n\nexport interface DurableSnapshotV1 {\n\treadonly version: 1;\n\treadonly exportedAt: number;\n\treadonly sessions: readonly DurableSessionRecordV1[];\n\treadonly operations: readonly DurableOperationRecordV1[];\n\treadonly artifacts: readonly DurableArtifactRecordV1[];\n\treadonly writer: { readonly holder: string | null; readonly crashPending: string | null };\n}\n\nexport type DurableWriterClaimV1 = { readonly status: \"claimed\" } | { readonly status: \"held\"; readonly by: string };\n\nexport type DurableWriterRecoveryV1 =\n\t| { readonly status: \"recovered\"; readonly previousWriter?: string }\n\t| { readonly status: \"held\" };\n\nexport interface DurableReadinessV1 {\n\treadonly ready: boolean;\n\treadonly reason?: string;\n}\n\n/** Diagnostics from the startup log replay of a backend-backed service. */\nexport interface DurableReplayDiagnosticsV1 {\n\t/** Malformed log lines skipped while replaying. */\n\treadonly corruptedLines: number;\n\t/** True when the log existed but could not be read. */\n\treadonly unreadable: boolean;\n}\n\nexport interface DurableServiceV1 {\n\tpersistSession(input: {\n\t\treadonly writerId: string;\n\t\treadonly sessionId: string;\n\t\treadonly data: unknown;\n\t}): DurableSessionRecordV1;\n\tloadSession(input: { readonly sessionId: string }): DurableSessionRecordV1 | undefined;\n\tpersistOperation(input: {\n\t\treadonly writerId: string;\n\t\treadonly operationId: string;\n\t\treadonly sessionId: string;\n\t\treadonly data: unknown;\n\t}): DurableOperationRecordV1;\n\tloadOperation(input: { readonly operationId: string }): DurableOperationRecordV1 | undefined;\n\tpersistArtifact(input: {\n\t\treadonly writerId: string;\n\t\treadonly artifactId: string;\n\t\treadonly sessionId: string;\n\t\treadonly data: unknown;\n\t}): DurableArtifactRecordV1;\n\tloadArtifact(input: { readonly artifactId: string }): DurableArtifactRecordV1 | undefined;\n\t/** All session records, ordered by sessionId for stable output. */\n\tlistSessions(): readonly DurableSessionRecordV1[];\n\tclaimWriter(writerId: string): DurableWriterClaimV1;\n\treleaseWriter(writerId: string): { readonly status: \"released\" };\n\trecoverWriter(writerId: string): DurableWriterRecoveryV1;\n\treadiness(): DurableReadinessV1;\n\texportState(): DurableSnapshotV1;\n\timportState(snapshot: unknown): void;\n\t/**\n\t * Diagnostics from the startup log replay of the backend (zeros/false\n\t * without a backend). Corrupted lines were skipped, not fatal.\n\t */\n\treplayDiagnostics(): DurableReplayDiagnosticsV1;\n}\n"]}