spawnfile 0.1.12 → 0.1.14

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 {};

package/dist/deployment/lifecycleCompletionLookup.js

@@ -0,0 +1,88 @@
+import { SpawnfileError } from "../shared/index.js";
+import { canonicalLifecycleJson, lifecycleDigest, lifecycleIdSchema, LIFECYCLE_LOOKUP_VERSION, } from "./lifecycleCompletionContracts.js";
+import { lifecycleOwnerIsAlive } from "./lifecycleCompletionOwner.js";
+import { parseLifecycleAdmission, parseLifecycleHeartbeat, parseLifecycleTerminal, } from "./lifecycleCompletionParsing.js";
+export const findLifecycleInvocationRecord = async (id, storage) => {
+    const parsed = lifecycleIdSchema.safeParse(id);
+    if (!parsed.success)
+        refuse("invalid invocation id");
+    if ((await storage.existingRoot()) === null)
+        return null;
+    const text = await storage.read(storage.admissionPath(parsed.data));
+    return text === null ? null : parseLifecycleAdmission(text).invocation;
+};
+const refuse = (message) => {
+    throw new SpawnfileError("runtime_error", `Lifecycle completion store refused: ${message}`);
+};
+export const lookupLifecycleCompletionRecord = async (id, storage) => {
+    const parsed = lifecycleIdSchema.safeParse(id);
+    if (!parsed.success)
+        refuse("invalid invocation id");
+    const value = parsed.data;
+    if ((await storage.existingRoot()) === null)
+        return {
+            invocation_id: value,
+            status: "not_applied",
+            version: LIFECYCLE_LOOKUP_VERSION,
+        };
+    const admissionText = await storage.read(storage.admissionPath(value));
+    const completionText = await storage.read(storage.completionPath(value));
+    const recoveryText = await storage.read(storage.recoveryPath(value));
+    const heartbeatText = await storage.read(storage.heartbeatPath(value));
+    if (admissionText === null &&
+        (completionText !== null || recoveryText !== null))
+        refuse("completion without admission");
+    if (admissionText === null)
+        return {
+            invocation_id: value,
+            status: "not_applied",
+            version: LIFECYCLE_LOOKUP_VERSION,
+        };
+    const admission = parseLifecycleAdmission(admissionText);
+    if (completionText !== null) {
+        const terminal = parseLifecycleTerminal(completionText);
+        if (terminal.status === "completed") {
+            if (canonicalLifecycleJson(terminal.completion.invocation) !==
+                canonicalLifecycleJson(admission.invocation))
+                refuse("completion admission drift");
+            return {
+                invocation_digest: lifecycleDigest(terminal.completion.invocation),
+                operation: terminal.completion.invocation.operation,
+                outcome_bytes: terminal.completion.outcome_bytes,
+                status: "completed",
+                version: LIFECYCLE_LOOKUP_VERSION,
+            };
+        }
+        const ambiguous = terminal.ambiguous;
+        if (ambiguous.invocation_digest !== lifecycleDigest(admission.invocation))
+            refuse("corrupt ambiguous record");
+        return {
+            invocation_digest: ambiguous.invocation_digest,
+            operation: admission.invocation.operation,
+            reason_code: ambiguous.reason_code,
+            status: "ambiguous",
+            version: LIFECYCLE_LOOKUP_VERSION,
+        };
+    }
+    if (recoveryText !== null) {
+        const recovery = parseLifecycleAdmission(recoveryText);
+        if (canonicalLifecycleJson(recovery.invocation) !==
+            canonicalLifecycleJson(admission.invocation))
+            refuse("invocation id drift");
+        if (!lifecycleOwnerIsAlive(recovery.owner, heartbeatText ? parseLifecycleHeartbeat(heartbeatText) : null)) {
+            return {
+                invocation_digest: lifecycleDigest(admission.invocation),
+                operation: admission.invocation.operation,
+                reason_code: "recovery_owner_died",
+                status: "ambiguous",
+                version: LIFECYCLE_LOOKUP_VERSION,
+            };
+        }
+    }
+    return {
+        invocation_digest: lifecycleDigest(admission.invocation),
+        operation: admission.invocation.operation,
+        status: "pending",
+        version: LIFECYCLE_LOOKUP_VERSION,
+    };
+};

