@danypops/papyrus 0.11.3 → 0.12.0

package/src/constants.ts

@@ -7,8 +7,14 @@ export const DAEMON_PROBE_TIMEOUT_MS = 800;
 export const DAEMON_UNIT_NAME = "papyrus.service";
 export const DAEMON_DIR_ENV = "PAPYRUS_DAEMON_DIR";
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
-export const SQLITE_SCHEMA_VERSION = 5;
+export const SQLITE_SCHEMA_VERSION = 10;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
+/** Bounded forum persistence behind the Discourse mutation authority. */
+export const DISCOURSE_QUERY_MAX_LIMIT = 100;
+export const DISCOURSE_CONTENT_MAX_BYTES = 65_536;
+export const DISCOURSE_EVENT_RETENTION_DEFAULT = 1_000;
+export const DISCOURSE_EVENT_RETENTION_MAX = 10_000;
+export const DISCOURSE_PARTICIPANT_MAX_COUNT = 100;
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
 export const DB_OPTIMIZE_INTERVAL_MS = 24 * 60 * 60_000;
 export const GATE_COMMAND_TIMEOUT_MS = 30_000;
@@ -19,6 +25,9 @@ export const GATE_FILE_MAX_BYTES = 1_048_576;
 
 export const PAPYRUS_CONTEXT_INJECTION_CHANNEL = "papyrus.context-injection.v1";
 export const PAPYRUS_CONTEXT_INJECTION_SCHEMA = "papyrus.context-injection/v1";
+/** Broadcasts which task is focused, content-free (taskId/sessionId/status/timestamp only), so other extensions (e.g. a token-cost router) can correlate their own telemetry without Papyrus depending on them. */
+export const PAPYRUS_TASK_FOCUS_CHANNEL = "papyrus.task-focus.v1";
+export const PAPYRUS_TASK_FOCUS_SCHEMA = "papyrus.task-focus/v1";
 export const CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN = 4;
 
 /** Compact task-context limits keep recurring prompt injection bounded. */
@@ -71,8 +80,23 @@ export const NOTE_LIST_MAX_LIMIT = 200;
 export const NOTE_HISTORY_MAX_EVENTS = 20;
 export const NOTE_PROVENANCE_MAX_LENGTH = 128;
 export const NOTE_REASON_MAX_CHARACTERS = 2_000;
+/** Generic, kind-agnostic mutation event log bounds (doc/task/rule/skill share one log). */
+export const ARTIFACT_EVENT_ACTOR_MAX_LENGTH = 128;
+export const ARTIFACT_EVENT_HISTORY_DEFAULT_LIMIT = 25;
+export const ARTIFACT_EVENT_HISTORY_MAX_LIMIT = 200;
+/** Bounds for the generic graph projection protocol (external bounded contexts). */
+export const GRAPH_PROJECTION_MAX_ARTIFACTS_PER_BATCH = 500;
+export const GRAPH_PROJECTION_MAX_EDGES_PER_BATCH = 1_000;
+export const GRAPH_PROJECTION_ID_MAX_LENGTH = 256;
+/** Per-agent-session Task Focus scoping. "global" is the default scope for callers that don't supply a session id (CLI, legacy behavior). */
+export const TASK_FOCUS_DEFAULT_SCOPE = "global";
+export const TASK_FOCUS_SCOPE_MAX_LENGTH = 128;
+/** Hard cap on distinct concurrent focus scopes (sessions); oldest-updated scope is evicted beyond this. */
+export const TASK_FOCUS_MAX_SCOPES = 500;
 /** Persisted project and focused-graph Task view bounds. */
 export const TASK_SCOPE_MAX_TASKS = 1_000;
+/** Docs/Rules/Skills project scope listing bound, mirroring TASK_SCOPE_MAX_TASKS. */
+export const ARTIFACT_SCOPE_MAX_ARTIFACTS = 1_000;
 export const TASK_PROJECT_ROOT_MAX_LENGTH = 4_096;
 export const GRAPH_RENDER_PADDING_X = 2;
 export const GRAPH_RENDER_PADDING_Y = 1;
@@ -93,14 +117,23 @@ export const DEFAULT_METADATA_DEPTH = 6;
 export const DEFAULT_METADATA_ITEMS = 100;
 export const MAX_METADATA_DEPTH = 12;
 export const MAX_METADATA_ITEMS = 500;
