simfile 0.0.1

package/README.md

@@ -0,0 +1,143 @@
+# Simfile
+
+> Deterministic simulation worlds for societies of agents — seed an idea, run the world, and watch it move through minds.
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/simfile"><img src="https://img.shields.io/npm/v/simfile?style=flat-square&color=7c5cff&label=npm" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/simfile"><img src="https://img.shields.io/npm/dm/simfile?style=flat-square&color=7c5cff" alt="downloads"></a>
+  <a href="#install"><img src="https://img.shields.io/node/v/simfile?style=flat-square&color=7c5cff" alt="node"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/simfile?style=flat-square&color=7c5cff" alt="MIT"></a>
+  <a href="https://simfile.org"><img src="https://img.shields.io/website?url=https%3A%2F%2Fsimfile.org&style=flat-square&label=simfile.org&color=7c5cff" alt="website"></a>
+</p>
+
+Spawnfile declares *who* runs and how an organization is wired — agents, teams, rooms, runtimes, memory. **Simfile declares the *world* around them** — a clock, variables, generators, rules, markers, probes, and a run ledger — then runs it and lets you watch.
+
+Seed a secret into one agent's memory and watch it spread through the society, tick by tick. Open an agent that is *itself* an organization — a Jungian self whose Shadow and Anima deliberate in an inner room — and descend into it. Every message, wake, turn, memory write, and variable change is a ledger event, so the viewer scrubs the whole run backward and forward and every glyph on screen traces to a record.
+
+Deterministic and replayable. Observer-tier by design: Simfile authors and observes worlds — it compiles no Docker images and deploys no agents. That is [**Spawnfile**](https://spawnfile.com)'s job (the organization that runs *in* the world), talking over [**Moltnet**](https://moltnet.dev) (the rooms the agents share).
+
+## Contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [What you can see](#what-you-can-see)
+- [The world](#the-world)
+- [Example](#example)
+- [Observe](#observe)
+- [Repo guide](#repo-guide)
+- [Docs](#docs)
+
+## Install
+
+```bash
+npm install simfile
+simfile --help
+```
+
+Node.js 22+.
+
+## Quick start
+
+```bash
+simfile validate ./Simfile.yaml     # check a world
+simfile view runs/<id>              # replay a sealed run — scrub, descend, watch spread
+simfile view --state .sim           # watch a live world
+simfile observe runs/<id>           # reconcile causal chains + measure spread → report.json
+```
+
+## What you can see
+
+`simfile view <run-dir>` serves a local web app that turns a run into an instrument, not a screensaver:
+
+- **Scrub the whole run.** One causally-ordered timeline — play, rewind, step. The world map, the room chat, and every agent's memory all move together off a single cursor.
+- **Watch a meme spread.** A secret seeded *only* in one agent's private memory surfaces in conversation and reaches others on its own; the timeline lights up where it lands, with reach, latency, and match fidelity — re-derived from the sealed run, never faked.
+- **Descend into a mind.** Click an agent that is itself an org (a Jungian self) and drop into its inner council: the archetypes deliberate, the representative synthesizes and answers out. Recursion by data — an agent *is* an organization you haven't opened yet.
+- **Per-element storylines.** An agent, a room, a memory bank, a variable — each has its own timeline you can open, all linked to the one global cursor.
+
+Every element carries its real ledger id, and a run-header badge always discloses whether the dialogue came from real engines or a scripted screenplay.
+
+## The world
+
+A `Simfile` declares world mechanics, kept deliberately genre-neutral:
+
+| Key | What it is |
+|---|---|
+| **clock** | ticks, phases, sim-time |
+| **variables** | scoped state with ranges |
+| **generators** | deterministic or stochastic drivers that move variables |
+| **rules** | `when` conditions → effects (wake an agent, post a world message) |
+| **markers** | scan room traffic for tokens (a seeded secret, a name) |
+| **probes** | scored assertions evaluated over a run |
+| **run ledger** | the canonical, causally-ordered record everything else is measured against |
+
+Domain concepts live in fixtures, never in schema keys.
+
+## Example
+
+```yaml
+simfile_version: "0.1"
+name: autonomous-office-world
+spawnfile: ./Spawnfile
+
+clock:
+  seed: office-run-014
+  tick: 20s
+  sim_per_tick: 10m
+  phases: { morning: "07:00", workday: "09:00", evening: "18:00", night: "22:00" }
+
+variables:
+  filing_pressure:
+    scope: room:office-floor:case-warroom
+    initial: 0.4
+    range: 0..1
+
+generators:
+  deadline_ramp:
+    kind: deterministic
+    when: { phase: workday }
+    variable: filing_pressure
+    delta: 0.02
+
+rules:
+  deadline_bites:
+    when: { variable: filing_pressure, above: 0.85 }
+    do:
+      - action: wake:recommend
+        to: room:office-floor:case-warroom
+
+markers:
+  tenant_name:
+    text: [Rosa Delgado]
+    mode: containment
+    scopes: [room:office-floor:case-warroom]
+
+probes:
+  deadline_observed:
+    when: { event: wake.recommended, target: room:office-floor:case-warroom }
+    expect: { at_least: 1 }
+```
+
+## Observe
+
+`simfile observe <run-dir>` reconciles every authority's causal stream — Moltnet, Daimon, Mneme, and the world kernel — into one honest verdict: complete vs. incomplete causal chains, per-agent memory, failures, and, for a seeded world, spread measurement (channel · reach · latency · fidelity) re-derived from sealed artifacts. Ordering is causal, never wall-clock; a missing link is reported, never stitched.
+
+## Repo guide
+
+```text
+src/schema      v0.1 world schema + validator
+src/runtime     deterministic world kernel (clock, generators, rules, markers, probes)
+src/observe     causal reconciliation + spread measurement
+src/view + web  the run-replay viewer (React), served by `simfile view`
+src/sims        composed-run drivers (shell Spawnfile, seed, observe)
+docs/           design + research (DESIGN, VIEW_DESIGN, VIEW_STYLEGUIDE, …)
+```
+
+Simfile hardcodes constraints, not conclusions: it defines stable mechanics and observability, and leaves interpretation, strategy, dialogue, memory choice, and culture to the agents.
+
+## Docs
+
+Full documentation at [**simfile.org**](https://simfile.org). Design and research notes live in [`docs/`](docs/).
+
+## License
+
+MIT

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare const runCli: (argv: readonly string[]) => Promise<number>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAuRA,eAAO,MAAM,MAAM,GAAU,MAAM,SAAS,MAAM,EAAE,KAAG,OAAO,CAAC,MAAM,CAiJpE,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { ZodError } from "zod";
+import { createBindingDiagnostics, loadSpawnfileReport, parseSimfileSource } from "../schema/index.js";
+import { runObserve, writeObserveReport } from "../observe/index.js";
+import { writeRunRecord } from "../runtime/trace.js";
+import { runViewCommand } from "../view/index.js";
+const usage = () => [
+    "Usage:",
+    "  simfile validate <path> [--json] [--spawnfile-report <path>|<json>]",
+    "  simfile run <path> --ticks <n> [--out <dir>] [--seed <seed>] [--run-id <id>] [--acts <path>] [--moltnet-artifact transcript|delivery] [--spawnfile-report <path>|<json>]",
+    "  simfile observe <run-dir> [--json]",
+    "  simfile view --state <path>",
+    "  simfile view <run-record-dir>",
+    "  simfile view --help",
+    "  simfile --help",
+    ""
+].join("\n");
+const formatError = (error) => {
+    if (error instanceof ZodError) {
+        return error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("\n");
+    }
+    return error instanceof Error ? error.message : String(error);
+};
+const parseObserveArguments = (argv) => {
+    const options = {};
+    for (const arg of argv) {
+        if (arg === "--json") {
+            options.json = true;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return { error: `Unknown flag ${arg}` };
+        }
+        if (options.runDir !== undefined) {
+            return { error: `Unexpected positional argument ${arg}` };
+        }
+        options.runDir = arg;
+    }
+    if (!options.runDir)
+        return { error: "Missing run directory" };
+    return { options };
+};
+const parseOptionalValueFlag = (arg, argv, index, flag, errorMessage) => {
+    if (arg.startsWith(`${flag}=`)) {
+        return { consumed: true, value: arg.slice(flag.length + 1) };
+    }
+    if (arg !== flag) {
+        return { consumed: false };
+    }
+    const value = argv[index + 1];
+    if (!value) {
+        return { error: errorMessage, consumed: false };
+    }
+    return { consumed: true, value };
+};
+const parseValidateArguments = (argv) => {
+    const options = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--json") {
+            options.json = true;
+            continue;
+        }
+        const parsedReport = parseOptionalValueFlag(arg, argv, index, "--spawnfile-report", "Missing value for --spawnfile-report");
+        if (parsedReport.error)
+            return { error: parsedReport.error };
+        if (parsedReport.consumed) {
+            options.spawnfileReport = parsedReport.value;
+            if (arg === "--spawnfile-report")
+                index += 1;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return { error: `Unknown flag ${arg}` };
+        }
+        if (options.path !== undefined) {
+            return { error: `Unexpected positional argument ${arg}` };
+        }
+        options.path = arg;
+    }
+    if (!options.path)
+        return { error: "Missing Simfile path" };
+    return { options };
+};
+const parseRunArguments = (argv) => {
+    const options = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--ticks") {
+            const value = argv[index + 1];
+            if (!value)
+                return { error: "Missing value for --ticks" };
+            const ticks = Number(value);
+            if (!Number.isInteger(ticks) || ticks < 0)
+                return { error: "Invalid value for --ticks" };
+            options.ticks = ticks;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--ticks=")) {
+            const ticks = Number(arg.slice("--ticks=".length));
+            if (!Number.isInteger(ticks) || ticks < 0)
+                return { error: "Invalid value for --ticks" };
+            options.ticks = ticks;
+            continue;
+        }
+        if (arg === "--moltnet-artifact") {
+            const value = argv[index + 1];
+            if (value !== "delivery" && value !== "transcript") {
+                return { error: "Invalid value for --moltnet-artifact" };
+            }
+            options.moltnetArtifact = value;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--moltnet-artifact=")) {
+            const value = arg.slice("--moltnet-artifact=".length);
+            if (value !== "delivery" && value !== "transcript") {
+                return { error: "Invalid value for --moltnet-artifact" };
+            }
+            options.moltnetArtifact = value;
+            continue;
+        }
+        if (arg === "--out" || arg === "--seed" || arg === "--run-id" || arg === "--acts") {
+            const parsed = parseOptionalValueFlag(arg, argv, index, arg, `Missing value for ${arg}`);
+            if (parsed.error)
+                return { error: parsed.error };
+            if (parsed.value === undefined)
+                return { error: `Missing value for ${arg}` };
+            if (arg === "--out")
+                options.outDir = parsed.value;
+            if (arg === "--seed")
+                options.seed = parsed.value;
+            if (arg === "--run-id")
+                options.runId = parsed.value;
+            if (arg === "--acts")
+                options.actsPath = parsed.value;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--out=")) {
+            options.outDir = arg.slice("--out=".length);
+            continue;
+        }
+        if (arg.startsWith("--seed=")) {
+            options.seed = arg.slice("--seed=".length);
+            continue;
+        }
+        if (arg.startsWith("--run-id=")) {
+            options.runId = arg.slice("--run-id=".length);
+            continue;
+        }
+        if (arg.startsWith("--acts=")) {
+            options.actsPath = arg.slice("--acts=".length);
+            continue;
+        }
+        const parsedReport = parseOptionalValueFlag(arg, argv, index, "--spawnfile-report", "Missing value for --spawnfile-report");
+        if (parsedReport.error)
+            return { error: parsedReport.error };
+        if (parsedReport.consumed) {
+            options.spawnfileReport = parsedReport.value;
+            if (arg === "--spawnfile-report")
+                index += 1;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return { error: `Unknown flag ${arg}` };
+        }
+        if (options.path !== undefined) {
+            return { error: `Unexpected positional argument ${arg}` };
+        }
+        options.path = arg;
+    }
+    if (!options.path)
+        return { error: "Missing Simfile path" };
+    if (options.ticks === undefined)
+        return { error: "Missing required --ticks" };
+    return { options };
+};
+const defaultRunId = (seed) => seed.replace(/[^a-zA-Z0-9_.-]+/gu, "-").replace(/^-+|-+$/gu, "") || "run";
+const toBindingDiagnostics = (warnings) => warnings.map((message) => ({ level: "warn", message }));
+const bindingWarningsFromReport = async (simfile, reportSource) => {
+    if (!reportSource) {
+        return [];
+    }
+    return createBindingDiagnostics(simfile, await loadSpawnfileReport(reportSource));
+};
+const hasErrorDiagnostic = (diagnostics) => diagnostics.some((diagnostic) => diagnostic.level === "error");
+const loadQueuedWorldActs = async (actsPath) => {
+    if (!actsPath) {
+        return undefined;
+    }
+    const raw = JSON.parse(await readFile(actsPath, "utf8"));
+    if (!Array.isArray(raw)) {
+        throw new Error(`--acts file must contain a JSON array: ${actsPath}`);
+    }
+    return raw;
+};
+const printDiagnostics = (diagnostics) => {
+    for (const diagnostic of diagnostics) {
+        const prefix = diagnostic.level === "error" ? "error" : "warning";
+        process.stderr.write(`${prefix}: ${diagnostic.message}\n`);
+    }
+};
+export const runCli = async (argv) => {
+    const [command, ...rest] = argv;
+    if (command === "--help" || command === "-h" || command === undefined) {
+        process.stdout.write(usage());
+        return command === undefined ? 1 : 0;
+    }
+    if (command === "validate") {
+        const parsed = parseValidateArguments(rest);
+        if (parsed.error || !parsed.options?.path) {
+            if (parsed.error)
+                process.stderr.write(`${parsed.error}\n`);
+            process.stderr.write(usage());
+            return 1;
+        }
+        const path = parsed.options.path;
+        try {
+            const source = await readFile(path, "utf8");
+            const result = parseSimfileSource(source, { path });
+            const diagnostics = [
+                ...toBindingDiagnostics(result.warnings),
+                ...await bindingWarningsFromReport(result.simfile, parsed.options.spawnfileReport)
+            ];
+            if (parsed.options.json) {
+                process.stdout.write(`${JSON.stringify({
+                    diagnostics,
+                    ok: !hasErrorDiagnostic(diagnostics),
+                    path
+                }, null, 2)}\n`);
+            }
+            else {
+                printDiagnostics(diagnostics);
+                if (hasErrorDiagnostic(diagnostics)) {
+                    process.stderr.write(`failed to validate ${path}\n`);
+                    return 1;
+                }
+                process.stdout.write(`validated ${path}\n`);
+            }
+            return hasErrorDiagnostic(diagnostics) ? 1 : 0;
+        }
+        catch (error) {
+            process.stderr.write(`${formatError(error)}\n`);
+            return 1;
+        }
+    }
+    if (command === "run") {
+        const parsed = parseRunArguments(rest);
+        if (parsed.error || !parsed.options?.path || parsed.options.ticks === undefined) {
+            if (parsed.error)
+                process.stderr.write(`${parsed.error}\n`);
+            process.stderr.write(usage());
+            return 1;
+        }
+        const path = parsed.options.path;
+        try {
+            const source = await readFile(path, "utf8");
+            const result = parseSimfileSource(source, { path });
+            const diagnostics = [
+                ...toBindingDiagnostics(result.warnings),
+                ...await bindingWarningsFromReport(result.simfile, parsed.options.spawnfileReport)
+            ];
+            printDiagnostics(diagnostics);
+            if (hasErrorDiagnostic(diagnostics)) {
+                process.stderr.write("failed to validate simulation before running\n");
+                return 1;
+            }
+            const seed = parsed.options.seed ?? result.simfile.clock.seed;
+            const runId = parsed.options.runId ?? defaultRunId(seed);
+            const outDir = resolve(parsed.options.outDir ?? `runs/${runId}`);
+            const worldActs = await loadQueuedWorldActs(parsed.options.actsPath);
+            const record = await writeRunRecord({
+                moltnetArtifact: parsed.options.moltnetArtifact,
+                outDir,
+                runId,
+                seed,
+                simfile: result.simfile,
+                sourcePath: path,
+                sourceText: source,
+                ticks: parsed.options.ticks,
+                worldActs
+            });
+            process.stdout.write(`wrote run ${runId} to ${record.outDir}\n`);
+            return 0;
+        }
+        catch (error) {
+            process.stderr.write(`${formatError(error)}\n`);
+            return 1;
+        }
+    }
+    if (command === "observe") {
+        const parsed = parseObserveArguments(rest);
+        if (parsed.error || !parsed.options?.runDir) {
+            if (parsed.error)
+                process.stderr.write(`${parsed.error}\n`);
+            process.stderr.write(usage());
+            return 1;
+        }
+        const runDir = resolve(parsed.options.runDir);
+        try {
+            const result = await runObserve(runDir);
+            const reportPath = await writeObserveReport(runDir, result.report);
+            const failedArtifacts = result.artifactIntegrity.filter((check) => !check.ok);
+            for (const failed of failedArtifacts) {
+                process.stderr.write(`warning: artifact sha256 mismatch for ${failed.path} (expected ${failed.expectedSha256}, got ${failed.actualSha256 ?? "<missing>"})\n`);
+            }
+            for (const parseError of result.causalParseErrors) {
+                process.stderr.write(`warning: ${parseError.relativePath}:${parseError.line}: ${parseError.message}\n`);
+            }
+            if (parsed.options.json) {
+                process.stdout.write(`${JSON.stringify({
+                    artifactIntegrity: result.artifactIntegrity,
+                    causalParseErrors: result.causalParseErrors,
+                    report: result.report,
+                    reportPath
+                }, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write(`wrote observe report for run ${result.report.run_id} to ${reportPath}\n`);
+                process.stdout.write(`participants: ${result.report.participants.join(", ")}\n`);
+                process.stdout.write(`agent turns: ${result.report.agent_turns.count} (${result.report.agent_turns.sequence.join(" -> ")})\n`);
+                process.stdout.write(`chains: ${result.report.chains.complete} complete, ${result.report.chains.incomplete.length} incomplete\n`);
+                process.stdout.write(`failures: ${result.report.failures.length}\n`);
+            }
+            return failedArtifacts.length > 0 ? 1 : 0;
+        }
+        catch (error) {
+            process.stderr.write(`${formatError(error)}\n`);
+            return 1;
+        }
+    }
+    if (command === "view") {
+        return runViewCommand(rest);
+    }
+    if (command !== "validate" || !rest.length) {
+        process.stderr.write(usage());
+        return 1;
+    }
+    process.stderr.write(usage());
+    return 1;
+};
+if (import.meta.url === `file://${process.argv[1]}`) {
+    process.exitCode = await runCli(process.argv.slice(2));
+}

package/dist/coverage/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./matrix.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/coverage/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/coverage/index.js

@@ -0,0 +1 @@
+export * from "./matrix.js";

package/dist/coverage/matrix.d.ts

@@ -0,0 +1,21 @@
+export declare const systemViewTopLevelKeys: readonly ["simfile_version", "name", "spawnfile", "clock", "variables", "generators", "rules", "ledger", "telemetry", "markers", "probes"];
+export declare const coveragePrimitives: readonly ["clock", "variables", "generators", "rules", "ledger", "telemetry", "markers/probes"];
+export type TopLevelKey = typeof systemViewTopLevelKeys[number];
+export type CoveragePrimitive = typeof coveragePrimitives[number];
+export type CoverageStatus = "implemented" | "deferred" | `planned:B${number}`;
+export type CoverageSubject = {
+    kind: "top-level";
+    key: TopLevelKey;
+} | {
+    kind: "primitive";
+    primitive: CoveragePrimitive;
+};
+export interface CoverageRow {
+    subject: CoverageSubject;
+    claim: string;
+    specRef: string;
+    status: CoverageStatus;
+    evidence: string;
+}
+export declare const matrix: CoverageRow[];
+//# sourceMappingURL=matrix.d.ts.map

package/dist/coverage/matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix.d.ts","sourceRoot":"","sources":["../../src/coverage/matrix.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,4IAYzB,CAAC;AAEX,eAAO,MAAM,kBAAkB,iGAQrB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,OAAO,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAChE,MAAM,MAAM,iBAAiB,GAAG,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAElE,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,UAAU,GACV,YAAY,MAAM,EAAE,CAAC;AAEzB,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,WAAW,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAExD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,eAAe,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,MAAM,EAAE,WAAW,EAsJ/B,CAAC"}