@danypops/papyrus 0.13.6 → 0.15.0

package/extension/src/index.ts

@@ -27,7 +27,7 @@ import { ActiveTaskContinuation, automaticPauseReason, shouldResumeFocusOnHumanI
 import { buildTaskWidgetProjection, type TaskWidgetProjection } from "./task-widget.ts";
 import { TASK_STATUS_PRESENTATION, taskTreeConnector } from "./task-presentation.ts";
 import { buildContextInjection } from "./context-injection-telemetry.ts";
-import { buildContextBreakdown, buildMessageHistoryTree, buildTaskItemTree, computeContextBudget, computeRuleBudget, type SessionEntryLike, type SessionTreeNodeLike } from "./context-budget.ts";
+import { buildContextBreakdown, buildMessageHistoryTree, buildTaskItemTree, computeContextBudget, computeRuleBudget, DEFAULT_RESERVE_TOKENS, type SessionEntryLike, type SessionTreeNodeLike } from "./context-budget.ts";
 import { showContextView } from "./context-view.ts";
 import { emitTaskFocusEvent, setTaskFocusEventBus } from "./task-focus-events.ts";
 import { renderPapyrusToolCall, renderPapyrusToolResult } from "./tool-rendering/index.ts";
@@ -160,6 +160,7 @@ export default async function (pi: ExtensionAPI) {
 	let contextInjectionSequence = 0;
 	const contextInjectionProducerId = randomUUID();
 	let previousContextInjectionFingerprint: string | undefined;
+	let logTurnSequence = 0;
 	// Cached from the most recent before_agent_start observation: Pi's own base system prompt
 	// is only ever visible transiently inside that hook's event.systemPrompt, so /context
 	// reuses the size buildContextInjection already computes every turn rather than going
@@ -200,6 +201,36 @@ export default async function (pi: ExtensionAPI) {
 		}
 	};
 
+	// ── Post-mortem AND live: every settled turn, log a real context-usage snapshot ────
+	// Deliberately lean (real usage + budget numbers only, no full segment breakdown --
+	// that stays /context's job on demand) so this stays cheap enough to run every turn:
+	// no extra daemon round-trips beyond the one logs.append call, no session tree walk.
+	const PI_SESSION_CONTEXT_LOG_SOURCE = "pi-session-context";
+	const logSessionContextSnapshot = async (ctx: ExtensionContext): Promise<void> => {
+		try {
+			const usage = ctx.getContextUsage?.();
+			if (!usage || usage.tokens === null) return; // nothing real to report yet (e.g. before the first assistant turn, or right after compaction)
+			const totalTokens = usage.tokens;
+			const sessionId = ctx.sessionManager.getSessionId();
+			const effectiveBudget = Math.max(0, usage.contextWindow - DEFAULT_RESERVE_TOKENS);
+			const percentOfBudget = effectiveBudget > 0 ? Math.round((totalTokens / effectiveBudget) * 1000) / 10 : null;
+			await callService("logs.append", {
+				source_id: PI_SESSION_CONTEXT_LOG_SOURCE,
+				source_label: "Pi session context usage",
+				project_root: ctx.cwd,
+				level: "info",
+				message: `context usage: ${totalTokens} tok / ${effectiveBudget} tok budget (${percentOfBudget}%)`,
+				operation_id: `${sessionId}:${++logTurnSequence}`,
+				session_id: sessionId,
+				fields: { totalTokens, contextWindow: usage.contextWindow, effectiveBudget, percentOfBudget },
+			});
+		} catch {
+			// The daemon may be unavailable during startup, reload, or shutdown -- a missed
+			// snapshot is not worth surfacing to the user, matching every other best-effort
+			// per-turn daemon call in this extension.
+		}
+	};
+
 	// ── Low-level graph-store tools ────────────────────────────────────
 
 	pi.registerTool({
@@ -501,7 +532,10 @@ export default async function (pi: ExtensionAPI) {
 		}
 	});
 	pi.on("agent_start", () => { taskContinuation.onAgentStart(); });
-	pi.on("agent_settled", async (_event, ctx) => { await driveActiveTasks(ctx); });
+	pi.on("agent_settled", async (_event, ctx) => {
+		await driveActiveTasks(ctx);
+		await logSessionContextSnapshot(ctx);
+	});
 
 	// ── "Are we there yet?" — inject active tasks into every turn ──────
 	// The agent sees its open work items every turn. If there are rejected

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.13.6",
+  "version": "0.15.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/adapters/sqlite-log-store.ts

@@ -0,0 +1,88 @@
+import type { Db } from "../db.ts";
+import type { JsonValue, LogEntry, LogLevel, LogSource } from "../domain/log-entry.ts";
+import type { LogStore } from "../ports/log-store.ts";
+
+interface SourceRow {
+	id: string;
+	label: string;
+	project_root: string | null;
+	created_at: string;
+}
+
+interface EntryRow {
+	id: string;
+	source_id: string;
+	occurred_at: string;
+	level: string;
+	message: string;
+	truncated: number;
+	fields_json: string;
+	operation_id: string;
+	session_id: string | null;
+}
+
+function toSource(row: SourceRow): LogSource {
+	return { id: row.id, label: row.label, projectRoot: row.project_root, createdAt: row.created_at };
+}
+
+function toEntry(row: EntryRow): LogEntry {
+	return {
+		id: row.id,
+		sourceId: row.source_id,
+		occurredAt: row.occurred_at,
+		level: row.level as LogLevel,
+		message: row.message,
+		truncated: row.truncated === 1,
+		fields: JSON.parse(row.fields_json) as JsonValue,
+		operationId: row.operation_id,
+		sessionId: row.session_id ?? undefined,
+	};
+}
+
+export class SQLiteLogStore implements LogStore {
+	constructor(private readonly db: Db) {}
+
+	ensureSource(sourceId: string, label: string, projectRoot: string | null): LogSource {
+		const existing = this.db.prepare("SELECT id, label, project_root, created_at FROM log_sources WHERE id = ?").get(sourceId) as SourceRow | undefined;
+		if (existing) return toSource(existing);
+		const createdAt = new Date().toISOString();
+		this.db.prepare("INSERT INTO log_sources (id, label, project_root, created_at) VALUES (?, ?, ?, ?)").run(sourceId, label, projectRoot, createdAt);
+		return { id: sourceId, label, projectRoot, createdAt };
+	}
+
+	findEntryByOperationId(sourceId: string, operationId: string): LogEntry | undefined {
+		const row = this.db.prepare(
+			"SELECT id, source_id, occurred_at, level, message, truncated, fields_json, operation_id, session_id FROM log_entries WHERE source_id = ? AND operation_id = ?",
+		).get(sourceId, operationId) as EntryRow | undefined;
+		return row ? toEntry(row) : undefined;
+	}
+
+	insertEntry(entry: LogEntry): void {
+		this.db.prepare(
+			`INSERT INTO log_entries (id, source_id, occurred_at, level, message, truncated, fields_json, operation_id, session_id)
+			 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		).run(
+			entry.id, entry.sourceId, entry.occurredAt, entry.level, entry.message,
+			entry.truncated ? 1 : 0, JSON.stringify(entry.fields), entry.operationId, entry.sessionId ?? null,
+		);
+	}
+
+	entriesForSource(sourceId: string): readonly LogEntry[] {
+		const rows = this.db.prepare(
+			"SELECT id, source_id, occurred_at, level, message, truncated, fields_json, operation_id, session_id FROM log_entries WHERE source_id = ? ORDER BY occurred_at, id",
+		).all(sourceId) as EntryRow[];
+		return rows.map(toEntry);
+	}
+
+	trimSource(sourceId: string, maxEntries: number): number {
+		const countRow = this.db.prepare("SELECT COUNT(*) as count FROM log_entries WHERE source_id = ?").get(sourceId) as { count: number };
+		const excess = countRow.count - maxEntries;
+		if (excess <= 0) return 0;
+		this.db.prepare(
+			`DELETE FROM log_entries WHERE id IN (
+				SELECT id FROM log_entries WHERE source_id = ? ORDER BY occurred_at, id LIMIT ?
+			)`,
+		).run(sourceId, excess);
+		return excess;
+	}
+}

package/src/authority-registry.ts

@@ -25,7 +25,7 @@ import type { ArtifactStore } from "./ports/artifact-store.ts";
 export type ArtifactAction = "create" | "link" | "status";
 
 export interface AuthorityClaim {
-	/** Module id that owns this kind/subtype/relation, e.g. "discourse", "notes", "tasks". */
+	/** Module id that owns this kind/subtype/relation, e.g. "notes", "tasks". */
 	readonly owner: string;
 	/** kind may be undefined at a call site that has not yet resolved an artifact's effective kind (e.g. pre-template-resolution). */
 	matchesArtifact(kind: string | undefined, subtype: string | undefined): boolean;

package/src/cli.ts

@@ -71,7 +71,6 @@ const USAGE = `Usage:
   papyrus migrate-ids mirror [--db <path>] --out <mirror-path> [--json]
   papyrus migrate-ids validate --mirror <mirror-path> [--idmap <path>] [--json]
   papyrus migrate-ids promote --mirror <mirror-path> [--db <path>] [--idmap <path>] [--force] [--json]
-  papyrus discourse store <action> --store-id <id> [--input-json <json>] [--json]
   papyrus graph link <from> <relation> <to> [--json]
   papyrus graph unlink <from> <relation> <to> [--json]
   papyrus graph tree <id> [--depth <n>] [--max-nodes <n>] [--json]
@@ -112,6 +111,8 @@ const USAGE = `Usage:
   papyrus notes consume <id> [--reason <reason>] [--json]
   papyrus notes promote <id> <target-id> [--reason <reason>] [--json]
   papyrus notes archive <id> <completed|duplicate|declined|superseded> [--reason <reason>] [--json]
+  papyrus log append --source <id> --level <debug|info|warning|error> --message <text> --operation-id <id> [--source-label <text>] [--fields-json <json>] [--session-id <id>] [--occurred-at <iso>] [--global] [--json]
+  papyrus log query --source <id> [--since <iso>] [--level <debug|info|warning|error>] [--limit <count>] [--json]
   papyrus tasks plan [--session-id <id>] [--json]
   papyrus tasks graph [--session-id <id>] [--json]
   papyrus tasks active [--session-id <id>] [--json]
@@ -306,36 +307,6 @@ export function runIdMigrationCli(args: string[]): string {
 	throw new Error("migrate-ids requires one of: mirror, validate, promote");
 }
 
-export async function runDiscourseCli(args: string[], client: TaskCliClient): Promise<string> {
-	const json = args.includes("--json");
-	const positional: string[] = [];
-	let storeId: string | undefined;
-	let operationInput: Record<string, unknown> = {};
-	for (let index = 0; index < args.length; index++) {
-		const argument = args[index]!;
-		if (argument === "--json") continue;
-		if (argument === "--store-id" || argument === "--input-json") {
-			const value = args[++index];
-			if (!value) throw new Error(`${argument} requires a value`);
-			if (argument === "--store-id") storeId = value;
-			else {
-				const parsed = JSON.parse(value) as unknown;
-				if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("--input-json must be a JSON object");
-				operationInput = parsed as Record<string, unknown>;
-			}
-			continue;
-		}
-		if (argument.startsWith("--")) throw new Error(`unknown discourse option ${argument}`);
-		positional.push(argument);
-	}
-	if (positional.length !== 2 || positional[0] !== "store") throw new Error("discourse requires `store <action>`");
-	if (!storeId) throw new Error("discourse store requires --store-id");
-	const result = await client.call<Record<string, unknown>, unknown>("discourse.store", {
-		action: positional[1], store_id: storeId, ...operationInput,
-	});
-	return json ? JSON.stringify(result) : `Discourse store ${positional[1]} completed.`;
-}
-
 export async function runSkillCli(args: string[], client: TaskCliClient, projectRoot: string = process.cwd()): Promise<string> {
 	const json = args.includes("--json");
 	const positional: string[] = [];
@@ -873,6 +844,71 @@ export async function runGraphProjectionCli(args: string[], client: TaskCliClien
 	throw new Error("graph-projection action must be apply or checkpoint");
 }
 
+export async function runLogCli(args: string[], client: TaskCliClient, projectRoot: string = process.cwd()): Promise<string> {
+	const json = args.includes("--json");
+	const positional: string[] = [];
+	let source: string | undefined;
+	let sourceLabel: string | undefined;
+	let level: string | undefined;
+	let message: string | undefined;
+	let operationId: string | undefined;
+	let sessionId: string | undefined;
+	let occurredAt: string | undefined;
+	let since: string | undefined;
+	let limit: number | undefined;
+	let fields: Record<string, unknown> | undefined;
+	let global = false;
+	for (let index = 0; index < args.length; index++) {
+		const argument = args[index]!;
+		if (argument === "--json") continue;
+		if (argument === "--global") { global = true; continue; }
+		if (argument === "--fields-json") { fields = parseJsonObjectFlag(args[++index], "--fields-json"); continue; }
+		if (["--source", "--source-label", "--level", "--message", "--operation-id", "--session-id", "--occurred-at", "--since", "--limit"].includes(argument)) {
+			const value = args[++index];
+			if (value === undefined) throw new Error(`${argument} requires a value`);
+			if (argument === "--source") source = value;
+			else if (argument === "--source-label") sourceLabel = value;
+			else if (argument === "--level") level = value;
+			else if (argument === "--message") message = value;
+			else if (argument === "--operation-id") operationId = value;
+			else if (argument === "--session-id") sessionId = value;
+			else if (argument === "--occurred-at") occurredAt = value;
+			else if (argument === "--since") since = value;
+			else {
+				limit = Number(value);
+				if (!Number.isInteger(limit)) throw new Error("--limit requires an integer");
+			}
+			continue;
+		}
+		if (argument.startsWith("--")) throw new Error(`unknown log option ${argument}`);
+		positional.push(argument);
+	}
+	const [action] = positional;
+	if (action === "append") {
+		if (!source) throw new Error("log append requires --source");
+		if (!level) throw new Error("log append requires --level");
+		if (!message) throw new Error("log append requires --message");
+		if (!operationId) throw new Error("log append requires --operation-id");
+		const result = await client.call("logs.append", {
+			source_id: source, ...(sourceLabel ? { source_label: sourceLabel } : {}),
+			...(global ? {} : { project_root: projectRoot }),
+			level, message, operation_id: operationId,
+			...(fields ? { fields } : {}), ...(sessionId ? { session_id: sessionId } : {}), ...(occurredAt ? { occurred_at: occurredAt } : {}),
+		});
+		return json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
+	}
+	if (action === "query") {
+		if (!source) throw new Error("log query requires --source");
+		const result = await client.call<Record<string, unknown>, { entries: unknown[]; truncated: boolean }>("logs.query", {
+			source_id: source, ...(since ? { since } : {}), ...(level ? { level } : {}), ...(limit === undefined ? {} : { limit }),
+		});
+		if (json) return JSON.stringify(result);
+		const lines = result.entries.map((entry) => JSON.stringify(entry));
+		return [...lines, result.truncated ? `(truncated -- more entries exist beyond this page)` : `(${lines.length} entries)`].join("\n");
+	}
+	throw new Error("log action must be append or query");
+}
+
 export async function runNoteCli(args: string[], client: TaskCliClient, projectRoot: string = process.cwd()): Promise<string> {
 	const json = args.includes("--json");
 	const positional: string[] = [];
@@ -1257,11 +1293,6 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
 		console.log(await runTaskCli(args.slice(1), client));
 		return;
 	}
-	if (command === "discourse") {
-		const client = await connectPapyrusClient();
-		console.log(await runDiscourseCli(args.slice(1), client));
-		return;
-	}
 	if (command === "skills") {
 		const client = await connectPapyrusClient();
 		console.log(await runSkillCli(args.slice(1), client));
@@ -1272,6 +1303,11 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
 		console.log(await runNoteCli(args.slice(1), client));
 		return;
 	}
+	if (command === "log") {
+		const client = await connectPapyrusClient();
+		console.log(await runLogCli(args.slice(1), client));
+		return;
+	}
 	if (command === "migrate") {
 		const client = await connectPapyrusClient();
 		console.log(await runMigrationCli(args.slice(1), client));

package/src/constants.ts

@@ -7,14 +7,9 @@ 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 = 10;
+export const SQLITE_SCHEMA_VERSION = 12;
 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;

package/src/db.ts

@@ -147,67 +147,6 @@ 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),
@@ -250,6 +189,27 @@ CREATE TABLE IF NOT EXISTS artifact_scopes (
 	assigned_at   TEXT NOT NULL
 );
 CREATE INDEX IF NOT EXISTS artifact_scopes_project_idx ON artifact_scopes(project_root, artifact_id);
+CREATE TABLE IF NOT EXISTS log_sources (
+	id            TEXT PRIMARY KEY,
+	label         TEXT NOT NULL,
+	project_root  TEXT,
+	created_at    TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS log_entries (
+	id            TEXT PRIMARY KEY,
+	source_id     TEXT NOT NULL REFERENCES log_sources(id),
+	occurred_at   TEXT NOT NULL,
+	level         TEXT NOT NULL CHECK (level IN ('debug', 'info', 'warning', 'error')),
+	message       TEXT NOT NULL,
+	truncated     INTEGER NOT NULL DEFAULT 0,
+	fields_json   TEXT NOT NULL DEFAULT '{}',
+	operation_id  TEXT NOT NULL,
+	session_id    TEXT,
+	UNIQUE (source_id, operation_id)
+);
+CREATE INDEX IF NOT EXISTS log_entries_source_idx ON log_entries(source_id, occurred_at, id);
+CREATE TRIGGER IF NOT EXISTS log_entries_no_update BEFORE UPDATE ON log_entries
+BEGIN SELECT RAISE(ABORT, 'log_entries are immutable once written; retention trimming is the only supported deletion path'); END;
 `;
 
 const SEED_SQL = `
@@ -282,8 +242,6 @@ 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);
 `;
 
@@ -327,6 +285,8 @@ export interface ModuleMigrationRow {
 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" },
+	{ version: 3, name: "log-domain", checksum: "c87f43c22b2608619ada9a529d7899ae74b7f38cd554135c8034116fc96e1eff" },
+	{ version: 4, name: "remove-discourse", checksum: "b923f41c44460f0aaeb2f4e60e28f8b8e1425d03f527955bd991434b46de4c82" },
 ];
 
 export function migrationLedger(db: Db): ModuleMigrationRow[] {
@@ -401,9 +361,19 @@ 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 && from !== 5 && from !== 6 && from !== 7) throw new Error(`no explicit migration path from database schema ${from}`);
+	if (from < 1) throw new Error(`no explicit migration path from database schema ${from}`);
 	const applied: string[] = [];
 
+	// Deliberately NOT a hand-enumerated allow-list of valid `from` values (e.g. "from !== 1 &&
+	// ... && from !== 7"): a real, latent bug was found here while adding the v10->v11 step --
+	// that enumeration was never extended when the v8->v9 and v9->v10 steps were added, so
+	// migrating any already-deployed database sitting at schema 8, 9, or 10 (including the real
+	// production database at the time this was found) would have thrown "no explicit migration
+	// path" before ever reaching the migration chain below. Checked dynamically after the chain
+	// runs instead: if schemaVersion(db) hasn't reached SQLITE_SCHEMA_VERSION once every
+	// `schemaVersion(db) === N` step below has had its chance to fire, `from` was never a valid
+	// starting point (a genuine gap in the chain) -- structurally cannot drift out of sync the
+	// way a separate, parallel enumeration did.
 	inTransaction(db, () => {
 		if (schemaVersion(db) === 1) {
 			db.exec(`
@@ -616,6 +586,58 @@ export function migrateDb(db: Db): MigrationResult {
 			`);
 			applied.push("docs-rules-skills-project-scope");
 		}
+		if (schemaVersion(db) === 10) {
+			db.exec(`
+				CREATE TABLE IF NOT EXISTS log_sources (
+					id            TEXT PRIMARY KEY,
+					label         TEXT NOT NULL,
+					project_root  TEXT,
+					created_at    TEXT NOT NULL
+				);
+				CREATE TABLE IF NOT EXISTS log_entries (
+					id            TEXT PRIMARY KEY,
+					source_id     TEXT NOT NULL REFERENCES log_sources(id),
+					occurred_at   TEXT NOT NULL,
+					level         TEXT NOT NULL CHECK (level IN ('debug', 'info', 'warning', 'error')),
+					message       TEXT NOT NULL,
+					truncated     INTEGER NOT NULL DEFAULT 0,
+					fields_json   TEXT NOT NULL DEFAULT '{}',
+					operation_id  TEXT NOT NULL,
+					session_id    TEXT,
+					UNIQUE (source_id, operation_id)
+				);
+				CREATE INDEX IF NOT EXISTS log_entries_source_idx ON log_entries(source_id, occurred_at, id);
+				CREATE TRIGGER IF NOT EXISTS log_entries_no_update BEFORE UPDATE ON log_entries
+				BEGIN SELECT RAISE(ABORT, 'log_entries are immutable once written; retention trimming is the only supported deletion path'); END;
+				PRAGMA user_version = 11;
+			`);
+			applied.push("log-domain");
+		}
+		if (schemaVersion(db) === 11) {
+			// Removes Discourse's Papyrus-embedded storage entirely: confirmed zero rows in every
+			// discourse_* table and zero Docs carrying the reserved context-thread/context-message
+			// subtypes in the real production database before this was written -- Discourse's real
+			// home is now the standalone @danypops/discourse package plus host adapters, and
+			// Papyrus's own copy never had a single real caller since it was built. IF EXISTS
+			// throughout: a database that never actually reached the v5->v6 discourse-context-mesh
+			// step in the first place (e.g. a test fixture that starts partway through the chain)
+			// must not fail here just because there was nothing to remove.
+			db.exec(`
+				DROP TRIGGER IF EXISTS discourse_artifact_type_immutable;
+				DROP TRIGGER IF EXISTS discourse_posts_artifact_type;
+				DROP TRIGGER IF EXISTS discourse_threads_artifact_type;
+				DROP INDEX IF EXISTS discourse_posts_thread_idx;
+				DROP TABLE IF EXISTS discourse_projection_cursors;
+				DROP TABLE IF EXISTS discourse_cursors;
+				DROP TABLE IF EXISTS discourse_events;
+				DROP TABLE IF EXISTS discourse_posts;
+				DROP TABLE IF EXISTS discourse_threads;
+				DELETE FROM relation_names WHERE name IN ('reply_to', 'discusses');
+				PRAGMA user_version = 12;
+			`);
+			applied.push("remove-discourse");
+		}
+		if (schemaVersion(db) !== SQLITE_SCHEMA_VERSION) throw new Error(`no explicit migration path from database schema ${from}`);
 	});
 	if (schemaVersion(db) === SQLITE_SCHEMA_VERSION) ensureCoreLedger(db, true);
 	return { from, to: schemaVersion(db), applied };

package/src/domain/log-entry.ts

@@ -0,0 +1,120 @@
+/**
+ * domain/log-entry.ts — the `log` domain: structured, timestamped event records from any
+ * source (an external adapter, a live session/context-window snapshot, later maybe
+ * Papyrus's own operations), captured for both post-mortem review and live tailing.
+ *
+ * Deliberately NOT an Artifact kind (see the "match durable output to the right artifact
+ * kind" Rule): a log entry has no lifecycle/status, is not individually curated, and the
+ * corpus is naturally unbounded/continuously growing -- the opposite of what belongs in the
+ * bounded, curated Artifact graph. Retention (LOG_RETENTION_MAX_ENTRIES_PER_SOURCE) is a
+ * first-class concern here in a way it deliberately is NOT for the permanent
+ * artifact_events/task_events audit trails: logs are meant to be rotated, not kept forever.
+ *
+ * Mirrors ConversationJournal's own discipline (idempotency via a caller-constructed
+ * composite operationId, explicit non-silent truncation) since both are append-only,
+ * externally-sourced record streams -- but logs have no reply structure and do carry a
+ * retention policy, which a durable conversation record deliberately does not.
+ */
+
+export const LOG_LEVELS = ["debug", "info", "warning", "error"] as const;
+export type LogLevel = typeof LOG_LEVELS[number];
+
+export const LOG_SOURCE_ID_MAX_LENGTH = 256;
+export const LOG_MESSAGE_MAX_CHARACTERS = 4000;
+/** Bound on the serialized JSON size of an entry's structured fields. */
+export const LOG_FIELDS_MAX_CHARACTERS = 8000;
+export const LOG_QUERY_MAX_ENTRIES = 500;
+/** Oldest entries beyond this count (per source) are trimmed on every append -- see the module comment on why logs are retained, not kept forever. */
+export const LOG_RETENTION_MAX_ENTRIES_PER_SOURCE = 5000;
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+export interface LogSource {
+	readonly id: string;
+	readonly label: string;
+	readonly projectRoot: string | null;
+	readonly createdAt: string;
+}
+
+export interface LogEntry {
+	readonly id: string;
+	readonly sourceId: string;
+	readonly occurredAt: string;
+	readonly level: LogLevel;
+	readonly message: string;
+	/** True when message was cut to LOG_MESSAGE_MAX_CHARACTERS -- never silently. */
+	readonly truncated: boolean;
+	readonly fields: JsonValue;
+	/**
+	 * Idempotency key. Must be a composite the caller constructs (e.g. `${sessionId}:${turn}`),
+	 * never a bare upstream id alone -- a source's own local ids are commonly unique only
+	 * within one recording run, not globally, matching ConversationJournal's identical
+	 * operationId discipline and the concrete case it generalizes from (Pi's /tree lessons).
+	 */
+	readonly operationId: string;
+	readonly sessionId?: string;
+}
+
+export interface AppendLogEntryCommand {
+	readonly sourceId: string;
+	/** Used only the first time this sourceId is seen; ignored on every later append to the same source. */
+	readonly sourceLabel?: string;
+	readonly projectRoot?: string | null;
+	readonly level: LogLevel;
+	readonly message: string;
+	readonly fields?: JsonValue;
+	readonly operationId: string;
+	readonly sessionId?: string;
+	/** Caller-supplied for post-mortem/backfilled entries with a real historical timestamp; defaults to now for live entries. */
+	readonly occurredAt?: string;
+}
+
+export interface AppendLogEntryResult {
+	readonly entry: LogEntry;
+	/** True when this exact operationId was already logged and this call was a safe no-op replay. */
+	readonly replayed: boolean;
+}
+
+export interface LogQuery {
+	readonly sourceId: string;
+	/** ISO timestamp, exclusive lower bound -- the live-tail/polling cursor. */
+	readonly since?: string;
+	/** A floor, not an exact match: "warning" returns warning and error, matching conventional log-level filters. */
+	readonly level?: LogLevel;
+	readonly limit?: number;
+}
+
+export interface LogEntryPage {
+	readonly entries: readonly LogEntry[];
+	/** True when more entries exist beyond this page -- never silently drop the remainder without saying so. */
+	readonly truncated: boolean;
+}
+
+function requireBounded(value: string, label: string, maxLength: number): string {
+	if (value.length === 0) throw new Error(`${label} is required`);
+	if (value.length > maxLength) throw new Error(`${label} exceeds ${maxLength} characters`);
+	return value;
+}
+
+export function validateAppendLogEntryCommand(command: AppendLogEntryCommand): void {
+	requireBounded(command.sourceId, "sourceId", LOG_SOURCE_ID_MAX_LENGTH);
+	requireBounded(command.operationId, "operationId", LOG_SOURCE_ID_MAX_LENGTH * 2);
+	if (command.message.length === 0) throw new Error("message is required");
+	if (!(LOG_LEVELS as readonly string[]).includes(command.level)) throw new Error(`level must be one of ${LOG_LEVELS.join(", ")}`);
+	const fieldsSize = command.fields === undefined ? 0 : JSON.stringify(command.fields).length;
+	if (fieldsSize > LOG_FIELDS_MAX_CHARACTERS) throw new Error(`fields exceeds ${LOG_FIELDS_MAX_CHARACTERS} characters when serialized`);
+}
+
+/** Applies the explicit truncation bound. Never silently drops the truncation fact -- callers must surface `truncated`. */
+export function boundMessage(message: string): { message: string; truncated: boolean } {
+	if (message.length <= LOG_MESSAGE_MAX_CHARACTERS) return { message, truncated: false };
+	return { message: message.slice(0, LOG_MESSAGE_MAX_CHARACTERS), truncated: true };
+}
+
+const LEVEL_SEVERITY: Record<LogLevel, number> = { debug: 0, info: 1, warning: 2, error: 3 };
+
+/** True when `level` meets or exceeds `minimum` -- LogQuery.level is a floor, not an exact match. */
+export function meetsLevel(level: LogLevel, minimum: LogLevel): boolean {
+	return LEVEL_SEVERITY[level] >= LEVEL_SEVERITY[minimum];
+}