@b00dea/cockpit 0.0.0-bootstrap.0 → 0.1.0

package/dist/environment/health-composition.js

@@ -0,0 +1,628 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path';
+import { loadCockpitConfig } from '../config/load.js';
+import { evaluatorUnavailable, findEvaluators } from '../grading/evaluate.js';
+import { createWorkStore } from '../work-orders/store.js';
+import { cockpitCommand } from '../fix-catalogue.js';
+import {} from './application/doctor.js';
+import { ObservationProducerRefusal } from './application/health.js';
+import { decodeLifecycleRecord, revalidateService } from './application/lifecycle.js';
+import {} from './application/lifecycle-context.js';
+import { decodeCoordinationRecord, observeClaimState, readRootPortInventory } from './claims.js';
+import { inspectCodexHookTrust } from './codex-hook-trust.js';
+import { observeEnvSchemas } from './env-schema-observation.js';
+import { hasErrorCode, RefusalError, ENVIRONMENT_CODES, errorCause, } from './contract.js';
+import { declaresNothingToRun, runtimeNotDeclared } from './declaration.js';
+import { resolveDockerExecutable, resolveGitExecutable } from './executable.js';
+import { createGitObservationStep, observeGit, observeRunningCheckout } from './git-observation.js';
+import { inspectProjectReadiness } from './readiness-composition.js';
+import { stackId } from './identity.js';
+import { createLifecycleCommandAdapters } from './lifecycle-composition.js';
+import { observeStateSeed, resolveLifecycleStage } from './lifecycle-stage.js';
+import { refreshObservationPostures, resolveObservationPostures } from './observations.js';
+import { deriveEntrypoints, observeRetainedPortFamily, projectRetainedPortFamilyResult, revalidatePortLeaseProjection, } from './ports.js';
+import { generatedApplicationProjection } from './generated-application/authorities.js';
+import { checkGeneratedEnvironment } from './generated-application/check.js';
+import { observeGeneratedApplicationSurfaces } from './generated-application/surface-observation.js';
+import { syncGeneratedEnvironment } from './generated-application/sync.js';
+import { admitRuntimeMeasurement, observeDockerRuntime, observeRuntimeMeasurement, observeRuntimeMountMaterialization, observeRuntimePortFamily, } from './runtime.js';
+import { readLocalRuntimeMeasurements } from './runtime-measurement-record.js';
+import { consumeSetupCheckoutProjection, observeSetupCheckout, withSetupCheckoutProjection, } from './setup-observation.js';
+import { observeConfiguration, readState, selectStateRoot } from './state.js';
+import { observeTemplateHealth } from './templates.js';
+function captureInput(value) {
+    try {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        const keys = ['configPath', 'env', 'timeoutMs'];
+        if (Reflect.ownKeys(descriptors).length !== keys.length
+            || keys.some((key) => !descriptors[key] || !('value' in descriptors[key])))
+            return undefined;
+        const configPath = descriptors.configPath.value;
+        const rawEnvironment = descriptors.env.value;
+        const timeoutMs = descriptors.timeoutMs.value;
+        if (typeof configPath !== 'string' || configPath.length === 0 || configPath.includes('\0')
+            || typeof timeoutMs !== 'number' || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30_000
+            || !rawEnvironment || typeof rawEnvironment !== 'object' || Array.isArray(rawEnvironment))
+            return undefined;
+        const env = {};
+        for (const [name, entry] of Object.entries(rawEnvironment)) {
+            if (name.length === 0 || name.includes('\0') || name.includes('=')
+                || entry !== undefined && (typeof entry !== 'string' || entry.includes('\0')))
+                return undefined;
+            env[name] = entry;
+        }
+        return { configPath: resolve(configPath), env, timeoutMs };
+    }
+    catch {
+        // A throwing accessor or proxy trap makes the input malformed, which the caller refuses.
+        return undefined;
+    }
+}
+function gitObservationEnvironment(env) {
+    return Object.fromEntries(Object.entries(env)
+        .filter((entry) => (entry[0] === 'LANG' || entry[0] === 'LC_ALL' || entry[0] === 'TZ') && typeof entry[1] === 'string'));
+}
+function checkoutObservationEnvironment(env) {
+    return Object.fromEntries(Object.entries(env)
+        .filter((entry) => typeof entry[1] === 'string'));
+}
+function commandConfigPath(value) {
+    try {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        const descriptor = descriptors.configPath;
+        return Reflect.ownKeys(descriptors).length === 1 && descriptor && 'value' in descriptor
+            && typeof descriptor.value === 'string'
+            ? descriptor.value
+            : undefined;
+    }
+    catch {
+        // A throwing accessor or proxy trap makes the command malformed, which the caller refuses.
+        return undefined;
+    }
+}
+// `sleep` releases the last holder and stops the services, so every runtime probe after it fails;
+// reporting that as missing observation evidence hid the one command that brings the stack back.
+async function sleepingStack(namespace, stack, configPath) {
+    const stored = await readState(namespace.paths.coordination(stack));
+    if (stored.kind !== 'complete')
+        return undefined;
+    const coordination = decodeCoordinationRecord(stored.value, stack);
+    if (!coordination || coordination.holders.length > 0)
+        return undefined;
+    const fix = cockpitCommand('up', { config: configPath });
+    return {
+        severity: 'error', code: ENVIRONMENT_CODES.STACK_NOT_RUNNING, target: stack,
+        message: 'the stack is asleep: no session holds it and its services are stopped, so there is nothing running to check; run up to start it, then rerun this command',
+        fix,
+    };
+}
+// Before the first `up` doctor still measures the machine, so a missing runtime is named there
+// rather than first at bring-up.
+function runtimeUnavailable(reason, target) {
+    return {
+        severity: 'error',
+        code: ENVIRONMENT_CODES.RUNTIME_UNAVAILABLE,
+        message: `the container runtime that runs this stack is not usable on this machine: ${reason}`,
+        target,
+        fix: 'install or start Docker so that docker info succeeds, then rerun this command',
+    };
+}
+function producers(input) {
+    const observedAt = () => new Date().toISOString();
+    const siblingRoot = resolve(dirname(input.config.result.source.path), input.config.result.config.cockpit.siblings_root);
+    const declaresStack = input.config.result.config.environment.compose_files.length > 0;
+    const runningStack = declaresStack && !input.stopped;
+    // Only doctor reaches here for a cockpit that declares nothing to run; a mounted sibling there
+    // gives Docker nothing to do, so a missing runtime must not be reported as a gap.
+    const configuredRuntime = !declaresNothingToRun(input.config.result.config.environment);
+    const runtimeMeasurement = configuredRuntime && !runningStack ? (async () => {
+        const docker = await resolveDockerExecutable(input.env);
+        if (docker.state !== 'available') {
+            if (input.stopped)
+                input.notice([runtimeUnavailable(docker.reason, input.stack)]);
+            return undefined;
+        }
+        const observed = await observeDockerRuntime({
+            executable: docker.value,
+            cwd: input.checkout.currentCheckoutPath,
+            env: Object.fromEntries(Object.entries(input.env).filter((entry) => ['PATH', 'DOCKER_HOST', 'DOCKER_CONTEXT', 'DOCKER_CONFIG', 'DOCKER_TLS_VERIFY', 'DOCKER_CERT_PATH'].includes(entry[0])
+                && typeof entry[1] === 'string')),
+            timeoutMs: input.timeoutMs,
+        }, input.execute);
+        if (observed.kind !== 'complete')
+            return undefined;
+        return observeRuntimeMeasurement(admitRuntimeMeasurement(observed, await readLocalRuntimeMeasurements(input.namespace.root)), input.stack);
+    })() : undefined;
+    const runtimeSession = runningStack ? (async () => {
+        const adapters = createLifecycleCommandAdapters({
+            configPath: input.config.result.source.path,
+            env: input.env,
+            sessionId: 'cockpit-health-read-only',
+            timeoutMs: input.timeoutMs,
+        }, input.execute);
+        const loaded = await adapters.load({ configPath: input.config.result.source.path });
+        if (loaded.kind === 'refusal')
+            return input.refuse?.(loaded.diagnostics);
+        if (loaded.kind !== 'complete' || loaded.result.stackId !== input.stack)
+            return undefined;
+        const stored = await readState(loaded.result.namespace.paths.lifecycle(loaded.result.stackId));
+        if (stored.kind !== 'complete')
+            return undefined;
+        const lifecycle = decodeLifecycleRecord(stored.value, loaded.result);
+        if (!lifecycle)
+            return undefined;
+        const retained = await observeRetainedPortFamily({
+            namespace: loaded.result.namespace,
+            stackId: loaded.result.stackId,
+            holderId: lifecycle.value.holderId,
+            checkoutId: loaded.result.checkoutId,
+            config: loaded.result.ports,
+        });
+        if (retained.kind !== 'complete')
+            return undefined;
+        const entrypoints = deriveEntrypoints({ lease: retained.lease, declarations: loaded.result.entrypointDerivatives });
+        if (entrypoints.kind !== 'complete')
+            return undefined;
+        const ports = await projectRetainedPortFamilyResult({ retainedResult: retained, entrypointResult: entrypoints });
+        if (!ports)
+            return undefined;
+        const readiness = await adapters.withRuntimeReadiness(loaded.result, async (value) => value, ports, (diagnostics) => input.refuse?.(diagnostics));
+        return readiness ? { adapters, context: loaded.result, readiness, lifecycle, ports,
+            lifecycleSnapshot: JSON.stringify(stored.value) } : undefined;
+    })() : undefined;
+    const stableSession = async () => {
+        const session = await runtimeSession;
+        if (!session)
+            return undefined;
+        const [configuration, stored, leaseCurrent] = await Promise.all([
+            loadCockpitConfig(input.config.result.source.path),
+            readState(session.context.namespace.paths.lifecycle(session.context.stackId)),
+            revalidatePortLeaseProjection({ projection: session.ports, namespace: session.context.namespace }),
+        ]);
+        return configuration.kind === 'complete' && configuration.result.source.sha256 === input.config.result.source.sha256
+            && stored.kind === 'complete' && JSON.stringify(stored.value) === session.lifecycleSnapshot && leaseCurrent
+            ? session : undefined;
+    };
+    // What stood in the way when the generated publication could not be checked: check's own errors.
+    // Their codes belong to check's owners (GENERATED_*, COMPOSE_*), which the environment registry does not list.
+    let checkRefusal = [];
+    const checkedApplication = (async () => {
+        const session = await runtimeSession;
+        if (runningStack && !session)
+            return undefined;
+        const checked = await checkGeneratedEnvironment({ configPath: input.config.result.source.path }, { execute: input.execute });
+        if (checked.kind !== 'complete')
+            checkRefusal = checked.diagnostics.filter(({ severity }) => severity === 'error');
+        return checked.kind === 'complete' ? generatedApplicationProjection(checked.result.application) : undefined;
+    })();
+    const machineFloor = !runningStack && input.config.result.config.environment.machine ? (async () => {
+        const adapters = createLifecycleCommandAdapters({
+            configPath: input.config.result.source.path,
+            env: input.env,
+            sessionId: 'cockpit-health-machine-floor',
+            timeoutMs: input.timeoutMs,
+        }, input.execute);
+        const loaded = await adapters.load({ configPath: input.config.result.source.path });
+        if (loaded.kind !== 'complete' || loaded.result.stackId !== input.stack)
+            return undefined;
+        return adapters.withMachineFloorReadiness(loaded.result, async (value) => value, (diagnostics) => { input.notice(diagnostics); return undefined; });
+    })() : undefined;
+    const inspectCurrentServices = async () => {
+        const session = await stableSession();
+        const completed = session?.lifecycle.value.completedServices;
+        if (!session || !completed
+            || completed.length !== session.readiness.topology.services.length
+            || JSON.stringify(completed.map(({ service }) => service).sort())
+                !== JSON.stringify(session.readiness.topology.services.map(({ id }) => id).sort()))
+            return undefined;
+        const values = new Map();
+        for (const service of completed) {
+            const admitted = await revalidateService(session.readiness.topology, service, { execute: input.execute });
+            if (admitted.kind !== 'complete')
+                return undefined;
+            values.set(service.service, admitted.evidence);
+        }
+        return await stableSession() ? values : undefined;
+    };
+    const currentServices = runningStack ? inspectCurrentServices() : undefined;
+    const observations = {
+        surfaces: async () => {
+            const application = await checkedApplication;
+            const observations = application && observeGeneratedApplicationSurfaces(application);
+            if (!observations && checkRefusal.length > 0)
+                throw new ObservationProducerRefusal('surface health needs a checked generated publication, and check refused it', checkRefusal);
+            if (!observations)
+                throw new RefusalError('surface health needs a current checked generated publication; run npx --no cockpit sync --config <your cockpit.toml>');
+            return observations;
+        },
+        claims: async () => [await observeClaimState({
+                namespace: input.namespace, stackId: input.stack, observedAt: observedAt(),
+            })],
+        git: async () => {
+            // Git status may refresh its index while checked publication authenticates checkout authority.
+            await machineFloor;
+            await checkedApplication;
+            const step = createGitObservationStep({
+                executable: input.git,
+                checkoutRoot: input.checkout.currentCheckoutPath,
+                env: gitObservationEnvironment(input.env),
+                timeoutMs: input.timeoutMs,
+                stackId: input.stack,
+                source: input.config.result.source.path,
+                checkoutId: input.checkout.checkoutId,
+            });
+            if (!step)
+                throw new RefusalError('Git health observation could not be planned');
+            const result = observeGit(step, await input.execute(step), {
+                stackId: input.stack,
+                checkoutId: input.checkout.checkoutId,
+                source: input.config.result.source.path,
+            });
+            if (result.kind !== 'complete')
+                throw new RefusalError('Git health observation is unavailable');
+            if (!runningStack)
+                return result.observations;
+            const session = await stableSession();
+            if (!session)
+                throw new RefusalError('running checkout health needs unchanged runtime and lifecycle authority');
+            const time = observedAt();
+            const setup = await observeSetupCheckout({ source: input.config.result.source,
+                cockpitName: input.config.result.config.cockpit.name, observedAt: time,
+                env: checkoutObservationEnvironment(input.env), gitExecutable: input.git });
+            const running = await withSetupCheckoutProjection(setup, { source: input.config.result.source,
+                cockpitName: input.config.result.config.cockpit.name, evaluatedAt: Date.parse(time) }, (projection) => observeRunningCheckout(session.readiness.topology, projection, session.context.runtimeSha256, time));
+            if (running?.kind !== 'complete')
+                throw new RefusalError('running checkout identity observation is unavailable');
+            return [...result.observations, running.observation];
+        },
+        host: async () => {
+            if (input.config.result.config.environment.machine) {
+                if (machineFloor) {
+                    const current = await machineFloor;
+                    // A stopped stack's unusable runtime is already a notice that names why.
+                    if (!current && input.stopped)
+                        return [];
+                    if (!current)
+                        throw new RefusalError('configured host capacity needs authenticated machine-floor execution evidence');
+                    return current;
+                }
+                const current = await runtimeSession;
+                if (!current)
+                    throw new RefusalError('configured host capacity needs authenticated machine-floor execution evidence');
+                return current.readiness.hostObservations;
+            }
+            return [];
+        },
+        lifecycle: async () => [await observeStateSeed({
+                namespace: input.namespace, stackId: input.stack, observedAt: observedAt(),
+            })],
+        ports: async () => {
+            if (!runningStack)
+                return [];
+            const [session, services] = await Promise.all([stableSession(), currentServices]);
+            if (!session || !services)
+                throw new RefusalError('runtime port health needs current lifecycle, lease and service identities');
+            const observation = await observeRuntimePortFamily({ topology: session.readiness.topology,
+                services: [...services.values()], namespace: session.context.namespace,
+                listenerTimeoutMs: input.timeoutMs,
+                revalidate: async () => {
+                    const fresh = await inspectCurrentServices();
+                    if (!fresh)
+                        throw new RefusalError('runtime services or lifecycle changed during port observation');
+                    return [...fresh.values()];
+                } });
+            return [observation];
+        },
+        runtime: async () => {
+            if (!configuredRuntime)
+                return [];
+            if (!runningStack) {
+                const measured = await runtimeMeasurement;
+                // A stopped stack's missing runtime is already a notice; its rows are left unobserved.
+                if (!measured && input.stopped)
+                    return [];
+                if (!measured)
+                    throw new RefusalError('configured runtime measurement needs authenticated runtime identity evidence');
+                return [measured];
+            }
+            const [session, services] = await Promise.all([stableSession(), currentServices]);
+            if (!session || !services)
+                throw new RefusalError('configured runtime health needs current runtime execution evidence');
+            return [...session.readiness.runtimeObservations,
+                observeRuntimeMountMaterialization({ topology: session.readiness.topology,
+                    services: [...services.values()], observedAt: observedAt() })];
+        },
+        envSchema: async () => await observeEnvSchemas({
+            stackId: input.stack,
+            siblings: input.config.result.config.sibling.map((sibling) => ({
+                slug: sibling.slug, dir: sibling.dir, root: resolve(siblingRoot, sibling.dir),
+            })),
+            env: input.env,
+            timeoutMs: input.timeoutMs,
+        }, { execute: input.execute }),
+        state: async () => observeConfiguration({
+            path: input.config.result.source.path, stackId: input.stack, observedAt: observedAt(),
+        }),
+        templates: async () => observeTemplateHealth({
+            stackId: input.stack, observedAt: observedAt(), siblingRoot,
+            siblings: input.config.result.config.sibling,
+        }),
+    };
+    return { observations, revalidate: async () => !runningStack || await stableSession() !== undefined };
+}
+async function checkoutProjection(input, loaded, git) {
+    const observedAt = new Date().toISOString();
+    const observed = await observeSetupCheckout({
+        source: loaded.result.source,
+        cockpitName: loaded.result.config.cockpit.name,
+        observedAt,
+        env: checkoutObservationEnvironment(input.env),
+        gitExecutable: git,
+    });
+    // The owner's reason (for example, a cockpit root that is not a Git checkout) says what to do; dropping
+    // it left preflight with only "observation source is unavailable".
+    if (observed.state === 'failed')
+        return { failed: { severity: 'error',
+                code: observed.code, message: observed.reason, target: loaded.result.source.path } };
+    return withSetupCheckoutProjection(observed, {
+        source: loaded.result.source,
+        cockpitName: loaded.result.config.cockpit.name,
+        evaluatedAt: Date.parse(observedAt),
+    }, consumeSetupCheckoutProjection);
+}
+// Work orders exist once workorders/ does, and from then on work grade and cockpit grade run the first
+// tool work.evaluators lists that can run, whichever agent tool did the work; doctor names the case
+// where none is on PATH before a grade fails on it, and says how each closed order closed.
+async function inspectWorkEvaluator(root, env, evaluators) {
+    try {
+        if (!(await lstat(join(root, 'workorders'))).isDirectory())
+            return [];
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return [];
+        throw error;
+    }
+    // The evaluator search looks only in canonical PATH directories, so doctor does too.
+    const directories = [];
+    for (const directory of (env.PATH ?? '').split(delimiter)) {
+        if (!directory || !isAbsolute(directory) || resolve(directory) !== directory)
+            continue;
+        try {
+            if (await realpath(directory) === directory)
+                directories.push(directory);
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'ENOENT', 'ENOTDIR', 'EACCES'))
+                continue;
+            throw error;
+        }
+    }
+    const closed = (await createWorkStore(root).list()).flatMap(record => record.closure ? [{ severity: 'info',
+            code: ENVIRONMENT_CODES.WORK_ORDER_CLOSED, target: `workorders/${record.id}.md`,
+            message: `${record.id} closed as ${record.closure.how}, signed off by ${record.closure.by}${record.closure.note ? `: ${record.closure.note}` : ''}` }] : []);
+    const { found, missing } = await findEvaluators(evaluators, directories);
+    if (found.length)
+        return closed;
+    return [{ severity: 'warning', target: 'workorders',
+            ...evaluatorUnavailable(`this cockpit has work orders, but no evaluator work.evaluators lists is on PATH to run work grade and cockpit grade: ${missing.map(row => row.message).join('; ')}`) }, ...closed];
+}
+export function createHealthCommandAdapters(rawInput, execute) {
+    const input = captureInput(rawInput);
+    let selectedNamespace;
+    const load = async (command, issue, refuse, purpose) => {
+        const requestedPath = commandConfigPath(command);
+        if (!input || typeof execute !== 'function' || typeof issue !== 'function'
+            || requestedPath !== input.configPath)
+            return undefined;
+        const loaded = await loadCockpitConfig(input.configPath);
+        // A malformed cockpit.toml is the user's to fix, so the loader's own diagnostics reach them.
+        if (loaded.kind === 'refusal')
+            return refuse?.(loaded.diagnostics);
+        if (loaded.kind !== 'complete')
+            return undefined;
+        // Health is about a running stack or a machine floor; with neither declared it is not declared,
+        // never healthy, and preflight refuses. Doctor still checks what such a cockpit does depend on:
+        // its Git working tree, its siblings and its surfaces.
+        const notDeclared = declaresNothingToRun(loaded.result.config.environment)
+            ? runtimeNotDeclared(loaded.result.source.path) : undefined;
+        if (notDeclared && purpose !== 'doctor')
+            return refuse?.([notDeclared]);
+        const git = await resolveGitExecutable(input.env);
+        if (git.state !== 'available')
+            return undefined;
+        const checkout = await checkoutProjection(input, loaded, git.value);
+        if (checkout && 'failed' in checkout)
+            return refuse?.([...notDeclared ? [notDeclared] : [], checkout.failed]);
+        if (!checkout || process.platform !== 'darwin' && process.platform !== 'linux')
+            return undefined;
+        const namespace = await selectStateRoot({
+            platform: process.platform,
+            home: input.env.HOME,
+            xdgStateHome: input.env.XDG_STATE_HOME,
+            checkoutRoots: [checkout.currentCheckoutPath, checkout.mainCheckoutPath],
+            cockpitId: checkout.cockpitId,
+        });
+        // Without the state root's own refusal, doctor reported only that its observation source
+        // was unavailable, which named neither the directory nor why it could not be used.
+        if (namespace.kind === 'refusal')
+            return refuse?.([{ severity: 'error',
+                    code: namespace.code, message: namespace.message, target: namespace.target }]);
+        if (namespace.kind !== 'complete')
+            return undefined;
+        selectedNamespace = namespace.value;
+        const currentStack = stackId({
+            cockpitId: checkout.cockpitId,
+            checkoutId: checkout.checkoutId,
+            variant: { kind: 'shared' },
+        });
+        let stopped = notDeclared ?? null;
+        const refreshPreflight = async (previous) => {
+            const observedAt = new Date().toISOString();
+            const configuration = (await observeConfiguration({
+                path: loaded.result.source.path,
+                stackId: currentStack,
+                observedAt,
+            })).find(({ code }) => code === ENVIRONMENT_CODES.CONFIG_STALE);
+            if (!configuration)
+                return undefined;
+            try {
+                const authorityInput = {
+                    configuration, cockpitId: checkout.cockpitId,
+                    checkoutPath: checkout.currentCheckoutPath, variant: { kind: 'shared' },
+                };
+                const authority = previous === undefined
+                    ? await resolveObservationPostures(authorityInput)
+                    : previous.authorities.length === 1
+                        ? await refreshObservationPostures({ ...authorityInput, previous: previous.authorities[0] })
+                        : undefined;
+                if (!authority)
+                    return undefined;
+                const stage = await resolveLifecycleStage({
+                    namespace: namespace.value,
+                    stackId: currentStack,
+                    observedAt,
+                });
+                if (stage.kind !== 'complete')
+                    return refuse?.(stage.diagnostics);
+                if (previous === undefined && !notDeclared) {
+                    if (stage.authority.stage !== 'steady') {
+                        const fix = cockpitCommand('up', { config: loaded.result.source.path });
+                        stopped = {
+                            severity: 'error', code: ENVIRONMENT_CODES.STATE_UNSEEDED, target: loaded.result.source.path,
+                            message: `lifecycle is still in bootstrap — the stack has never completed a first bring-up, so only the checks that need no running stack ran; fix: ${fix}; then retry the command that stopped`,
+                            fix,
+                        };
+                    }
+                    else
+                        stopped = await sleepingStack(namespace.value, currentStack, loaded.result.source.path) ?? null;
+                }
+                return {
+                    authorities: [authority],
+                    stages: [stage.authority],
+                };
+            }
+            catch (error) {
+                return refuse?.([{
+                        severity: 'error', code: ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE,
+                        message: `preflight evidence could not be read: ${errorCause(error)}`, target: loaded.result.source.path,
+                    }]);
+            }
+        };
+        const preflight = await refreshPreflight();
+        if (!preflight)
+            return undefined;
+        const notices = [];
+        const sourceProducers = producers({
+            checkout,
+            config: loaded,
+            namespace: namespace.value,
+            stack: currentStack,
+            git: git.value,
+            env: input.env,
+            timeoutMs: input.timeoutMs,
+            execute,
+            ...(refuse ? { refuse: (diagnostics) => refuse(diagnostics) } : {}),
+            stopped: stopped !== null,
+            notice: (diagnostics) => {
+                for (const diagnostic of diagnostics) {
+                    if (!notices.some(({ code, target }) => code === diagnostic.code && target === diagnostic.target))
+                        notices.push(diagnostic);
+                }
+            },
+        });
+        const secondObservedAt = new Date().toISOString();
+        const secondObservation = await observeSetupCheckout({
+            source: loaded.result.source,
+            cockpitName: loaded.result.config.cockpit.name,
+            observedAt: secondObservedAt,
+            env: checkoutObservationEnvironment(input.env),
+            gitExecutable: git.value,
+        });
+        return withSetupCheckoutProjection(secondObservation, {
+            source: loaded.result.source,
+            cockpitName: loaded.result.config.cockpit.name,
+            evaluatedAt: Date.parse(secondObservedAt),
+        }, (projection) => issue({
+            checkout: projection,
+            configuration: loaded.result,
+            preflight,
+            env: gitObservationEnvironment(input.env),
+            gitExecutable: git.value,
+            timeoutMs: input.timeoutMs,
+            producers: sourceProducers.observations,
+            refreshPreflight: async (previous) => await sourceProducers.revalidate() ? refreshPreflight(previous) : undefined,
+            stopped,
+            notices: () => [...notices],
+        }));
+    };
+    const inspectSurfaceOverrides = async (configPath) => {
+        if (!input) {
+            return {
+                kind: 'unavailable',
+                code: 'SURFACE_OVERRIDE_INSPECTION_UNAVAILABLE',
+                reason: 'surface override inspection needs valid command composition input',
+            };
+        }
+        if (configPath !== input.configPath) {
+            return {
+                kind: 'refusal',
+                code: 'SURFACE_OVERRIDE_INSPECTION_PATH_MISMATCH',
+                reason: 'surface override inspection is bound to the configured cockpit source',
+            };
+        }
+        try {
+            const outcome = await syncGeneratedEnvironment({ configPath: input.configPath, dryRun: true }, { execute });
+            if (outcome.kind !== 'complete') {
+                const diagnostic = outcome.diagnostics[0];
+                return {
+                    kind: 'refusal',
+                    code: diagnostic?.code || 'SURFACE_OVERRIDE_INSPECTION_REFUSED',
+                    reason: diagnostic?.message || 'generated surface override inspection was refused',
+                };
+            }
+            const application = generatedApplicationProjection(outcome.result.application);
+            if (!application
+                || application.sourceSha256 !== outcome.result.sourceSha256
+                || application.generation !== outcome.result.generation) {
+                return {
+                    kind: 'refusal',
+                    code: 'SURFACE_OVERRIDE_INSPECTION_INVALID',
+                    reason: 'generated surface override inspection did not return an authenticated application projection',
+                };
+            }
+            return {
+                kind: 'complete',
+                activeOverrides: application.activeSurfaceOverrides,
+                changedOverrideOriginals: application.changedOverrideOriginals,
+            };
+        }
+        catch (error) {
+            return {
+                kind: 'unavailable',
+                code: 'SURFACE_OVERRIDE_INSPECTION_UNAVAILABLE',
+                reason: `authenticated generated surface override inspection is unavailable: ${errorCause(error)}`,
+            };
+        }
+    };
+    // Codex skips a project hook nobody on this machine has trusted, so doctor says so.
+    const inspectHookTrust = input ? () => inspectCodexHookTrust({ root: dirname(input.configPath), env: input.env })
+        : undefined;
+    const inspectEvaluator = input ? (evaluators) => inspectWorkEvaluator(dirname(input.configPath), input.env, evaluators) : undefined;
+    const inspectReadiness = input ? () => inspectProjectReadiness({ root: dirname(input.configPath), configPath: input.configPath,
+        checkRoot: false, env: input.env, timeoutMs: input.timeoutMs }, execute) : undefined;
+    // Read after load, which selects this cockpit's state namespace; before that there is no state root to read.
+    const readUnreadableState = async () => {
+        if (!selectedNamespace)
+            return { kind: 'complete', skipped: [] };
+        const inventory = await readRootPortInventory(selectedNamespace);
+        return inventory.kind === 'complete' ? { kind: 'complete', skipped: inventory.skipped } : inventory;
+    };
+    return { load, inspectSurfaceOverrides, ...(inspectHookTrust ? { inspectHookTrust } : {}),
+        ...(inspectEvaluator ? { inspectEvaluator } : {}), ...(inspectReadiness ? { inspectReadiness } : {}), readUnreadableState,
+        execute: (step) => execute(step) };
+}