@possumtech/rummy 0.2.6 → 0.2.8

package/.env.example

@@ -11,7 +11,7 @@ PORT=3044
 # Absolute path, no ~
 # RUMMY_HOME=/home/ubuntu/.rummy
 
-RUMMY_DB_PATH=./rummy.db
+RUMMY_DB_PATH=rummy.db
 # SQLite mmap size in MB
 RUMMY_MMAP_MB=0
 
@@ -57,7 +57,6 @@ RUMMY_X_TITLE=RUMMY
 # Web Search
 # RUMMY_SEARXNG_URL="http://127.0.0.1:8888"
 
-# required for web fetch and search
+# External plugins: npm i -g <package>, then uncomment
 # RUMMY_PLUGIN_WEB="@possumtech/rummy.web"
-# required for git repo and repomap/symbol functionality
 # RUMMY_PLUGIN_REPO="@possumtech/rummy.repo"

package/PLUGINS.md

@@ -8,13 +8,21 @@ constructor receives `core` (a PluginContext) — the plugin's complete
 interface with the system.
 
 ```js
+import { readFileSync } from "node:fs";
+
 export default class MyTool {
     #core;
 
     constructor(core) {
         this.#core = core;
+        core.registerScheme();
         core.on("handler", this.handler.bind(this));
         core.on("full", this.full.bind(this));
+        core.on("summary", this.summary.bind(this));
+        const docs = readFileSync(new URL("./docs.md", import.meta.url), "utf8");
+        core.filter("instructions.toolDocs", async (content) =>
+            content ? `${content}\n\n${docs}` : docs,
+        );
     }
 
     async handler(entry, rummy) {
@@ -22,13 +30,17 @@ export default class MyTool {
     }
 
     full(entry) {
-        // What the model sees at full fidelity
         return `# mytool ${entry.path}\n${entry.body}`;
     }
+
+    summary(entry) {
+        return entry.body;
+    }
 }
 ```
 
 File naming: `src/plugins/mytool/mytool.js`. Class name = file name.
+Tool docs: `src/plugins/mytool/docs.md`.
 
 External plugins install via npm and load via `RUMMY_PLUGIN_*` env vars:
 
@@ -51,18 +63,36 @@ Plugin: rummy.rm({ path: "file.txt" })
 
 ## Registration
 
-All registration happens in the constructor via `core.on()` and
-`core.filter()`. No static methods. No direct hook manipulation.
+All registration happens in the constructor via `core.on()`,
+`core.filter()`, and `core.registerScheme()`.
+
+### core.registerScheme(config?)
+
+Registers this plugin's scheme in the database. Called once in the
+constructor. Defaults are third-party friendly:
+
+```js
+core.registerScheme({
+    fidelity: "full",        // "full", "turn", or "null"
+    modelVisible: 1,         // 1 or 0
+    validStates: ["full", "proposed", "pass", "rejected", "error"],
+    category: "result",      // "result", "file", "knowledge", "structural", "audit", "tool"
+});
+```
+
+All fields optional. `core.registerScheme()` with no args gives a
+sensible result-type scheme.
 
 ### core.on(event, callback, priority?)
 
 | Event | Purpose |
 |-------|---------|
 | `"handler"` | Tool handler — called when model/client invokes this tool |
-| `"full"` | Full projection — what the model sees at full fidelity |
-| `"summary"` | Summary projection — condensed view under token pressure |
-| `"docs"` | Tool documentation — included in model prompt |
-| `"turn"` | Turn processor — runs before context materialization |
+| `"full"` | Full fidelity — what the model sees in `<current>` |
+| `"summary"` | Summary fidelity — what the model sees in `<previous>` |
+| `"turn.started"` | Turn beginning — write prompt/progress/instructions entries |
+| `"turn.response"` | LLM responded — write audit entries, commit usage |
+| `"turn.proposing"` | All dispatches done — materialize file edit proposals |
 | `"entry.created"` | Entry created during dispatch |
 | `"entry.changed"` | File entries changed on disk |
 | Any `"dotted.name"` | Resolves to the matching hook in the hook tree |
@@ -71,12 +101,25 @@ All registration happens in the constructor via `core.on()` and
 
 | Filter | Purpose |
 |--------|---------|
+| `"instructions.toolDocs"` | Append tool documentation to model prompt |
 | `"assembly.system"` | Contribute to system message |
 | `"assembly.user"` | Contribute to user message |
 | `"llm.messages"` | Transform final messages before LLM call |
 | `"llm.response"` | Transform LLM response |
 | Any `"dotted.name"` | Resolves to the matching filter in the hook tree |
 
+### Tool Docs
+
+Each tool plugin has a `docs.md` file with model-facing documentation.
+Registered via the `instructions.toolDocs` filter in the constructor:
+
+```js
+const docs = readFileSync(new URL("./docs.md", import.meta.url), "utf8");
+core.filter("instructions.toolDocs", async (content) =>
+    content ? `${content}\n\n${docs}` : docs,
+);
+```
+
 ### handler(entry, rummy)
 
 The handler receives the parsed command entry and a per-turn RummyContext:
@@ -98,23 +141,24 @@ to stop the chain.
 ### full(entry) / summary(entry)
 
 Returns the string the model sees for this tool's entries at the given
-fidelity. Called during materialization. Every tool MUST register `full`.
-`summary` is optional — if unregistered, the entry is invisible at summary
-fidelity (no fallback).
+fidelity. `full` renders in `<current>` (active loop). `summary` renders
+in `<previous>` (completed loops). Every tool MUST register `full`.
+`summary` is optional — if unregistered, the entry is empty at summary
+fidelity.
 
 ## Two Objects
 
 Plugins interact with two objects at different scopes:
 
 **PluginContext** (`this.#core`) — startup-scoped. Created once per plugin.
