@b00dea/cockpit 0.0.0-stage → 0.1.0

package/dist/environment/lifecycle-stage.d.ts

@@ -0,0 +1,115 @@
+import { type CheckoutId, type CockpitId, type EnvironmentDiagnostic, type EnvironmentObservation, type HolderId, type LifecycleProgress, type ObservationLifecycleStage, type StackId } from './contract.js';
+import { type StateNamespace, type StateRecord } from './state.js';
+export declare const observationDeclarations: readonly [{
+    readonly id: 'state-seed';
+    readonly owner: "lifecycle-stage";
+    readonly postures: readonly ["environment"];
+    readonly stages: readonly [{
+        readonly stage: 'bootstrap';
+        readonly disposition: 'not-applicable';
+        readonly reason: 'the first seed has not completed';
+    }, {
+        readonly stage: 'steady';
+        readonly disposition: 'required';
+    }];
+    readonly code: "STATE_UNSEEDED";
+    readonly isIssued: typeof isLifecycleStageObservation;
+    readonly issuedAt: typeof observationIssuedAt;
+}];
+export interface LifecycleRecordValue extends LifecycleProgress {
+    readonly holderId: HolderId;
+    readonly teardownComplete?: true;
+    /**
+     * The digest of each file the running stack was started from, by the name a person edits, so a
+     * refused declaration change can say which one changed.
+     */
+    readonly runtimeInputs?: RuntimeInputs;
+}
+export type RuntimeInputs = Readonly<Record<string, string>>;
+export interface CurrentLifecycleRecord {
+    readonly record: StateRecord;
+    readonly value: LifecycleRecordValue;
+}
+export type EarlierNameResult = Readonly<{
+    kind: 'complete';
+    name: string | undefined;
+}> | Readonly<{
+    kind: 'refusal';
+    code: EnvironmentDiagnostic['code'];
+    message: string;
+    target: string;
+}>;
+export declare function findStackUnderEarlierName(input: Readonly<{
+    namespace: StateNamespace;
+    cockpitId: CockpitId;
+    checkoutId: CheckoutId;
+}>): Promise<EarlierNameResult>;
+export declare function earlierNameRefusalMessage(configPath: string, earlierName: string): string;
+export declare function decodeLifecycleRecord(record: StateRecord, context: Readonly<{
+    cockpitId: CockpitId;
+    stackId: StackId;
+}>): CurrentLifecycleRecord | undefined;
+export interface LifecycleStageAuthority {
+    readonly stackId: StackId;
+    readonly stage: ObservationLifecycleStage;
+    readonly observedAt: string;
+    readonly validThrough: string;
+}
+declare const lifecycleStageProjectionBrand: unique symbol;
+export interface LifecycleStageProjection {
+    readonly [lifecycleStageProjectionBrand]: true;
+}
+export interface LifecycleStageEvidence {
+    readonly stackId: StackId;
+    readonly stage: ObservationLifecycleStage;
+}
+export type LifecycleStageResolution = {
+    readonly kind: 'complete';
+    readonly authority: LifecycleStageAuthority;
+    readonly observation: EnvironmentObservation;
+} | {
+    readonly kind: 'refusal';
+    readonly diagnostics: readonly EnvironmentDiagnostic[];
+};
+export type LifecycleHistoryTransition = {
+    readonly kind: 'complete' | 'unchanged';
+    readonly record: StateRecord;
+} | {
+    readonly kind: 'refusal';
+    readonly diagnostics: readonly EnvironmentDiagnostic[];
+};
+declare function isLifecycleStageObservation(value: unknown): value is EnvironmentObservation;
+declare function observationIssuedAt(value: unknown): number | undefined;
+export declare function resolveLifecycleStage(input: {
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly observedAt: string;
+}): Promise<LifecycleStageResolution>;
+export declare function observeStateSeed(input: {
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly observedAt: string;
+}): Promise<EnvironmentObservation>;
+export declare function authenticateLifecycleStageAuthority(value: unknown, stackId: StackId, cockpitId: string, earliest: number, latest: number, evaluatedAt: number): ObservationLifecycleStage | undefined;
+export declare function projectLifecycleStage(input: {
+    readonly authority: LifecycleStageAuthority;
+    readonly stackId: StackId;
+    readonly cockpitId: CockpitId;
+    readonly earliest: number;
+    readonly latest: number;
+    readonly evaluatedAt: number;
+}): LifecycleStageProjection | undefined;
+export declare function consumeLifecycleStageProjection(projection: LifecycleStageProjection): LifecycleStageEvidence | undefined;
+export declare function recordLifecycleStarted(input: {
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly holderId: HolderId;
+    readonly observedAt: string;
+}): Promise<LifecycleHistoryTransition>;
+export declare function recordLifecycleSeeded(input: {
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly holderId: HolderId;
+    readonly observedAt: string;
+}): Promise<LifecycleHistoryTransition>;
+export {};

