@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment/application/lifecycle-context.d.ts

@@ -0,0 +1,235 @@
+import type { ExecuteProbeOutcome, ForegroundProcessInput, ForegroundProcessOutcome } from '../../environment-exec/execute.js';
+import { type CheckoutId, type EnvironmentCommandOutcome, type EnvironmentDiagnostic, type EnvironmentObservation, type ExecutionStep, type HolderId, type SourceProvenance, type StackId } from '../contract.js';
+import type { ExecutableResolution } from '../executable.js';
+import { CockpitConfig, type EntrypointDerivative } from '../../schema.js';
+import { type StateNamespace } from '../state.js';
+import type { RuntimeInputs, LifecycleStageProjection } from '../lifecycle-stage.js';
+import { type ConsumedSetupCheckoutObservation, type SetupCheckoutProjection } from '../setup-observation.js';
+import { type LoadedConfigProjection } from '../../config/load.js';
+import { type RegistryDerivationResult } from '../../registry-derivation.js';
+import type { LeasePortFamilyResult, PortFamilyConfig, PortLeaseProjection } from '../ports.js';
+import type { RuntimeLifecycleProjection, RuntimeTopologyEvidence } from '../runtime.js';
+import type { PlanResetInput, PlanTeardownInput, ResetTargetInput } from '../reclaim.js';
+import { type SelectDestructiveInstanceInput } from '../instance.js';
+export interface UpCommandInput {
+    readonly configPath: string;
+}
+export interface SleepCommandInput {
+    readonly configPath: string;
+}
+export interface SessionCommandInput {
+    readonly configPath: string;
+    readonly argv: readonly [string, ...string[]];
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+}
+export interface LifecycleRunContext {
+    readonly configPath: string;
+    readonly source: SourceProvenance;
+    /** Identifies the stack: its ownership labels, generation, saved progress and data history. */
+    readonly runtimeSha256: string;
+    readonly namespace: StateNamespace;
+    readonly cockpitId: ConsumedSetupCheckoutObservation['cockpitId'];
+    readonly checkoutId: CheckoutId;
+    readonly stackId: StackId;
+    readonly holderId: HolderId;
+    readonly ports: PortFamilyConfig;
+    readonly entrypointDerivatives: readonly EntrypointDerivative[];
+}
+export interface LifecycleRunContextInput {
+    readonly configPath: string;
+    readonly checkout: SetupCheckoutProjection;
+    readonly configuration: LoadedConfigProjection;
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly holderId: HolderId;
+    readonly sessionId: string;
+}
+export interface RuntimeReadiness {
+    readonly topology: RuntimeTopologyEvidence;
+    readonly lifecycle: RuntimeLifecycleProjection;
+    readonly hostObservations: readonly EnvironmentObservation[];
+    readonly runtimeObservations: readonly EnvironmentObservation[];
+    /** The digest of each file this runtime is started from, by the name a person edits. */
+    readonly inputs: RuntimeInputs;
+    /** The Compose profiles this runtime activates, sorted. */
+    readonly activeProfiles: readonly string[];
+}
+export interface AcquiredPorts {
+    readonly leaseResult: LeasePortFamilyResult;
+    readonly projection: PortLeaseProjection;
+    readonly retainOnFailure: () => void;
+}
+export type ReadinessRefusal<T> = (diagnostics: readonly EnvironmentDiagnostic[]) => T;
+export type RuntimeReadinessPurpose = 'teardown';
+interface LifecycleCommandAdapters {
+    load(input: UpCommandInput | SleepCommandInput): Promise<EnvironmentCommandOutcome<LifecycleRunContext>>;
+    execute(step: ExecutionStep): Promise<ExecuteProbeOutcome>;
+    withRuntimeReadiness<T>(context: LifecycleRunContext, use: (runtime: RuntimeReadiness) => Promise<T>, ports?: PortLeaseProjection, refuse?: ReadinessRefusal<T>, purpose?: RuntimeReadinessPurpose): Promise<T | undefined>;
+}
+type SeedOutcome = Readonly<{
+    kind: 'none' | 'current' | 'ran';
+}> | Readonly<{
+    kind: 'refusal';
+    diagnostics: readonly EnvironmentDiagnostic[];
+}>;
+export interface UpCommandAdapters extends LifecycleCommandAdapters {
+    /** Runs environment.seed once the stack is healthy, when a resettable volume is newer than the last seed. */
+    seed?(context: LifecycleRunContext, up: Extract<UpCommandResult, {
+        kind: 'complete';
+    }>['result']): Promise<SeedOutcome>;
+    /**
+     * Records the siblings' lockfiles and rebuild inputs the stack runs on; warnings when it cannot.
+     * A resumed stack keeps the record of its start, because resuming restarts nothing.
+     */
+    recordStackInputs?(context: LifecycleRunContext, change: 'started' | 'resumed' | 'unchanged'): Promise<readonly EnvironmentDiagnostic[]>;
+    withLifecycleStage<T>(context: LifecycleRunContext, use: (stage: LifecycleStageProjection) => Promise<T>, refuse?: ReadinessRefusal<T>): Promise<T | undefined>;
+    withAcquiredPorts<T>(context: LifecycleRunContext, use: (ports: AcquiredPorts) => Promise<T>, refuse?: ReadinessRefusal<T>): Promise<T | undefined>;
+}
+export interface SleepCommandAdapters extends LifecycleCommandAdapters {
+}
+export interface SessionCommandAdapters {
+    up(input: UpCommandInput): Promise<UpCommandResult>;
+    sleep(input: SleepCommandInput): Promise<SleepCommandResult>;
+    resolveExecutable(name: string, env: Readonly<Record<string, string>>): Promise<ExecutableResolution>;
+    executeForeground(input: ForegroundProcessInput, options: {
+        signal?: AbortSignal;
+    }): Promise<ForegroundProcessOutcome>;
+    readonly signal?: AbortSignal;
+}
+export interface DownCommandInput {
+    readonly configPath: string;
+}
+export interface ResetCommandInput {
+    readonly configPath: string;
+}
+export interface DestructiveRunContext extends LifecycleRunContext {
+    readonly instance: SelectDestructiveInstanceInput;
+}
+export interface DestructiveObservation {
+    readonly instance: SelectDestructiveInstanceInput;
+    readonly runtime: RuntimeLifecycleProjection;
+    readonly ports: PortLeaseProjection;
+    readonly down: Omit<PlanTeardownInput, 'expectedDiscoveryDigest' | 'consent' | 'continuation' | 'recoveredReservation'>;
+    readonly reset: Omit<PlanResetInput, 'confirmationDigest' | 'consent' | 'continuation' | 'recoveredReservation'>;
+}
+/** The evidence a step of an already-reserved drain re-reads: no runtime readiness, no ports. */
+export type DestructiveReclaimObservation = Pick<DestructiveObservation, 'instance' | 'down' | 'reset'>;
+export interface DestructiveCommandAdapters {
+    load(input: DownCommandInput | ResetCommandInput): Promise<EnvironmentCommandOutcome<DestructiveRunContext>>;
+    observe(context: DestructiveRunContext): Promise<DestructiveObservation | DestructiveObservationRefusal | undefined>;
+    /** Reclaim evidence only, after `observe` measured the runtime for the same context. */
+    observeReclaim?(context: DestructiveRunContext): Promise<DestructiveReclaimObservation | DestructiveObservationRefusal | undefined>;
+    execute(step: ExecutionStep): Promise<ExecuteProbeOutcome>;
+}
+export type DestructiveObservationRefusal = Extract<EnvironmentCommandOutcome<never>, {
+    kind: 'refusal';
+}>;
+export interface DownCommandAdapters extends DestructiveCommandAdapters {
+}
+export interface ResetCommandAdapters extends DestructiveCommandAdapters {
+}
+export type DownCommandResult = EnvironmentCommandOutcome<Readonly<{
+    stackId: StackId;
+    change: 'removed' | 'unchanged';
+}>>;
+interface ResetPreviewResult {
+    readonly stackId: StackId;
+    readonly planDigest: string;
+    readonly targets: readonly ResetTargetInput[];
+    readonly noop: boolean;
+}
+export type ResetCommandResult = Readonly<{
+    kind: 'preview';
+    status: 0;
+    diagnostics: readonly EnvironmentDiagnostic[];
+    result: ResetPreviewResult;
+}> | Readonly<{
+    kind: 'refusal';
+    status: 2;
+    diagnostics: readonly EnvironmentDiagnostic[];
+    result: null;
+}>;
+export type OperatorResetResult = EnvironmentCommandOutcome<Readonly<{
+    stackId: StackId;
+    change: 'reset' | 'unchanged';
+    /** On `reset`: what the approved plan removed, as its preview listed them. */
+    targets?: readonly ResetTargetInput[];
+}>>;
+export interface OperatorResetSession {
+    readonly preview: Extract<ResetCommandResult, {
+        kind: 'preview';
+    }>;
+    decide(decision: 'approve' | 'decline'): Promise<OperatorResetResult>;
+}
+interface DestructiveRunContextInput {
+    readonly lifecycle: LifecycleRunContext;
+    readonly instance: SelectDestructiveInstanceInput;
+    /** The holder claim the load took on a stack no session held, so this run could read it. */
+    readonly claim?: LeasePortFamilyResult;
+}
+export type UpCommandResult = EnvironmentCommandOutcome<Readonly<{
+    stackId: StackId;
+    change: 'started' | 'resumed' | 'unchanged';
+    /** Each `[ports.bases]` name with its leased port, the values the stack's Compose files read. */
+    ports: PortLeaseProjection['lease']['ports'];
+    entrypoints: PortLeaseProjection['entrypoints'];
+    coldStart?: Readonly<{
+        measuredMillis: number;
+        limitMillis: number;
+        headroomMillis: number;
+    }>;
+    /** Present when environment.seed is declared: whether this up ran it or found the data current. */
+    seed?: 'ran' | 'current';
+}>>;
+export type SleepCommandResult = EnvironmentCommandOutcome<Readonly<{
+    stackId: StackId;
+    change: 'retained' | 'released' | 'stopped' | 'unchanged';
+}>>;
+export type SessionCommandResult = Readonly<{
+    kind: 'complete';
+    status: number;
+    diagnostics: readonly EnvironmentDiagnostic[];
+    result: Readonly<{
+        child: Readonly<{
+            exitCode: number;
+            signal: NodeJS.Signals | null;
+        }>;
+        sleep: Extract<SleepCommandResult, {
+            kind: 'complete';
+        }>['result'];
+    }>;
+}> | Readonly<{
+    kind: 'refusal';
+    status: number;
+    diagnostics: readonly EnvironmentDiagnostic[];
+    result: null;
+}>;
+export declare const issuedLifecycleRuns: WeakSet<object>;
+export declare function noticeLifecycleRun(context: LifecycleRunContext, diagnostic: EnvironmentDiagnostic): void;
+export declare function withLifecycleRunNotices<Result extends {
+    readonly diagnostics: readonly EnvironmentDiagnostic[];
+}>(context: LifecycleRunContext, result: Result): Result;
+export declare const issuedDestructiveRuns: WeakSet<object>;
+export declare const provisionalClaims: WeakMap<DestructiveRunContext, LeasePortFamilyResult>;
+type EffectiveConfigurationResult = Readonly<{
+    kind: 'complete';
+    source: SourceProvenance;
+    runtimeSha256: string;
+    config: CockpitConfig;
+}> | Readonly<{
+    kind: 'unavailable';
+}> | Extract<RegistryDerivationResult, {
+    kind: 'refusal';
+}>;
+export declare function consumeEffectiveConfiguration(configuration: LoadedConfigProjection): EffectiveConfigurationResult;
+export declare function registryRefusalMessage(result: Extract<EffectiveConfigurationResult, {
+    kind: 'refusal';
+}>): string;
+export declare function issueDestructiveRunContext(input: DestructiveRunContextInput): EnvironmentCommandOutcome<DestructiveRunContext>;
+export declare function issueLifecycleRunContext(input: LifecycleRunContextInput): EnvironmentCommandOutcome<LifecycleRunContext>;
+export declare function withLifecycleConfiguration<T>(context: LifecycleRunContext, use: (configuration: LoadedConfigProjection) => Promise<T>): Promise<T | undefined>;
+export declare function lifecycleContextRefusal(message?: string): Extract<EnvironmentCommandOutcome<LifecycleRunContext>, {
+    kind: 'refusal';
+}>;
+export {};

