spawnfile 0.1.12 → 0.1.14

package/dist/status/moltnetWiringProbes.js

@@ -0,0 +1,178 @@
+import path from "node:path";
+const CONTAINER_ROOTFS_ROOT = "container/rootfs";
+const MOLTNET_NODE_CONFIG_VERSION = "moltnet.node.v1";
+// src/compiler/moltnetRuntimeConfig.ts:108 — pi/daimon attachments both lower to kind "pi".
+const CONTROL_URL_PATTERN = /^http:\/\/127\.0\.0\.1:\d+\/agents\/[a-z0-9-]+\/wake$/u;
+const WIRING_KEYS = [
+    "network.wiring.node_config",
+    "network.wiring.control_url",
+    "network.wiring.network_resolves",
+    "network.wiring.membership"
+];
+const createObservation = (input) => ({
+    ...input,
+    label: `${input.severity.toUpperCase()} ${input.key}`,
+    source: "compile_report"
+});
+const missingReportObservations = () => WIRING_KEYS.map((key) => createObservation({
+    key,
+    message: `${key} was not checked: no compile report is available`,
+    severity: "unknown",
+    subject: "compile"
+}));
+// node_plans[].config_path is a container-absolute path
+// (toContainerRootfsPath, src/compiler/moltnetArtifactPaths.ts) — the
+// physical file on disk lives under the compiled output's rootfs mirror.
+const nodeConfigPhysicalPath = (outputDirectory, configPath) => path.join(outputDirectory, CONTAINER_ROOTFS_ROOT, configPath);
+const readNodePlans = async (nodePlans, outputDirectory, readFile) => Promise.all(nodePlans.map(async (plan) => {
+    if (!outputDirectory) {
+        return { networkId: plan.networkId, parsed: null, physicalPath: null };
+    }
+    const physicalPath = nodeConfigPhysicalPath(outputDirectory, plan.configPath);
+    const content = await readFile(physicalPath);
+    if (content === null) {
+        return { networkId: plan.networkId, parsed: null, physicalPath };
+    }
+    try {
+        return { networkId: plan.networkId, parsed: JSON.parse(content), physicalPath };
+    }
+    catch {
+        return { networkId: plan.networkId, parsed: null, physicalPath };
+    }
+}));
+const isValidNodeConfig = (plan) => plan.parsed !== null && plan.parsed.version === MOLTNET_NODE_CONFIG_VERSION;
+const collectNodeConfigObservations = (plans) => plans.map((plan) => {
+    const subject = `network:${plan.networkId}`;
+    if (!plan.physicalPath) {
+        return createObservation({
+            key: "network.wiring.node_config",
+            message: `${plan.networkId} node config has no compiled output directory to read from`,
+            severity: "unknown",
+            subject
+        });
+    }
+    if (plan.parsed === null) {
+        return createObservation({
+            key: "network.wiring.node_config",
+            message: `${plan.networkId} node config at ${plan.physicalPath} is unreadable or not valid JSON`,
+            severity: "error",
+            subject
+        });
+    }
+    const validVersion = isValidNodeConfig(plan);
+    return createObservation({
+        key: "network.wiring.node_config",
+        message: validVersion
+            ? `${plan.networkId} node config at ${plan.physicalPath} parses as ${MOLTNET_NODE_CONFIG_VERSION}`
+            : `${plan.networkId} node config at ${plan.physicalPath} does not declare version ${MOLTNET_NODE_CONFIG_VERSION}`,
+        severity: validVersion ? "ok" : "error",
+        subject
+    });
+});
+const collectControlUrlObservations = (plans) => {
+    const observations = [];
+    for (const plan of plans) {
+        if (!isValidNodeConfig(plan)) {
+            continue;
+        }
+        const subject = `network:${plan.networkId}`;
+        for (const attachment of plan.parsed?.attachments ?? []) {
+            const kind = attachment.runtime?.kind;
+            const agentId = typeof attachment.agent?.id === "string" ? attachment.agent.id : "unknown-agent";
+            if (kind === "pi") {
+                const controlUrl = attachment.runtime?.control_url;
+                const valid = typeof controlUrl === "string" && CONTROL_URL_PATTERN.test(controlUrl);
+                observations.push(createObservation({
+                    key: "network.wiring.control_url",
+                    message: valid
+                        ? `${agentId} control_url ${String(controlUrl)} matches the expected loopback wake pattern`
+                        : typeof controlUrl === "string"
+                            ? `${agentId} control_url "${controlUrl}" does not match the expected loopback wake pattern`
+                            : `${agentId} pi attachment is missing control_url`,
+                    severity: valid ? "ok" : "error",
+                    subject
+                }));
+            }
+            else if (kind === "picoclaw") {
+                const configPath = attachment.runtime?.config_path;
+                const valid = typeof configPath === "string" && configPath.length > 0;
+                observations.push(createObservation({
+                    key: "network.wiring.control_url",
+                    message: valid
+                        ? `${agentId} picoclaw runtime declares config_path ${String(configPath)}`
+                        : `${agentId} picoclaw attachment is missing config_path`,
+                    severity: valid ? "ok" : "error",
+                    subject
+                }));
+            }
+        }
+    }
+    return observations;
+};
+const collectNetworkResolvesObservations = (nodePlans, servers) => {
+    const serverNetworkIds = new Set(servers.map((server) => server.networkId));
+    return nodePlans.map((plan) => {
+        const resolves = serverNetworkIds.has(plan.networkId);
+        return createObservation({
+            key: "network.wiring.network_resolves",
+            message: resolves
+                ? `${plan.networkId} node plan resolves to a compiled Moltnet server plan`
+                : `${plan.networkId} node plan has no matching compiled Moltnet server plan`,
+            severity: resolves ? "ok" : "error",
+            subject: `network:${plan.networkId}`
+        });
+    });
+};
+const collectAttachmentAgentIdsByNetwork = (plans) => {
+    const idsByNetwork = new Map();
+    for (const plan of plans) {
+        if (!isValidNodeConfig(plan)) {
+            continue;
+        }
+        const ids = idsByNetwork.get(plan.networkId) ?? new Set();
+        for (const attachment of plan.parsed?.attachments ?? []) {
+            if (typeof attachment.agent?.id === "string") {
+                ids.add(attachment.agent.id);
+            }
+        }
+        idsByNetwork.set(plan.networkId, ids);
+    }
+    return idsByNetwork;
+};
+const collectMembershipObservations = (servers, plans) => {
+    const agentIdsByNetwork = collectAttachmentAgentIdsByNetwork(plans);
+    const observations = [];
+    for (const server of servers) {
+        const knownAgentIds = agentIdsByNetwork.get(server.networkId);
+        for (const room of server.rooms) {
+            const subject = `room:${server.networkId}:${room.id}`;
+            for (const memberId of room.members) {
+                const orphan = !knownAgentIds?.has(memberId);
+                observations.push(createObservation({
+                    key: "network.wiring.membership",
+                    message: orphan
+                        ? `${server.networkId}/${room.id} member ${memberId} has no matching node config attachment`
+                        : `${server.networkId}/${room.id} member ${memberId} maps to a node config attachment`,
+                    severity: orphan ? "warn" : "ok",
+                    subject
+                }));
+            }
+        }
+    }
+    return observations;
+};
+export const collectMoltnetWiringProbeObservations = async (options) => {
+    if (options.loadedReport.kind !== "loaded") {
+        return missingReportObservations();
+    }
+    const { report } = options.loadedReport;
+    const servers = report.moltnetServers ?? [];
+    const nodePlans = report.moltnetNodePlans ?? [];
+    const readPlans = await readNodePlans(nodePlans, options.outputDirectory, options.readFile);
+    return [
+        ...collectNodeConfigObservations(readPlans),
+        ...collectControlUrlObservations(readPlans),
+        ...collectNetworkResolvesObservations(nodePlans, servers),
+        ...collectMembershipObservations(servers, readPlans)
+    ];
+};

