spawnfile 0.1.13 → 0.1.17

package/dist/deployment/upReceiptTypes.d.ts

@@ -0,0 +1,137 @@
+import { z } from "zod";
+import { type OrganizationReadiness } from "./organizationReady.js";
+import { type OrganizationHandoff } from "./organizationHandoffTypes.js";
+import { type OpaqueTargetHandle } from "../target/index.js";
+/**
+ * `spawnfile.up-receipt.v1` — the machine contract `spawnfile up --json` writes to stdout
+ * (contracts.md's Spawnfile up-receipt registry row; Decision 21's Piece 4). It is thin by
+ * design: enough for a non-Docker caller (simfile's sim harness, later its supervisor) to
+ * drive lifecycle without touching Docker directly, per `contracts.md`'s rule that
+ * "Simfile -> spawnfile only through documented CLI + versioned receipts".
+ *
+ * `compiled_schedule` is populated even though nothing consumes it yet — it freezes the
+ * shape simfile's wake-diff (the expected-wake denominator oracle, see contracts.md's
+ * `simfile.run-manifest.v1` field notes) will read from later, so the receipt shape does
+ * not need to change again when that consumer lands.
+ *
+ * No credentials/tokens ever belong on this contract (contracts.md: "No credentials in
+ * exchanged artifacts") — `moltnet_base_url` is a bare URL, never an auth header/token.
+ */
+export declare const UP_RECEIPT_VERSION: "spawnfile.up-receipt.v1";
+declare const readinessStateSchema: z.ZodUnion<readonly [z.ZodLiteral<"running">, z.ZodLiteral<"exited">, z.ZodLiteral<"unknown">]>;
+export type UpReceiptReadinessState = z.infer<typeof readinessStateSchema>;
+declare const compiledScheduleEntrySchema: z.ZodObject<{
+    agent: z.ZodString;
+    cron: z.ZodString;
+}, z.core.$strict>;
+export type CompiledScheduleEntry = z.infer<typeof compiledScheduleEntrySchema>;
+/**
+ * `{agent, engine}` disclosure entry (Piece 5, Slice B): ground truth for the
+ * run-manifest's `pinned-engine` field, so a `scripted` (or any non-default)
+ * pi engine is visibly disclosed rather than an invisible test-only branch.
+ * Derived in `buildUpReceipt` from the compiled report's
+ * `container.runtime_instances[].engine_by_node_id`. Optional on the schema
+ * so existing (pre-Piece-5) receipts without this field still validate.
+ */
+declare const compiledEngineEntrySchema: z.ZodObject<{
+    agent: z.ZodString;
+    engine: z.ZodString;
+}, z.core.$strict>;
+export type CompiledEngineEntry = z.infer<typeof compiledEngineEntrySchema>;
+declare const moltnetReleaseIdentitySchema: z.ZodUnion<readonly [z.ZodObject<{
+    architecture: z.ZodUnion<readonly [z.ZodLiteral<"amd64">, z.ZodLiteral<"arm64">]>;
+    asset: z.ZodString;
+    asset_sha256: z.ZodString;
+    capabilities: z.ZodUnion<readonly [z.ZodTuple<[z.ZodLiteral<"pi-bridge">], null>, z.ZodTuple<[z.ZodLiteral<"daimon-bridge">, z.ZodLiteral<"pi-bridge">], null>]>;
+    release_version: z.ZodString;
+    source_revision: z.ZodString;
+    version: z.ZodLiteral<"spawnfile.moltnet-release-identity.v1">;
+}, z.core.$strict>, z.ZodObject<{
+    architecture: z.ZodUnion<readonly [z.ZodLiteral<"amd64">, z.ZodLiteral<"arm64">]>;
+    asset: z.ZodString;
+    asset_sha256: z.ZodString;
+    capabilities: z.ZodTuple<[z.ZodLiteral<"daimon-bridge">, z.ZodLiteral<"pi-bridge">], null>;
+    development: z.ZodObject<{
+        mode: z.ZodLiteral<"local-development">;
+        non_production: z.ZodLiteral<true>;
+        unsigned: z.ZodLiteral<true>;
+        unpublished: z.ZodLiteral<true>;
+    }, z.core.$strict>;
+    source_sha256: z.ZodString;
+    version: z.ZodLiteral<"spawnfile.moltnet-release-identity.v1">;
+}, z.core.$strict>]>;
+export type MoltnetReleaseReceiptIdentity = z.infer<typeof moltnetReleaseIdentitySchema>;
+export declare const upReceiptSchema: z.ZodPreprocess<z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.up-receipt.v1">;
+    run_id: z.ZodNullable<z.ZodString>;
+    fingerprint: z.ZodString;
+    deployment: z.ZodObject<{
+        name: z.ZodNullable<z.ZodString>;
+        container_ids: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    readiness: z.ZodObject<{
+        state: z.ZodUnion<readonly [z.ZodLiteral<"running">, z.ZodLiteral<"exited">, z.ZodLiteral<"unknown">]>;
+        moltnet_base_url: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    compiled_schedule: z.ZodArray<z.ZodObject<{
+        agent: z.ZodString;
+        cron: z.ZodString;
+    }, z.core.$strict>>;
+    engines: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        agent: z.ZodString;
+        engine: z.ZodString;
+    }, z.core.$strict>>>;
+    moltnet_release: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        architecture: z.ZodUnion<readonly [z.ZodLiteral<"amd64">, z.ZodLiteral<"arm64">]>;
+        asset: z.ZodString;
+        asset_sha256: z.ZodString;
+        capabilities: z.ZodUnion<readonly [z.ZodTuple<[z.ZodLiteral<"pi-bridge">], null>, z.ZodTuple<[z.ZodLiteral<"daimon-bridge">, z.ZodLiteral<"pi-bridge">], null>]>;
+        release_version: z.ZodString;
+        source_revision: z.ZodString;
+        version: z.ZodLiteral<"spawnfile.moltnet-release-identity.v1">;
+    }, z.core.$strict>, z.ZodObject<{
+        architecture: z.ZodUnion<readonly [z.ZodLiteral<"amd64">, z.ZodLiteral<"arm64">]>;
+        asset: z.ZodString;
+        asset_sha256: z.ZodString;
+        capabilities: z.ZodTuple<[z.ZodLiteral<"daimon-bridge">, z.ZodLiteral<"pi-bridge">], null>;
+        development: z.ZodObject<{
+            mode: z.ZodLiteral<"local-development">;
+            non_production: z.ZodLiteral<true>;
+            unsigned: z.ZodLiteral<true>;
+            unpublished: z.ZodLiteral<true>;
+        }, z.core.$strict>;
+        source_sha256: z.ZodString;
+        version: z.ZodLiteral<"spawnfile.moltnet-release-identity.v1">;
+    }, z.core.$strict>]>>;
+    organization_handoff: z.ZodOptional<z.ZodObject<{
+        binding_digest: z.ZodString;
+        deployment_handle: z.ZodString;
+        lifecycle_receipts: z.ZodObject<{
+            down: z.ZodLiteral<"spawnfile.down-receipt.v1">;
+            export: z.ZodLiteral<"spawnfile.export-index.v1">;
+            up: z.ZodLiteral<"spawnfile.up-receipt.v1">;
+        }, z.core.$strict>;
+        network_attachment_handle: z.ZodString;
+        run_id: z.ZodString;
+        selected_target_receipt_digest: z.ZodString;
+        version: z.ZodLiteral<"spawnfile.organization-handoff.v1">;
+    }, z.core.$strict>>;
+    organization_handoff_handle: z.ZodOptional<z.ZodString>;
+    organization_ready: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
+        code: z.ZodUnion<readonly [z.ZodLiteral<"organization_ready">, z.ZodLiteral<"external_moltnet">, z.ZodLiteral<"compiled_evidence_missing">, z.ZodLiteral<"unit_unavailable">, z.ZodLiteral<"unit_restarted">, z.ZodLiteral<"probe_unavailable">, z.ZodLiteral<"identity_mismatch">, z.ZodLiteral<"topology_mismatch">, z.ZodLiteral<"probe_timeout">, z.ZodLiteral<"probe_cancelled">]>;
+        compile_fingerprint: z.ZodString;
+        run_id: z.ZodNullable<z.ZodString>;
+        state: z.ZodUnion<readonly [z.ZodLiteral<"ready">, z.ZodLiteral<"pending">, z.ZodLiteral<"failed">, z.ZodLiteral<"cancelled">]>;
+        unit_id: z.ZodString;
+        version: z.ZodLiteral<"spawnfile.organization-ready.v1">;
+        world_binding_digest: z.ZodNullable<z.ZodString>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>>;
+export type UpReceipt = Omit<z.infer<typeof upReceiptSchema>, "organization_handoff" | "organization_handoff_handle" | "organization_ready"> & {
+    organization_handoff?: OrganizationHandoff;
+    organization_handoff_handle?: OpaqueTargetHandle;
+    organization_ready?: OrganizationReadiness;
+};
+export declare const parseUpReceipt: (raw: unknown) => UpReceipt;
+export {};

