@possumtech/rummy 0.5.0 → 2.0.1

package/bin/demo.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// Fast inspector for the most recent (or a named) run.
+//
+// Pulls the packet the model actually saw (system://N, user://N), the
+// model's response (assistant://N, reasoning://N), the log entries for
+// the turn, and optional summaries across the whole run.
+//
+// Usage:
+//   npm run test:demo                  # latest run, latest turn
+//   npm run test:demo -- --turn 5      # latest run, turn 5
+//   npm run test:demo -- --run alias   # specific run, its latest turn
+//   npm run test:demo -- --all         # all turns' headers + final packet
+//   npm run test:demo -- --packet      # only dump system/user/assistant
+
+import { parseArgs } from "node:util";
+import { DatabaseSync } from "node:sqlite";
+import { readFileSync } from "node:fs";
+
+const args = parseArgs({
+	options: {
+		run: { type: "string" },
+		turn: { type: "string" },
+		all: { type: "boolean", default: false },
+		packet: { type: "boolean", default: false },
+		db: { type: "string", default: "rummy_dev.db" },
+	},
+	allowPositionals: false,
+}).values;
+
+const db = new DatabaseSync(args.db);
+
+const runRow = args.run
+	? db.prepare("SELECT * FROM runs WHERE alias = ?").get(args.run)
+	: db.prepare("SELECT * FROM runs ORDER BY id DESC LIMIT 1").get();
+
+if (!runRow) {
+	console.error(args.run ? `run ${args.run} not found` : "no runs in db");
+	process.exit(1);
+}
+
+const runId = runRow.id;
+const alias = runRow.alias;
+
+const turns = db
+	.prepare(
+		"SELECT sequence, context_tokens, prompt_tokens, completion_tokens, reasoning_tokens, total_tokens, cost FROM turns WHERE run_id = ? ORDER BY sequence",
+	)
+	.all(runId);
+
+const selectedTurn = args.turn ? Number(args.turn) : turns.at(-1)?.sequence;
+
+const banner = (s) => console.log(`\n━━━ ${s} ${"━".repeat(Math.max(4, 70 - s.length))}`);
+
+const loadBody = (path) => {
+	const row = db
+		.prepare(
+			"SELECT e.body, e.attributes, rv.state, rv.outcome, rv.visibility FROM entries e JOIN run_views rv ON rv.entry_id = e.id WHERE rv.run_id = ? AND e.path = ?",
+		)
+		.get(runId, path);
+	return row ? row : null;
+};
+
+// ── header ─────────────────────────────────────────────────────────
+const totalCost = turns.reduce((s, t) => s + (t.cost || 0), 0);
+banner(`run ${alias}  (id=${runId}, status=${runRow.status})`);
+console.log(
+	`model=${runRow.model}  turns=${turns.length}  cost=${totalCost.toFixed(6)}`,
+);
+
+if (!args.packet) {
+	banner("turns");
+	for (const t of turns) {
+		const marker = t.sequence === selectedTurn ? "▶" : " ";
+		console.log(
+			`${marker} turn ${String(t.sequence).padStart(2)}  ctx=${String(t.context_tokens).padStart(6)}  in=${String(t.prompt_tokens).padStart(6)}  out=${String(t.completion_tokens).padStart(5)}  reason=${String(t.reasoning_tokens).padStart(5)}`,
+		);
+	}
+}
+
+// ── packet for the selected turn ───────────────────────────────────
+if (selectedTurn) {
+	const system = loadBody(`system://${selectedTurn}`);
+	const user = loadBody(`user://${selectedTurn}`);
+	const assistant = loadBody(`assistant://${selectedTurn}`);
+	const reasoning = loadBody(`reasoning://${selectedTurn}`);
+
+	banner(`turn ${selectedTurn} — system://`);
+	console.log(system ? system.body : "(not recorded)");
+	banner(`turn ${selectedTurn} — user://`);
+	console.log(user ? user.body : "(not recorded)");
+	banner(`turn ${selectedTurn} — assistant://`);
+	console.log(assistant ? assistant.body : "(not recorded)");
+	if (reasoning) {
+		banner(`turn ${selectedTurn} — reasoning://`);
+		console.log(reasoning.body);
+	}
+}
+
+if (args.packet) process.exit(0);
+
+// ── log entries for the selected turn ──────────────────────────────
+if (selectedTurn) {
+	banner(`turn ${selectedTurn} — log entries`);
+	const logs = db
+		.prepare(
+			"SELECT e.path, e.body, e.attributes, rv.state, rv.outcome, rv.visibility FROM entries e JOIN run_views rv ON rv.entry_id = e.id WHERE rv.run_id = ? AND rv.turn = ? AND e.path LIKE 'log://%' ORDER BY e.id",
+		)
+		.all(runId, selectedTurn);
+	if (logs.length === 0) console.log("(none)");
+	for (const l of logs) {
+		const attrs = l.attributes ? JSON.parse(l.attributes) : {};
+		const body = l.body ? l.body.replace(/\n/g, "⏎").slice(0, 100) : "";
+		console.log(
+			`  ${l.state.padEnd(9)} ${l.visibility.padEnd(10)} ${l.path}`,
+		);
+		if (Object.keys(attrs).length > 0)
+			console.log(`    attrs: ${JSON.stringify(attrs).slice(0, 200)}`);
+		if (body) console.log(`    body:  ${body}`);
+	}
+}
+
+// ── unresolved (proposals awaiting client) ─────────────────────────
+banner("unresolved");
+const pending = db
+	.prepare(
+		"SELECT e.path, substr(e.attributes,1,200) AS attrs, rv.turn FROM entries e JOIN run_views rv ON rv.entry_id = e.id WHERE rv.run_id = ? AND rv.state IN ('proposed','streaming') ORDER BY e.id",
+	)
+	.all(runId);
+if (pending.length === 0) console.log("(none)");
+for (const p of pending) console.log(`  turn ${p.turn}  ${p.path}\n    ${p.attrs}`);
+
+// ── unknowns + knowns tally ────────────────────────────────────────
+const unknowns = db
+	.prepare(
+		"SELECT e.path, e.body FROM entries e JOIN run_views rv ON rv.entry_id = e.id WHERE rv.run_id = ? AND e.scheme = 'unknown' ORDER BY e.id",
+	)
+	.all(runId);
+banner(`unknowns (${unknowns.length})`);
+for (const u of unknowns)
+	console.log(`  ${u.path}\n    ${u.body.slice(0, 120)}`);
+
+const knowns = db
+	.prepare(
+		"SELECT e.path FROM entries e JOIN run_views rv ON rv.entry_id = e.id WHERE rv.run_id = ? AND e.scheme = 'known' ORDER BY e.id",
+	)
+	.all(runId);
+banner(`knowns (${knowns.length})`);
+for (const k of knowns) console.log(`  ${k.path}`);
+
+// ── all turns (if --all) ───────────────────────────────────────────
+if (args.all) {
+	for (const t of turns) {
+		if (t.sequence === selectedTurn) continue;
+		const system = loadBody(`system://${t.sequence}`);
+		const user = loadBody(`user://${t.sequence}`);
+		const assistant = loadBody(`assistant://${t.sequence}`);
+		banner(`turn ${t.sequence} — system://`);
+		console.log(system ? system.body : "(not recorded)");
+		banner(`turn ${t.sequence} — user://`);
+		console.log(user ? user.body : "(not recorded)");
+		banner(`turn ${t.sequence} — assistant://`);
+		console.log(assistant ? assistant.body : "(not recorded)");
+	}
+}
+
+db.close();

