spawnfile 0.1.12 → 0.1.14

package/dist/deployment/organizationHandoffTypes.js

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { assertOrdinaryJsonGraph, parseOpaqueTargetHandle, parseRunId } from "../target/index.js";
+export const ORGANIZATION_HANDOFF_VERSION = "spawnfile.organization-handoff.v1";
+const digestSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/u);
+const lifecycleReceiptsSchema = z.object({
+    down: z.literal("spawnfile.down-receipt.v1"),
+    export: z.literal("spawnfile.export-index.v1"),
+    up: z.literal("spawnfile.up-receipt.v1")
+}).strict();
+const parseError = (label, detail) => {
+    throw new Error(`invalid ${ORGANIZATION_HANDOFF_VERSION} ${label}: ${detail}`);
+};
+export const parseCanonicalSha256Digest = (value, label = "digest") => {
+    const parsed = digestSchema.safeParse(value);
+    if (!parsed.success)
+        parseError(label, "must be a canonical sha256 digest");
+    return parsed.data;
+};
+const lifecycleReceipts = {
+    down: "spawnfile.down-receipt.v1",
+    export: "spawnfile.export-index.v1",
+    up: "spawnfile.up-receipt.v1"
+};
+const canonicalDerivationBytes = (input) => [
+    "spawnfile.organization-handoff.v1\0",
+    input.run_id,
+    input.selected_target_receipt_digest,
+    input.network_attachment_handle,
+    input.binding_digest,
+    input.lifecycle_receipts.up,
+    input.lifecycle_receipts.export,
+    input.lifecycle_receipts.down
+].join("\n");
+export const createOrganizationDeploymentHandle = (input) => `sf-oh1-${createHash("sha256").update(canonicalDerivationBytes(input), "utf8").digest("hex")}`;
+export const createOrganizationHandoff = (runId, input) => {
+    const handoff = {
+        binding_digest: parseCanonicalSha256Digest(input.bindingDigest, "binding_digest"),
+        lifecycle_receipts: lifecycleReceipts,
+        network_attachment_handle: parseOpaqueTargetHandle(input.networkAttachmentHandle),
+        run_id: parseRunId(runId),
+        selected_target_receipt_digest: parseCanonicalSha256Digest(input.selectedTargetReceiptDigest, "selected_target_receipt_digest")
+    };
+    return {
+        ...handoff,
+        deployment_handle: createOrganizationDeploymentHandle(handoff),
+        version: ORGANIZATION_HANDOFF_VERSION
+    };
+};
+const organizationHandoffSchema = z.object({
+    binding_digest: digestSchema,
+    deployment_handle: z.string().regex(/^sf-oh1-[a-f0-9]{64}$/u),
+    lifecycle_receipts: lifecycleReceiptsSchema,
+    network_attachment_handle: z.string(),
+    run_id: z.string(),
+    selected_target_receipt_digest: digestSchema,
+    version: z.literal(ORGANIZATION_HANDOFF_VERSION)
+}).strict();
+export const parseOrganizationHandoff = (value) => {
+    try {
+        assertOrdinaryJsonGraph(value);
+        const parsed = organizationHandoffSchema.safeParse(value);
+        if (!parsed.success)
+            throw new TypeError();
+        const handoff = {
+            binding_digest: parseCanonicalSha256Digest(parsed.data.binding_digest, "binding_digest"),
+            lifecycle_receipts: parsed.data.lifecycle_receipts,
+            network_attachment_handle: parseOpaqueTargetHandle(parsed.data.network_attachment_handle),
+            run_id: parseRunId(parsed.data.run_id),
+            selected_target_receipt_digest: parseCanonicalSha256Digest(parsed.data.selected_target_receipt_digest, "selected_target_receipt_digest")
+        };
+        const expectedHandle = createOrganizationDeploymentHandle(handoff);
+        if (parsed.data.deployment_handle !== expectedHandle)
+            throw new TypeError();
+        return { ...handoff, deployment_handle: expectedHandle, version: ORGANIZATION_HANDOFF_VERSION };
+    }
+    catch {
+        return parseError("artifact", "must be a bounded canonical handoff");
+    }
+};