package/dist/deployment/lifecycleCompletionOwner.d.ts

@@ -0,0 +1,8 @@
+import { type LifecycleAdmission, type LifecycleInvocation, type LifecycleOwnerCapability } from "./lifecycleCompletionContracts.js";
+export declare const LIFECYCLE_LEASE_MS = 30000;
+export declare const createLifecycleAdmission: (invocation: LifecycleInvocation) => LifecycleAdmission;
+export declare const lifecycleOwnerIsAlive: (owner: LifecycleAdmission["owner"], heartbeat?: {
+    epoch: string;
+    lease_expires_at: number;
+} | null) => boolean;
+export declare const assertLifecycleOwnerCapability: (invocation: LifecycleInvocation, admitted: LifecycleAdmission, recovered: LifecycleAdmission | null, capability: LifecycleOwnerCapability) => void;

package/dist/deployment/lifecycleCompletionOwner.js

@@ -0,0 +1,31 @@
+import { randomUUID } from "node:crypto";
+import { LIFECYCLE_ADMISSION_VERSION, LIFECYCLE_OWNER_VERSION, canonicalLifecycleJson, } from "./lifecycleCompletionContracts.js";
+import { SpawnfileError } from "../shared/index.js";
+export const LIFECYCLE_LEASE_MS = 30_000;
+export const createLifecycleAdmission = (invocation) => ({
+    invocation,
+    owner: {
+        epoch: randomUUID(),
+        lease_expires_at: Date.now() + LIFECYCLE_LEASE_MS,
+        pid: process.pid,
+        version: LIFECYCLE_OWNER_VERSION,
+    },
+    version: LIFECYCLE_ADMISSION_VERSION,
+});
+export const lifecycleOwnerIsAlive = (owner, heartbeat) => {
+    const expiry = heartbeat?.epoch === owner.epoch
+        ? heartbeat.lease_expires_at
+        : owner.lease_expires_at;
+    return expiry > Date.now();
+};
+export const assertLifecycleOwnerCapability = (invocation, admitted, recovered, capability) => {
+    if (recovered &&
+        canonicalLifecycleJson(recovered.invocation) !==
+            canonicalLifecycleJson(invocation))
+        throw new SpawnfileError("runtime_error", "Lifecycle invocation id drift");
+    const active = recovered
+        ? { epoch: recovered.owner.epoch, role: "recovery" }
+        : { epoch: admitted.owner.epoch, role: "initial" };
+    if (capability?.epoch !== active.epoch || capability?.role !== active.role)
+        throw new SpawnfileError("runtime_error", "Lifecycle completion store refused: invalid owner capability");
+};

package/dist/deployment/lifecycleCompletionParsing.d.ts

@@ -0,0 +1,12 @@
+import { type LifecycleCompletion, type LifecycleAdmission, type LifecycleAmbiguousReason, type LifecycleTerminal, type LifecycleInvocation, type LifecycleHeartbeat } from "./lifecycleCompletionContracts.js";
+export declare const parseLifecycleInvocation: (raw: unknown) => LifecycleInvocation;
+export declare const parseLifecycleHeartbeat: (text: string) => LifecycleHeartbeat;
+export declare const parseLifecycleAdmission: (text: string) => LifecycleAdmission;
+export declare const parseLifecycleCompletion: (text: string) => LifecycleCompletion;
+export declare const parseLifecycleAmbiguous: (text: string) => {
+    invocation_digest: string;
+    reason_code: LifecycleAmbiguousReason;
+    version: "spawnfile.lifecycle-ambiguous.v1";
+};
+export declare const parseLifecycleTerminal: (text: string) => LifecycleTerminal;
+export declare const parseLifecycleCompletedTerminal: (text: string) => LifecycleCompletion;