package/dist/environment/application/lifecycle-context.js

@@ -0,0 +1,154 @@
+import { dirname, resolve } from 'node:path';
+import { ENVIRONMENT_CODES, errorCause, } from '../contract.js';
+import { CockpitConfig } from '../../schema.js';
+import { authenticateStateNamespace } from '../state.js';
+import { holderId as deriveHolderId, stackId as deriveStackId } from '../identity.js';
+import { consumeSetupCheckoutProjection } from '../setup-observation.js';
+import { loadCockpitConfig, consumeLoadedConfigProjection } from '../../config/load.js';
+import { deriveRegistry } from '../../registry-derivation.js';
+import { selectDestructiveInstance } from '../instance.js';
+import { ownerDiagnostic, sameSource } from './shared.js';
+export const issuedLifecycleRuns = new WeakSet();
+// Warnings an owner raised while a run held its context, such as an interrupted restore released
+// with its data possibly half applied. The command's result carries them whatever its outcome:
+// dropping one left a person working on partial data with nobody told.
+const lifecycleRunNotices = new WeakMap();
+export function noticeLifecycleRun(context, diagnostic) {
+    const notices = lifecycleRunNotices.get(context) ?? [];
+    notices.push({ ...diagnostic });
+    lifecycleRunNotices.set(context, notices);
+}
+export function withLifecycleRunNotices(context, result) {
+    const notices = lifecycleRunNotices.get(context);
+    lifecycleRunNotices.delete(context);
+    return notices ? { ...result, diagnostics: [...result.diagnostics, ...notices] } : result;
+}
+const lifecycleConfigurationSources = new WeakMap();
+export const issuedDestructiveRuns = new WeakSet();
+export const provisionalClaims = new WeakMap();
+export function consumeEffectiveConfiguration(configuration) {
+    const loaded = consumeLoadedConfigProjection(configuration);
+    if (!loaded)
+        return { kind: 'unavailable' };
+    const derived = deriveRegistry(loaded.config);
+    return derived.kind === 'complete'
+        ? { kind: 'complete', source: loaded.source, runtimeSha256: loaded.runtimeSha256, config: derived.result.config }
+        : derived;
+}
+export function registryRefusalMessage(result) {
+    return `effective registry refused (${result.code}): ${result.message}`;
+}
+export function issueDestructiveRunContext(input) {
+    try {
+        if (!input || typeof input !== 'object' || Array.isArray(input))
+            return lifecycleContextRefusal();
+        const descriptors = Object.getOwnPropertyDescriptors(input);
+        if (Reflect.ownKeys(descriptors).length !== (descriptors.claim ? 3 : 2)
+            || !('value' in descriptors.lifecycle) || !('value' in descriptors.instance)
+            || descriptors.claim && !('value' in descriptors.claim))
+            return lifecycleContextRefusal();
+        const lifecycle = descriptors.lifecycle.value;
+        const instance = descriptors.instance.value;
+        const claim = descriptors.claim?.value;
+        const namespace = authenticateStateNamespace(lifecycle?.namespace);
+        const selected = selectDestructiveInstance(instance);
+        if (!namespace || selected.kind !== 'selected' || selected.stackId !== lifecycle.stackId
+            || selected.checkoutId !== lifecycle.checkoutId || lifecycle.configPath !== resolve(lifecycle.configPath)) {
+            return lifecycleContextRefusal();
+        }
+        const context = { ...lifecycle, namespace, instance };
+        issuedDestructiveRuns.add(context);
+        if (claim)
+            provisionalClaims.set(context, claim);
+        return { kind: 'complete', status: 0, diagnostics: [], result: context };
+    }
+    catch (error) {
+        return lifecycleContextRefusal(`destructive run authority could not be read: ${errorCause(error)}`);
+    }
+}
+export function issueLifecycleRunContext(input) {
+    try {
+        if (!input || typeof input !== 'object' || Array.isArray(input))
+            return lifecycleContextRefusal();
+        const descriptors = Object.getOwnPropertyDescriptors(input);
+        const keys = ['checkout', 'configPath', 'configuration', 'namespace', 'stackId', 'holderId', 'sessionId'];
+        if (Reflect.ownKeys(descriptors).length !== keys.length
+            || keys.some((key) => !descriptors[key] || !('value' in descriptors[key])))
+            return lifecycleContextRefusal();
+        const checkout = consumeSetupCheckoutProjection(descriptors.checkout.value);
+        const requestedConfigPath = descriptors.configPath.value;
+        const loaded = consumeEffectiveConfiguration(descriptors.configuration.value);
+        const namespace = authenticateStateNamespace(descriptors.namespace.value);
+        const stackId = descriptors.stackId.value;
+        const holderId = descriptors.holderId.value;
+        const sessionId = descriptors.sessionId.value;
+        if (loaded.kind === 'refusal')
+            return lifecycleContextRefusal(registryRefusalMessage(loaded));
+        if (!checkout || loaded.kind !== 'complete' || !namespace || typeof requestedConfigPath !== 'string' || requestedConfigPath.length === 0
+            || requestedConfigPath.includes('\0') || resolve(requestedConfigPath) !== loaded.source.path
+            || typeof sessionId !== 'string'
+            || !sameSource(checkout.source, loaded.source)
+            || loaded.config.cockpit.name !== checkout.cockpitName)
+            return lifecycleContextRefusal();
+        const expectedStackId = deriveStackId({
+            cockpitId: checkout.cockpitId,
+            checkoutId: checkout.checkoutId,
+            variant: { kind: 'shared' },
+        });
+        const expectedHolderId = deriveHolderId({
+            stackId: expectedStackId,
+            checkoutId: checkout.checkoutId,
+            sessionId,
+        });
+        if (stackId !== expectedStackId || holderId !== expectedHolderId
+            || namespace.paths.lifecycle(expectedStackId).cockpitId !== checkout.cockpitId) {
+            return lifecycleContextRefusal();
+        }
+        const context = {
+            configPath: resolve(requestedConfigPath),
+            source: { ...loaded.source },
+            runtimeSha256: loaded.runtimeSha256,
+            namespace,
+            cockpitId: checkout.cockpitId,
+            checkoutId: checkout.checkoutId,
+            stackId: expectedStackId,
+            holderId: expectedHolderId,
+            ports: {
+                step: loaded.config.ports.step,
+                count: loaded.config.ports.count,
+                bases: { ...loaded.config.ports.bases },
+            },
+            entrypointDerivatives: loaded.config.environment.entrypoint_derivatives.map((value) => ({ ...value })),
+        };
+        issuedLifecycleRuns.add(context);
+        lifecycleConfigurationSources.set(context, Object.freeze({ source: context.source,
+            siblingsRoot: resolve(dirname(loaded.source.path), loaded.config.cockpit.siblings_root) }));
+        return { kind: 'complete', status: 0, diagnostics: [], result: context };
+    }
+    catch (error) {
+        return lifecycleContextRefusal(`lifecycle run authority could not be read: ${errorCause(error)}`);
+    }
+}
+export async function withLifecycleConfiguration(context, use) {
+    if (!context || typeof context !== 'object')
+        return undefined;
+    const expected = lifecycleConfigurationSources.get(context);
+    if (!expected)
+        return undefined;
+    // Each leaf consumes its own loader-issued handle; a copied parsed config has no authority.
+    const loaded = await loadCockpitConfig(expected.source.path);
+    if (loaded.kind !== 'complete' || !sameSource(expected.source, loaded.result.source))
+        return undefined;
+    try {
+        return await use(loaded.result);
+    }
+    finally {
+        consumeLoadedConfigProjection(loaded.result);
+    }
+}
+export function lifecycleContextRefusal(message = 'lifecycle run authority is unavailable or does not match the loaded configuration') {
+    return {
+        kind: 'refusal', status: 2, result: null,
+        diagnostics: [ownerDiagnostic(ENVIRONMENT_CODES.LIFECYCLE_EVIDENCE_INVALID, message, 'lifecycle')],
+    };
+}

