@straiffi/archon 1.7.4 → 1.7.6

package/dist/server/lib/executionArtifacts.js

@@ -0,0 +1,705 @@
+import { createHash, randomUUID } from 'crypto';
+import { constants } from 'fs';
+import { isIP } from 'net';
+import { basename, dirname, isAbsolute, relative, resolve, sep } from 'path';
+import { lstat, mkdir, link, open, realpath, unlink } from 'fs/promises';
+import db from '../db.js';
+import { withExecutionRunTransaction } from './executionRuns.js';
+import { resolveArchonArtifactsRoot } from './runtimePaths.js';
+import { isProjectArtifactCleanupActive } from './executionArtifactCleanupState.js';
+import { truncateUtf8 } from './transcriptRuns.js';
+import { ARTIFACT_RETENTION_DURATIONS_MS, DEFAULT_ARTIFACT_RETENTION_CLASS, MAX_ARTIFACT_FILENAME_LENGTH, MAX_ARTIFACTS_PER_RUN, MAX_ARTIFACT_SUMMARIES_PER_TIMELINE_ITEM, MAX_ARTIFACT_TITLE_LENGTH, MAX_ARTIFACT_URL_LENGTH, MAX_MANAGED_ARTIFACT_BYTES, } from './types.js';
+const ARTIFACT_KINDS = new Set(['report', 'screenshot', 'log_excerpt', 'structured_result']);
+const ARTIFACT_SENSITIVITIES = new Set(['normal', 'sensitive']);
+const ARTIFACT_RETENTION_CLASSES = new Set(['short', 'standard']);
+const ARTIFACT_AVAILABILITIES = new Set([
+    'available',
+    'expired',
+    'missing',
+    'deletion_failed',
+    'deleted',
+]);
+const MEDIA_TYPES_BY_KIND = {
+    report: new Set(['text/plain', 'text/markdown', 'application/json', 'application/pdf']),
+    screenshot: new Set(['image/png', 'image/jpeg', 'image/webp']),
+    log_excerpt: new Set(['text/plain']),
+    structured_result: new Set(['application/json']),
+};
+const MAX_BATCH_RUN_IDS = 200;
+const MAX_CLEANUP_ERROR_BYTES = 2_048;
+export const ARTIFACT_REGISTRATION_HEARTBEAT_MS = 30_000;
+export class ExecutionArtifactError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'ExecutionArtifactError';
+        this.code = code;
+    }
+}
+const intentSelect = `
+  SELECT *
+  FROM execution_artifact_registration_intents
+  WHERE artifact_id = ? AND project_id = ? AND execution_run_id = ?
+`;
+const artifactSelect = `
+  SELECT *
+  FROM execution_artifacts
+  WHERE id = ? AND project_id = ? AND execution_run_id = ?
+`;
+const normalizeRequiredText = (value, name, maxLength) => {
+    const normalized = value.trim();
+    if (!normalized || normalized.length > maxLength || normalized.includes('\0')) {
+        throw new ExecutionArtifactError('invalid_input', `${name} must contain between 1 and ${maxLength} characters`);
+    }
+    return normalized;
+};
+const normalizeRegistrationInput = (input) => {
+    const artifactId = normalizeRequiredText(input.artifactId, 'Artifact ID', 255);
+    const projectId = normalizeRequiredText(input.projectId, 'Project ID', 255);
+    const runId = normalizeRequiredText(input.runId, 'Execution run ID', 255);
+    const title = normalizeRequiredText(input.title, 'Artifact title', MAX_ARTIFACT_TITLE_LENGTH);
+    const mediaType = normalizeRequiredText(input.mediaType, 'Artifact media type', 255).toLowerCase();
+    const sensitivity = input.sensitivity ?? 'normal';
+    const retentionClass = input.retentionClass ?? DEFAULT_ARTIFACT_RETENTION_CLASS;
+    if (!ARTIFACT_KINDS.has(input.kind)) {
+        throw new ExecutionArtifactError('invalid_input', 'Unsupported artifact kind');
+    }
+    if (!ARTIFACT_SENSITIVITIES.has(sensitivity)) {
+        throw new ExecutionArtifactError('invalid_input', 'Unsupported artifact sensitivity');
+    }
+    if (!ARTIFACT_RETENTION_CLASSES.has(retentionClass)) {
+        throw new ExecutionArtifactError('invalid_input', 'Unsupported artifact retention class');
+    }
+    if (!MEDIA_TYPES_BY_KIND[input.kind].has(mediaType)) {
+        throw new ExecutionArtifactError('invalid_input', `Unsupported media type for ${input.kind} artifacts`);
+    }
+    return { artifactId, projectId, runId, kind: input.kind, title, mediaType, sensitivity, retentionClass };
+};
+const normalizeFilename = (value) => {
+    const filename = normalizeRequiredText(value, 'Artifact filename', MAX_ARTIFACT_FILENAME_LENGTH);
+    if (filename !== basename(filename) || filename === '.' || filename === '..' || filename.includes('/') || filename.includes('\\')) {
+        throw new ExecutionArtifactError('invalid_input', 'Artifact filename must not contain path components');
+    }
+    return filename;
+};
+const pathSegment = (value) => createHash('sha256').update(value).digest('hex').slice(0, 32);
+const generateRelativePaths = (projectId, runId, artifactId) => {
+    const directory = [pathSegment(projectId), pathSegment(runId)].join('/');
+    const reservationId = randomUUID();
+    const artifactSegment = pathSegment(artifactId);
+    const finalRelativePath = `${directory}/${artifactSegment}.${reservationId}.artifact`;
+    const temporaryRelativePath = `${directory}/.${artifactSegment}.${reservationId}.tmp`;
+    return { temporaryRelativePath, finalRelativePath };
+};
+const currentSqlTimestamp = () => new Date(Math.floor(Date.now() / 1_000) * 1_000).toISOString();
+const expiryFor = (createdAt, retentionClass) => (new Date(Date.parse(createdAt) + ARTIFACT_RETENTION_DURATIONS_MS[retentionClass]).toISOString());
+const isConstraintError = (error) => (error instanceof Error && (error.message.includes('UNIQUE constraint failed')
+    || error.message.includes('Artifact identity exists')
+    || error.message.includes('FOREIGN KEY constraint failed')));
+export const getExecutionArtifactRegistrationIntent = (projectId, runId, artifactId) => {
+    const row = db.prepare(intentSelect).get(artifactId, projectId, runId);
+    return row ?? null;
+};
+export const reserveExecutionArtifactRegistration = (input) => {
+    const normalized = normalizeRegistrationInput(input);
+    const filename = normalizeFilename(input.filename);
+    const paths = generateRelativePaths(normalized.projectId, normalized.runId, normalized.artifactId);
+    const createdAt = currentSqlTimestamp();
+    const expiresAt = expiryFor(createdAt, normalized.retentionClass);
+    try {
+        return withExecutionRunTransaction(() => {
+            const projectDeleting = db.prepare('SELECT deletion_started_at FROM projects WHERE id = ?').get(normalized.projectId);
+            if (isProjectArtifactCleanupActive(normalized.projectId) || projectDeleting?.deletion_started_at) {
+                throw new ExecutionArtifactError('conflict', 'Artifact registration is unavailable while the project is being deleted');
+            }
+            const run = db.prepare('SELECT 1 FROM execution_runs WHERE id = ? AND project_id = ?').get(normalized.runId, normalized.projectId);
+            if (!run) {
+                throw new ExecutionArtifactError('not_found', 'Execution run not found');
+            }
+            db.prepare(`
+        INSERT INTO execution_artifact_registration_intents (
+          artifact_id, execution_run_id, project_id, kind, title, media_type,
+          sensitivity, retention_class, expires_at, filename,
+          temporary_relative_path, final_relative_path, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(normalized.artifactId, normalized.runId, normalized.projectId, normalized.kind, normalized.title, normalized.mediaType, normalized.sensitivity, normalized.retentionClass, expiresAt, filename, paths.temporaryRelativePath, paths.finalRelativePath, createdAt, createdAt);
+            const intent = getExecutionArtifactRegistrationIntent(normalized.projectId, normalized.runId, normalized.artifactId);
+            if (!intent) {
+                throw new Error('Artifact reservation was not persisted');
+            }
+            return intent;
+        });
+    }
+    catch (error) {
+        if (error instanceof ExecutionArtifactError) {
+            throw error;
+        }
+        if (isConstraintError(error)) {
+            throw new ExecutionArtifactError('conflict', 'Artifact identity is already registered or the run is at capacity', error);
+        }
+        throw error;
+    }
+};
+const updateIntentState = (intent, expectedState, state) => {
+    const result = db.prepare(`
+    UPDATE execution_artifact_registration_intents
+    SET state = ?, updated_at = ?
+    WHERE artifact_id = ? AND project_id = ? AND execution_run_id = ?
+      AND temporary_relative_path = ? AND final_relative_path = ?
+      AND state = ?
+  `).run(state, currentSqlTimestamp(), intent.artifact_id, intent.project_id, intent.execution_run_id, intent.temporary_relative_path, intent.final_relative_path, expectedState);
+    if (result.changes !== 1) {
+        throw new ExecutionArtifactError('conflict', 'Artifact reservation is no longer owned by this registration');
+    }
+};
+const renewIntentLease = (intent) => {
+    const result = db.prepare(`
+    UPDATE execution_artifact_registration_intents
+    SET updated_at = ?
+    WHERE artifact_id = ? AND project_id = ? AND execution_run_id = ?
+      AND temporary_relative_path = ? AND final_relative_path = ?
+      AND state IN ('writing', 'publishing')
+      AND cleanup_claim_id IS NULL
+  `).run(currentSqlTimestamp(), intent.artifact_id, intent.project_id, intent.execution_run_id, intent.temporary_relative_path, intent.final_relative_path);
+    if (result.changes !== 1) {
+        throw new ExecutionArtifactError('conflict', 'Artifact reservation is no longer owned by this registration');
+    }
+};
+const startIntentHeartbeat = (intent, content) => {
+    let ownershipError = null;
+    const renew = () => {
+        if (ownershipError) {
+            throw ownershipError;
+        }
+        try {
+            renewIntentLease(intent);
+        }
+        catch (error) {
+            ownershipError = error instanceof ExecutionArtifactError
+                ? error
+                : new ExecutionArtifactError('conflict', 'Artifact reservation heartbeat failed', error);
+            destroyContent(content, ownershipError);
+            throw ownershipError;
+        }
+    };
+    const timer = setInterval(() => {
+        try {
+            renew();
+        }
+        catch {
+            // The registration observes ownership loss before publication or finalization.
+        }
+    }, ARTIFACT_REGISTRATION_HEARTBEAT_MS);
+    timer.unref();
+    return {
+        assertOwned: renew,
+        stop: () => clearInterval(timer),
+    };
+};
+const resolveOwnedPath = (root, relativePath) => {
+    if (isAbsolute(relativePath) || relativePath.includes('\\')) {
+        throw new ExecutionArtifactError('storage_error', 'Artifact storage path is invalid');
+    }
+    const resolved = resolve(root, relativePath);
+    const fromRoot = relative(resolve(root), resolved);
+    if (!fromRoot || fromRoot === '..' || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) {
+        throw new ExecutionArtifactError('storage_error', 'Artifact storage path escapes the artifact root');
+    }
+    return resolved;
+};
+const prepareOwnedPaths = async (intent) => {
+    const configuredRoot = resolveArchonArtifactsRoot();
+    await mkdir(configuredRoot, { recursive: true });
+    const root = await realpath(configuredRoot);
+    const temporaryPath = resolveOwnedPath(root, intent.temporary_relative_path);
+    const finalPath = resolveOwnedPath(root, intent.final_relative_path);
+    const relativeParent = relative(root, dirname(temporaryPath));
+    let ownedParent = root;
+    for (const segment of relativeParent.split(sep)) {
+        if (!segment || segment === '.' || segment === '..') {
+            throw new ExecutionArtifactError('storage_error', 'Artifact storage directory is invalid');
+        }
+        ownedParent = resolve(ownedParent, segment);
+        try {
+            await mkdir(ownedParent, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST') {
+                throw error;
+            }
+        }
+        const stats = await lstat(ownedParent);
+        if (!stats.isDirectory() || stats.isSymbolicLink()) {
+            throw new ExecutionArtifactError('storage_error', 'Artifact storage directory must not be a symbolic link');
+        }
+    }
+    const actualParent = await realpath(ownedParent);
+    const parentFromRoot = relative(root, actualParent);
+    if (parentFromRoot === '..' || parentFromRoot.startsWith(`..${sep}`) || isAbsolute(parentFromRoot)) {
+        throw new ExecutionArtifactError('storage_error', 'Artifact storage directory escapes the artifact root');
+    }
+    return { temporaryPath, finalPath };
+};
+const destroyContent = (content, error) => {
+    const destroy = content.destroy;
+    if (typeof destroy === 'function') {
+        destroy.call(content, error);
+    }
+};
+const writeManagedContent = async (temporaryPath, content, onCreated) => {
+    const handle = await open(temporaryPath, 'wx', 0o600);
+    onCreated();
+    const hash = createHash('sha256');
+    let byteSize = 0;
+    try {
+        const chunks = Buffer.isBuffer(content)
+            ? (async function* () { yield content; })()
+            : content;
+        for await (const chunk of chunks) {
+            const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : Buffer.from(chunk);
+            byteSize += bytes.byteLength;
+            if (byteSize > MAX_MANAGED_ARTIFACT_BYTES) {
+                const error = new ExecutionArtifactError('invalid_input', 'Managed artifact exceeds the 25 MiB limit');
+                destroyContent(content, error);
+                throw error;
+            }
+            let offset = 0;
+            while (offset < bytes.byteLength) {
+                const { bytesWritten } = await handle.write(bytes, offset, bytes.byteLength - offset);
+                if (bytesWritten === 0) {
+                    throw new ExecutionArtifactError('storage_error', 'Managed artifact write made no progress');
+                }
+                offset += bytesWritten;
+            }
+            hash.update(bytes);
+        }
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    return { byteSize, sha256: hash.digest('hex') };
+};
+const boundedCleanupError = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    return truncateUtf8(message, MAX_CLEANUP_ERROR_BYTES).text ?? 'Artifact cleanup failed';
+};
+const removeIfOwned = async (path, owned) => {
+    if (!owned) {
+        return null;
+    }
+    try {
+        await unlink(path);
+        return null;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        return error;
+    }
+};
+const compensateRegistration = async (intent, paths, ownership) => {
+    const errors = paths
+        ? (await Promise.all([
+            removeIfOwned(paths.temporaryPath, ownership.temporary),
+            removeIfOwned(paths.finalPath, ownership.final),
+        ])).filter(error => error !== null)
+        : [];
+    if (errors.length === 0) {
+        db.prepare(`
+      DELETE FROM execution_artifact_registration_intents
+      WHERE artifact_id = ? AND project_id = ? AND execution_run_id = ?
+        AND temporary_relative_path = ? AND final_relative_path = ?
+        AND state NOT IN ('cleanup_pending', 'cleanup_failed')
+    `).run(intent.artifact_id, intent.project_id, intent.execution_run_id, intent.temporary_relative_path, intent.final_relative_path);
+        return;
+    }
+    const now = currentSqlTimestamp();
+    db.prepare(`
+    UPDATE execution_artifact_registration_intents
+    SET state = CASE WHEN cleanup_attempts >= 9 THEN 'cleanup_failed' ELSE 'cleanup_pending' END,
+        cleanup_attempts = MIN(cleanup_attempts + 1, 10),
+        last_cleanup_error = ?, last_cleanup_attempt_at = ?, updated_at = ?
+    WHERE artifact_id = ? AND project_id = ? AND execution_run_id = ?
+      AND temporary_relative_path = ? AND final_relative_path = ?
+  `).run(boundedCleanupError(errors[0]), now, now, intent.artifact_id, intent.project_id, intent.execution_run_id, intent.temporary_relative_path, intent.final_relative_path);
+};
+const finalizeArtifact = ({ intent, expectedState, storageType, byteSize, sha256, externalUrl, emitter }) => (withExecutionRunTransaction(transaction => {
+    const ownedIntent = getExecutionArtifactRegistrationIntent(intent.project_id, intent.execution_run_id, intent.artifact_id);
+    if (!ownedIntent
+        || ownedIntent.temporary_relative_path !== intent.temporary_relative_path
+        || ownedIntent.final_relative_path !== intent.final_relative_path
+        || ownedIntent.state !== expectedState) {
+        throw new ExecutionArtifactError('conflict', 'Artifact reservation is no longer owned by this registration');
+    }
+    const removed = db.prepare(`
+      DELETE FROM execution_artifact_registration_intents
+      WHERE artifact_id = ? AND project_id = ? AND execution_run_id = ?
+        AND temporary_relative_path = ? AND final_relative_path = ?
+        AND state = ?
+    `).run(intent.artifact_id, intent.project_id, intent.execution_run_id, intent.temporary_relative_path, intent.final_relative_path, expectedState);
+    if (removed.changes !== 1) {
+        throw new ExecutionArtifactError('conflict', 'Artifact reservation could not be finalized');
+    }
+    db.prepare(`
+      INSERT INTO execution_artifacts (
+        id, execution_run_id, project_id, kind, title, storage_type, availability,
+        media_type, byte_size, sha256, sensitivity, retention_class, expires_at,
+        filename, managed_relative_path, external_url, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, 'available', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(intent.artifact_id, intent.execution_run_id, intent.project_id, intent.kind, intent.title, storageType, intent.media_type, byteSize, sha256, intent.sensitivity, intent.retention_class, intent.expires_at, storageType === 'managed_file' ? intent.filename : null, storageType === 'managed_file' ? intent.final_relative_path : null, externalUrl, intent.created_at, intent.created_at);
+    transaction.appendLifecycleEvent({
+        projectId: intent.project_id,
+        runId: intent.execution_run_id,
+        eventType: 'artifact_created',
+        metadata: intent.sensitivity === 'normal' ? { artifact_id: intent.artifact_id } : null,
+    });
+    const artifact = getExecutionArtifact(intent.project_id, intent.execution_run_id, intent.artifact_id);
+    if (!artifact) {
+        throw new Error('Finalized artifact metadata was not persisted');
+    }
+    return artifact;
+}, emitter));
+const publicationError = (error) => {
+    const code = error.code;
+    if (code === 'EEXIST') {
+        return new ExecutionArtifactError('conflict', 'Artifact destination already exists', error);
+    }
+    if (code === 'EXDEV' || code === 'ENOTSUP' || code === 'EOPNOTSUPP' || code === 'EPERM') {
+        return new ExecutionArtifactError('storage_error', 'Artifact storage does not support no-clobber publication', error);
+    }
+    return new ExecutionArtifactError('storage_error', 'Artifact could not be published', error);
+};
+export const registerManagedExecutionArtifact = async (input, emitter) => {
+    const intent = reserveExecutionArtifactRegistration(input);
+    let paths = null;
+    let ownsTemporary = false;
+    let ownsFinal = false;
+    let heartbeat = null;
+    try {
+        updateIntentState(intent, 'reserved', 'writing');
+        heartbeat = startIntentHeartbeat(intent, input.content);
+        paths = await prepareOwnedPaths(intent);
+        const digest = await writeManagedContent(paths.temporaryPath, input.content, () => {
+            ownsTemporary = true;
+        });
+        heartbeat.assertOwned();
+        updateIntentState(intent, 'writing', 'publishing');
+        heartbeat.assertOwned();
+        try {
+            await link(paths.temporaryPath, paths.finalPath);
+            ownsFinal = true;
+        }
+        catch (error) {
+            throw publicationError(error);
+        }
+        await unlink(paths.temporaryPath);
+        ownsTemporary = false;
+        heartbeat.assertOwned();
+        return finalizeArtifact({
+            intent,
+            expectedState: 'publishing',
+            storageType: 'managed_file',
+            byteSize: digest.byteSize,
+            sha256: digest.sha256,
+            externalUrl: null,
+            emitter,
+        });
+    }
+    catch (error) {
+        await compensateRegistration(intent, paths, { temporary: ownsTemporary, final: ownsFinal });
+        throw error;
+    }
+    finally {
+        heartbeat?.stop();
+    }
+};
+const isPrivateIpv4 = (address) => {
+    const octets = address.split('.').map(Number);
+    return octets[0] === 0
+        || octets[0] === 10
+        || octets[0] === 127
+        || (octets[0] === 169 && octets[1] === 254)
+        || (octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31)
+        || (octets[0] === 192 && octets[1] === 168);
+};
+const isPrivateIpv6 = (address) => {
+    const normalized = address.toLowerCase();
+    const [leftValue, rightValue = ''] = normalized.split('::');
+    const left = leftValue ? leftValue.split(':') : [];
+    const right = rightValue ? rightValue.split(':') : [];
+    const missingGroups = 8 - left.length - right.length;
+    const groups = normalized.includes('::')
+        ? [...left, ...Array(Math.max(0, missingGroups)).fill('0'), ...right]
+        : left;
+    if (groups.length !== 8) {
+        return true;
+    }
+    const bytes = groups.flatMap(group => {
+        const value = Number.parseInt(group || '0', 16);
+        return [value >> 8, value & 0xff];
+    });
+    const isUnspecified = bytes.every(byte => byte === 0);
+    const isLoopback = bytes.slice(0, 15).every(byte => byte === 0) && bytes[15] === 1;
+    const isUniqueLocal = (bytes[0] & 0xfe) === 0xfc;
+    const isLinkLocal = bytes[0] === 0xfe && (bytes[1] & 0xc0) === 0x80;
+    const isMappedIpv4 = bytes.slice(0, 10).every(byte => byte === 0) && bytes[10] === 0xff && bytes[11] === 0xff;
+    const mappedIpv4 = bytes.slice(12).join('.');
+    return isUnspecified || isLoopback || isUniqueLocal || isLinkLocal || (isMappedIpv4 && isPrivateIpv4(mappedIpv4));
+};
+const validateExternalUrl = (value) => {
+    const normalized = normalizeRequiredText(value, 'External artifact URL', MAX_ARTIFACT_URL_LENGTH);
+    let url;
+    try {
+        url = new URL(normalized);
+    }
+    catch (error) {
+        throw new ExecutionArtifactError('invalid_input', 'External artifact URL is invalid', error);
+    }
+    if (url.protocol !== 'https:' || url.username || url.password || url.hash) {
+        throw new ExecutionArtifactError('invalid_input', 'External artifacts require an HTTPS URL without credentials or a fragment');
+    }
+    const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.+$/, '');
+    const ipVersion = isIP(hostname);
+    if (hostname === 'localhost'
+        || hostname.endsWith('.localhost')
+        || (ipVersion === 4 && isPrivateIpv4(hostname))
+        || (ipVersion === 6 && isPrivateIpv6(hostname))) {
+        throw new ExecutionArtifactError('invalid_input', 'External artifact URL target is not allowed');
+    }
+    return url.toString();
+};
+export const registerExternalExecutionArtifact = (input, emitter) => {
+    const normalized = normalizeRegistrationInput(input);
+    if (normalized.sensitivity !== 'normal') {
+        throw new ExecutionArtifactError('invalid_input', 'External artifacts must use normal sensitivity');
+    }
+    const externalUrl = validateExternalUrl(input.url);
+    const intent = reserveExecutionArtifactRegistration({
+        ...input,
+        filename: `${pathSegment(normalized.artifactId)}.external`,
+    });
+    try {
+        return finalizeArtifact({
+            intent,
+            expectedState: 'reserved',
+            storageType: 'external_url',
+            byteSize: null,
+            sha256: null,
+            externalUrl,
+            emitter,
+        });
+    }
+    catch (error) {
+        db.prepare(`
+      DELETE FROM execution_artifact_registration_intents
+      WHERE artifact_id = ? AND project_id = ? AND execution_run_id = ?
+        AND temporary_relative_path = ? AND final_relative_path = ?
+        AND state = 'reserved'
+    `).run(intent.artifact_id, intent.project_id, intent.execution_run_id, intent.temporary_relative_path, intent.final_relative_path);
+        throw error;
+    }
+};
+export const getExecutionArtifact = (projectId, runId, artifactId) => {
+    const row = db.prepare(artifactSelect).get(artifactId, projectId, runId);
+    return row ?? null;
+};
+const isArtifactRetrievable = (row, now) => (row.availability === 'available'
+    && Number.isFinite(Date.parse(row.expires_at))
+    && Date.parse(row.expires_at) > now);
+const toPublicSummary = (row, now) => ({
+    id: row.id,
+    execution_run_id: row.execution_run_id,
+    project_id: row.project_id,
+    kind: row.kind,
+    title: row.sensitivity === 'sensitive' ? null : row.title,
+    storage_type: row.storage_type,
+    availability: row.availability === 'available' && !isArtifactRetrievable(row, now) ? 'expired' : row.availability,
+    media_type: row.media_type,
+    byte_size: row.byte_size,
+    sensitivity: row.sensitivity,
+    expires_at: row.expires_at,
+    filename: row.sensitivity === 'sensitive' ? null : row.filename,
+    created_at: row.created_at,
+    actions: isArtifactRetrievable(row, now)
+        ? [row.storage_type === 'managed_file' ? 'download' : 'open_external']
+        : [],
+});
+export const getExecutionArtifactSummary = (projectId, runId, artifactId) => {
+    const artifact = getExecutionArtifact(projectId, runId, artifactId);
+    return artifact ? toPublicSummary(artifact, Date.now()) : null;
+};
+export const loadExecutionArtifactSummariesForRuns = (projectId, runIds, perRunLimit = MAX_ARTIFACT_SUMMARIES_PER_TIMELINE_ITEM) => {
+    const uniqueRunIds = [...new Set(runIds)];
+    const now = Date.now();
+    if (uniqueRunIds.length === 0) {
+        return new Map();
+    }
+    if (uniqueRunIds.length > MAX_BATCH_RUN_IDS) {
+        throw new ExecutionArtifactError('invalid_input', `Artifact summary lookup supports at most ${MAX_BATCH_RUN_IDS} runs`);
+    }
+    if (!Number.isInteger(perRunLimit) || perRunLimit < 1 || perRunLimit > MAX_ARTIFACTS_PER_RUN) {
+        throw new ExecutionArtifactError('invalid_input', `Artifact summary limit must be between 1 and ${MAX_ARTIFACTS_PER_RUN}`);
+    }
+    const placeholders = uniqueRunIds.map(() => '?').join(', ');
+    const rows = db.prepare(`
+    SELECT * FROM (
+      SELECT execution_artifacts.*,
+        COUNT(*) OVER (PARTITION BY execution_run_id) AS artifact_count,
+        ROW_NUMBER() OVER (
+          PARTITION BY execution_run_id
+          ORDER BY created_at DESC, id DESC
+        ) AS artifact_rank
+      FROM execution_artifacts
+      WHERE project_id = ? AND execution_run_id IN (${placeholders})
+    )
+    WHERE artifact_rank <= ?
+    ORDER BY execution_run_id, created_at DESC, id DESC
+  `).all(projectId, ...uniqueRunIds, perRunLimit);
+    const summaries = new Map(uniqueRunIds.map(runId => [runId, { artifacts: [], artifact_count: 0 }]));
+    for (const row of rows) {
+        const batch = summaries.get(row.execution_run_id);
+        if (batch) {
+            batch.artifacts.push(toPublicSummary(row, now));
+            batch.artifact_count = row.artifact_count;
+        }
+    }
+    return summaries;
+};
+const isOwnedPath = (root, path) => {
+    const fromRoot = relative(root, path);
+    return fromRoot !== '' && fromRoot !== '..' && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot);
+};
+const sanitizeDownloadFilename = (filename, sensitive) => {
+    if (sensitive || !filename) {
+        return 'artifact';
+    }
+    const sanitized = filename
+        .normalize('NFKD')
+        .replace(/[^\x20-\x7E]/g, '_')
+        .replace(/["\\/;\r\n]/g, '_')
+        .replace(/^\.+/, '')
+        .slice(0, MAX_ARTIFACT_FILENAME_LENGTH);
+    return sanitized || 'artifact';
+};
+export const openExecutionArtifactForRetrieval = async (projectId, runId, artifactId, emitter) => {
+    const artifact = getExecutionArtifact(projectId, runId, artifactId);
+    if (!artifact) {
+        return { kind: 'not_found' };
+    }
+    if (!isArtifactRetrievable(artifact, Date.now())) {
+        return { kind: 'unavailable' };
+    }
+    if (!MEDIA_TYPES_BY_KIND[artifact.kind].has(artifact.media_type)) {
+        return { kind: 'unavailable' };
+    }
+    if (artifact.storage_type === 'external_url') {
+        if (!artifact.external_url) {
+            return { kind: 'unavailable' };
+        }
+        try {
+            return { kind: 'external', url: validateExternalUrl(artifact.external_url) };
+        }
+        catch {
+            return { kind: 'unavailable' };
+        }
+    }
+    if (!artifact.managed_relative_path) {
+        return { kind: 'unavailable' };
+    }
+    try {
+        const root = await realpath(resolveArchonArtifactsRoot());
+        const path = resolveOwnedPath(root, artifact.managed_relative_path);
+        const parent = await realpath(dirname(path));
+        if (!isOwnedPath(root, parent)) {
+            return { kind: 'unavailable' };
+        }
+        const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stats = await handle.stat();
+            if (!stats.isFile()) {
+                await handle.close();
+                return { kind: 'unavailable' };
+            }
+            const current = getExecutionArtifact(projectId, runId, artifactId);
+            if (!current || !isArtifactRetrievable(current, Date.now())) {
+                await handle.close();
+                return { kind: 'unavailable' };
+            }
+            return {
+                kind: 'managed',
+                handle,
+                byteSize: stats.size,
+                filename: sanitizeDownloadFilename(artifact.filename, artifact.sensitivity === 'sensitive'),
+                mediaType: artifact.media_type,
+            };
+        }
+        catch (error) {
+            await handle.close().catch(() => undefined);
+            throw error;
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            observeExecutionArtifactMissing(projectId, runId, artifactId, emitter);
+        }
+        return { kind: 'unavailable' };
+    }
+};
+const observeExecutionArtifactMissing = (projectId, runId, artifactId, emitter) => withExecutionRunTransaction(transaction => {
+    const now = currentSqlTimestamp();
+    const result = db.prepare(`
+    UPDATE execution_artifacts
+    SET availability = 'missing', updated_at = ?
+    WHERE id = ? AND project_id = ? AND execution_run_id = ?
+      AND availability = 'available'
+  `).run(now, artifactId, projectId, runId);
+    if (result.changes !== 1) {
+        return;
+    }
+    const artifact = getExecutionArtifact(projectId, runId, artifactId);
+    transaction.appendLifecycleEvent({
+        projectId,
+        runId,
+        eventType: 'artifact_availability_changed',
+        domainStatus: 'missing',
+        metadata: artifact?.sensitivity === 'normal' ? { artifact_id: artifactId } : null,
+    });
+}, emitter);
+export const persistExecutionArtifactAvailability = (input, emitter) => {
+    if (!ARTIFACT_AVAILABILITIES.has(input.availability)) {
+        throw new ExecutionArtifactError('invalid_input', 'Unsupported artifact availability');
+    }
+    return withExecutionRunTransaction(transaction => {
+        const current = getExecutionArtifact(input.projectId, input.runId, input.artifactId);
+        if (!current) {
+            throw new ExecutionArtifactError('not_found', 'Execution artifact not found');
+        }
+        if (current.availability === input.availability) {
+            return current;
+        }
+        if (current.availability !== 'available' || input.availability !== 'missing') {
+            throw new ExecutionArtifactError('conflict', 'Artifact availability transition is managed by retention cleanup');
+        }
+        const now = currentSqlTimestamp();
+        db.prepare(`
+      UPDATE execution_artifacts
+      SET availability = ?, updated_at = ?, deleted_at = CASE WHEN ? = 'deleted' THEN ? ELSE deleted_at END
+      WHERE id = ? AND project_id = ? AND execution_run_id = ?
+    `).run(input.availability, now, input.availability, now, input.artifactId, input.projectId, input.runId);
+        transaction.appendLifecycleEvent({
+            projectId: input.projectId,
+            runId: input.runId,
+            eventType: 'artifact_availability_changed',
+            domainStatus: input.availability,
+            metadata: current.sensitivity === 'normal' ? { artifact_id: current.id } : null,
+        });
+        const updated = getExecutionArtifact(input.projectId, input.runId, input.artifactId);
+        if (!updated) {
+            throw new Error('Updated artifact metadata was not persisted');
+        }
+        return updated;
+    }, emitter);
+};
+//# sourceMappingURL=executionArtifacts.js.map