spawnfile 0.1.13 → 0.1.17

package/dist/compiler/memoryArtifacts.js

@@ -0,0 +1,210 @@
+import { resolveMnemeDurableMemoryMountPath } from "../runtime/mnemeMcp.js";
+import { createExclusiveReattachVolumeName, SpawnfileError } from "../shared/index.js";
+import { slugify } from "./helpers.js";
+const safeSlug = (value) => slugify(value).trim() || "memory";
+const createMountId = (mountPath) => `memory-${safeSlug(mountPath)}`;
+const isFileBackedMemoryStore = (bank) => bank.store.kind === "sqlite" || bank.store.kind === "json";
+const transportFromRuntime = (runtimeName, bank) => {
+    switch (runtimeName) {
+        case "pi":
+        case "daimon":
+            // Mneme runs in-process for these runtimes (no MCP subprocess), but
+            // whether that in-process runtime is reachable -- and whether it
+            // persists anything -- depends on the store:
+            //   - sqlite/json WITH a durable mount: a real runtime home backed by
+            //     a persistent volume this same module emits.
+            //   - sqlite/json WITHOUT one (persistence.mode "ephemeral", or no
+            //     resolvable path at all): no volume is mounted and Daimon emits no
+            //     memory block, so recall lasts at most the container's lifetime --
+            //     exactly the "memory" kind's situation, and reported the same way.
+            //   - memory: Mneme still runs in-process against a synthesized runtime
+            //     home path, but no persistent volume is emitted for this kind.
+            //   - postgres: no runtime home path at all; the in-process runtime
+            //     gets no memory whatsoever.
+            //
+            // The durable/ephemeral half of that decision is NOT re-derived here:
+            // it comes from resolveMnemeDurableMemoryMountPath, the same authority
+            // that decides the mount below, so the report cannot disagree with what
+            // was actually emitted.
+            switch (bank.store.kind) {
+                case "sqlite":
+                case "json":
+                    return resolveMnemeDurableMemoryMountPath(bank) === null ? "degraded" : "direct";
+                case "memory":
+                    return "degraded";
+                default:
+                    return "unsupported";
+            }
+        case "picoclaw":
+        case "openclaw":
+            return isFileBackedMemoryStore(bank) ? "mcp" : "degraded_mcp";
+        default:
+            return "unsupported";
+    }
+};
+// The mount decision itself lives in runtime/mnemeMcp.ts so that runtime config
+// emitters (which must only point an in-process Mneme runtime at a path this
+// module actually mounts) and this module cannot drift apart.
+const memoryMountPath = resolveMnemeDurableMemoryMountPath;
+const summarizeMemoryStore = (bank, mountId) => {
+    const persistenceMode = bank.store.kind === "sqlite" || bank.store.kind === "json"
+        ? (bank.store.persistence?.mode ?? "durable")
+        : undefined;
+    return {
+        kind: bank.store.kind,
+        ...(bank.store.path ? { path: bank.store.path } : {}),
+        ...(persistenceMode ? { persistence: persistenceMode } : {}),
+        ...(mountId ? { persistent_mount_id: mountId } : {}),
+        ...(bank.store.kind === "postgres" ? { dsn_secret: bank.store.dsn_secret } : {})
+    };
+};
+/**
+ * The identity of the PHYSICAL store a declared bank resolves to.
+ *
+ * Mneme addresses a store by its runtime home directory and then discards the
+ * declared filename: `JsonlMemoryStore` always writes `<home>/memory/events.jsonl`
+ * and `SQLiteMemoryIndex` always opens `<home>/memory/<default>.db`
+ * (mneme/src/store/store.ts, mneme/src/store/sqliteIndex.ts). Spawnfile resolves
+ * that home as `dirname(store.path)` unless `persistence.mount` overrides it, so
+ * `/data/mem/a.jsonl` and `/data/mem/b.jsonl` are ONE physical store wearing two
+ * declared names — two concurrent MemoryRuntimes appending to one file and
+ * opening one SQLite database.
+ *
+ * Two declarations may therefore share a durable directory only when they are
+ * the same bank said twice (the legitimate case: one bank declared in an org
+ * scope and again in a nested team scope so both sides can access it). Anything
+ * that differs — a different id, a different declared file, a different index
+ * intent — means the author believes they have two stores and the runtime will
+ * silently give them one.
+ */
+const physicalStoreIdentity = (bank) => JSON.stringify({
+    consolidation: bank.consolidation,
+    id: bank.id,
+    index: bank.index,
+    retention: bank.retention,
+    store: {
+        kind: bank.store.kind,
+        mount: bank.store.persistence?.mount ?? null,
+        name: bank.store.persistence?.name ?? null,
+        path: bank.store.path ?? null
+    }
+});
+const collidingBankMessage = (mountPath, prior, next) => `Memory banks ${prior.bankId} (declared in ${prior.source}) and ${next.bankId} `
+    + `(declared in ${next.source}) both resolve to the durable memory directory ${mountPath}, `
+    + "but do not declare the same store. Mneme keys a store by that directory and ignores the "
+    + "declared filename, so these two banks would silently become one physical store with two "
+    + "runtimes writing it. Give each bank its own directory (a distinct store.path parent or "
+    + "persistence.mount), or declare them identically if one shared bank is what you meant.";
+/**
+ * The docker volume name for a durable memory directory.
+ *
+ * Deliberately NOT run-scoped. `createPersistentVolumeName` folds NOOPOLIS_RUN_ID
+ * into the name, and `ensureNoopolisRunId` mints a fresh id on every `spawnfile
+ * run`/`up`, so a run-scoped memory volume means the organization you redeploy
+ * tomorrow starts with an empty memory bank. There is no working escape hatch
+ * today either: `spawnfile product-state clone` refuses SQLite paths, and reusing
+ * yesterday's NOOPOLIS_RUN_ID to reproduce the volume name would collapse two
+ * distinct causal runs onto one run_id in the ledger (specs/CAUSAL.md).
+ *
+ * `exclusive-reattach` is the existing lifecycle for exactly this: a host-stable
+ * name derived from the project root plus the deployment lineage, with a
+ * daemon-side reservation that refuses to start when another live container
+ * already holds the volume (src/compiler/runProjectDockerReservation.ts). That
+ * mutual exclusion is a requirement here rather than a cost — Mneme's append-only
+ * JSONL plus its SQLite index are single-writer — and it is why an organization
+ * with durable memory cannot use the concurrent blue/green canary workflow and
+ * must stop-and-reattach instead (specs/CONTAINERS.md).
+ *
+ * An author-declared `persistence.name` is honored verbatim: naming a volume is
+ * precisely a request for a host-stable identity.
+ */
+const durableMemoryVolumeName = (planRoot, mountId, declaredName, deploymentLineage) => declaredName?.trim()
+    || createExclusiveReattachVolumeName(`${planRoot}\0${deploymentLineage}`, mountId);
+export const createMemoryArtifactBundle = (plan, deploymentLineage = "compile") => {
+    const sourceToNode = new Map(plan.nodes.map((node) => [node.value.source, node]));
+    const groupedMemory = new Map();
+    for (const access of plan.memoryAccess ?? []) {
+        const key = `${access.source}::${access.bank.id}`;
+        const existing = groupedMemory.get(key);
+        if (existing) {
+            existing.accesses.push(access);
+        }
+        else {
+            groupedMemory.set(key, { bank: access.bank, source: access.source, accesses: [access] });
+        }
+    }
+    const mounts = [];
+    const mountPathMemoryMap = new Map();
+    const mountByPath = new Map();
+    const claimantByPath = new Map();
+    const memories = [...groupedMemory.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([, entry]) => {
+        const declaringNode = sourceToNode.get(entry.source);
+        if (!declaringNode) {
+            return null;
+        }
+        const transportByNodeId = {};
+        const accessibleNodeIds = new Set();
+        for (const access of entry.accesses) {
+            const agentNode = sourceToNode.get(access.agentSource);
+            if (!agentNode || agentNode.value.kind !== "agent") {
+                continue;
+            }
+            const transport = transportFromRuntime(agentNode.runtimeName, entry.bank);
+            transportByNodeId[agentNode.id] = transport;
+            accessibleNodeIds.add(agentNode.id);
+        }
+        const declaringNodeId = declaringNode.id;
+        const mountPath = memoryMountPath(entry.bank);
+        let persistentMountId;
+        if (mountPath !== null) {
+            const mountId = createMountId(mountPath);
+            const declaredVolumeName = entry.bank.store.persistence?.name?.trim();
+            const volumeName = durableMemoryVolumeName(plan.root, mountId, entry.bank.store.persistence?.name, deploymentLineage);
+            const identity = physicalStoreIdentity(entry.bank);
+            const claimant = { bankId: entry.bank.id, identity, source: entry.source };
+            const priorClaimant = claimantByPath.get(mountPath);
+            if (priorClaimant && priorClaimant.identity !== identity) {
+                throw new SpawnfileError("validation_error", collidingBankMessage(mountPath, priorClaimant, claimant));
+            }
+            claimantByPath.set(mountPath, claimant);
+            const existingMount = mountByPath.get(mountPath);
+            if (existingMount && existingMount.volume_name !== volumeName) {
+                throw new Error(`Memory store mount ${mountPath} resolves to conflicting volume names`);
+            }
+            const mount = existingMount ?? {
+                ...(declaredVolumeName ? { declared_volume_name: declaredVolumeName } : {}),
+                id: mountId,
+                lifecycle: "exclusive-reattach",
+                mount_path: mountPath,
+                reason: `durable memory stores under ${mountPath}`,
+                volume_name: volumeName
+            };
+            mountByPath.set(mountPath, mount);
+            if (!existingMount) {
+                mounts.push(mount);
+            }
+            persistentMountId = mount.id;
+            mountPathMemoryMap.set(persistentMountId, mountPath);
+        }
+        return {
+            id: entry.bank.id,
+            declaring_node_id: declaringNodeId,
+            accessible_node_ids: [...accessibleNodeIds].sort(),
+            store: summarizeMemoryStore(entry.bank, persistentMountId),
+            index: entry.bank.index,
+            consolidation: entry.bank.consolidation,
+            retention: entry.bank.retention,
+            transport_by_node_id: transportByNodeId
+        };
+    })
+        .filter((entry) => entry !== null)
+        .sort((left, right) => left.declaring_node_id.localeCompare(right.declaring_node_id)
+        || left.id.localeCompare(right.id));
+    return {
+        mountPathMemoryMap,
+        memories,
+        mounts: [...mounts].sort((left, right) => left.id.localeCompare(right.id) || left.mount_path.localeCompare(right.mount_path))
+    };
+};