package/dist/environment/application/lifecycle-state.d.ts

@@ -0,0 +1,25 @@
+import { type EnvironmentDiagnostic, type ExecutionFence, type HolderId } from '../contract.js';
+import { type StateRecord, type StateResult, type SkippedStateNamespace } from '../state.js';
+import { type CurrentLifecycleRecord, type LifecycleRecordValue } from '../lifecycle-stage.js';
+import { type PortLeaseProjection } from '../ports.js';
+import { type DrainOutcome } from '../claims.js';
+import { type LifecycleRunContext, type SleepCommandResult, type UpCommandResult } from './lifecycle-context.js';
+export declare function lifecycleSuggestion(context: LifecycleRunContext, command: 'up' | 'down'): string;
+export declare function readLifecycleRecord(context: LifecycleRunContext): Promise<CurrentLifecycleRecord | null | UpCommandResult>;
+export declare function publishLifecycleRecord(context: LifecycleRunContext, expected: StateRecord | null, value: LifecycleRecordValue, transfer?: Readonly<{
+    readonly previousHolderId: HolderId;
+    readonly projection: PortLeaseProjection;
+}>, rebind?: PortLeaseProjection): Promise<StateResult<StateRecord> | UpCommandResult>;
+export declare function unreadableStateWarning(skipped: readonly SkippedStateNamespace[]): EnvironmentDiagnostic | undefined;
+export declare function unheldStack(context: LifecycleRunContext): Promise<SleepCommandResult | undefined>;
+export declare function repairRequired(context: LifecycleRunContext): Extract<SleepCommandResult, {
+    kind: 'refusal';
+}>;
+export declare function invalidateCompletedLifecycle(context: LifecycleRunContext, workBasisSha256: string, operationGeneration: string, purpose: 'sleep' | 'down'): Promise<Extract<SleepCommandResult, {
+    kind: 'refusal';
+}> | undefined>;
+export declare function publishDrainOutcomeRecord(context: LifecycleRunContext, outcome: DrainOutcome): Promise<Extract<SleepCommandResult, {
+    kind: 'refusal';
+}> | undefined>;
+export declare function publishDrainOutcome(context: LifecycleRunContext, outcome: DrainOutcome, fence: ExecutionFence): Promise<SleepCommandResult | undefined>;
+export declare function exactCommandConfigPath(input: unknown): string | undefined;