package/dist/target/cleanupRun.d.ts

@@ -0,0 +1,41 @@
+import { type OpaqueTargetHandle, type TargetResourceReceipt, type TargetResourceRequest } from "./contracts.js";
+import { type TargetJournalClaim, type TargetJournalStore } from "./journal.js";
+type CleanupRequest = Extract<TargetResourceRequest, {
+    operation: "cleanup_run";
+}>;
+export interface CleanupRunResource {
+    readonly authority: unknown;
+    readonly handle: OpaqueTargetHandle;
+}
+export interface CleanupRunPlan {
+    readonly attachment: CleanupRunResource | null;
+    readonly cleanupPolicy: CleanupRequest["cleanup_policy"];
+    readonly dataNetwork: CleanupRunResource | null;
+    readonly evidence: CleanupRunResource | null;
+    readonly exportState: "exported" | "incomplete" | "not_requested";
+    readonly secrets: CleanupRunResource | null;
+    readonly world: CleanupRunResource | null;
+}
+export interface CleanupRunOperationsOptions {
+    readonly journal: TargetJournalStore;
+    readonly prepare: (input: {
+        readonly claim: TargetJournalClaim;
+        readonly request: CleanupRequest;
+    }) => Promise<CleanupRunPlan>;
+    readonly steps: {
+        readonly detachAttachment: (resource: CleanupRunResource) => Promise<void>;
+        readonly preserveEvidence: (resource: CleanupRunResource) => Promise<void>;
+        readonly removeDataNetwork: (resource: CleanupRunResource) => Promise<void>;
+        readonly removeEvidence: (resource: CleanupRunResource) => Promise<void>;
+        readonly removeSecrets: (resource: CleanupRunResource) => Promise<void>;
+        readonly removeWorld: (resource: CleanupRunResource) => Promise<void>;
+    };
+}
+export interface CleanupRunOperations {
+    execute(raw: unknown): Promise<{
+        readonly receipt: TargetResourceReceipt;
+        readonly receiptBytes: string;
+    }>;
+}
+export declare const createCleanupRunOperations: (options: CleanupRunOperationsOptions) => CleanupRunOperations;
+export {};