+/** Independent bounds for model-facing tool content and persisted renderer details. */
+export const TOOL_MODEL_CONTENT_MAX_CHARACTERS = 12_000;
+export const TOOL_DETAILS_BODY_MAX_CHARACTERS = 20_000;
+export const TOOL_DETAILS_FIELD_MAX_CHARACTERS = 1_000;
+export const TOOL_DETAILS_ROW_OUTPUT_MAX_CHARACTERS = 1_000;
+export const TOOL_DETAILS_MAX_SERIALIZED_CHARACTERS = 131_072;
+export const TOOL_COLLAPSED_ROW_LIMIT = 5;
+export const TOOL_DETAILS_MAX_ITEMS = 100;
+export const TOOL_DETAILS_MAX_EDGES = 200;
 
 /** Reconciliation instruction appended whenever Papyrus has open work. */
 export const TASK_RECONCILIATION_INSTRUCTION = [
 	"Reconcile before concluding or moving on:",
 	'• For each current task, ask: "Did we accomplish this task?"',
-	"• If yes, run its gates before marking it done; a claim is not verification.",
-	"• If no, continue with the next concrete action toward its desired state.",
-	"• Address blocked work or explicitly move failed review to rejected with the reason.",
+	"• If yes, run its gates before marking it done; a claim is not verification. A written summary is not evidence -- identify what would actually prove each requirement in the task's desired state and checklist, and treat indirect or merely-plausible signals as not sufficient.",
+	"• If no, continue with the next concrete action toward its desired state. Do not shrink the task's scope to whatever fits in this turn, and do not substitute a narrower, easier, or merely-passing-looking change for the actual desired outcome.",
+	"• Address blocked work or explicitly move failed review to rejected with the reason. Do not reject or call something blocked on the first obstacle -- only after the same blocking condition genuinely recurs, and only when the task truly cannot proceed without external input or a change outside the agent's control.",
 ].join("\n");
 
 /** $XDG_DATA_HOME/papyrus/papyrus.db */