package/dist/compiler/memoryResolution.d.ts

@@ -0,0 +1,4 @@
+import type { CompilePlan, ResolvedMemoryBank } from "./types.js";
+import type { MemoryBank } from "../manifest/index.js";
+export declare const resolveDeclaredMemoryBanks: (memory: MemoryBank[] | undefined, source: string, declaredBy: "agent" | "team", manifestName: string) => ResolvedMemoryBank[];
+export declare const resolvePlanMemoryAccess: (plan: CompilePlan) => void;

package/dist/compiler/memoryResolution.js

@@ -0,0 +1,147 @@
+import { SpawnfileError } from "../shared/index.js";
+import { slugify } from "./helpers.js";
+const resolveMemoryIndex = (index) => ({
+    graph: {
+        enabled: index?.graph?.enabled ?? false,
+        ...(index?.graph?.kind ? { kind: index.graph.kind } : {})
+    },
+    lexical: {
+        enabled: index?.lexical?.enabled ?? true,
+        ...(index?.lexical?.engine ? { engine: index.lexical.engine } : {})
+    },
+    rerank: {
+        enabled: index?.rerank?.enabled ?? false
+    },
+    vector: {
+        ...(index?.vector?.base_url ? { base_url: index.vector.base_url } : {}),
+        dimensions: index?.vector?.dimensions,
+        enabled: index?.vector?.enabled ?? false,
+        ...(index?.vector?.model ? { model: index.vector.model } : {}),
+        ...(index?.vector?.provider ? { provider: index.vector.provider } : {}),
+        ...(index?.vector?.timeout_ms ? { timeout_ms: index.vector.timeout_ms } : {})
+    }
+});
+const resolveMemoryConsolidation = (consolidation) => ({
+    mode: consolidation?.mode ?? "disabled",
+    ...(consolidation?.schedule ? { schedule: consolidation.schedule } : {}),
+    ...(consolidation?.summarize_after_events
+        ? { summarize_after_events: consolidation.summarize_after_events }
+        : {})
+});
+const resolveMemoryRetention = (retention) => ({
+    forgetting: retention?.forgetting ?? "manual",
+    ...(retention?.ttl ? { ttl: retention.ttl } : {})
+});
+const resolveMemoryStore = (store, manifestName, bankId) => {
+    const manifestSlug = slugify(manifestName) || "memory";
+    const baseDirectory = `/var/lib/spawnfile/memory/${manifestSlug}/${bankId}`;
+    if (store.kind === "sqlite" || store.kind === "json") {
+        return {
+            kind: store.kind,
+            path: store.path ?? `${baseDirectory}/${store.kind === "sqlite" ? "memory.sqlite" : "memory.jsonl"}`,
+            ...(store.persistence
+                ? {
+                    persistence: {
+                        mode: store.persistence.mode,
+                        ...(store.persistence.mount ? { mount: store.persistence.mount } : {}),
+                        ...(store.persistence.name ? { name: store.persistence.name } : {})
+                    }
+                }
+                : {
+                    persistence: {
+                        mode: "durable"
+                    }
+                })
+        };
+    }
+    if (store.kind === "postgres") {
+        return {
+            kind: store.kind,
+            dsn_secret: store.dsn_secret
+        };
+    }
+    return { kind: "memory" };
+};
+export const resolveDeclaredMemoryBanks = (memory, source, declaredBy, manifestName) => (memory ?? []).map((entry) => ({
+    access: entry.access,
+    consolidation: resolveMemoryConsolidation(entry.consolidation),
+    declaredBy,
+    declaredName: manifestName,
+    id: entry.id,
+    index: resolveMemoryIndex(entry.index),
+    retention: resolveMemoryRetention(entry.retention),
+    source,
+    store: resolveMemoryStore(entry.store, manifestName, entry.id)
+}));
+const getAgentNodes = (plan) => new Map(plan.nodes
+    .filter((node) => node.value.kind === "agent")
+    .map((node) => [node.value.source, node.value]));
+const getTeamNodes = (plan) => new Map(plan.nodes
+    .filter((node) => node.value.kind === "team")
+    .map((node) => [node.value.source, node.value]));
+const resolveTeamMembersForBank = (team, members) => {
+    if (members !== undefined) {
+        return members;
+    }
+    return team.members.filter((member) => member.kind === "agent").map((member) => member.id);
+};
+export const resolvePlanMemoryAccess = (plan) => {
+    const agentBySource = getAgentNodes(plan);
+    const teamBySource = getTeamNodes(plan);
+    const memoryAccess = [];
+    for (const agent of agentBySource.values()) {
+        for (const bank of agent.memory ?? []) {
+            memoryAccess.push({
+                agentSource: agent.source,
+                declaringKind: "agent",
+                source: bank.source,
+                bank
+            });
+        }
+    }
+    for (const team of teamBySource.values()) {
+        for (const bank of team.memory ?? []) {
+            const allowedMembers = resolveTeamMembersForBank(team, bank.access?.members);
+            const validMemberIds = new Set(team.members.map((member) => member.id));
+            if (bank.access?.members) {
+                for (const memberId of bank.access.members) {
+                    if (!validMemberIds.has(memberId)) {
+                        throw new SpawnfileError("validation_error", `Team ${team.name} memory bank ${bank.id} references unknown member ${memberId}`);
+                    }
+                }
+            }
+            for (const memberId of allowedMembers) {
+                const member = team.members.find((memberRef) => memberRef.id === memberId);
+                if (!member || member.kind !== "agent") {
+                    continue;
+                }
+                const agentNode = agentBySource.get(member.nodeSource);
+                if (!agentNode) {
+                    throw new SpawnfileError("validation_error", `Unable to resolve agent member ${memberId} in team ${team.name} for memory bank ${bank.id}`);
+                }
+                memoryAccess.push({
+                    agentSource: agentNode.source,
+                    declaringKind: "team",
+                    slotId: memberId,
+                    source: team.source,
+                    bank
+                });
+            }
+        }
+    }
+    if (memoryAccess.length === 0) {
+        return;
+    }
+    const uniqueAccess = new Map();
+    for (const access of memoryAccess) {
+        const key = `${access.agentSource}::${access.declaringKind}::${access.source}::${access.bank.id}::${access.slotId ?? ""}`;
+        uniqueAccess.set(key, access);
+    }
+    plan.memoryAccess = [...uniqueAccess.values()].sort((left, right) => `${left.agentSource}:${left.bank.id}:${left.source}:${left.slotId ?? ""}`.localeCompare(`${right.agentSource}:${right.bank.id}:${right.source}:${right.slotId ?? ""}`));
+    for (const agent of agentBySource.values()) {
+        const access = plan.memoryAccess.filter((entry) => entry.agentSource === agent.source);
+        if (access.length > 0) {
+            agent.memoryAccess = access;
+        }
+    }
+};

