@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment/declaration.d.ts

@@ -0,0 +1,14 @@
+import type { CockpitConfig } from '../schema.js';
+import { type EnvironmentDiagnostic, RefusalError } from './contract.js';
+export type DeclaredRuntime = 'compose' | 'none';
+export declare function declaredRuntime(environment: Pick<CockpitConfig['environment'], 'compose_files'>): DeclaredRuntime;
+export declare function declaresNothingToRun(environment: Pick<CockpitConfig['environment'], 'compose_files' | 'machine'>): boolean;
+/** The one refusal every runtime command gives a cockpit that declares no environment. */
+export declare function runtimeNotDeclared(target: string): EnvironmentDiagnostic;
+/** A service named on the command line that the stack does not declare: a wrong name, not a runtime failure. */
+export declare function serviceNotDeclared(service: string, declared: readonly string[]): EnvironmentDiagnostic;
+/** Carries a declaration refusal through owners whose only failure channel is a thrown error. */
+export declare class DeclarationRefusalError extends RefusalError {
+    readonly diagnostic: EnvironmentDiagnostic;
+    constructor(diagnostic: EnvironmentDiagnostic);
+}

package/dist/environment/declaration.js

@@ -0,0 +1,39 @@
+import { ENVIRONMENT_CODES, RefusalError } from './contract.js';
+export function declaredRuntime(environment) {
+    return environment.compose_files.length > 0 ? 'compose' : 'none';
+}
+// A machine floor alone still has something to measure: preflight checks this laptop against it,
+// so only a cockpit that declares no runtime and no floor has nothing for runtime commands to do.
+export function declaresNothingToRun(environment) {
+    return declaredRuntime(environment) === 'none' && environment.machine === undefined;
+}
+/** The one refusal every runtime command gives a cockpit that declares no environment. */
+export function runtimeNotDeclared(target) {
+    return {
+        severity: 'error',
+        // A literal, so the diagnostic inventory captures the fix beside the code.
+        code: 'ENVIRONMENT_NOT_DECLARED',
+        message: 'this cockpit declares no runtime environment, so there is nothing to start, stop, observe or measure; sync and check publish and verify the harness surfaces only',
+        target,
+        fix: 'declare environment.compose_files = ["compose.yml"] to run your Compose file (for a small app with none, npx --no cockpit init <cockpit root> --scaffold-compose <app dir> --port <port> writes a starting one), then run npx --no cockpit sync --config <your cockpit.toml>',
+    };
+}
+/** A service named on the command line that the stack does not declare: a wrong name, not a runtime failure. */
+export function serviceNotDeclared(service, declared) {
+    return {
+        severity: 'error',
+        code: 'SERVICE_NOT_DECLARED',
+        message: `this stack declares no service ${service}; it declares ${declared.length === 0 ? 'no services' : declared.join(', ')}`,
+        target: service,
+        fix: 'rerun with --service set to one of the declared services',
+    };
+}
+/** Carries a declaration refusal through owners whose only failure channel is a thrown error. */
+export class DeclarationRefusalError extends RefusalError {
+    diagnostic;
+    constructor(diagnostic) {
+        super(diagnostic.message);
+        this.name = 'DeclarationRefusalError';
+        this.diagnostic = diagnostic;
+    }
+}

package/dist/environment/destructive-composition.d.ts

