@zhivex-ai/core 1.5.0 → 1.7.0

package/dist/artifact.js

@@ -3,11 +3,20 @@ import { createHash } from "node:crypto";
 import path from "node:path";
 import { ConflictError, ValidationError } from "./errors.js";
 import { assertPostgresClient } from "./postgres-client.js";
-import { createSecureId } from "./secure-id.js";
+import { createSecureId } from "#secure-id";
 import { canonicalStoreFileStem, canonicalStoreKey, ensurePrivateDirectory, writePrivateFile } from "./store-security.js";
 const randomId = createSecureId;
 const cloneJson = (value) => JSON.parse(JSON.stringify(value));
+const MIB = 1024 * 1024;
 export const ARTIFACT_SCHEMA_VERSION = 1;
+export const DEFAULT_ARTIFACT_SERVICE_LIMITS = Object.freeze({
+    maxJsonBytes: MIB,
+    maxTextBytes: MIB,
+    maxBase64Bytes: 16 * MIB,
+    maxBinaryBytes: 16 * MIB,
+    maxMetadataBytes: 64 * 1024,
+    maxRecordBytes: 24 * MIB
+});
 const artifactParts = (input) => [input.appName, input.userId, input.sessionId, input.id];
 const artifactKey = (input) => canonicalStoreKey("artifact", artifactParts(input));
 const legacyArtifactKey = (input) => `${input.appName}:${input.userId}:${input.sessionId}:${input.id}`;
@@ -16,25 +25,141 @@ const matchesArtifactLookup = (artifact, input) => artifact.appName === input.ap
     artifact.sessionId === input.sessionId &&
     artifact.id === input.id;
 const identifierPattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const artifactEncodings = new Set(["json", "text", "base64"]);
+const artifactStorageModes = new Set(["json", "binary"]);
+const positiveSafeIntegerLimit = (value, fallback, name) => {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+        throw new ValidationError(`The "${name}" artifact limit must be a positive safe integer.`);
+    }
+    return resolved;
+};
+export const resolveArtifactServiceLimits = (limits = {}) => ({
+    maxJsonBytes: positiveSafeIntegerLimit(limits.maxJsonBytes, DEFAULT_ARTIFACT_SERVICE_LIMITS.maxJsonBytes, "maxJsonBytes"),
+    maxTextBytes: positiveSafeIntegerLimit(limits.maxTextBytes, DEFAULT_ARTIFACT_SERVICE_LIMITS.maxTextBytes, "maxTextBytes"),
+    maxBase64Bytes: positiveSafeIntegerLimit(limits.maxBase64Bytes, DEFAULT_ARTIFACT_SERVICE_LIMITS.maxBase64Bytes, "maxBase64Bytes"),
+    maxBinaryBytes: positiveSafeIntegerLimit(limits.maxBinaryBytes, DEFAULT_ARTIFACT_SERVICE_LIMITS.maxBinaryBytes, "maxBinaryBytes"),
+    maxMetadataBytes: positiveSafeIntegerLimit(limits.maxMetadataBytes, DEFAULT_ARTIFACT_SERVICE_LIMITS.maxMetadataBytes, "maxMetadataBytes"),
+    maxRecordBytes: positiveSafeIntegerLimit(limits.maxRecordBytes, DEFAULT_ARTIFACT_SERVICE_LIMITS.maxRecordBytes, "maxRecordBytes")
+});
+const jsonText = (value, fieldName) => {
+    try {
+        const serialized = JSON.stringify(value);
+        if (serialized === undefined) {
+            throw new ValidationError(`Artifact ${fieldName} must be JSON-serializable.`);
+        }
+        return serialized;
+    }
+    catch (error) {
+        if (error instanceof ValidationError) {
+            throw error;
+        }
+        throw new ValidationError(`Artifact ${fieldName} must be JSON-serializable.`, { cause: error });
+    }
+};
+const utf8Bytes = (value) => Buffer.byteLength(value, "utf8");
+const assertByteLimit = (actual, maximum, fieldName) => {
+    if (actual > maximum) {
+        throw new ValidationError(`Artifact ${fieldName} is ${actual} bytes and exceeds the ${maximum}-byte limit.`);
+    }
+};
+const validateRequiredString = (value, fieldName) => {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new ValidationError(`Artifact "${fieldName}" must be a non-empty string.`);
+    }
+};
+const validateOptionalString = (value, fieldName) => {
+    if (value !== undefined) {
+        validateRequiredString(value, fieldName);
+    }
+};
+const validateArtifactLookup = (input) => {
+    validateRequiredString(input.appName, "appName");
+    validateRequiredString(input.userId, "userId");
+    validateRequiredString(input.sessionId, "sessionId");
+    validateRequiredString(input.id, "id");
+};
+const validateArtifactListInput = (input) => {
+    validateRequiredString(input.appName, "appName");
+    validateRequiredString(input.userId, "userId");
+    validateRequiredString(input.sessionId, "sessionId");
+    validateOptionalString(input.workflowRunId, "workflowRunId");
+    validateOptionalString(input.workflowStepId, "workflowStepId");
+    validateOptionalString(input.agentRunId, "agentRunId");
+};
+const validateRevision = (revision, fieldName = "revision") => {
+    if (revision !== undefined && (!Number.isSafeInteger(revision) || revision < 0)) {
+        throw new ValidationError(`Artifact "${fieldName}" must be a non-negative safe integer.`);
+    }
+};
+const externalBlobReference = (metadata) => {
+    const externalBlob = metadata?.externalBlob;
+    if (!externalBlob || typeof externalBlob !== "object" || Array.isArray(externalBlob)) {
+        return undefined;
+    }
+    const reference = externalBlob;
+    return reference.managedBy === "application" &&
+        typeof reference.uri === "string" &&
+        reference.uri.length > 0 &&
+        !/[\u0000-\u001f\u007f]/.test(reference.uri)
+        ? { uri: reference.uri }
+        : undefined;
+};
 export const normalizeArtifactRecord = (value) => {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw new ValidationError("ArtifactRecord must be an object.");
     }
     const artifact = value;
