Skip to content

feat: add local experiment archive - #27

Merged
christopherjnelson merged 1 commit into
mainfrom
feat/0020-experiment-archive
Aug 20, 2026
Merged

christopherjnelson merged 1 commit into
mainfrom
feat/0020-experiment-archive

Conversation

@christopherjnelson

Copy link
Copy Markdown
Member

Scope

Adds a durable local SQLite experiment archive and compact query CLI for schema-v9 exports, plus FTS-searchable curated research notes. The active in-memory engine remains authoritative; this PR does not change gameplay, prompts, Patient Zero behavior, scheduling, map behavior, or World Lab UX.

Schema and service decisions

  • Uses Node 24 built-in node:sqlite with versioned migrations, strict tables, foreign keys, useful indexes, WAL for file databases, prepared statements, and transactional batch import.
  • Normalizes authoritative turns, attempts, actions, communications, diplomacy/alliance/world events, roster/configuration, topology, retention, and provenance.
  • Stable identifiers and source hashes make reimports idempotent.
  • Preserves source aggregate metrics for audit while deriving canonical query metrics from stored records.
  • Defines canonical direction changes after communication as the sum of per-agent chronological calculations and reports source inconsistencies.
  • Separates messages to Patient Zero, replies after directives, and observable compliance.
  • Keeps query and note services application-independent for a future read-only adapter.

Local verification

  • Imported both existing logs/ schema-v9 exports: 923 and 954 inserted records.
  • Reimported the latest export: 0 inserted, 1 existing, 0 skipped, 0 rejected.
  • Queried latest summary and Patient Zero analysis; compared both runs with per-turn, per-agent-turn, per-active-agent, and per-Patient-Zero-turn rates.
  • Imported and FTS-searched an accepted Markdown implementation note.
  • Reopened the database in fresh processes and repeated list/summary successfully.
  • Confirmed SQLite, WAL, and shared-memory files are ignored and untracked.
  • pnpm validate — passed.
  • pnpm test:e2e — passed (1 Chromium test).

Risks and boundaries

  • This is an append-only research archive, not crash recovery or restartable simulation state.
  • Import currently accepts the schema-v9 export produced by main and rejects malformed or unsupported input transactionally.
  • Compliance remains indeterminate when a free-text directive cannot map unambiguously to one structured action.
  • Local archive and note contents remain untrusted data and are excluded from Git.

Intentionally deferred

MCP, embeddings, vector databases/search, a database browser, arbitrary SQL, active-runtime persistence, and restartable simulations are intentionally out of scope. A future read-only MCP adapter can reuse ExperimentQueryService and ResearchNoteService.

@christopherjnelson
christopherjnelson marked this pull request as ready for review August 20, 2026 08:12
@christopherjnelson
christopherjnelson merged commit 54d217a into main Aug 20, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant