spawnfile 0.1.12 → 0.1.14

package/dist/deployment/downDeployment.js

@@ -0,0 +1,147 @@
+import path from "node:path";
+import { fileExists, readUtf8File } from "../filesystem/index.js";
+import { REPORT_FILENAME, SpawnfileError } from "../shared/index.js";
+import { exportRunArtifacts } from "./artifactsExport.js";
+import { assertDeploymentLifecycleCorrelation, } from "./deploymentLifecycleCorrelation.js";
+import { defaultDockerTeardownExecFile, removeDockerContainer, removeDockerVolume, } from "./dockerTeardown.js";
+import { DOWN_RECEIPT_VERSION } from "./downReceiptTypes.js";
+import { initializeOrganizationHandoffAuthorityStore, } from "./organizationHandoffAuthorityStore.js";
+import { readDeploymentRecordFromOutput } from "./record.js";
+const targetRefForUnit = (unit) => unit.container_id ?? unit.container_name;
+const readCompileReport = async (compiledOutputDirectory) => {
+    const reportPath = path.join(compiledOutputDirectory, REPORT_FILENAME);
+    if (!(await fileExists(reportPath))) {
+        return null;
+    }
+    return JSON.parse(await readUtf8File(reportPath));
+};
+const explainRefusal = (deploymentName) => `Deployment "${deploymentName}" has no export-index: its durable artifacts (moltnet ` +
+    "causal log, mneme bank ledgers, daimon telemetry) have not been exported yet, and " +
+    "`spawnfile down` would destroy the container they live in before anyone reads them. " +
+    `Run \`spawnfile artifacts export --deployment ${deploymentName} --out <dir>\` first, ` +
+    "or pass `--export-to <dir>` to export-then-down in one call, or `--force` to " +
+    "deliberately discard the un-exported artifacts.";
+/** Enforces the export-before-teardown invariant (Decision 21): resolves whether this
+ * deployment's record already carries an `export_index` marker (stamped by
+ * `exportRunArtifacts` — see record.ts), and if not, either refuses, auto-exports, or
+ * (with `--force`) proceeds anyway. Returns the record `spawnfile down` should act on —
+ * re-read after an auto-export, since that call updates the record on disk. */
+const ensureExported = async (record, options) => {
+    if (record.export_index || options.force) {
+        return record;
+    }
+    const exportTo = options.exportTo;
+    if (!exportTo) {
+        throw new SpawnfileError("runtime_error", explainRefusal(options.deploymentName));
+    }
+    await exportRunArtifacts({
+        compiledOutputDirectory: options.compiledOutputDirectory,
+        deploymentName: options.deploymentName,
+        destinationDirectory: exportTo,
+        dockerCommand: options.dockerCommand,
+        // Structurally identical exec-call shape as DockerArtifactExecFile (see
+        // artifactsExportDocker.ts) — forwarded so an injected fake/override execFile covers
+        // the auto-export step too, not just container/volume removal.
+        execFile: options.execFile,
+        readerImage: options.readerImage,
+        timeoutMs: options.timeoutMs,
+    });
+    return readDeploymentRecordFromOutput(options.compiledOutputDirectory, options.deploymentName);
+};
+const closeOrganizationHandoff = async (record) => {
+    const hasPublicHandoff = record.organization_handoff !== undefined;
+    const hasPrivateHandle = record.organization_handoff_handle !== undefined;
+    if (hasPublicHandoff !== hasPrivateHandle) {
+        throw new SpawnfileError("runtime_error", "Deployment organization handoff authority is incomplete; refusing teardown");
+    }
+    if (!hasPrivateHandle ||
+        record.organization_handoff === undefined ||
+        record.organization_handoff_handle === undefined)
+        return;
+    let authority;
+    let failed = false;
+    try {
+        authority = await initializeOrganizationHandoffAuthorityStore();
+        await authority.close({
+            expectedHandoff: record.organization_handoff,
+            organizationHandoffHandle: record.organization_handoff_handle,
+        });
+    }
+    catch {
+        failed = true;
+    }
+    finally {
+        try {
+            await authority?.dispose();
+        }
+        catch {
+            failed = true;
+        }
+    }
+    if (failed) {
+        throw new SpawnfileError("runtime_error", "Unable to close organization handoff authority before deployment teardown");
+    }
+};
+/**
+ * `spawnfile down` — record-driven teardown: resolves the deployment record, enforces the
+ * export-before-teardown invariant, `docker rm -f`s every recorded container unit, and
+ * (only with `--volumes`) removes named volumes. Always returns a `spawnfile.down-
+ * receipt.v1`, even when some units/volumes failed to remove (`errors` carries the
+ * per-item failures; a partial failure is never silently swallowed, but it also never
+ * stops the rest of the teardown from being attempted).
+ */
+export const downDeployment = async (options) => {
+    const compiledOutputDirectory = path.resolve(options.compiledOutputDirectory);
+    const dockerCommand = options.dockerCommand ?? "docker";
+    const execFileImpl = options.execFile ?? defaultDockerTeardownExecFile;
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const initialRecord = await readDeploymentRecordFromOutput(compiledOutputDirectory, options.deploymentName);
+    assertDeploymentLifecycleCorrelation(initialRecord, options.expectedLifecycleCorrelation);
+    const record = await ensureExported(initialRecord, {
+        ...options,
+        compiledOutputDirectory,
+    });
+    assertDeploymentLifecycleCorrelation(record, options.expectedLifecycleCorrelation);
+    await closeOrganizationHandoff(record);
+    const runnerOptions = { dockerCommand, execFile: execFileImpl, timeoutMs };
+    const unitsStopped = [];
+    const errors = [];
+    for (const unit of record.units) {
+        const containerRef = targetRefForUnit(unit);
+        if (!containerRef) {
+            errors.push(`unit ${unit.id} has no recorded container id or name; nothing to remove`);
+            continue;
+        }
+        const outcome = await removeDockerContainer(record.target, containerRef, runnerOptions);
+        if (outcome.removed) {
+            unitsStopped.push(unit.id);
+        }
+        else {
+            errors.push(`unable to remove container ${containerRef} (unit ${unit.id}): ${outcome.error}`);
+        }
+    }
+    const report = await readCompileReport(compiledOutputDirectory);
+    const volumeNames = [
+        ...new Set((report?.container?.persistent_mounts ?? []).map((mount) => mount.volume_name)),
+    ].sort();
+    const retainedVolumes = [];
+    if (options.removeVolumes) {
+        for (const volumeName of volumeNames) {
+            const outcome = await removeDockerVolume(record.target, volumeName, runnerOptions);
+            if (!outcome.removed) {
+                errors.push(`unable to remove volume ${volumeName}: ${outcome.error}`);
+                retainedVolumes.push(volumeName);
+            }
+        }
+    }
+    else {
+        retainedVolumes.push(...volumeNames);
+    }
+    return {
+        deployment: record.name,
+        errors,
+        retained_volumes: retainedVolumes.sort(),
+        units_stopped: unitsStopped.sort(),
+        version: DOWN_RECEIPT_VERSION,
+    };
+};

