persistent-world-sim

A local persistent-world simulation engine: SQLite-backed state with CAS content addressing, idempotent operations, immutable revisions, and fail-closed billing rails.

Built as the state layer for a long-running simulated environment where multiple agents share one persistent world — every mutation is content-addressed and idempotent, every revision is immutable, and money gates fail closed (a missing webhook secret means billing endpoints refuse, not guess).

What's in here

server.mjs          HTTP API over the sim store (Node >= 22, ESM, stdlib only)
billing.mjs         webhook-signature verification + fail-closed billing gates
test.mjs            node --test suite: CAS, idempotency, revisions, path traversal, billing
scripts/            world-building tooling: house/room builders (GLB), census, roster inventory
assets/             seed-world reference assets (Kenney CC0 + CC-BY furnishing)

Design decisions

• Content-addressed state. Every mutation is hashed; replaying the same operation twice is a no-op. Idempotency is the foundation for multi-agent worlds where retries and races are normal.
• Immutable revisions. World history is append-only — corrections are new revisions, never edits. Auditable by construction.
• Fail-closed billing. verifySignature throws when the secret is unconfigured; endpoints return 503 rather than processing unsigned payloads. Payment rails are the one place where "fail open" is never acceptable.
• Path traversal rejected. Media endpoints resolve inside the store root only (tested).

Run

PORT=8907 node server.mjs   # http://127.0.0.1:8907/

Tests

npm install
npm test    # node --test — loopback only, fresh temp DB

Status

Local operator pilot: loopback only, no auth on non-billing endpoints by design (single-operator world). Not deployed.

License

MIT