@@ -175,5 +208,5 @@ export const DEFAULT_STATUS_BY_KIND: Readonly<Record<string, string>> = {
 export const SEED_RELATIONS = [
 	"references", "implements", "follows", "depends_on",
 	"documents", "blocks", "supersedes", "relates_to",
-	"gates", "triggers", "contains", "part_of",
+	"gates", "triggers", "contains", "part_of", "reply_to", "discusses",
 ] as const;

package/src/conversation-journal-service.ts

@@ -0,0 +1,87 @@
+/**
+ * conversation-journal-service.ts — host-neutral ConversationJournal application layer.
+ *
+ * Owns idempotency (checking operationId before insert) and bounds enforcement; the
+ * ConversationJournalStore port underneath is dumb storage. See
+ * src/domain/conversation-journal.ts for the domain shapes and the design rationale.
+ */
+import {
+	ancestorChain,
+	boundContent,
+	buildThreadTree,
+	CONVERSATION_JOURNAL_READ_MAX_POSTS,
+	validateAppendPostCommand,
+	type AppendPostCommand,
+	type AppendPostResult,
+	type JournalPost,
+	type JournalThread,
+	type ReadThreadQuery,
+	type ThreadPage,
+	type ThreadTreeNode,
+} from "./domain/conversation-journal.ts";
+import type { ConversationJournalStore } from "./ports/conversation-journal-store.ts";
+
+export class ConversationJournalService {
+	constructor(private readonly store: ConversationJournalStore) {}
+
+	appendPost(command: AppendPostCommand): AppendPostResult {
+		validateAppendPostCommand(command);
+
+		const existing = this.store.findPostByOperationId(command.operationId);
+		if (existing) return { post: existing, replayed: true };
+
+		if (command.replyToPostId !== undefined && !this.store.getPost(command.replyToPostId)) {
+			throw new Error(`replyToPostId "${command.replyToPostId}" not found`);
+		}
+
+		this.store.ensureThread(command.threadId);
+		const { content, truncated } = boundContent(command.content);
+		const post: JournalPost = {
+			id: crypto.randomUUID(),
+			threadId: command.threadId,
+			...(command.replyToPostId !== undefined ? { replyToPostId: command.replyToPostId } : {}),
+			authorId: command.authorId,
+			content,
+			truncated,
+			timestamp: new Date().toISOString(),
+			sourceSessionId: command.sourceSessionId,
+			operationId: command.operationId,
+			references: command.references ? [...command.references] : [],
+		};
+		this.store.insertPost(post);
+		return { post, replayed: false };
+	}
+
+	getThread(threadId: string): JournalThread | undefined {
+		return this.store.getThread(threadId);
+	}
+
+	getPost(id: string): JournalPost | undefined {
+		return this.store.getPost(id);
+	}
+
+	/** Bounded, explicit-completeness thread read. Never silently drops posts past the bound. */
+	readThread(query: ReadThreadQuery): ThreadPage {
+		const limit = query.limit;
+		if (!Number.isInteger(limit) || limit < 1 || limit > CONVERSATION_JOURNAL_READ_MAX_POSTS) {
+			throw new Error(`readThread limit must be between 1 and ${CONVERSATION_JOURNAL_READ_MAX_POSTS}`);
+		}
+		const all = [...this.store.postsForThread(query.threadId)].sort(
+			(left, right) => left.timestamp.localeCompare(right.timestamp) || left.id.localeCompare(right.id),
+		);
+		const truncated = all.length > limit;
+		return { posts: all.slice(0, limit), truncated };
+	}
+
+	/** Reconstructed reply tree for a thread, bounded and orphan/cycle-safe -- see buildThreadTree. */
+	readThreadTree(threadId: string): ThreadTreeNode[] {
+		return buildThreadTree(this.store.postsForThread(threadId));
+	}
+
+	/** Root-first ancestor chain for one post -- the host-neutral equivalent of Pi's getBranch(). */
+	ancestorsOf(postId: string): JournalPost[] {
+		const posts = this.store.postsForThread(this.store.getPost(postId)?.threadId ?? "");
+		const byId = new Map(posts.map((post) => [post.id, post]));
+		return ancestorChain(postId, byId);
+	}
+}

package/src/db.ts

@@ -3,6 +3,7 @@
  * Dual-runtime: bun:sqlite (Bun) / node:sqlite (Node/pi host).
  * Four kinds (doc/task/rule/skill) are FK-enforced; relations are universal (any→any).
  */
+import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
@@ -65,6 +66,14 @@ export function inTransaction<T>(db: Db, fn: () => T): T {
 }
 
 const SCHEMA = `
+CREATE TABLE IF NOT EXISTS module_migrations (
+	module_id   TEXT NOT NULL,
+	version     INTEGER NOT NULL,
+	name        TEXT NOT NULL,
+	checksum    TEXT NOT NULL,
+	applied_at  TEXT NOT NULL,
+	PRIMARY KEY (module_id, version)
+);
 CREATE TABLE IF NOT EXISTS kinds (
 	name        TEXT PRIMARY KEY,
 	description TEXT
@@ -98,8 +107,8 @@ CREATE TABLE IF NOT EXISTS relation_names (
 	description TEXT
 );
 CREATE TABLE IF NOT EXISTS task_focus (
-	scope       TEXT PRIMARY KEY CHECK (scope = 'global'),
-	task_id     TEXT NOT NULL UNIQUE REFERENCES artifacts(id),
+	scope       TEXT PRIMARY KEY,
+	task_id     TEXT NOT NULL REFERENCES artifacts(id),
 	status      TEXT NOT NULL CHECK (status IN ('active', 'paused')),
 	pause_reason TEXT,
 	updated_at  TEXT NOT NULL
@@ -138,6 +147,109 @@ CREATE TABLE IF NOT EXISTS task_views (
 	updated_at    TEXT NOT NULL,
 	CHECK ((mode = 'graph' AND root_task_id IS NOT NULL) OR (mode != 'graph' AND root_task_id IS NULL))
 );
+CREATE TABLE IF NOT EXISTS discourse_threads (
+	store_id      TEXT NOT NULL,
+	forum_id      TEXT NOT NULL,
+	topic_id      TEXT NOT NULL,
+	thread_id     TEXT NOT NULL,
+	artifact_id   TEXT NOT NULL UNIQUE REFERENCES artifacts(id),
+	PRIMARY KEY (store_id, forum_id, topic_id, thread_id)
+);
+CREATE TABLE IF NOT EXISTS discourse_posts (
+	store_id       TEXT NOT NULL,
+	sequence       INTEGER NOT NULL,
+	id             TEXT NOT NULL,
+	artifact_id    TEXT NOT NULL UNIQUE REFERENCES artifacts(id),
+	operation_id   TEXT NOT NULL,
+	command_json   TEXT NOT NULL,
+	forum_id       TEXT NOT NULL,
+	topic_id       TEXT NOT NULL,
+	thread_id      TEXT NOT NULL,
+	author_id      TEXT NOT NULL,
+	content_json   TEXT NOT NULL,
+	timestamp      INTEGER NOT NULL,
+	correlation_id TEXT,
+	causation_id   TEXT,
+	reply_to_post_id TEXT,
+	references_json TEXT NOT NULL,
+	question_type  TEXT CHECK (question_type IN ('question', 'answer')),
+	response_id    TEXT,
+	target_id      TEXT,
+	PRIMARY KEY (store_id, id),
+	UNIQUE (store_id, operation_id),
+	UNIQUE (store_id, sequence)
+);
+CREATE INDEX IF NOT EXISTS discourse_posts_thread_idx ON discourse_posts(store_id, forum_id, topic_id, thread_id, sequence);
+CREATE TABLE IF NOT EXISTS discourse_events (
+	store_id       TEXT NOT NULL,
+	sequence       INTEGER NOT NULL,
+	event_json     TEXT NOT NULL,
+	PRIMARY KEY (store_id, sequence)
+);
+CREATE TABLE IF NOT EXISTS discourse_cursors (
+	store_id       TEXT NOT NULL,
+	consumer_id    TEXT NOT NULL,
+	sequence       INTEGER NOT NULL,
+	PRIMARY KEY (store_id, consumer_id)
+);
+CREATE TABLE IF NOT EXISTS discourse_projection_cursors (
+	store_id       TEXT NOT NULL,
+	projection_id  TEXT NOT NULL,
+	sequence       INTEGER NOT NULL,
+	PRIMARY KEY (store_id, projection_id)
+);
+CREATE TRIGGER IF NOT EXISTS discourse_threads_artifact_type BEFORE INSERT ON discourse_threads
+WHEN NOT EXISTS (SELECT 1 FROM artifacts WHERE id = NEW.artifact_id AND kind = 'doc' AND subtype = 'context-thread')
+BEGIN SELECT RAISE(ABORT, 'discourse thread artifact must be a context-thread Doc'); END;
+CREATE TRIGGER IF NOT EXISTS discourse_posts_artifact_type BEFORE INSERT ON discourse_posts
+WHEN NOT EXISTS (SELECT 1 FROM artifacts WHERE id = NEW.artifact_id AND kind = 'doc' AND subtype = 'context-message')
+BEGIN SELECT RAISE(ABORT, 'discourse post artifact must be a context-message Doc'); END;
+CREATE TRIGGER IF NOT EXISTS discourse_artifact_type_immutable BEFORE UPDATE OF kind, subtype ON artifacts
+WHEN (EXISTS (SELECT 1 FROM discourse_threads WHERE artifact_id = OLD.id) AND (NEW.kind != 'doc' OR NEW.subtype != 'context-thread'))
+  OR (EXISTS (SELECT 1 FROM discourse_posts WHERE artifact_id = OLD.id) AND (NEW.kind != 'doc' OR NEW.subtype != 'context-message'))
+BEGIN SELECT RAISE(ABORT, 'discourse Context Mesh artifact type is immutable'); END;
+CREATE TABLE IF NOT EXISTS artifact_events (
+	id                   INTEGER PRIMARY KEY AUTOINCREMENT,
+	artifact_id          TEXT NOT NULL REFERENCES artifacts(id),
+	occurred_at          TEXT NOT NULL,
+	event_type           TEXT NOT NULL,
+	actor                TEXT NOT NULL,
+	source               TEXT NOT NULL,
+	session_id           TEXT,
+	from_status          TEXT,
+	to_status            TEXT,
+	relation             TEXT,
+	related_id           TEXT,
+	event_schema_version INTEGER NOT NULL DEFAULT 1
+);
+CREATE INDEX IF NOT EXISTS artifact_events_artifact_idx ON artifact_events(artifact_id, occurred_at, id);
+CREATE INDEX IF NOT EXISTS artifact_events_related_idx ON artifact_events(related_id, occurred_at, id);
+CREATE INDEX IF NOT EXISTS artifact_events_actor_idx ON artifact_events(actor, occurred_at, id);
+CREATE INDEX IF NOT EXISTS artifact_events_session_idx ON artifact_events(session_id, occurred_at, id);
+CREATE TRIGGER IF NOT EXISTS artifact_events_no_update BEFORE UPDATE ON artifact_events
+BEGIN SELECT RAISE(ABORT, 'artifact_events are append-only'); END;
+CREATE TRIGGER IF NOT EXISTS artifact_events_no_delete BEFORE DELETE ON artifact_events
+BEGIN SELECT RAISE(ABORT, 'artifact_events are append-only'); END;
+CREATE TABLE IF NOT EXISTS graph_projection_checkpoints (
+	producer_id    TEXT PRIMARY KEY,
+	last_sequence  INTEGER NOT NULL,
+	last_batch_id  TEXT NOT NULL,
+	applied_at     TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS graph_projection_identities (
+	producer_id   TEXT NOT NULL,
+	external_id   TEXT NOT NULL,
+	artifact_id   TEXT NOT NULL REFERENCES artifacts(id),
+	PRIMARY KEY (producer_id, external_id)
+);
+CREATE INDEX IF NOT EXISTS graph_projection_identities_artifact_idx ON graph_projection_identities(artifact_id);
+CREATE TABLE IF NOT EXISTS artifact_scopes (
+	artifact_id   TEXT PRIMARY KEY REFERENCES artifacts(id),
+	project_root  TEXT,
+	source        TEXT NOT NULL CHECK (source IN ('cwd', 'explicit', 'unscoped')),
+	assigned_at   TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS artifact_scopes_project_idx ON artifact_scopes(project_root, artifact_id);
 `;
 
 const SEED_SQL = `
@@ -170,6 +282,8 @@ INSERT OR IGNORE INTO relation_names VALUES ('gates','This rule gates that task
 INSERT OR IGNORE INTO relation_names VALUES ('triggers','This skill applies to that work (skill→task)');
 INSERT OR IGNORE INTO relation_names VALUES ('contains','Parent contains a nested artifact (any→any)');
 INSERT OR IGNORE INTO relation_names VALUES ('part_of','Artifact belongs to a parent artifact (any→any)');
+INSERT OR IGNORE INTO relation_names VALUES ('reply_to','Append-only message replies to another message in the same thread');
+INSERT OR IGNORE INTO relation_names VALUES ('discusses','Message or turn concerns a verified artifact');
 CREATE INDEX IF NOT EXISTS edges_to_id_idx ON edges(to_id);
 `;
 
@@ -183,16 +297,102 @@ export function schemaVersion(db: Db): number {
 	return (db.prepare("PRAGMA user_version").get() as { user_version: number }).user_version;
 }
 
+/**
+ * One row per (module_id, version) applied migration, checksummed so a since-edited
+ * definition is detected rather than silently trusted.
+ */
+export interface ModuleMigrationRow {
+	readonly moduleId: string;
+	readonly version: number;
+	readonly name: string;
+	readonly checksum: string;
+	readonly appliedAt: string;
+}
+
+/**
+ * "core"'s ledger history. Each entry's checksum is a FROZEN, hardcoded literal, computed
+ * once at the moment that version was introduced and embedded here permanently -- never
+ * recomputed from the live, evolving SCHEMA/SEED_SQL constants. That distinction is the
+ * entire point: an earlier version of this file computed the checksum from the current
+ * SCHEMA text every time, which meant "core version 1" silently redefined itself every
+ * time SCHEMA grew, and would have thrown a checksum-mismatch error against every
+ * database that had already recorded the OLDER value -- including a real, already-
+ * deployed production database. Only the LAST entry's DDL actually runs (SCHEMA+SEED_SQL,
+ * the full current shape) for a truly fresh database; every earlier entry is pure
+ * historical bookkeeping, backfilled alongside it without being replayed, so a new
+ * database is not forced to pass through migrations it never structurally needed. A
+ * database that already recorded an earlier version keeps that exact checksum forever;
+ * adding schema later means appending a new entry here, never editing an existing one.
+ */
+const CORE_LEDGER_VERSIONS: ReadonlyArray<{ version: number; name: string; checksum: string }> = [
+	{ version: 1, name: "baseline", checksum: "af81e9f51d915ba538af3f468dc044bda5e2c5a5f5037e9c7c01540f87288763" },
+	{ version: 2, name: "docs-rules-skills-project-scope", checksum: "8b16d8f631ad628f4799ff09b1ebe8be28343e4f677d52bf2a39a8bedc19e64e" },
+];
+
+export function migrationLedger(db: Db): ModuleMigrationRow[] {
+	// A database that has never reached current schema (still awaiting explicit migrateDb())
+	// has no ledger table yet -- "nothing recorded" is the correct answer, not an error.
+	const tableExists = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'module_migrations'").get() != null;
+	if (!tableExists) return [];
+	const rows = db.prepare("SELECT module_id, version, name, checksum, applied_at FROM module_migrations ORDER BY module_id, version").all() as Array<{
+		module_id: string; version: number; name: string; checksum: string; applied_at: string;
+	}>;
+	return rows.map((row) => ({ moduleId: row.module_id, version: row.version, name: row.name, checksum: row.checksum, appliedAt: row.applied_at }));
+}
+
+/**
+ * Ensures the ledger correctly reflects every entry in CORE_LEDGER_VERSIONS once a
+ * database is confirmed at the full current schema, however it got there: a truly empty
+ * database runs the current bootstrap DDL once (for the last/current entry only) and
+ * backfills every entry as historical bookkeeping; a database that already reached
+ * current shape (a fresh bootstrap from a past release, or a full upgrade through the
+ * pre-ledger sequential migrateDb() chain below) is backfilled without re-running any DDL
+ * against data that already exists. Verifies every already-recorded entry's stored
+ * checksum on every open so a since-edited definition is caught, not silently trusted --
+ * and because each entry's checksum is frozen at introduction (see the constant's own
+ * comment), an already-recorded entry can never spuriously mismatch just because a later
+ * entry was appended.
+ */
+function ensureCoreLedger(db: Db, alreadyAtCurrentSchema: boolean): void {
+	// Idempotent and standalone: must succeed even on a truly empty database, before the rest
+	// of SCHEMA (which also declares this table) has run.
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS module_migrations (
+			module_id   TEXT NOT NULL,
+			version     INTEGER NOT NULL,
+			name        TEXT NOT NULL,
+			checksum    TEXT NOT NULL,
+			applied_at  TEXT NOT NULL,
+			PRIMARY KEY (module_id, version)
+		);
+	`);
+	inTransaction(db, () => {
+		for (const [index, entry] of CORE_LEDGER_VERSIONS.entries()) {
+			const existingRow = db.prepare("SELECT checksum FROM module_migrations WHERE module_id = 'core' AND version = ?").get(entry.version) as { checksum: string } | null;
+			if (existingRow != null) {
+				if (existingRow.checksum !== entry.checksum) {
+					throw new Error(`module migration "core" version ${entry.version} checksum mismatch: the frozen definition for this version was edited after it was applied`);
+				}
+				continue;
+			}
+			const isLast = index === CORE_LEDGER_VERSIONS.length - 1;
+			if (isLast && !alreadyAtCurrentSchema) {
+				db.exec(SCHEMA);
+				db.exec(SEED_SQL);
+				db.exec(`PRAGMA user_version = ${SQLITE_SCHEMA_VERSION}`);
+			}
+			db.prepare("INSERT INTO module_migrations (module_id, version, name, checksum, applied_at) VALUES ('core', ?, ?, ?, ?)")
+				.run(entry.version, entry.name, entry.checksum, new Date().toISOString());
+		}
+	});
+}
+
 function bootstrapEmptyDatabase(db: Db): void {
 	const existing = db
 		.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' LIMIT 1")
 		.get();
 	if (existing) throw new Error("database schema is unversioned; refusing to migrate existing data during boot");
-	inTransaction(db, () => {
-		db.exec(SCHEMA);
-		db.exec(SEED_SQL);
-		db.exec(`PRAGMA user_version = ${SQLITE_SCHEMA_VERSION}`);
-	});
+	ensureCoreLedger(db, false);
 }
 
 export function migrateDb(db: Db): MigrationResult {
@@ -201,7 +401,7 @@ export function migrateDb(db: Db): MigrationResult {
 		throw new Error(`database schema ${from} is newer than supported ${SQLITE_SCHEMA_VERSION}`);
 	}
 	if (from === SQLITE_SCHEMA_VERSION) return { from, to: from, applied: [] };
-	if (from !== 1 && from !== 2 && from !== 3 && from !== 4) throw new Error(`no explicit migration path from database schema ${from}`);
+	if (from !== 1 && from !== 2 && from !== 3 && from !== 4 && from !== 5 && from !== 6 && from !== 7) throw new Error(`no explicit migration path from database schema ${from}`);
 	const applied: string[] = [];
 
 	inTransaction(db, () => {
@@ -290,7 +490,134 @@ export function migrateDb(db: Db): MigrationResult {
 			`);
 			applied.push("task-focus-continuation");
 		}