package/dist/deployment/downReceiptTypes.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+/**
+ * `spawnfile.down-receipt.v1` — the machine contract `spawnfile down --json` writes to
+ * stdout (contracts.md's Spawnfile down-receipt registry row; Decision 21's Piece 4).
+ * `units_stopped` names the deployment record's own unit ids (`record.ts`'s
+ * `unit.id`, e.g. `"<deployment>-container"`), not raw Docker container ids, so a caller
+ * can cross-reference the up-receipt/deployment record without re-deriving anything.
+ * `retained_volumes` is "named volumes still present on disk after this call returns" —
+ * true whether they were never touched (the default) or survived an attempted
+ * `--volumes` removal that failed (surfaced in `errors`, not silently dropped).
+ */
+export declare const DOWN_RECEIPT_VERSION: "spawnfile.down-receipt.v1";
+export declare const downReceiptSchema: z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.down-receipt.v1">;
+    deployment: z.ZodString;
+    units_stopped: z.ZodArray<z.ZodString>;
+    retained_volumes: z.ZodArray<z.ZodString>;
+    errors: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type DownReceipt = z.infer<typeof downReceiptSchema>;
+export declare const parseDownReceipt: (raw: unknown) => DownReceipt;

package/dist/deployment/downReceiptTypes.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+/**
+ * `spawnfile.down-receipt.v1` — the machine contract `spawnfile down --json` writes to
+ * stdout (contracts.md's Spawnfile down-receipt registry row; Decision 21's Piece 4).
+ * `units_stopped` names the deployment record's own unit ids (`record.ts`'s
+ * `unit.id`, e.g. `"<deployment>-container"`), not raw Docker container ids, so a caller
+ * can cross-reference the up-receipt/deployment record without re-deriving anything.
+ * `retained_volumes` is "named volumes still present on disk after this call returns" —
+ * true whether they were never touched (the default) or survived an attempted
+ * `--volumes` removal that failed (surfaced in `errors`, not silently dropped).
+ */
+export const DOWN_RECEIPT_VERSION = "spawnfile.down-receipt.v1";
+export const downReceiptSchema = z
+    .object({
+    version: z.literal(DOWN_RECEIPT_VERSION),
+    deployment: z.string().min(1),
+    units_stopped: z.array(z.string().min(1)),
+    retained_volumes: z.array(z.string().min(1)),
+    errors: z.array(z.string().min(1))
+})
+    .strict();
+export const parseDownReceipt = (raw) => {
+    const result = downReceiptSchema.safeParse(raw);
+    if (!result.success) {
+        throw new Error(`invalid ${DOWN_RECEIPT_VERSION}: ${result.error.issues
+            .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+            .join("; ")}`);
+    }
+    return result.data;
+};

