spawnfile 0.1.13 → 0.1.17

package/dist/deployment/index.js

@@ -1,10 +1,31 @@
+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 "./candidateDiagnostics.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 "./lifecycleUpRecords.js";
 export * from "./names.js";
+export * from "./organizationHandoffTypes.js";
+export * from "./organizationHandoffAuthorityTypes.js";
+export * from "./organizationHandoffAuthorityStore.js";
+export * from "./organizationReady.js";
+export * from "./canaryCutover.js";
+export * from "./productStateClone.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,
+});

package/dist/deployment/lifecycleCompletionContracts.d.ts

@@ -0,0 +1,224 @@
+import { z } from "zod";
+export declare const LIFECYCLE_INVOCATION_VERSION: "spawnfile.lifecycle-invocation.v1";
+export declare const LIFECYCLE_COMPLETION_VERSION: "spawnfile.lifecycle-completion.v1";
+export declare const LIFECYCLE_LOOKUP_VERSION: "spawnfile.lifecycle-lookup.v1";
+export declare const LIFECYCLE_OWNER_VERSION: "spawnfile.lifecycle-owner.v1";
+export declare const LIFECYCLE_ADMISSION_VERSION: "spawnfile.lifecycle-admission.v1";
+export declare const LIFECYCLE_AMBIGUOUS_VERSION: "spawnfile.lifecycle-ambiguous.v1";
+export declare const LIFECYCLE_TERMINAL_VERSION: "spawnfile.lifecycle-terminal.v1";
+export declare const LIFECYCLE_UP_START_VERSION: "spawnfile.lifecycle-up-start.v1";
+export declare const LIFECYCLE_UP_RESERVATION_VERSION: "spawnfile.lifecycle-up-reservation.v1";
+export declare const LIFECYCLE_UP_CLEANUP_VERSION: "spawnfile.lifecycle-up-cleanup.v1";
+export declare const LIFECYCLE_UP_EXTRA_LABELS: "image-config-labels";
+export declare const LIFECYCLE_RECORD_MAX_BYTES = 1000000;
+export declare const lifecycleIdSchema: z.ZodString;
+export declare const lifecycleInvocationSchema: z.ZodObject<{
+    correlation: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+    id: z.ZodString;
+    operation: z.ZodEnum<{
+        down: "down";
+        up: "up";
+        artifacts_export: "artifacts_export";
+    }>;
+    request_policy: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+    version: z.ZodLiteral<"spawnfile.lifecycle-invocation.v1">;
+}, z.core.$strict>;
+export type LifecycleInvocation = z.infer<typeof lifecycleInvocationSchema>;
+export declare const lifecycleOwnerSchema: z.ZodObject<{
+    epoch: z.ZodString;
+    lease_expires_at: z.ZodNumber;
+    pid: z.ZodNumber;
+    version: z.ZodLiteral<"spawnfile.lifecycle-owner.v1">;
+}, z.core.$strict>;
+export type LifecycleOwner = z.infer<typeof lifecycleOwnerSchema>;
+export declare const LIFECYCLE_HEARTBEAT_VERSION: "spawnfile.lifecycle-heartbeat.v1";
+export declare const lifecycleHeartbeatSchema: z.ZodObject<{
+    epoch: z.ZodString;
+    lease_expires_at: z.ZodNumber;
+    version: z.ZodLiteral<"spawnfile.lifecycle-heartbeat.v1">;
+}, z.core.$strict>;
+export type LifecycleHeartbeat = z.infer<typeof lifecycleHeartbeatSchema>;
+export interface LifecycleOwnerCapability {
+    epoch: string;
+    role: "initial" | "recovery";
+}
+export type LifecycleClaim = {
+    capability: LifecycleOwnerCapability;
+    status: "owner";
+} | {
+    status: "pending" | "replay";
+};
+export declare const lifecycleAdmissionSchema: z.ZodObject<{
+    invocation: z.ZodObject<{
+        correlation: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+        id: z.ZodString;
+        operation: z.ZodEnum<{
+            down: "down";
+            up: "up";
+            artifacts_export: "artifacts_export";
+        }>;
+        request_policy: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+        version: z.ZodLiteral<"spawnfile.lifecycle-invocation.v1">;
+    }, z.core.$strict>;
+    owner: z.ZodObject<{
+        epoch: z.ZodString;
+        lease_expires_at: z.ZodNumber;
+        pid: z.ZodNumber;
+        version: z.ZodLiteral<"spawnfile.lifecycle-owner.v1">;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<"spawnfile.lifecycle-admission.v1">;
+}, z.core.$strict>;
+export type LifecycleAdmission = z.infer<typeof lifecycleAdmissionSchema>;
+export declare const lifecycleAmbiguousReasonSchema: z.ZodEnum<{
+    reconciliation_ambiguous: "reconciliation_ambiguous";
+    recovery_owner_died: "recovery_owner_died";
+}>;
+export type LifecycleAmbiguousReason = z.infer<typeof lifecycleAmbiguousReasonSchema>;
+export declare const lifecycleAmbiguousSchema: z.ZodObject<{
+    invocation_digest: z.ZodString;
+    reason_code: z.ZodEnum<{
+        reconciliation_ambiguous: "reconciliation_ambiguous";
+        recovery_owner_died: "recovery_owner_died";
+    }>;
+    version: z.ZodLiteral<"spawnfile.lifecycle-ambiguous.v1">;
+}, z.core.$strict>;
+export declare const lifecycleCompletionSchema: z.ZodObject<{
+    invocation: z.ZodObject<{
+        correlation: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+        id: z.ZodString;
+        operation: z.ZodEnum<{
+            down: "down";
+            up: "up";
+            artifacts_export: "artifacts_export";
+        }>;
+        request_policy: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+        version: z.ZodLiteral<"spawnfile.lifecycle-invocation.v1">;
+    }, z.core.$strict>;
+    outcome_bytes: z.ZodString;
+    version: z.ZodLiteral<"spawnfile.lifecycle-completion.v1">;
+}, z.core.$strict>;
+export type LifecycleCompletion = z.infer<typeof lifecycleCompletionSchema>;
+export declare const lifecycleUpReservationSchema: z.ZodObject<{
+    container_name: z.ZodString;
+    docker_command: z.ZodString;
+    docker_context: z.ZodNullable<z.ZodString>;
+    invocation: z.ZodObject<{
+        correlation: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+        id: z.ZodString;
+        operation: z.ZodEnum<{
+            down: "down";
+            up: "up";
+            artifacts_export: "artifacts_export";
+        }>;
+        request_policy: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+        version: z.ZodLiteral<"spawnfile.lifecycle-invocation.v1">;
+    }, z.core.$strict>;
+    label_authority: z.ZodObject<{
+        required: z.ZodRecord<z.ZodString, z.ZodString>;
+        permitted_extra_labels: z.ZodLiteral<"image-config-labels">;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<"spawnfile.lifecycle-up-reservation.v1">;
+}, z.core.$strict>;
+export type LifecycleUpReservation = z.infer<typeof lifecycleUpReservationSchema>;
+export declare const lifecycleUpStartSchema: z.ZodObject<{
+    attempt: z.ZodNumber;
+    container_id: z.ZodString;
+    container_name: z.ZodString;
+    image_id: z.ZodString;
+    invocation: z.ZodObject<{
+        correlation: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+        id: z.ZodString;
+        operation: z.ZodEnum<{
+            down: "down";
+            up: "up";
+            artifacts_export: "artifacts_export";
+        }>;
+        request_policy: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+        version: z.ZodLiteral<"spawnfile.lifecycle-invocation.v1">;
+    }, z.core.$strict>;
+    label_authority: z.ZodObject<{
+        required: z.ZodRecord<z.ZodString, z.ZodString>;
+        permitted_extra_labels: z.ZodLiteral<"image-config-labels">;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<"spawnfile.lifecycle-up-start.v1">;
+}, z.core.$strict>;
+export type LifecycleUpStart = z.infer<typeof lifecycleUpStartSchema>;
+export declare const lifecycleUpCleanupSchema: z.ZodObject<{
+    attempt: z.ZodNumber;
+    container_id: z.ZodString;
+    invocation: z.ZodObject<{
+        correlation: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+        id: z.ZodString;
+        operation: z.ZodEnum<{
+            down: "down";
+            up: "up";
+            artifacts_export: "artifacts_export";
+        }>;
+        request_policy: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+        version: z.ZodLiteral<"spawnfile.lifecycle-invocation.v1">;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<"spawnfile.lifecycle-up-cleanup.v1">;
+}, z.core.$strict>;
+export type LifecycleUpCleanup = z.infer<typeof lifecycleUpCleanupSchema>;
+export declare const lifecycleTerminalSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    completion: z.ZodObject<{
+        invocation: z.ZodObject<{
+            correlation: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+            id: z.ZodString;
+            operation: z.ZodEnum<{
+                down: "down";
+                up: "up";
+                artifacts_export: "artifacts_export";
+            }>;
+            request_policy: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+            version: z.ZodLiteral<"spawnfile.lifecycle-invocation.v1">;
+        }, z.core.$strict>;
+        outcome_bytes: z.ZodString;
+        version: z.ZodLiteral<"spawnfile.lifecycle-completion.v1">;
+    }, z.core.$strict>;
+    status: z.ZodLiteral<"completed">;
+    version: z.ZodLiteral<"spawnfile.lifecycle-terminal.v1">;
+}, z.core.$strict>, z.ZodObject<{
+    ambiguous: z.ZodObject<{
+        invocation_digest: z.ZodString;
+        reason_code: z.ZodEnum<{
+            reconciliation_ambiguous: "reconciliation_ambiguous";
+            recovery_owner_died: "recovery_owner_died";
+        }>;
+        version: z.ZodLiteral<"spawnfile.lifecycle-ambiguous.v1">;
+    }, z.core.$strict>;
+    status: z.ZodLiteral<"ambiguous">;
+    version: z.ZodLiteral<"spawnfile.lifecycle-terminal.v1">;
+}, z.core.$strict>], "status">;
+export type LifecycleTerminal = z.infer<typeof lifecycleTerminalSchema>;
+export declare const lifecycleExportOutcomeSchema: z.ZodObject<{
+    deployment: z.ZodString;
+    failed_files: z.ZodArray<z.ZodString>;
+    index: z.ZodUnknown;
+    index_path: z.ZodString;
+    missing_optional_files: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type LifecycleLookup = {
+    invocation_id: string;
+    status: "not_applied";
+    version: typeof LIFECYCLE_LOOKUP_VERSION;
+} | {
+    invocation_digest: string;
+    operation: LifecycleInvocation["operation"];
+    outcome_bytes: string;
+    status: "completed";
+    version: typeof LIFECYCLE_LOOKUP_VERSION;
+} | {
+    invocation_digest: string;
+    operation: LifecycleInvocation["operation"];
+    status: "pending";
+    version: typeof LIFECYCLE_LOOKUP_VERSION;
+} | {
+    invocation_digest: string;
+    operation: LifecycleInvocation["operation"];
+    reason_code: LifecycleAmbiguousReason;
+    status: "ambiguous";
+    version: typeof LIFECYCLE_LOOKUP_VERSION;
+};
+export declare const canonicalLifecycleJson: (value: unknown) => string;
+export declare const lifecycleDigest: (value: unknown) => string;

package/dist/deployment/lifecycleCompletionContracts.js

@@ -0,0 +1,140 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+export const LIFECYCLE_INVOCATION_VERSION = "spawnfile.lifecycle-invocation.v1";
+export const LIFECYCLE_COMPLETION_VERSION = "spawnfile.lifecycle-completion.v1";
+export const LIFECYCLE_LOOKUP_VERSION = "spawnfile.lifecycle-lookup.v1";
+export const LIFECYCLE_OWNER_VERSION = "spawnfile.lifecycle-owner.v1";
+export const LIFECYCLE_ADMISSION_VERSION = "spawnfile.lifecycle-admission.v1";
+export const LIFECYCLE_AMBIGUOUS_VERSION = "spawnfile.lifecycle-ambiguous.v1";
+export const LIFECYCLE_TERMINAL_VERSION = "spawnfile.lifecycle-terminal.v1";
+export const LIFECYCLE_UP_START_VERSION = "spawnfile.lifecycle-up-start.v1";
+export const LIFECYCLE_UP_RESERVATION_VERSION = "spawnfile.lifecycle-up-reservation.v1";
+export const LIFECYCLE_UP_CLEANUP_VERSION = "spawnfile.lifecycle-up-cleanup.v1";
+// Docker carries an image's config labels onto a container; no other extras are allowed.
+export const LIFECYCLE_UP_EXTRA_LABELS = "image-config-labels";
+export const LIFECYCLE_RECORD_MAX_BYTES = 1_000_000;
+export const lifecycleIdSchema = z
+    .string()
+    .regex(/^lci_[a-z0-9][a-z0-9_-]{15,127}$/u);
+const scalar = z.union([
+    z.string().max(512),
+    z.boolean(),
+    z.number().finite(),
+    z.null(),
+]);
+const binding = z
+    .record(z.string().min(1).max(64), scalar)
+    .refine((value) => Object.keys(value).length <= 32);
+export const lifecycleInvocationSchema = z
+    .object({
+    correlation: binding,
+    id: lifecycleIdSchema,
+    operation: z.enum(["up", "artifacts_export", "down"]),
+    request_policy: binding,
+    version: z.literal(LIFECYCLE_INVOCATION_VERSION),
+})
+    .strict();
+export const lifecycleOwnerSchema = z
+    .object({
+    epoch: z.string().uuid(),
+    lease_expires_at: z.number().int().positive(),
+    pid: z.number().int().positive(),
+    version: z.literal(LIFECYCLE_OWNER_VERSION),
+})
+    .strict();
+export const LIFECYCLE_HEARTBEAT_VERSION = "spawnfile.lifecycle-heartbeat.v1";
+export const lifecycleHeartbeatSchema = z
+    .object({
+    epoch: z.string().uuid(),
+    lease_expires_at: z.number().int().positive(),
+    version: z.literal(LIFECYCLE_HEARTBEAT_VERSION),
+})
+    .strict();
+export const lifecycleAdmissionSchema = z
+    .object({
+    invocation: lifecycleInvocationSchema,
+    owner: lifecycleOwnerSchema,
+    version: z.literal(LIFECYCLE_ADMISSION_VERSION),
+})
+    .strict();
+export const lifecycleAmbiguousReasonSchema = z.enum([
+    "reconciliation_ambiguous",
+    "recovery_owner_died",
+]);
+export const lifecycleAmbiguousSchema = z
+    .object({
+    invocation_digest: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    reason_code: lifecycleAmbiguousReasonSchema,
+    version: z.literal(LIFECYCLE_AMBIGUOUS_VERSION),
+})
+    .strict();
+export const lifecycleCompletionSchema = z
+    .object({
+    invocation: lifecycleInvocationSchema,
+    outcome_bytes: z.string().min(1).max(LIFECYCLE_RECORD_MAX_BYTES),
+    version: z.literal(LIFECYCLE_COMPLETION_VERSION),
+})
+    .strict();
+const lifecycleUpLabelAuthoritySchema = z.object({
+    required: z.record(z.string().min(1).max(255), z.string().max(4096)),
+    permitted_extra_labels: z.literal(LIFECYCLE_UP_EXTRA_LABELS),
+}).strict();
+export const lifecycleUpReservationSchema = z.object({
+    container_name: z.string().min(1).max(255),
+    docker_command: z.string().min(1).max(4096),
+    docker_context: z.string().min(1).max(128).nullable(),
+    invocation: lifecycleInvocationSchema,
+    label_authority: lifecycleUpLabelAuthoritySchema,
+    version: z.literal(LIFECYCLE_UP_RESERVATION_VERSION),
+}).strict();
+export const lifecycleUpStartSchema = z
+    .object({
+    attempt: z.number().int().min(0).max(16),
+    container_id: z.string().regex(/^[a-f0-9]{64}$/u),
+    container_name: z.string().min(1).max(255),
+    image_id: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    invocation: lifecycleInvocationSchema,
+    label_authority: lifecycleUpLabelAuthoritySchema,
+    version: z.literal(LIFECYCLE_UP_START_VERSION),
+})
+    .strict();
+export const lifecycleUpCleanupSchema = z.object({
+    attempt: z.number().int().min(0).max(16),
+    container_id: z.string().regex(/^[a-f0-9]{64}$/u),
+    invocation: lifecycleInvocationSchema,
+    version: z.literal(LIFECYCLE_UP_CLEANUP_VERSION),
+}).strict();
+export const lifecycleTerminalSchema = z.discriminatedUnion("status", [
+    z
+        .object({
+        completion: lifecycleCompletionSchema,
+        status: z.literal("completed"),
+        version: z.literal(LIFECYCLE_TERMINAL_VERSION),
+    })
+        .strict(),
+    z
+        .object({
+        ambiguous: lifecycleAmbiguousSchema,
+        status: z.literal("ambiguous"),
+        version: z.literal(LIFECYCLE_TERMINAL_VERSION),
+    })
+        .strict(),
+]);
+export const lifecycleExportOutcomeSchema = z
+    .object({
+    deployment: z.string().min(1).max(128),
+    failed_files: z.array(z.string().min(1).max(512)).max(10_000),
+    index: z.unknown(),
+    index_path: z.string().min(1).max(4096),
+    missing_optional_files: z.array(z.string().min(1).max(512)).max(10_000),
+})
+    .strict();
+export const canonicalLifecycleJson = (value) => value === null || typeof value !== "object"
+    ? JSON.stringify(value)
+    : Array.isArray(value)
+        ? `[${value.map(canonicalLifecycleJson).join(",")}]`
+        : `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalLifecycleJson(value[key])}`)
+            .join(",")}}`;
+export const lifecycleDigest = (value) => `sha256:${createHash("sha256").update(canonicalLifecycleJson(value)).digest("hex")}`;

package/dist/deployment/lifecycleCompletionHeartbeat.d.ts

@@ -0,0 +1,2 @@
+import { type LifecycleHeartbeat } from "./lifecycleCompletionContracts.js";
+export declare const writeLifecycleHeartbeat: (directory: string, file: string, epoch: string, syncDirectory: (directory: string) => Promise<void>) => Promise<LifecycleHeartbeat>;