package/dist/deployment/organizationReady.d.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import type { OrganizationReadinessEvidence } from "../compiler/organizationReadyEvidence.js";
+import type { DockerUnitInspection } from "./dockerInspect.js";
+export declare const ORGANIZATION_READY_VERSION: "spawnfile.organization-ready.v1";
+declare const codes: readonly ["organization_ready", "external_moltnet", "compiled_evidence_missing", "unit_unavailable", "unit_restarted", "probe_unavailable", "identity_mismatch", "topology_mismatch", "probe_timeout", "probe_cancelled"];
+export type OrganizationReadyCode = (typeof codes)[number];
+export type OrganizationReadyState = "ready" | "pending" | "failed" | "cancelled";
+export interface OrganizationReadiness {
+    readonly version: typeof ORGANIZATION_READY_VERSION;
+    readonly run_id: string | null;
+    readonly compile_fingerprint: string;
+    readonly unit_id: string;
+    readonly world_binding_digest: string | null;
+    readonly state: OrganizationReadyState;
+    readonly code: OrganizationReadyCode;
+    readonly reason?: string;
+}
+export interface OrganizationReadinessProbeData {
+    readonly configs: ReadonlyMap<string, string>;
+    readonly networks: readonly {
+        readonly healthOk: boolean;
+        readonly id: string;
+    }[];
+    readonly worldBindings: string | null;
+}
+export interface ReconcileOrganizationReadinessInput {
+    readonly evidence: OrganizationReadinessEvidence;
+    readonly inspection: DockerUnitInspection | null;
+    readonly record: {
+        readonly compileFingerprint: string;
+        readonly deploymentName: string;
+        readonly runId: string | null;
+        readonly unitCount: number;
+        readonly unitId: string;
+    };
+    readonly probe: OrganizationReadinessProbeData | null;
+}
+export declare const organizationReadinessSchema: 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>>;
+export declare const createOrganizationReadinessPending: (evidence: OrganizationReadinessEvidence, record: ReconcileOrganizationReadinessInput["record"]) => OrganizationReadiness;
+export declare const parseOrganizationReadiness: (value: unknown) => OrganizationReadiness;
+export declare const reconcileOrganizationReadiness: (input: ReconcileOrganizationReadinessInput) => OrganizationReadiness;
+export declare const organizationReadinessFromProbeError: (evidence: OrganizationReadinessEvidence, record: ReconcileOrganizationReadinessInput["record"], error: unknown) => OrganizationReadiness;
+export {};

package/dist/deployment/organizationReady.js