package/dist/deployment/index.d.ts

@@ -1,9 +1,26 @@
+export * from "./artifactsExport.js";
+export * from "./artifactsExportDocker.js";
+export * from "./artifactsExportPlan.js";
+export * from "./artifactsExportTypes.js";
+export * from "./privateArtifactsExport.js";
+export * from "./buildImageCacheStore.js";
 export * from "./dockerLabels.js";
 export * from "./dockerInspect.js";
 export * from "./dockerLogs.js";
 export * from "./dockerManager.js";
 export * from "./dockerProbeGateway.js";
+export * from "./dockerRecover.js";
+export * from "./dockerTeardown.js";
+export * from "./deploymentLifecycleCorrelation.js";
+export * from "./downDeployment.js";
+export * from "./downReceiptTypes.js";
 export * from "./homeStore.js";
+export * from "./lifecycleCompletion.js";
 export * from "./names.js";
+export * from "./organizationHandoffTypes.js";
+export * from "./organizationHandoffAuthorityTypes.js";
+export * from "./organizationHandoffAuthorityStore.js";
+export * from "./organizationReady.js";
 export * from "./record.js";
 export * from "./target.js";
+export * from "./upReceiptTypes.js";

package/dist/deployment/index.js

@@ -1,9 +1,27 @@
+export * from "./artifactsExport.js";
+export * from "./artifactsExportDocker.js";
+export * from "./artifactsExportPlan.js";
+export * from "./artifactsExportTypes.js";
+export * from "./privateArtifactsExport.js";
+export * from "./buildImageCacheStore.js";
 export * from "./dockerLabels.js";
 export * from "./dockerInspect.js";
 export * from "./dockerLogs.js";
 export * from "./dockerManager.js";
 export * from "./dockerProbeGateway.js";
