simfile 0.0.1

package/dist/sims/composedJungianSimDriver.js

@@ -0,0 +1,199 @@
+import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { exportMoltnetTranscript, roomTranscriptTargetFromScope } from "../moltnet/transcript-export.js";
+import { sendWorldEventToMoltnet } from "../moltnet/world-participant.js";
+import { composeRunManifest, sha256HexOfBuffer } from "./composeRunManifest.js";
+import { allMembersConnected, getMoltnetRoom, listMoltnetAgents, listMoltnetRoomMessages, moltnetHealthy } from "./moltnetRoomClient.js";
+import { defaultSleep, pollUntilReady } from "./poll.js";
+import { runSpawnfileArtifactsExport, runSpawnfileDown, runSpawnfileUp } from "./spawnfileCli.js";
+const DEFAULT_SEED_NETWORK = "psyche-floor";
+const DEFAULT_SEED_ROOM = "commons";
+const DEFAULT_SEED_TARGET = "luna-representative";
+const DEFAULT_SEED_TEXT = "@luna-representative The floor asks: how should Luna meet the coming change?";
+const DEFAULT_SYNTHESIS_MARKER = "council has spoken";
+const DEFAULT_TIMEOUT_MS = 300_000;
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const asString = (value) => (typeof value === "string" ? value : undefined);
+/**
+ * Reads `spawnfile-report.json` and extracts the managed networks: id,
+ * base url (host-published 1:1), and per-room membership. This is the driver's
+ * ONE structured read of the compile report — everything else is HTTP polling.
+ */
+const readNetworkPlans = async (compiledOutputDirectory) => {
+    const raw = await readFile(path.join(compiledOutputDirectory, "spawnfile-report.json"), "utf8");
+    const report = JSON.parse(raw);
+    const plans = Array.isArray(report.container?.moltnet?.server_plans)
+        ? report.container.moltnet.server_plans
+        : [];
+    const networks = [];
+    for (const plan of plans) {
+        if (asString(plan.mode) !== "managed")
+            continue;
+        const networkId = asString(plan.network_id);
+        const baseUrl = asString(plan.base_url);
+        if (!networkId || !baseUrl)
+            continue;
+        const rooms = Array.isArray(plan.rooms) ? plan.rooms : [];
+        networks.push({
+            networkId,
+            baseUrl,
+            rooms: rooms
+                .map((room) => ({
+                roomId: asString(room.id),
+                members: Array.isArray(room.members) ? room.members.filter((m) => typeof m === "string") : []
+            }))
+                .filter((room) => room.roomId !== undefined)
+        });
+    }
+    return networks;
+};
+/** Waits until EVERY managed network is healthy and every declared room member has a live, connected bridge — the precondition for a single seed to reach the whole psyche. */
+const waitForPsycheReady = async (networks, poll) => {
+    for (const network of networks) {
+        await pollUntilReady(`moltnet ${network.networkId} health`, poll, async () => (await moltnetHealthy(network.baseUrl)) ? true : null);
+        for (const room of network.rooms) {
+            await pollUntilReady(`${network.networkId}:${room.roomId} membership`, poll, async () => {
+                const summary = await getMoltnetRoom(network.baseUrl, room.roomId);
+                const expected = [...room.members].sort();
+                const actual = [...summary.members].sort();
+                return expected.length === actual.length && expected.every((id, i) => actual[i] === id) ? summary : null;
+            });
+            await pollUntilReady(`${network.networkId}:${room.roomId} bridges`, poll, async () => {
+                const agents = await listMoltnetAgents(network.baseUrl);
+                return allMembersConnected(agents, room.roomId, room.members) ? agents : null;
+            });
+        }
+    }
+};
+const buildSeedEvent = (networkId, roomId, targetAgentId, text) => ({
+    event_id: `seed-${Date.now()}`,
+    kind: "world.message",
+    target: `room:${networkId}:${roomId}`,
+    sim_time: 0,
+    provenance: "external",
+    actor: `operator:${targetAgentId}`,
+    scope: "global",
+    payload: { content: text }
+});
+const messageText = (message) => message.parts.find((part) => part.kind === "text")?.text ?? "";
+/** Writes one per-network room transcript to `raw/moltnet/<networkId>/transcript.json` and returns its manifest artifact entry. */
+const writeNetworkTranscript = async (runDir, network) => {
+    const transcript = await exportMoltnetTranscript({
+        baseUrl: network.baseUrl,
+        targets: network.rooms.map((room) => roomTranscriptTargetFromScope(`room:${network.networkId}:${room.roomId}`))
+    });
+    const relativePath = path.posix.join("raw", "moltnet", network.networkId, "transcript.json");
+    const absolutePath = path.join(runDir, "raw", "moltnet", network.networkId, "transcript.json");
+    await mkdir(path.dirname(absolutePath), { recursive: true });
+    const content = `${JSON.stringify(transcript, null, 2)}\n`;
+    await writeFile(absolutePath, content, "utf8");
+    return { path: relativePath, sha256: sha256HexOfBuffer(Buffer.from(content, "utf8")) };
+};
+/** Copies the compile report into the run-dir (the viewer's named feed #1, source of the derived membranes) and returns its artifact entry. */
+const copyCompileReport = async (runDir, compiledOutputDirectory) => {
+    const source = path.join(compiledOutputDirectory, "spawnfile-report.json");
+    const destination = path.join(runDir, "spawnfile-report.json");
+    await copyFile(source, destination);
+    const content = await readFile(destination);
+    return { path: "spawnfile-report.json", sha256: sha256HexOfBuffer(content) };
+};
+/**
+ * Runs the composed jungian psyche end to end: up -> poll every network ready
+ * -> seed the floor ONCE -> wait for the representative's synthesis to reappear
+ * on the floor (proof the interior council deliberated and answered across the
+ * membrane) -> export per-network transcripts + causal artifacts + the compile
+ * report -> down -> write `manifest.json` (with `world.rooms[]`) LAST.
+ */
+export const runComposedJungianSim = async (options) => {
+    const cli = { spawnfileBin: options.spawnfileBin };
+    const seedNetworkId = options.seedNetworkId ?? DEFAULT_SEED_NETWORK;
+    const seedRoomId = options.seedRoomId ?? DEFAULT_SEED_ROOM;
+    const seedTargetAgentId = options.seedTargetAgentId ?? DEFAULT_SEED_TARGET;
+    const seedMessageText = options.seedMessageText ?? DEFAULT_SEED_TEXT;
+    const synthesisMarker = options.synthesisMarker ?? DEFAULT_SYNTHESIS_MARKER;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const poll = {
+        intervalMs: options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+        sleep: defaultSleep,
+        timeoutMs
+    };
+    const now = options.now ?? (() => new Date());
+    const upReceipt = await runSpawnfileUp(cli, {
+        orgPath: options.orgPath,
+        containerName: options.containerName,
+        deploymentName: options.deploymentName,
+        compiledOutputDirectory: options.compiledOutputDirectory
+    });
+    if (!upReceipt.run_id) {
+        throw new Error("spawnfile up-receipt had no run_id; cannot assemble a run directory");
+    }
+    const runId = upReceipt.run_id;
+    const runDir = path.join(options.runsRootDirectory, runId);
+    const networks = await readNetworkPlans(options.compiledOutputDirectory);
+    const seedNetwork = networks.find((network) => network.networkId === seedNetworkId);
+    if (!seedNetwork) {
+        throw new Error(`seed network ${seedNetworkId} not found in compile report`);
+    }
+    let synthesis;
+    try {
+        await waitForPsycheReady(networks, poll);
+        // The ONE write this driver performs — everything else is a read.
+        await sendWorldEventToMoltnet(buildSeedEvent(seedNetworkId, seedRoomId, seedTargetAgentId, seedMessageText), {
+            baseUrl: seedNetwork.baseUrl,
+            networkId: seedNetworkId
+        });
+        // Completion = the representative's floor-facing synthesis appears. It can
+        // only exist AFTER the representative was woken by the council's conclusion
+        // inside the inner network, which itself required the representative to have
+        // first crossed the membrane inward — so this single condition proves the
+        // whole wake-across-membranes chain closed.
+        const synthesisMessage = await pollUntilReady("representative synthesis on the floor", poll, async () => {
+            const messages = await listMoltnetRoomMessages(seedNetwork.baseUrl, seedRoomId, 200);
+            return (messages.find((message) => message.from.id === seedTargetAgentId && messageText(message).includes(synthesisMarker)) ?? null);
+        });
+        synthesis = messageText(synthesisMessage);
+        const exportResult = await runSpawnfileArtifactsExport(cli, {
+            orgPath: options.orgPath,
+            deploymentName: options.deploymentName,
+            compiledOutputDirectory: options.compiledOutputDirectory,
+            destinationDirectory: runDir
+        });
+        // Per-network transcripts + compile report, fetched/copied while the
+        // deployment is still live (transcripts need the running Moltnet HTTP API).
+        const transcriptArtifacts = await Promise.all(networks.map((network) => writeNetworkTranscript(runDir, network)));
+        const reportArtifact = await copyCompileReport(runDir, options.compiledOutputDirectory);
+        await runSpawnfileDown(cli, {
+            orgPath: options.orgPath,
+            deploymentName: options.deploymentName,
+            compiledOutputDirectory: options.compiledOutputDirectory,
+            removeVolumes: options.removeVolumesOnDown ?? true
+        });
+        const world = {
+            rooms: networks.flatMap((network) => network.rooms.map((room) => ({
+                network_id: network.networkId,
+                room_id: room.roomId,
+                members: [...room.members].sort()
+            })))
+        };
+        const manifest = composeRunManifest({
+            runId,
+            createdAt: now().toISOString(),
+            fingerprint: upReceipt.fingerprint,
+            engine: [...new Set((upReceipt.engines ?? []).map((entry) => entry.engine))].sort().join("+") || "unknown",
+            world,
+            exportedArtifacts: exportResult.index.files,
+            extraArtifacts: [...transcriptArtifacts, reportArtifact]
+        });
+        await writeFile(path.join(runDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    }
+    catch (error) {
+        await runSpawnfileDown(cli, {
+            orgPath: options.orgPath,
+            deploymentName: options.deploymentName,
+            compiledOutputDirectory: options.compiledOutputDirectory,
+            removeVolumes: options.removeVolumesOnDown ?? true
+        }).catch(() => undefined);
+        throw error;
+    }
+    return { runDir, runId, synthesis };
+};

package/dist/sims/composedOfficeSimDriver.d.ts

@@ -0,0 +1,53 @@
+import { type ConversationExchangeResult } from "./exchangeWait.js";
+/**
+ * The composed-run driver (Decision 21 / Piece 5 design's "MINIMAL
+ * composed-run driver in simfile"): shells the three documented `spawnfile
+ * ... --json` lifecycle subcommands, seeds the room exactly ONCE, polls
+ * read-only, and assembles a sealed `runs/<id>/` directory `simfile observe`
+ * can reconcile. Zero Docker, zero runtime auth, zero Spawnfile TS imports —
+ * this package's charter. Any wait that would otherwise need a coax/retry is
+ * a Phase-B platform defect to FILE, never something this driver papers over
+ * by re-sending a mention.
+ */
+export interface RunComposedOfficeSimOptions {
+    /** Path to Spawnfile's built CLI entrypoint (e.g. `dist/cli/index.js`). */
+    spawnfileBin: string;
+    /** Path to the composed office-sim org (`fixtures/sims/office-sim/org`). */
+    orgPath: string;
+    containerName: string;
+    deploymentName: string;
+    /** Scratch directory for spawnfile's own compile output + deployment record — separate from the sealed run-dir. */
+    compiledOutputDirectory: string;
+    /** Parent directory under which `runs/<run_id>/` is assembled. */
+    runsRootDirectory: string;
+    networkId?: string;
+    roomId?: string;
+    agentIds?: readonly string[];
+    seedTargetAgentId?: string;
+    seedMessageText?: string;
+    targetTurns?: number;
+    quietGraceMs?: number;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    /** Passed straight to `spawnfile down --volumes`; defaults true so a
+     * composed run leaves nothing behind once its artifacts are safely
+     * exported into the run-dir. */
+    removeVolumesOnDown?: boolean;
+    now?: () => Date;
+}
+export interface RunComposedOfficeSimResult {
+    runDir: string;
+    runId: string;
+    exchange: ConversationExchangeResult;
+}
+/**
+ * Runs the composed office-sim end to end: `spawnfile up` (detached) ->
+ * poll-read-only for moltnet health/room/bridge readiness -> seed the room
+ * ONCE -> poll-read-only for the exchange to conclude -> `spawnfile
+ * artifacts export` -> fetch the moltnet transcript (while the container is
+ * still live — export/transcript both need the running deployment) ->
+ * `spawnfile down` -> compose and write `manifest.json` LAST. Returns the
+ * sealed run-dir path for `simfile observe` to reconcile.
+ */
+export declare const runComposedOfficeSim: (options: RunComposedOfficeSimOptions) => Promise<RunComposedOfficeSimResult>;
+//# sourceMappingURL=composedOfficeSimDriver.d.ts.map

package/dist/sims/composedOfficeSimDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composedOfficeSimDriver.d.ts","sourceRoot":"","sources":["../../src/sims/composedOfficeSimDriver.ts"],"names":[],"mappings":"AAgBA,OAAO,EAIL,KAAK,0BAA0B,EAChC,MAAM,mBAAmB,CAAC;AAgB3B;;;;;;;;;GASG;AACH,MAAM,WAAW,2BAA2B;IAC1C,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,mHAAmH;IACnH,uBAAuB,EAAE,MAAM,CAAC;IAChC,kEAAkE;IAClE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;oCAEgC;IAChC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,0BAA0B,CAAC;CACtC;AAsED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAC/B,SAAS,2BAA2B,KACnC,OAAO,CAAC,0BAA0B,CAwGpC,CAAC"}

package/dist/sims/composedOfficeSimDriver.js

@@ -0,0 +1,162 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { exportMoltnetTranscript, roomTranscriptTargetFromScope } from "../moltnet/transcript-export.js";
+import { sendWorldEventToMoltnet } from "../moltnet/world-participant.js";
+import { composeRunManifest, sha256HexOfBuffer } from "./composeRunManifest.js";
+import { DEFAULT_QUIET_GRACE_MS, resolveTargetTurns, waitForConversationExchange } from "./exchangeWait.js";
+import { allMembersConnected, getMoltnetRoom, listMoltnetAgents, listMoltnetRoomMessages, moltnetHealthy } from "./moltnetRoomClient.js";
+import { defaultSleep, pollUntilReady } from "./poll.js";
+import { runSpawnfileArtifactsExport, runSpawnfileDown, runSpawnfileUp } from "./spawnfileCli.js";
+const DEFAULT_NETWORK_ID = "office_lab";
+const DEFAULT_ROOM_ID = "office-room";
+const DEFAULT_AGENT_IDS = ["eleanor", "sam"];
+const DEFAULT_SEED_TARGET = "eleanor";
+const DEFAULT_SEED_TEXT = "@eleanor We need to finalize the office pilot rollout with Sam: propose the pilot office and a target date for the file migration, and get Sam's agreement.";
+const DEFAULT_TIMEOUT_MS = 240_000;
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+/** Collapses `up-receipt.engines[]` to one disclosure string for the run
+ * manifest: every agent's declared engine when they all agree (true for this
+ * composed office-sim, where both agents run `scripted`), else a sorted
+ * comma-joined list so a mixed-engine run is still visibly disclosed. */
+const collapseEngineDisclosure = (engines) => {
+    const distinct = [...new Set((engines ?? []).map((entry) => entry.engine))].sort();
+    if (distinct.length === 0)
+        return "unknown";
+    return distinct.join("+");
+};
+const waitForMoltnetReadyForSeed = async (baseUrl, roomId, agentIds, pollOptions) => {
+    await pollUntilReady("moltnet health", pollOptions, async () => ((await moltnetHealthy(baseUrl)) ? true : null));
+    await pollUntilReady(`moltnet room ${roomId} membership`, pollOptions, async () => {
+        const room = await getMoltnetRoom(baseUrl, roomId);
+        const expected = [...agentIds].sort();
+        const actual = [...room.members].sort();
+        return expected.length === actual.length && expected.every((id, index) => actual[index] === id) ? room : null;
+    });
+    await pollUntilReady(`moltnet bridge attachments for ${roomId}`, pollOptions, async () => {
+        const agents = await listMoltnetAgents(baseUrl);
+        return allMembersConnected(agents, roomId, agentIds) ? agents : null;
+    });
+};
+/** Builds the single seed `world.message` event this driver ever sends —
+ * the ONE write in the whole flow. Everything else is a GET. */
+const buildSeedEvent = (networkId, roomId, seedTargetAgentId, seedMessageText) => ({
+    event_id: `seed-${Date.now()}`,
+    kind: "world.message",
+    target: `room:${networkId}:${roomId}`,
+    sim_time: 0,
+    provenance: "external",
+    actor: `operator:${seedTargetAgentId}`,
+    scope: "global",
+    payload: { content: seedMessageText }
+});
+const writeTranscriptArtifact = async (runDir, transcript) => {
+    const relativePath = path.posix.join("raw", "moltnet", "transcript.json");
+    const absolutePath = path.join(runDir, "raw", "moltnet", "transcript.json");
+    await mkdir(path.dirname(absolutePath), { recursive: true });
+    const content = `${JSON.stringify(transcript, null, 2)}\n`;
+    await writeFile(absolutePath, content, "utf8");
+    return { path: relativePath, sha256: sha256HexOfBuffer(Buffer.from(content, "utf8")) };
+};
+/**
+ * Runs the composed office-sim end to end: `spawnfile up` (detached) ->
+ * poll-read-only for moltnet health/room/bridge readiness -> seed the room
+ * ONCE -> poll-read-only for the exchange to conclude -> `spawnfile
+ * artifacts export` -> fetch the moltnet transcript (while the container is
+ * still live — export/transcript both need the running deployment) ->
+ * `spawnfile down` -> compose and write `manifest.json` LAST. Returns the
+ * sealed run-dir path for `simfile observe` to reconcile.
+ */
+export const runComposedOfficeSim = async (options) => {
+    const cliContext = { spawnfileBin: options.spawnfileBin };
+    const networkId = options.networkId ?? DEFAULT_NETWORK_ID;
+    const roomId = options.roomId ?? DEFAULT_ROOM_ID;
+    const agentIds = options.agentIds ?? DEFAULT_AGENT_IDS;
+    const seedTargetAgentId = options.seedTargetAgentId ?? DEFAULT_SEED_TARGET;
+    const seedMessageText = options.seedMessageText ?? DEFAULT_SEED_TEXT;
+    const targetTurns = resolveTargetTurns(options.targetTurns);
+    const quietGraceMs = options.quietGraceMs ?? DEFAULT_QUIET_GRACE_MS;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const pollOptions = {
+        intervalMs: options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+        sleep: defaultSleep,
+        timeoutMs
+    };
+    const now = options.now ?? (() => new Date());
+    const upReceipt = await runSpawnfileUp(cliContext, {
+        orgPath: options.orgPath,
+        containerName: options.containerName,
+        deploymentName: options.deploymentName,
+        compiledOutputDirectory: options.compiledOutputDirectory
+    });
+    if (!upReceipt.run_id) {
+        throw new Error("spawnfile up-receipt had no run_id; cannot assemble a run directory");
+    }
+    const baseUrl = upReceipt.readiness.moltnet_base_url;
+    if (!baseUrl) {
+        throw new Error("spawnfile up-receipt had no moltnet_base_url; is human_ingress enabled on the network?");
+    }
+    const runId = upReceipt.run_id;
+    const runDir = path.join(options.runsRootDirectory, runId);
+    let exchange;
+    try {
+        await waitForMoltnetReadyForSeed(baseUrl, roomId, agentIds, pollOptions);
+        const baseline = await listMoltnetRoomMessages(baseUrl, roomId, 200);
+        const baselineIds = new Set(baseline.map((message) => message.id));
+        // The ONE write this driver performs — everything else is a read.
+        await sendWorldEventToMoltnet(buildSeedEvent(networkId, roomId, seedTargetAgentId, seedMessageText), {
+            baseUrl,
+            networkId
+        });
+        exchange = await waitForConversationExchange(baseUrl, roomId, baselineIds, {
+            agentIds,
+            intervalMs: pollOptions.intervalMs,
+            quietGraceMs,
+            sleep: pollOptions.sleep,
+            targetTurns,
+            timeoutMs
+        });
+        // Export before teardown, and fetch the transcript while the container
+        // (and therefore moltnet's HTTP API) is still live — both need the
+        // running deployment, so both happen before `spawnfile down`.
+        const exportResult = await runSpawnfileArtifactsExport(cliContext, {
+            orgPath: options.orgPath,
+            deploymentName: options.deploymentName,
+            compiledOutputDirectory: options.compiledOutputDirectory,
+            destinationDirectory: runDir
+        });
+        const transcript = await exportMoltnetTranscript({
+            baseUrl,
+            targets: [roomTranscriptTargetFromScope(`room:${networkId}:${roomId}`)]
+        });
+        const transcriptArtifact = await writeTranscriptArtifact(runDir, transcript);
+        await runSpawnfileDown(cliContext, {
+            orgPath: options.orgPath,
+            deploymentName: options.deploymentName,
+            compiledOutputDirectory: options.compiledOutputDirectory,
+            removeVolumes: options.removeVolumesOnDown ?? true
+        });
+        const world = { network_id: networkId, room_id: roomId, members: [...agentIds].sort() };
+        const manifest = composeRunManifest({
+            runId,
+            createdAt: now().toISOString(),
+            fingerprint: upReceipt.fingerprint,
+            engine: collapseEngineDisclosure(upReceipt.engines),
+            world,
+            exportedArtifacts: exportResult.index.files,
+            extraArtifacts: [transcriptArtifact]
+        });
+        await writeFile(path.join(runDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    }
+    catch (error) {
+        // Best-effort teardown on failure so a broken run never leaks a live
+        // container/volumes; the original error is what's reported.
+        await runSpawnfileDown(cliContext, {
+            orgPath: options.orgPath,
+            deploymentName: options.deploymentName,
+            compiledOutputDirectory: options.compiledOutputDirectory,
+            removeVolumes: options.removeVolumesOnDown ?? true
+        }).catch(() => undefined);
+        throw error;
+    }
+    return { runDir, runId, exchange };
+};

package/dist/sims/exchangeWait.d.ts

@@ -0,0 +1,56 @@
+import { type MoltnetRoomMessage } from "./moltnetRoomClient.js";
+/**
+ * Pure stop/continue decision + polling loop for a bounded multi-turn Moltnet
+ * exchange, ported from `src/e2e/moltnetExchangeWait.ts` (Piece 5's design
+ * calls that file out as "pure, scenario-agnostic" — the logic to reuse, not
+ * a module to import: this package's charter forbids depending on Spawnfile
+ * internals, so the decision function and polling loop are reproduced here
+ * verbatim rather than referenced across the package boundary).
+ *
+ * Derail guard (Decision 21, Piece 5 design): this ONLY polls and decides
+ * "done" — it never re-sends a mention or otherwise coaxes a reply. If a
+ * real run never completes an exchange, that is a platform gap to FILE
+ * against the owning layer (Phase B), never something this loop works around
+ * by nudging the room again.
+ */
+export declare const MIN_TARGET_TURNS = 3;
+export declare const DEFAULT_TARGET_TURNS = 3;
+export declare const DEFAULT_QUIET_GRACE_MS = 35000;
+export type ExchangeEndReason = "turn-cap" | "quiet-timeout" | "timeout";
+export declare const resolveTargetTurns: (targetTurns?: number) => number;
+export interface ExchangeCompletionInput {
+    agentTurnCount: number;
+    elapsedSinceLastAgentMessageMs: number;
+    elapsedSinceStartMs: number;
+    quietGraceMs: number;
+    targetTurns: number;
+    timeoutMs: number;
+}
+export interface ExchangeCompletionResult {
+    done: boolean;
+    reason: ExchangeEndReason | null;
+}
+/** Same precedence as the ported original: turn-cap, then quiet-timeout
+ * (only once at least one agent turn has landed), then the overall timeout. */
+export declare const evaluateExchangeCompletion: (input: ExchangeCompletionInput) => ExchangeCompletionResult;
+export interface WaitForConversationExchangeOptions {
+    agentIds: readonly string[];
+    intervalMs: number;
+    /** Injectable for tests; defaults to a real `listMoltnetRoomMessages` GET. */
+    listMessages?: (baseUrl: string, roomId: string, limit: number) => Promise<MoltnetRoomMessage[]>;
+    now?: () => number;
+    quietGraceMs: number;
+    sleep: (delayMs: number) => Promise<void>;
+    targetTurns: number;
+    timeoutMs: number;
+}
+export interface ConversationExchangeResult {
+    agentTurns: MoltnetRoomMessage[];
+    endedReason: ExchangeEndReason;
+    transcript: MoltnetRoomMessage[];
+}
+/** Only ever GETs the room's message list and re-evaluates
+ * `evaluateExchangeCompletion` — poll-read-only, seed-once discipline. The
+ * caller seeds the room exactly once, before calling this. */
+export declare const waitForConversationExchange: (baseUrl: string, roomId: string, baselineIds: ReadonlySet<string>, options: WaitForConversationExchangeOptions) => Promise<ConversationExchangeResult>;
+//# sourceMappingURL=exchangeWait.d.ts.map

package/dist/sims/exchangeWait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exchangeWait.d.ts","sourceRoot":"","sources":["../../src/sims/exchangeWait.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE1F;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAClC,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,eAAe,GAAG,SAAS,CAAC;AAEzE,eAAO,MAAM,kBAAkB,GAAI,cAAc,MAAM,KAAG,MACO,CAAC;AAElE,MAAM,WAAW,uBAAuB;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,8BAA8B,EAAE,MAAM,CAAC;IACvC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAClC;AAED;+EAC+E;AAC/E,eAAO,MAAM,0BAA0B,GAAI,OAAO,uBAAuB,KAAG,wBAO3E,CAAC;AAEF,MAAM,WAAW,kCAAkC;IACjD,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACjG,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,UAAU,EAAE,kBAAkB,EAAE,CAAC;CAClC;AAED;;8DAE8D;AAC9D,eAAO,MAAM,2BAA2B,GACtC,SAAS,MAAM,EACf,QAAQ,MAAM,EACd,aAAa,WAAW,CAAC,MAAM,CAAC,EAChC,SAAS,kCAAkC,KAC1C,OAAO,CAAC,0BAA0B,CAgCpC,CAAC"}

package/dist/sims/exchangeWait.js

@@ -0,0 +1,66 @@
+import { listMoltnetRoomMessages } from "./moltnetRoomClient.js";
+/**
+ * Pure stop/continue decision + polling loop for a bounded multi-turn Moltnet
+ * exchange, ported from `src/e2e/moltnetExchangeWait.ts` (Piece 5's design
+ * calls that file out as "pure, scenario-agnostic" — the logic to reuse, not
+ * a module to import: this package's charter forbids depending on Spawnfile
+ * internals, so the decision function and polling loop are reproduced here
+ * verbatim rather than referenced across the package boundary).
+ *
+ * Derail guard (Decision 21, Piece 5 design): this ONLY polls and decides
+ * "done" — it never re-sends a mention or otherwise coaxes a reply. If a
+ * real run never completes an exchange, that is a platform gap to FILE
+ * against the owning layer (Phase B), never something this loop works around
+ * by nudging the room again.
+ */
+export const MIN_TARGET_TURNS = 3;
+export const DEFAULT_TARGET_TURNS = 3;
+export const DEFAULT_QUIET_GRACE_MS = 35_000;
+export const resolveTargetTurns = (targetTurns) => Math.max(MIN_TARGET_TURNS, targetTurns ?? DEFAULT_TARGET_TURNS);
+/** Same precedence as the ported original: turn-cap, then quiet-timeout
+ * (only once at least one agent turn has landed), then the overall timeout. */
+export const evaluateExchangeCompletion = (input) => {
+    if (input.agentTurnCount >= input.targetTurns)
+        return { done: true, reason: "turn-cap" };
+    if (input.agentTurnCount > 0 && input.elapsedSinceLastAgentMessageMs >= input.quietGraceMs) {
+        return { done: true, reason: "quiet-timeout" };
+    }
+    if (input.elapsedSinceStartMs >= input.timeoutMs)
+        return { done: true, reason: "timeout" };
+    return { done: false, reason: null };
+};
+/** Only ever GETs the room's message list and re-evaluates
+ * `evaluateExchangeCompletion` — poll-read-only, seed-once discipline. The
+ * caller seeds the room exactly once, before calling this. */
+export const waitForConversationExchange = async (baseUrl, roomId, baselineIds, options) => {
+    const now = options.now ?? (() => Date.now());
+    const listMessages = options.listMessages ?? listMoltnetRoomMessages;
+    const startedAt = now();
+    const seenIds = new Set(baselineIds);
+    const agentTurns = [];
+    let lastAgentMessageAt = startedAt;
+    let transcript = [];
+    for (;;) {
+        transcript = await listMessages(baseUrl, roomId, 200);
+        for (const message of transcript) {
+            if (seenIds.has(message.id))
+                continue;
+            seenIds.add(message.id);
+            if (options.agentIds.includes(message.from.id)) {
+                agentTurns.push(message);
+                lastAgentMessageAt = now();
+            }
+        }
+        const evaluation = evaluateExchangeCompletion({
+            agentTurnCount: agentTurns.length,
+            elapsedSinceLastAgentMessageMs: now() - lastAgentMessageAt,
+            elapsedSinceStartMs: now() - startedAt,
+            quietGraceMs: options.quietGraceMs,
+            targetTurns: options.targetTurns,
+            timeoutMs: options.timeoutMs
+        });
+        if (evaluation.done)
+            return { agentTurns, endedReason: evaluation.reason, transcript };
+        await options.sleep(options.intervalMs);
+    }
+};

package/dist/sims/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./composedJungianSimDriver.js";
+export * from "./composedOfficeSimDriver.js";
+export * from "./composeRunManifest.js";
+export * from "./exchangeWait.js";
+export * from "./moltnetRoomClient.js";
+export * from "./poll.js";
+export * from "./spawnfileCli.js";
+export * from "./spawnfileReceipts.js";
+export * from "./worldDrivenOfficeSimDriver.js";
+export * from "./worldLedgerWriter.js";
+export * from "./worldSeedLint.js";
+export * from "./worldTickIngest.js";
+export * from "./worldTickLoop.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/sims/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sims/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,iCAAiC,CAAC;AAChD,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC"}

package/dist/sims/index.js

@@ -0,0 +1,13 @@
+export * from "./composedJungianSimDriver.js";
+export * from "./composedOfficeSimDriver.js";
+export * from "./composeRunManifest.js";
+export * from "./exchangeWait.js";
+export * from "./moltnetRoomClient.js";
+export * from "./poll.js";
+export * from "./spawnfileCli.js";
+export * from "./spawnfileReceipts.js";
+export * from "./worldDrivenOfficeSimDriver.js";
+export * from "./worldLedgerWriter.js";
+export * from "./worldSeedLint.js";
+export * from "./worldTickIngest.js";
+export * from "./worldTickLoop.js";

package/dist/sims/moltnetRoomClient.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Read-only Moltnet HTTP polling helpers for the composed-run driver —
+ * `/healthz`, `/v1/rooms/:id`, `/v1/agents`, `/v1/rooms/:id/messages` are
+ * Moltnet's own public wire API (documented, not a Spawnfile internal), the
+ * same endpoints `src/e2e/moltnetE2ESupport.ts`'s `createMoltnetHttpClient`
+ * speaks — reimplemented locally here (never imported from Spawnfile's
+ * `src/e2e`) so this package's charter ("Do not import Spawnfile internals")
+ * holds. Every function here is a plain GET: seeding (the one write this
+ * driver ever performs) goes through `world-participant.ts` instead.
+ */
+export interface MoltnetRoomSummary {
+    id: string;
+    members: string[];
+}
+export interface MoltnetAgentSummary {
+    id: string;
+    rooms: string[];
+    connected: boolean;
+}
+export interface MoltnetRoomMessage {
+    id: string;
+    from: {
+        id: string;
+        type?: string;
+    };
+    parts: {
+        kind: string;
+        text?: string;
+    }[];
+    created_at?: string;
+}
+export interface MoltnetRoomClientOptions {
+    fetchFn?: typeof fetch;
+    timeoutMs?: number;
+}
+/** Read-only health probe; never throws — a not-yet-ready server is a
+ * negative poll result, not an error. */
+export declare const moltnetHealthy: (baseUrl: string, options?: MoltnetRoomClientOptions) => Promise<boolean>;
+export declare const getMoltnetRoom: (baseUrl: string, roomId: string, options?: MoltnetRoomClientOptions) => Promise<MoltnetRoomSummary>;
+export declare const listMoltnetAgents: (baseUrl: string, options?: MoltnetRoomClientOptions) => Promise<MoltnetAgentSummary[]>;
+export declare const listMoltnetRoomMessages: (baseUrl: string, roomId: string, limit: number, options?: MoltnetRoomClientOptions) => Promise<MoltnetRoomMessage[]>;
+/** True once every expected member both appears in room config membership
+ * AND has a live, connected bridge attachment — mirrors
+ * `moltnetE2ESupport.ts`'s `waitForAgents` gate (room membership alone can be
+ * static config, seeding before the bridge attaches is unrecoverable). */
+export declare const allMembersConnected: (agents: readonly MoltnetAgentSummary[], roomId: string, expectedMembers: readonly string[]) => boolean;
+//# sourceMappingURL=moltnetRoomClient.d.ts.map

package/dist/sims/moltnetRoomClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moltnetRoomClient.d.ts","sourceRoot":"","sources":["../../src/sims/moltnetRoomClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAiBD;yCACyC;AACzC,eAAO,MAAM,cAAc,GAAU,SAAS,MAAM,EAAE,UAAU,wBAAwB,KAAG,OAAO,CAAC,OAAO,CASzG,CAAC;AAEF,eAAO,MAAM,cAAc,GACzB,SAAS,MAAM,EACf,QAAQ,MAAM,EACd,UAAU,wBAAwB,KACjC,OAAO,CAAC,kBAAkB,CAA4E,CAAC;AAE1G,eAAO,MAAM,iBAAiB,GAC5B,SAAS,MAAM,EACf,UAAU,wBAAwB,KACjC,OAAO,CAAC,mBAAmB,EAAE,CACqE,CAAC;AAEtG,eAAO,MAAM,uBAAuB,GAClC,SAAS,MAAM,EACf,QAAQ,MAAM,EACd,OAAO,MAAM,EACb,UAAU,wBAAwB,KACjC,OAAO,CAAC,kBAAkB,EAAE,CAMb,CAAC;AAEnB;;;0EAG0E;AAC1E,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,SAAS,mBAAmB,EAAE,EACtC,QAAQ,MAAM,EACd,iBAAiB,SAAS,MAAM,EAAE,KACjC,OAGA,CAAC"}