@straiffi/archon 1.8.14 → 1.8.16

package/dist/server/lib/executionEnvironmentValidationOperations.js

@@ -0,0 +1,635 @@
+import db from '../db.js';
+import { DOCKER_SANDBOX_ADAPTER_CONTRACT_VERSION, QUALIFIED_DOCKER_SANDBOX_TEMPLATES, QUALIFIED_SBX_VERSION, SbxCommandFailure, createDockerSandboxName, dockerSandboxExecutionEnvironmentCapabilities, } from './dockerSandboxExecutionEnvironment.js';
+import { DockerSandboxRuntimeFailure, } from './dockerSandboxRuntimeController.js';
+import { createEnvironmentValidationFingerprint } from './executionEnvironmentLifecycle.js';
+import { EXECUTION_ENVIRONMENT_VALIDATION_SCHEMA_VERSION, validateExecutionEnvironmentForAgent, } from './executionEnvironmentValidation.js';
+import { listDockerSandboxCredentials } from './dockerSandboxCredentials.js';
+import { appendExecutionEnvironmentEvent, bindExecutionRunToEnvironment, claimExecutionEnvironmentPreparation, getExecutionEnvironment, markExecutionEnvironmentValidated, releaseExecutionRunFromEnvironment, transitionExecutionEnvironment, } from './executionEnvironments.js';
+import { resolveExpectedDockerSandbox, stopAndRecordEnvironmentValidationCleanup, } from './executionEnvironmentReconciliation.js';
+import { createExecutionRun, getExecutionRun, listLifecycleEvents, toCanonicalLifecycleEvent, transitionExecutionRun, } from './executionRuns.js';
+import { getLocalProjectBranch } from './git.js';
+import { getProjectById, getProjectActiveTarget } from './projects.js';
+import { resolveExecutionTarget } from './executionTargets.js';
+import { getBundle } from './tickets.js';
+import { workspaceIdentitiesMatch } from './workspaceIdentity.js';
+import { getModelProvider, normalizeModelId, normalizeModelProvider } from './models.js';
+export class ExecutionEnvironmentRouteError extends Error {
+    status;
+    reason;
+    constructor(status, reason, message) {
+        super(message);
+        this.name = 'ExecutionEnvironmentRouteError';
+        this.status = status;
+        this.reason = reason;
+    }
+}
+const SANDBOX_CREATE_TIMEOUT_MS = 300_000;
+const isValidationCancelled = (error, signal) => (signal?.aborted === true
+    || (error instanceof SbxCommandFailure && error.kind === 'cancelled')
+    || (error instanceof DockerSandboxRuntimeFailure && error.kind === 'cancelled'));
+export const parseExecutionEnvironmentAgent = (value) => {
+    if (value !== 'opencode' && value !== 'claude') {
+        throw new ExecutionEnvironmentRouteError(400, 'invalid_agent', 'agent must be opencode or claude');
+    }
+    return value;
+};
+export const parseExecutionEnvironmentModel = (value) => {
+    if (value == null) {
+        return null;
+    }
+    const model = normalizeModelId(value);
+    if (!model) {
+        throw new ExecutionEnvironmentRouteError(400, 'invalid_model', 'model must be a valid OpenCode model id');
+    }
+    return model;
+};
+export const parseExecutionEnvironmentProvider = (value, model = null) => {
+    if (value != null) {
+        const provider = normalizeModelProvider(value);
+        if (!provider) {
+            throw new ExecutionEnvironmentRouteError(400, 'invalid_provider', 'provider must be a valid provider id');
+        }
+        const modelProvider = getModelProvider(model);
+        if (modelProvider && modelProvider !== provider) {
+            throw new ExecutionEnvironmentRouteError(400, 'provider_model_mismatch', 'provider must match the provider in model');
+        }
+        return provider;
+    }
+    return getModelProvider(model) || null;
+};
+export const resolveCurrentExecutionEnvironmentDescriptor = (project) => {
+    const target = getProjectActiveTarget(project);
+    if (target.kind === 'repo_root') {
+        const branch = getLocalProjectBranch(project);
+        if (!branch) {
+            throw new ExecutionEnvironmentRouteError(409, 'target_unavailable', 'The project target branch is unavailable.');
+        }
+        return { kind: 'project-root', bundleId: null, branch };
+    }
+    if (!target.bundle_id) {
+        throw new ExecutionEnvironmentRouteError(409, 'target_unavailable', 'The selected project bundle is unavailable.');
+    }
+    const bundle = getBundle(target.bundle_id, project.id);
+    if (!bundle) {
+        throw new ExecutionEnvironmentRouteError(409, 'target_unavailable', 'The selected project bundle is unavailable.');
+    }
+    return { kind: 'bundle-worktree', bundleId: bundle.id, branch: bundle.branch };
+};
+export const currentExecutionEnvironmentValidationFingerprint = (agent) => (createEnvironmentValidationFingerprint({
+    workspaceMode: 'direct',
+    template: { kind: 'identity', value: QUALIFIED_DOCKER_SANDBOX_TEMPLATES[agent] },
+    compatibleAgents: [agent],
+    validationSuiteSchemaVersion: EXECUTION_ENVIRONMENT_VALIDATION_SCHEMA_VERSION,
+    adapterContractVersion: DOCKER_SANDBOX_ADAPTER_CONTRACT_VERSION,
+    qualifiedSbxVersion: QUALIFIED_SBX_VERSION,
+}));
+const descriptorsMatch = (left, right) => (left.kind === right.kind
+    && left.branch === right.branch
+    && left.bundleId === right.bundleId);
+const assertValidationTargetCurrent = async (projectId, capturedDescriptor, capturedTarget, requiresActiveProjectTarget = true) => {
+    try {
+        const currentProject = getProjectById(projectId);
+        if (!currentProject) {
+            throw new Error('Project no longer exists.');
+        }
+        const currentDescriptor = requiresActiveProjectTarget
+            ? resolveCurrentExecutionEnvironmentDescriptor(currentProject)
+            : capturedDescriptor;
+        if (!descriptorsMatch(capturedDescriptor, currentDescriptor)) {
+            throw new Error('Target descriptor changed.');
+        }
+        const currentTarget = await resolveExecutionTarget({
+            project: currentProject,
+            descriptor: currentDescriptor,
+            expectedWorkspacePath: capturedTarget.workspacePath,
+        });
+        const capturedIdentity = capturedTarget.workspaceEvidence.workspaceIdentity;
+        const currentIdentity = currentTarget.workspaceEvidence.workspaceIdentity;
+        if (capturedIdentity.state !== 'available' || currentIdentity.state !== 'available') {
+            throw new ExecutionEnvironmentRouteError(409, 'target_evidence_unavailable', 'The project target workspace identity could not be verified during validation.');
+        }
+        if (currentTarget.identity.key !== capturedTarget.identity.key
+            || currentTarget.identity.kind !== capturedTarget.identity.kind
+            || !workspaceIdentitiesMatch(currentIdentity, capturedIdentity)) {
+            throw new Error('Workspace identity changed.');
+        }
+    }
+    catch (error) {
+        if (error instanceof ExecutionEnvironmentRouteError && error.reason === 'target_evidence_unavailable') {
+            throw error;
+        }
+        throw new ExecutionEnvironmentRouteError(409, 'target_changed', 'The project target changed during validation.');
+    }
+};
+const emitRunAndEvent = (emitter, run, event) => {
+    emitter?.emit('execution-run:updated', run);
+    emitter?.emit('lifecycle-event:created', toCanonicalLifecycleEvent(event));
+};
+const requireRunAndLatestEvent = (projectId, runId) => {
+    const run = getExecutionRun(projectId, runId);
+    const event = listLifecycleEvents(projectId, runId).at(-1);
+    if (!run || !event) {
+        throw new Error(`Environment validation run ${runId} was not persisted`);
+    }
+    return { run, event };
+};
+const emitLatestRun = (projectId, runId, dependencies) => {
+    const latest = requireRunAndLatestEvent(projectId, runId);
+    emitRunAndEvent(dependencies.emitter, latest.run, latest.event);
+};
+const createBoundValidationRun = (preparation, agent, model, provider, initiatedBy) => {
+    const { project, descriptor, target, environment } = preparation;
+    let runId = '';
+    db.transaction(() => {
+        const currentTarget = db.prepare(`
+      SELECT active_target_kind, active_target_bundle_id
+      FROM projects WHERE id = ? AND deletion_started_at IS NULL
+    `).get(project.id);
+        if (!currentTarget) {
+            throw new ExecutionEnvironmentRouteError(409, 'target_changed', 'The project target changed while validation was being prepared.');
+        }
+        if (preparation.requiresActiveProjectTarget) {
+            const expectedTargetKind = descriptor.kind === 'bundle-worktree' ? 'bundle' : 'repo_root';
+            const expectedBundleId = descriptor.kind === 'bundle-worktree' ? descriptor.bundleId : null;
+            if (currentTarget.active_target_kind !== expectedTargetKind
+                || currentTarget.active_target_bundle_id !== expectedBundleId) {
+                throw new ExecutionEnvironmentRouteError(409, 'target_changed', 'The project target changed while validation was being prepared.');
+            }
+        }
+        const active = db.prepare(`
+       SELECT run.id, binding.relationship
+      FROM execution_environment_run_bindings binding
+      JOIN execution_runs run ON run.id = binding.execution_run_id AND run.project_id = binding.project_id
+       WHERE binding.project_id = ? AND binding.environment_id = ?
+         AND binding.released_at IS NULL
+      LIMIT 1
+    `).get(project.id, environment.id);
+        if (active) {
+            throw new ExecutionEnvironmentRouteError(409, active.relationship === 'validation' ? 'validation_active' : 'environment_in_use', active.relationship === 'validation' ? 'Environment validation is already active.' : 'The environment is already in use.');
+        }
+        const run = createExecutionRun({
+            projectId: project.id,
+            kind: 'environment_validation',
+            initiatedBy,
+            domainStatus: 'queued',
+            sourceReference: { kind: 'project', id: project.id, label: project.name },
+            metadata: {
+                environment_id: environment.id,
+                agent,
+                provider,
+                model,
+                target: target.identity,
+                workspace_path: target.workspacePath,
+                workspace_evidence: target.workspaceEvidence,
+            },
+            eventType: 'environment_validation_created',
+            eventMessage: `Environment validation was requested for ${agent}.`,
+        });
+        bindExecutionRunToEnvironment({
+            projectId: project.id,
+            environmentId: environment.id,
+            executionRunId: run.id,
+            relationship: 'validation',
+        });
+        runId = run.id;
+    }).immediate();
+    return runId;
+};
+const persistFailureOutcome = (preparation, runId, code, message, dependencies, runStatus = 'failed', failCreatedEnvironment = false) => {
+    let transitionedRun = false;
+    db.transaction(() => {
+        const currentEnvironment = getExecutionEnvironment(preparation.project.id, preparation.environment.id);
+        if (!currentEnvironment) {
+            throw new Error(`Execution environment ${preparation.environment.id} was not persisted`);
+        }
+        if (failCreatedEnvironment && preparation.created && !['failed', 'retired'].includes(currentEnvironment.lifecycle_state)) {
+            transitionExecutionEnvironment({
+                projectId: preparation.project.id,
+                environmentId: preparation.environment.id,
+                state: 'failed',
+                eventType: 'environment_preparation_failed',
+                failure: { code, message },
+                metadata: { executionRunId: runId },
+            });
+        }
+        else {
+            appendExecutionEnvironmentEvent({
+                projectId: preparation.project.id,
+                environmentId: preparation.environment.id,
+                eventType: runStatus === 'cancelled' ? 'environment_validation_cancelled' : 'environment_validation_failed',
+                fromState: currentEnvironment.lifecycle_state,
+                toState: currentEnvironment.lifecycle_state,
+                message,
+                metadata: { executionRunId: runId, failureCode: code },
+            });
+        }
+        const run = getExecutionRun(preparation.project.id, runId);
+        if (run && ['queued', 'running', 'waiting'].includes(run.status)) {
+            transitionExecutionRun({
+                projectId: preparation.project.id,
+                runId,
+                status: runStatus,
+                domainStatus: runStatus === 'cancelled' ? 'cancelled' : 'error',
+                failure: runStatus === 'failed' ? { code, message } : null,
+                eventType: runStatus === 'cancelled' ? 'environment_validation_cancelled' : 'environment_validation_failed',
+                eventMessage: message,
+            });
+            transitionedRun = true;
+        }
+    })();
+    if (transitionedRun) {
+        emitLatestRun(preparation.project.id, runId, dependencies);
+    }
+};
+const persistValidationOutcome = (preparation, runId, agent, validation) => {
+    const status = validation.cancelled ? 'cancelled' : validation.agent.ready ? 'completed' : 'failed';
+    const domainStatus = validation.cancelled ? 'cancelled' : validation.agent.ready ? 'ready' : 'not_ready';
+    const message = validation.cancelled
+        ? `Environment validation for ${agent} was cancelled.`
+        : validation.agent.ready
+            ? `Environment validation for ${agent} passed.`
+            : `Environment validation for ${agent} did not pass.`;
+    db.transaction(() => {
+        const currentEnvironment = getExecutionEnvironment(preparation.project.id, preparation.environment.id);
+        if (!currentEnvironment) {
+            throw new Error(`Execution environment ${preparation.environment.id} was not persisted`);
+        }
+        appendExecutionEnvironmentEvent({
+            projectId: preparation.project.id,
+            environmentId: preparation.environment.id,
+            eventType: 'environment_validation_completed',
+            fromState: currentEnvironment.lifecycle_state,
+            toState: currentEnvironment.lifecycle_state,
+            message,
+            metadata: { executionRunId: runId, agent, validation },
+        });
+        transitionExecutionRun({
+            projectId: preparation.project.id,
+            runId,
+            status,
+            domainStatus,
+            failure: status === 'failed' ? { code: 'validation_failed', message } : null,
+            eventType: 'environment_validation_completed',
+            eventMessage: message,
+        });
+        if (status === 'completed') {
+            markExecutionEnvironmentValidated({
+                projectId: preparation.project.id,
+                environmentId: preparation.environment.id,
+            });
+        }
+    })();
+};
+const cleanupAfterValidation = async (preparation, agent, runId, adapter) => {
+    await stopAndRecordEnvironmentValidationCleanup({
+        environment: preparation.environment,
+        executionRunId: runId,
+        adapter,
+        requestedAgent: agent,
+    });
+};
+const releaseTerminalValidationBinding = (preparation, runId) => {
+    const run = getExecutionRun(preparation.project.id, runId);
+    if (!run || ['queued', 'running', 'waiting'].includes(run.status)) {
+        return;
+    }
+    releaseExecutionRunFromEnvironment({
+        projectId: preparation.project.id,
+        environmentId: preparation.environment.id,
+        executionRunId: runId,
+        relationship: 'validation',
+    });
+};
+const runtimeFailureMessage = (error) => `${error.message} ${error.remediation}`;
+const runtimeFailureRouteError = (error) => {
+    if (error.kind === 'cancelled') {
+        return new ExecutionEnvironmentRouteError(499, 'validation_cancelled', 'Environment validation was cancelled.');
+    }
+    return new ExecutionEnvironmentRouteError(503, `docker_runtime_${error.kind}`, runtimeFailureMessage(error));
+};
+const logProviderValidationFailures = (preparation, run, validation) => {
+    for (const check of validation.agent.checks) {
+        const providerError = check.details?.providerError;
+        if (check.kind !== 'destination' || check.state !== 'failed' || !providerError) {
+            continue;
+        }
+        console.warn('[execution-validation] destination provider error', {
+            project_id: preparation.project.id,
+            environment_id: preparation.environment.id,
+            execution_run_id: run.id,
+            correlation_id: run.correlation_id,
+            agent: validation.agent.agent,
+            model: validation.model,
+            error_name: providerError.name ?? null,
+            error_message: providerError.message ?? null,
+            provider_reference: providerError.reference ?? null,
+            provider: providerError.provider ?? null,
+            provider_model: providerError.model ?? null,
+        });
+    }
+};
+const executePreparedValidation = async (preparation, agent, model, provider, initiatedBy, dependencies, signal) => {
+    let runId;
+    try {
+        runId = createBoundValidationRun(preparation, agent, model, provider, initiatedBy);
+    }
+    catch (error) {
+        if (preparation.created) {
+            const message = error instanceof Error ? error.message : 'Environment validation could not be bound.';
+            transitionExecutionEnvironment({
+                projectId: preparation.project.id,
+                environmentId: preparation.environment.id,
+                state: 'failed',
+                eventType: 'environment_preparation_failed',
+                failure: {
+                    code: error instanceof ExecutionEnvironmentRouteError ? error.reason : 'validation_binding_failed',
+                    message,
+                },
+            });
+        }
+        throw error;
+    }
+    emitLatestRun(preparation.project.id, runId, dependencies);
+    let runtimeReady = false;
+    let running = null;
+    let validationOutcomePersistenceFailed = false;
+    try {
+        try {
+            await dependencies.runtimeController.ensureReady({ signal });
+            runtimeReady = true;
+        }
+        catch (error) {
+            const runtimeError = error instanceof DockerSandboxRuntimeFailure
+                ? error
+                : new DockerSandboxRuntimeFailure('unsupported_prerequisite');
+            const cancelled = runtimeError.kind === 'cancelled';
+            persistFailureOutcome(preparation, runId, cancelled ? 'validation_cancelled' : `docker_runtime_${runtimeError.kind}`, runtimeFailureMessage(runtimeError), dependencies, cancelled ? 'cancelled' : 'failed', true);
+            throw runtimeFailureRouteError(runtimeError);
+        }
+        const expected = resolveExpectedDockerSandbox(preparation.environment, agent);
+        if (preparation.created) {
+            const sandbox = await dependencies.adapter.create({
+                identity: {
+                    projectId: preparation.project.id,
+                    targetKey: preparation.target.identity.key,
+                    environmentRevision: preparation.environment.environment_revision,
+                    validationFingerprint: preparation.environment.environment_validation_fingerprint,
+                },
+                agent,
+                workspacePath: preparation.target.workspacePath,
+                template: QUALIFIED_DOCKER_SANDBOX_TEMPLATES[agent],
+            }, { signal, timeoutMs: SANDBOX_CREATE_TIMEOUT_MS });
+            if (sandbox.name !== preparation.environment.external_id) {
+                throw new Error('Docker Sandbox returned an unexpected external identity.');
+            }
+            transitionExecutionEnvironment({
+                projectId: preparation.project.id,
+                environmentId: preparation.environment.id,
+                state: 'ready',
+                eventType: 'environment_ready',
+            });
+        }
+        else if (preparation.environment.lifecycle_state === 'stopped') {
+            const reconnected = await dependencies.adapter.reconnect(expected, { signal });
+            if (reconnected.state !== 'running') {
+                throw new Error('Docker Sandbox did not reach the running state after reconnecting.');
+            }
+            transitionExecutionEnvironment({
+                projectId: preparation.project.id,
+                environmentId: preparation.environment.id,
+                state: 'running',
+                eventType: 'environment_reconnected',
+                message: 'Docker Sandbox was reconnected for environment validation.',
+            });
+        }
+        await assertValidationTargetCurrent(preparation.project.id, preparation.descriptor, preparation.target, preparation.requiresActiveProjectTarget);
+        running = transitionExecutionRun({
+            projectId: preparation.project.id,
+            runId,
+            status: 'running',
+            domainStatus: 'validating',
+            eventType: 'environment_validation_started',
+        }, dependencies.emitter);
+        let credentialInventory;
+        let credentialInventoryUnavailable = agent === 'opencode' && !dependencies.runner;
+        if (agent === 'opencode' && dependencies.runner) {
+            try {
+                credentialInventory = await listDockerSandboxCredentials(dependencies.runner, { signal });
+            }
+            catch {
+                credentialInventory = undefined;
+                credentialInventoryUnavailable = true;
+            }
+        }
+        const validation = await validateExecutionEnvironmentForAgent(dependencies.adapter, expected, agent, {
+            signal,
+            model,
+            provider,
+            sandboxName: expected.name,
+            credentialInventory,
+            credentialInventoryUnavailable,
+        });
+        await assertValidationTargetCurrent(preparation.project.id, preparation.descriptor, preparation.target, preparation.requiresActiveProjectTarget);
+        logProviderValidationFailures(preparation, running, validation);
+        try {
+            persistValidationOutcome(preparation, runId, agent, validation);
+        }
+        catch (error) {
+            validationOutcomePersistenceFailed = true;
+            const message = error instanceof Error ? error.message : 'Environment validation could not be persisted.';
+            try {
+                persistFailureOutcome(preparation, runId, 'validation_persistence_failed', message, dependencies);
+            }
+            catch {
+                // Preserve the validation-outcome persistence error while cleanup still runs in finally.
+            }
+            throw error;
+        }
+        emitLatestRun(preparation.project.id, runId, dependencies);
+        const completed = requireRunAndLatestEvent(preparation.project.id, runId);
+        return {
+            run: completed.run,
+            environment_id: preparation.environment.id,
+            agent,
+            validation,
+            started_at: running.started_at,
+        };
+    }
+    catch (error) {
+        if (error instanceof ExecutionEnvironmentRouteError && !runtimeReady) {
+            throw error;
+        }
+        const currentRun = getExecutionRun(preparation.project.id, runId);
+        if (currentRun && ['queued', 'running', 'waiting'].includes(currentRun.status) && !validationOutcomePersistenceFailed) {
+            const cancelled = isValidationCancelled(error, signal);
+            const targetInvalid = error instanceof ExecutionEnvironmentRouteError
+                && (error.reason === 'target_changed' || error.reason === 'target_evidence_unavailable');
+            const code = cancelled
+                ? 'validation_cancelled'
+                : targetInvalid
+                    ? error.reason
+                    : preparation.created && !running
+                        ? 'preparation_failed'
+                        : 'validation_error';
+            const message = error instanceof Error ? error.message : 'Environment validation failed unexpectedly.';
+            persistFailureOutcome(preparation, runId, code, message, dependencies, cancelled ? 'cancelled' : 'failed');
+        }
+        if (error instanceof ExecutionEnvironmentRouteError) {
+            throw error;
+        }
+        if (isValidationCancelled(error, signal)) {
+            throw new ExecutionEnvironmentRouteError(499, 'validation_cancelled', 'Environment validation was cancelled.');
+        }
+        if (preparation.created && !running) {
+            throw new ExecutionEnvironmentRouteError(502, 'preparation_failed', 'Docker Sandbox preparation failed.');
+        }
+        throw new ExecutionEnvironmentRouteError(502, 'validation_error', error instanceof Error ? error.message : 'Environment validation failed unexpectedly.');
+    }
+    finally {
+        try {
+            if (runtimeReady) {
+                await cleanupAfterValidation(preparation, agent, runId, dependencies.adapter);
+            }
+        }
+        finally {
+            releaseTerminalValidationBinding(preparation, runId);
+        }
+    }
+};
+const resolveExistingValidation = async (projectId, environmentId, agent, expectedTarget, requestedTarget) => {
+    const project = getProjectById(projectId);
+    if (!project) {
+        throw new ExecutionEnvironmentRouteError(404, 'project_not_found', 'Not found');
+    }
+    const environment = getExecutionEnvironment(project.id, environmentId);
+    if (!environment) {
+        throw new ExecutionEnvironmentRouteError(404, 'environment_not_found', 'Execution environment not found');
+    }
+    if (!environment.compatible_agents.includes(agent)) {
+        throw new ExecutionEnvironmentRouteError(409, 'agent_incompatible', 'The selected environment is not compatible with this agent.');
+    }
+    if (environment.environment_validation_fingerprint !== currentExecutionEnvironmentValidationFingerprint(agent)
+        || environment.workspace_mode !== 'direct'
+        || environment.template_identity !== QUALIFIED_DOCKER_SANDBOX_TEMPLATES[agent]
+        || environment.agent_identity !== agent) {
+        throw new ExecutionEnvironmentRouteError(409, 'environment_obsolete', 'The selected environment uses an obsolete validation contract.');
+    }
+    if (environment.provider_kind !== 'docker_sandbox'
+        || environment.provider_version !== QUALIFIED_SBX_VERSION
+        || !['ready', 'running', 'stopped'].includes(environment.lifecycle_state)) {
+        throw new ExecutionEnvironmentRouteError(409, 'environment_unavailable', 'The selected environment is not ready for validation.');
+    }
+    const descriptor = requestedTarget
+        ? descriptorForResolvedTarget(project, requestedTarget)
+        : resolveCurrentExecutionEnvironmentDescriptor(project);
+    const target = await resolveExecutionTarget({
+        project,
+        descriptor,
+        expectedWorkspacePath: environment.target_workspace_path,
+    });
+    if (target.identity.key !== environment.target_key || target.identity.kind !== environment.target_kind) {
+        throw new ExecutionEnvironmentRouteError(409, 'target_changed', 'The selected environment does not match the current project target.');
+    }
+    if (expectedTarget
+        && (target.identity.kind !== expectedTarget.kind
+            || target.identity.key !== expectedTarget.key
+            || target.workspacePath !== expectedTarget.workspacePath)) {
+        throw new ExecutionEnvironmentRouteError(409, 'target_changed', 'The selected environment does not match the requested execution target.');
+    }
+    return {
+        project,
+        descriptor,
+        target,
+        environment,
+        created: false,
+        requiresActiveProjectTarget: requestedTarget === undefined,
+    };
+};
+const prepareValidationForTarget = async (project, descriptor, target, agent, requiresActiveProjectTarget) => {
+    const claim = claimExecutionEnvironmentPreparation({
+        projectId: project.id,
+        providerKind: 'docker_sandbox',
+        providerVersion: QUALIFIED_SBX_VERSION,
+        target: { kind: target.identity.kind, key: target.identity.key, workspacePath: target.workspacePath },
+        validation: {
+            workspaceMode: 'direct',
+            template: { kind: 'identity', value: QUALIFIED_DOCKER_SANDBOX_TEMPLATES[agent] },
+            compatibleAgents: [agent],
+            validationSuiteSchemaVersion: EXECUTION_ENVIRONMENT_VALIDATION_SCHEMA_VERSION,
+            adapterContractVersion: DOCKER_SANDBOX_ADAPTER_CONTRACT_VERSION,
+            qualifiedSbxVersion: QUALIFIED_SBX_VERSION,
+        },
+        agentIdentity: agent,
+        capabilities: dockerSandboxExecutionEnvironmentCapabilities,
+        resolveExternalId: (environmentRevision, validationFingerprint) => createDockerSandboxName({
+            projectId: project.id,
+            targetKey: target.identity.key,
+            environmentRevision,
+            validationFingerprint,
+        }),
+    });
+    if (claim.kind === 'preparing') {
+        throw new ExecutionEnvironmentRouteError(409, 'preparation_active', 'Equivalent environment preparation is already active.');
+    }
+    return {
+        project,
+        descriptor,
+        target,
+        environment: claim.environment,
+        created: claim.kind === 'created',
+        requiresActiveProjectTarget,
+    };
+};
+const prepareValidation = async (projectId, agent) => {
+    const project = getProjectById(projectId);
+    if (!project) {
+        throw new ExecutionEnvironmentRouteError(404, 'project_not_found', 'Not found');
+    }
+    const descriptor = resolveCurrentExecutionEnvironmentDescriptor(project);
+    const target = await resolveExecutionTarget({ project, descriptor });
+    return prepareValidationForTarget(project, descriptor, target, agent, true);
+};
+const descriptorForResolvedTarget = (project, target) => {
+    if (target.identity.kind === 'project-root') {
+        const branch = getLocalProjectBranch(project);
+        if (!branch) {
+            throw new ExecutionEnvironmentRouteError(409, 'target_unavailable', 'The project target branch is unavailable.');
+        }
+        return { kind: 'project-root', bundleId: null, branch };
+    }
+    if (target.identity.kind === 'bundle-worktree') {
+        const bundle = getBundle(target.identity.bundleId, project.id);
+        if (!bundle) {
+            throw new ExecutionEnvironmentRouteError(409, 'target_unavailable', 'The selected ticket bundle is unavailable.');
+        }
+        return { kind: 'bundle-worktree', bundleId: bundle.id, branch: bundle.branch };
+    }
+    return { kind: 'branch-worktree', bundleId: null, branch: target.identity.branch };
+};
+const prepareValidationForResolvedTarget = async (projectId, agent, requestedTarget) => {
+    const project = getProjectById(projectId);
+    if (!project) {
+        throw new ExecutionEnvironmentRouteError(404, 'project_not_found', 'Not found');
+    }
+    const descriptor = descriptorForResolvedTarget(project, requestedTarget);
+    const target = await resolveExecutionTarget({
+        project,
+        descriptor,
+        expectedWorkspacePath: requestedTarget.workspacePath,
+    });
+    if (target.identity.kind !== requestedTarget.identity.kind
+        || target.identity.key !== requestedTarget.identity.key
+        || target.workspacePath !== requestedTarget.workspacePath) {
+        throw new ExecutionEnvironmentRouteError(409, 'target_changed', 'The requested Build target changed before validation.');
+    }
+    return prepareValidationForTarget(project, descriptor, target, agent, false);
+};
+export const validateExecutionEnvironment = async (input, dependencies) => executePreparedValidation(await resolveExistingValidation(input.projectId, input.environmentId, input.agent, input.expectedTarget), input.agent, input.model ?? null, input.provider ?? getModelProvider(input.model), input.initiatedBy ?? 'user', dependencies, input.signal);
+export const validateExecutionEnvironmentForTarget = async (input, dependencies) => executePreparedValidation(await resolveExistingValidation(input.projectId, input.environmentId, input.agent, {
+    kind: input.target.identity.kind,
+    key: input.target.identity.key,
+    workspacePath: input.target.workspacePath,
+}, input.target), input.agent, input.model ?? null, input.provider ?? getModelProvider(input.model), input.initiatedBy ?? 'user', dependencies, input.signal);
+export const prepareAndValidateExecutionEnvironment = async (input, dependencies) => executePreparedValidation(await prepareValidation(input.projectId, input.agent), input.agent, input.model ?? null, input.provider ?? getModelProvider(input.model), input.initiatedBy ?? 'user', dependencies, input.signal);
+export const prepareAndValidateExecutionEnvironmentForTarget = async (input, dependencies) => executePreparedValidation(await prepareValidationForResolvedTarget(input.projectId, input.agent, input.target), input.agent, input.model ?? null, input.provider ?? getModelProvider(input.model), input.initiatedBy ?? 'user', dependencies, input.signal);
+//# sourceMappingURL=executionEnvironmentValidationOperations.js.map