package/dist/compiler/modelEnv.d.ts

@@ -1,6 +1,13 @@
 import type { ExecutionBlock, ModelTarget } from "../manifest/index.js";
 import { type ModelAuthMethod } from "../shared/index.js";
 import type { EffectiveModelTarget } from "./types.js";
+export declare const CLI_CREDENTIAL_SECRET_NAME = "SPAWNFILE_CLI_AUTH_JSON";
+/**
+ * Only the host-imported CLI logins travel as `SPAWNFILE_CLI_AUTH_JSON`. `grok`
+ * is a Daimon-owned subscription: its credential is the broker's bootstrap
+ * slot (`runtime/daimon/runAuth.ts`), never this secret.
+ */
+export declare const modelAuthMethodNeedsCliCredential: (method: ModelAuthMethod) => boolean;
 export declare const resolveModelProviderEnvName: (provider: string) => string;
 export declare const listExecutionModelTargets: (execution: ExecutionBlock | undefined) => ModelTarget[];
 export declare const resolveEffectiveModelTarget: (target: ModelTarget, execution: ExecutionBlock | undefined) => EffectiveModelTarget;

package/dist/compiler/modelEnv.js

@@ -8,6 +8,13 @@ const MODEL_PROVIDER_ENV_VARS = new Map([
     ["openrouter", "OPENROUTER_API_KEY"],
     ["xai", "XAI_API_KEY"]
 ]);