-Used for registration (`on()`, `filter()`), database access, store queries.
-Lives for the lifetime of the service. This is `rummy.core` — the
-plugin-only tier that clients cannot reach.
+Used for registration (`on()`, `filter()`, `registerScheme()`), database
+access, store queries. This is `rummy.core` — the plugin-only tier that
+clients cannot reach.
 
 **RummyContext** (`rummy` argument) — turn-scoped. Passed to handlers
 per-invocation. Has tool verbs, per-turn state (runId, turn, mode).
 
-### Tool Verbs (available on both objects)
+### Tool Verbs (on RummyContext)
 
 | Method | Effect |
 |--------|--------|
@@ -146,26 +190,42 @@ per-invocation. Has tool verbs, per-turn state (runId, turn, mode).
 | `rummy.projectId` | Current project ID |
 | `rummy.sequence` | Current turn number (RummyContext only) |
 
-## Events & Filters
+## Hedberg
 
-**Events** are fire-and-forget. All handlers run. Return values ignored.
+The hedberg plugin exposes pattern matching and interpretation utilities
+on `core.hooks.hedberg` for all plugins to use:
 
 ```js
-hooks.entry.changed.on(async ({ rummy, runId, turn, paths }) => {
-    // React to file changes
-}, priority);
+const { match, search, replace, parseSed, parseEdits, normalizeAttrs, generatePatch }
+    = core.hooks.hedberg;
 ```
 
-**Filters** transform data through a chain. Each handler receives the value
-and context, returns the (possibly modified) value.
+| Method | Purpose |
+|--------|---------|
+| `match(pattern, string)` | Full-string pattern match (glob, regex, literal) |
+| `search(pattern, string)` | Substring search, returns `{ found, match, index }` |
+| `replace(body, search, replacement, opts?)` | Apply replacement (sed → literal → heuristic) |
+| `parseSed(input)` | Parse sed syntax into `[{ search, replace, flags, sed }]` |
+| `parseEdits(content)` | Detect edit format (merge conflict, udiff, Claude XML) |
+| `normalizeAttrs(attrs)` | Heal model attribute names |
+| `generatePatch(path, old, new)` | Generate unified diff |
 
-```js
-hooks.llm.messages.addFilter(async (messages, context) => {
-    return [{ role: "system", content: "Extra" }, ...messages];
-}, priority);
-```
+Pattern types (auto-detected):
+
+| Syntax | Type | Example |
+|--------|------|---------|
+| `s/old/new/flags` | Sed replace | `s/3000/8080/g` |
+| `/pattern/flags` | Regex | `/\d+/g` |
+| `$.path` | JSONPath | `$.config.port` |
+| `//element` | XPath | `//div[@class]` |
+| `*glob*` | Glob | `src/**/*.js` |
+| Everything else | Literal | `port = 3000` |
 
-Lower priority runs first. All hooks are async.
+## Events & Filters
+
+**Events** are fire-and-forget. All handlers run. Return values ignored.
+**Filters** transform data through a chain. Lower priority runs first.
+All hooks are async.
 
 ### Project Lifecycle
 