package/dist/target/cleanupRun.js

@@ -0,0 +1,139 @@
+import { SpawnfileError } from "../shared/index.js";
+import { TARGET_RESOURCE_RECEIPT_VERSION, parseOpaqueTargetHandle, parseTargetResourceRequest } from "./contracts.js";
+import { createTargetReceiptDigest } from "./handles.js";
+const CLEANUP_ERROR = "Target cleanup failed";
+const fail = () => { throw new SpawnfileError("runtime_error", CLEANUP_ERROR); };
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const exactKeys = (value, expected) => {
+    const keys = Object.keys(value).sort();
+    return keys.length === expected.length && keys.every((key, index) => key === expected[index]);
+};
+const request = (raw) => {
+    const value = parseTargetResourceRequest(raw);
+    if (value.operation !== "cleanup_run"
+        || value.cleanup_policy === "preserve_evidence" && value.evidence_volume_handle === undefined)
+        return fail();
+    return value;
+};
+const resource = (raw, expected) => {
+    if (!record(raw) || !Object.isFrozen(raw) || !exactKeys(raw, ["authority", "handle"]))
+        return fail();
+    const handle = parseOpaqueTargetHandle(raw.handle);
+    if (expected !== undefined && handle !== expected)
+        return fail();
+    return raw;
+};
+const optionalResource = (raw, expected) => {
+    if (expected === undefined) {
+        if (raw !== null)
+            return fail();
+        return null;
+    }
+    return resource(raw, expected);
+};
+const plan = (raw, value) => {
+    if (!record(raw) || !Object.isFrozen(raw) || !exactKeys(raw, [
+        "attachment", "cleanupPolicy", "dataNetwork", "evidence", "exportState", "secrets", "world"
+    ]) || raw.cleanupPolicy !== value.cleanup_policy
+        || raw.exportState !== "exported" && raw.exportState !== "incomplete"
+            && raw.exportState !== "not_requested")
+        return fail();
+    const attachment = optionalResource(raw.attachment, value.organization_attachment_handle);
+    const dataNetwork = raw.dataNetwork === null ? null : resource(raw.dataNetwork);
+    const evidence = optionalResource(raw.evidence, value.evidence_volume_handle);
+    const world = optionalResource(raw.world, value.world_service_handle);
+    if ((evidence === null) !== (raw.exportState === "not_requested")
+        || dataNetwork === null && (world !== null || attachment !== null))
+        return fail();
+    return Object.freeze({
+        attachment,
+        cleanupPolicy: value.cleanup_policy,
+        dataNetwork,
+        evidence,
+        exportState: raw.exportState,
+        secrets: optionalResource(raw.secrets, value.secret_bindings_handle),
+        world
+    });
+};
+const receipt = (value, claim, prepared) => {
+    const raw = {
+        cleanup_state: value.cleanup_policy === "preserve_evidence" ? "preserved" : "removed",
+        descriptor_digest: value.descriptor_digest,
+        export_state: prepared.exportState,
+        labels: [],
+        operation: value.operation,
+        operation_handle: claim.operationHandle,
+        receipt_digest: `sha256:${"0".repeat(64)}`,
+        request_digest: claim.requestDigest,
+        result_handle: value.cleanup_policy === "preserve_evidence"
+            ? prepared.evidence.handle : null,
+        resulting_revision: value.expected_revision + 1,
+        run_id: value.run_id,
+        selected_target: value.selected_target,
+        version: TARGET_RESOURCE_RECEIPT_VERSION
+    };
+    return { ...raw, receipt_digest: createTargetReceiptDigest(raw) };
+};
+class Operations {
+    #live = new Map();
+    #options;
+    constructor(options) { this.#options = options; }
+    execute(raw) {
+        let value;
+        try {
+            value = request(raw);
+        }
+        catch {
+            return Promise.reject(new SpawnfileError("runtime_error", CLEANUP_ERROR));
+        }
+        const active = this.#live.get(value.idempotency_key);
+        if (active)
+            return same(active.request, value) ? active.promise
+                : Promise.reject(new SpawnfileError("runtime_error", CLEANUP_ERROR));
+        const promise = this.#owner(value).finally(() => {
+            if (this.#live.get(value.idempotency_key)?.promise === promise) {
+                this.#live.delete(value.idempotency_key);
+            }
+        });
+        this.#live.set(value.idempotency_key, { promise, request: value });
+        return promise;
+    }
+    async #owner(value) {
+        try {
+            const reservation = await this.#options.journal.reserve(value);
+            if (reservation.kind === "replay") {
+                return { receipt: reservation.receipt, receiptBytes: reservation.receiptBytes };
+            }
+            const prepared = plan(await this.#options.prepare({ claim: reservation.claim, request: value }), value);
+            if (prepared.world)
+                await this.#options.steps.removeWorld(prepared.world);
+            if (prepared.attachment)
+                await this.#options.steps.detachAttachment(prepared.attachment);
+            if (prepared.secrets)
+                await this.#options.steps.removeSecrets(prepared.secrets);
+            if (prepared.evidence) {
+                if (prepared.cleanupPolicy === "preserve_evidence") {
+                    await this.#options.steps.preserveEvidence(prepared.evidence);
+                }
+                else {
+                    await this.#options.steps.removeEvidence(prepared.evidence);
+                }
+            }
+            if (prepared.dataNetwork) {
+                await this.#options.steps.removeDataNetwork(prepared.dataNetwork);
+            }
+            return await this.#options.journal.complete(reservation.claim, receipt(value, reservation.claim, prepared));
+        }
+        catch {
+            return fail();
+        }
+    }
+}
+export const createCleanupRunOperations = (options) => {
+    if (!options?.journal || typeof options.journal.reserve !== "function"
+        || typeof options.journal.complete !== "function" || typeof options.prepare !== "function"
+        || !options.steps || Object.values(options.steps).some((step) => typeof step !== "function"))
+        return fail();
+    return new Operations(options);
+};