package/dist/deployment/lifecycleCompletionParsing.js

@@ -0,0 +1,108 @@
+import { SpawnfileError } from "../shared/index.js";
+import { parseExportIndex } from "./artifactsExportTypes.js";
+import { parseDownReceipt } from "./downReceiptTypes.js";
+import { canonicalLifecycleJson, lifecycleAdmissionSchema, lifecycleAmbiguousSchema, lifecycleCompletionSchema, lifecycleExportOutcomeSchema, lifecycleHeartbeatSchema, lifecycleInvocationSchema, lifecycleTerminalSchema, } from "./lifecycleCompletionContracts.js";
+import { parseUpReceipt } from "./upReceiptTypes.js";
+const refuse = (message) => {
+    throw new SpawnfileError("runtime_error", `Lifecycle completion store refused: ${message}`);
+};
+export const parseLifecycleInvocation = (raw) => {
+    const parsed = lifecycleInvocationSchema.safeParse(raw);
+    if (!parsed.success)
+        refuse("invalid invocation contract");
+    return parsed.data;
+};
+export const parseLifecycleHeartbeat = (text) => {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        refuse("corrupt heartbeat");
+    }
+    const parsed = lifecycleHeartbeatSchema.safeParse(raw);
+    if (!parsed.success || `${canonicalLifecycleJson(parsed.data)}\n` !== text)
+        refuse("corrupt heartbeat");
+    return parsed.data;
+};
+export const parseLifecycleAdmission = (text) => {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        refuse("corrupt admission");
+    }
+    const parsed = lifecycleAdmissionSchema.safeParse(raw);
+    if (!parsed.success || `${canonicalLifecycleJson(parsed.data)}\n` !== text)
+        refuse("noncanonical admission");
+    return parsed.data;
+};
+export const parseLifecycleCompletion = (text) => {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        refuse("corrupt completion");
+    }
+    const parsed = lifecycleCompletionSchema.safeParse(raw);
+    if (!parsed.success || `${canonicalLifecycleJson(parsed.data)}\n` !== text)
+        refuse("corrupt completion");
+    const value = parsed.data;
+    let outcome;
+    try {
+        outcome = JSON.parse(value.outcome_bytes);
+    }
+    catch {
+        refuse("corrupt outcome");
+    }
+    if (JSON.stringify(outcome, null, 2) !== value.outcome_bytes)
+        refuse("noncanonical outcome");
+    try {
+        if (value.invocation.operation === "up")
+            parseUpReceipt(outcome);
+        else if (value.invocation.operation === "down")
+            parseDownReceipt(outcome);
+        else
+            parseExportIndex(lifecycleExportOutcomeSchema.parse(outcome).index);
+    }
+    catch {
+        refuse("outcome operation mismatch");
+    }
+    return value;
+};
+export const parseLifecycleAmbiguous = (text) => {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        refuse("corrupt ambiguous record");
+    }
+    const parsed = lifecycleAmbiguousSchema.safeParse(raw);
+    if (!parsed.success || `${canonicalLifecycleJson(parsed.data)}\n` !== text)
+        refuse("corrupt ambiguous record");
+    return parsed.data;
+};
+export const parseLifecycleTerminal = (text) => {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        refuse("corrupt terminal record");
+    }
+    const parsed = lifecycleTerminalSchema.safeParse(raw);
+    if (!parsed.success || `${canonicalLifecycleJson(parsed.data)}\n` !== text)
+        refuse("corrupt terminal record");
+    if (parsed.data.status === "completed")
+        parseLifecycleCompletion(`${canonicalLifecycleJson(parsed.data.completion)}\n`);
+    return parsed.data;
+};
+export const parseLifecycleCompletedTerminal = (text) => {
+    const terminal = parseLifecycleTerminal(text);
+    if (terminal.status !== "completed")
+        refuse("ambiguous terminal");
+    return terminal.completion;
+};