+		if (schemaVersion(db) === 5) {
+			db.exec(`
+				INSERT OR IGNORE INTO relation_names VALUES ('reply_to','Append-only message replies to another message in the same thread');
+				INSERT OR IGNORE INTO relation_names VALUES ('discusses','Message or turn concerns a verified artifact');
+				CREATE TABLE discourse_threads (
+					store_id TEXT NOT NULL, forum_id TEXT NOT NULL, topic_id TEXT NOT NULL, thread_id TEXT NOT NULL,
+					artifact_id TEXT NOT NULL UNIQUE REFERENCES artifacts(id),
+					PRIMARY KEY (store_id, forum_id, topic_id, thread_id)
+				);
+				CREATE TABLE discourse_posts (
+					store_id TEXT NOT NULL, sequence INTEGER NOT NULL, id TEXT NOT NULL,
+					artifact_id TEXT NOT NULL UNIQUE REFERENCES artifacts(id), operation_id TEXT NOT NULL,
+					command_json TEXT NOT NULL, forum_id TEXT NOT NULL, topic_id TEXT NOT NULL, thread_id TEXT NOT NULL,
+					author_id TEXT NOT NULL, content_json TEXT NOT NULL, timestamp INTEGER NOT NULL,
+					correlation_id TEXT, causation_id TEXT, reply_to_post_id TEXT, references_json TEXT NOT NULL,
+					question_type TEXT CHECK (question_type IN ('question', 'answer')), response_id TEXT, target_id TEXT,
+					PRIMARY KEY (store_id, id), UNIQUE (store_id, operation_id), UNIQUE (store_id, sequence)
+				);
+				CREATE INDEX discourse_posts_thread_idx ON discourse_posts(store_id, forum_id, topic_id, thread_id, sequence);
+				CREATE TABLE discourse_events (
+					store_id TEXT NOT NULL, sequence INTEGER NOT NULL, event_json TEXT NOT NULL,
+					PRIMARY KEY (store_id, sequence)
+				);
+				CREATE TABLE discourse_cursors (
+					store_id TEXT NOT NULL, consumer_id TEXT NOT NULL, sequence INTEGER NOT NULL,
+					PRIMARY KEY (store_id, consumer_id)
+				);
+				CREATE TABLE discourse_projection_cursors (
+					store_id TEXT NOT NULL, projection_id TEXT NOT NULL, sequence INTEGER NOT NULL,
+					PRIMARY KEY (store_id, projection_id)
+				);
+				CREATE TRIGGER discourse_threads_artifact_type BEFORE INSERT ON discourse_threads
+				WHEN NOT EXISTS (SELECT 1 FROM artifacts WHERE id = NEW.artifact_id AND kind = 'doc' AND subtype = 'context-thread')
+				BEGIN SELECT RAISE(ABORT, 'discourse thread artifact must be a context-thread Doc'); END;
+				CREATE TRIGGER discourse_posts_artifact_type BEFORE INSERT ON discourse_posts
+				WHEN NOT EXISTS (SELECT 1 FROM artifacts WHERE id = NEW.artifact_id AND kind = 'doc' AND subtype = 'context-message')
+				BEGIN SELECT RAISE(ABORT, 'discourse post artifact must be a context-message Doc'); END;
+				CREATE TRIGGER discourse_artifact_type_immutable BEFORE UPDATE OF kind, subtype ON artifacts
+				WHEN (EXISTS (SELECT 1 FROM discourse_threads WHERE artifact_id = OLD.id) AND (NEW.kind != 'doc' OR NEW.subtype != 'context-thread'))
+				  OR (EXISTS (SELECT 1 FROM discourse_posts WHERE artifact_id = OLD.id) AND (NEW.kind != 'doc' OR NEW.subtype != 'context-message'))
+				BEGIN SELECT RAISE(ABORT, 'discourse Context Mesh artifact type is immutable'); END;
+				PRAGMA user_version = 6;
+			`);
+			applied.push("discourse-context-mesh");
+		}
+		if (schemaVersion(db) === 6) {
+			db.exec(`
+				CREATE TABLE artifact_events (
+					id INTEGER PRIMARY KEY AUTOINCREMENT,
+					artifact_id TEXT NOT NULL REFERENCES artifacts(id),
+					occurred_at TEXT NOT NULL,
+					event_type TEXT NOT NULL,
+					actor TEXT NOT NULL,
+					source TEXT NOT NULL,
+					session_id TEXT,
+					from_status TEXT,
+					to_status TEXT,
+					relation TEXT,
+					related_id TEXT,
+					event_schema_version INTEGER NOT NULL DEFAULT 1
+				);
+				CREATE INDEX artifact_events_artifact_idx ON artifact_events(artifact_id, occurred_at, id);
+				CREATE INDEX artifact_events_related_idx ON artifact_events(related_id, occurred_at, id);
+				CREATE INDEX artifact_events_actor_idx ON artifact_events(actor, occurred_at, id);
+				CREATE INDEX artifact_events_session_idx ON artifact_events(session_id, occurred_at, id);
+				CREATE TRIGGER artifact_events_no_update BEFORE UPDATE ON artifact_events
+				BEGIN SELECT RAISE(ABORT, 'artifact_events are append-only'); END;
+				CREATE TRIGGER artifact_events_no_delete BEFORE DELETE ON artifact_events
+				BEGIN SELECT RAISE(ABORT, 'artifact_events are append-only'); END;
+				PRAGMA user_version = 7;
+			`);
+			applied.push("artifact-event-log");
+		}
+		if (schemaVersion(db) === 7) {
+			db.exec(`
+				CREATE TABLE task_focus_v7 (
+					scope TEXT PRIMARY KEY,
+					task_id TEXT NOT NULL REFERENCES artifacts(id),
+					status TEXT NOT NULL CHECK (status IN ('active', 'paused')),
+					pause_reason TEXT,
+					updated_at TEXT NOT NULL
+				);
+				INSERT INTO task_focus_v7 SELECT scope, task_id, status, pause_reason, updated_at FROM task_focus;
+				DROP TABLE task_focus;
+				ALTER TABLE task_focus_v7 RENAME TO task_focus;
+				PRAGMA user_version = 8;
+			`);
+			applied.push("task-focus-session-scope");
+		}
+		if (schemaVersion(db) === 8) {
+			// IF NOT EXISTS here, unlike earlier migration branches: a fully-bootstrapped
+			// :memory: fixture (used by unrelated tests that only roll user_version back to
+			// simulate an older *file* database) already has every table the current bootstrap
+			// DDL declares, this one included -- so this branch must be safe to run whether or
+			// not that already happened, not assume a truly-old database created it first.
+			db.exec(`
+				CREATE TABLE IF NOT EXISTS graph_projection_checkpoints (
+					producer_id    TEXT PRIMARY KEY,
+					last_sequence  INTEGER NOT NULL,
+					last_batch_id  TEXT NOT NULL,
+					applied_at     TEXT NOT NULL
+				);
+				CREATE TABLE IF NOT EXISTS graph_projection_identities (
+					producer_id   TEXT NOT NULL,
+					external_id   TEXT NOT NULL,
+					artifact_id   TEXT NOT NULL REFERENCES artifacts(id),
+					PRIMARY KEY (producer_id, external_id)
+				);
+				CREATE INDEX IF NOT EXISTS graph_projection_identities_artifact_idx ON graph_projection_identities(artifact_id);
+				PRAGMA user_version = 9;
+			`);
+			applied.push("graph-projection-protocol");
+		}
+		if (schemaVersion(db) === 9) {
+			db.exec(`
+				CREATE TABLE IF NOT EXISTS artifact_scopes (
+					artifact_id   TEXT PRIMARY KEY REFERENCES artifacts(id),
+					project_root  TEXT,
+					source        TEXT NOT NULL CHECK (source IN ('cwd', 'explicit', 'unscoped')),
+					assigned_at   TEXT NOT NULL
+				);
+				CREATE INDEX IF NOT EXISTS artifact_scopes_project_idx ON artifact_scopes(project_root, artifact_id);
+				PRAGMA user_version = 10;
+			`);
+			applied.push("docs-rules-skills-project-scope");
+		}
 	});