package/dist/environment/lifecycle-stage.js

@@ -0,0 +1,398 @@
+import { exactKeys } from '../exact-keys.js';
+import { z } from 'zod';
+import { lstatSync } from 'node:fs';
+import { dirname, isAbsolute, relative, sep } from 'node:path';
+import { hasErrorCode, RefusalError, ENVIRONMENT_CODES, isCanonicalTimestamp, snapshotJson, snapshotEnvironmentObservation, } from './contract.js';
+import { abortStateTransaction, authenticateStateNamespace, lifecycleHistoryAddress, readState, transactState, withStateNamespaceInventory, } from './state.js';
+import { stackId as deriveStackId } from './identity.js';
+import { cockpitCommand } from '../fix-catalogue.js';
+const OWNER = 'lifecycle-stage';
+export const observationDeclarations = Object.freeze([{
+        id: 'state-seed',
+        owner: OWNER,
+        postures: ['environment'],
+        stages: [
+            { stage: 'bootstrap', disposition: 'not-applicable', reason: 'the first seed has not completed' },
+            { stage: 'steady', disposition: 'required' },
+        ],
+        code: ENVIRONMENT_CODES.STATE_UNSEEDED,
+        isIssued: isLifecycleStageObservation,
+        issuedAt: observationIssuedAt,
+    }]);
+const HistoryValue = z.object({ status: z.enum(['started', 'seeded']) }).strict();
+const STACK_ID = /^stack:[a-f0-9]{64}$/;
+const HOLDER_ID = /^holder:[a-f0-9]{64}:session$/;
+const AUTHORITY_LIFETIME_MS = 30_000;
+const issuedObservations = new WeakMap();
+const issuedAuthorities = new WeakMap();
+const issuedLifecycleStageProjections = new WeakMap();
+const lifecycleDigest = /^[a-f0-9]{64}$/;
+const lifecycleService = /^[a-z0-9][a-z0-9_.-]*$/;
+// A stack keeps the cockpit identity it started under, and that identity carries `cockpit.name`.
+// After a rename this checkout's stack is still recorded under the earlier name, where sync, up and
+// down no longer look: down reported nothing to act on while the containers kept running. This
+// returns that earlier name while such a stack is recorded and not torn down, so they can refuse
+// with the recovery instead.
+export async function findStackUnderEarlierName(input) {
+    const [, currentName, checkoutDigest] = input.cockpitId.split(':');
+    const placeholder = `stack:${'0'.repeat(64)}`;
+    const found = await withStateNamespaceInventory(input.namespace, async (namespaces) => {
+        for (const candidate of namespaces) {
+            const cockpitId = candidate.paths.lifecycle(placeholder).cockpitId;
+            const [, name, digest] = cockpitId.split(':');
+            if (digest !== checkoutDigest || name === currentName || name === undefined)
+                continue;
+            const stack = deriveStackId({ cockpitId, checkoutId: input.checkoutId, variant: { kind: 'shared' } });
+            const address = candidate.paths.lifecycle(stack);
+            const stored = await readState(address);
+            if (stored.kind === 'missing')
+                continue;
+            if (stored.kind !== 'complete')
+                return { kind: 'refusal', code: stored.code, message: stored.message, target: stored.target };
+            const lifecycle = decodeLifecycleRecord(stored.value, { cockpitId, stackId: stack });
+            if (!lifecycle)
+                return { kind: 'refusal', code: ENVIRONMENT_CODES.STATE_RECORD_MALFORMED, message: 'lifecycle progress record is malformed', target: address.path };
+            if (lifecycle.value.teardownComplete !== true)
+                return { kind: 'complete', name };
+        }
+        return { kind: 'complete', name: undefined };
+    });
+    if (found.kind === 'complete')
+        return found.value;
+    if (found.kind === 'missing')
+        return { kind: 'complete', name: undefined };
+    return { kind: 'refusal', code: found.code, message: found.message, target: found.target };
+}
+export function earlierNameRefusalMessage(configPath, earlierName) {
+    return `cockpit.name was changed from "${earlierName}" while a stack started under that name is still recorded; the stack keeps the earlier name, so only down run under that name removes its containers — fix: set name = "${earlierName}" in ${configPath} again, run \`${cockpitCommand('down', { config: configPath })}\`, then rename the cockpit and run \`${cockpitCommand('sync', { config: configPath })}\``;
+}
+export function decodeLifecycleRecord(record, context) {
+    const value = snapshotJson(record.value);
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+        || !exactKeys(value, ['completedServices', 'holderId', 'operationGeneration', 'workBasisSha256'], ['runtimeInputs', 'teardownComplete'])
+        || record.format !== 'cockpit-state/v1' || record.kind !== 'lifecycle'
+        || record.cockpitId !== context.cockpitId || record.subjectId !== context.stackId)
+        return undefined;
+    const candidate = value;
+    if (typeof candidate.holderId !== 'string' || !HOLDER_ID.test(candidate.holderId)
+        || typeof candidate.workBasisSha256 !== 'string' || !lifecycleDigest.test(candidate.workBasisSha256)
+        || typeof candidate.operationGeneration !== 'string' || !lifecycleDigest.test(candidate.operationGeneration)
+        || !Array.isArray(candidate.completedServices) || candidate.completedServices.length > 4_096)
+        return undefined;
+    const teardownComplete = Object.hasOwn(candidate, 'teardownComplete');
+    if (teardownComplete && (candidate.teardownComplete !== true || candidate.completedServices.length !== 0))
+        return undefined;
+    let runtimeInputs;
+    if (Object.hasOwn(candidate, 'runtimeInputs')) {
+        const value = candidate.runtimeInputs;
+        if (teardownComplete || !value || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const entries = Object.entries(value);
+        if (entries.length === 0 || entries.length > 64 || entries.some(([name, digest]) => name.length === 0 || name.length > 1_024
+            || name.includes('\0') || typeof digest !== 'string' || !lifecycleDigest.test(digest)))
+            return undefined;
+        runtimeInputs = Object.fromEntries(entries);
+    }
+    const completed = candidate.completedServices.map((item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)
+            || !exactKeys(item, ['containerId', 'service']))
+            return undefined;
+        const service = item.service;
+        const containerId = item.containerId;
+        return typeof service === 'string' && lifecycleService.test(service)
+            && typeof containerId === 'string' && lifecycleDigest.test(containerId)
+            ? { service, containerId }
+            : undefined;
+    });
+    if (completed.some((item) => item === undefined))
+        return undefined;
+    return {
+        record,
+        value: {
+            holderId: candidate.holderId,
+            ...(teardownComplete ? { teardownComplete: true } : {}),
+            ...(runtimeInputs ? { runtimeInputs } : {}),
+            workBasisSha256: candidate.workBasisSha256,
+            operationGeneration: candidate.operationGeneration,
+            completedServices: completed,
+        },
+    };
+}
+function refusal(message, target) {
+    return {
+        kind: 'refusal',
+        diagnostics: [{
+                severity: 'error',
+                code: ENVIRONMENT_CODES.STATE_RECORD_MALFORMED,
+                message,
+                target,
+                fix: 'inspect lifecycle state and history before explicit recovery or adoption',
+            }],
+    };
+}
+function stableInput(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const { namespace: rawNamespace, stackId, observedAt } = value;
+    const namespace = authenticateStateNamespace(rawNamespace);
+    const observedMillis = typeof observedAt === 'string' ? Date.parse(observedAt) : Number.NaN;
+    const now = Date.now();
+    if (!namespace || typeof stackId !== 'string' || !STACK_ID.test(stackId)
+        || !isCanonicalTimestamp(observedAt) || observedMillis > now || now - observedMillis > AUTHORITY_LIFETIME_MS)
+        return undefined;
+    return { namespace, stackId: stackId, observedAt };
+}
+function stableTransitionInput(value) {
+    const base = stableInput(value);
+    const holderId = base ? value.holderId : undefined;
+    return base && typeof holderId === 'string' && HOLDER_ID.test(holderId)
+        ? { ...base, holderId: holderId }
+        : undefined;
+}
+function historyStatus(record) {
+    return record.kind === 'lifecycle-history' ? HistoryValue.safeParse(record.value).data?.status : undefined;
+}
+function sameResult(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function fileIdentity(path) {
+    try {
+        const status = lstatSync(path, { bigint: true });
+        const state = status.isSymbolicLink() ? 'symlink'
+            : status.isFile() ? 'file'
+                : status.isDirectory() ? 'directory'
+                    : 'other';
+        const identity = state === 'directory'
+            ? [status.dev, status.ino]
+            : [status.dev, status.ino, status.mode, status.size, status.mtimeNs, status.ctimeNs];
+        return { state, identity: identity.map(String).join(':') };
+    }
+    catch (error) {
+        return hasErrorCode(error, 'ENOENT')
+            ? { state: 'missing' }
+            : undefined;
+    }
+}
+function sameIdentity(left, right) {
+    return left.state === right.state && left.identity === right.identity;
+}
+function pathIdentity(root, path) {
+    const relation = relative(root, path);
+    if (!isAbsolute(root) || !isAbsolute(path) || relation === '' || isAbsolute(relation)
+        || relation === '..' || relation.startsWith(`..${sep}`))
+        return undefined;
+    const chain = [];
+    let cursor = path;
+    while (true) {
+        chain.push(cursor);
+        const parent = dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    const identities = [];
+    for (const candidate of chain.reverse()) {
+        const identity = fileIdentity(candidate);
+        if (!identity)
+            return undefined;
+        identities.push(identity);
+    }
+    return identities;
+}
+function samePathIdentity(left, right) {
+    return left.length === right.length && left.every((identity, index) => sameIdentity(identity, right[index]));
+}
+function lifecycleBinding(namespace, cockpitId, historyPath, lifecyclePath) {
+    const historyIdentity = pathIdentity(namespace.root, historyPath);
+    const lifecycleIdentity = pathIdentity(namespace.root, lifecyclePath);
+    return historyIdentity && lifecycleIdentity
+        ? {
+            cockpitId,
+            namespace,
+            historyPath,
+            historyIdentity,
+            lifecyclePath,
+            lifecycleIdentity,
+        }
+        : undefined;
+}
+function sameBinding(left, right) {
+    return left.historyPath === right.historyPath
+        && left.lifecyclePath === right.lifecyclePath
+        && left.cockpitId === right.cockpitId
+        && samePathIdentity(left.historyIdentity, right.historyIdentity)
+        && samePathIdentity(left.lifecycleIdentity, right.lifecycleIdentity);
+}
+function issueObservation(value) {
+    const snapshot = snapshotEnvironmentObservation(value);
+    if (!snapshot || snapshot.owner !== OWNER)
+        throw new RefusalError('lifecycle stage observation is malformed');
+    issuedObservations.set(snapshot, Date.now());
+    return snapshot;
+}
+function isLifecycleStageObservation(value) {
+    return value !== null && typeof value === 'object' && issuedObservations.has(value);
+}
+function observationIssuedAt(value) {
+    return value !== null && typeof value === 'object' ? issuedObservations.get(value) : undefined;
+}
+async function inspect(input) {
+    const historyAddress = lifecycleHistoryAddress(input.namespace, input.stackId);
+    const lifecycleAddress = input.namespace.paths.lifecycle(input.stackId);
+    if (!historyAddress)
+        return refusal('lifecycle history address is unavailable', lifecycleAddress.path);
+    if (historyAddress.cockpitId !== lifecycleAddress.cockpitId) {
+        return refusal('lifecycle state addresses disagree on cockpit identity', historyAddress.path);
+    }
+    const bindingBefore = lifecycleBinding(input.namespace, historyAddress.cockpitId, historyAddress.path, lifecycleAddress.path);
+    if (!bindingBefore)
+        return refusal('lifecycle state identity is unavailable', historyAddress.path);
+    const historyBefore = await readState(historyAddress);
+    const lifecycleBefore = await readState(lifecycleAddress);
+    const historyAfter = await readState(historyAddress);
+    const lifecycleAfter = await readState(lifecycleAddress);
+    const bindingAfter = lifecycleBinding(input.namespace, historyAddress.cockpitId, historyAddress.path, lifecycleAddress.path);
+    if (!bindingAfter || !sameBinding(bindingBefore, bindingAfter)
+        || !sameResult(historyBefore, historyAfter) || !sameResult(lifecycleBefore, lifecycleAfter)) {
+        return refusal('lifecycle state changed while its stage was observed', historyAddress.path);
+    }
+    if (historyBefore.kind === 'refusal' || historyBefore.kind === 'indeterminate') {
+        return refusal(historyBefore.message, historyAddress.path);
+    }
+    if (lifecycleBefore.kind === 'refusal' || lifecycleBefore.kind === 'indeterminate') {
+        return refusal(lifecycleBefore.message, lifecycleAddress.path);
+    }
+    const status = historyBefore.kind === 'complete' ? historyStatus(historyBefore.value) : undefined;
+    if (historyBefore.kind === 'complete' && !status)
+        return refusal('lifecycle history is malformed', historyAddress.path);
+    if (historyBefore.kind === 'missing' && lifecycleBefore.kind === 'complete') {
+        return refusal('lifecycle data exists without durable lifecycle history', lifecycleAddress.path);
+    }
+    const stage = status === 'seeded' ? 'steady' : 'bootstrap';
+    const seeded = lifecycleBefore.kind === 'complete';
+    const issuedAt = Date.now();
+    const authority = {
+        stackId: input.stackId,
+        stage,
+        observedAt: input.observedAt,
+        validThrough: new Date(issuedAt + AUTHORITY_LIFETIME_MS).toISOString(),
+    };
+    issuedAuthorities.set(authority, bindingAfter);
+    const observation = issueObservation({
+        code: ENVIRONMENT_CODES.STATE_UNSEEDED,
+        owner: OWNER,
+        stackId: input.stackId,
+        source: lifecycleAddress.path,
+        observed: { state: 'available', value: seeded, observedAt: input.observedAt },
+        expectation: { kind: 'equal', value: true },
+        applicability: { state: 'required', posture: 'environment' },
+        freshness: { state: 'current' },
+        remedy: 'restore or seed lifecycle state without deleting its durable history',
+    });
+    return { kind: 'complete', authority, observation };
+}
+export async function resolveLifecycleStage(input) {
+    const stable = stableInput(input);
+    return stable ? inspect(stable) : refusal('lifecycle stage input is malformed', 'lifecycle stage input');
+}
+export async function observeStateSeed(input) {
+    const result = await resolveLifecycleStage(input);
+    if (result.kind !== 'complete')
+        throw new RefusalError(result.diagnostics[0]?.message ?? 'lifecycle stage is unavailable');
+    return result.observation;
+}
+function validAuthorityExpectation(value) {
+    return Number.isSafeInteger(value.earliest)
+        && Number.isSafeInteger(value.latest)
+        && Number.isSafeInteger(value.evaluatedAt)
+        && value.earliest <= value.evaluatedAt
+        && value.evaluatedAt <= value.latest;
+}
+function consumeLifecycleStageAuthority(value, expected, trustedCurrentTime) {
+    if (value === null || typeof value !== 'object' || !validAuthorityExpectation(expected)
+        || !Number.isSafeInteger(trustedCurrentTime) || expected.evaluatedAt > trustedCurrentTime)
+        return undefined;
+    const binding = issuedAuthorities.get(value);
+    if (!binding || binding.cockpitId !== expected.cockpitId)
+        return undefined;
+    const authority = value;
+    const observedAt = Date.parse(authority.observedAt);
+    const validThrough = Date.parse(authority.validThrough);
+    if (authority.stackId !== expected.stackId || !Number.isFinite(observedAt) || !Number.isFinite(validThrough)
+        || observedAt < expected.earliest || observedAt > expected.latest
+        || observedAt > expected.evaluatedAt || trustedCurrentTime > validThrough)
+        return undefined;
+    const namespace = authenticateStateNamespace(binding.namespace);
+    const currentBinding = namespace
+        ? lifecycleBinding(namespace, binding.cockpitId, binding.historyPath, binding.lifecyclePath)
+        : undefined;
+    if (!currentBinding || !sameBinding(binding, currentBinding))
+        return undefined;
+    issuedAuthorities.delete(value);
+    return authority.stage;
+}
+export function authenticateLifecycleStageAuthority(value, stackId, cockpitId, earliest, latest, evaluatedAt) {
+    return consumeLifecycleStageAuthority(value, { stackId, cockpitId, earliest, latest, evaluatedAt }, evaluatedAt);
+}
+export function projectLifecycleStage(input) {
+    const expected = { stackId: input.stackId, cockpitId: input.cockpitId, earliest: input.earliest, latest: input.latest, evaluatedAt: input.evaluatedAt };
+    const stage = consumeLifecycleStageAuthority(input.authority, expected, Date.now());
+    if (!stage)
+        return undefined;
+    const projection = {};
+    issuedLifecycleStageProjections.set(projection, Object.freeze({ stackId: expected.stackId, stage }));
+    return projection;
+}
+export function consumeLifecycleStageProjection(projection) {
+    const evidence = issuedLifecycleStageProjections.get(projection);
+    if (!evidence)
+        return undefined;
+    issuedLifecycleStageProjections.delete(projection);
+    return evidence;
+}
+async function transition(value, requested) {
+    const input = stableTransitionInput(value);
+    if (!input)
+        return refusal('lifecycle history transition input is malformed', 'lifecycle history input');
+    const address = lifecycleHistoryAddress(input.namespace, input.stackId);
+    if (!address)
+        return refusal('lifecycle history address is unavailable', input.stackId);
+    const result = await transactState(input.namespace, address, { ownerId: input.holderId }, (current) => {
+        const currentStatus = current ? historyStatus(current) : undefined;
+        if (current && !currentStatus)
+            return abortStateTransaction(refusal('lifecycle history is malformed', address.path));
+        if (requested === 'seeded' && currentStatus === undefined) {
+            return abortStateTransaction(refusal('lifecycle history must be started before it is seeded', address.path));
+        }
+        // Seeded history already records its start, so a later `started` (setup acquiring a
+        // sibling added after the stack has run) leaves it seeded. Refusing it deadlocked setup.
+        if (currentStatus === requested || currentStatus === 'seeded') {
+            return abortStateTransaction({ kind: 'unchanged', record: current });
+        }
+        return {
+            format: 'cockpit-state/v1',
+            kind: 'lifecycle-history',
+            cockpitId: address.cockpitId,
+            subjectId: input.stackId,
+            revision: (current?.revision ?? -1) + 1,
+            updatedAt: input.observedAt,
+            value: { status: requested },
+        };
+    });
+    const aborted = result;
+    if (aborted.aborted === true)
+        return aborted.value;
+    const stateResult = result;
+    if (stateResult.kind === 'complete')
+        return { kind: 'complete', record: stateResult.value };
+    const message = stateResult.kind === 'refusal' || stateResult.kind === 'indeterminate'
+        ? stateResult.message
+        : 'lifecycle history transition failed';
+    return refusal(message, address.path);
+}
+export function recordLifecycleStarted(input) {
+    return transition(input, 'started');
+}
+export function recordLifecycleSeeded(input) {
+    return transition(input, 'seeded');
+}

package/dist/environment/lifecycle.d.ts

@@ -0,0 +1,75 @@
+import { type EnvironmentDiagnostic, type LifecyclePlan, type LifecycleProgress } from './contract.js';
+import { type LifecycleStageProjection } from './lifecycle-stage.js';
+import { type PortLeaseProjection } from './ports.js';
+import type { ReclaimTargetEnvelope } from './reclaim.js';
+import { type RuntimeLifecycleProjection, type RuntimeServiceEvidence, type RuntimeTopologyEvidence } from './runtime.js';
+import type { DrainReservationRequest } from './claims.js';
+type PortOwnership = PortLeaseProjection['ownership'];
+export interface LifecycleIssuance {
+    readonly topology: RuntimeTopologyEvidence;
+    readonly firstIncompleteServiceIndex: number;
+    readonly portOwnership: PortOwnership;
+    readonly drainRequest: DrainReservationRequest | null;
+    readonly reclaim: ReclaimTargetEnvelope | null;
+}
+export type UpLifecycleResult = {
+    readonly kind: 'execute';
+    readonly mode: 'start' | 'resume';
+    readonly plan: LifecyclePlan;
+} | {
+    readonly kind: 'noop';
+    readonly plan: LifecyclePlan;
+} | LifecycleRefusal;
+export type SleepLifecycleResult = {
+    readonly kind: 'release-only';
+    readonly plan: LifecyclePlan;
+} | {
+    readonly kind: 'drain';
+    readonly plan: LifecyclePlan;
+    readonly request: DrainReservationRequest;
+} | LifecycleRefusal;
+export type DestructiveLifecycleResult = {
+    readonly kind: 'drain';
+    readonly plan: LifecyclePlan;
+    readonly request: DrainReservationRequest;
+} | LifecycleRefusal;
+type LifecycleRefusal = {
+    readonly kind: 'refusal';
+    readonly diagnostics: readonly EnvironmentDiagnostic[];
+};
+declare const upPlanningAuthorityBrand: unique symbol;
+export interface UpPlanningAuthority {
+    readonly [upPlanningAuthorityBrand]: true;
+}
+export declare function consumeLifecycleIssuance(plan: LifecyclePlan): LifecycleIssuance | undefined;
+export declare function admitUpProgress(input: {
+    readonly lifecycleStage: LifecycleStageProjection;
+    readonly runtime: RuntimeLifecycleProjection;
+    readonly ports: PortLeaseProjection;
+    readonly progress: LifecycleProgress | null;
+    readonly operationGeneration: string;
+}): {
+    readonly kind: 'admitted';
+    readonly authority: UpPlanningAuthority;
+} | LifecycleRefusal;
+export declare function planAdmittedUp(input: {
+    readonly authority: UpPlanningAuthority;
+    readonly completedServices: readonly RuntimeServiceEvidence[];
+}): UpLifecycleResult;
+export declare function planSleep(input: {
+    readonly runtime: RuntimeLifecycleProjection;
+    readonly ports: PortLeaseProjection;
+    readonly operationGeneration: string;
+    readonly runtimeStopValidForMs: number;
+}): SleepLifecycleResult;
+interface DestructivePlanningInput {
+    readonly runtime: RuntimeLifecycleProjection;
+    readonly ports: PortLeaseProjection;
+    readonly reclaim: ReclaimTargetEnvelope;
+    readonly operationGeneration: string;
+    readonly runtimeStopValidForMs: number;
+    readonly reclaimValidForMs: number;
+}
+export declare function planDown(input: DestructivePlanningInput): DestructiveLifecycleResult;
+export declare function planResetLifecycle(input: DestructivePlanningInput): DestructiveLifecycleResult;
+export {};