spawnfile 0.1.13 → 0.1.14

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,158 @@
+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_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 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,106 @@
+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_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();
+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>;

package/dist/deployment/lifecycleCompletionHeartbeat.js

@@ -0,0 +1,50 @@
+import { constants } from "node:fs";
+import { lstat, open, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { SpawnfileError } from "../shared/index.js";
+import { canonicalLifecycleJson, lifecycleHeartbeatSchema, LIFECYCLE_HEARTBEAT_VERSION, } from "./lifecycleCompletionContracts.js";
+import { LIFECYCLE_LEASE_MS } from "./lifecycleCompletionOwner.js";
+const refuse = (message) => {
+    throw new SpawnfileError("runtime_error", `Lifecycle completion store refused: ${message}`);
+};
+export const writeLifecycleHeartbeat = async (directory, file, epoch, syncDirectory) => {
+    const heartbeat = lifecycleHeartbeatSchema.parse({
+        epoch,
+        lease_expires_at: Date.now() + LIFECYCLE_LEASE_MS,
+        version: LIFECYCLE_HEARTBEAT_VERSION,
+    });
+    const final = path.join(directory, file);
+    const prior = await lstat(final).catch((error) => {
+        if (error.code !== "ENOENT")
+            refuse("unsafe heartbeat");
+        return null;
+    });
+    if (prior &&
+        (!prior.isFile() ||
+            prior.isSymbolicLink() ||
+            prior.nlink !== 1 ||
+            prior.uid !== (process.getuid?.() ?? -1) ||
+            (prior.mode & 0o777) !== 0o600))
+        refuse("unsafe heartbeat");
+    const temp = path.join(directory, `.${file}.${process.pid}.${randomUUID()}.tmp`);
+    const handle = await open(temp, constants.O_CREAT |
+        constants.O_EXCL |
+        constants.O_WRONLY |
+        constants.O_NOFOLLOW, 0o600);
+    try {
+        await handle.writeFile(`${canonicalLifecycleJson(heartbeat)}\n`, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(temp, final);
+        await syncDirectory(directory);
+    }
+    finally {
+        await unlink(temp).catch(() => undefined);
+    }
+    return heartbeat;
+};

package/dist/deployment/lifecycleCompletionLookup.d.ts

@@ -0,0 +1,18 @@
+import { type LifecycleLookup } from "./lifecycleCompletionContracts.js";
+interface LookupStorage {
+    admissionPath: (id: string) => string;
+    completionPath: (id: string) => string;
+    existingRoot: () => Promise<string | null>;
+    read: (file: string) => Promise<string | null>;
+    heartbeatPath: (id: string) => string;
+    recoveryPath: (id: string) => string;
+}
+export declare const findLifecycleInvocationRecord: (id: string, storage: Pick<LookupStorage, "admissionPath" | "existingRoot" | "read">) => 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>;
+export declare const lookupLifecycleCompletionRecord: (id: string, storage: LookupStorage) => Promise<LifecycleLookup>;
+export {};