package/dist/environment/application/lifecycle-state.js

@@ -0,0 +1,202 @@
+import { dirname, join, resolve } from 'node:path';
+import { cleanupFencedExecution } from '../../environment-exec/execute.js';
+import { ENVIRONMENT_CODES, snapshotJson, forwardedRefusal, } from '../contract.js';
+import { cockpitCommand } from '../../fix-catalogue.js';
+import { abortStateTransaction, readState, transactState } from '../state.js';
+import { decodeLifecycleRecord, resolveLifecycleStage } from '../lifecycle-stage.js';
+import { inspectPortLeaseTransfer, revalidatePortLeaseProjection } from '../ports.js';
+import { commitDrainOutcome, decodeCoordinationRecord } from '../claims.js';
+import { lifecycleRefusal, ownerDiagnostic } from './shared.js';
+import { withLifecycleConfiguration } from './lifecycle-context.js';
+export function lifecycleSuggestion(context, command) {
+    return cockpitCommand(command, { config: context.source.path });
+}
+export async function readLifecycleRecord(context) {
+    const address = context.namespace.paths.lifecycle(context.stackId);
+    const result = await readState(address);
+    if (result.kind === 'missing') {
+        const stage = await resolveLifecycleStage({
+            namespace: context.namespace, stackId: context.stackId, observedAt: new Date().toISOString(),
+        });
+        if (stage.kind !== 'complete')
+            return forwardedRefusal(stage.diagnostics);
+        return stage.authority.stage === 'steady'
+            ? lifecycleRefusal(ENVIRONMENT_CODES.LIFECYCLE_PROGRESS_INVALID, 'seeded lifecycle history requires persisted progress', address.path)
+            : null;
+    }
+    if (result.kind !== 'complete') {
+        return lifecycleRefusal(result.code, result.message, result.target);
+    }
+    return decodeLifecycleRecord(result.value, context) ?? lifecycleRefusal(ENVIRONMENT_CODES.STATE_RECORD_MALFORMED, 'lifecycle progress record is malformed', address.path);
+}
+function lifecycleStateRecord(context, current, value, updatedAt) {
+    return {
+        format: 'cockpit-state/v1',
+        kind: 'lifecycle',
+        cockpitId: context.cockpitId,
+        subjectId: context.stackId,
+        revision: current === null ? 0 : current.revision + 1,
+        updatedAt,
+        value: snapshotJson(value),
+    };
+}
+export async function publishLifecycleRecord(context, expected, value, transfer, rebind) {
+    const address = context.namespace.paths.lifecycle(context.stackId);
+    const expectedBytes = JSON.stringify(expected);
+    const result = await transactState(context.namespace, address, { ownerId: context.holderId }, async (current) => {
+        if (JSON.stringify(current) !== expectedBytes)
+            return abortStateTransaction(lifecycleRefusal(ENVIRONMENT_CODES.LIFECYCLE_PROGRESS_INVALID, 'lifecycle progress changed during execution', address.path));
+        if (transfer) {
+            const ownership = await inspectPortLeaseTransfer({
+                namespace: context.namespace,
+                stackId: context.stackId,
+                holderId: context.holderId,
+                checkoutId: context.checkoutId,
+                previousHolderId: transfer.previousHolderId,
+                projection: transfer.projection,
+            });
+            if (ownership.kind === 'refusal')
+                return abortStateTransaction({
+                    kind: 'refusal',
+                    status: 2,
+                    result: null,
+                    diagnostics: ownership.diagnostics.map((diagnostic) => diagnostic.code === ENVIRONMENT_CODES.CLAIM_CO_TENANT
+                        ? ownerDiagnostic(diagnostic.code, `lifecycle progress belongs to another active session; run \`${lifecycleSuggestion(context, 'up')}\` to resume it or \`${lifecycleSuggestion(context, 'down')}\` to release it`, diagnostic.target ?? context.stackId)
+                        : diagnostic),
+                });
+        }
+        if (rebind && (!await withLifecycleConfiguration(context, async () => true)
+            || !await revalidatePortLeaseProjection({ projection: rebind, namespace: context.namespace }))) {
+            return abortStateTransaction(lifecycleRefusal(ENVIRONMENT_CODES.EXECUTION_PRECONDITION_CHANGED, `configuration or sole-holder lease changed before generated lifecycle refresh; rerun \`${lifecycleSuggestion(context, 'up')}\``, context.stackId, 'rerun npx --no cockpit up --config <your cockpit.toml> once nothing else is changing cockpit.toml or bringing the stack up'));
+        }
+        return lifecycleStateRecord(context, current, value, new Date().toISOString());
+    });
+    if ('aborted' in result)
+        return result.value;
+    if (result.kind === 'complete' || result.kind === 'indeterminate')
+        return result;
+    return result.kind === 'missing'
+        ? lifecycleRefusal(ENVIRONMENT_CODES.STATE_RECORD_MALFORMED, 'lifecycle progress publication returned no record', result.path)
+        : lifecycleRefusal(result.code, result.message, result.target);
+}
+// Port leases are machine-wide, so up reads every cockpit's state. Another cockpit's namespace this
+// version cannot read is skipped there rather than refused; this cockpit's own unreadable state still
+// refuses in the command itself. The skipped ones are named in a single warning with one cleanup
+// command (`stacks prune`), and only by doctor: the folders belong to other cockpits, usually ones an earlier version
+// left behind, and repeating them on every up (and so every session) buried each result under lines
+// about cockpits the person was not working on. A port they still hold fails up on its own.
+export function unreadableStateWarning(skipped) {
+    if (skipped.length === 0)
+        return undefined;
+    const directory = dirname(skipped[0].path);
+    const reasons = [...new Set(skipped.map(({ reason }) => reason))].join('; ');
+    const count = skipped.length === 1 ? '1 state folder of another cockpit' : `${skipped.length} state folders of other cockpits`;
+    return {
+        severity: 'warning',
+        code: ENVIRONMENT_CODES.STATE_RECORD_MALFORMED,
+        message: `${count} under ${directory} cannot be read by this cockpit version (${reasons}), so their claims and port leases were ignored`,
+        target: directory,
+        fix: `preview their removal with ${cockpitCommand('stacks prune')}, which removes those an earlier cockpit build left once none of their stacks is kept, then apply it with --apply`,
+    };
+}
+// `up` keeps a holder whenever containers may exist, so a stack no session holds has nothing running.
+// Sleep then has nothing to stop; refusing with a co-tenant error sent people looking for a session
+// that did not exist, after an `up` that never started anything or a second `sleep`.
+export async function unheldStack(context) {
+    const stored = await readState(context.namespace.paths.coordination(context.stackId));
+    if (stored.kind !== 'complete')
+        return undefined;
+    const coordination = decodeCoordinationRecord(stored.value, context.stackId);
+    if (!coordination || coordination.holders.length > 0)
+        return undefined;
+    const reserved = coordination.lease !== null && !coordination.lease.released;
+    return {
+        kind: 'complete', status: 0,
+        diagnostics: [{
+                severity: 'warning', code: ENVIRONMENT_CODES.STACK_NOT_RUNNING, target: context.stackId,
+                message: reserved
+                    ? `no session holds this stack, so nothing is running and sleep has nothing to stop; its port family stays reserved for the next up until \`${lifecycleSuggestion(context, 'down')}\` releases it`
+                    : 'the stack is already asleep: no session holds it and its services are stopped, so sleep has nothing to do',
+            }],
+        result: { stackId: context.stackId, change: 'unchanged' },
+    };
+}
+export function repairRequired(context) {
+    return lifecycleRefusal(ENVIRONMENT_CODES.DRAIN_ATTEMPT_REPAIR_REQUIRED, 'cockpit cannot prove the interrupted sleep executor stopped, so it will not overlap it with another destructive action; preserve the coordination state for explicit repair', context.stackId);
+}
+export async function invalidateCompletedLifecycle(context, workBasisSha256, operationGeneration, purpose) {
+    const current = await readLifecycleRecord(context);
+    if (current !== null && 'kind' in current)
+        return forwardedRefusal(current.diagnostics);
+    const stored = current;
+    // `up` writes the lifecycle record before it starts a service, so without one nothing ever ran
+    // and there is no identity to retire. Writing one here left a record without lifecycle history,
+    // which the next `up` refused as malformed state.
+    if (stored === null)
+        return undefined;
+    if (purpose === 'down' && stored.value.teardownComplete === true
+        && stored.value.holderId === context.holderId && stored.value.workBasisSha256 === workBasisSha256
+        && stored.value.operationGeneration === operationGeneration)
+        return undefined;
+    // Sleep retains containers, so its replay still guards resume. Only a reconciled down
+    // retires that identity, before the final drain publication can release its claim.
+    const value = {
+        holderId: context.holderId,
+        workBasisSha256,
+        operationGeneration,
+        completedServices: [],
+        ...(purpose === 'down' ? { teardownComplete: true } : {
+            ...(stored.value.runtimeInputs ? { runtimeInputs: stored.value.runtimeInputs } : {}),
+            ...(stored.value.activeProfiles ? { activeProfiles: stored.value.activeProfiles } : {}),
+        }),
+    };
+    const publication = await publishLifecycleRecord(context, stored.record, value);
+    if ('status' in publication)
+        return forwardedRefusal(publication.diagnostics);
+    if (publication.kind === 'indeterminate')
+        return lifecycleRefusal(ENVIRONMENT_CODES.STATE_DURABILITY_INDETERMINATE, publication.message, publication.target);
+    if (publication.kind !== 'complete' || !decodeLifecycleRecord(publication.value, context)) {
+        return lifecycleRefusal(ENVIRONMENT_CODES.STATE_RECORD_MALFORMED, 'stopped lifecycle invalidation could not be verified', context.namespace.paths.lifecycle(context.stackId).path);
+    }
+    return undefined;
+}
+export async function publishDrainOutcomeRecord(context, outcome) {
+    const publication = await commitDrainOutcome({
+        outcome,
+        namespace: context.namespace,
+        stackId: context.stackId,
+    });
+    if ('diagnostics' in publication) {
+        return forwardedRefusal(publication.diagnostics);
+    }
+    if (publication.kind === 'indeterminate')
+        return lifecycleRefusal(ENVIRONMENT_CODES.STATE_DURABILITY_INDETERMINATE, publication.message, publication.target);
+    if (publication.kind !== 'complete') {
+        return publication.kind === 'missing'
+            ? lifecycleRefusal(ENVIRONMENT_CODES.STATE_RECORD_MALFORMED, 'drain outcome publication returned no record', publication.path)
+            : lifecycleRefusal(publication.code, publication.message, publication.target);
+    }
+    return undefined;
+}
+export async function publishDrainOutcome(context, outcome, fence) {
+    const published = await publishDrainOutcomeRecord(context, outcome);
+    if (published)
+        return published;
+    return await cleanupFencedExecution(fence) ? undefined : lifecycleRefusal(ENVIRONMENT_CODES.STATE_DURABILITY_INDETERMINATE, 'the drain outcome was published but its durable execution fence could not be removed', fence.markerPath);
+}
+export function exactCommandConfigPath(input) {
+    try {
+        if (!input || typeof input !== 'object' || Array.isArray(input))
+            return undefined;
+        const descriptors = Object.getOwnPropertyDescriptors(input);
+        if (Reflect.ownKeys(descriptors).length !== 1 || !descriptors.configPath || !('value' in descriptors.configPath)
+            || typeof descriptors.configPath.value !== 'string' || descriptors.configPath.value.length === 0
+            || descriptors.configPath.value.includes('\0'))
+            return undefined;
+        return resolve(descriptors.configPath.value);
+    }
+    catch {
+        // A throwing accessor or proxy trap makes the input malformed, which the caller refuses.
+        return undefined;
+    }
+}