package/bin/rummy.js

@@ -10,9 +10,15 @@ const packageRoot = join(__dirname, "..");
 
 const rummyHome = process.env.RUMMY_HOME || join(homedir(), ".rummy");
 
-// Load defaults, then user overrides
-process.loadEnvFile(join(packageRoot, ".env.example"));
-const userEnv = join(rummyHome, ".env");
+// Base dir for env files: cwd if it has .env.example, else $RUMMY_HOME.
+// The package's own .env.example is never consulted — silent package-
+// root defaults break the project-as-context model and hide behavior
+// from the user.
+const cwd = process.cwd();
+const baseDir = existsSync(join(cwd, ".env.example")) ? cwd : rummyHome;
+
+process.loadEnvFile(join(baseDir, ".env.example"));
+const userEnv = join(baseDir, ".env");
 if (existsSync(userEnv)) process.loadEnvFile(userEnv);
 
 // Resolve RUMMY_HOME and make DB path absolute relative to it

package/biome/no-fallbacks.grit

@@ -0,0 +1,50 @@
+// No silent fallbacks outside hedberg.
+// Rule: interiors crash on contract violation, boundaries validate.
+// Patterns like `|| 0`, `?? ""` silently mask missing data.
+// hedberg is the stochastic-interpretation boundary — fallbacks
+// there are legitimate and filtered out below.
+//
+// Two classes caught:
+//   1. Falsy-literal defaults: `$_ || 0` / `$_ ?? ""` / etc.
+//   2. Env-var defaults: `process.env.X || <anything>`. These mask
+//      a missing documented env var; the right shape is either a
+//      naked `Number(process.env.X)` (NaN propagates on absence)
+//      or `process.env.X` directly.
+
+language js
+
+or {
+  `$_ || 0`,
+  `$_ || ""`,
+  `$_ || ''`,
+  `$_ || null`,
+  `$_ || false`,
+  `$_ || []`,
+  `$_ || {}`,
+  `$_ ?? 0`,
+  `$_ ?? ""`,
+  `$_ ?? ''`,
+  `$_ ?? null`,
+  `$_ ?? false`,
+  `$_ ?? []`,
+  `$_ ?? {}`,
+  `process.env.$_ || $_`,
+  `process.env.$_ ?? $_`,
+  `Number(process.env.$_) || $_`,
+  `Number(process.env.$_) ?? $_`,
+  `parseInt(process.env.$_, $_) || $_`,
+  `parseInt(process.env.$_, $_) ?? $_`,
+  `Number.parseInt(process.env.$_, $_) || $_`,
+  `Number.parseInt(process.env.$_, $_) ?? $_`,
+  `Number.parseFloat(process.env.$_) || $_`,
+  `Number.parseFloat(process.env.$_) ?? $_`
+} as $match where {
+  $filename <: not includes "src/plugins/hedberg/",
+  $filename <: not includes "src/agent/XmlParser.js",
+  $filename <: not includes "/test/",
+  $filename <: not includes ".test.js",
+  register_diagnostic(
+    span = $match,
+    message = "Silent fallback outside hedberg masks contract violations — fix the contract instead."
+  )
+}