+export * from "./dockerRecover.js";
+export * from "./dockerTeardown.js";
+export * from "./deploymentLifecycleCorrelation.js";
+export * from "./downDeployment.js";
+export * from "./downReceiptTypes.js";
 export * from "./homeStore.js";
+export * from "./lifecycleCompletion.js";
 export * from "./names.js";
+export * from "./organizationHandoffTypes.js";
+export * from "./organizationHandoffAuthorityTypes.js";
+export * from "./organizationHandoffAuthorityStore.js";
+export * from "./organizationReady.js";
 export * from "./record.js";
+// Compatibility target exports remain available from this legacy deployment barrel.
 export * from "./target.js";
+export * from "./upReceiptTypes.js";

package/dist/deployment/lifecycleCompletion.d.ts

@@ -0,0 +1,37 @@
+import { type LifecycleAmbiguousReason, type LifecycleCompletion, type LifecycleInvocation, type LifecycleOwnerCapability } from "./lifecycleCompletionContracts.js";
+import { resolveLifecycleCompletionDirectory, resolveLifecycleCompletionPath } from "./lifecycleCompletionStore.js";
+export { LIFECYCLE_COMPLETION_VERSION, LIFECYCLE_INVOCATION_VERSION, LIFECYCLE_LOOKUP_VERSION, type LifecycleCompletion, type LifecycleInvocation, type LifecycleLookup, type LifecycleOwnerCapability, } from "./lifecycleCompletionContracts.js";
+export { resolveLifecycleCompletionDirectory, resolveLifecycleCompletionPath };
+export declare const findLifecycleInvocation: (id: string) => Promise<{
+    correlation: Record<string, string | number | boolean | null>;
+    id: string;
+    operation: "down" | "up" | "artifacts_export";
+    request_policy: Record<string, string | number | boolean | null>;
+    version: "spawnfile.lifecycle-invocation.v1";
+} | null>;
+/**
+ * Durably reserves one exact effect-free lifecycle plan. Execution later
+ * promotes the same bytes to an admission or refuses id drift.
+ */
+export declare const admitLifecyclePlan: (raw: LifecycleInvocation) => Promise<LifecycleInvocation>;
+export declare const findExactLifecycleCompletion: (invocation: LifecycleInvocation) => Promise<LifecycleCompletion | null>;
+export declare const claimLifecycleInvocation: (raw: LifecycleInvocation) => Promise<{
+    readonly capability: {
+        readonly epoch: string;
+        readonly role: "initial";
+    };
+    readonly status: "owner";
+} | {
+    readonly status: "pending" | "replay";
+    readonly capability?: undefined;
+}>;
+export declare const claimLifecycleRecovery: (raw: LifecycleInvocation) => Promise<import("./lifecycleCompletionRecovery.js").LifecycleRecoveryClaim>;
+export declare const renewLifecycleOwner: (raw: LifecycleInvocation, capability: LifecycleOwnerCapability) => Promise<void>;
+export declare const recordLifecycleOutcomeEvidence: (raw: LifecycleInvocation, outcomeBytes: string, capability: LifecycleOwnerCapability, deploymentInstanceDigest: string) => Promise<void>;
+export declare const findLifecycleOutcomeEvidence: (raw: LifecycleInvocation) => Promise<{
+    completion: LifecycleCompletion;
+    deployment_instance_digest: string;
+} | null>;
+export declare const completeLifecycleInvocation: (raw: LifecycleInvocation, outcomeBytes: string, capability: LifecycleOwnerCapability) => Promise<LifecycleCompletion>;
+export declare const markLifecycleAmbiguous: (raw: LifecycleInvocation, reasonCode: LifecycleAmbiguousReason, capability: LifecycleOwnerCapability) => Promise<void>;
+export declare const lookupLifecycleCompletion: (id: string) => Promise<import("./lifecycleCompletionContracts.js").LifecycleLookup>;