@@ -193,7 +253,7 @@ Lower priority runs first. All hooks are async.
 | `act.started` | event | `{ projectId, model, prompt, run }` | Run requested in act mode |
 | `run.config` | filter | Config object, `{ projectId }` | Before run config applied |
 | `run.progress` | event | `{ run, turn, status }` | Status change (thinking, processing) |
-| `run.state` | event | `{ run, turn, status, summary, history, unknowns, proposed, telemetry }` | After each turn — full state snapshot |
+| `run.state` | event | `{ run, turn, status, summary, history, unknowns, proposed, telemetry }` | After each turn |
 | `run.step.completed` | event | `{ run, turn, flags }` | Turn resolved, no proposals pending |
 | `ask.completed` | event | `{ projectId, run, status, turn }` | Ask run finished |
 | `act.completed` | event | `{ projectId, run, status, turn }` | Act run finished |
@@ -204,14 +264,16 @@ Hooks fire in this order every turn:
 
 | Hook | Type | Payload | When |
 |------|------|---------|------|
-| `entry.changed` | event | `{ rummy, runId, turn, paths }` | Files changed on disk since last turn |
+| `turn.started` | event | `{ rummy, mode, prompt, isContinuation }` | Plugins write prompt/progress/instructions entries |
+| `entry.changed` | event | `{ rummy, runId, turn, paths }` | Files changed on disk (repo plugin) |
 | `onTurn` | processor | `(rummy)` | Plugin turn setup, before context assembly |
-| `assembly.system` | filter | `(content, { rows, loopStartTurn, type, tools })` | Build system message — plugins append sections |
-| `assembly.user` | filter | `(content, { rows, loopStartTurn, type, tools })` | Build user message — plugins append sections |
-| `llm.messages` | filter | `messages[], { model, projectId, runId }` | Before LLM call — modify final messages |
+| `assembly.system` | filter | `(content, { rows, loopStartTurn, type, contextSize })` | Build system message |
+| `assembly.user` | filter | `(content, { rows, loopStartTurn, type, contextSize })` | Build user message |
+| `llm.messages` | filter | `messages[], { model, projectId, runId }` | Before LLM call |
 | `llm.request.started` | event | `{ model, turn }` | LLM call about to fire |
-| `llm.response` | filter | `response, { model, projectId, runId }` | Raw LLM response — normalize, transform |
+| `llm.response` | filter | `response, { model, projectId, runId }` | Raw LLM response |
 | `llm.request.completed` | event | `{ model, turn, usage }` | LLM call finished |
+| `turn.response` | event | `{ rummy, turn, result, responseMessage, content, ... }` | Plugins write audit entries |
 | `tools.dispatch` | handler | `(entry, rummy)` | Per command — handler chain executes |
 | `entry.created` | event | `{ scheme, path, body, attributes, state, resultPath }` | After each command dispatched |
 | `turn.proposing` | event | `{ rummy, recorded }` | All dispatches done — materialize proposals |
@@ -223,46 +285,6 @@ Hooks fire in this order every turn:
 | `ui.render` | event | `{ text, append }` | Text for client display |
 | `ui.notify` | event | `{ text, level }` | Status notification |
 
-## RPC Registration
-
-```js
-hooks.rpc.registry.register("myMethod", {
-    handler: async (params, ctx) => {
-        // ctx.projectAgent, ctx.db, ctx.projectId, ctx.projectRoot
-        return { result: "value" };
-    },
-    description: "What this method does",
-    params: { arg1: "description" },
-    requiresInit: true,
-    longRunning: true,  // for methods that call the model
-});
-```
-
-## Hedberg Pattern Library
-
-Available in JS and SQL. Five pattern types, auto-detected:
-
-| Syntax | Type | Example |
-|--------|------|---------|
-| `s/old/new/flags` | Sed replace | `s/3000/8080/g` |
-| `/pattern/flags` | Regex | `/\d+/g` |
-| `$.path` | JSONPath | `$.config.port` |
-| `//element` | XPath | `//div[@class]` |
-| `*glob*` | Glob | `src/**/*.js` |
-| Everything else | Literal | `port = 3000` |
-
-JS API:
-
-```js
-import { hedmatch, hedsearch, hedreplace } from "./sql/functions/hedberg.js";
-
-hedmatch(pattern, string)              // → boolean (full string match)
-hedsearch(pattern, string)             // → { found, match, index }
-hedreplace(pattern, replacement, string) // → new string or null
-```
-
-SQL functions: `hedmatch()`, `hedsearch()`, `hedreplace()`.
-
 ## Bundled Plugins
 
 Each plugin has its own README at `src/plugins/{name}/README.md`.