+export const CLI_CREDENTIAL_SECRET_NAME = "SPAWNFILE_CLI_AUTH_JSON";
+/**
+ * Only the host-imported CLI logins travel as `SPAWNFILE_CLI_AUTH_JSON`. `grok`
+ * is a Daimon-owned subscription: its credential is the broker's bootstrap
+ * slot (`runtime/daimon/runAuth.ts`), never this secret.
+ */
+export const modelAuthMethodNeedsCliCredential = (method) => method === "claude-code" || method === "codex";
 const resolveLegacyModelAuthMethod = (execution, provider) => {
     const auth = execution?.model?.auth;
     if (!auth) {
@@ -66,7 +73,8 @@ export const resolveEffectiveModelTarget = (target, execution) => {
         },
         ...(target.endpoint ? { endpoint: target.endpoint } : {}),
         name: target.name,
-        provider: target.provider
+        provider: target.provider,
+        ...(target.reasoning_effort ? { reasoningEffort: target.reasoning_effort } : {})
     };
 };
 export const listEffectiveExecutionModelTargets = (execution) => listExecutionModelTargets(execution).map((target) => resolveEffectiveModelTarget(target, execution));
@@ -88,6 +96,10 @@ export const resolveExecutionModelAuthMethods = (execution) => {
 export const listExecutionModelSecretNames = (execution) => {
     const secretNames = new Set();
     for (const target of listEffectiveExecutionModelTargets(execution)) {
+        if (modelAuthMethodNeedsCliCredential(target.auth.method)) {
+            secretNames.add(CLI_CREDENTIAL_SECRET_NAME);
+            continue;
+        }
         if (target.auth.method !== "api_key") {
             continue;
         }

package/dist/compiler/moltnetAllowedWakeSendersValidation.d.ts

@@ -0,0 +1,2 @@
+import type { CompilePlan } from "./types.js";
+export declare const validateAllowedWakeSenders: (plan: CompilePlan) => void;

package/dist/compiler/moltnetAllowedWakeSendersValidation.js

@@ -0,0 +1,42 @@
+import { SpawnfileError } from "../shared/index.js";
+const rootTeamNode = (plan) => {
+    const rootNodes = plan.nodes
+        .map((entry) => entry.kind === "team" &&
+        entry.value.kind === "team" &&
+        entry.value.source === plan.root
+        ? entry.value
+        : undefined)
+        .filter((team) => Boolean(team));
+    if (rootNodes.length !== 1) {
+        throw new SpawnfileError("validation_error", `Moltnet attachment validation requires exactly one source-root team; found ${rootNodes.length}`);
+    }
+    return rootNodes[0];
+};
+const describeAttachment = (network, memberId) => `${network}/${memberId ?? "unknown"}`;
+export const validateAllowedWakeSenders = (plan) => {
+    let rootTeam;
+    const rootParticipants = () => {
+        if (!rootTeam) {
+            rootTeam = rootTeamNode(plan);
+        }
+        return rootTeam.externalParticipants ?? [];
+    };
+    for (const node of plan.nodes) {
+        if (node.value.kind !== "agent")
+            continue;
+        const attachments = node.value.surfaces?.moltnet ?? [];
+        for (const attachment of attachments) {
+            if (!attachment.dms?.allowedWakeSenders?.length) {
+                continue;
+            }
+            const rootNodeParticipants = rootParticipants();
+            for (const authorId of attachment.dms.allowedWakeSenders) {
+                const compatible = rootNodeParticipants.filter((service) => service.id === authorId &&
+                    service.surfaces.moltnet.some((entry) => entry.network === attachment.network && entry.dms.enabled === true));
+                if (compatible.length !== 1) {
+                    throw new SpawnfileError("validation_error", `Moltnet attachment ${node.value.name}/${describeAttachment(attachment.network, attachment.memberId)} has ${compatible.length} root matches for allowed_wake_senders entry ${authorId}`);
+                }
+            }
+        }
+    }
+};

package/dist/compiler/moltnetArtifactPaths.d.ts

@@ -0,0 +1,31 @@
+import type { ResolvedTeamNode } from "./types.js";
+export declare const createMoltnetExternalParticipantArtifactPath: (networkId: string, memberId: string) => string;
+/**
+ * Derives the host-mounted docker volume name for a **run-scoped** durable
+ * mount — state whose whole point is to be fresh per run (today: the Moltnet
+ * causal event log, Daimon telemetry, per-network Moltnet runtime state).
+ *
+ * `runId` (the compiling process's resolved NOOPOLIS_RUN_ID, see
+ * src/runtime/common.ts) is the run-scoping key: `spawnfile run`/`spawnfile
+ * up` always call `ensureNoopolisRunId()` before compiling, so a fresh
+ * invocation with no host-pinned run id gets a fresh generated one and
+ * therefore a fresh volume — two concurrent/successive runs (e.g. two
+ * memetics replicates) never share it. A cold restart that wants the same
+ * run's state sets the SAME `NOOPOLIS_RUN_ID` before re-running, which
+ * reproduces this name and remounts it. Omitted (a bare `spawnfile
+ * compile`/`spawnfile build` with no run id in the host env) reproduces the
+ * pre-run-scoping name exactly, so standard compiles stay byte-identical.
+ *
+ * State that must SURVIVE a redeploy — workspace `kind: volume` resources,
+ * durable Moltnet stores, open-mode agent token directories, durable memory
+ * banks, the Daimon usage ledger — must NEVER be named here. Those are
+ * `lifecycle: "exclusive-reattach"` and are named by
+ * `createExclusiveReattachVolumeName` from the plan root and the deployment
+ * lineage, honouring an author-declared name verbatim. This function
+ * deliberately takes no author-declared name: a run-scoped volume is never
+ * the thing an author names.
+ */
+export declare const createPersistentVolumeName: (planRoot: string, id: string, runId?: string) => string;
+export declare const toContainerRootfsPath: (rootfsPath: string) => string;
+export declare const isNetworkHttpEnabled: (network: NonNullable<ResolvedTeamNode["networks"]>[number]) => boolean;
+export declare const resolveNetworkPort: (network: NonNullable<ResolvedTeamNode["networks"]>[number], fallbackPort: number) => number;

package/dist/compiler/moltnetArtifactPaths.js

@@ -0,0 +1,51 @@
+import { SpawnfileError } from "../shared/index.js";
+import { createShortHash, slugify } from "./helpers.js";
+const ROOTFS_PREFIX = "container/rootfs";
+const ARTIFACT_SEGMENT = /^[a-z][a-z0-9-]{0,62}$/u;
+export const createMoltnetExternalParticipantArtifactPath = (networkId, memberId) => {
+    if (!ARTIFACT_SEGMENT.test(networkId) ||
+        !/^[a-z][a-z0-9-]{0,62}(?:\.[a-z][a-z0-9-]{0,62}){0,7}$/u.test(memberId) ||
+        Buffer.byteLength(memberId, "ascii") > 255) {
+        throw new SpawnfileError("validation_error", "invalid Moltnet external participant artifact path segment");
+    }
+    return `moltnet/external-participants/${networkId}/${memberId}.json`;
+};
+const truncateSegment = (value, maxLength) => value.length > maxLength ? value.slice(0, maxLength).replace(/[-_.]+$/u, "") : value;
+/**
+ * Derives the host-mounted docker volume name for a **run-scoped** durable
+ * mount — state whose whole point is to be fresh per run (today: the Moltnet
+ * causal event log, Daimon telemetry, per-network Moltnet runtime state).
+ *
+ * `runId` (the compiling process's resolved NOOPOLIS_RUN_ID, see
+ * src/runtime/common.ts) is the run-scoping key: `spawnfile run`/`spawnfile
+ * up` always call `ensureNoopolisRunId()` before compiling, so a fresh
+ * invocation with no host-pinned run id gets a fresh generated one and
+ * therefore a fresh volume — two concurrent/successive runs (e.g. two
+ * memetics replicates) never share it. A cold restart that wants the same
+ * run's state sets the SAME `NOOPOLIS_RUN_ID` before re-running, which
+ * reproduces this name and remounts it. Omitted (a bare `spawnfile
+ * compile`/`spawnfile build` with no run id in the host env) reproduces the
+ * pre-run-scoping name exactly, so standard compiles stay byte-identical.
+ *
+ * State that must SURVIVE a redeploy — workspace `kind: volume` resources,
+ * durable Moltnet stores, open-mode agent token directories, durable memory
+ * banks, the Daimon usage ledger — must NEVER be named here. Those are
+ * `lifecycle: "exclusive-reattach"` and are named by
+ * `createExclusiveReattachVolumeName` from the plan root and the deployment
+ * lineage, honouring an author-declared name verbatim. This function
+ * deliberately takes no author-declared name: a run-scoped volume is never
+ * the thing an author names.
+ */
+export const createPersistentVolumeName = (planRoot, id, runId) => {
+    const project = truncateSegment(slugify(planRoot.split("/").slice(-2, -1)[0] ?? "project") || "project", 32);
+    const suffix = truncateSegment(slugify(id) || "state", 48);
+    const trimmedRunId = runId?.trim();
+    if (!trimmedRunId) {
+        return `spawnfile-${project}-${suffix}-${createShortHash(`${planRoot}:${id}`)}`;
+    }
+    const runSegment = truncateSegment(slugify(trimmedRunId) || "run", 24);
+    return `spawnfile-${project}-${suffix}-${runSegment}-${createShortHash(`${planRoot}:${id}:${trimmedRunId}`)}`;
+};
+export const toContainerRootfsPath = (rootfsPath) => `/${rootfsPath.replace(`${ROOTFS_PREFIX}/`, "")}`;
+export const isNetworkHttpEnabled = (network) => network.server?.mode === "managed" && network.server.human_ingress === true;
+export const resolveNetworkPort = (network, fallbackPort) => network.server?.mode === "managed" ? network.server.listen.port : fallbackPort;

package/dist/compiler/moltnetArtifactTypes.d.ts

@@ -0,0 +1,56 @@
+import type { EmittedFile } from "../runtime/index.js";
+import type { TeamNetworkServer } from "../manifest/index.js";
+import type { MoltnetSecretPatch } from "./moltnetConfigLowering.js";
+import type { MoltnetExternalParticipantArtifactV1 } from "./moltnetExternalParticipantArtifact.js";
+export interface MoltnetServerPlan {
+    baseUrl: string;
+    configPath?: string;
+    id: string;
+    mode: "external" | "managed";
+    name: string;
+    networkId: string;
+    port?: number;
+    rooms: Array<{
+        federation?: "all" | "none" | string[];
+        id: string;
+        members: string[];
+        name?: string;
+        visibility?: "public" | "private";
+        write_policy?: "members" | "operators" | "registered_agents";
+    }>;
+    server: TeamNetworkServer;
+    secretPatches: MoltnetSecretPatch[];
+    teamSource: string;
+}
+export interface MoltnetNodePlan {
+    configPath: string;
+    credentialAgentId?: string;
+    credentialId?: string;
+    credentialSecret?: string;
+    memberId?: string;
+    networkId: string;
+    receiptStorePath?: string;
+}
+export interface MoltnetPersistentMount {
+    /** The author's `store.persistence.name`, when declared. */
+    declaredVolumeName?: string;
+    id: string;
+    /**
+     * `exclusive-reattach` marks state that MUST survive container replacement
+     * and redeploy: its volume name is deployment-stable (never run-scoped) and
+     * only one live container may hold it at a time.
+     */
+    lifecycle?: "exclusive-reattach";
+    mountPath: string;
+    reason: string;
+    volumeName: string;
+}
+export interface MoltnetArtifacts {
+    externalParticipantArtifacts?: MoltnetExternalParticipantArtifactV1[];
+    files: EmittedFile[];
+    nodePlans: MoltnetNodePlan[];
+    persistentMounts: MoltnetPersistentMount[];
+    ports: number[];
+    publishedPorts: number[];
+    serverPlans: MoltnetServerPlan[];
+}

package/dist/compiler/moltnetArtifactTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/compiler/moltnetArtifacts.d.ts

@@ -1,42 +1,4 @@
-import type { EmittedFile } from "../runtime/index.js";
-import type { TeamNetworkServer } from "../manifest/index.js";
-import { type MoltnetSecretPatch } from "./moltnetConfigLowering.js";
+import type { MoltnetArtifacts } from "./moltnetArtifactTypes.js";
 import type { CompilePlan } from "./types.js";
-export interface MoltnetServerPlan {
-    baseUrl: string;
-    configPath?: string;
-    id: string;
-    mode: "external" | "managed";
-    name: string;
-    networkId: string;
-    port?: number;
-    rooms: Array<{
-        id: string;
-        members: string[];
-        name?: string;
-        visibility?: "public" | "private";
-        write_policy?: "members" | "operators" | "registered_agents";
-    }>;
-    server: TeamNetworkServer;
-    secretPatches: MoltnetSecretPatch[];
-    teamSource: string;
-}
-export interface MoltnetNodePlan {
-    configPath: string;
-    networkId: string;
-}
-export interface MoltnetPersistentMount {
-    id: string;
-    mountPath: string;
-    reason: string;
-    volumeName: string;
-}
-export interface MoltnetArtifacts {
-    files: EmittedFile[];
-    nodePlans: MoltnetNodePlan[];
-    persistentMounts: MoltnetPersistentMount[];
-    ports: number[];
-    publishedPorts: number[];
-    serverPlans: MoltnetServerPlan[];
-}
-export declare const generateMoltnetArtifacts: (plan: CompilePlan) => Promise<MoltnetArtifacts | null>;
+export type { MoltnetArtifacts, MoltnetNodePlan, MoltnetPersistentMount, MoltnetServerPlan } from "./moltnetArtifactTypes.js";
+export declare const generateMoltnetArtifacts: (plan: CompilePlan, deploymentLineage?: string) => Promise<MoltnetArtifacts | null>;