-    if (artifact.schemaVersion !== undefined && artifact.schemaVersion > ARTIFACT_SCHEMA_VERSION) {
+    if (artifact.schemaVersion !== undefined &&
+        (!Number.isSafeInteger(artifact.schemaVersion) || artifact.schemaVersion < 0 || artifact.schemaVersion > ARTIFACT_SCHEMA_VERSION)) {
         throw new ValidationError(`Unsupported ArtifactRecord schemaVersion ${artifact.schemaVersion}.`);
     }
-    if (typeof artifact.id !== "string" ||
-        typeof artifact.appName !== "string" ||
-        typeof artifact.userId !== "string" ||
-        typeof artifact.sessionId !== "string" ||
-        typeof artifact.name !== "string" ||
-        typeof artifact.contentType !== "string" ||
-        typeof artifact.createdAt !== "number" ||
-        typeof artifact.updatedAt !== "number" ||
-        !("data" in artifact)) {
+    if (!("data" in artifact)) {
         throw new ValidationError("ArtifactRecord is missing required fields.");
     }
+    validateRequiredString(artifact.id, "id");
+    validateRequiredString(artifact.appName, "appName");
+    validateRequiredString(artifact.userId, "userId");
+    validateRequiredString(artifact.sessionId, "sessionId");
+    validateRequiredString(artifact.name, "name");
+    validateRequiredString(artifact.contentType, "contentType");
+    validateOptionalString(artifact.workflowRunId, "workflowRunId");
+    validateOptionalString(artifact.workflowStepId, "workflowStepId");
+    validateOptionalString(artifact.agentRunId, "agentRunId");
+    if (artifact.revision !== undefined && (!Number.isSafeInteger(artifact.revision) || artifact.revision < 1)) {
+        throw new ValidationError('Artifact "revision" must be a positive safe integer.');
+    }
+    if (!Number.isSafeInteger(artifact.createdAt) || artifact.createdAt < 0) {
+        throw new ValidationError('Artifact "createdAt" must be a non-negative safe integer.');
+    }
+    if (!Number.isSafeInteger(artifact.updatedAt) || artifact.updatedAt < artifact.createdAt) {
+        throw new ValidationError('Artifact "updatedAt" must be a safe integer greater than or equal to "createdAt".');
+    }
+    if (artifact.encoding !== undefined && !artifactEncodings.has(artifact.encoding)) {
+        throw new ValidationError('Artifact "encoding" must be "json", "text", or "base64".');
+    }
+    if (artifact.storageMode !== undefined && !artifactStorageModes.has(artifact.storageMode)) {
+        throw new ValidationError('Artifact "storageMode" must be "json" or "binary".');
+    }
+    if (artifact.metadata !== undefined && (!artifact.metadata || typeof artifact.metadata !== "object" || Array.isArray(artifact.metadata))) {
+        throw new ValidationError('Artifact "metadata" must be a JSON object.');
+    }
+    if ((artifact.storageMode ?? "json") !== "binary" &&
+        (artifact.encoding === "base64" || artifact.encoding === "text") &&
+        typeof artifact.data !== "string") {
+        throw new ValidationError(`Artifact data must be a string when "encoding" is "${artifact.encoding}".`);
+    }
+    if ((artifact.storageMode ?? "json") === "binary" && artifact.data !== null) {
+        throw new ValidationError('Artifact data must be null when "storageMode" is "binary".');
+    }
+    if (artifact.blobPath !== undefined && (artifact.storageMode !== "binary" || artifact.data !== null)) {
+        throw new ValidationError('Artifact "blobPath" is only valid for separate binary storage.');
+    }
+    validateArtifactMetadata({ size: artifact.size, sha256: artifact.sha256 });
+    jsonText(artifact.data, "data");
+    if (artifact.metadata !== undefined) {
+        jsonText(artifact.metadata, "metadata");
+    }
     return {
         schemaVersion: ARTIFACT_SCHEMA_VERSION,
         revision: typeof artifact.revision === "number" ? artifact.revision : 1,
@@ -65,7 +190,9 @@ export const migrateArtifactRecord = (value, targetVersion = ARTIFACT_SCHEMA_VER
     return normalizeArtifactRecord(value);
 };
 const cloneArtifact = (artifact) => cloneJson(normalizeArtifactRecord(artifact));
-const bytesFromBinaryInput = (data) => {
+const binaryInputByteLength = (data) => typeof data === "string" ? utf8Bytes(data) : data.byteLength;
+const bytesFromBinaryInput = (data, maxBytes) => {
+    assertByteLimit(binaryInputByteLength(data), maxBytes, "binary data");
     const buffer = typeof data === "string"
         ? Buffer.from(data, "utf8")
         : data instanceof Uint8Array
@@ -83,6 +210,7 @@ const resolveBinarySha256 = (data, expectedSha256) => {
     return actualSha256;
 };
 const assertExpectedRevision = (current, expectedRevision, resource) => {
+    validateRevision(expectedRevision, "expectedRevision");
     if (expectedRevision !== undefined && (current?.revision ?? 0) !== expectedRevision) {
         throw new ConflictError(`${resource} revision conflict.`);
     }
@@ -103,14 +231,74 @@ const validateArtifactMetadata = (input) => {
         throw new ValidationError('The "sha256" artifact option must be a 64-character hexadecimal digest.');
     }
 };
-const base64Bytes = (value) => {
+const encodedBase64Length = (decodedBytes) => 4 * Math.ceil(decodedBytes / 3);
+const base64Bytes = (value, maxBytes) => {
+    assertByteLimit(utf8Bytes(value), encodedBase64Length(maxBytes), "base64 data");
     const normalized = value.replace(/\s/g, "");
     if (normalized.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(normalized)) {
         throw new ValidationError('Artifact data must be valid base64 when "encoding" is "base64".');
     }
-    return new Uint8Array(Buffer.from(normalized, "base64"));
+    const padding = normalized.endsWith("==") ? 2 : normalized.endsWith("=") ? 1 : 0;
+    const decodedBytes = normalized.length === 0 ? 0 : (normalized.length / 4) * 3 - padding;
+    assertByteLimit(decodedBytes, maxBytes, "decoded base64 data");
+    const bytes = new Uint8Array(Buffer.from(normalized, "base64"));
+    if (bytes.byteLength !== decodedBytes) {
+        throw new ValidationError('Artifact data must be valid base64 when "encoding" is "base64".');
+    }
+    return bytes;
+};
+const validateArtifactSaveInput = (input, limits, internal = {}) => {
+    validateRequiredString(input.appName, "appName");
+    validateRequiredString(input.userId, "userId");
+    validateRequiredString(input.sessionId, "sessionId");
+    if (input.id !== undefined) {
+        validateRequiredString(input.id, "id");
+    }
+    validateOptionalString(input.workflowRunId, "workflowRunId");
+    validateOptionalString(input.workflowStepId, "workflowStepId");
+    validateOptionalString(input.agentRunId, "agentRunId");
+    validateRequiredString(input.name, "name");
+    validateRequiredString(input.contentType, "contentType");
+    validateRevision(input.expectedRevision, "expectedRevision");
+    if (input.encoding !== undefined && !artifactEncodings.has(input.encoding)) {
+        throw new ValidationError('Artifact "encoding" must be "json", "text", or "base64".');
+    }
+    if (input.storageMode !== undefined && !artifactStorageModes.has(input.storageMode)) {
+        throw new ValidationError('Artifact "storageMode" must be "json" or "binary".');
+    }
+    if (input.metadata !== undefined && (!input.metadata || typeof input.metadata !== "object" || Array.isArray(input.metadata))) {
+        throw new ValidationError('Artifact "metadata" must be a JSON object.');
+    }
+    if (input.metadata !== undefined) {
+        assertByteLimit(utf8Bytes(jsonText(input.metadata, "metadata")), limits.maxMetadataBytes, "metadata");
+    }
+    if ((input.storageMode ?? "json") === "binary") {
+        if (input.data !== null) {
+            throw new ValidationError('Artifact data must be null when "storageMode" is "binary".');
+        }
+        if (!internal.managedBinary && !externalBlobReference(input.metadata)) {
+            throw new ValidationError('Binary artifact metadata must contain an application-managed externalBlob reference.');
+        }
+        return;
+    }
+    if (input.encoding === "base64") {
+        if (typeof input.data !== "string") {
+            throw new ValidationError('Artifact data must be a string when "encoding" is "base64".');
+        }
+        base64Bytes(input.data, limits.maxBase64Bytes);
+        return;
+    }
+    if (input.encoding === "text" && typeof input.data !== "string") {
+        throw new ValidationError('Artifact data must be a string when "encoding" is "text".');
+    }
+    if (typeof input.data === "string") {
+        assertByteLimit(utf8Bytes(input.data), limits.maxTextBytes, "text data");
+    }
+    else {
+        assertByteLimit(utf8Bytes(jsonText(input.data, "data")), limits.maxJsonBytes, "JSON data");
+    }
 };
-const enrichArtifactMetadata = (input) => {
+const enrichArtifactMetadata = (input, limits) => {
     validateArtifactMetadata(input);
     if (input.encoding !== "base64" || typeof input.data !== "string") {
         return {
@@ -118,7 +306,7 @@ const enrichArtifactMetadata = (input) => {
             sha256: input.sha256
         };
     }
-    const bytes = base64Bytes(input.data);
+    const bytes = base64Bytes(input.data, limits.maxBase64Bytes);
     const actualSha256 = sha256Digest(bytes);
     if (input.size !== undefined && input.size !== bytes.byteLength) {
         throw new ValidationError('The "size" artifact option does not match the decoded base64 data.');
@@ -131,6 +319,27 @@ const enrichArtifactMetadata = (input) => {
         sha256: actualSha256
     };
 };
+const validateArtifactRecordLimits = (artifact, limits) => {
+    assertByteLimit(utf8Bytes(jsonText(artifact, "record")), limits.maxRecordBytes, "record");
+    if (artifact.metadata !== undefined) {
+        assertByteLimit(utf8Bytes(jsonText(artifact.metadata, "metadata")), limits.maxMetadataBytes, "metadata");
+    }
+    if (artifact.storageMode !== "binary") {
+        if (artifact.encoding === "base64") {
+            if (typeof artifact.data !== "string") {
+                throw new ValidationError('Artifact data must be a string when "encoding" is "base64".');
+            }
+            base64Bytes(artifact.data, limits.maxBase64Bytes);
+        }
+        else if (typeof artifact.data === "string") {
+            assertByteLimit(utf8Bytes(artifact.data), limits.maxTextBytes, "text data");
+        }
+        else {
+            assertByteLimit(utf8Bytes(jsonText(artifact.data, "data")), limits.maxJsonBytes, "JSON data");
+        }
+    }
+    return artifact;
+};
 const validateIdentifier = (value, fieldName) => {
     if (!identifierPattern.test(value)) {
         throw new ValidationError(`The "${fieldName}" option must match the SQL identifier pattern [A-Za-z_][A-Za-z0-9_]*.`);
@@ -149,14 +358,15 @@ const getRecordField = (value, candidates) => {
     }
     return undefined;
 };
-const parseArtifactJson = (value) => {
+const parseArtifactJson = (value, limits) => {
     if (!value) {
         return undefined;
     }
     if (typeof value === "string") {
-        return normalizeArtifactRecord(JSON.parse(value));
+        assertByteLimit(utf8Bytes(value), limits.maxRecordBytes, "record");
+        return validateArtifactRecordLimits(normalizeArtifactRecord(JSON.parse(value)), limits);
     }
-    return normalizeArtifactRecord(value);
+    return validateArtifactRecordLimits(normalizeArtifactRecord(value), limits);
 };
 const prepareSqliteStatement = (db, sql) => {
     if (typeof db.prepare === "function") {
@@ -183,10 +393,11 @@ const ensurePostgresTable = (() => {
         await initialization;
     };
 })();
-const createArtifact = (input, existing, internal) => {
-    const integrity = enrichArtifactMetadata(input);
+const createArtifact = (input, limits, existing, internal) => {
+    validateArtifactSaveInput(input, limits, internal);
+    const integrity = enrichArtifactMetadata(input, limits);
     const now = Date.now();
-    return {
+    const artifact = {
         schemaVersion: ARTIFACT_SCHEMA_VERSION,
         revision: existing ? existing.revision + 1 : 1,
         id: input.id ?? existing?.id ?? randomId("art"),
@@ -206,8 +417,10 @@ const createArtifact = (input, existing, internal) => {
         blobPath: internal?.blobPath,
         metadata: input.metadata ? cloneJson(input.metadata) : undefined,
         createdAt: existing?.createdAt ?? now,
-        updatedAt: now
+        updatedAt: existing ? Math.max(now, existing.updatedAt + 1) : now
     };
+    assertByteLimit(utf8Bytes(jsonText(artifact, "record")), limits.maxRecordBytes, "record");
+    return artifact;
 };
 const matchesListInput = (artifact, input) => artifact.appName === input.appName &&
     artifact.userId === input.userId &&
@@ -244,25 +457,26 @@ const lookupFromArtifact = (artifact) => ({
     sessionId: artifact.sessionId,
     id: artifact.id
 });
-export const createBase64ArtifactData = (input) => {
+export const createBase64ArtifactData = (input, limits = {}) => {
     const data = typeof input === "object" && "data" in input ? input.data : input;
-    const buffer = typeof data === "string"
-        ? Buffer.from(data, "utf8")
-        : data instanceof Uint8Array
-            ? Buffer.from(data)
-            : Buffer.from(data);
+    const resolvedLimits = resolveArtifactServiceLimits(limits);
+    const buffer = Buffer.from(bytesFromBinaryInput(data, resolvedLimits.maxBase64Bytes));
     return {
         data: buffer.toString("base64"),
         encoding: "base64",
         size: buffer.byteLength
     };
 };
-export const createExternalArtifactReference = (input) => {
+export const createExternalArtifactReference = (input, limits = {}) => {
+    const resolvedLimits = resolveArtifactServiceLimits(limits);
     validateArtifactMetadata(input);
-    if (!input.uri) {
+    if (!input.uri || /[\u0000-\u001f\u007f]/.test(input.uri)) {
         throw new ValidationError('The "uri" external artifact reference option is required.');
     }
-    return {
+    if (input.metadata !== undefined && (!input.metadata || typeof input.metadata !== "object" || Array.isArray(input.metadata))) {
+        throw new ValidationError('Artifact "metadata" must be a JSON object.');
+    }
+    const reference = {
         data: null,
         storageMode: "binary",
         size: input.size,
@@ -275,14 +489,19 @@ export const createExternalArtifactReference = (input) => {
             }
         }
     };
+    assertByteLimit(utf8Bytes(jsonText(reference.metadata, "metadata")), resolvedLimits.maxMetadataBytes, "metadata");
+    return reference;
 };
-export const verifyArtifactRecordIntegrity = (record, data) => {
+export const verifyArtifactRecordIntegrity = (record, data, limits = {}) => {
     const artifact = normalizeArtifactRecord(record);
+    const resolvedLimits = resolveArtifactServiceLimits(limits);
     const issues = [];
     let bytes = data;
+    let decodedInlineBase64 = false;
     if (!bytes && artifact.encoding === "base64" && typeof artifact.data === "string") {
         try {
-            bytes = new Uint8Array(Buffer.from(artifact.data, "base64"));
+            bytes = base64Bytes(artifact.data, resolvedLimits.maxBase64Bytes);
+            decodedInlineBase64 = true;
         }
         catch {
             issues.push({
@@ -291,6 +510,18 @@ export const verifyArtifactRecordIntegrity = (record, data) => {
             });
         }
     }
+    if (bytes && !decodedInlineBase64) {
+        try {
+            assertByteLimit(bytes.byteLength, resolvedLimits.maxBinaryBytes, "binary data");
+        }
+        catch (error) {
+            issues.push({
+                type: "metadata-invalid",
+                message: error instanceof Error ? error.message : `Artifact "${artifact.id}" binary data exceeds its limit.`
+            });
+            bytes = undefined;
+        }
+    }
     if (bytes) {
         if (artifact.size !== undefined && artifact.size !== bytes.byteLength) {
             issues.push({
@@ -318,7 +549,7 @@ export const verifyArtifactRecordIntegrity = (record, data) => {
         issues
     };
 };
-export const verifyArtifactIntegrity = async (service, lookup) => {
+export const verifyArtifactIntegrity = async (service, lookup, limits = {}) => {
     const artifact = await service.loadArtifact(lookup);
     if (!artifact) {
         return {
@@ -332,18 +563,21 @@ export const verifyArtifactIntegrity = async (service, lookup) => {
     if (artifact.storageMode === "binary") {
         const binary = await service.loadBinaryArtifact(lookup);
         if (!binary) {
+            const external = externalBlobReference(artifact.metadata);
             return {
                 ok: false,
                 artifact,
                 issues: [{
-                        type: "missing-blob",
-                        message: `Artifact "${lookup.id}" binary blob was not found.`
+                        type: external ? "external-data-unavailable" : "missing-blob",
+                        message: external
+                            ? `Artifact "${lookup.id}" uses application-managed external data at "${external.uri}".`
+                            : `Artifact "${lookup.id}" binary blob was not found.`
                     }]
             };
         }
-        return verifyArtifactRecordIntegrity(binary.artifact, binary.data);
+        return verifyArtifactRecordIntegrity(binary.artifact, binary.data, limits);
     }
-    return verifyArtifactRecordIntegrity(artifact);
+    return verifyArtifactRecordIntegrity(artifact, undefined, limits);
 };
 const listFilesRecursive = async (directory) => {
     try {
@@ -365,6 +599,7 @@ const listFilesRecursive = async (directory) => {
     }
 };
 export const inspectFileArtifactStore = async (options) => {
+    const limits = resolveArtifactServiceLimits(options.limits);
     const artifacts = new Map();
     const issues = [];
     const referencedBlobPaths = new Set();
@@ -383,7 +618,9 @@ export const inspectFileArtifactStore = async (options) => {
         }
         const metadataPath = path.join(options.directory, entry);
         try {
-            const artifact = normalizeArtifactRecord(JSON.parse(await fs.readFile(metadataPath, "utf8")));
+            const stat = await fs.stat(metadataPath);
+            assertByteLimit(stat.size, limits.maxRecordBytes, "record");
+            const artifact = validateArtifactRecordLimits(normalizeArtifactRecord(JSON.parse(await fs.readFile(metadataPath, "utf8"))), limits);
             const fullBlobPath = resolveFileArtifactBlobPath(options.directory, artifact);
             const key = artifactKey(artifact);
             if (!artifacts.has(key) || entry === fileNameForArtifact(artifact)) {
@@ -394,12 +631,14 @@ export const inspectFileArtifactStore = async (options) => {
             }
             if (artifact.storageMode === "binary") {
                 if (!artifact.blobPath) {
-                    issues.push({
-                        type: "missing-blob",
-                        path: metadataPath,
-                        artifact,
-                        message: `Artifact "${artifact.id}" has no blobPath.`
-                    });
+                    if (!externalBlobReference(artifact.metadata)) {
+                        issues.push({
+                            type: "missing-blob",
+                            path: metadataPath,
+                            artifact,
+                            message: `Artifact "${artifact.id}" has no blobPath.`
+                        });
+                    }
                 }
                 else {
                     try {
@@ -467,7 +706,10 @@ export const cleanupFileArtifactStore = async (options) => {
 export const pruneFileArtifactStore = async (options) => {
     const now = options.now ?? Date.now();
     const dryRun = options.dryRun ?? true;
-    const inspection = await inspectFileArtifactStore({ directory: options.directory });
+    const inspection = await inspectFileArtifactStore({
+        directory: options.directory,
+        limits: options.limits
+    });
     const sorted = inspection.artifacts.sort((left, right) => right.updatedAt - left.updatedAt || artifactKey(left).localeCompare(artifactKey(right)));
     const keepByCount = new Set(options.keepLast === undefined ? [] : sorted.slice(0, Math.max(0, options.keepLast)).map((artifact) => artifactKey(artifact)));
     const shouldDelete = (artifact) => !keepByCount.has(artifactKey(artifact)) &&
@@ -498,7 +740,8 @@ export const pruneFileArtifactStore = async (options) => {
         deletedBlobPaths
     };
 };
-export const createInMemoryArtifactService = () => {
+export const createInMemoryArtifactService = (options = {}) => {
+    const limits = resolveArtifactServiceLimits(options.limits);
     const artifacts = new Map();
     const binaryData = new Map();
     return {
@@ -510,9 +753,10 @@ export const createInMemoryArtifactService = () => {
                 sessionId: input.sessionId,
                 id
             };
+            validateArtifactLookup(lookup);
             const existing = artifacts.get(artifactKey(lookup));
             assertExpectedRevision(existing, input.expectedRevision, "ArtifactRecord");
-            const artifact = createArtifact({ ...input, id }, existing);
+            const artifact = createArtifact({ ...input, id }, limits, existing);
             artifacts.set(artifactKey(lookup), cloneArtifact(artifact));
             binaryData.delete(artifactKey(lookup));
             return cloneArtifact(artifact);
@@ -525,7 +769,8 @@ export const createInMemoryArtifactService = () => {
                 sessionId: input.sessionId,
                 id
             };
-            const bytes = bytesFromBinaryInput(input.data);
+            validateArtifactLookup(lookup);
+            const bytes = bytesFromBinaryInput(input.data, limits.maxBinaryBytes);
             const sha256 = resolveBinarySha256(bytes, input.sha256);
             const existing = artifacts.get(artifactKey(lookup));
             assertExpectedRevision(existing, input.expectedRevision, "ArtifactRecord");
@@ -537,16 +782,18 @@ export const createInMemoryArtifactService = () => {
                 size: bytes.byteLength,
                 sha256,
                 storageMode: "binary"
-            }, existing);
+            }, limits, existing, { managedBinary: true });
             artifacts.set(artifactKey(lookup), cloneArtifact(artifact));
             binaryData.set(artifactKey(lookup), new Uint8Array(bytes));
             return cloneArtifact(artifact);
         },
         loadArtifact(input) {
+            validateArtifactLookup(input);
             const artifact = artifacts.get(artifactKey(input));
             return artifact ? cloneArtifact(artifact) : undefined;
         },
         loadBinaryArtifact(input) {
+            validateArtifactLookup(input);
             const artifact = artifacts.get(artifactKey(input));
             const data = binaryData.get(artifactKey(input));
             if (!artifact || !data) {
@@ -558,26 +805,32 @@ export const createInMemoryArtifactService = () => {
             };
         },
         listArtifacts(input) {
+            validateArtifactListInput(input);
             return [...artifacts.values()]
                 .filter((artifact) => matchesListInput(artifact, input))
                 .sort((left, right) => left.createdAt - right.createdAt || left.id.localeCompare(right.id))
                 .map(cloneArtifact);
         },
         deleteArtifact(input) {
+            validateArtifactLookup(input);
             artifacts.delete(artifactKey(input));
             binaryData.delete(artifactKey(input));
         }
     };
 };
 export const createFileArtifactService = (options) => {
+    const limits = resolveArtifactServiceLimits(options.limits);
     const filePath = (input) => path.join(options.directory, fileNameForArtifact(input));
     const binaryPath = (input) => path.join(options.directory, blobPathForArtifact(input));
     const legacyFilePath = (input) => path.join(options.directory, legacyFileNameForArtifact(input));
     const load = async (input) => {
+        validateArtifactLookup(input);
         for (const candidate of [filePath(input), legacyFilePath(input)]) {
             try {
+                const stat = await fs.stat(candidate);
+                assertByteLimit(stat.size, limits.maxRecordBytes, "record");
                 const content = await fs.readFile(candidate, "utf8");
-                const artifact = normalizeArtifactRecord(JSON.parse(content));
+                const artifact = validateArtifactRecordLimits(normalizeArtifactRecord(JSON.parse(content)), limits);
                 if (!matchesArtifactLookup(artifact, input)) {
                     continue;
                 }
@@ -594,7 +847,7 @@ export const createFileArtifactService = (options) => {
     };
     const save = async (artifact) => {
         await ensurePrivateDirectory(options.directory);
-        await writePrivateFile(filePath(artifact), JSON.stringify(cloneArtifact(artifact), null, 2));
+        await writePrivateFile(filePath(artifact), JSON.stringify(cloneArtifact(artifact)));
         try {
             const legacyArtifact = normalizeArtifactRecord(JSON.parse(await fs.readFile(legacyFilePath(artifact), "utf8")));
             if (matchesArtifactLookup(legacyArtifact, artifact)) {
@@ -624,9 +877,10 @@ export const createFileArtifactService = (options) => {
                 sessionId: input.sessionId,
                 id
             };
+            validateArtifactLookup(lookup);
             const existing = await load(lookup);
             assertExpectedRevision(existing, input.expectedRevision, "ArtifactRecord");
-            const artifact = createArtifact({ ...input, id }, existing);
+            const artifact = createArtifact({ ...input, id }, limits, existing);
             await save(artifact);
             const existingBlob = binaryPath(lookup);
             await fs.unlink(existingBlob).catch((error) => {
@@ -644,7 +898,8 @@ export const createFileArtifactService = (options) => {
                 sessionId: input.sessionId,
                 id
             };
-            const bytes = bytesFromBinaryInput(input.data);
+            validateArtifactLookup(lookup);
+            const bytes = bytesFromBinaryInput(input.data, limits.maxBinaryBytes);
             const sha256 = resolveBinarySha256(bytes, input.sha256);
             const blobPath = blobPathForArtifact(lookup);
             const existing = await load(lookup);
@@ -657,7 +912,7 @@ export const createFileArtifactService = (options) => {
                 size: bytes.byteLength,
                 sha256,
                 storageMode: "binary"
-            }, existing, { blobPath });
+            }, limits, existing, { blobPath, managedBinary: true });
             await ensurePrivateDirectory(path.dirname(binaryPath(lookup)));
             await writePrivateFile(binaryPath(lookup), bytes);
             await save(artifact);
@@ -672,7 +927,11 @@ export const createFileArtifactService = (options) => {
                 return undefined;
             }
             try {
-                const data = await fs.readFile(resolveFileArtifactBlobPath(options.directory, artifact));
+                const resolvedBlobPath = resolveFileArtifactBlobPath(options.directory, artifact);
+                const stat = await fs.stat(resolvedBlobPath);
+                assertByteLimit(stat.size, limits.maxBinaryBytes, "binary data");
+                const data = await fs.readFile(resolvedBlobPath);
+                assertByteLimit(data.byteLength, limits.maxBinaryBytes, "binary data");
                 return {
                     artifact,
                     data: new Uint8Array(data)
@@ -686,6 +945,7 @@ export const createFileArtifactService = (options) => {
             }
         },
         async listArtifacts(input) {
+            validateArtifactListInput(input);
             let entries;
             try {
                 entries = await fs.readdir(options.directory);
@@ -701,8 +961,11 @@ export const createFileArtifactService = (options) => {
                 if (!entry.endsWith(".json")) {
                     continue;
                 }
-                const content = await fs.readFile(path.join(options.directory, entry), "utf8");
-                const artifact = normalizeArtifactRecord(JSON.parse(content));
+                const metadataPath = path.join(options.directory, entry);
+                const stat = await fs.stat(metadataPath);
+                assertByteLimit(stat.size, limits.maxRecordBytes, "record");
+                const content = await fs.readFile(metadataPath, "utf8");
+                const artifact = validateArtifactRecordLimits(normalizeArtifactRecord(JSON.parse(content)), limits);
                 resolveFileArtifactBlobPath(options.directory, artifact);
                 if (matchesListInput(artifact, input)) {
                     const key = artifactKey(artifact);
@@ -714,6 +977,7 @@ export const createFileArtifactService = (options) => {
             return [...artifacts.values()].sort((left, right) => left.createdAt - right.createdAt || left.id.localeCompare(right.id));
         },
         async deleteArtifact(input) {
+            validateArtifactLookup(input);
             const artifact = await load(input);
             await fs.unlink(filePath(input)).catch((error) => {
                 if (error.code !== "ENOENT") {
@@ -745,6 +1009,7 @@ export const createFileArtifactService = (options) => {
     };
 };
 export const createSqliteArtifactService = (options) => {
+    const limits = resolveArtifactServiceLimits(options.limits);
     const tableName = validateIdentifier(options.tableName ?? "zhivex_artifacts", "tableName");
     options.db.exec(`
     CREATE TABLE IF NOT EXISTS ${tableName} (
@@ -795,6 +1060,23 @@ export const createSqliteArtifactService = (options) => {
       agent_run_id = excluded.agent_run_id,
       artifact_json = excluded.artifact_json,
       updated_at_ms = excluded.updated_at_ms
+  `);
+    const insertCasStatement = prepareSqliteStatement(options.db, `
+    INSERT INTO ${tableName} (
+      artifact_key,
+      app_name,
+      user_id,
+      session_id,
+      artifact_id,
+      workflow_run_id,
+      workflow_step_id,
+      agent_run_id,
+      artifact_json,
+      created_at_ms,
+      updated_at_ms
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(artifact_key) DO NOTHING
   `);
     const updateCasStatement = prepareSqliteStatement(options.db, `
     UPDATE ${tableName}
@@ -812,9 +1094,10 @@ export const createSqliteArtifactService = (options) => {
   `);
     const deleteStatement = prepareSqliteStatement(options.db, `DELETE FROM ${tableName} WHERE artifact_key = ?`);
     const load = (input) => {
+        validateArtifactLookup(input);
         for (const key of [artifactKey(input), legacyArtifactKey(input)]) {
             const row = loadStatement.get([key]);
-            const artifact = parseArtifactJson(getRecordField(row, ["artifact_json", "artifactJson"]));
+            const artifact = parseArtifactJson(getRecordField(row, ["artifact_json", "artifactJson"]), limits);
             if (artifact && matchesArtifactLookup(artifact, input)) {
                 return artifact;
             }
@@ -822,8 +1105,26 @@ export const createSqliteArtifactService = (options) => {
         return undefined;
     };
     const save = (artifact, options) => {
-        if (options?.expectedRevision !== undefined && options.existing) {
-            const canonicalExisting = parseArtifactJson(getRecordField(loadStatement.get([artifactKey(artifact)]), ["artifact_json", "artifactJson"]));
+        if (options?.expectedRevision === 0 && !options.existing) {
+            const result = insertCasStatement.run([
+                artifactKey(lookupFromArtifact(artifact)),
+                artifact.appName,
+                artifact.userId,
+                artifact.sessionId,
+                artifact.id,
+                artifact.workflowRunId ?? null,
+                artifact.workflowStepId ?? null,
+                artifact.agentRunId ?? null,
+                JSON.stringify(artifact),
+                artifact.createdAt,
+                artifact.updatedAt
+            ]);
+            if (sqliteMutationCount(result) !== 1) {
+                throw new ConflictError("ArtifactRecord revision conflict.");
+            }
+        }
+        else if (options?.expectedRevision !== undefined && options.existing) {
+            const canonicalExisting = parseArtifactJson(getRecordField(loadStatement.get([artifactKey(artifact)]), ["artifact_json", "artifactJson"]), limits);
             if (canonicalExisting && matchesArtifactLookup(canonicalExisting, artifact)) {
                 const result = updateCasStatement.run([
                     artifact.appName,
@@ -838,12 +1139,12 @@ export const createSqliteArtifactService = (options) => {
                     artifactKey(lookupFromArtifact(artifact)),
                     options.existing.updatedAt
                 ]);
-                if (sqliteMutationCount(result) === 0) {
+                if (sqliteMutationCount(result) !== 1) {
                     throw new ConflictError("ArtifactRecord revision conflict.");
                 }
             }
             else {
-                const legacy = parseArtifactJson(getRecordField(loadStatement.get([legacyArtifactKey(artifact)]), ["artifact_json", "artifactJson"]));
+                const legacy = parseArtifactJson(getRecordField(loadStatement.get([legacyArtifactKey(artifact)]), ["artifact_json", "artifactJson"]), limits);
                 if (!legacy || !matchesArtifactLookup(legacy, artifact) || legacy.updatedAt !== options.existing.updatedAt) {
                     throw new ConflictError("ArtifactRecord revision conflict.");
                 }
@@ -877,7 +1178,7 @@ export const createSqliteArtifactService = (options) => {
                 artifact.updatedAt
             ]);
         }
-        const legacy = parseArtifactJson(getRecordField(loadStatement.get([legacyArtifactKey(artifact)]), ["artifact_json", "artifactJson"]));
+        const legacy = parseArtifactJson(getRecordField(loadStatement.get([legacyArtifactKey(artifact)]), ["artifact_json", "artifactJson"]), limits);
         if (legacy && matchesArtifactLookup(legacy, artifact)) {
             deleteStatement.run([legacyArtifactKey(artifact)]);
         }
@@ -886,6 +1187,7 @@ export const createSqliteArtifactService = (options) => {
     return {
         saveArtifact(input) {
             const id = input.id ?? randomId("art");
+            validateArtifactLookup({ appName: input.appName, userId: input.userId, sessionId: input.sessionId, id });
             const existing = load({
                 appName: input.appName,
                 userId: input.userId,
@@ -893,14 +1195,16 @@ export const createSqliteArtifactService = (options) => {
                 id
             });
             assertExpectedRevision(existing, input.expectedRevision, "ArtifactRecord");
-            return save(createArtifact({ ...input, id }, existing), {
+            return save(createArtifact({ ...input, id }, limits, existing), {
                 existing,
                 expectedRevision: input.expectedRevision
             });
         },
         saveBinaryArtifact(input) {
             const id = input.id ?? randomId("art");
-            const bytes = bytesFromBinaryInput(input.data);
+            validateArtifactLookup({ appName: input.appName, userId: input.userId, sessionId: input.sessionId, id });
+            const bytes = bytesFromBinaryInput(input.data, limits.maxBinaryBytes);
+            const sha256 = resolveBinarySha256(bytes, input.sha256);
             const existing = load({
                 appName: input.appName,
                 userId: input.userId,
@@ -914,9 +1218,9 @@ export const createSqliteArtifactService = (options) => {
                 data: Buffer.from(bytes).toString("base64"),
                 encoding: "base64",
                 size: bytes.byteLength,
-                sha256: input.sha256 ?? sha256Digest(bytes),
+                sha256,
                 storageMode: "json"
-            }, existing), {
+            }, limits, existing), {
                 existing,
                 expectedRevision: input.expectedRevision
             });
@@ -931,10 +1235,11 @@ export const createSqliteArtifactService = (options) => {
             }
             return {
                 artifact,
-                data: new Uint8Array(Buffer.from(artifact.data, "base64"))
+                data: base64Bytes(artifact.data, limits.maxBase64Bytes)
             };
         },
         listArtifacts(input) {
+            validateArtifactListInput(input);
             const params = [
                 input.appName,
                 input.userId,
@@ -949,7 +1254,7 @@ export const createSqliteArtifactService = (options) => {
             const rows = listStatement.all?.(params) ?? [];
             const artifacts = new Map();
             for (const row of rows) {
-                const artifact = parseArtifactJson(getRecordField(row, ["artifact_json", "artifactJson"]));
+                const artifact = parseArtifactJson(getRecordField(row, ["artifact_json", "artifactJson"]), limits);
                 if (artifact) {
                     artifacts.set(artifactKey(artifact), artifact);
                 }
@@ -957,8 +1262,9 @@ export const createSqliteArtifactService = (options) => {
             return [...artifacts.values()];
         },
         deleteArtifact(input) {
+            validateArtifactLookup(input);
             deleteStatement.run([artifactKey(input)]);
-            const legacy = parseArtifactJson(getRecordField(loadStatement.get([legacyArtifactKey(input)]), ["artifact_json", "artifactJson"]));
+            const legacy = parseArtifactJson(getRecordField(loadStatement.get([legacyArtifactKey(input)]), ["artifact_json", "artifactJson"]), limits);
             if (legacy && matchesArtifactLookup(legacy, input)) {
                 deleteStatement.run([legacyArtifactKey(input)]);
             }
@@ -967,6 +1273,7 @@ export const createSqliteArtifactService = (options) => {
 };
 export const createPostgresArtifactService = (options) => {
     assertPostgresClient(options.client);
+    const limits = resolveArtifactServiceLimits(options.limits);
     const tableName = validateIdentifier(options.tableName ?? "zhivex_artifacts", "tableName");
     const createSql = `
     CREATE TABLE IF NOT EXISTS ${tableName} (
@@ -984,10 +1291,11 @@ export const createPostgresArtifactService = (options) => {
     )
   `;
     const load = async (input) => {
+        validateArtifactLookup(input);
         await ensurePostgresTable(options.client, tableName, createSql);
         for (const key of [artifactKey(input), legacyArtifactKey(input)]) {
             const result = await options.client.query(`SELECT artifact_json FROM ${tableName} WHERE artifact_key = $1`, [key]);
-            const artifact = parseArtifactJson(getRecordField(result.rows[0], ["artifact_json", "artifactJson"]));
+            const artifact = parseArtifactJson(getRecordField(result.rows[0], ["artifact_json", "artifactJson"]), limits);
             if (artifact && matchesArtifactLookup(artifact, input)) {
                 return artifact;
             }
@@ -996,7 +1304,40 @@ export const createPostgresArtifactService = (options) => {
     };
     const save = async (artifact, saveOptions) => {
         await ensurePostgresTable(options.client, tableName, createSql);
-        if (saveOptions?.expectedRevision !== undefined && saveOptions.existing) {
+        if (saveOptions?.expectedRevision === 0 && !saveOptions.existing) {
+            const result = await options.client.query(`INSERT INTO ${tableName} (
+           artifact_key,
+           app_name,
+           user_id,
+           session_id,
+           artifact_id,
+           workflow_run_id,
+           workflow_step_id,
+           agent_run_id,
+           artifact_json,
+           created_at_ms,
+           updated_at_ms
+         )
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10, $11)
+         ON CONFLICT(artifact_key) DO NOTHING
+         RETURNING artifact_json`, [
+                artifactKey(lookupFromArtifact(artifact)),
+                artifact.appName,
+                artifact.userId,
+                artifact.sessionId,
+                artifact.id,
+                artifact.workflowRunId ?? null,
+                artifact.workflowStepId ?? null,
+                artifact.agentRunId ?? null,
+                JSON.stringify(artifact),
+                artifact.createdAt,
+                artifact.updatedAt
+            ]);
+            if (result.rows.length === 0) {
+                throw new ConflictError("ArtifactRecord revision conflict.");
+            }
+        }
+        else if (saveOptions?.expectedRevision !== undefined && saveOptions.existing) {
             const result = await options.client.query(`UPDATE ${tableName}
          SET app_name = $2,
              user_id = $3,
@@ -1094,7 +1435,7 @@ export const createPostgresArtifactService = (options) => {
             ]);
         }
         const legacyResult = await options.client.query(`SELECT artifact_json FROM ${tableName} WHERE artifact_key = $1`, [legacyArtifactKey(artifact)]);
-        const legacy = parseArtifactJson(getRecordField(legacyResult.rows[0], ["artifact_json", "artifactJson"]));
+        const legacy = parseArtifactJson(getRecordField(legacyResult.rows[0], ["artifact_json", "artifactJson"]), limits);
         if (legacy && matchesArtifactLookup(legacy, artifact)) {
             await options.client.query(`DELETE FROM ${tableName} WHERE artifact_key = $1`, [legacyArtifactKey(artifact)]);
         }
@@ -1103,6 +1444,7 @@ export const createPostgresArtifactService = (options) => {
     return {
         async saveArtifact(input) {
             const id = input.id ?? randomId("art");
+            validateArtifactLookup({ appName: input.appName, userId: input.userId, sessionId: input.sessionId, id });
             const existing = await load({
                 appName: input.appName,
                 userId: input.userId,
@@ -1110,14 +1452,16 @@ export const createPostgresArtifactService = (options) => {
                 id
             });
             assertExpectedRevision(existing, input.expectedRevision, "ArtifactRecord");
-            return save(createArtifact({ ...input, id }, existing), {
+            return save(createArtifact({ ...input, id }, limits, existing), {
                 existing,
                 expectedRevision: input.expectedRevision
             });
         },
         async saveBinaryArtifact(input) {
             const id = input.id ?? randomId("art");
-            const bytes = bytesFromBinaryInput(input.data);
+            validateArtifactLookup({ appName: input.appName, userId: input.userId, sessionId: input.sessionId, id });
+            const bytes = bytesFromBinaryInput(input.data, limits.maxBinaryBytes);
+            const sha256 = resolveBinarySha256(bytes, input.sha256);
             const existing = await load({
                 appName: input.appName,
                 userId: input.userId,
@@ -1131,9 +1475,9 @@ export const createPostgresArtifactService = (options) => {
                 data: Buffer.from(bytes).toString("base64"),
                 encoding: "base64",
                 size: bytes.byteLength,
-                sha256: input.sha256 ?? sha256Digest(bytes),
+                sha256,
                 storageMode: "json"
-            }, existing), {
+            }, limits, existing), {
                 existing,
                 expectedRevision: input.expectedRevision
             });
@@ -1148,10 +1492,11 @@ export const createPostgresArtifactService = (options) => {
             }
             return {
                 artifact,
-                data: new Uint8Array(Buffer.from(artifact.data, "base64"))
+                data: base64Bytes(artifact.data, limits.maxBase64Bytes)
             };
         },
         async listArtifacts(input) {
+            validateArtifactListInput(input);
             await ensurePostgresTable(options.client, tableName, createSql);
             const result = await options.client.query(`SELECT artifact_json FROM ${tableName}
          WHERE app_name = $1
@@ -1170,7 +1515,7 @@ export const createPostgresArtifactService = (options) => {
             ]);
             const artifacts = new Map();
             for (const row of result.rows) {
-                const artifact = parseArtifactJson(getRecordField(row, ["artifact_json", "artifactJson"]));
+                const artifact = parseArtifactJson(getRecordField(row, ["artifact_json", "artifactJson"]), limits);
                 if (artifact) {
                     artifacts.set(artifactKey(artifact), artifact);
                 }
@@ -1178,10 +1523,11 @@ export const createPostgresArtifactService = (options) => {
             return [...artifacts.values()];
         },
         async deleteArtifact(input) {
+            validateArtifactLookup(input);
             await ensurePostgresTable(options.client, tableName, createSql);
             await options.client.query(`DELETE FROM ${tableName} WHERE artifact_key = $1`, [artifactKey(input)]);
             const legacyResult = await options.client.query(`SELECT artifact_json FROM ${tableName} WHERE artifact_key = $1`, [legacyArtifactKey(input)]);
-            const legacy = parseArtifactJson(getRecordField(legacyResult.rows[0], ["artifact_json", "artifactJson"]));
+            const legacy = parseArtifactJson(getRecordField(legacyResult.rows[0], ["artifact_json", "artifactJson"]), limits);
             if (legacy && matchesArtifactLookup(legacy, input)) {
                 await options.client.query(`DELETE FROM ${tableName} WHERE artifact_key = $1`, [legacyArtifactKey(input)]);
             }