@@ -271,7 +293,7 @@ Each plugin has its own README at `src/plugins/{name}/README.md`.
 |--------|------|-------------|
 | [`get`](src/plugins/get/) | Core tool | Load file/entry into context |
 | [`set`](src/plugins/set/) | Core tool | Edit file/entry |
-| [`known`](src/plugins/known/) | Core tool | Save knowledge, render `<known>` |
+| [`known`](src/plugins/known/) | Core tool + Assembly | Save knowledge, render `<knowns>` section |
 | [`store`](src/plugins/store/) | Core tool | Remove from context |
 | [`rm`](src/plugins/rm/) | Core tool | Delete permanently |
 | [`mv`](src/plugins/mv/) | Core tool | Move entry |
@@ -281,22 +303,23 @@ Each plugin has its own README at `src/plugins/{name}/README.md`.
 | [`ask_user`](src/plugins/ask_user/) | Core tool | Ask the user |
 | [`summarize`](src/plugins/summarize/) | Structural | Signal completion |
 | [`update`](src/plugins/update/) | Structural | Signal continued work |
-| [`unknown`](src/plugins/unknown/) | Structural | Register unknowns, render `<unknowns>` |
+| [`unknown`](src/plugins/unknown/) | Structural + Assembly | Register unknowns, render `<unknowns>` |
 | [`previous`](src/plugins/previous/) | Assembly | Render `<previous>` loop history |
 | [`current`](src/plugins/current/) | Assembly | Render `<current>` active loop work |
-| [`progress`](src/plugins/progress/) | Assembly | Render `<progress>` bridge text |
+| [`progress`](src/plugins/progress/) | Assembly | Render `<progress>` telemetry + bridge |
 | [`prompt`](src/plugins/prompt/) | Assembly | Render `<ask>`/`<act>` prompt tag |
-| [`instructions`](src/plugins/instructions/) | Internal | System prompt assembly |
-| [`file`](src/plugins/file/) | Internal | File projections, constraints, scanning |
+| [`hedberg`](src/plugins/hedberg/) | Utility | Pattern matching, interpretation, normalization |
+| [`instructions`](src/plugins/instructions/) | Internal | Preamble + tool docs + persona assembly |
+| [`file`](src/plugins/file/) | Internal | File entry projections and constraints |
 | [`rpc`](src/plugins/rpc/) | Internal | RPC method registration |
 | [`skills`](src/plugins/skills/) | Internal | Skill/persona management |
-| [`telemetry`](src/plugins/telemetry/) | Internal | Debug logging |
+| [`telemetry`](src/plugins/telemetry/) | Internal | Audit entries, usage stats, last_run.txt |
 
 ## External Plugins
 
 | Plugin | Package | Description |
 |--------|---------|-------------|
-| Web | `@possumtech/rummy.web` | Search and URL fetching |
-| Repo | `@possumtech/rummy.repo` | Symbol extraction |
+| Repo | `@possumtech/rummy.repo` | Git-aware file scanning and symbol extraction |
+| Web | `@possumtech/rummy.web` | Web search and URL fetching via searxng |
 
-Loaded via `RUMMY_PLUGIN_*` env vars. Graceful failure if not installed.
+Loaded via `RUMMY_PLUGIN_*` env vars.