package/dist/target/cleanupRunDocker.d.ts

@@ -0,0 +1,16 @@
+import { type CleanupRunOperations } from "./cleanupRun.js";
+import { type DockerCleanupRunPreflightOptions } from "./cleanupRunDockerPreflight.js";
+import { type DockerSecretExecutor } from "./dockerSecretsProvider.js";
+import { type DockerResourceExecutor } from "./dockerResourcesProvider.js";
+import { type DockerWorldServiceExecutor } from "./dockerWorldServiceProvider.js";
+import { type DockerOrganizationAttachmentExecutor } from "./organizationAttachmentProvider.js";
+export interface DockerCleanupRunOptions extends DockerCleanupRunPreflightOptions {
+    readonly attachmentExecutor: DockerOrganizationAttachmentExecutor;
+    readonly context: string;
+    readonly resourceExecutor: DockerResourceExecutor;
+    readonly secretExecutor: DockerSecretExecutor;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs: number;
+    readonly worldExecutor: DockerWorldServiceExecutor;
+}
+export declare const createDockerCleanupRunOperations: (rawOptions: DockerCleanupRunOptions) => CleanupRunOperations;

package/dist/target/cleanupRunDocker.js

@@ -0,0 +1,66 @@
+import { SpawnfileError } from "../shared/index.js";
+import { createCleanupRunOperations } from "./cleanupRun.js";
+import { prepareDockerCleanupRun } from "./cleanupRunDockerPreflight.js";
+import { cleanupExactDockerSecretBindings } from "./dockerSecretsLifecycle.js";
+import { proveExactDockerResourcePresent, removeExactDockerResource } from "./dockerResources.js";
+import { removeExactDockerWorldService } from "./dockerWorldServiceLifecycle.js";
+import { detachExactOrganizationAttachment } from "./organizationAttachmentLifecycle.js";
+const CLEANUP_ERROR = "Target cleanup failed";
+const CONTEXT = /^[a-z][a-z0-9_-]{0,63}$/u;
+const fail = () => {
+    throw new SpawnfileError("runtime_error", CLEANUP_ERROR);
+};
+const validateOptions = (raw) => {
+    if (!raw || typeof raw.context !== "string" || !CONTEXT.test(raw.context)
+        || !Number.isSafeInteger(raw.timeoutMs) || raw.timeoutMs < 1
+        || raw.timeoutMs > 120_000 || typeof raw.attachmentExecutor !== "function"
+        || typeof raw.resourceExecutor !== "function"
+        || typeof raw.secretExecutor !== "function"
+        || typeof raw.worldExecutor !== "function" || !raw.journal
+        || typeof raw.journal.read !== "function"
+        || typeof raw.journal.resolveCompletedReceipt !== "function"
+        || !raw.attachmentStore
+        || typeof raw.attachmentStore.loadAttachment !== "function"
+        || !raw.worldStore || typeof raw.worldStore.loadService !== "function"
+        || !raw.evidenceExportStore
+        || typeof raw.evidenceExportStore.loadAdmission !== "function"
+        || typeof raw.evidenceExportStore.loadIndex !== "function")
+        return fail();
+    return raw;
+};
+export const createDockerCleanupRunOperations = (rawOptions) => {
+    const options = validateOptions(rawOptions);
+    const resourceOptions = {
+        context: options.context,
+        executor: options.resourceExecutor,
+        signal: options.signal,
+        timeoutMs: options.timeoutMs
+    };
+    return createCleanupRunOperations({
+        journal: options.journal,
+        prepare: async ({ request }) => prepareDockerCleanupRun(request, options),
+        steps: {
+            detachAttachment: async ({ authority }) => detachExactOrganizationAttachment(authority, {
+                context: options.context,
+                executor: options.attachmentExecutor,
+                signal: options.signal,
+                timeoutMs: options.timeoutMs
+            }),
+            preserveEvidence: async ({ authority }) => proveExactDockerResourcePresent(authority, resourceOptions),
+            removeDataNetwork: async ({ authority }) => removeExactDockerResource(authority, resourceOptions),
+            removeEvidence: async ({ authority }) => removeExactDockerResource(authority, resourceOptions),
+            removeSecrets: async ({ authority }) => cleanupExactDockerSecretBindings(authority, {
+                context: options.context,
+                executor: options.secretExecutor,
+                signal: options.signal,
+                timeoutMs: options.timeoutMs
+            }),
+            removeWorld: async ({ authority }) => removeExactDockerWorldService(authority, {
+                context: options.context,
+                executor: options.worldExecutor,
+                signal: options.signal,
+                timeoutMs: options.timeoutMs
+            })
+        }
+    });
+};