package/dist/deployment/lifecycleCompletionPaths.d.ts

@@ -0,0 +1,9 @@
+export declare const failLifecycleStore: (message: string) => never;
+export declare const resolveLifecycleCompletionDirectory: () => string;
+export declare const lifecycleRecordName: (id: string, kind: "admission" | "completion" | "evidence" | "plan" | "recovery") => string;
+export declare const resolveLifecycleCompletionPath: (id: string) => string;
+export declare const admissionPath: (id: string) => string;
+export declare const planPath: (id: string) => string;
+export declare const recoveryPath: (id: string) => string;
+export declare const evidencePath: (id: string) => string;
+export declare const heartbeatPath: (id: string) => string;

package/dist/deployment/lifecycleCompletionPaths.js

@@ -0,0 +1,16 @@
+import path from "node:path";
+import { resolveSpawnfileHome } from "../auth/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { lifecycleIdSchema } from "./lifecycleCompletionContracts.js";
+export const failLifecycleStore = (message) => {
+    throw new SpawnfileError("runtime_error", `Lifecycle completion store refused: ${message}`);
+};
+export const resolveLifecycleCompletionDirectory = () => path.join(resolveSpawnfileHome(), "lifecycle-completions");
+export const lifecycleRecordName = (id, kind) => `${lifecycleIdSchema.parse(id)}.${kind}`;
+const lifecyclePath = (id, kind) => path.join(resolveLifecycleCompletionDirectory(), lifecycleRecordName(id, kind));
+export const resolveLifecycleCompletionPath = (id) => lifecyclePath(id, "completion");
+export const admissionPath = (id) => lifecyclePath(id, "admission");
+export const planPath = (id) => lifecyclePath(id, "plan");
+export const recoveryPath = (id) => lifecyclePath(id, "recovery");
+export const evidencePath = (id) => lifecyclePath(id, "evidence");
+export const heartbeatPath = (id) => path.join(resolveLifecycleCompletionDirectory(), `${lifecycleIdSchema.parse(id)}.heartbeat`);

package/dist/deployment/lifecycleCompletionPublication.d.ts

@@ -0,0 +1,5 @@
+type RecordReader = (file: string, links?: readonly number[]) => Promise<string | null>;
+export declare const settleLifecyclePublication: (file: string) => Promise<void>;
+export declare const readSettledLifecycleRecord: (file: string, read: RecordReader) => Promise<string | null>;
+export declare const matchesSettledLifecyclePublication: (file: string, expected: string, read: RecordReader) => Promise<boolean>;
+export {};

package/dist/deployment/lifecycleCompletionPublication.js

@@ -0,0 +1,35 @@
+import { lstat } from "node:fs/promises";
+import { SpawnfileError } from "../shared/index.js";
+const refuse = (message) => {
+    throw new SpawnfileError("runtime_error", `Lifecycle completion store refused: ${message}`);
+};
+export const settleLifecyclePublication = async (file) => {
+    for (let attempt = 0; attempt < 16; attempt += 1) {
+        const info = await lstat(file).catch(() => refuse("publication changed"));
+        if (info.nlink === 1)
+            return;
+        await new Promise((resolve) => setImmediate(resolve));
+    }
+    refuse("publication did not settle");
+};
+export const readSettledLifecycleRecord = async (file, read) => {
+    const text = await read(file, [1, 2]);
+    if (text === null)
+        return null;
+    const info = await lstat(file).catch(() => refuse("publication changed"));
+    if (info.nlink === 2) {
+        await settleLifecyclePublication(file);
+        return read(file);
+    }
+    if (info.nlink !== 1)
+        refuse("unsafe record");
+    return text;
+};
+export const matchesSettledLifecyclePublication = async (file, expected, read) => {
+    const prior = await readSettledLifecycleRecord(file, read);
+    if (prior === null)
+        return false;
+    if (prior !== expected)
+        refuse("divergent immutable record");
+    return true;
+};