@@ -0,0 +1,200 @@
+import { createHash } from "node:crypto";
+import { types as nodeTypes } from "node:util";
+import { z } from "zod";
+export const ORGANIZATION_READY_VERSION = "spawnfile.organization-ready.v1";
+const ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/u;
+const FINGERPRINT = /^sf1:[a-f0-9]{12}$/u;
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const codes = [
+    "organization_ready",
+    "external_moltnet",
+    "compiled_evidence_missing",
+    "unit_unavailable",
+    "unit_restarted",
+    "probe_unavailable",
+    "identity_mismatch",
+    "topology_mismatch",
+    "probe_timeout",
+    "probe_cancelled"
+];
+const isPlainRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value)
+    && Object.getPrototypeOf(value) === Object.prototype && !nodeTypes.isProxy(value);
+const organizationReadinessObjectSchema = z.object({
+    code: z.union([
+        z.literal("organization_ready"), z.literal("external_moltnet"),
+        z.literal("compiled_evidence_missing"), z.literal("unit_unavailable"),
+        z.literal("unit_restarted"), z.literal("probe_unavailable"),
+        z.literal("identity_mismatch"), z.literal("topology_mismatch"),
+        z.literal("probe_timeout"), z.literal("probe_cancelled")
+    ]),
+    compile_fingerprint: z.string(),
+    run_id: z.string().nullable(),
+    state: z.union([
+        z.literal("ready"), z.literal("pending"), z.literal("failed"), z.literal("cancelled")
+    ]),
+    unit_id: z.string(),
+    version: z.literal(ORGANIZATION_READY_VERSION),
+    world_binding_digest: z.string().nullable(),
+    reason: z.string().min(1).max(512).optional()
+}).strict().superRefine((result, context) => {
+    if (!FINGERPRINT.test(result.compile_fingerprint)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["compile_fingerprint"], message: "invalid fingerprint" });
+    }
+    if (!ID.test(result.unit_id)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["unit_id"], message: "invalid unit id" });
+    }
+    if (result.run_id !== null && !ID.test(result.run_id)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["run_id"], message: "invalid run id" });
+    }
+    if (result.world_binding_digest !== null && !DIGEST.test(result.world_binding_digest)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["world_binding_digest"], message: "invalid digest" });
+    }
+    if (!validStateCode(result.state, result.code)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["state"], message: "invalid state/code combination" });
+    }
+    if (result.state === "ready" && (result.run_id === null || result.world_binding_digest === null)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["state"], message: "ready requires run_id and world_binding_digest" });
+    }
+});
+export const organizationReadinessSchema = z.preprocess((value) => isPlainRecord(value) ? value : null, organizationReadinessObjectSchema);
+const exact = (value, fields) => {
+    if (!isPlainRecord(value))
+        return null;
+    const keys = Object.keys(value);
+    return keys.length === fields.length
+        && keys.every((key) => fields.includes(key))
+        && fields.every((field) => Object.hasOwn(value, field))
+        ? value
+        : null;
+};
+const sameSet = (left, right) => left.length === right.length
+    && new Set(left).size === left.length
+    && new Set(right).size === right.length
+    && left.every((entry) => right.includes(entry));
+const create = (input) => ({
+    code: input.code,
+    compile_fingerprint: input.compileFingerprint,
+    run_id: input.runId,
+    state: input.state,
+    unit_id: input.unitId,
+    version: ORGANIZATION_READY_VERSION,
+    world_binding_digest: input.worldBindingDigest,
+    ...(input.reason ? { reason: input.reason } : {})
+});
+const correlation = (evidence, record, state, code) => create({
+    code,
+    compileFingerprint: evidence.compileFingerprint,
+    runId: record.runId,
+    state,
+    unitId: record.unitId,
+    worldBindingDigest: evidence.worldBindings?.digest ?? null
+});
+const validStateCode = (state, code) => (state === "ready" && code === "organization_ready")
+    || (state === "pending" && [
+        "external_moltnet", "compiled_evidence_missing", "unit_unavailable", "unit_restarted", "probe_unavailable"
+    ].includes(code))
+    || (state === "failed" && ["identity_mismatch", "topology_mismatch", "probe_timeout"].includes(code))
+    || (state === "cancelled" && code === "probe_cancelled");
+export const createOrganizationReadinessPending = (evidence, record) => correlation(evidence, record, "pending", evidence.hasExternalMoltnet ? "external_moltnet" : evidence.worldBindings ? "probe_unavailable" : "compiled_evidence_missing");
+export const parseOrganizationReadiness = (value) => {
+    const parsed = organizationReadinessSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new Error(`invalid ${ORGANIZATION_READY_VERSION}`);
+    }
+    const result = {
+        code: parsed.data.code,
+        compile_fingerprint: parsed.data.compile_fingerprint,
+        run_id: parsed.data.run_id,
+        state: parsed.data.state,
+        unit_id: parsed.data.unit_id,
+        version: ORGANIZATION_READY_VERSION,
+        world_binding_digest: parsed.data.world_binding_digest,
+        ...(parsed.data.reason ? { reason: parsed.data.reason } : {})
+    };
+    return result;
+};
+const hash = (content) => `sha256:${createHash("sha256").update(content).digest("hex")}`;
+const validNodeConfig = (content, expectedDigest) => {
+    if (!content || hash(content) !== expectedDigest)
+        return false;
+    try {
+        const config = JSON.parse(content);
+        return isPlainRecord(config) && config.version === "moltnet.node.v1";
+    }
+    catch {
+        return false;
+    }
+};
+const validBindings = (evidence, content) => {
+    if (!content || !evidence.worldBindings || hash(content) !== evidence.worldBindings.digest)
+        return false;
+    try {
+        const body = exact(JSON.parse(content), ["schema", "bindings"]);
+        if (!body || body.schema !== evidence.worldBindings.schema || !Array.isArray(body.bindings))
+            return false;
+        const members = body.bindings.map((entry) => {
+            const binding = exact(entry, [
+                "member", "run_id", "world_instance_id", "capability_manifest_digest", "token_env", "json", "mcp"
+            ]);
+            const member = binding ? exact(binding.member, ["id", "principal_id"]) : null;
+            return member && typeof member.id === "string" && member.principal_id === `agent:${member.id}` && ID.test(member.id)
+                ? member.id
+                : null;
+        });
+        return members.every((member) => member !== null)
+            && sameSet(members, evidence.worldBindings.assignments.map((assignment) => assignment.memberId));
+    }
+    catch {
+        return false;
+    }
+};
+export const reconcileOrganizationReadiness = (input) => {
+    const { evidence, inspection, record } = input;
+    if (evidence.hasExternalMoltnet)
+        return correlation(evidence, record, "pending", "external_moltnet");
+    if (!evidence.worldBindings || !record.runId)
+        return correlation(evidence, record, "pending", "compiled_evidence_missing");
+    if (record.unitCount !== 1 || !inspection || inspection.running !== true || inspection.exists !== true) {
+        return correlation(evidence, record, "pending", "unit_unavailable");
+    }
+    if (inspection.restartCount !== 0)
+        return correlation(evidence, record, "pending", "unit_restarted");
+    const identity = inspection.identity;
+    if (!identity)
+        return correlation(evidence, record, "pending", "probe_unavailable");
+    if (inspection.drift.length > 0 || record.compileFingerprint !== evidence.compileFingerprint
+        || identity.compileFingerprint !== evidence.compileFingerprint || identity.deployment !== record.deploymentName
+        || identity.project !== evidence.projectLabel || identity.runId !== record.runId
+        || identity.unit !== record.unitId || identity.version !== evidence.compileVersion) {
+        return correlation(evidence, record, "failed", "identity_mismatch");
+    }
+    if (!input.probe || input.probe.networks.length !== evidence.networks.length
+        || !evidence.networks.every((network) => {
+            const live = input.probe?.networks.find((candidate) => candidate.id === network.id);
+            return live?.healthOk === true;
+        })
+        || !evidence.networks.every((network) => network.nodes.every((node) => validNodeConfig(input.probe.configs.get(node.configPath), node.sha256)))
+        || !validBindings(evidence, input.probe.worldBindings)) {
+        return correlation(evidence, record, "failed", "topology_mismatch");
+    }
+    return correlation(evidence, record, "ready", "organization_ready");
+};
+export const organizationReadinessFromProbeError = (evidence, record, error) => {
+    const name = error instanceof Error ? error.name : "";
+    const message = error instanceof Error ? error.message : "";
+    if (name === "TimeoutError" || /timeout|timed out/iu.test(message)) {
+        return { ...correlation(evidence, record, "failed", "probe_timeout"), reason: boundedReadinessReason(message) };
+    }
+    if (name === "AbortError" || /cancel|abort/iu.test(message)) {
+        return { ...correlation(evidence, record, "cancelled", "probe_cancelled"), reason: boundedReadinessReason(message) };
+    }
+    if (/\bHTTP 4\d{2}\b/iu.test(message)) {
+        return { ...correlation(evidence, record, "failed", "topology_mismatch"), reason: boundedReadinessReason(message) };
+    }
+    return { ...correlation(evidence, record, "pending", "probe_unavailable"), reason: boundedReadinessReason(message) };
+};
+const boundedReadinessReason = (message) => message
+    .replace(/\s+/gu, " ")
+    .replace(/(bearer|token|password|passwd|secret|authorization)[=: ]+(?:bearer[ ]+)?[^ ]+/giu, "$1=[redacted]")
+    .replace(/https?:\/\/[^ ]+/giu, "[url redacted]")
+    .slice(0, 512) || "probe unavailable";

