@straiffi/archon 1.8.15 → 1.8.17

package/dist/server/lib/executionEnvironments.js

@@ -0,0 +1,726 @@
+import { randomUUID } from 'crypto';
+import db from '../db.js';
+import { canonicalizeEnvironmentValidationFingerprintInput, createEnvironmentValidationFingerprint, } from './executionEnvironmentLifecycle.js';
+const MAX_JSON_BYTES = 16 * 1024;
+const MAX_EVENT_MESSAGE_LENGTH = 4_000;
+const REUSABLE_STATES = ['ready', 'running', 'stopped'];
+const CLEANUP_CLAIMABLE_STATES = ['retiring', 'cleanup_pending', 'failed', 'unavailable'];
+const ALLOWED_TRANSITIONS = {
+    queued: new Set(['preparing', 'retiring', 'failed', 'unavailable']),
+    preparing: new Set(['ready', 'stopped', 'retiring', 'cleanup_pending', 'failed', 'unavailable']),
+    ready: new Set(['running', 'stopped', 'retiring', 'failed', 'unavailable']),
+    running: new Set(['ready', 'stopped', 'retiring', 'failed', 'unavailable']),
+    stopped: new Set(['preparing', 'ready', 'running', 'retiring', 'failed', 'unavailable']),
+    retiring: new Set(['cleanup_pending', 'retired', 'failed', 'unavailable']),
+    cleanup_pending: new Set(['retired', 'failed', 'unavailable']),
+    retired: new Set(),
+    failed: new Set(['preparing', 'retiring', 'cleanup_pending']),
+    unavailable: new Set(['preparing', 'retiring', 'cleanup_pending']),
+};
+const getEnvironmentStatement = db.prepare(`
+  SELECT * FROM execution_environments WHERE id = ? AND project_id = ?
+`);
+const projectExistsStatement = db.prepare(`
+  SELECT 1 FROM projects WHERE id = ? AND deletion_started_at IS NULL
+`);
+const insertEnvironmentStatement = db.prepare(`
+  INSERT INTO execution_environments (
+    id, project_id, provider_kind, provider_version, external_id, target_kind, target_key,
+    target_workspace_path, environment_revision, workspace_mode,
+    environment_validation_fingerprint, template_identity, template_digest, agent_identity,
+    compatible_agents_json, capabilities_json, lifecycle_state, created_at, updated_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'direct', ?, ?, ?, ?, ?, ?, 'queued', ?, ?)
+`);
+const updateEnvironmentStatement = db.prepare(`
+  UPDATE execution_environments
+  SET lifecycle_state = ?, external_id = ?, capabilities_json = ?, failure_code = ?,
+      failure_message = ?, failure_details_json = ?, preparation_started_at = ?, ready_at = ?,
+      last_validated_at = ?, last_used_at = ?, stopped_at = ?, retirement_started_at = ?,
+      cleanup_pending_at = ?, retired_at = ?, failed_at = ?, unavailable_at = ?, updated_at = ?
+  WHERE id = ? AND project_id = ? AND lifecycle_state = ?
+`);
+const insertEventStatement = db.prepare(`
+  INSERT INTO execution_environment_events (
+    id, project_id, environment_id, sequence, event_type, from_state, to_state, message,
+    metadata_schema_version, metadata_json, created_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+`);
+const nextEventSequenceStatement = db.prepare(`
+  SELECT COALESCE(MAX(sequence), 0) + 1 AS sequence
+  FROM execution_environment_events WHERE environment_id = ?
+`);
+const getEventStatement = db.prepare(`
+  SELECT * FROM execution_environment_events WHERE id = ? AND project_id = ?
+`);
+const insertBindingStatement = db.prepare(`
+  INSERT INTO execution_environment_run_bindings (
+    environment_id, execution_run_id, project_id, relationship, environment_revision,
+    environment_validation_fingerprint, authority_json, bound_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+`);
+const getBindingStatement = db.prepare(`
+  SELECT * FROM execution_environment_run_bindings
+  WHERE environment_id = ? AND execution_run_id = ? AND relationship = ?
+`);
+const releaseBindingStatement = db.prepare(`
+  UPDATE execution_environment_run_bindings
+  SET released_at = ?
+  WHERE environment_id = ? AND execution_run_id = ? AND project_id = ?
+    AND relationship = ? AND released_at IS NULL
+`);
+const capturePlacementStatement = db.prepare(`
+  UPDATE execution_environment_run_bindings
+  SET placement_json = ?
+  WHERE environment_id = ? AND execution_run_id = ? AND project_id = ?
+    AND relationship = 'execution' AND released_at IS NULL AND placement_json IS NULL
+`);
+const assertBoundedString = (value, name, maxBytes) => {
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (bytes < 1 || bytes > maxBytes) {
+        throw new Error(`${name} must contain between 1 and ${maxBytes} bytes`);
+    }
+};
+const serializeBoundedObject = (value, name) => {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch {
+        throw new Error(`${name} must be JSON serializable`);
+    }
+    if (Buffer.byteLength(serialized, 'utf8') > MAX_JSON_BYTES) {
+        throw new Error(`${name} exceeds ${MAX_JSON_BYTES} bytes`);
+    }
+    return serialized;
+};
+const parseStoredObject = (value) => {
+    if (value === null || Buffer.byteLength(value, 'utf8') > MAX_JSON_BYTES) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+};
+const createDefaultAuthority = (environment) => {
+    if (environment.provider_kind !== 'docker_sandbox' || !environment.agent_identity) {
+        throw new Error('Execution bindings require an explicit Docker Sandbox authority snapshot');
+    }
+    return {
+        schema_version: 1,
+        provider: 'docker_sandbox',
+        provider_version: environment.provider_version,
+        environment_id: environment.id,
+        environment_revision: environment.environment_revision,
+        environment_validation_fingerprint: environment.environment_validation_fingerprint,
+        target: {
+            kind: environment.target_kind,
+            key: environment.target_key,
+            workspace_path: environment.target_workspace_path,
+        },
+        capabilities: environment.capabilities,
+        degradation_reasons: environment.workspace_mode === 'direct' ? ['direct_workspace_writable'] : [],
+        agent: environment.agent_identity,
+        authentication_mode: 'validated_guest',
+        credential_delivery: 'sandbox_template',
+    };
+};
+const assertAuthorityMatchesEnvironment = (authority, environment) => {
+    if (authority.schema_version !== 1
+        || authority.provider !== 'docker_sandbox'
+        || authority.provider_version !== environment.provider_version
+        || authority.environment_id !== environment.id
+        || authority.environment_revision !== environment.environment_revision
+        || authority.environment_validation_fingerprint !== environment.environment_validation_fingerprint
+        || authority.target.kind !== environment.target_kind
+        || authority.target.key !== environment.target_key
+        || authority.target.workspace_path !== environment.target_workspace_path
+        || authority.agent !== environment.agent_identity
+        || authority.authentication_mode !== 'validated_guest'
+        || authority.credential_delivery !== 'sandbox_template') {
+        throw new Error('Execution environment authority does not match the durable environment identity');
+    }
+};
+const parseCompatibleAgents = (value) => {
+    if (Buffer.byteLength(value, 'utf8') > 100) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed)
+            || parsed.length === 0
+            || parsed.some(agent => agent !== 'opencode' && agent !== 'claude')
+            || new Set(parsed).size !== parsed.length
+            || [...parsed].sort().some((agent, index) => agent !== parsed[index])) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+};
+const serializeEnvironment = (row) => {
+    const compatibleAgents = parseCompatibleAgents(row.compatible_agents_json);
+    const capabilities = parseStoredObject(row.capabilities_json);
+    if (compatibleAgents === null
+        || capabilities === null
+        || !/^[0-9a-f]{64}$/.test(row.environment_validation_fingerprint)) {
+        return null;
+    }
+    return {
+        ...row,
+        compatible_agents: compatibleAgents,
+        capabilities,
+        failure_details: parseStoredObject(row.failure_details_json),
+    };
+};
+const serializeEvent = (row) => ({
+    ...row,
+    metadata: parseStoredObject(row.metadata_json),
+});
+const requireEnvironment = (projectId, environmentId) => {
+    const row = getEnvironmentStatement.get(environmentId, projectId);
+    if (!row) {
+        throw new Error(`Execution environment ${environmentId} was not found in project ${projectId}`);
+    }
+    const environment = serializeEnvironment(row);
+    if (!environment) {
+        throw new Error(`Execution environment ${environmentId} contains invalid durable identity data`);
+    }
+    return environment;
+};
+const appendEventInTransaction = (input) => {
+    assertBoundedString(input.eventType, 'Environment event type', 100);
+    const metadataSchemaVersion = input.metadataSchemaVersion ?? 1;
+    if (!Number.isSafeInteger(metadataSchemaVersion) || metadataSchemaVersion < 1) {
+        throw new Error('Environment event metadata schema version must be a positive integer');
+    }
+    const message = input.message ?? null;
+    if (message && message.length > MAX_EVENT_MESSAGE_LENGTH) {
+        throw new Error(`Environment event message exceeds ${MAX_EVENT_MESSAGE_LENGTH} characters`);
+    }
+    const id = randomUUID();
+    const sequence = nextEventSequenceStatement.get(input.environmentId).sequence;
+    insertEventStatement.run(id, input.projectId, input.environmentId, sequence, input.eventType, input.fromState, input.toState, message, metadataSchemaVersion, input.metadata ? serializeBoundedObject(input.metadata, 'Environment event metadata') : null, input.createdAt ?? new Date().toISOString());
+    return serializeEvent(getEventStatement.get(id, input.projectId));
+};
+const createEnvironmentInTransaction = (input) => {
+    if (!projectExistsStatement.get(input.projectId)) {
+        throw new Error(`Project ${input.projectId} was not found`);
+    }
+    const id = input.id ?? randomUUID();
+    assertBoundedString(id, 'Environment ID', 128);
+    assertBoundedString(input.providerKind, 'Provider kind', 100);
+    assertBoundedString(input.providerVersion, 'Provider version', 200);
+    assertBoundedString(input.target.kind, 'Target kind', 100);
+    assertBoundedString(input.target.key, 'Target key', 1_000);
+    assertBoundedString(input.target.workspacePath, 'Target workspace path', 4_096);
+    if (!Number.isSafeInteger(input.environmentRevision) || input.environmentRevision < 1) {
+        throw new Error('Environment revision must be a positive integer');
+    }
+    if (input.externalId) {
+        assertBoundedString(input.externalId, 'Provider external ID', 2_048);
+    }
+    const validation = canonicalizeEnvironmentValidationFingerprintInput(input.validation);
+    if (input.agentIdentity && !validation.compatibleAgents.includes(input.agentIdentity)) {
+        throw new Error('Agent identity must be included in the compatible agent set');
+    }
+    const capabilitiesJson = serializeBoundedObject(input.capabilities, 'Environment capabilities');
+    const createdAt = input.createdAt ?? new Date().toISOString();
+    insertEnvironmentStatement.run(id, input.projectId, input.providerKind, input.providerVersion, input.externalId ?? null, input.target.kind, input.target.key, input.target.workspacePath, input.environmentRevision, createEnvironmentValidationFingerprint(validation), validation.template.kind === 'identity' ? validation.template.value : null, validation.template.kind === 'digest' ? validation.template.value : null, input.agentIdentity ?? null, JSON.stringify(validation.compatibleAgents), capabilitiesJson, createdAt, createdAt);
+    const environment = requireEnvironment(input.projectId, id);
+    const event = appendEventInTransaction({
+        projectId: input.projectId,
+        environmentId: id,
+        eventType: 'environment_created',
+        fromState: null,
+        toState: 'queued',
+        createdAt,
+    });
+    return { environment, event };
+};
+const stateTimestampUpdates = (environment, state, occurredAt) => ({
+    preparationStartedAt: state === 'preparing' ? occurredAt : environment.preparation_started_at,
+    readyAt: state === 'ready' ? occurredAt : environment.ready_at,
+    lastValidatedAt: environment.last_validated_at,
+    lastUsedAt: state === 'running' ? occurredAt : environment.last_used_at,
+    stoppedAt: state === 'stopped' ? occurredAt : environment.stopped_at,
+    retirementStartedAt: state === 'retiring' ? occurredAt : environment.retirement_started_at,
+    cleanupPendingAt: state === 'cleanup_pending' ? occurredAt : environment.cleanup_pending_at,
+    retiredAt: state === 'retired' ? occurredAt : environment.retired_at,
+    failedAt: state === 'failed' ? occurredAt : environment.failed_at,
+    unavailableAt: state === 'unavailable' ? occurredAt : environment.unavailable_at,
+});
+const transitionEnvironmentInTransaction = (input) => {
+    const environment = requireEnvironment(input.projectId, input.environmentId);
+    if (environment.lifecycle_state === input.state) {
+        return { environment, event: null };
+    }
+    if (!ALLOWED_TRANSITIONS[environment.lifecycle_state].has(input.state)) {
+        throw new Error(`Invalid execution environment transition: ${environment.lifecycle_state} -> ${input.state}`);
+    }
+    if (environment.external_id && input.externalId !== undefined && input.externalId !== environment.external_id) {
+        throw new Error('Provider external ID cannot be replaced');
+    }
+    if (input.failure && input.state !== 'failed' && input.state !== 'unavailable' && input.state !== 'cleanup_pending') {
+        throw new Error('Environment failure evidence requires a failed, unavailable, or cleanup-pending state');
+    }
+    const failure = input.failure ?? null;
+    if (failure) {
+        assertBoundedString(failure.code, 'Environment failure code', 100);
+        if (failure.message.length > MAX_EVENT_MESSAGE_LENGTH) {
+            throw new Error(`Environment failure message exceeds ${MAX_EVENT_MESSAGE_LENGTH} characters`);
+        }
+    }
+    const occurredAt = input.occurredAt ?? new Date().toISOString();
+    const timestamps = stateTimestampUpdates(environment, input.state, occurredAt);
+    const capabilitiesJson = input.capabilities
+        ? serializeBoundedObject(input.capabilities, 'Environment capabilities')
+        : JSON.stringify(environment.capabilities);
+    const result = updateEnvironmentStatement.run(input.state, input.externalId === undefined ? environment.external_id : input.externalId, capabilitiesJson, failure?.code ?? null, failure?.message ?? null, failure?.details ? serializeBoundedObject(failure.details, 'Environment failure details') : null, timestamps.preparationStartedAt, timestamps.readyAt, timestamps.lastValidatedAt, timestamps.lastUsedAt, timestamps.stoppedAt, timestamps.retirementStartedAt, timestamps.cleanupPendingAt, timestamps.retiredAt, timestamps.failedAt, timestamps.unavailableAt, occurredAt, input.environmentId, input.projectId, environment.lifecycle_state);
+    if (result.changes !== 1) {
+        throw new Error(`Execution environment ${input.environmentId} changed concurrently`);
+    }
+    const updated = requireEnvironment(input.projectId, input.environmentId);
+    const event = appendEventInTransaction({
+        projectId: input.projectId,
+        environmentId: input.environmentId,
+        eventType: input.eventType ?? `environment_${input.state}`,
+        fromState: environment.lifecycle_state,
+        toState: input.state,
+        message: input.message ?? failure?.message,
+        metadata: input.metadata,
+        metadataSchemaVersion: input.metadataSchemaVersion,
+        createdAt: occurredAt,
+    });
+    return { environment: updated, event };
+};
+const bindRunInTransaction = (input) => {
+    const environment = requireEnvironment(input.projectId, input.environmentId);
+    const authority = input.relationship === 'execution'
+        ? input.authority ?? createDefaultAuthority(environment)
+        : null;
+    if (authority) {
+        assertAuthorityMatchesEnvironment(authority, environment);
+    }
+    const boundAt = input.boundAt ?? new Date().toISOString();
+    insertBindingStatement.run(input.environmentId, input.executionRunId, input.projectId, input.relationship, environment.environment_revision, environment.environment_validation_fingerprint, authority ? serializeBoundedObject(authority, 'Execution environment authority') : null, boundAt);
+    const binding = getBindingStatement.get(input.environmentId, input.executionRunId, input.relationship);
+    appendEventInTransaction({
+        projectId: input.projectId,
+        environmentId: input.environmentId,
+        eventType: 'execution_run_bound',
+        fromState: environment.lifecycle_state,
+        toState: environment.lifecycle_state,
+        metadata: { executionRunId: input.executionRunId, relationship: input.relationship },
+        createdAt: boundAt,
+    });
+    return binding;
+};
+const releaseRunInTransaction = (input) => {
+    const environment = requireEnvironment(input.projectId, input.environmentId);
+    const releasedAt = input.releasedAt ?? new Date().toISOString();
+    const result = releaseBindingStatement.run(releasedAt, input.environmentId, input.executionRunId, input.projectId, input.relationship);
+    if (result.changes !== 1) {
+        throw new Error('Execution environment run binding was not found or was already released');
+    }
+    const binding = getBindingStatement.get(input.environmentId, input.executionRunId, input.relationship);
+    appendEventInTransaction({
+        projectId: input.projectId,
+        environmentId: input.environmentId,
+        eventType: 'execution_run_released',
+        fromState: environment.lifecycle_state,
+        toState: environment.lifecycle_state,
+        metadata: { executionRunId: input.executionRunId, relationship: input.relationship },
+        createdAt: releasedAt,
+    });
+    return binding;
+};
+const isPromiseLike = (value) => {
+    if ((typeof value !== 'object' || value === null) && typeof value !== 'function') {
+        return false;
+    }
+    return typeof value.then === 'function';
+};
+export const withExecutionEnvironmentTransaction = (callback) => {
+    const transaction = db.transaction(() => {
+        const operations = {
+            createExecutionEnvironment: input => createEnvironmentInTransaction(input).environment,
+            transitionExecutionEnvironment: input => transitionEnvironmentInTransaction(input).environment,
+            bindExecutionRunToEnvironment: bindRunInTransaction,
+            releaseExecutionRunFromEnvironment: releaseRunInTransaction,
+            appendExecutionEnvironmentEvent: appendEventInTransaction,
+        };
+        const result = callback(operations);
+        if (isPromiseLike(result)) {
+            throw new Error('Execution environment transactions require a synchronous callback');
+        }
+        return result;
+    });
+    return transaction();
+};
+export const createExecutionEnvironment = (input) => (withExecutionEnvironmentTransaction(transaction => transaction.createExecutionEnvironment(input)));
+export const transitionExecutionEnvironment = (input) => (withExecutionEnvironmentTransaction(transaction => transaction.transitionExecutionEnvironment(input)));
+export const bindExecutionRunToEnvironment = (input) => (withExecutionEnvironmentTransaction(transaction => transaction.bindExecutionRunToEnvironment(input)));
+export const acquireExecutionEnvironmentLease = (input) => {
+    try {
+        return db.transaction(() => {
+            const active = db.prepare(`
+        SELECT 1 FROM execution_environment_run_bindings
+        WHERE environment_id = ? AND released_at IS NULL
+        LIMIT 1
+      `).get(input.environmentId);
+            if (active) {
+                throw new Error(`Execution environment ${input.environmentId} is already leased`);
+            }
+            return bindRunInTransaction({
+                ...input,
+                relationship: 'execution',
+            });
+        }).immediate();
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('UNIQUE constraint failed')) {
+            throw new Error(`Execution environment ${input.environmentId} is already leased`);
+        }
+        throw error;
+    }
+};
+const placementMatchesBinding = (placement, binding) => (placement.provider === 'docker_sandbox'
+    && placement.environmentId === binding.environment_id
+    && placement.environmentRevision === binding.environment_revision
+    && placement.executionRunId === binding.execution_run_id
+    && placement.scope.kind === 'exact-sandbox');
+export const captureExecutionEnvironmentPlacement = (input) => withExecutionEnvironmentTransaction(transaction => {
+    const binding = getBindingStatement.get(input.environmentId, input.executionRunId, 'execution');
+    if (!binding || binding.project_id !== input.projectId || binding.released_at !== null) {
+        throw new Error('Active execution environment lease was not found');
+    }
+    if (!placementMatchesBinding(input.placement, binding)) {
+        throw new Error('Execution placement does not match its durable lease');
+    }
+    if (binding.placement_json !== null) {
+        const existingPlacement = parseStoredObject(binding.placement_json);
+        if (existingPlacement && JSON.stringify(existingPlacement) === JSON.stringify(input.placement)) {
+            return binding;
+        }
+        throw new Error('Conflicting execution placement evidence was already captured');
+    }
+    const result = capturePlacementStatement.run(serializeBoundedObject(input.placement, 'Execution placement evidence'), input.environmentId, input.executionRunId, input.projectId);
+    if (result.changes !== 1) {
+        throw new Error('Execution placement evidence was already captured');
+    }
+    transaction.appendExecutionEnvironmentEvent({
+        projectId: input.projectId,
+        environmentId: input.environmentId,
+        eventType: 'execution_placement_captured',
+        fromState: requireEnvironment(input.projectId, input.environmentId).lifecycle_state,
+        toState: requireEnvironment(input.projectId, input.environmentId).lifecycle_state,
+        metadata: { executionRunId: input.executionRunId },
+    });
+    return getBindingStatement.get(input.environmentId, input.executionRunId, 'execution');
+});
+export const getExecutionEnvironmentRunBinding = (input) => getBindingStatement.get(input.environmentId, input.executionRunId, input.relationship) ?? null;
+export const getExecutionEnvironmentBindingForRun = (projectId, executionRunId) => db.prepare(`
+    SELECT * FROM execution_environment_run_bindings
+    WHERE project_id = ? AND execution_run_id = ? AND relationship = 'execution'
+    ORDER BY bound_at DESC LIMIT 1
+  `).get(projectId, executionRunId) ?? null;
+export const releaseExecutionEnvironmentLease = (input) => withExecutionEnvironmentTransaction(transaction => {
+    const binding = getExecutionEnvironmentRunBinding({
+        environmentId: input.environmentId,
+        executionRunId: input.executionRunId,
+        relationship: 'execution',
+    });
+    if (!binding || binding.project_id !== input.projectId || binding.released_at !== null) {
+        throw new Error('Active execution environment lease was not found');
+    }
+    if (input.proof.kind === 'terminal_local_execution') {
+        const run = db.prepare('SELECT status FROM execution_runs WHERE id = ? AND project_id = ?').get(input.executionRunId, input.projectId);
+        if (!run || ['queued', 'running', 'waiting'].includes(run.status)) {
+            throw new Error('Execution environment lease release requires a terminal execution run');
+        }
+    }
+    else if (input.proof.kind === 'placement_terminated') {
+        const placement = parseStoredObject(binding.placement_json);
+        if (!placement
+            || !placementMatchesBinding(placement, binding)
+            || input.proof.inspection.state === 'running'
+            || JSON.stringify(input.proof.inspection.identity) !== JSON.stringify(placement)) {
+            throw new Error('Execution environment lease release requires exact terminated placement proof');
+        }
+    }
+    else {
+        const environment = requireEnvironment(input.projectId, input.environmentId);
+        if (!environment.external_id || environment.external_id !== input.proof.externalId) {
+            throw new Error('Execution environment lease release requires the exact stopped sandbox identity');
+        }
+    }
+    if (input.cleanupCompletion) {
+        const environment = requireEnvironment(input.projectId, input.environmentId);
+        const targetState = input.cleanupCompletion.state === 'stopped' ? 'stopped' : 'unavailable';
+        if (environment.lifecycle_state === targetState
+            || ['failed', 'unavailable', 'retired'].includes(environment.lifecycle_state)) {
+            transaction.appendExecutionEnvironmentEvent({
+                projectId: input.projectId,
+                environmentId: input.environmentId,
+                eventType: input.cleanupCompletion.eventType,
+                fromState: environment.lifecycle_state,
+                toState: environment.lifecycle_state,
+                message: input.cleanupCompletion.message,
+                metadata: input.cleanupCompletion.metadata,
+            });
+        }
+        else {
+            transaction.transitionExecutionEnvironment({
+                projectId: input.projectId,
+                environmentId: input.environmentId,
+                state: targetState,
+                eventType: input.cleanupCompletion.eventType,
+                message: input.cleanupCompletion.message,
+                metadata: input.cleanupCompletion.metadata,
+                failure: input.cleanupCompletion.failure,
+            });
+        }
+    }
+    return releaseRunInTransaction({
+        projectId: input.projectId,
+        environmentId: input.environmentId,
+        executionRunId: input.executionRunId,
+        relationship: 'execution',
+        releasedAt: input.releasedAt,
+    });
+});
+export const releaseExecutionRunFromEnvironment = (input) => (withExecutionEnvironmentTransaction(transaction => transaction.releaseExecutionRunFromEnvironment(input)));
+export const appendExecutionEnvironmentEvent = (input) => (withExecutionEnvironmentTransaction(transaction => transaction.appendExecutionEnvironmentEvent(input)));
+export const retireExecutionEnvironment = (input) => transitionExecutionEnvironment({ ...input, state: 'retiring', eventType: input.eventType ?? 'environment_retirement_started' });
+export const getExecutionEnvironment = (projectId, environmentId) => {
+    const row = getEnvironmentStatement.get(environmentId, projectId);
+    return row ? serializeEnvironment(row) : null;
+};
+export const listExecutionEnvironments = (projectId) => {
+    const rows = db.prepare(`
+    SELECT * FROM execution_environments
+    WHERE project_id = ?
+    ORDER BY environment_revision DESC, created_at DESC, id DESC
+  `).all(projectId);
+    return rows.flatMap(row => {
+        const environment = serializeEnvironment(row);
+        return environment ? [environment] : [];
+    });
+};
+export const listExecutionEnvironmentEvents = (projectId, environmentId) => (db.prepare(`
+    SELECT * FROM execution_environment_events
+    WHERE project_id = ? AND environment_id = ?
+    ORDER BY sequence ASC
+  `).all(projectId, environmentId).map(row => serializeEvent(row)));
+export const findReusableExecutionEnvironment = (input) => {
+    const validation = canonicalizeEnvironmentValidationFingerprintInput(input.validation);
+    if (input.agentIdentity && !validation.compatibleAgents.includes(input.agentIdentity)) {
+        return null;
+    }
+    const rows = db.prepare(`
+    SELECT * FROM execution_environments
+    WHERE project_id = ?
+      AND provider_kind = ?
+      AND provider_version = ?
+      AND target_kind = ?
+      AND target_key = ?
+      AND target_workspace_path = ?
+      AND environment_revision = ?
+      AND workspace_mode = 'direct'
+      AND environment_validation_fingerprint = ?
+      AND template_identity IS ?
+      AND template_digest IS ?
+      AND compatible_agents_json = ?
+      AND (agent_identity IS NULL OR agent_identity IS ?)
+      AND lifecycle_state IN (${REUSABLE_STATES.map(() => '?').join(', ')})
+    ORDER BY last_validated_at DESC, created_at DESC, id DESC
+  `).all(input.projectId, input.providerKind, input.providerVersion, input.target.kind, input.target.key, input.target.workspacePath, input.environmentRevision, createEnvironmentValidationFingerprint(validation), validation.template.kind === 'identity' ? validation.template.value : null, validation.template.kind === 'digest' ? validation.template.value : null, JSON.stringify(validation.compatibleAgents), input.agentIdentity ?? null, ...REUSABLE_STATES);
+    for (const row of rows) {
+        const environment = serializeEnvironment(row);
+        if (environment) {
+            return environment;
+        }
+    }
+    return null;
+};
+export const claimExecutionEnvironmentPreparation = (input) => {
+    const transaction = db.transaction(() => {
+        const validation = canonicalizeEnvironmentValidationFingerprintInput(input.validation);
+        if (input.agentIdentity && !validation.compatibleAgents.includes(input.agentIdentity)) {
+            throw new Error('Agent identity must be included in the compatible agent set');
+        }
+        const fingerprint = createEnvironmentValidationFingerprint(validation);
+        const identityValues = [
+            input.projectId,
+            input.providerKind,
+            input.providerVersion,
+            input.target.kind,
+            input.target.key,
+            input.target.workspacePath,
+            fingerprint,
+            validation.template.kind === 'identity' ? validation.template.value : null,
+            validation.template.kind === 'digest' ? validation.template.value : null,
+            JSON.stringify(validation.compatibleAgents),
+            input.agentIdentity ?? null,
+        ];
+        const exactRows = db.prepare(`
+      SELECT * FROM execution_environments
+      WHERE project_id = ? AND provider_kind = ? AND provider_version = ?
+        AND target_kind = ? AND target_key = ? AND target_workspace_path = ?
+        AND workspace_mode = 'direct' AND environment_validation_fingerprint = ?
+        AND template_identity IS ? AND template_digest IS ?
+        AND compatible_agents_json = ? AND agent_identity IS ?
+      ORDER BY environment_revision DESC, created_at DESC, id DESC
+    `).all(...identityValues);
+        for (const row of exactRows) {
+            const environment = serializeEnvironment(row);
+            if (!environment) {
+                continue;
+            }
+            if (REUSABLE_STATES.includes(environment.lifecycle_state)) {
+                return { kind: 'reusable', environment };
+            }
+            if (environment.lifecycle_state === 'queued' || environment.lifecycle_state === 'preparing') {
+                return { kind: 'preparing', environment };
+            }
+        }
+        const revision = db.prepare(`
+      SELECT COALESCE(MAX(environment_revision), 0) + 1 AS revision
+      FROM execution_environments
+      WHERE project_id = ? AND provider_kind = ? AND target_kind = ? AND target_key = ?
+    `).get(input.projectId, input.providerKind, input.target.kind, input.target.key).revision;
+        const externalId = input.resolveExternalId(revision, fingerprint);
+        const environment = createEnvironmentInTransaction({
+            ...input,
+            environmentRevision: revision,
+            externalId,
+        }).environment;
+        const preparing = transitionEnvironmentInTransaction({
+            projectId: input.projectId,
+            environmentId: environment.id,
+            state: 'preparing',
+            eventType: 'environment_preparing',
+        }).environment;
+        return { kind: 'created', environment: preparing };
+    });
+    return transaction.immediate();
+};
+export const markExecutionEnvironmentValidated = (input) => withExecutionEnvironmentTransaction(() => {
+    const environment = requireEnvironment(input.projectId, input.environmentId);
+    const validatedAt = input.validatedAt ?? new Date().toISOString();
+    const result = db.prepare(`
+    UPDATE execution_environments
+    SET last_validated_at = ?, updated_at = ?
+    WHERE id = ? AND project_id = ?
+  `).run(validatedAt, validatedAt, input.environmentId, input.projectId);
+    if (result.changes !== 1) {
+        throw new Error(`Execution environment ${input.environmentId} changed concurrently`);
+    }
+    return { ...environment, last_validated_at: validatedAt, updated_at: validatedAt };
+});
+export const claimExecutionEnvironmentsForCleanup = (input = {}) => withExecutionEnvironmentTransaction(transaction => {
+    const limit = input.limit ?? 50;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 200) {
+        throw new Error('Environment cleanup claim limit must be between 1 and 200');
+    }
+    const claimId = input.claimId ?? randomUUID();
+    assertBoundedString(claimId, 'Environment cleanup claim ID', 128);
+    const claimedAt = input.claimedAt ?? new Date().toISOString();
+    const rows = db.prepare(`
+    SELECT * FROM execution_environments
+    WHERE lifecycle_state IN (${CLEANUP_CLAIMABLE_STATES.map(() => '?').join(', ')})
+      AND (? IS NULL OR project_id = ?)
+      AND (? IS NULL OR target_kind = ?)
+      AND (? IS NULL OR target_key = ?)
+      AND (cleanup_claim_id IS NULL OR (? IS NOT NULL AND cleanup_claimed_at < ?))
+    ORDER BY updated_at ASC, id ASC
+    LIMIT ?
+  `).all(...CLEANUP_CLAIMABLE_STATES, input.projectId ?? null, input.projectId ?? null, input.targetKind ?? null, input.targetKind ?? null, input.targetKey ?? null, input.targetKey ?? null, input.staleBefore ?? null, input.staleBefore ?? null, limit);
+    const claimed = [];
+    for (const row of rows) {
+        const result = db.prepare(`
+      UPDATE execution_environments
+      SET lifecycle_state = 'cleanup_pending', cleanup_claim_id = ?, cleanup_claimed_at = ?,
+          cleanup_attempts = cleanup_attempts + 1,
+          cleanup_pending_at = COALESCE(cleanup_pending_at, ?), updated_at = ?
+      WHERE id = ? AND project_id = ?
+        AND lifecycle_state = ?
+        AND (cleanup_claim_id IS NULL OR (? IS NOT NULL AND cleanup_claimed_at < ?))
+    `).run(claimId, claimedAt, claimedAt, claimedAt, row.id, row.project_id, row.lifecycle_state, input.staleBefore ?? null, input.staleBefore ?? null);
+        if (result.changes !== 1) {
+            continue;
+        }
+        transaction.appendExecutionEnvironmentEvent({
+            projectId: row.project_id,
+            environmentId: row.id,
+            eventType: 'environment_cleanup_claimed',
+            fromState: row.lifecycle_state,
+            toState: 'cleanup_pending',
+            metadata: { claimId },
+            createdAt: claimedAt,
+        });
+        claimed.push(requireEnvironment(row.project_id, row.id));
+    }
+    return claimed;
+});
+export const completeExecutionEnvironmentCleanup = (input) => withExecutionEnvironmentTransaction(transaction => {
+    const environment = requireEnvironment(input.projectId, input.environmentId);
+    if (environment.lifecycle_state !== 'cleanup_pending' || environment.cleanup_claim_id !== input.claimId) {
+        throw new Error(`Execution environment ${input.environmentId} cleanup claim is not owned by ${input.claimId}`);
+    }
+    const completedAt = input.completedAt ?? new Date().toISOString();
+    const result = db.prepare(`
+    UPDATE execution_environments
+    SET lifecycle_state = 'retired', cleanup_claim_id = NULL, cleanup_claimed_at = NULL,
+        retired_at = ?, updated_at = ?
+    WHERE id = ? AND project_id = ? AND lifecycle_state = 'cleanup_pending' AND cleanup_claim_id = ?
+  `).run(completedAt, completedAt, input.environmentId, input.projectId, input.claimId);
+    if (result.changes !== 1) {
+        throw new Error(`Execution environment ${input.environmentId} cleanup claim was lost`);
+    }
+    transaction.appendExecutionEnvironmentEvent({
+        projectId: input.projectId,
+        environmentId: input.environmentId,
+        eventType: 'environment_cleanup_completed',
+        fromState: 'cleanup_pending',
+        toState: 'retired',
+        createdAt: completedAt,
+    });
+    return requireEnvironment(input.projectId, input.environmentId);
+});
+export const failExecutionEnvironmentCleanup = (input) => withExecutionEnvironmentTransaction(transaction => {
+    assertBoundedString(input.failure.code, 'Environment cleanup failure code', 100);
+    if (input.failure.message.length > MAX_EVENT_MESSAGE_LENGTH) {
+        throw new Error(`Environment cleanup failure message exceeds ${MAX_EVENT_MESSAGE_LENGTH} characters`);
+    }
+    const failedAt = input.failedAt ?? new Date().toISOString();
+    const result = db.prepare(`
+    UPDATE execution_environments
+    SET cleanup_claim_id = NULL, cleanup_claimed_at = NULL, failure_code = ?, failure_message = ?,
+        failure_details_json = ?, updated_at = ?
+    WHERE id = ? AND project_id = ? AND lifecycle_state = 'cleanup_pending' AND cleanup_claim_id = ?
+  `).run(input.failure.code, input.failure.message, input.failure.details ? serializeBoundedObject(input.failure.details, 'Environment cleanup failure details') : null, failedAt, input.environmentId, input.projectId, input.claimId);
+    if (result.changes !== 1) {
+        throw new Error(`Execution environment ${input.environmentId} cleanup claim was lost`);
+    }
+    transaction.appendExecutionEnvironmentEvent({
+        projectId: input.projectId,
+        environmentId: input.environmentId,
+        eventType: 'environment_cleanup_failed',
+        fromState: 'cleanup_pending',
+        toState: 'cleanup_pending',
+        message: input.failure.message,
+        metadata: { failureCode: input.failure.code },
+        createdAt: failedAt,
+    });
+    return requireEnvironment(input.projectId, input.environmentId);
+});
+//# sourceMappingURL=executionEnvironments.js.map