+	if (schemaVersion(db) === SQLITE_SCHEMA_VERSION) ensureCoreLedger(db, true);
 	return { from, to: schemaVersion(db), applied };
 }
 
@@ -306,6 +633,7 @@ export function openDb(path: string): Db {
 		throw new Error(`database schema ${current} is newer than supported ${SQLITE_SCHEMA_VERSION}`);
 	}
 	if (current === 0) bootstrapEmptyDatabase(db);
+	else if (current === SQLITE_SCHEMA_VERSION) ensureCoreLedger(db, true);
 	db.exec("PRAGMA optimize=0x10002");
 	return db;
 }

package/src/domain/artifact-event.ts

@@ -0,0 +1,99 @@
+/**
+ * Generic, kind-agnostic mutation event log — the "who did what, when" answer
+ * shared by every artifact kind (doc, task, rule, skill), not reinvented per domain.
+ *
+ * Modeled after scribe's parchment.Event/EventFilter/GetEvents shape, but avoids its
+ * known gap: there, the Actor column is defined and filterable yet never populated by
+ * any caller. Here, actor/source default to explicit sentinels ("system"/"unknown")
+ * rather than being silently blank, and the event is appended by the same choke point
+ * that performs the mutation (src/ops.ts), so no domain call site can skip it.
+ */
+import { ARTIFACT_EVENT_ACTOR_MAX_LENGTH, ARTIFACT_EVENT_HISTORY_DEFAULT_LIMIT, ARTIFACT_EVENT_HISTORY_MAX_LIMIT } from "../constants.ts";
+
+export const ARTIFACT_EVENT_TYPES = ["created", "updated", "status_changed", "extra_set", "linked", "unlinked"] as const;
+export type ArtifactEventType = typeof ARTIFACT_EVENT_TYPES[number];
+export type ArtifactEventDirection = "asc" | "desc";
+
+/** Caller-supplied identity for a mutation. All fields are advisory (self-reported), not cryptographically verified. */
+export interface ArtifactEventContext {
+	actor?: string;
+	source?: string;
+	sessionId?: string;
+}
+
+export interface ArtifactEvent {
+	id: number;
+	artifactId: string;
+	occurredAt: string;
+	type: ArtifactEventType;
+	actor: string;
+	source: string;
+	sessionId?: string;
+	fromStatus?: string;
+	toStatus?: string;
+	relation?: string;
+	relatedId?: string;
+	schemaVersion: 1;
+}
+
+export interface AppendArtifactEvent {
+	artifactId: string;
+	type: ArtifactEventType;
+	actor?: string;
+	source?: string;
+	sessionId?: string;
+	fromStatus?: string;
+	toStatus?: string;
+	relation?: string;
+	relatedId?: string;
+}
+
+export interface ArtifactEventQuery {
+	artifactId?: string;
+	actor?: string;
+	sessionId?: string;
+	since?: string;
+	limit?: number;
+	cursor?: number;
+	direction?: ArtifactEventDirection;
+}
+
+export interface ArtifactEventPage {
+	events: ArtifactEvent[];
+	nextCursor?: number;
+}
+
+/** No caller-supplied identity defaults to these explicit sentinels — never a silent blank. */
+export const ARTIFACT_EVENT_DEFAULT_ACTOR = "system";
+export const ARTIFACT_EVENT_DEFAULT_SOURCE = "unknown";
+
+function boundedString(value: string, field: string, maximum: number): string {
+	if (value.length === 0 || value.length > maximum) throw new Error(`${field} must be between 1 and ${maximum} characters`);
+	return value;
+}
+
+/** Fills defaults and enforces bounds. The one place every appended event is normalized. */
+export function resolveArtifactEvent(input: AppendArtifactEvent): Required<Pick<AppendArtifactEvent, "actor" | "source">> & AppendArtifactEvent {
+	if (!input.artifactId) throw new Error("artifactId is required");
+	const actor = boundedString(input.actor ?? ARTIFACT_EVENT_DEFAULT_ACTOR, "actor", ARTIFACT_EVENT_ACTOR_MAX_LENGTH);
+	const source = boundedString(input.source ?? ARTIFACT_EVENT_DEFAULT_SOURCE, "source", ARTIFACT_EVENT_ACTOR_MAX_LENGTH);
+	if (input.sessionId !== undefined) boundedString(input.sessionId, "sessionId", ARTIFACT_EVENT_ACTOR_MAX_LENGTH);
+	return { ...input, actor, source };
+}
+
+export function normalizeArtifactEventQuery(query: ArtifactEventQuery): Required<Pick<ArtifactEventQuery, "limit" | "direction">> & ArtifactEventQuery {
+	if (!query.artifactId && !query.actor && !query.sessionId) {
+		throw new Error("artifact event query requires artifactId, actor, or sessionId to stay bounded");
+	}
+	const limit = query.limit ?? ARTIFACT_EVENT_HISTORY_DEFAULT_LIMIT;
+	if (!Number.isInteger(limit) || limit < 1 || limit > ARTIFACT_EVENT_HISTORY_MAX_LIMIT) {
+		throw new Error(`artifact event limit must be between 1 and ${ARTIFACT_EVENT_HISTORY_MAX_LIMIT}`);
+	}
+	if (query.cursor !== undefined && (!Number.isInteger(query.cursor) || query.cursor < 1)) {
+		throw new Error("artifact event cursor must be a positive integer");
+	}
+	if (query.direction !== undefined && query.direction !== "asc" && query.direction !== "desc") {
+		throw new Error("artifact event direction must be asc or desc");
+	}
+	return { ...query, limit, direction: query.direction ?? "desc" };
+}