package/dist/deployment/privateArtifactsExport.d.ts

@@ -0,0 +1,18 @@
+import type { CompileReport } from "../report/index.js";
+import { type DockerArtifactExecFile } from "./artifactsExportDocker.js";
+import type { ExportIndexFile } from "./artifactsExportTypes.js";
+import type { DeploymentRecord } from "./record.js";
+export interface PrivateArtifactsExportResult {
+    readonly files: readonly ExportIndexFile[];
+    readonly missing: readonly string[];
+}
+/** Explicit opt-in egress for unredacted runtime training artifacts. */
+export declare const exportPrivateRuntimeArtifacts: (input: Readonly<{
+    containerRef: string;
+    destinationDirectory: string;
+    dockerCommand: string;
+    execFile: DockerArtifactExecFile;
+    report: CompileReport;
+    target: DeploymentRecord["target"];
+    timeoutMs: number;
+}>) => Promise<PrivateArtifactsExportResult>;

package/dist/deployment/privateArtifactsExport.js

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { ensureDirectory } from "../filesystem/index.js";
+import { copyContainerFileToHost, } from "./artifactsExportDocker.js";
+const plans = (report) => (report.container?.runtime_instances ?? [])
+    .filter((instance) => (instance.runtime === "pi" || instance.runtime === "daimon")
+    && instance.home_path !== null)
+    .flatMap((instance) => {
+    const instanceRoot = path.posix.dirname(instance.home_path);
+    return (instance.node_ids ?? [])
+        .filter((nodeId) => nodeId.startsWith("agent:"))
+        .map((nodeId) => nodeId.slice("agent:".length))
+        .filter((slug) => /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(slug))
+        .map((slug) => Object.freeze({
+        containerPath: `${instanceRoot}/runtime/agents/${slug}/private-training/pi/raw`,
+        relativePath: `private/daimon/${slug}/private-training/pi/raw`,
+    }));
+});
+const filesUnder = async (root) => {
+    if (!(await lstat(root)).isDirectory()) {
+        throw new Error("Private artifact export source is not a directory");
+    }
+    const files = [];
+    const pending = [root];
+    while (pending.length > 0) {
+        const directory = pending.pop();
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const child = path.join(directory, entry.name);
+            if (entry.isSymbolicLink() || !entry.isDirectory() && !entry.isFile()) {
+                throw new Error("Private artifact export rejects non-regular entries");
+            }
+            if (entry.isDirectory())
+                pending.push(child);
+            else
+                files.push(path.relative(root, child).split(path.sep).join("/"));
+        }
+    }
+    return Object.freeze(files.sort());
+};
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** Explicit opt-in egress for unredacted runtime training artifacts. */
+export const exportPrivateRuntimeArtifacts = async (input) => {
+    const output = [];
+    const missing = [];
+    for (const plan of plans(input.report)) {
+        const destination = path.join(input.destinationDirectory, ...plan.relativePath.split("/"));
+        await ensureDirectory(path.dirname(destination));
+        const copied = await copyContainerFileToHost({
+            containerPath: plan.containerPath,
+            containerRef: input.containerRef,
+            dockerCommand: input.dockerCommand,
+            execFile: input.execFile,
+            hostPath: destination,
+            target: input.target,
+            timeoutMs: input.timeoutMs,
+        });
+        if (!copied) {
+            await rm(destination, { force: true, recursive: true });
+            missing.push(plan.relativePath);
+            continue;
+        }
+        for (const relative of await filesUnder(destination)) {
+            const bytes = await readFile(path.join(destination, ...relative.split("/")));
+            output.push({
+                bytes: bytes.byteLength,
+                path: `${plan.relativePath}/${relative}`,
+                sha256: digest(bytes),
+                source: {
+                    kind: "container",
+                    ref: `${input.containerRef}:${plan.containerPath}/${relative}`,
+                },
+            });
+        }
+    }
+    return Object.freeze({
+        files: Object.freeze(output),
+        missing: Object.freeze(missing),
+    });
+};