package/dist/deployment/upReceiptTypes.js

@@ -0,0 +1,191 @@
+import { z } from "zod";
+import { organizationReadinessSchema, parseOrganizationReadiness } from "./organizationReady.js";
+import { ORGANIZATION_HANDOFF_VERSION, parseOrganizationHandoff } from "./organizationHandoffTypes.js";
+import { assertOrdinaryJsonGraph, parseOpaqueTargetHandle } from "../target/index.js";
+/**
+ * `spawnfile.up-receipt.v1` — the machine contract `spawnfile up --json` writes to stdout
+ * (contracts.md's Spawnfile up-receipt registry row; Decision 21's Piece 4). It is thin by
+ * design: enough for a non-Docker caller (simfile's sim harness, later its supervisor) to
+ * drive lifecycle without touching Docker directly, per `contracts.md`'s rule that
+ * "Simfile -> spawnfile only through documented CLI + versioned receipts".
+ *
+ * `compiled_schedule` is populated even though nothing consumes it yet — it freezes the
+ * shape simfile's wake-diff (the expected-wake denominator oracle, see contracts.md's
+ * `simfile.run-manifest.v1` field notes) will read from later, so the receipt shape does
+ * not need to change again when that consumer lands.
+ *
+ * No credentials/tokens ever belong on this contract (contracts.md: "No credentials in
+ * exchanged artifacts") — `moltnet_base_url` is a bare URL, never an auth header/token.
+ */
+export const UP_RECEIPT_VERSION = "spawnfile.up-receipt.v1";
+const readinessStateSchema = z.union([
+    z.literal("running"),
+    z.literal("exited"),
+    z.literal("unknown")
+]);
+const compiledScheduleEntrySchema = z
+    .object({
+    agent: z.string().min(1),
+    cron: z.string().min(1)
+})
+    .strict();
+/**
+ * `{agent, engine}` disclosure entry (Piece 5, Slice B): ground truth for the
+ * run-manifest's `pinned-engine` field, so a `scripted` (or any non-default)
+ * pi engine is visibly disclosed rather than an invisible test-only branch.
+ * Derived in `buildUpReceipt` from the compiled report's
+ * `container.runtime_instances[].engine_by_node_id`. Optional on the schema
+ * so existing (pre-Piece-5) receipts without this field still validate.
+ */
+const compiledEngineEntrySchema = z
+    .object({
+    agent: z.string().min(1),
+    engine: z.string().min(1)
+})
+    .strict();
+const publishedMoltnetReleaseIdentitySchema = z.object({
+    architecture: z.union([z.literal("amd64"), z.literal("arm64")]),
+    asset: z.string().regex(/^moltnet_linux_(amd64|arm64)\.tar\.gz$/u),
+    asset_sha256: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    // Union, not replacement: moltnet v0.1.18 publishes both bridges, and every
+    // older pi-only release must still validate.
+    capabilities: z.union([
+        z.tuple([z.literal("pi-bridge")]),
+        z.tuple([z.literal("daimon-bridge"), z.literal("pi-bridge")])
+    ]),
+    release_version: z.string().regex(/^v?\d+\.\d+\.\d+(?:-\d+-g[a-f0-9]{7,40})?$/u),
+    source_revision: z.string().regex(/^[a-f0-9]{40}$/u),
+    version: z.literal("spawnfile.moltnet-release-identity.v1")
+}).strict().superRefine((value, context) => {
+    if (!value.asset.includes(`_${value.architecture}.`)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["asset"],
+            message: "Moltnet asset architecture must match identity architecture"
+        });
+    }
+    const describedRevision = value.release_version.match(/-g([a-f0-9]{7,40})$/u)?.[1];
+    if (describedRevision && !value.source_revision.startsWith(describedRevision)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["source_revision"],
+            message: "Moltnet release version must match source revision"
+        });
+    }
+});
+const localMoltnetReleaseIdentitySchema = z.object({
+    architecture: z.union([z.literal("amd64"), z.literal("arm64")]),
+    asset: z.string().regex(/^moltnet_linux_(amd64|arm64)\.tar\.gz$/u),
+    asset_sha256: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    capabilities: z.tuple([z.literal("daimon-bridge"), z.literal("pi-bridge")]),
+    development: z.object({
+        mode: z.literal("local-development"),
+        non_production: z.literal(true),
+        unsigned: z.literal(true),
+        unpublished: z.literal(true)
+    }).strict(),
+    source_sha256: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    version: z.literal("spawnfile.moltnet-release-identity.v1")
+}).strict().superRefine((value, context) => {
+    if (!value.asset.includes(`_${value.architecture}.`)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["asset"], message: "Moltnet asset architecture must match identity architecture" });
+    }
+});
+const moltnetReleaseIdentitySchema = z.union([
+    publishedMoltnetReleaseIdentitySchema,
+    localMoltnetReleaseIdentitySchema
+]);
+const organizationHandoffReceiptSchema = z.object({
+    binding_digest: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    deployment_handle: z.string().regex(/^sf-oh1-[a-f0-9]{64}$/u),
+    lifecycle_receipts: z.object({
+        down: z.literal("spawnfile.down-receipt.v1"),
+        export: z.literal("spawnfile.export-index.v1"),
+        up: z.literal(UP_RECEIPT_VERSION)
+    }).strict(),
+    network_attachment_handle: z.string().regex(/^opaque_[a-z0-9]{16,64}$/u),
+    run_id: z.string().min(1),
+    selected_target_receipt_digest: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    version: z.literal(ORGANIZATION_HANDOFF_VERSION)
+}).strict().superRefine((value, context) => {
+    try {
+        parseOrganizationHandoff(value);
+    }
+    catch {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "invalid organization handoff" });
+    }
+});
+const INVALID_JSON_GRAPH = Symbol("invalid-json-graph");
+const upReceiptObjectSchema = z
+    .object({
+    version: z.literal(UP_RECEIPT_VERSION),
+    run_id: z.string().min(1).nullable(),
+    fingerprint: z.string().min(1),
+    deployment: z
+        .object({
+        name: z.string().min(1).nullable(),
+        container_ids: z.array(z.string().min(1))
+    })
+        .strict(),
+    readiness: z
+        .object({
+        state: readinessStateSchema,
+        moltnet_base_url: z.string().min(1).nullable()
+    })
+        .strict(),
+    compiled_schedule: z.array(compiledScheduleEntrySchema),
+    engines: z.array(compiledEngineEntrySchema).optional(),
+    moltnet_release: moltnetReleaseIdentitySchema.optional(),
+    organization_handoff: organizationHandoffReceiptSchema.optional(),
+    organization_handoff_handle: z.string().optional(),
+    organization_ready: organizationReadinessSchema.optional()
+})
+    .strict()
+    .superRefine((value, context) => {
+    if (value.organization_handoff && (value.run_id === null || value.run_id !== value.organization_handoff.run_id)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["organization_handoff", "run_id"],
+            message: "organization handoff run_id must match receipt run_id"
+        });
+    }
+    if (value.organization_handoff_handle !== undefined) {
+        if (!value.organization_handoff) {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ["organization_handoff_handle"], message: "organization handoff handle requires organization handoff" });
+        }
+        try {
+            parseOpaqueTargetHandle(value.organization_handoff_handle);
+        }
+        catch {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ["organization_handoff_handle"], message: "invalid organization handoff handle" });
+        }
+    }
+});
+export const upReceiptSchema = z
+    .preprocess((value) => {
+    try {
+        assertOrdinaryJsonGraph(value);
+        return value;
+    }
+    catch {
+        return INVALID_JSON_GRAPH;
+    }
+}, upReceiptObjectSchema);
+export const parseUpReceipt = (raw) => {
+    try {
+        assertOrdinaryJsonGraph(raw);
+        const result = upReceiptSchema.safeParse(raw);
+        if (!result.success)
+            throw new TypeError();
+        const { organization_handoff: handoff, organization_handoff_handle: handoffHandle, organization_ready: readiness, ...receipt } = result.data;
+        return {
+            ...receipt,
+            ...(handoff ? { organization_handoff: parseOrganizationHandoff(handoff) } : {}),
+            ...(handoffHandle ? { organization_handoff_handle: parseOpaqueTargetHandle(handoffHandle) } : {}),
+            ...(readiness ? { organization_ready: parseOrganizationReadiness(readiness) } : {})
+        };
+    }
+    catch {
+        throw new Error(`invalid ${UP_RECEIPT_VERSION}`);
+    }
+};