package/bin/rummy.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { existsSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { isAbsolute, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 
@@ -9,10 +9,17 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, "..");
 
 const rummyHome = process.env.RUMMY_HOME || join(homedir(), ".rummy");
-process.env.RUMMY_HOME = rummyHome;
 
+// Load defaults, then user overrides
 process.loadEnvFile(join(packageRoot, ".env.example"));
 const userEnv = join(rummyHome, ".env");
 if (existsSync(userEnv)) process.loadEnvFile(userEnv);
 
+// Resolve RUMMY_HOME and make DB path absolute relative to it
+process.env.RUMMY_HOME = rummyHome;
+const dbPath = process.env.RUMMY_DB_PATH;
+if (dbPath && !isAbsolute(dbPath)) {
+	process.env.RUMMY_DB_PATH = join(rummyHome, dbPath);
+}
+
 await import(join(packageRoot, "service.js"));

package/migrations/001_initial_schema.sql

@@ -4,13 +4,12 @@ PRAGMA mmap_size = $mmap_size;
 -- INIT: initial_schema
 
 -- Scheme registry: single source of truth for all scheme metadata.
--- fidelity: 'full' = always visible, 'turn' = visible when turn>0, 'null' = never visible.
--- valid_states: JSON array of allowed state values for this scheme.
+-- 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.
 CREATE TABLE IF NOT EXISTS schemes (
 	name TEXT PRIMARY KEY
-	, fidelity TEXT NOT NULL CHECK (fidelity IN ('full', 'turn', 'null'))
 	, model_visible BOOLEAN NOT NULL DEFAULT 1
-	, valid_states TEXT NOT NULL
 	, category TEXT
 );
 
@@ -37,15 +36,14 @@ CREATE TABLE IF NOT EXISTS models (
 );
 
 -- Runs: execution units belonging to a project.
--- Each run has its own config (temperature, persona, context_limit).
+-- Status uses HTTP codes: 100=queued, 102=running, 200=completed,
+-- 202=proposed, 500=failed, 499=aborted.
 CREATE TABLE IF NOT EXISTS runs (
 	id INTEGER PRIMARY KEY AUTOINCREMENT
 	, project_id INTEGER NOT NULL REFERENCES projects (id) ON DELETE CASCADE
 	, parent_run_id INTEGER REFERENCES runs (id) ON DELETE SET NULL
 	, model TEXT
-	, status TEXT NOT NULL DEFAULT 'queued' CHECK (
-		status IN ('queued', 'running', 'proposed', 'completed', 'failed', 'aborted')
-	)
+	, status INTEGER NOT NULL DEFAULT 100 CHECK (status BETWEEN 100 AND 599)
 	, alias TEXT NOT NULL UNIQUE
 	, temperature REAL CHECK (
 		temperature IS NULL OR (temperature >= 0 AND temperature <= 2)
@@ -53,16 +51,39 @@ CREATE TABLE IF NOT EXISTS runs (
 	, persona TEXT
 	, context_limit INTEGER CHECK (context_limit IS NULL OR context_limit >= 1024)
 	, next_turn INTEGER NOT NULL DEFAULT 1 CHECK (next_turn >= 1)
+	, next_loop INTEGER NOT NULL DEFAULT 1 CHECK (next_loop >= 1)
 	, created_at DATETIME DEFAULT CURRENT_TIMESTAMP
 );
 
 CREATE INDEX IF NOT EXISTS idx_runs_alias ON runs (alias);
 CREATE INDEX IF NOT EXISTS idx_runs_project ON runs (project_id);
 
+-- Loops: execution units within a run. Each ask/act call creates a loop.
+-- Status: 100=pending, 102=running, 200=completed, 202=proposed,
+-- 500=failed, 499=aborted.
+CREATE TABLE IF NOT EXISTS loops (
+	id INTEGER PRIMARY KEY AUTOINCREMENT
+	, run_id INTEGER NOT NULL REFERENCES runs (id) ON DELETE CASCADE
+	, sequence INTEGER NOT NULL CHECK (sequence >= 1)
+	, mode TEXT NOT NULL CHECK (mode IN ('ask', 'act'))
+	, model TEXT
+	, prompt TEXT NOT NULL DEFAULT ''
+	, status INTEGER NOT NULL DEFAULT 100 CHECK (status BETWEEN 100 AND 599)
+	, config JSON
+	, result JSON
+	, created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+	, UNIQUE (run_id, sequence)
+);
+CREATE INDEX IF NOT EXISTS idx_loops_run ON loops (run_id);
+-- Enforce at most one running loop per run.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_loops_one_active
+ON loops (run_id) WHERE status = 102;
+
 -- Turns: usage stats and sequencing (operational, not model-facing)
 CREATE TABLE IF NOT EXISTS turns (
 	id INTEGER PRIMARY KEY AUTOINCREMENT
 	, run_id INTEGER NOT NULL REFERENCES runs (id) ON DELETE CASCADE
+	, loop_id INTEGER NOT NULL REFERENCES loops (id) ON DELETE CASCADE
 	, sequence INTEGER NOT NULL CHECK (sequence >= 1)
 	, prompt_tokens INTEGER NOT NULL DEFAULT 0 CHECK (prompt_tokens >= 0)
 	, cached_tokens INTEGER NOT NULL DEFAULT 0 CHECK (cached_tokens >= 0)
@@ -90,15 +111,20 @@ ON file_constraints (project_id);
 -- Known K/V Store: the unified state machine.
 -- Files, knowledge, tool results, audit — everything is a keyed entry.
 -- scheme: derived from path via schemeOf(). Generated column.
--- State validated by trigger against schemes.valid_states.
+-- 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 (
 	id INTEGER PRIMARY KEY AUTOINCREMENT
 	, run_id INTEGER NOT NULL REFERENCES runs (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
 	, body TEXT NOT NULL DEFAULT ''
 	, scheme TEXT GENERATED ALWAYS AS (schemeOf(path)) STORED
-	, state TEXT NOT NULL
+	, status INTEGER NOT NULL DEFAULT 200 CHECK (status BETWEEN 100 AND 599)
+	, fidelity TEXT NOT NULL DEFAULT 'full' CHECK (
+		fidelity IN ('full', 'summary', 'index', 'stored')
+	)
 	, hash TEXT
 	, attributes JSON NOT NULL DEFAULT '{}' CHECK (json_valid(attributes))
 	, tokens INTEGER NOT NULL DEFAULT 0 CHECK (tokens >= 0)
@@ -110,43 +136,14 @@ CREATE TABLE IF NOT EXISTS known_entries (
 );
 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_state
-ON known_entries (run_id, scheme, state);
+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);
 
--- Validate state against schemes.valid_states on insert.
-CREATE TRIGGER IF NOT EXISTS trg_known_entry_state_insert
-BEFORE INSERT ON known_entries
-FOR EACH ROW
-BEGIN
-	SELECT RAISE(ABORT, 'invalid state for scheme')
-	WHERE NOT EXISTS (
-		SELECT 1
-		FROM schemes AS s, json_each(s.valid_states) AS j
-		WHERE
-			s.name = COALESCE(schemeOf(NEW.path), 'file')
-			AND j.value = NEW.state
-	);
-END;
-
--- Validate state against schemes.valid_states on update.
-CREATE TRIGGER IF NOT EXISTS trg_known_entry_state_update
-BEFORE UPDATE OF state ON known_entries
-FOR EACH ROW
-WHEN OLD.state != NEW.state
-BEGIN
-	SELECT RAISE(ABORT, 'invalid state for scheme')
-	WHERE NOT EXISTS (
-		SELECT 1
-		FROM schemes AS s, json_each(s.valid_states) AS j
-		WHERE
-			s.name = COALESCE(schemeOf(NEW.path), 'file')
-			AND j.value = NEW.state
-	);
-END;
+-- No state validation triggers — HTTP status codes are universal.
 
--- UNRESOLVED VIEW: all entries awaiting user action
+-- UNRESOLVED VIEW: all entries awaiting user action (202 Accepted)
 CREATE VIEW IF NOT EXISTS v_unresolved AS
 SELECT
 	run_id
@@ -155,19 +152,20 @@ SELECT
 	, attributes
 	, turn
 FROM known_entries
-WHERE state = 'proposed';
+WHERE status = 202;
 
 -- Turn context: materialized snapshot of what the model sees each turn.
 -- known_entries is the warehouse. turn_context is the shipment.
 CREATE TABLE IF NOT EXISTS turn_context (
 	id INTEGER PRIMARY KEY AUTOINCREMENT
 	, run_id INTEGER NOT NULL REFERENCES runs (id) ON DELETE CASCADE
+	, loop_id INTEGER REFERENCES loops (id) ON DELETE CASCADE
 	, turn INTEGER NOT NULL CHECK (turn >= 1)
 	, 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 ('full', 'summary', 'index'))
-	, state TEXT NOT NULL DEFAULT 'full'
 	, body TEXT NOT NULL DEFAULT ''
 	, tokens INTEGER NOT NULL DEFAULT 0 CHECK (tokens >= 0)
 	, attributes JSON NOT NULL DEFAULT '{}' CHECK (json_valid(attributes))
@@ -177,8 +175,8 @@ CREATE TABLE IF NOT EXISTS turn_context (
 CREATE INDEX IF NOT EXISTS idx_turn_context_run_turn
 ON turn_context (run_id, turn);
 
--- Enforce valid run state transitions.
--- completed → running: continuation (new turn on finished run)
+-- Enforce valid run state transitions (HTTP status codes).
+-- 100=queued, 102=running, 200=completed, 202=proposed, 499=aborted, 500=failed.
 CREATE TRIGGER IF NOT EXISTS trg_run_state_transition
 BEFORE UPDATE OF status ON runs
 FOR EACH ROW
@@ -186,30 +184,17 @@ WHEN OLD.status != NEW.status
 BEGIN
 	SELECT RAISE(ABORT, 'invalid run state transition')
 	WHERE NOT (
-		(OLD.status = 'queued' AND NEW.status IN ('running', 'aborted'))
-		OR (OLD.status = 'running' AND NEW.status IN ('proposed', 'completed', 'failed', 'aborted'))
-		OR (OLD.status = 'proposed' AND NEW.status IN ('running', 'completed', 'aborted'))
-		OR (OLD.status = 'completed' AND NEW.status IN ('running', 'aborted'))
-		OR (OLD.status = 'failed' AND NEW.status IN ('running', 'aborted'))
-		OR (OLD.status = 'aborted' AND NEW.status IN ('running'))
+		(OLD.status = 100 AND NEW.status IN (102, 499))
+		OR (OLD.status = 102 AND NEW.status IN (200, 202, 500, 499))
+		OR (OLD.status = 202 AND NEW.status IN (102, 200, 499))
+		OR (OLD.status = 200 AND NEW.status IN (102, 499))
+		OR (OLD.status = 500 AND NEW.status IN (102, 499))
+		OR (OLD.status = 499 AND NEW.status IN (102))
 	);
 END;
 
--- Prompt queue. All prompts flow through here. Worker consumes FIFO per run.
-CREATE TABLE IF NOT EXISTS prompt_queue (
-	id INTEGER PRIMARY KEY AUTOINCREMENT
-	, run_id INTEGER NOT NULL REFERENCES runs (id) ON DELETE CASCADE
-	, mode TEXT NOT NULL CHECK (mode IN ('ask', 'act'))
-	, model TEXT
-	, prompt TEXT NOT NULL
-	, config JSON
-	, status TEXT NOT NULL DEFAULT 'pending'
-	CHECK (status IN ('pending', 'active', 'completed', 'aborted'))
-	, result JSON
-	, created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE INDEX IF NOT EXISTS idx_prompt_queue_run ON prompt_queue (run_id, status);
+-- Prompt queue is the loops table (defined above).
+-- Each ask/act enqueues a loop (status=pending). Worker claims FIFO per run.
 
 -- RPC audit log. Every call recorded unconditionally.
 CREATE TABLE IF NOT EXISTS rpc_log (

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@possumtech/rummy",
-	"version": "0.2.6",
+	"version": "0.2.8",
 	"description": "Relational Unknowns Memory Management Yoke",
 	"keywords": [
 		"llm"
@@ -47,12 +47,10 @@
 	},
 	"dependencies": {
 		"@possumtech/sqlrite": "^3.1.0",
+		"@xmldom/xmldom": "^0.9.9",
 		"htmlparser2": "^12.0.0",
 		"tiktoken": "^1.0.22",
-		"ws": "^8.19.0"
-	},
-	"optionalDependencies": {
-		"@possumtech/rummy.repo": "^0.0.4",
-		"@possumtech/rummy.web": "^0.0.7"
+		"ws": "^8.19.0",
+		"xpath": "^0.0.34"
 	}
 }

package/service.js

@@ -53,7 +53,7 @@ async function main() {
 	await registerPlugins([pluginsDir, userPluginsDir], hooks);
 
 	// 5. Bootstrap Persistence
-	const dbPath = process.env.RUMMY_DB_PATH || join(rummyHome, "rummy.db");
+	const dbPath = process.env.RUMMY_DB_PATH;
 	const functionsDir = fileURLToPath(new URL("./src/sql/functions", import.meta.url));
 	const sqlFunctions = readdirSync(functionsDir)
 		.filter((f) => f.endsWith(".js") && !f.endsWith(".test.js"))
@@ -115,7 +115,7 @@ async function main() {
 	}
 
 	// 6b. Abort stuck runs (can't be running if the server just started)
-	await db.reset_active_prompts.run({});
+	await db.reset_active_loops.run({});
 	const aborted = await db.abort_stuck_runs.run({});
 	if (aborted.changes > 0) {
 		console.log(`[RUMMY] Recovered ${aborted.changes} stuck run(s)`);