package/dist/deployment/providerRuntimeBoundaryScanner.test-helper.d.ts

@@ -0,0 +1,8 @@
+export type ProviderRuntimeViolationKind = "moltnet-live-endpoint" | "provider-authenticated-http" | "docker-exec-http-transport" | "transport-receipt" | "generated-client" | "cursor-operation";
+export type ProviderRuntimeViolation = {
+    classification: ProviderRuntimeViolationKind;
+    file: string;
+    matched: string;
+};
+export declare const scanProviderRuntimeSource: (source: string, file?: string) => ProviderRuntimeViolation[];
+export declare const scanProviderRuntimeTree: (repositoryRoot: string) => Promise<ProviderRuntimeViolation[]>;

package/dist/deployment/providerRuntimeBoundaryScanner.test-helper.js

@@ -0,0 +1,60 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+const forbiddenIdentifiers = [
+    ["transport-receipt", /spawnfile\.moltnet-transport/u],
+    ["transport-receipt", /ContainedMoltnetTransport/u],
+    ["generated-client", /CONTAINED_MOLTNET_CLIENT/u],
+    ["generated-client", /SendMessageRequest/u],
+    ["cursor-operation", /ListRoomMessages/u]
+];
+const productionFiles = async (directory) => {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const nested = await Promise.all(entries.map(async (entry) => {
+        const file = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            return productionFiles(file);
+        if (!entry.isFile() || !entry.name.endsWith(".ts") || entry.name.endsWith(".test.ts") || entry.name.endsWith(".test-helper.ts"))
+            return [];
+        return [file];
+    }));
+    return nested.flat();
+};
+const violationsForSource = (source, file) => {
+    const violations = [];
+    for (const endpoint of ["/v1/messages", "/v1/network", "/v1/rooms", "/v1/agents"]) {
+        if (source.includes(endpoint))
+            violations.push({ classification: "moltnet-live-endpoint", file, matched: endpoint });
+    }
+    const providerSurface = /(?:fetch|httpGet|curl)[\s\S]*(?:\/healthz|\/v1\/)/u.test(source)
+        || /(?:\/healthz|\/v1\/)[\s\S]*(?:fetch|httpGet|curl)/u.test(source);
+    const authenticatedMarker = [
+        [/\bAuthorization\s*:/u, "Authorization property"],
+        [/["']Authorization["']\s*:/u, "Authorization string key"],
+        [/\[\s*["']Authorization["']\s*\]\s*=/u, "Authorization element assignment"],
+        [/`Bearer\s+/u, "Bearer template"],
+        [/["']Bearer\s+["']\s*\+/u, "Bearer concatenation"],
+        [/["']Bearer\s+/u, "Bearer literal"]
+    ].find(([pattern]) => pattern.test(source));
+    if (providerSurface && authenticatedMarker) {
+        violations.push({
+            classification: "provider-authenticated-http",
+            file,
+            matched: authenticatedMarker[1]
+        });
+    }
+    if (/(?:exec\s*\(\s*\[\s*["'](?:curl|wget)["'])|(?:["']exec["'][\s\S]{0,160}["'](?:curl|wget)["'])/u.test(source)) {
+        violations.push({ classification: "docker-exec-http-transport", file, matched: "exec curl/wget" });
+    }
+    for (const [classification, pattern] of forbiddenIdentifiers) {
+        if (pattern.test(source))
+            violations.push({ classification, file, matched: pattern.source });
+    }
+    return violations;
+};
+export const scanProviderRuntimeSource = (source, file = "synthetic.ts") => violationsForSource(source, file);
+export const scanProviderRuntimeTree = async (repositoryRoot) => {
+    const roots = ["cli", "compiler", "deployment", "status"].map((folder) => path.join(repositoryRoot, "src", folder));
+    const files = (await Promise.all(roots.map(productionFiles))).flat();
+    const results = await Promise.all(files.map(async (file) => violationsForSource(await readFile(file, "utf8"), path.relative(repositoryRoot, file))));
+    return results.flat();
+};

package/dist/deployment/record.d.ts

@@ -1,4 +1,7 @@
 import { z } from "zod";
+import { type OrganizationHandoff } from "./organizationHandoffTypes.js";
+import { type OpaqueTargetHandle } from "../target/index.js";
+import { type OrganizationReadiness } from "./organizationReady.js";
 declare const recordSourceSchema: z.ZodUnion<readonly [z.ZodObject<{
     kind: z.ZodLiteral<"project">;
     root: z.ZodString;
@@ -15,7 +18,10 @@ export declare const deploymentRecordSchema: z.ZodObject<{
     env_file: z.ZodOptional<z.ZodString>;
     manager: z.ZodString;
     name: z.ZodString;
+    organization_handoff: z.ZodOptional<z.ZodUnknown>;
+    organization_handoff_handle: z.ZodOptional<z.ZodString>;
     output_directory: z.ZodNullable<z.ZodString>;
+    run_id: z.ZodOptional<z.ZodString>;
     source: z.ZodUnion<readonly [z.ZodObject<{
         kind: z.ZodLiteral<"project">;
         root: z.ZodString;
@@ -63,8 +69,27 @@ export declare const deploymentRecordSchema: z.ZodObject<{
         }, z.core.$strict>]>>;
     }, z.core.$strict>>;
     version: z.ZodLiteral<"spawnfile.deployment.v2">;
+    export_index: z.ZodOptional<z.ZodObject<{
+        exported_at: z.ZodString;
+        path: z.ZodString;
+        run_id: z.ZodString;
+    }, z.core.$strict>>;
+    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 DeploymentRecord = z.infer<typeof deploymentRecordSchema>;
+export type DeploymentRecord = Omit<z.infer<typeof deploymentRecordSchema>, "organization_handoff" | "organization_handoff_handle" | "organization_ready"> & {
+    organization_handoff?: OrganizationHandoff;
+    organization_handoff_handle?: OpaqueTargetHandle;
+    organization_ready?: OrganizationReadiness;
+};
 export declare const parseDeploymentRecord: (source: unknown, sourceLabel?: string) => DeploymentRecord;
 export declare const readDeploymentRecord: (recordPath: string) => Promise<DeploymentRecord>;
 export declare const readDeploymentRecordFromOutput: (outputDirectory: string, deploymentName: string) => Promise<DeploymentRecord>;

package/dist/deployment/record.js

@@ -3,7 +3,10 @@ import { readdir, rename, writeFile } from "node:fs/promises";
 import { z } from "zod";
 import { ensureDirectory, readUtf8File } from "../filesystem/index.js";
 import { SpawnfileError } from "../shared/index.js";
+import { parseOrganizationHandoff } from "./organizationHandoffTypes.js";
+import { parseOpaqueTargetHandle } from "../target/index.js";
 import { normalizeDeploymentName, resolveDeploymentRecordPath, resolveDeploymentRecordsDirectory } from "./names.js";
+import { parseOrganizationReadiness, organizationReadinessSchema } from "./organizationReady.js";
 const contextTargetSchema = z.object({
     endpoint_fingerprint: z.string().regex(/^sha256:[a-f0-9]{32}$/),
     kind: z.literal("context"),
@@ -82,12 +85,40 @@ export const deploymentRecordSchema = z.object({
     env_file: z.string().min(1).optional(),
     manager: z.string().min(1),
     name: z.string().min(1),
+    organization_handoff: z.unknown().optional(),
+    organization_handoff_handle: z.string().optional(),
     output_directory: z.string().min(1).nullable(),
+    // Optional: the NOOPOLIS_RUN_ID stamped on every authority container's
+    // causal events for this deployment's run (see specs/CAUSAL.md and
+    // src/runtime/common.ts). Populated only when the compiling process had a
+    // run id set (every `spawnfile run`/`up --detach` invocation via
+    // ensureNoopolisRunId()); absent for image-consume/recovered records that
+    // have no reliable run-time id to source. This is what lets
+    // `spawnfile artifacts export --run-id <id>` find the deployment whose
+    // containers/volumes were compiled under that run.
+    run_id: z.string().min(1).optional(),
     source: recordSourceSchema,
     target: targetSchema,
     units: z.array(unitSchema).min(1),
-    version: z.literal("spawnfile.deployment.v2")
-}).strict();
+    version: z.literal("spawnfile.deployment.v2"),
+    // Optional: stamped by `spawnfile artifacts export` (artifactsExport.ts) once it has
+    // successfully written `spawnfile.export-index.v1` for this deployment's run. This is
+    // the record-driven marker `spawnfile down` (downDeployment.ts) reads to enforce the
+    // export-before-teardown invariant (Decision 21) without needing to be told, out of
+    // band, where a prior export went: down resolves the SAME deployment record export
+    // already writes back to, so the two commands share one source of truth. Absent means
+    // "never exported" — not "exported to an unknown location".
+    export_index: z.object({
+        exported_at: z.string().min(1),
+        path: z.string().min(1),
+        run_id: z.string().min(1)
+    }).strict().optional(),
+    organization_ready: organizationReadinessSchema.optional()
+}).strict().superRefine((value, context) => {
+    if (value.organization_handoff_handle !== undefined && value.organization_handoff === undefined) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["organization_handoff_handle"], message: "organization handoff handle requires organization handoff" });
+    }
+});
 const upgradeV1Record = (record) => ({
     auth_profile: record.auth_profile,
     compile_fingerprint: record.compile_fingerprint,
@@ -104,7 +135,14 @@ const upgradeV1Record = (record) => ({
 const hasVersion = (source, version) => typeof source === "object"
     && source !== null
     && source.version === version;
+const readOrganizationReadiness = (source) => {
+    if (typeof source !== "object" || source === null || !Object.hasOwn(source, "organization_ready")) {
+        return undefined;
+    }
+    return parseOrganizationReadiness(source.organization_ready);
+};
 export const parseDeploymentRecord = (source, sourceLabel = "deployment record") => {
+    const organizationReadiness = readOrganizationReadiness(source);
     let record;
     if (hasVersion(source, "spawnfile.deployment.v1")) {
         const parsed = deploymentRecordV1Schema.safeParse(source);
@@ -118,13 +156,20 @@ export const parseDeploymentRecord = (source, sourceLabel = "deployment record")
         if (!parsed.success) {
             throw new SpawnfileError("validation_error", `Invalid ${sourceLabel}: ${z.prettifyError(parsed.error)}`);
         }
-        record = parsed.data;
+        const { organization_handoff: organizationHandoff, organization_handoff_handle: organizationHandoffHandle, organization_ready: _organizationReady, ...recordWithoutMetadata } = parsed.data;
+        record = {
+            ...recordWithoutMetadata,
+            ...(organizationHandoff === undefined
+                ? {}
+                : { organization_handoff: parseOrganizationHandoff(organizationHandoff) }),
+            ...(organizationHandoffHandle === undefined ? {} : { organization_handoff_handle: parseOpaqueTargetHandle(organizationHandoffHandle) })
+        };
     }
     const normalizedName = normalizeDeploymentName(record.name);
     if (normalizedName !== record.name) {
         throw new SpawnfileError("validation_error", `Invalid ${sourceLabel}: deployment name must be normalized`);
     }
-    return record;
+    return organizationReadiness ? { ...record, organization_ready: organizationReadiness } : record;
 };
 export const readDeploymentRecord = async (recordPath) => {
     let parsed;

package/dist/deployment/simfileFixtureBoundary.test-helper.d.ts

@@ -0,0 +1,8 @@
+export type SimfileFixtureViolation = {
+    file: string;
+    classification: "simfile-scenario-direct-literal" | "simfile-scenario-path-join" | "simfile-scenario-path-resolve";
+    matchedPath: string;
+};
+export declare const scanSimfileFixtureSource: (text: string, file?: string) => SimfileFixtureViolation[];
+export declare const scanSimfileFixtureFile: (file: string) => Promise<SimfileFixtureViolation[]>;
+export declare const scanSimfileFixtureTree: (repositoryRoot: string) => Promise<SimfileFixtureViolation[]>;