@@ -0,0 +1,29 @@
+import type { ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import { type DownCommandAdapters, type ResetCommandAdapters } from './application/lifecycle-context.js';
+import { type ExecutionStep } from './contract.js';
+import type { RuntimeMeasurementProbeAuthority } from './runtime.js';
+export interface DestructiveCompositionInput {
+    readonly configPath: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly sessionId: string;
+    readonly timeoutMs: number;
+    readonly dockerContext: string;
+    readonly activeProfiles?: readonly string[];
+    readonly runtimeMeasurementProbeAuthority?: RuntimeMeasurementProbeAuthority | (() => RuntimeMeasurementProbeAuthority);
+}
+type Executor = (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+export type DestructiveDaemonSelection = Readonly<{
+    kind: 'complete';
+    dockerContext: string;
+}> | Readonly<{
+    kind: 'refusal';
+    adapters: DestructiveAdapters;
+}>;
+/**
+ * Names the one Docker context down and reset delete from, fixed before any adapter exists so
+ * every discovery and deletion step of the command addresses that context.
+ */
+export declare function selectDestructiveDaemon(env: Readonly<Record<string, string | undefined>>, timeoutMs: number, execute: Executor): Promise<DestructiveDaemonSelection>;
+type DestructiveAdapters = DownCommandAdapters & ResetCommandAdapters;
+export declare function createDestructiveCommandAdapters(rawInput: DestructiveCompositionInput, execute: Executor): DestructiveAdapters;
+export {};

package/dist/environment/destructive-composition.js

@@ -0,0 +1,333 @@
+import { resolve } from 'node:path';
+import { admitLocalDockerEndpoint } from './docker-endpoint.js';
+import { selectLocalDockerDaemon } from './docker-daemon.js';
+import { cockpitCommand } from '../fix-catalogue.js';
+import { loadCockpitConfig, consumeLoadedConfigProjection } from '../config/load.js';
+import { issueDestructiveRunContext, noticeLifecycleRun, } from './application/lifecycle-context.js';
+import { ENVIRONMENT_CODES, forwardedRefusal } from './contract.js';
+import { decodeCoordinationRecord, liveHolderMessage, observeProcessStart, processHost, readActiveStackInventory, releaseDeadSessionHolders } from './claims.js';
+import { declaresNothingToRun, runtimeNotDeclared } from './declaration.js';
+import { resolveDockerExecutable, resolvePathRemovalExecutable } from './executable.js';
+import { composeProjectName } from './identity.js';
+import { createLifecycleCommandAdapters } from './lifecycle-composition.js';
+import { deriveEntrypoints, observeRetainedPortFamily, projectRetainedPortFamilyResult, } from './ports.js';
+import { discoverReclaim } from './reclaim.js';
+import { readState } from './state.js';
+import { earlierNameRefusalMessage, findStackUnderEarlierName } from './lifecycle-stage.js';
+function captureInput(value) {
+    try {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        const keys = ['configPath', 'env', 'sessionId', 'timeoutMs', 'dockerContext'];
+        const optionalKeys = ['activeProfiles', 'runtimeMeasurementProbeAuthority'].filter((key) => descriptors[key] !== undefined);
+        if (Reflect.ownKeys(descriptors).length !== keys.length + optionalKeys.length
+            || keys.some((key) => !descriptors[key] || !('value' in descriptors[key]))
+            || optionalKeys.some((key) => !('value' in descriptors[key])))
+            return undefined;
+        const configPath = descriptors.configPath.value;
+        const rawEnvironment = descriptors.env.value;
+        const sessionId = descriptors.sessionId.value;
+        const timeoutMs = descriptors.timeoutMs.value;
+        const dockerContext = descriptors.dockerContext.value;
+        const activeProfiles = descriptors.activeProfiles?.value;
+        const runtimeMeasurementProbeAuthority = descriptors.runtimeMeasurementProbeAuthority?.value;
+        if (typeof configPath !== 'string' || configPath.length === 0 || configPath.includes('\0')
+            || typeof sessionId !== 'string' || sessionId.length === 0 || sessionId.includes('\0')
+            || typeof timeoutMs !== 'number' || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30_000
+            || typeof dockerContext !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.test(dockerContext)
+            || activeProfiles !== undefined && (!Array.isArray(activeProfiles) || activeProfiles.length > 64
+                || new Set(activeProfiles).size !== activeProfiles.length
+                || activeProfiles.some((profile) => typeof profile !== 'string' || !/^[a-z0-9][a-z0-9_.-]*$/.test(profile)))
+            || !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;
+        }
+        // A local DOCKER_HOST is selected through Docker's `default` context, which reports that
+        // endpoint; dropping it addressed whatever the default context named instead. TLS and
+        // remote hosts stay refused.
+        if (env.DOCKER_HOST !== undefined && (admitLocalDockerEndpoint(env.DOCKER_HOST) === undefined
+            || dockerContext !== 'default' || env.DOCKER_CONTEXT !== undefined)
+            || env.DOCKER_TLS_VERIFY !== undefined || env.DOCKER_CERT_PATH !== undefined
+            || env.DOCKER_CONTEXT !== undefined && env.DOCKER_CONTEXT !== dockerContext)
+            return undefined;
+        return {
+            configPath: resolve(configPath),
+            env,
+            sessionId,
+            timeoutMs,
+            dockerContext,
+            ...(activeProfiles === undefined ? {} : { activeProfiles: [...activeProfiles].sort() }),
+            ...(runtimeMeasurementProbeAuthority === undefined ? {} : { runtimeMeasurementProbeAuthority }),
+        };
+    }
+    catch { // A throwing accessor or proxy trap makes the input malformed; the caller refuses it.
+        return undefined;
+    }
+}
+function refusal(target, message = 'destructive run authority is unavailable or does not match current state', code = ENVIRONMENT_CODES.LIFECYCLE_EVIDENCE_INVALID) {
+    return forwardedRefusal([{ severity: 'error', code, message, target }]);
+}
+function sameSource(left, right) {
+    return left.path === right.path && left.byteLength === right.byteLength && left.sha256 === right.sha256;
+}
+function executionEnvironment(env) {
+    return Object.fromEntries(Object.entries(env)
+        .filter((entry) => (['PATH', 'TMPDIR', 'LANG', 'LC_ALL'].includes(entry[0]) && typeof entry[1] === 'string'))
+        .sort(([left], [right]) => left.localeCompare(right)));
+}
+/**
+ * Names the one Docker context down and reset delete from, fixed before any adapter exists so
+ * every discovery and deletion step of the command addresses that context.
+ */
+export async function selectDestructiveDaemon(env, timeoutMs, execute) {
+    const daemon = await selectLocalDockerDaemon(env, timeoutMs, execute, { command: 'down and reset', localOnly: 'down and reset never delete from a remote daemon' });
+    return daemon.kind === 'refusal'
+        ? { kind: 'refusal', adapters: refusingAdapters(execute, daemon.diagnostic) }
+        : { kind: 'complete', dockerContext: daemon.dockerContext };
+}
+async function observeReclaim(input, context, cwd, execute) {
+    const [runtimeExecutable, pathExecutable] = await Promise.all([
+        resolveDockerExecutable(input.env),
+        resolvePathRemovalExecutable(),
+    ]);
+    if (runtimeExecutable.state !== 'available' || pathExecutable.state !== 'available')
+        return undefined;
+    const discovery = await discoverReclaim({
+        executable: runtimeExecutable.value,
+        cwd,
+        env: executionEnvironment(input.env),
+        stackId: context.stackId,
+        cockpitId: context.cockpitId,
+        timeoutMs: input.timeoutMs,
+        context: input.dockerContext,
+        ...(input.env.DOCKER_HOST === undefined ? {} : { host: input.env.DOCKER_HOST }),
+    }, execute);
+    if (!discovery)
+        return undefined;
+    if ('diagnostics' in discovery)
+        return forwardedRefusal(discovery.diagnostics);
+    return { discovery, runtimeExecutable, pathExecutable };
+}
+// Adapters that load nothing. A cockpit with no runtime has nothing to stop or reset; that
+// outranks any runtime-input problem, so it is reported before `reason` or the generic refusal.
+function refusingAdapters(execute, reason) {
+    return {
+        load: async (request) => {
+            const loaded = typeof request?.configPath === 'string' ? await loadCockpitConfig(request.configPath) : undefined;
+            const diagnostic = loaded?.kind === 'complete' && declaresNothingToRun(loaded.result.config.environment)
+                ? runtimeNotDeclared(loaded.result.source.path) : reason;
+            return diagnostic === undefined ? refusal(request?.configPath ?? 'destructive')
+                : { kind: 'refusal', status: 2, result: null, diagnostics: [diagnostic] };
+        },
+        observe: async () => undefined,
+        execute,
+    };
+}
+export function createDestructiveCommandAdapters(rawInput, execute) {
+    const input = captureInput(rawInput);
+    if (!input || typeof execute !== 'function')
+        return refusingAdapters(execute);
+    const lifecycleInput = {
+        configPath: input.configPath,
+        env: input.env.DOCKER_HOST === undefined ? { ...input.env, DOCKER_CONTEXT: input.dockerContext } : input.env,
+        sessionId: input.sessionId,
+        timeoutMs: input.timeoutMs,
+        ...(input.activeProfiles === undefined ? {} : { activeProfiles: input.activeProfiles }),
+        ...(input.runtimeMeasurementProbeAuthority === undefined ? {} : { runtimeMeasurementProbeAuthority: input.runtimeMeasurementProbeAuthority }),
+    };
+    const lifecycle = createLifecycleCommandAdapters(lifecycleInput, execute);
+    const issued = new WeakMap();
+    // The checkout root runtime readiness resolved for each context, so a reclaim-only
+    // observation reuses it instead of re-measuring the runtime.
+    const readinessRoots = new WeakMap();
+    // Config, coordination and reclaim discovery, the evidence each destructive step re-reads.
+    const observeReclaimTargets = async (context, configuration, cwd) => {
+        const coordinationAddress = context.namespace.paths.coordination(context.stackId);
+        const stored = await readState(coordinationAddress);
+        if (stored.kind !== 'complete')
+            return undefined;
+        const reclaim = await observeReclaim(input, context, cwd, execute);
+        if (!reclaim)
+            return undefined;
+        if ('diagnostics' in reclaim)
+            return reclaim;
+        // Policy rows select installers. They do not identify an instantiated cache or
+        // its owning root, so treating their logical volume names as cache authority
+        // could authorize deletion of unrelated data.
+        const declaredCacheIds = [];
+        const dependencyCaches = [];
+        const common = {
+            stackId: context.stackId,
+            cockpitId: context.cockpitId,
+            configSha256: context.runtimeSha256,
+            coordinationRecord: stored.value,
+            coordinationAddress,
+            requesterHolderId: context.holderId,
+            declaredCacheIds,
+            discovery: reclaim.discovery,
+            cwd,
+            env: executionEnvironment(input.env),
+            timeoutMs: input.timeoutMs,
+        };
+        return {
+            instance: context.instance,
+            down: {
+                ...common,
+                executable: reclaim.runtimeExecutable.value,
+                dependencyCaches,
+                pathExecutable: reclaim.pathExecutable.value,
+            },
+            reset: {
+                ...common,
+                expectedCoordinationRevision: stored.value.revision,
+                resettableVolumes: [...configuration.config.environment.resettable_volumes],
+                composeProject: composeProjectName({ cockpitName: configuration.config.cockpit.name, stackId: context.stackId }),
+                generatedHostPaths: configuration.config.environment.generated_host_paths.map((declaration) => ({
+                    root: cwd,
+                    path: resolve(cwd, declaration),
+                    declaration,
+                })),
+                runtimeExecutable: reclaim.runtimeExecutable.value,
+                pathExecutable: reclaim.pathExecutable.value,
+            },
+        };
+    };
+    const currentConfiguration = async (context) => {
+        const loaded = await loadCockpitConfig(context.configPath);
+        if (loaded.kind === 'refusal')
+            return loaded;
+        if (loaded.kind !== 'complete')
+            return undefined;
+        const configuration = consumeLoadedConfigProjection(loaded.result);
+        return configuration && sameSource(context.source, configuration.source) ? configuration : undefined;
+    };
+    return {
+        async load(request) {
+            if (request.configPath !== resolve(input.configPath))
+                return refusal(request.configPath);
+            const loaded = await lifecycle.load(request);
+            if (loaded.kind !== 'complete') {
+                return loaded.kind === 'refusal' ? loaded : refusal(request.configPath);
+            }
+            const context = loaded.result;
+            const reaped = await releaseDeadSessionHolders({
+                namespace: context.namespace, stackId: context.stackId,
+                successor: { holderId: context.holderId, checkoutId: context.checkoutId },
+                now: new Date().toISOString(), observe: (pid) => observeProcessStart(pid, processHost(execute)),
+            });
+            if (reaped.kind === 'refusal')
+                return forwardedRefusal(reaped.diagnostics);
+            // A restore released above leaves data that may be half applied; the warning rides on
+            // whatever this load returns.
+            let claim;
+            const outcome = await (async () => {
+                let inventory = await readActiveStackInventory(context.namespace);
+                if (inventory.kind !== 'complete')
+                    return refusal(context.stackId);
+                const currentRecord = inventory.value.find(({ stackId }) => stackId === context.stackId)?.record;
+                if (!currentRecord?.holders.some(({ holderId, checkoutId }) => (holderId === context.holderId && checkoutId === context.checkoutId))) {
+                    // The active inventory omits a stack whose final holder released it, so the
+                    // coordination record itself says whether this stack ever ran.
+                    const stored = await readState(context.namespace.paths.coordination(context.stackId));
+                    if (stored.kind === 'missing') {
+                        const earlier = await findStackUnderEarlierName({ namespace: context.namespace, cockpitId: context.cockpitId, checkoutId: context.checkoutId });
+                        if (earlier.kind === 'refusal')
+                            return refusal(earlier.target, earlier.message, earlier.code);
+                        if (earlier.name !== undefined)
+                            return refusal(context.stackId, earlierNameRefusalMessage(context.source.path, earlier.name), ENVIRONMENT_CODES.STACK_RECORDED_UNDER_EARLIER_NAME);
+                        return refusal(context.stackId, `this checkout has never claimed the stack, so down and reset have nothing to act on; run \`${cockpitCommand('up')}\` first`);
+                    }
+                    const coordination = stored.kind === 'complete' ? decodeCoordinationRecord(stored.value, context.stackId) : undefined;
+                    if (!coordination)
+                        return refusal(context.stackId);
+                    if (coordination.holders.length > 0) {
+                        return refusal(context.stackId, liveHolderMessage(coordination.holders), ENVIRONMENT_CODES.CLAIM_CO_TENANT);
+                    }
+                    // `sleep` and an ended `session` release the final holder and stop the runtime,
+                    // but its containers, networks and images remain. Claiming the stack here, as
+                    // `up` would without starting anything, gives down the holder authority to retire
+                    // them; refusing sent the operator to start a stack only to remove it. The
+                    // application gives the claim back when the run reserves no drain.
+                    let claimRefusal;
+                    claim = await lifecycle.withAcquiredPorts(context, async ({ leaseResult }) => leaseResult, (diagnostics) => { claimRefusal = diagnostics; return undefined; });
+                    if (claimRefusal)
+                        return forwardedRefusal(claimRefusal);
+                    if (claim?.kind !== 'complete' || claim.change !== 'acquired')
+                        return refusal(context.stackId, 'the stopped stack could not be claimed for down or reset');
+                    inventory = await readActiveStackInventory(context.namespace);
+                    if (inventory.kind !== 'complete')
+                        return refusal(context.stackId);
+                }
+                const claimInventory = inventory.value.flatMap(({ stackId, record }) => (record.holders.map(({ checkoutId }) => ({ stackId, checkoutId }))));
+                const current = { stackId: context.stackId, checkoutId: context.checkoutId };
+                const destructive = issueDestructiveRunContext({
+                    lifecycle: context,
+                    instance: {
+                        launcher: current,
+                        claimInventory,
+                    },
+                    ...claim ? { claim } : {},
+                });
+                if (destructive.kind === 'complete')
+                    issued.set(destructive.result, context);
+                return destructive;
+            })();
+            return outcome;
+        },
+        async observe(context) {
+            const lifecycleContext = issued.get(context);
+            if (!lifecycleContext)
+                return undefined;
+            const configuration = await currentConfiguration(context);
+            if (!configuration || 'diagnostics' in configuration)
+                return configuration;
+            const retained = await observeRetainedPortFamily({
+                namespace: context.namespace,
+                stackId: context.stackId,
+                holderId: context.holderId,
+                checkoutId: context.checkoutId,
+                config: 'recorded',
+            });
+            if (retained.kind !== 'complete')
+                return forwardedRefusal(retained.diagnostics);
+            const entrypoints = deriveEntrypoints({
+                lease: retained.lease,
+                declarations: context.entrypointDerivatives,
+            });
+            if (entrypoints.kind !== 'complete')
+                return forwardedRefusal(entrypoints.diagnostics);
+            const ports = await projectRetainedPortFamilyResult({ retainedResult: retained, entrypointResult: entrypoints });
+            if (!ports)
+                return undefined;
+            let runtimeRefusal;
+            const readiness = await lifecycle.withRuntimeReadiness(lifecycleContext, async (value) => value, ports, (diagnostics) => { runtimeRefusal = forwardedRefusal(diagnostics); return undefined; }, 'teardown');
+            if (runtimeRefusal)
+                return runtimeRefusal;
+            if (!readiness)
+                return undefined;
+            readinessRoots.set(context, readiness.topology.cwd);
+            const targets = await observeReclaimTargets(context, configuration, readiness.topology.cwd);
+            if (!targets || 'diagnostics' in targets)
+                return targets;
+            return { ...targets, runtime: readiness.lifecycle, ports };
+        },
+        // Runtime readiness proves the runtime the plan was made for; the steps of a drain that
+        // plan already reserved need only fresh reclaim evidence against the same checkout root.
+        async observeReclaim(context) {
+            const cwd = readinessRoots.get(context);
+            if (!issued.has(context) || cwd === undefined)
+                return undefined;
+            const configuration = await currentConfiguration(context);
+            if (!configuration || 'diagnostics' in configuration)
+                return configuration;
+            return observeReclaimTargets(context, configuration, cwd);
+        },
+        execute,
+    };
+}

package/dist/environment/docker-daemon.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Names the one local Docker daemon a command addresses, before the command does any work, so
+ * `down`, `reset` and `runtime measure` choose a daemon by one rule. It observes Docker's own
+ * context configuration through the supplied `execute`; it never spawns a process itself.
+ */
+import { type ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import { type Diagnostic, type ExecutionStep } from './contract.js';
+type Executor = (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+export type LocalDockerDaemon = Readonly<{
+    kind: 'complete';
+    dockerContext: string;
+    endpoint: string;
+    source: string;
+}> | Readonly<{
+    kind: 'refusal';
+    diagnostic: Diagnostic;
+}>;
+export interface DaemonUse {
+    readonly command: string;
+    readonly localOnly: string;
+}
+/**
+ * A local DOCKER_HOST is taken as given, through Docker's `default` context. Otherwise the context
+ * is the one DOCKER_CONTEXT names or, with neither set, the active one, read once here so the
+ * caller can pin it for every later step: reading it per step lets a `docker context use` mid-run
+ * point one step at one daemon and the next at another. Either way the context must resolve to a
+ * local Unix socket, so a remote daemon is refused however it was named.
+ */
+export declare function selectLocalDockerDaemon(env: Readonly<Record<string, string | undefined>>, timeoutMs: number, execute: Executor, use: DaemonUse): Promise<LocalDockerDaemon>;
+export {};

package/dist/environment/docker-daemon.js

@@ -0,0 +1,78 @@
+/**
+ * Names the one local Docker daemon a command addresses, before the command does any work, so
+ * `down`, `reset` and `runtime measure` choose a daemon by one rule. It observes Docker's own
+ * context configuration through the supplied `execute`; it never spawns a process itself.
+ */
+import { authenticatedExecutionOutcome } from '../environment-exec/execute.js';
+import { ENVIRONMENT_CODES } from './contract.js';
+import { admitLocalDockerEndpoint } from './docker-endpoint.js';
+import { resolveDockerExecutable } from './executable.js';
+const DOCKER_CONTEXT_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/;
+async function readContext(execute, executable, env, timeoutMs, id, args) {
+    const step = {
+        id,
+        argv: [executable.canonicalPath, ...args],
+        argv0: executable.invocationPath,
+        // The context lookup reads only Docker's client configuration, and the config's own
+        // directory may not exist yet; a missing config is reported by the command, not here.
+        cwd: '/', env, timeoutMs,
+        stdoutLimitBytes: 1_024, stderrLimitBytes: 4_096,
+        paths: [], ports: [],
+        labels: { purpose: id },
+        expected: [],
+        consumedFiles: [{
+                path: executable.canonicalPath, sha256: executable.sha256,
+                maxBytes: 536_870_912, argvIndexes: [0], executable: true,
+                executionMode: executable.executionMode,
+            }],
+        filesystemChecks: [],
+        compensation: [],
+    };
+    const outcome = authenticatedExecutionOutcome(await execute(step), step);
+    if (outcome?.kind !== 'complete' || outcome.stderr.byteLength !== 0)
+        return undefined;
+    const text = outcome.stdout.toString('utf8');
+    // Docker's final line ending is framing; trimming more would rewrite the endpoint's identity.
+    return Buffer.from(text, 'utf8').equals(outcome.stdout) ? text.replace(/\r?\n$/, '') : undefined;
+}
+/**
+ * A local DOCKER_HOST is taken as given, through Docker's `default` context. Otherwise the context
+ * is the one DOCKER_CONTEXT names or, with neither set, the active one, read once here so the
+ * caller can pin it for every later step: reading it per step lets a `docker context use` mid-run
+ * point one step at one daemon and the next at another. Either way the context must resolve to a
+ * local Unix socket, so a remote daemon is refused however it was named.
+ */
+export async function selectLocalDockerDaemon(env, timeoutMs, execute, use) {
+    const refuse = (code, message, target) => ({
+        kind: 'refusal', diagnostic: { severity: 'error', code, message, target },
+    });
+    if (env.DOCKER_HOST !== undefined) {
+        return admitLocalDockerEndpoint(env.DOCKER_HOST) === undefined
+            ? refuse('CLI_USAGE_INVALID', `DOCKER_HOST is not a local Docker endpoint, and ${use.localOnly}; fix: unset DOCKER_HOST to use the active Docker context, or set DOCKER_HOST to a local Unix socket`, 'DOCKER_HOST')
+            : { kind: 'complete', dockerContext: 'default', endpoint: env.DOCKER_HOST, source: 'DOCKER_HOST' };
+    }
+    const named = env.DOCKER_CONTEXT;
+    if (named !== undefined && !DOCKER_CONTEXT_NAME.test(named)) {
+        return refuse('CLI_USAGE_INVALID', `DOCKER_CONTEXT ${JSON.stringify(named.slice(0, 128))} is not a Docker context name; fix: set it to a local context from \`docker context ls\`, or unset it to use the active context`, 'DOCKER_CONTEXT');
+    }
+    const executable = await resolveDockerExecutable(env);
+    if (executable.state !== 'available')
+        return refuse(ENVIRONMENT_CODES.RUNTIME_UNAVAILABLE, executable.reason, 'docker');
+    // Only the search path: Docker then reads the operator's own context store, as `up` does.
+    const stepEnv = { ...(env.PATH === undefined ? {} : { PATH: env.PATH }) };
+    const context = named ?? await readContext(execute, executable.value, stepEnv, timeoutMs, 'runtime:daemon:context', ['context', 'show']);
+    if (context === undefined || !DOCKER_CONTEXT_NAME.test(context)) {
+        return refuse(ENVIRONMENT_CODES.RUNTIME_UNAVAILABLE, `${use.command} could not read the active Docker context from \`docker context show\`; fix: run \`docker context show\` to see why, or set DOCKER_CONTEXT to the local context to use`, 'docker context');
+    }
+    const which = named === undefined ? `active Docker context ${context}` : `Docker context ${context} named by DOCKER_CONTEXT`;
+    const target = `docker context ${context}`;
+    const endpoint = await readContext(execute, executable.value, stepEnv, timeoutMs, 'runtime:daemon:endpoint', ['context', 'inspect', context, '--format', '{{.Endpoints.docker.Host}}']);
+    if (endpoint === undefined) {
+        return refuse(ENVIRONMENT_CODES.RUNTIME_UNAVAILABLE, `${use.command} could not read the endpoint of the ${which}; fix: run \`docker context inspect ${context}\` to see why`, target);
+    }
+    if (admitLocalDockerEndpoint(endpoint) === undefined) {
+        const select = named === undefined ? 'select a local context with `docker context use <name>`' : 'set DOCKER_CONTEXT to a local context, or unset it';
+        return refuse(ENVIRONMENT_CODES.RUNTIME_UNAVAILABLE, `the ${which} points at ${endpoint}, not a local Unix socket, and ${use.localOnly}; fix: ${select}, then retry`, target);
+    }
+    return { kind: 'complete', dockerContext: context, endpoint, source: target };
+}

package/dist/environment/docker-endpoint.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Classifies local Docker transports without rewriting endpoint identity. Context observation and
+ * execution authentication remain with the runtime owners; syntax alone grants neither.
+ */
+export declare function parseLocalDockerEndpoint(value: unknown): Readonly<{
+    transport: 'unix';
+    endpoint: string;
+}> | undefined;
+/** Admits transport syntax for this process without granting native execution or state authority. */
+export declare function admitLocalDockerEndpoint(value: unknown): ReturnType<typeof parseLocalDockerEndpoint>;

package/dist/environment/docker-endpoint.js

@@ -0,0 +1,19 @@
+/**
+ * Classifies local Docker transports without rewriting endpoint identity. Context observation and
+ * execution authentication remain with the runtime owners; syntax alone grants neither.
+ */
+export function parseLocalDockerEndpoint(value) {
+    // Docker trims host input. Reject that alias rather than bind authority to a different string.
+    if (typeof value !== 'string' || value.trim() !== value || /[\u0000-\u001f\u007f]/.test(value))
+        return undefined;
+    if (!value.startsWith('unix://'))
+        return undefined;
+    const path = value.slice('unix://'.length);
+    // Docker passes this raw pathname to the socket transport: spaces and URI punctuation are literal.
+    return path.startsWith('/') && !path.startsWith('//') && path.length > 1
+        ? { transport: 'unix', endpoint: value } : undefined;
+}
+/** Admits transport syntax for this process without granting native execution or state authority. */
+export function admitLocalDockerEndpoint(value) {
+    return process.platform === 'darwin' || process.platform === 'linux' ? parseLocalDockerEndpoint(value) : undefined;
+}

package/dist/environment/env-schema-observation.d.ts

@@ -0,0 +1,46 @@
+import { type ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import { type EnvironmentObservation, type ExecutionStep, type JsonSnapshot, type StackId } from './contract.js';
+export declare const VARLOCK_INSTALL_URL = "https://varlock.dev";
+export declare const observationDeclarations: readonly [{
+    readonly id: 'env-schema';
+    readonly owner: "env-schema-observation";
+    readonly postures: readonly ["environment"];
+    readonly stages: readonly [{
+        readonly stage: 'bootstrap';
+        readonly disposition: 'required';
+    }, {
+        readonly stage: 'steady';
+        readonly disposition: 'required';
+    }];
+    readonly code: "ENV_SCHEMA_UNHEALTHY";
+    readonly isIssued: typeof isEnvSchemaObservation;
+    readonly issuedAt: typeof observationIssuedAt;
+}];
+declare function isEnvSchemaObservation(value: unknown): value is EnvironmentObservation;
+declare function observationIssuedAt(value: unknown): number | undefined;
+export interface EnvSchemaSibling {
+    readonly slug: string;
+    /** Directory as declared in cockpit.toml; only used to tell the operator where to run varlock. */
+    readonly dir: string;
+    readonly root: string;
+}
+/**
+ * Observes every sibling that contains `.env.schema`. Returns one aggregate observation per
+ * stack, with the per-sibling status in its measured value. `env` is the caller's environment:
+ * a secret provider may need its own variables to resolve.
+ */
+export declare function observeEnvSchemas(input: {
+    readonly stackId: StackId;
+    readonly siblings: readonly EnvSchemaSibling[];
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly timeoutMs: number;
+}, options: {
+    readonly execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+}): Promise<readonly EnvironmentObservation[]>;
+/** Siblings whose schema was skipped because varlock is not installed, from a passing row. */
+export declare function envSchemaToolMissing(check: {
+    readonly owner: string;
+    readonly verdict: string;
+    readonly measured?: JsonSnapshot;
+}): readonly string[];
+export {};