package/dist/deployment/workspaceResourceMigration.d.ts

@@ -0,0 +1,55 @@
+export declare const WORKSPACE_RESOURCE_MANIFEST_VERSION: "spawnfile.workspace-resource-manifest.v1";
+export declare const WORKSPACE_RESOURCE_MIGRATION_VERSION: "spawnfile.workspace-resource-migration.v1";
+export interface WorkspaceResourceManifestFile {
+    gid: number;
+    mode: number;
+    path: string;
+    sha256: `sha256:${string}`;
+    size: number;
+    uid: number;
+}
+export interface WorkspaceResourceManifestDirectory {
+    gid: number;
+    mode: number;
+    path: string;
+    uid: number;
+}
+export interface WorkspaceResourceManifest {
+    version: typeof WORKSPACE_RESOURCE_MANIFEST_VERSION;
+    root: {
+        gid: number;
+        mode: number;
+        uid: number;
+    };
+    directories: WorkspaceResourceManifestDirectory[];
+    files: WorkspaceResourceManifestFile[];
+}
+export interface WorkspaceResourceMigrationReceipt {
+    version: typeof WORKSPACE_RESOURCE_MIGRATION_VERSION;
+    active_path: string;
+    destination_path: string;
+    manifest_sha256: `sha256:${string}`;
+    rollback: boolean;
+    source_path: string;
+    source_retained: true;
+    status: "activated" | "rolled_back";
+}
+export interface WorkspaceResourceMigrationHooks {
+    beforeActivation?: (destinationPath: string) => Promise<void>;
+    afterActivation?: (destinationPath: string) => Promise<void>;
+    afterCopy?: (temporaryPath: string) => Promise<void>;
+    activate?: (temporaryPath: string, destinationPath: string) => Promise<void>;
+    copy?: (sourcePath: string, temporaryPath: string) => Promise<void>;
+    freeBytes?: (parentPath: string) => Promise<bigint>;
+    withSourceWriteFence?: <T>(operation: () => Promise<T>) => Promise<T>;
+}
+export interface WorkspaceResourceMigrationOptions {
+    destinationPath: string;
+    hooks?: WorkspaceResourceMigrationHooks;
+    manifestPath: string;
+    resolvedIdentity: string;
+    sourceQuiesced?: boolean;
+    sourcePath: string;
+}
+export declare const migrateWorkspaceResource: (options: WorkspaceResourceMigrationOptions) => Promise<WorkspaceResourceMigrationReceipt>;
+export declare const buildWorkspaceResourceManifest: (sourcePath: string) => Promise<WorkspaceResourceManifest>;