package/lang/en.json

@@ -27,8 +27,8 @@
 	"error.tool_already_registered": "Tool '{name}' already registered.",
 	"error.rpc_already_registered": "RPC method '{name}' already registered.",
 	"error.resolution_invalid": "Invalid resolution action: {action}. Use 'accept' or 'reject'.",
-	"error.xai_base_url_missing": "x.ai/ model requested but XAI_BASE_URL is not set.",
-	"error.xai_api_key_missing": "x.ai/ model requested but XAI_API_KEY is not set.",
+	"error.xai_base_url_missing": "xai/ model requested but XAI_BASE_URL is not set.",
+	"error.xai_api_key_missing": "xai/ model requested but XAI_API_KEY is not set.",
 	"error.xai_auth": "xAI Authentication Error: {status}. Please check your XAI_API_KEY.",
 	"error.xai_api": "xAI API error: {status}"
 }

package/migrations/001_initial_schema.sql

@@ -4,13 +4,19 @@ PRAGMA mmap_size = $mmap_size;
 -- INIT: initial_schema
 
 -- Scheme registry: single source of truth for all scheme metadata.
--- Status codes are HTTP: 2xx success, 3xx redirect, 4xx model error, 5xx system error.
--- No valid_states — HTTP semantics are universal.
--- No fidelity — entries don't decide their own importance.
+-- writable_by: JSON array of {system, plugin, client, model} — four writer tiers.
+-- capability_class: optional restriction group (e.g. "shell", "files", "web")
+-- so the policy plugin can compute the effective toolset from a run's
+-- restriction list. Null means the scheme is always available.
 CREATE TABLE IF NOT EXISTS schemes (
 	name TEXT PRIMARY KEY
 	, model_visible BOOLEAN NOT NULL DEFAULT 1
 	, category TEXT
+	, default_scope TEXT NOT NULL DEFAULT 'run'
+	CHECK (default_scope IN ('run', 'project', 'global'))
+	, writable_by JSON NOT NULL DEFAULT '["model","plugin"]'
+	CHECK (json_valid(writable_by))
+	, capability_class TEXT
 );
 
 -- Schemes are registered by plugins at startup via core.registerScheme().