package/dist/deployment/lifecycleCompletion.js

@@ -0,0 +1,236 @@
+import path from "node:path";
+import { readSettledLifecycleRecord } from "./lifecycleCompletionPublication.js";
+import { canonicalLifecycleJson, lifecycleIdSchema, LIFECYCLE_COMPLETION_VERSION, LIFECYCLE_TERMINAL_VERSION, } from "./lifecycleCompletionContracts.js";
+import { findLifecycleInvocationRecord, lookupLifecycleCompletionRecord, } from "./lifecycleCompletionLookup.js";
+import { writeLifecycleHeartbeat } from "./lifecycleCompletionHeartbeat.js";
+import { assertLifecycleOwnerCapability, createLifecycleAdmission, } from "./lifecycleCompletionOwner.js";
+import { parseLifecycleAdmission, parseLifecycleCompletedTerminal, parseLifecycleCompletion, parseLifecycleHeartbeat, parseLifecycleInvocation, } from "./lifecycleCompletionParsing.js";
+import { claimLifecycleRecoveryRecord, markLifecycleAmbiguousRecord, } from "./lifecycleCompletionRecovery.js";
+import { admissionPath, evidencePath, existingLifecycleRoot as existingRoot, failLifecycleStore as fail, heartbeatPath, lifecycleRecordName as name, lifecycleRoot as root, planPath, publishLifecycleRecord as publish, readLifecycleRecord as read, recoveryPath, resolveLifecycleCompletionDirectory, resolveLifecycleCompletionPath, syncLifecycleDirectory as sync, } from "./lifecycleCompletionStore.js";
+export { LIFECYCLE_COMPLETION_VERSION, LIFECYCLE_INVOCATION_VERSION, LIFECYCLE_LOOKUP_VERSION, } from "./lifecycleCompletionContracts.js";
+const canonical = canonicalLifecycleJson;
+export { resolveLifecycleCompletionDirectory, resolveLifecycleCompletionPath };
+const exactAdmission = async (invocation) => {
+    const text = await readSettledLifecycleRecord(admissionPath(invocation.id), read);
+    if (text === null)
+        return null;
+    const stored = parseLifecycleAdmission(text);
+    if (canonical(stored.invocation) !== canonical(invocation))
+        fail("invocation id drift");
+    return stored;
+};
+const exactCompletion = async (invocation) => {
+    const text = await readSettledLifecycleRecord(resolveLifecycleCompletionPath(invocation.id), read);
+    if (text === null)
+        return null;
+    const stored = parseLifecycleCompletedTerminal(text);
+    if (canonical(stored.invocation) !== canonical(invocation))
+        fail("invocation id drift");
+    return stored;
+};
+export const findLifecycleInvocation = (id) => (async () => {
+    const parsed = lifecycleIdSchema.safeParse(id);
+    if (!parsed.success)
+        fail("invalid invocation id");
+    if ((await existingRoot()) === null)
+        return null;
+    const value = parsed.data;
+    const admitted = await findLifecycleInvocationRecord(value, {
+        admissionPath,
+        existingRoot,
+        read: (file) => readSettledLifecycleRecord(file, read),
+    });
+    if (admitted)
+        return admitted;
+    const text = await readSettledLifecycleRecord(planPath(value), read);
+    if (text === null)
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        fail("corrupt lifecycle plan");
+    }
+    const planned = parseLifecycleInvocation(raw);
+    if (`${canonical(planned)}\n` !== text)
+        fail("corrupt lifecycle plan");
+    return planned;
+})();
+const exactPlan = async (invocation) => {
+    const text = await readSettledLifecycleRecord(planPath(invocation.id), read);
+    if (text === null)
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        fail("corrupt lifecycle plan");
+    }
+    const stored = parseLifecycleInvocation(raw);
+    if (`${canonical(stored)}\n` !== text ||
+        canonical(stored) !== canonical(invocation))
+        fail("invocation id drift");
+    return stored;
+};
+/**
+ * Durably reserves one exact effect-free lifecycle plan. Execution later
+ * promotes the same bytes to an admission or refuses id drift.
+ */
+export const admitLifecyclePlan = async (raw) => {
+    const invocation = parseLifecycleInvocation(raw);
+    const directory = await root();
+    const admitted = await exactAdmission(invocation);
+    const completed = await exactCompletion(invocation);
+    if (completed && !admitted)
+        fail("completion without admission");
+    if (admitted)
+        return invocation;
+    const content = `${canonical(invocation)}\n`;
+    await publish(directory, name(invocation.id, "plan"), content);
+    await exactPlan(invocation);
+    // Close the plan-vs-execution race: an admission published concurrently is
+    // authoritative and must contain the same invocation bytes.
+    await exactAdmission(invocation);
+    return invocation;
+};
+export const findExactLifecycleCompletion = async (invocation) => {
+    const parsed = parseLifecycleInvocation(invocation);
+    await root();
+    const admission = await exactAdmission(parsed);
+    const completion = await exactCompletion(parsed);
+    if (completion && !admission)
+        fail("completion without admission");
+    return completion;
+};
+export const claimLifecycleInvocation = async (raw) => {
+    const invocation = parseLifecycleInvocation(raw);
+    const directory = await root();
+    const admission = await exactAdmission(invocation);
+    // An existing admission is authoritative. Otherwise a prior read-only plan
+    // reserves this id and must match before we publish the first effect owner.
+    if (!admission)
+        await exactPlan(invocation);
+    const completion = await exactCompletion(invocation);
+    if (completion && !admission)
+        fail("completion without admission");
+    if (completion)
+        return { status: "replay" };
+    const createdAdmission = createLifecycleAdmission(invocation);
+    const content = `${canonical(createdAdmission)}\n`;
+    const created = await publish(directory, name(invocation.id, "admission"), content, "ignore");
+    if (created)
+        return {
+            capability: { epoch: createdAdmission.owner.epoch, role: "initial" },
+            status: "owner",
+        };
+    await exactAdmission(invocation);
+    return {
+        status: (await exactCompletion(invocation)) ? "replay" : "pending",
+    };
+};
+export const claimLifecycleRecovery = async (raw) => {
+    const invocation = parseLifecycleInvocation(raw);
+    const directory = await root();
+    return claimLifecycleRecoveryRecord(invocation, {
+        exactAdmission,
+        exactCompletion,
+        publish: (value, kind, content) => publish(directory, name(value.id, kind), content, kind === "recovery" ? "ignore" : "match"),
+        readRecovery: (value) => readSettledLifecycleRecord(recoveryPath(value.id), read),
+        readHeartbeat: async (value) => {
+            const text = await readSettledLifecycleRecord(heartbeatPath(value.id), read);
+            return text ? parseLifecycleHeartbeat(text) : null;
+        },
+    });
+};
+export const renewLifecycleOwner = async (raw, capability) => {
+    const invocation = parseLifecycleInvocation(raw);
+    const directory = await root();
+    const admitted = await exactAdmission(invocation);
+    const exactAdmitted = admitted ?? fail("missing admission");
+    const recoveryText = await readSettledLifecycleRecord(recoveryPath(invocation.id), read);
+    const recovered = recoveryText ? parseLifecycleAdmission(recoveryText) : null;
+    assertLifecycleOwnerCapability(invocation, exactAdmitted, recovered, capability);
+    await writeLifecycleHeartbeat(directory, path.basename(heartbeatPath(invocation.id)), capability.epoch, sync);
+};
+const assertActiveCapability = async (invocation, capability) => {
+    const admitted = await exactAdmission(invocation);
+    const exactAdmitted = admitted ?? fail("missing admission");
+    const recoveryText = await readSettledLifecycleRecord(recoveryPath(invocation.id), read);
+    const recovered = recoveryText ? parseLifecycleAdmission(recoveryText) : null;
+    assertLifecycleOwnerCapability(invocation, exactAdmitted, recovered, capability);
+};
+export const recordLifecycleOutcomeEvidence = async (raw, outcomeBytes, capability, deploymentInstanceDigest) => {
+    const invocation = parseLifecycleInvocation(raw);
+    const directory = await root();
+    await assertActiveCapability(invocation, capability);
+    const evidence = parseLifecycleCompletion(`${canonical({
+        invocation,
+        outcome_bytes: outcomeBytes,
+        version: LIFECYCLE_COMPLETION_VERSION,
+    })}\n`);
+    await publish(directory, name(invocation.id, "evidence"), `${canonical({
+        completion: evidence,
+        deployment_instance_digest: deploymentInstanceDigest,
+        version: "spawnfile.lifecycle-evidence.v1",
+    })}\n`);
+};
+export const findLifecycleOutcomeEvidence = async (raw) => {
+    const invocation = parseLifecycleInvocation(raw);
+    await root();
+    await exactAdmission(invocation);
+    const text = await readSettledLifecycleRecord(evidencePath(invocation.id), read);
+    if (text === null)
+        return null;
+    const rawEvidence = JSON.parse(text);
+    if (rawEvidence.version !== "spawnfile.lifecycle-evidence.v1" ||
+        typeof rawEvidence.deployment_instance_digest !== "string")
+        fail("invalid outcome evidence");
+    const deploymentInstanceDigest = rawEvidence.deployment_instance_digest;
+    const evidence = parseLifecycleCompletion(`${canonical(rawEvidence.completion)}\n`);
+    if (`${canonical(rawEvidence)}\n` !== text ||
+        canonical(evidence.invocation) !== canonical(invocation))
+        fail("invocation id drift");
+    return {
+        completion: evidence,
+        deployment_instance_digest: deploymentInstanceDigest,
+    };
+};
+export const completeLifecycleInvocation = async (raw, outcomeBytes, capability) => {
+    const invocation = parseLifecycleInvocation(raw);
+    const directory = await root();
+    await assertActiveCapability(invocation, capability);
+    const completion = parseLifecycleCompletion(`${canonical({ invocation, outcome_bytes: outcomeBytes, version: LIFECYCLE_COMPLETION_VERSION })}\n`);
+    await publish(directory, name(invocation.id, "completion"), `${canonical({
+        completion,
+        status: "completed",
+        version: LIFECYCLE_TERMINAL_VERSION,
+    })}\n`);
+    const stored = await exactCompletion(invocation);
+    if (!stored)
+        fail("missing completion");
+    return parseLifecycleCompletion(`${canonical(stored)}\n`);
+};
+export const markLifecycleAmbiguous = async (raw, reasonCode, capability) => {
+    const invocation = parseLifecycleInvocation(raw);
+    const directory = await root();
+    await markLifecycleAmbiguousRecord(invocation, reasonCode, capability, {
+        exactAdmission,
+        exactCompletion,
+        publish: (value, kind, content) => publish(directory, name(value.id, kind), content),
+        readRecovery: (value) => readSettledLifecycleRecord(recoveryPath(value.id), read),
+        readHeartbeat: async (value) => {
+            const text = await readSettledLifecycleRecord(heartbeatPath(value.id), read);
+            return text ? parseLifecycleHeartbeat(text) : null;
+        },
+    });
+};
+export const lookupLifecycleCompletion = (id) => lookupLifecycleCompletionRecord(id, {
+    admissionPath,
+    completionPath: resolveLifecycleCompletionPath,
+    existingRoot,
+    heartbeatPath,
+    read: (file) => readSettledLifecycleRecord(file, read),
+    recoveryPath,
+});