package/dist/target/cleanupRunDocker.test-helper.d.ts

@@ -0,0 +1,67 @@
+import { type OpaqueTargetHandle } from "./contracts.js";
+import { type DockerResourceExecutor, type DockerResourceSpec } from "./dockerResourcesProvider.js";
+import { type WorldServiceAuthorityStore } from "./dockerWorldServiceStore.js";
+import { type OrganizationAttachmentAuthorityStore } from "./organizationAttachmentStore.js";
+import { type EvidenceExportAuthorityStore } from "./evidenceExportStore.js";
+export declare const canonicalCleanupBindings: (input: {
+    readonly attachmentOperationHandle: OpaqueTargetHandle;
+    readonly attachmentRequestDigest: string;
+    readonly descriptorDigest: string;
+    readonly evidence: DockerResourceSpec;
+    readonly evidenceOperationHandle: OpaqueTargetHandle;
+    readonly evidenceRequestDigest: string;
+    readonly network: DockerResourceSpec;
+    readonly networkOperationHandle: OpaqueTargetHandle;
+    readonly networkRequestDigest: string;
+    readonly runId: string;
+    readonly secretHandle: OpaqueTargetHandle;
+    readonly selected: {
+        readonly fingerprint: string;
+        readonly handle: OpaqueTargetHandle;
+    };
+    readonly worldOperationHandle: OpaqueTargetHandle;
+    readonly worldRequestDigest: string;
+}) => {
+    attachment: import("./organizationAttachmentStore.js").OrganizationAttachmentBinding;
+    world: import("./dockerWorldServiceStore.js").WorldServiceBinding;
+};
+export declare const canonicalCleanupScenario: (input: Parameters<typeof canonicalCleanupBindings>[0]) => {
+    attachmentExecutor: (_file: string, args: string[]) => Promise<{
+        stderr: string;
+        stdout: string;
+    }>;
+    bindings: {
+        attachment: import("./organizationAttachmentStore.js").OrganizationAttachmentBinding;
+        world: import("./dockerWorldServiceStore.js").WorldServiceBinding;
+    };
+    calls: {
+        attachment: string[][];
+        secret: string[][];
+        world: string[][];
+    };
+    drift: {
+        attachment: import("./organizationAttachmentStore.js").OrganizationAttachmentBinding;
+        world: import("./dockerWorldServiceStore.js").WorldServiceBinding;
+    };
+    secretExecutor: (_file: string, args: string[]) => Promise<never>;
+    worldExecutor: (_file: string, args: string[]) => Promise<never>;
+};
+export declare const cleanupResourceExecutor: (specs: DockerResourceSpec[]) => {
+    calls: string[][];
+    executor: DockerResourceExecutor;
+    present: Set<string>;
+};
+export declare const cleanupAuthorityStores: (input?: {
+    readonly admission?: unknown;
+    readonly attachment?: unknown;
+    readonly index?: unknown;
+    readonly world?: unknown;
+}) => {
+    attachmentStore: OrganizationAttachmentAuthorityStore;
+    evidenceExportStore: EvidenceExportAuthorityStore;
+    loads: {
+        attachment: number;
+        world: number;
+    };
+    worldStore: WorldServiceAuthorityStore;
+};