package/dist/environment/application/lifecycle.d.ts

@@ -0,0 +1,18 @@
+import { type EnvironmentDiagnostic, type LifecycleProgress } from '../contract.js';
+import { type RuntimeServiceEvidence, type RuntimeServiceFailureEvidence, type RuntimeServiceObservation, type RuntimeTopologyEvidence } from '../runtime.js';
+import { type SessionCommandAdapters, type SessionCommandInput, type SessionCommandResult, type SleepCommandAdapters, type SleepCommandInput, type SleepCommandResult, type UpCommandAdapters, type UpCommandInput, type UpCommandResult } from './lifecycle-context.js';
+export { decodeLifecycleRecord } from '../lifecycle-stage.js';
+type ServiceAdmission = {
+    readonly kind: 'complete';
+    readonly evidence: RuntimeServiceEvidence;
+} | {
+    readonly kind: 'stale';
+} | {
+    readonly kind: 'failure';
+    readonly logs?: RuntimeServiceFailureEvidence | RuntimeServiceObservation;
+};
+export declare function revalidateService(topology: RuntimeTopologyEvidence, completed: LifecycleProgress['completedServices'][number], adapters: Pick<UpCommandAdapters, 'execute'>): Promise<ServiceAdmission>;
+export declare function collectFailureLogs(evidence: RuntimeServiceFailureEvidence | RuntimeServiceObservation | undefined, service: string, adapters: Pick<UpCommandAdapters, 'execute'>): Promise<readonly EnvironmentDiagnostic[]>;
+export declare function runUp(input: UpCommandInput, adapters: UpCommandAdapters): Promise<UpCommandResult>;
+export declare function runSession(input: SessionCommandInput, adapters: SessionCommandAdapters): Promise<SessionCommandResult>;
+export declare function runSleep(input: SleepCommandInput, adapters: SleepCommandAdapters): Promise<SleepCommandResult>;