@@ -98,7 +104,7 @@ CREATE TABLE IF NOT EXISTS turns (
 CREATE INDEX IF NOT EXISTS idx_turns_run_seq ON turns (run_id, sequence);
 
 -- File constraints: client-set visibility rules, project-scoped.
--- Persists across runs. Orthogonal to fidelity.
+-- Persists across runs. Orthogonal to visibility.
 CREATE TABLE IF NOT EXISTS file_constraints (
 	id INTEGER PRIMARY KEY AUTOINCREMENT
 	, project_id INTEGER NOT NULL REFERENCES projects (id) ON DELETE CASCADE
@@ -110,50 +116,93 @@ CREATE TABLE IF NOT EXISTS file_constraints (
 CREATE INDEX IF NOT EXISTS idx_file_constraints_project
 ON file_constraints (project_id);
 
--- Known K/V Store: the unified state machine.
--- Files, knowledge, tool results, audit — everything is a keyed entry.
+-- Entries: content-addressable by (scope, path). The actual payload.
+-- scope: 'global' | 'project:N' | 'run:N'. Determines read access.
 -- scheme: derived from path via schemeOf(). Generated column.
--- status: HTTP status code (2xx success, 4xx model error, 5xx system error).
--- fidelity: visibility level, independently managed by relevance engine.
-CREATE TABLE IF NOT EXISTS known_entries (
+-- No visibility, status, turn, loop — those are view-side concerns.
+CREATE TABLE IF NOT EXISTS entries (
+	id INTEGER PRIMARY KEY AUTOINCREMENT
+	, scope TEXT NOT NULL
+	, path TEXT NOT NULL CHECK (length(path) <= 2048)
+	, scheme TEXT GENERATED ALWAYS AS (schemeOf(path)) STORED
+	, body TEXT NOT NULL DEFAULT ''
+	, attributes JSON NOT NULL DEFAULT '{}' CHECK (json_valid(attributes))
+	, hash TEXT
+	, created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+	, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_entries_scope_path
+ON entries (scope, path);
+CREATE INDEX IF NOT EXISTS idx_entries_scope_scheme
+ON entries (scope, scheme);
+
+-- Run views: per-run projection of entries. State, visibility, turn live here.
+-- A run has at most one view of any given entry. Absent view = not in context.
+-- state: lifecycle. visibility: what the model sees. Orthogonal axes (SPEC §0.1).
+-- outcome: short reason string when state ∈ {failed, cancelled}; NULL otherwise.
+CREATE TABLE IF NOT EXISTS run_views (
 	id INTEGER PRIMARY KEY AUTOINCREMENT
 	, run_id INTEGER NOT NULL REFERENCES runs (id) ON DELETE CASCADE
+	, entry_id INTEGER NOT NULL REFERENCES entries (id) ON DELETE CASCADE
 	, loop_id INTEGER REFERENCES loops (id) ON DELETE CASCADE
 	, turn INTEGER NOT NULL DEFAULT 0 CHECK (turn >= 0)
-	, path TEXT NOT NULL CHECK (length(path) <= 2048)
-	, body TEXT NOT NULL DEFAULT ''
-	, scheme TEXT GENERATED ALWAYS AS (schemeOf(path)) STORED
-	, status INTEGER NOT NULL DEFAULT 200 CHECK (status BETWEEN 100 AND 599)
-	, fidelity TEXT NOT NULL DEFAULT 'promoted' CHECK (
-		fidelity IN ('promoted', 'demoted', 'archived')
+	, state TEXT NOT NULL DEFAULT 'resolved' CHECK (
+		state IN ('proposed', 'streaming', 'resolved', 'failed', 'cancelled')
+	)
+	, outcome TEXT
+	, visibility TEXT NOT NULL DEFAULT 'visible' CHECK (
+		visibility IN ('visible', 'summarized', 'archived')
 	)
-	, hash TEXT
-	, attributes JSON NOT NULL DEFAULT '{}' CHECK (json_valid(attributes))
-	, tokens INTEGER NOT NULL DEFAULT 0 CHECK (tokens >= 0)
-	, refs INTEGER NOT NULL DEFAULT 0 CHECK (refs >= 0)
 	, write_count INTEGER NOT NULL DEFAULT 1 CHECK (write_count >= 1)
+	, refs INTEGER NOT NULL DEFAULT 0 CHECK (refs >= 0)
 	, created_at DATETIME DEFAULT CURRENT_TIMESTAMP
 	, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
 );
-CREATE UNIQUE INDEX IF NOT EXISTS idx_known_entries_run_path
-ON known_entries (run_id, path);
-CREATE INDEX IF NOT EXISTS idx_known_entries_scheme_status
-ON known_entries (run_id, scheme, status);
-CREATE INDEX IF NOT EXISTS idx_known_entries_turn
-ON known_entries (run_id, turn);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_run_views_run_entry
+ON run_views (run_id, entry_id);
+CREATE INDEX IF NOT EXISTS idx_run_views_run_turn
+ON run_views (run_id, turn);
+CREATE INDEX IF NOT EXISTS idx_run_views_run_visibility
+ON run_views (run_id, visibility);
 
--- No state validation triggers — HTTP status codes are universal.
+-- Legacy-shape compatibility view. Joins run_views to entries; reads
+-- against this view keep one shape. Writes MUST target entries +
+-- run_views directly.
+CREATE VIEW IF NOT EXISTS known_entries AS
+SELECT
+	rv.id AS id
+	, rv.run_id AS run_id
+	, rv.loop_id AS loop_id
+	, rv.turn AS turn
+	, e.path AS path
+	, e.body AS body
+	, e.scheme AS scheme
+	, rv.state AS state
+	, rv.outcome AS outcome
+	, rv.visibility AS visibility
+	, e.hash AS hash
+	, e.attributes AS attributes
+	, rv.refs AS refs
+	, rv.write_count AS write_count
+	, e.created_at AS created_at
+	, rv.updated_at AS updated_at
+	, e.id AS entry_id
+	, e.scope AS scope
+FROM run_views AS rv
+JOIN entries AS e ON e.id = rv.entry_id;
 
--- UNRESOLVED VIEW: all entries awaiting user action (202 Accepted)
+-- UNRESOLVED VIEW: entries that haven't reached a terminal state.
+-- Proposed (awaiting user decision) or streaming (in-flight).
 CREATE VIEW IF NOT EXISTS v_unresolved AS
 SELECT
-	run_id
-	, path
-	, body
-	, attributes
-	, turn
-FROM known_entries
-WHERE status = 202;
+	rv.run_id
+	, e.path
+	, e.body
+	, e.attributes
+	, rv.turn
+FROM run_views AS rv
+JOIN entries AS e ON e.id = rv.entry_id
+WHERE rv.state IN ('proposed', 'streaming');
 
 -- Turn context: materialized snapshot of what the model sees each turn.
 -- known_entries is the warehouse. turn_context is the shipment.
@@ -165,10 +214,12 @@ CREATE TABLE IF NOT EXISTS turn_context (
 	, ordinal INTEGER NOT NULL CHECK (ordinal >= 0)
 	, path TEXT NOT NULL
 	, scheme TEXT GENERATED ALWAYS AS (schemeOf(path)) STORED
-	, status INTEGER NOT NULL DEFAULT 200 CHECK (status BETWEEN 100 AND 599)
-	, fidelity TEXT NOT NULL CHECK (fidelity IN ('promoted', 'demoted'))
+	, state TEXT NOT NULL DEFAULT 'resolved' CHECK (
+		state IN ('proposed', 'streaming', 'resolved', 'failed', 'cancelled')
+	)
+	, outcome TEXT
+	, visibility TEXT NOT NULL CHECK (visibility IN ('visible', 'summarized'))
 	, body TEXT NOT NULL DEFAULT ''
-	, tokens INTEGER NOT NULL DEFAULT 0 CHECK (tokens >= 0)
 	, attributes JSON NOT NULL DEFAULT '{}' CHECK (json_valid(attributes))
 	, category TEXT NOT NULL DEFAULT 'logging'
 	, source_turn INTEGER DEFAULT 0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@possumtech/rummy",
-	"version": "0.5.0",
+	"version": "2.0.1",
 	"description": "Relational Unknowns Memory Management Yoke",
 	"keywords": [
 		"llm"
@@ -37,21 +37,23 @@
 		"fix:sql": ". .venv/bin/activate && sqlfluff fix . --force",
 		"test": "npm run lint && npm run test:unit && npm run test:intg",
 		"test:all": "npm run lint && npm run test:unit && npm run test:intg && npm run test:e2e",
-		"test:unit": "node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.test --experimental-test-coverage --test-coverage-lines=50 --test-coverage-branches=50 --test-coverage-functions=50 --test-concurrency=1 --test-force-exit --test $(find src -name '*.test.js')",
-		"test:intg": "node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.test --test-concurrency=1 --test $(find test/integration -name '*.test.js')",
+		"test:unit": "node --env-file-if-exists=.env.example --env-file-if-exists=.env.test --experimental-test-coverage --test-coverage-lines=50 --test-coverage-branches=50 --test-coverage-functions=50 --test-concurrency=1 --test-force-exit --test $(find src -name '*.test.js')",
+		"test:intg": "node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.test --test-concurrency=1 --test-force-exit --test $(find test/integration -name '*.test.js')",
 		"test:e2e": "mkdir -p /tmp/rummy_test_diag && node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.test --test-concurrency=1 --test-force-exit --test-reporter=spec --test $(find test/e2e -name '*.test.js') 2>&1 | tee /tmp/rummy_test_diag/e2e_$(date +%Y%m%dT%H%M%S).log",
 		"test:live": "mkdir -p /tmp/rummy_test_diag && node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.test --test-concurrency=1 --test-force-exit --test-reporter=spec --test $(find test/live -name '*.test.js') 2>&1 | tee /tmp/rummy_test_diag/live_$(date +%Y%m%dT%H%M%S).log",
-		"test:clean": "rm -rf test/lme/results test/mab/results test/tmp /tmp/rummy_test_diag /tmp/rummy_test_*.db /tmp/rummy_test_*.db-shm /tmp/rummy_test_*.db-wal && echo 'Test artifacts cleaned.'",
-		"test:mab:get": "node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.test test/mab/download.js",
-		"test:mab": "bash -c 'mkdir -p /tmp/rummy_test_diag && node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.test test/mab/runner.js \"$@\" 2>&1 | tee /tmp/rummy_test_diag/mab_$(date +%Y%m%dT%H%M%S).log' --",
-		"test:grok": "bash -c 'mkdir -p /tmp/rummy_test_diag && node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.test --env-file-if-exists=.env.grok test/mab/runner.js \"$@\" 2>&1 | tee /tmp/rummy_test_diag/mab_grok_$(date +%Y%m%dT%H%M%S).log' --",
-		"test:mab:taxonomy": "bash -c 'mkdir -p /tmp/rummy_test_diag && node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.test test/mab/runner.js --split Conflict_Resolution --row 0 --no-questions 2>&1 | tee /tmp/rummy_test_diag/taxonomy_$(date +%Y%m%dT%H%M%S).log' --",
-		"test:grok:taxonomy": "bash -c 'mkdir -p /tmp/rummy_test_diag && node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.test --env-file-if-exists=.env.grok test/mab/runner.js --split Conflict_Resolution --row 0 --no-questions 2>&1 | tee /tmp/rummy_test_diag/taxonomy_grok_$(date +%Y%m%dT%H%M%S).log' --",
+		"test:clean": "rm -rf test/lme/results test/swe/results test/swe/repos test/tmp /tmp/rummy_test_diag /tmp/rummy_test_*.db /tmp/rummy_test_*.db-shm /tmp/rummy_test_*.db-wal && echo 'Test artifacts cleaned.'",
 		"test:lme:get": "node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.test test/lme/download.js",
 		"test:lme": "bash -c 'mkdir -p /tmp/rummy_test_diag && node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.test test/lme/runner.js \"$@\" 2>&1 | tee /tmp/rummy_test_diag/lme_$(date +%Y%m%dT%H%M%S).log' --",
-		"test:mab:clean": "rm -rf test/mab/results/*/",
+		"test:swe:setup": "bash test/swe/setup.sh",
+		"test:swe:get": "node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.test test/swe/download.js",
+		"test:swe": "bash -c 'mkdir -p /tmp/rummy_test_diag && node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.test test/swe/runner.js \"$@\" 2>&1 | tee /tmp/rummy_test_diag/swe_$(date +%Y%m%dT%H%M%S).log' --",
+		"test:swe:eval": "bash -c 'cd test/swe && source .venv/bin/activate && python evaluate.py \"$@\"' --",
+		"test:swe:baseline": "bash -c 'cd test/swe && source .venv/bin/activate && python baseline.py \"$@\"' --",
 		"test:lme:clean": "rm -rf test/lme/results/*/",
-		"test:clear": "rm -rf /tmp/rummy_test_diag /tmp/rummy_test_*.db /tmp/rummy_test_*.db-shm /tmp/rummy_test_*.db-wal /tmp/rummy-stories-*"
+		"test:swe:clean": "rm -rf test/swe/results/*/ test/swe/repos/",
+		"test:clear": "rm -rf /tmp/rummy_test_diag /tmp/rummy_test_*.db /tmp/rummy_test_*.db-shm /tmp/rummy_test_*.db-wal /tmp/rummy-stories-*",
+		"test:demo": "node --env-file-if-exists=.env.example --env-file-if-exists=.env bin/demo.js",
+		"test:spec": "node test/spec-coverage.js"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.6"

package/scriptify/ask_run.js

@@ -0,0 +1,77 @@
+/**
+ * Inject a follow-up question into an existing LME run and print the answer.
+ *
+ * Usage: node scriptify/ask_run.js <db_path> <run_alias> "your question"
+ *
+ * Reuses the run's full ingested context so the model answers with all
+ * its accumulated knowledge. Used as a debugging tool to interrogate
+ * the model's reasoning after a benchmark completes.
+ */
+import TestDb from "../test/helpers/TestDb.js";
+import TestServer from "../test/helpers/TestServer.js";
+import RpcClient from "../test/helpers/RpcClient.js";
+
+const [, , dbPath, alias, ...questionParts] = process.argv;
+const question = questionParts.join(" ");
+
+if (!dbPath || !alias || !question) {
+	console.error(
+		'Usage: node scriptify/ask_run.js <db_path> <run_alias> "your question"',
+	);
+	process.exit(1);
+}
+
+const tdb = await TestDb.createAt(dbPath);
+const tserver = await TestServer.start(tdb);
+const client = new RpcClient(tserver.url);
+await client.connect();
+await client.call("rummy/hello", {
+	name: "ask_run",
+	projectRoot: "/tmp/rummy-lme",
+});
+
+console.log(`Asking ${alias}: ${question}\n`);
+
+const TERMINAL = [200, 204, 413, 422, 499, 500];
+const startRes = await client.call("set", {
+	path: `run://${alias}`,
+	body: question,
+	attributes: {
+		model: "grok",
+		mode: "ask",
+		noRepo: true,
+		noInteraction: true,
+		noWeb: true,
+		noProposals: true,
+	},
+});
+
+const deadline = Date.now() + 600_000;
+while (Date.now() < deadline) {
+	const row = await tdb.db.get_run_by_alias.get({ alias });
+	if (TERMINAL.includes(row.status)) break;
+	await new Promise((r) => setTimeout(r, 500));
+}
+
+const runRow = await tdb.db.get_run_by_alias.get({ alias });
+const entries = await tdb.db.get_known_entries.all({ run_id: runRow.id });
+const reasoning = entries
+	.filter((e) => e.scheme === "reasoning")
+	.toSorted((a, b) => b.turn - a.turn)[0];
+const assistant = entries
+	.filter((e) => e.scheme === "assistant")
+	.toSorted((a, b) => b.turn - a.turn)[0];
+
+if (reasoning) {
+	console.log("=== REASONING ===");
+	console.log(reasoning.body);
+	console.log("");
+}
+if (assistant) {
+	console.log("=== ANSWER ===");
+	console.log(assistant.body);
+}
+
+await client.close();
+await tserver.stop();
+await tdb.cleanup();

package/service.js

@@ -1,9 +1,8 @@
-import { mkdirSync, readdirSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 
-// Helper to expand ~ in paths since node --env-file doesn't do it
 // 0. Pre-flight Check: Environment and Dependencies
 const rummyHome = process.env.RUMMY_HOME;
 
@@ -12,13 +11,54 @@ if (!rummyHome) {
 	process.exit(1);
 }
 
+// 0a. Env resolution: local project config wins over RUMMY_HOME.
+//
+// If CWD has a rummy-shaped `.env.example` (contains any RUMMY_* var),
+// this is an authoritative local config — the npm script's
+// --env-file-if-exists flags already loaded it, and RUMMY_HOME would
+// only pollute it with machine-wide config that doesn't belong to this
+// instance.
+//
+// If CWD has no rummy-shaped config, fall back to
+// `${RUMMY_HOME}/.env.example` (canonical defaults, shipped with the
+// package) → `${RUMMY_HOME}/.env` (user overrides). On first run we
+// seed the bundled .env.example into RUMMY_HOME so the user has
+// something to edit.
+//
+// This makes multiple rummy instances on the same box cleanly
+// independent: each owns its own .env.example in its CWD.
+{
+	const cwdExample = join(process.cwd(), ".env.example");
+	const isLocalRummyConfig =
+		existsSync(cwdExample) && /^\s*(#\s*)?RUMMY_\w+\s*=/m.test(readFileSync(cwdExample, "utf8"));
+
+	if (!isLocalRummyConfig) {
+		mkdirSync(rummyHome, { recursive: true });
+		const homeExample = join(rummyHome, ".env.example");
+		const homeEnv = join(rummyHome, ".env");
+		const bundledExample = fileURLToPath(new URL("./.env.example", import.meta.url));
+		if (!existsSync(homeExample) && existsSync(bundledExample)) {
+			copyFileSync(bundledExample, homeExample);
+			console.log(`[RUMMY] Seeded ${homeExample} from package defaults.`);
+		}
+		for (const path of [homeExample, homeEnv]) {
+			if (!existsSync(path)) continue;
+			try {
+				process.loadEnvFile(path);
+			} catch (err) {
+				console.warn(`[RUMMY] Failed to load ${path}: ${err.message}`);
+			}
+		}
+	}
+}
+
 // Check for optional system dependencies
 const gitCheck = spawnSync("git", ["--version"]);
 if (gitCheck.error || gitCheck.status !== 0) {
 	console.warn("[RUMMY] WARNING: 'git' not found. File tracking will use manual activation only.");
 }
 
-let SqlRite, SocketServer, registerPlugins, initPlugins, createHooks, RpcRegistry;
+let SqlRite, SocketServer, registerPlugins, initPlugins, createHooks;
 try {
 	SqlRite = (await import("@possumtech/sqlrite")).default;
 	SocketServer = (await import("./src/server/SocketServer.js")).default;
@@ -26,7 +66,6 @@ try {
 	registerPlugins = pluginIndex.registerPlugins;
 	initPlugins = pluginIndex.initPlugins;
 	createHooks = (await import("./src/hooks/Hooks.js")).default;
-	RpcRegistry = (await import("./src/server/RpcRegistry.js")).default;
 } catch (err) {
 	if (err.code === "ERR_MODULE_NOT_FOUND") {
 		console.error("RUMMY Dependency Error: node_modules not found or incomplete.");
@@ -40,7 +79,6 @@ async function main() {
 	// 1. Initialize Hooks (Agnostic Engine)
 	const debug = process.env.RUMMY_DEBUG === "true";
 	const hooks = createHooks(debug);
-	hooks.rpc.registry = new RpcRegistry();
 
 	// 2. Resolve Directories
 	const userPluginsDir = join(rummyHome, "plugins");
@@ -50,7 +88,10 @@ async function main() {
 	mkdirSync(userPluginsDir, { recursive: true });
 
 	// 4. Register Plugins
-	await registerPlugins([pluginsDir, userPluginsDir], hooks);
+	const pluginInstances = await registerPlugins(
+		[pluginsDir, userPluginsDir],
+		hooks,
+	);
 
 	// 5. Bootstrap Persistence
 	const dbPath = process.env.RUMMY_DB_PATH;
@@ -71,8 +112,8 @@ async function main() {
 		},
 	});
 
-	// 6. Initialize plugins (inject DB, register schemes)
-	await initPlugins(db, null, hooks);
+	// 6. Initialize plugins (register schemes)
+	await initPlugins(db, hooks, pluginInstances);
 
 	// 7. Bootstrap models from env vars
 	{
@@ -99,7 +140,7 @@ async function main() {
 	const { statSync } = await import("node:fs");
 	try {
 		const dbSizeBefore = statSync(dbPath).size;
-		const retentionDays = Number.parseInt(process.env.RUMMY_RETENTION_DAYS || "31", 10);
+		const retentionDays = Number.parseInt(process.env.RUMMY_RETENTION_DAYS, 10);
 		await db.purge_old_runs.run({ retention_days: retentionDays });
 		const dbSizeAfter = statSync(dbPath).size;
 		const dbSizeMB = (dbSizeAfter / 1024 / 1024).toFixed(2);