@b00dea/cockpit 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,35 @@
+import { type UnconfirmedAnswerName } from '../../guards/answer-confirmation.js';
+import { type Diagnostic } from '../contract.js';
+import type { EvaluatedObservation } from '../observations.js';
+export interface ConfirmCommandInput {
+    readonly configPath: string;
+    readonly answer: UnconfirmedAnswerName;
+}
+type Observed = Readonly<{
+    status: number;
+    diagnostics: readonly Diagnostic[];
+}>;
+export interface ConfirmCommandAdapters {
+    /** The preflight command, run against the configuration on disk. */
+    readonly preflight: (input: Readonly<{
+        configPath: string;
+    }>) => Promise<Observed & Readonly<{
+        result: Readonly<{
+            checks: readonly EvaluatedObservation[];
+        }>;
+    }>>;
+    /** The check command, run against the configuration on disk. */
+    readonly check: (input: Readonly<{
+        configPath: string;
+    }>) => Promise<Observed>;
+    readonly now: () => Date;
+}
+export interface ConfirmCommandOutcome {
+    readonly status: 0 | 2;
+    readonly artifact: string | null;
+    readonly destination: null;
+    readonly result: unknown;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function runConfirm(input: ConfirmCommandInput, adapters: ConfirmCommandAdapters): Promise<ConfirmCommandOutcome>;
+export {};

package/dist/environment/application/confirm.js

@@ -0,0 +1,122 @@
+// Sequences `cockpit confirm <answer>`: refuse an answer only a person may confirm, run the existing
+// observation that verifies the rest against this machine and the running product, record what ran,
+// then drop the answer from `unconfirmed` in cockpit.toml. The record goes first, so a failed edit
+// leaves a record nothing uses, never a removed entry the guard cannot account for.
+import { dirname, join } from 'node:path';
+import { canonicalJson } from '../../canonical-json.js';
+import { loadCockpitConfig, readBoundedInput } from '../../config/load.js';
+import { removeUnconfirmedAnswer } from '../../config/unconfirmed-toml.js';
+import { writeVerifiedConfig } from '../../config/verified-write.js';
+import { cockpitCommand } from '../../fix-catalogue.js';
+import { ANSWER_CONFIRMATION_PATH, ANSWER_CONFIRMATIONS, confirmationConfigurationSha256, encodeAnswerConfirmations, parseAnswerConfirmations, personConfirmationFix, } from '../../guards/answer-confirmation.js';
+import { writeCockpitLocalFiles } from '../../guards/local-identity.js';
+import { refusalOutcome } from '../../refusal.js';
+import { sha256Hex } from '../../sha256.js';
+import { ENVIRONMENT_CODES, hasErrorCode } from '../contract.js';
+import { declaredRuntime } from '../declaration.js';
+// The rows of preflight that say the runtime measured on this machine meets the declared floor.
+const RUNTIME_FLOOR_CODES = [ENVIRONMENT_CODES.MACHINE_MEMORY_BELOW_FLOOR, ENVIRONMENT_CODES.MACHINE_CPU_BELOW_FLOOR,
+    ENVIRONMENT_CODES.MACHINE_DISK_BELOW_FLOOR, ENVIRONMENT_CODES.RUNTIME_UNMEASURED];
+// Preflight passes only with the stack up; this row says the port family it holds is leased on the
+// declared bases with current listener evidence.
+const PORT_FAMILY_CODES = [ENVIRONMENT_CODES.PORT_FAMILY_COLLISION];
+const failing = (diagnostics) => diagnostics.filter(row => row.severity === 'error');
+async function observe(observation, configPath, config, adapters) {
+    // A machine floor alone is still measured; the stack and its Compose files need a declared runtime.
+    if (observation !== 'runtime-floor' && declaredRuntime(config.environment) !== 'compose') {
+        return { passed: false, reason: 'cockpit.toml declares no Compose files, so there is no stack or topology to observe', diagnostics: [] };
+    }
+    if (observation === 'check') {
+        const checked = await adapters.check({ configPath });
+        return checked.status === 0 ? { passed: true, evidence: { status: checked.status, diagnostics: checked.diagnostics } }
+            : { passed: false, reason: 'check did not pass', diagnostics: failing(checked.diagnostics) };
+    }
+    const preflight = await adapters.preflight({ configPath });
+    const codes = observation === 'preflight' ? PORT_FAMILY_CODES : RUNTIME_FLOOR_CODES;
+    const rows = preflight.result.checks.filter(check => codes.includes(check.code));
+    const unmet = codes.filter(code => !rows.some(row => row.code === code && row.verdict === 'pass'));
+    const evidence = { checks: rows.map(({ code, verdict, source, measured, observedAt }) => ({ code, verdict, source, measured, observedAt })) };
+    if (observation === 'preflight' && preflight.status !== 0) {
+        return { passed: false, reason: 'preflight did not pass, so the stack is not up and healthy on the declared ports', diagnostics: failing(preflight.diagnostics) };
+    }
+    return unmet.length === 0 ? { passed: true, evidence }
+        : { passed: false, reason: `preflight did not observe ${unmet.join(', ')} passing`, diagnostics: failing(preflight.diagnostics) };
+}
+async function readConfirmations(root) {
+    try {
+        const read = await readBoundedInput(join(root, ANSWER_CONFIRMATION_PATH));
+        return read.kind === 'complete' ? read.bytes : undefined;
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    }
+}
+export async function runConfirm(input, adapters) {
+    const { answer } = input;
+    const confirmation = ANSWER_CONFIRMATIONS[answer];
+    if (confirmation.by === 'person') {
+        return refusalOutcome('CONFIRM_PERSON_REQUIRED', `${answer} is confirmed only by a person: ${confirmation.trustDecision ? `it is a trust decision, because ${confirmation.why}` : confirmation.why}`, answer, personConfirmationFix([answer], input.configPath));
+    }
+    const loaded = await loadCockpitConfig(input.configPath);
+    if (loaded.kind !== 'complete')
+        return { status: 2, artifact: null, destination: null, result: null, diagnostics: loaded.diagnostics };
+    const configPath = loaded.result.source.path;
+    const config = loaded.result.config;
+    if (!config.unconfirmed?.includes(answer)) {
+        return refusalOutcome('CONFIRM_ANSWER_NOT_LISTED', `${answer} is not listed under unconfirmed in ${configPath}, so there is nothing to confirm`, 'unconfirmed', `run ${cockpitCommand('doctor', { config: configPath })}; DECLARATION_UNCONFIRMED names the answers still to confirm`);
+    }
+    const ranAt = adapters.now().toISOString();
+    const verdict = await observe(confirmation.observation, configPath, config, adapters);
+    if (!verdict.passed) {
+        const refused = refusalOutcome('CONFIRM_OBSERVATION_FAILED', `${answer} stays unconfirmed: ${verdict.reason}; confirming it needs ${confirmation.verifies}`, answer, `clear the diagnostics reported beside this one, then run ${cockpitCommand('confirm', { config: configPath, operand: answer })} again; if the value itself is wrong, correct it in cockpit.toml first`);
+        return { ...refused, diagnostics: [...refused.diagnostics, ...verdict.diagnostics] };
+    }
+    // The observation re-reads cockpit.toml itself, so the record binds to what it observed only if the
+    // file is still the one loaded above. An agent edit made meanwhile cannot be reverted before this
+    // read: the guard holds every call but sync and check once the file differs from the synced one.
+    const after = await loadCockpitConfig(configPath);
+    if (after.kind !== 'complete' || after.result.source.sha256 !== loaded.result.source.sha256) {
+        return refusalOutcome(ENVIRONMENT_CODES.CONFIG_CHANGED_DURING_EXECUTION, 'cockpit.toml changed while the observation ran, so it cannot show which configuration passed; nothing was recorded or removed', configPath, `run ${cockpitCommand('confirm', { config: configPath, operand: answer })} again`);
+    }
+    const root = dirname(configPath);
+    const record = { observation: confirmation.observation, ranAt, result: 'passed',
+        evidenceSha256: sha256Hex(canonicalJson(verdict.evidence)), configurationSha256: confirmationConfigurationSha256(config) };
+    const written = await writeCockpitLocalFiles(root, [{ name: 'answer-confirmations',
+            bytes: encodeAnswerConfirmations({ ...parseAnswerConfirmations(await readConfirmations(root)), [answer]: record }) }]);
+    if (written.kind !== 'complete') {
+        return refusalOutcome('CONFIRM_RECORD_UNWRITABLE', `the observation passed, but its record could not be written: ${written.message}; cockpit.toml was not changed`, ANSWER_CONFIRMATION_PATH, `make ${ANSWER_CONFIRMATION_PATH} writable for this user, then run ${cockpitCommand('confirm', { config: configPath, operand: answer })} again`);
+    }
+    const remaining = config.unconfirmed.filter(row => row !== answer);
+    const expected = canonicalJson({ ...config, unconfirmed: remaining.length ? remaining : undefined });
+    const exact = (candidate) => canonicalJson(candidate) === expected;
+    const rerun = `run ${cockpitCommand('confirm', { config: configPath, operand: answer })} again`;
+    const byHand = personConfirmationFix([answer], configPath);
+    const edited = await writeVerifiedConfig({
+        path: configPath, expectedSha256: loaded.result.source.sha256, temporaryTag: 'confirm',
+        edit: text => {
+            const edit = removeUnconfirmedAnswer(text, answer);
+            return edit.kind === 'edited' ? edit.text : text;
+        },
+        isExactChange: exact,
+        messages: {
+            changedBefore: { message: 'cockpit.toml changed while the observation ran; nothing was removed', fix: rerun },
+            changedDuring: { message: 'cockpit.toml changed while the edit was being prepared; nothing was removed', fix: rerun },
+            invalid: reason => ({ message: `removing ${answer} would leave cockpit.toml invalid (${reason}); nothing was removed`, fix: byHand }),
+            notExact: { message: `cockpit.toml does not list ${answer} on one unconfirmed = [...] line this command can edit; nothing was removed`, fix: byHand },
+            writtenMismatch: { message: `${answer} was removed, but re-reading cockpit.toml shows a change beyond it`,
+                fix: `review cockpit.toml for the change you did not make before running ${cockpitCommand('sync', { config: configPath, args: '--dry-run' })}` },
+        },
+    });
+    if (edited.kind !== 'complete')
+        return refusalOutcome(edited.code, edited.message, configPath, edited.fix);
+    const sync = cockpitCommand('sync', { config: configPath });
+    return {
+        status: 0, destination: null, diagnostics: [],
+        artifact: `Confirmed ${answer}: ${confirmation.verifies}. Removed it from unconfirmed in ${configPath} and recorded the observation in ${ANSWER_CONFIRMATION_PATH}.\n`
+            + `Run ${sync} to apply the edit; an agent may where [autonomy] sync = "agent", because the recorded observation makes the removal non-widening.\n`,
+        result: { answer, observation: confirmation.observation, ranAt, outcome: 'passed', evidenceSha256: record.evidenceSha256,
+            record: ANSWER_CONFIRMATION_PATH, unconfirmed: remaining, next: sync },
+    };
+}

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

@@ -0,0 +1,6 @@
+import { type DownCommandAdapters, type DownCommandInput, type DownCommandResult, type OperatorResetSession, type ResetCommandAdapters, type ResetCommandInput, type ResetCommandResult } from './lifecycle-context.js';
+export declare function runDown(input: DownCommandInput, adapters: DownCommandAdapters): Promise<DownCommandResult>;
+export declare function runReset(input: ResetCommandInput, adapters: ResetCommandAdapters): Promise<ResetCommandResult>;
+export declare function beginOperatorReset(input: ResetCommandInput, adapters: ResetCommandAdapters): Promise<OperatorResetSession | Extract<ResetCommandResult, {
+    kind: 'refusal';
+}>>;

package/dist/environment/application/destructive.js

@@ -0,0 +1,429 @@
+import { randomBytes } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { dirname, join } from 'node:path';
+import { cleanupFencedExecution, repairFencedExecution } from '../../environment-exec/execute.js';
+import { ENVIRONMENT_CODES, forwardedRefusal } from '../contract.js';
+import { readState } from '../state.js';
+import { compensateAcquiredPortHolder } from '../ports.js';
+import { consumeLifecycleIssuance, planDown, planResetLifecycle } from '../lifecycle.js';
+import { stopRuntime } from '../runtime.js';
+import { inspectDestructiveDrainRecovery, settleInterruptedDrainRepair, recoverDrainReservation, reserveDrain, reserveDrainAttempt, } from '../claims.js';
+import { executeReclaimAction, keptTeardownResources, planReset, planTeardown, reconcileReclaimAction, } from '../reclaim.js';
+import { selectDestructiveInstance } from '../instance.js';
+import { issuedDestructiveRuns, lifecycleContextRefusal, provisionalClaims, withLifecycleRunNotices, } from './lifecycle-context.js';
+import { exactCommandConfigPath, invalidateCompletedLifecycle, lifecycleSuggestion, publishDrainOutcome, publishDrainOutcomeRecord, } from './lifecycle-state.js';
+import { lifecycleRefusal, uniqueDiagnostics } from './shared.js';
+import { forgetStackInputs } from '../stack-inputs.js';
+function destructiveRepairRequired(context) {
+    return lifecycleRefusal(ENVIRONMENT_CODES.DRAIN_ATTEMPT_REPAIR_REQUIRED, 'cockpit cannot prove the interrupted destructive executor stopped, so it will not overlap it with another destructive action; preserve the coordination state for explicit repair', context.stackId);
+}
+// A stack no session holds is claimed only so down or reset can read it, and the claim belongs to
+// the drain the run reserves, which releases it. A run that reserves no drain (a preview, a decline,
+// a refusal before the drain) gives it back, or the next up meets a holder it did not take and
+// refuses on every retry.
+async function settleProvisionalClaim(context, outcome) {
+    const claim = provisionalClaims.get(context);
+    if (!claim)
+        return outcome;
+    provisionalClaims.delete(context);
+    const released = await compensateAcquiredPortHolder({ namespace: context.namespace, leaseResult: claim, now: new Date().toISOString() });
+    if (released.kind === 'complete')
+        return outcome;
+    return forwardedRefusal(uniqueDiagnostics([...outcome.kind === 'refusal' ? outcome.diagnostics : [], ...released.diagnostics]));
+}
+async function loadDestructiveContext(input, adapters) {
+    const configPath = exactCommandConfigPath(input);
+    if (!configPath)
+        return lifecycleContextRefusal();
+    const loaded = await adapters.load({ configPath });
+    if (loaded.kind !== 'complete')
+        return loaded.kind === 'refusal' ? loaded : lifecycleContextRefusal();
+    if (loaded.result.configPath !== configPath || !issuedDestructiveRuns.delete(loaded.result)) {
+        return lifecycleRefusal(ENVIRONMENT_CODES.LIFECYCLE_EVIDENCE_INVALID, 'destructive run authority is unavailable', configPath);
+    }
+    return loaded;
+}
+function selectedObservation(context, observation) {
+    if (!observation)
+        return undefined;
+    try {
+        const selected = selectDestructiveInstance(observation.instance);
+        return selected.kind === 'selected' && selected.stackId === context.stackId
+            && selected.checkoutId === context.checkoutId ? observation : undefined;
+    }
+    catch {
+        // An observation whose instance cannot be read is not this run's, which the caller refuses.
+        return undefined;
+    }
+}
+async function observeDestructive(context, adapters) {
+    const observed = await adapters.observe(context);
+    return observed && 'diagnostics' in observed ? observed : selectedObservation(context, observed);
+}
+// Each removal is proven by a fresh discovery, but re-measuring the runtime and re-listing the
+// daemon twice per removal made `down` take minutes on a busy shared daemon. A reserved drain's
+// steps re-read only reclaim evidence, and one discovery both reconciles a removal and plans the next.
+async function observeDestructiveReclaim(context, adapters) {
+    const observed = adapters.observeReclaim ? await adapters.observeReclaim(context) : await adapters.observe(context);
+    return observed && 'diagnostics' in observed ? observed : selectedObservation(context, observed);
+}
+// Before this run reserves a drain there is no attempt of its own to repair, so a missing
+// observation is an evidence failure. Reporting DRAIN_ATTEMPT_REPAIR_REQUIRED here sent the
+// operator of a stopped runtime looking for an interrupted attempt that did not exist.
+function destructivePreconditionRefusal(context, observed) {
+    return observed ?? lifecycleRefusal(ENVIRONMENT_CODES.LIFECYCLE_EVIDENCE_INVALID, 'destructive preconditions (configuration, retained ports, runtime readiness or reclaim discovery) could not be observed; this run reserved no destructive attempt', context.stackId);
+}
+// After a reservation the attempt is real and must be repaired; the owner's own diagnostics
+// still say why the observation failed.
+function destructiveRepairAfterObservation(context, observed) {
+    const repair = destructiveRepairRequired(context);
+    return observed ? forwardedRefusal(uniqueDiagnostics([...repair.diagnostics, ...observed.diagnostics])) : repair;
+}
+async function publishDestructiveOutcome(context, outcome, fence) {
+    const result = await publishDrainOutcome(context, outcome, fence);
+    return result?.kind === 'refusal' ? result : undefined;
+}
+async function executeRuntimeDrain(context, adapters, topology, attempt) {
+    if (attempt.kind !== 'complete')
+        return forwardedRefusal(attempt.diagnostics);
+    const stopped = await stopRuntime({ topology, attempt, execute: (step) => adapters.execute(step) });
+    if (stopped.kind === 'unavailable')
+        return destructiveRepairRequired(context);
+    const { outcome, fence } = stopped;
+    if (stopped.kind === 'not-started')
+        return { outcome, fence };
+    const reservation = attempt.reservation;
+    if (reservation.purpose === 'down' && reservation.actions.length === 1) {
+        const invalidated = await invalidateCompletedLifecycle(context, reservation.operationBasis, reservation.generation, 'down');
+        if (invalidated)
+            return invalidated;
+    }
+    return { outcome, fence };
+}
+// Teardown removes only what it can prove is this stack's and unused, so a finished drain can
+// still leave the stack's own resources in place. Reporting `removed` then told the operator the
+// stack was gone while its containers and network stayed, so down refuses and names each one.
+function downKeptRefusal(context, observed) {
+    const kept = keptTeardownResources(observed.down);
+    if (kept === undefined)
+        return lifecycleRefusal(ENVIRONMENT_CODES.RECLAIM_ACCOUNTING_MISMATCH, 'down finished its removals, but its last resource discovery could not be classified, so it cannot confirm the stack is gone; inspect the stack with docker compose ls and docker ps --all', context.stackId);
+    if (kept.length === 0)
+        return undefined;
+    const listed = kept.slice(0, 8).map(({ kind, id, name, reason }) => `${kind} ${name} (${id}): ${reason}`).join('; ');
+    return forwardedRefusal([{
+            severity: 'error', code: ENVIRONMENT_CODES.DOWN_RESOURCES_KEPT, target: context.stackId,
+            message: `down removed what it could, but kept ${kept.length} of this stack's own resources: ${listed}${kept.length > 8 ? `; and ${kept.length - 8} more` : ''}`,
+            fix: `release each kept resource as its reason says (remove the image's other tag, stop the container still attached to the network), then run \`${lifecycleSuggestion(context, 'down')}\``,
+        }]);
+}
+async function executeDestructivePlan(context, adapters, purpose, lifecyclePlan, firstPlan, plannedFrom, recoveredReservation, recoveredRequest) {
+    if (lifecyclePlan.kind !== 'drain')
+        return forwardedRefusal(lifecyclePlan.diagnostics);
+    const issuance = consumeLifecycleIssuance(lifecyclePlan.plan);
+    if (!issuance?.drainRequest || !issuance.reclaim || issuance.reclaim.purpose !== purpose) {
+        return destructiveRepairRequired(context);
+    }
+    const request = recoveredRequest ?? lifecyclePlan.request;
+    // From here the drain owns the stack's claim: it releases it on completion, and keeps it for repair.
+    provisionalClaims.delete(context);
+    const reserved = recoveredReservation ?? await reserveDrain({ namespace: context.namespace, request });
+    if (reserved.kind !== 'complete')
+        return forwardedRefusal(reserved.diagnostics);
+    let availableReservation = reserved.reservation.completedActionCount === 0 ? undefined : reserved;
+    if (reserved.reservation.completedActionCount === 0) {
+        const runtimeAttempt = await reserveDrainAttempt({ namespace: context.namespace, reservation: reserved.reservation });
+        const runtimeOutcome = await executeRuntimeDrain(context, adapters, issuance.topology, runtimeAttempt);
+        if ('kind' in runtimeOutcome)
+            return runtimeOutcome;
+        const runtimePublished = await publishDestructiveOutcome(context, runtimeOutcome.outcome, runtimeOutcome.fence);
+        if (runtimePublished)
+            return runtimePublished;
+    }
+    let plan = firstPlan;
+    // The latest discovery: what the stack still holds once the last removal is reconciled.
+    let observed = plannedFrom;
+    while (plan.action !== null) {
+        const recovered = availableReservation ?? await recoverDrainReservation({ namespace: context.namespace, request });
+        availableReservation = undefined;
+        if (recovered.kind !== 'complete')
+            return forwardedRefusal(recovered.diagnostics);
+        const attempt = await reserveDrainAttempt({ namespace: context.namespace, reservation: recovered.reservation });
+        if (attempt.kind !== 'complete')
+            return forwardedRefusal(attempt.diagnostics);
+        const ran = await executeReclaimAction({ action: plan.action, attempt, execute: (step) => adapters.execute(step) });
+        if (ran.kind === 'unavailable')
+            return destructiveRepairRequired(context);
+        if (ran.kind === 'not-started') {
+            const published = await publishDestructiveOutcome(context, ran.outcome, ran.fence);
+            return published ?? forwardedRefusal([{
+                    severity: 'error', code: ran.code,
+                    message: 'destructive action did not start', target: context.stackId,
+                }]);
+        }
+        const postAction = await observeDestructiveReclaim(context, adapters);
+        if (!postAction || 'diagnostics' in postAction)
+            return destructiveRepairAfterObservation(context, postAction);
+        observed = postAction;
+        const reconciled = await reconcileReclaimAction({
+            executed: ran.executed,
+            discovery: purpose === 'down' ? postAction.down.discovery : postAction.reset.discovery,
+        });
+        if (reconciled.kind === 'refusal') {
+            // An already-absent target ran nothing, so the owner's reason is the whole story.
+            return ran.executed.receipt === null ? forwardedRefusal(reconciled.diagnostics) : destructiveRepairRequired(context);
+        }
+        if (purpose === 'down' && reconciled.continuation === null) {
+            const invalidated = await invalidateCompletedLifecycle(context, request.operationBasis, request.generation, 'down');
+            if (invalidated)
+                return invalidated;
+        }
+        const fence = ran.executed.fence;
+        const published = fence === null
+            ? await publishDrainOutcomeRecord(context, reconciled.outcome)
+            : await publishDestructiveOutcome(context, reconciled.outcome, fence);
+        if (published)
+            return published;
+        if (reconciled.continuation === null)
+            break;
+        // The discovery that reconciled this removal plans the next; only the coordination record
+        // moved since, by the outcome just published, so it is read again.
+        const coordination = await readState(context.namespace.paths.coordination(context.stackId));
+        if (coordination.kind !== 'complete')
+            return destructiveRepairRequired(context);
+        const next = purpose === 'down'
+            ? await planTeardown({ ...postAction.down, coordinationRecord: coordination.value,
+                expectedDiscoveryDigest: request.planDigest, continuation: reconciled.continuation })
+            : await planReset({ ...postAction.reset, coordinationRecord: coordination.value,
+                expectedCoordinationRevision: coordination.value.revision,
+                confirmationDigest: request.planDigest, continuation: reconciled.continuation });
+        if (next.kind !== 'complete')
+            return next.kind === 'refusal'
+                ? forwardedRefusal(next.diagnostics) : destructiveRepairRequired(context);
+        plan = next;
+    }
+    return purpose === 'down'
+        ? downKeptRefusal(context, observed) ?? {
+            kind: 'complete', status: 0, diagnostics: lifecyclePlan.plan.diagnostics,
+            result: { stackId: context.stackId, change: 'removed' },
+        }
+        : {
+            kind: 'complete', status: 0, diagnostics: lifecyclePlan.plan.diagnostics,
+            result: { stackId: context.stackId, change: 'reset' },
+        };
+}
+function destructivePlanningBasis(request) {
+    const runtimeStop = request?.actions.find(({ stage }) => stage === 'runtime-stop');
+    const reclaim = request?.actions.find(({ stage }) => stage === 'reclaim');
+    return {
+        generation: request?.generation ?? randomBytes(32).toString('hex'),
+        runtimeStopValidForMs: runtimeStop?.validForMs ?? 60_000,
+        reclaimValidForMs: reclaim?.validForMs ?? 60_000,
+    };
+}
+function matchesPersistedDrainRequest(planned, persisted) {
+    if (persisted === undefined)
+        return true;
+    const { expectedCoordinationRevision: plannedRevision, ...plannedWork } = planned;
+    const { expectedCoordinationRevision: persistedRevision, ...persistedWork } = persisted;
+    return plannedRevision >= persistedRevision && isDeepStrictEqual(plannedWork, persistedWork);
+}
+async function prepareDown(context, adapters, recovered) {
+    const previewObservation = await observeDestructive(context, adapters);
+    if (!previewObservation || 'diagnostics' in previewObservation)
+        return destructivePreconditionRefusal(context, previewObservation);
+    const preview = await planTeardown({ ...previewObservation.down,
+        ...(recovered ? { recoveredReservation: recovered.reservation } : {}) });
+    if (preview.kind !== 'complete')
+        return forwardedRefusal(preview.diagnostics);
+    // The plan needs a discovery after the preview's consent; the runtime the preview measured
+    // seconds ago still stands for planning the drain.
+    const observation = await observeDestructiveReclaim(context, adapters);
+    if (!observation || 'diagnostics' in observation)
+        return destructivePreconditionRefusal(context, observation);
+    return { runtime: previewObservation.runtime, ports: previewObservation.ports, observation, preview };
+}
+async function inspectDestructiveRecoveryWithRepair(context, purpose) {
+    let inspection = await inspectDestructiveDrainRecovery({
+        namespace: context.namespace, stackId: context.stackId, holderId: context.holderId, purpose,
+    });
+    if (inspection.kind !== 'repairable')
+        return inspection;
+    const terminated = await repairFencedExecution(inspection.fence);
+    if (terminated.kind !== 'complete')
+        return inspection;
+    const repaired = await settleInterruptedDrainRepair({ namespace: context.namespace, record: inspection.record, evidence: terminated.evidence });
+    if (repaired.kind !== 'complete')
+        return inspection;
+    if (!await cleanupFencedExecution(inspection.fence))
+        return inspection;
+    inspection = await inspectDestructiveDrainRecovery({
+        namespace: context.namespace, stackId: context.stackId, holderId: context.holderId, purpose,
+    });
+    return inspection;
+}
+export async function runDown(input, adapters) {
+    const loaded = await loadDestructiveContext(input, adapters);
+    if (loaded.kind !== 'complete')
+        return loaded;
+    const outcome = await settleProvisionalClaim(loaded.result, await downWithContext(loaded.result, adapters));
+    // A removed stack runs nothing a later doctor could call stale.
+    const forgotten = outcome.kind === 'complete' && outcome.result.change === 'removed' ? await forgetStackInputs(dirname(loaded.result.source.path)) : [];
+    return withLifecycleRunNotices(loaded.result, forgotten.length === 0 ? outcome : { ...outcome, diagnostics: uniqueDiagnostics([...outcome.diagnostics, ...forgotten]) });
+}
+async function downWithContext(context, adapters) {
+    const inspection = await inspectDestructiveRecoveryWithRepair(context, 'down');
+    if (inspection.kind === 'refusal')
+        return forwardedRefusal(inspection.diagnostics);
+    if (inspection.kind === 'repairable')
+        return destructiveRepairRequired(context);
+    const persistedRequest = inspection.kind === 'recoverable' ? inspection.request : undefined;
+    const recovered = persistedRequest === undefined ? undefined
+        : await recoverDrainReservation({ namespace: context.namespace, request: persistedRequest });
+    if (recovered?.kind === 'refusal')
+        return forwardedRefusal(recovered.diagnostics);
+    const prepared = await prepareDown(context, adapters, recovered);
+    if ('diagnostics' in prepared)
+        return prepared;
+    const basis = destructivePlanningBasis(persistedRequest);
+    const lifecycle = planDown({
+        runtime: prepared.runtime,
+        ports: prepared.ports,
+        reclaim: prepared.preview.envelope,
+        operationGeneration: basis.generation,
+        runtimeStopValidForMs: basis.runtimeStopValidForMs,
+        reclaimValidForMs: basis.reclaimValidForMs,
+    });
+    if (lifecycle.kind !== 'drain')
+        return forwardedRefusal(lifecycle.diagnostics);
+    if (!matchesPersistedDrainRequest(lifecycle.request, persistedRequest))
+        return destructiveRepairRequired(context);
+    const plan = await planTeardown({
+        ...prepared.observation.down,
+        expectedDiscoveryDigest: prepared.preview.discoveryDigest,
+        ...(recovered?.kind === 'complete'
+            ? { recoveredReservation: recovered.reservation }
+            : prepared.preview.consent === null ? {} : { consent: prepared.preview.consent }),
+    });
+    if (plan.kind !== 'complete')
+        return forwardedRefusal(plan.diagnostics);
+    return await executeDestructivePlan(context, adapters, 'down', lifecycle, plan, prepared.observation, recovered?.kind === 'complete' ? recovered : undefined, persistedRequest);
+}
+const privateResetSessions = new WeakMap();
+async function resetPreview(context, adapters) {
+    const observation = await observeDestructive(context, adapters);
+    if (!observation || 'diagnostics' in observation)
+        return destructivePreconditionRefusal(context, observation);
+    const preview = await planReset(observation.reset);
+    return preview.kind === 'preview' ? preview : preview.kind === 'refusal'
+        ? forwardedRefusal(preview.diagnostics) : destructivePreconditionRefusal(context, undefined);
+}
+function publicResetPreview(context, preview) {
+    return {
+        kind: 'preview', status: 0, diagnostics: [],
+        result: {
+            stackId: context.stackId, planDigest: preview.digest,
+            targets: preview.targets.map((target) => ({ ...target })),
+            noop: preview.noop,
+        },
+    };
+}
+export async function runReset(input, adapters) {
+    const loaded = await loadDestructiveContext(input, adapters);
+    if (loaded.kind !== 'complete')
+        return loaded;
+    const preview = await resetPreview(loaded.result, adapters);
+    return withLifecycleRunNotices(loaded.result, await settleProvisionalClaim(loaded.result, 'status' in preview ? preview : publicResetPreview(loaded.result, preview)));
+}
+export async function beginOperatorReset(input, adapters) {
+    const loaded = await loadDestructiveContext(input, adapters);
+    if (loaded.kind !== 'complete')
+        return loaded;
+    const context = loaded.result;
+    const preview = await resetPreview(context, adapters);
+    if ('status' in preview)
+        return withLifecycleRunNotices(context, await settleProvisionalClaim(context, preview));
+    const token = {};
+    privateResetSessions.set(token, Object.freeze({ context, adapters, preview }));
+    const session = {
+        preview: withLifecycleRunNotices(context, publicResetPreview(context, preview)),
+        decide: (decision) => continueOperatorReset(token, decision),
+    };
+    return session;
+}
+async function continueOperatorReset(token, decision) {
+    const session = privateResetSessions.get(token);
+    privateResetSessions.delete(token);
+    const unapproved = forwardedRefusal([{
+            severity: 'error', code: ENVIRONMENT_CODES.RESET_CONFIRMATION_MISMATCH,
+            message: decision === 'decline' ? 'reset was declined' : 'reset operator session is unavailable', target: 'reset',
+        }]);
+    if (!session)
+        return unapproved;
+    return settleProvisionalClaim(session.context, decision === 'approve' ? await approveOperatorReset(session) : unapproved);
+}
+async function approveOperatorReset(session) {
+    const inspection = await inspectDestructiveRecoveryWithRepair(session.context, 'reset');
+    if (inspection.kind === 'refusal')
+        return forwardedRefusal(inspection.diagnostics);
+    if (inspection.kind === 'repairable')
+        return destructiveRepairRequired(session.context);
+    const persistedRequest = inspection.kind === 'recoverable' ? inspection.request : undefined;
+    const recovered = persistedRequest === undefined ? undefined
+        : await recoverDrainReservation({ namespace: session.context.namespace, request: persistedRequest });
+    if (recovered?.kind === 'refusal')
+        return forwardedRefusal(recovered.diagnostics);
+    const observation = await observeDestructive(session.context, session.adapters);
+    if (!observation || 'diagnostics' in observation)
+        return destructivePreconditionRefusal(session.context, observation);
+    if (session.preview.noop && !persistedRequest) {
+        const noop = await planReset({
+            ...observation.reset,
+            confirmationDigest: session.preview.digest,
+            consent: session.preview.consent,
+        });
+        if (noop.kind !== 'complete' || !noop.noop || noop.action !== null) {
+            return noop.kind === 'refusal' ? forwardedRefusal(noop.diagnostics) : destructivePreconditionRefusal(session.context, undefined);
+        }
+        const finalInspection = await inspectDestructiveDrainRecovery({ namespace: session.context.namespace,
+            stackId: session.context.stackId, holderId: session.context.holderId, purpose: 'reset' });
+        if (finalInspection.kind !== 'none')
+            return finalInspection.kind === 'refusal'
+                ? forwardedRefusal(finalInspection.diagnostics) : destructiveRepairRequired(session.context);
+        return {
+            kind: 'complete', status: 0, diagnostics: [],
+            result: { stackId: session.context.stackId, change: 'unchanged' },
+        };
+    }
+    const recoveryPlan = recovered ? await planReset({ ...observation.reset,
+        confirmationDigest: persistedRequest.planDigest,
+        recoveredReservation: recovered.reservation, operatorApproval: session.preview }) : undefined;
+    if (recoveryPlan && recoveryPlan.kind !== 'complete')
+        return recoveryPlan.kind === 'refusal'
+            ? forwardedRefusal(recoveryPlan.diagnostics) : destructiveRepairRequired(session.context);
+    const basis = destructivePlanningBasis(persistedRequest);
+    const lifecycle = planResetLifecycle({
+        runtime: observation.runtime,
+        ports: observation.ports,
+        reclaim: recoveryPlan ? recoveryPlan.envelope : session.preview.envelope,
+        operationGeneration: basis.generation,
+        runtimeStopValidForMs: basis.runtimeStopValidForMs,
+        reclaimValidForMs: basis.reclaimValidForMs,
+    });
+    if (lifecycle.kind !== 'drain')
+        return forwardedRefusal(lifecycle.diagnostics);
+    if (!matchesPersistedDrainRequest(lifecycle.request, persistedRequest))
+        return destructiveRepairRequired(session.context);
+    const actionablePlan = recoveryPlan ?? await planReset({
+        ...observation.reset,
+        confirmationDigest: session.preview.digest,
+        ...(recovered?.kind === 'complete'
+            ? { recoveredReservation: recovered.reservation }
+            : { consent: session.preview.consent }),
+    });
+    if (actionablePlan.kind !== 'complete')
+        return actionablePlan.kind === 'refusal'
+            ? forwardedRefusal(actionablePlan.diagnostics) : destructiveRepairRequired(session.context);
+    const applied = await executeDestructivePlan(session.context, session.adapters, 'reset', lifecycle, actionablePlan, observation, recovered?.kind === 'complete' ? recovered : undefined, persistedRequest);
+    return applied.kind === 'complete' ? { ...applied, result: { ...applied.result,
+            targets: publicResetPreview(session.context, session.preview).result.targets } } : applied;
+}