@danypops/papyrus 0.13.5 → 0.14.0

package/extension/src/context-budget.ts

@@ -172,9 +172,24 @@ export interface MessageHistoryTree {
  * estimate the conversation's context contribution AND surface branches explored via /tree
  * that are no longer on the active path -- content that cost real tokens to generate but is
  * NOT currently part of the context window. Bounded and cycle-safe (CONTEXT_TREE_MAX_NODES):
- * a session file is external, mutable state, and this deliberately
- * hardens past a confirmed real gap in Pi's own getBranch() (no cycle guard at all) rather
- * than assuming the tree can never be malformed.
+ * a session file is external, mutable state, and this deliberately hardens past a confirmed
+ * real gap in Pi's own getBranch() (no cycle guard at all) rather than assuming the tree can
+ * never be malformed.
+ *
+ * `activeEntryIds` MUST come from ctx.sessionManager.buildContextEntries(), not getBranch().
+ * getBranch()'s own docstring says it "[i]ncludes all entry types... Use buildSessionContext()
+ * to get the resolved messages for the LLM" -- it does not skip entries a real compaction has
+ * already summarized away. A real session with 3 compactions confirmed using getBranch() here
+ * overcounts activeTokens by over 13x, since every pre-compaction message still reads as
+ * "active". buildContextEntries() is Pi's own compaction-aware entry list: the latest
+ * compaction entry, its kept entries from firstKeptEntryId onward, and everything after.
+ *
+ * `branchEntryIds` (optional) is the full raw current-path id set (getBranch()'s own output).
+ * When given, an entry on the branch path but excluded from activeEntryIds is labeled
+ * "(compacted)" rather than the less accurate "(inactive branch)", which is reserved for
+ * entries not on the current path at all (a genuinely abandoned /tree branch). Omitting it
+ * preserves the simpler binary active/inactive-branch labeling for callers that only have one
+ * set to give (e.g. tests).
  */
 interface WalkFrame {
 	node: SessionTreeNodeLike;
@@ -190,7 +205,7 @@ interface WalkFrame {
  * JavaScript call-stack overflow at that scale, independent of the CONTEXT_TREE_MAX_NODES
  * bound entirely.
  */
-export function buildMessageHistoryTree(roots: ReadonlyArray<SessionTreeNodeLike>, activeEntryIds: ReadonlySet<string>): MessageHistoryTree {
+export function buildMessageHistoryTree(roots: ReadonlyArray<SessionTreeNodeLike>, activeEntryIds: ReadonlySet<string>, branchEntryIds?: ReadonlySet<string>): MessageHistoryTree {
 	const visited = new Set<string>();
 	let truncated = false;
 	let activeTokens = 0;
@@ -222,12 +237,13 @@ export function buildMessageHistoryTree(roots: ReadonlyArray<SessionTreeNodeLike
 		const tokens = Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
 		const isActive = activeEntryIds.has(entry.id);
 		if (isActive) activeTokens += tokens;
+		const isOnBranch = branchEntryIds ? branchEntryIds.has(entry.id) : isActive; // no branch set given -- fall back to the old binary active/inactive-branch label
 
 		const children = childItemsByParent.get(index) ?? [];
 		if (tokens === 0 && children.length === 0) continue; // no content, no descendants with content -- nothing to show
 
 		const item: ContextSegmentItem = {
-			label: isActive ? entryLabel(entry) : `${entryLabel(entry)} (inactive branch)`,
+			label: isActive ? entryLabel(entry) : isOnBranch ? `${entryLabel(entry)} (compacted)` : `${entryLabel(entry)} (inactive branch)`,
 			estimatedTokens: tokens,
 			...(children.length > 0 ? { children } : {}),
 		};

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({
@@ -431,8 +462,17 @@ export default async function (pi: ExtensionAPI) {
 				// Real tree (not just the linear current-branch path): surfaces content sitting in an
 				// abandoned /tree branch, which cost real tokens to generate but isn't in context now.
 				const tree = ctx.sessionManager.getTree() as unknown as SessionTreeNodeLike[];
-				const activeEntryIds = new Set((ctx.sessionManager.getBranch() as unknown as SessionEntryLike[]).map((entry) => entry.id));
-				const messageHistory = buildMessageHistoryTree(tree, activeEntryIds);
+				// buildContextEntries(), NOT getBranch(): getBranch() returns every raw entry on the
+				// current path including everything a real compaction has already summarized away.
+				// A session with 3 real compactions confirmed this made "active" message-history
+				// tokens overcount the real total by over 13x -- getBranch()'s own docstring already
+				// says as much ("Use buildSessionContext() to get the resolved messages for the
+				// LLM"); buildContextEntries() is the compaction-aware entry list matching what the
+				// LLM actually sees (the latest compaction entry itself, plus kept entries from its
+				// firstKeptEntryId onward, plus everything after -- older summarized entries omitted).
+				const activeEntryIds = new Set((ctx.sessionManager.buildContextEntries() as unknown as SessionEntryLike[]).map((entry) => entry.id));
+				const branchEntryIds = new Set((ctx.sessionManager.getBranch() as unknown as SessionEntryLike[]).map((entry) => entry.id));
+				const messageHistory = buildMessageHistoryTree(tree, activeEntryIds, branchEntryIds);
 				const breakdown = buildContextBreakdown({
 					totalTokens: usage?.tokens ?? null,
 					contextWindow: ctx.model?.contextWindow ?? null,
@@ -492,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.5",
+  "version": "0.14.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/cli.ts

@@ -112,6 +112,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]
@@ -873,6 +875,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[] = [];
@@ -1272,6 +1339,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,7 +7,7 @@ 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 = 11;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 /** Bounded forum persistence behind the Discourse mutation authority. */
 export const DISCOURSE_QUERY_MAX_LIMIT = 100;

package/src/db.ts

@@ -250,6 +250,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 = `
@@ -327,6 +348,7 @@ 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" },
 ];
 
 export function migrationLedger(db: Db): ModuleMigrationRow[] {
@@ -401,9 +423,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 +648,34 @@ 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) !== 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];
+}

package/src/log-service.ts

@@ -0,0 +1,58 @@
+import { randomUUID } from "node:crypto";
+import {
+	boundMessage,
+	LOG_QUERY_MAX_ENTRIES,
+	LOG_RETENTION_MAX_ENTRIES_PER_SOURCE,
+	meetsLevel,
+	validateAppendLogEntryCommand,
+	type AppendLogEntryCommand,
+	type AppendLogEntryResult,
+	type LogEntryPage,
+	type LogQuery,
+} from "./domain/log-entry.ts";
+import type { LogStore } from "./ports/log-store.ts";
+
+export class Logs {
+	constructor(private readonly store: LogStore) {}
+
+	append(command: AppendLogEntryCommand): AppendLogEntryResult {
+		validateAppendLogEntryCommand(command);
+		this.store.ensureSource(command.sourceId, command.sourceLabel ?? command.sourceId, command.projectRoot ?? null);
+		const existing = this.store.findEntryByOperationId(command.sourceId, command.operationId);
+		if (existing) return { entry: existing, replayed: true };
+
+		const { message, truncated } = boundMessage(command.message);
+		const entry = {
+			id: randomUUID(),
+			sourceId: command.sourceId,
+			occurredAt: command.occurredAt ?? new Date().toISOString(),
+			level: command.level,
+			message,
+			truncated,
+			fields: command.fields ?? {},
+			operationId: command.operationId,
+			sessionId: command.sessionId,
+		};
+		this.store.insertEntry(entry);
+		this.store.trimSource(command.sourceId, LOG_RETENTION_MAX_ENTRIES_PER_SOURCE);
+		return { entry, replayed: false };
+	}
+
+	/**
+	 * `since` given: this is a live-tail/polling cursor -- return the OLDEST entries in the
+	 * window so a caller can advance its cursor without skipping any, at the cost of not yet
+	 * seeing the very latest (call again with a later `since` to keep catching up).
+	 * `since` omitted: this is a post-mortem browse -- return the MOST RECENT entries,
+	 * matching `tail -n`'s familiar behavior.
+	 */
+	query(query: LogQuery): LogEntryPage {
+		const limit = Math.min(query.limit ?? LOG_QUERY_MAX_ENTRIES, LOG_QUERY_MAX_ENTRIES);
+		const matching = this.store.entriesForSource(query.sourceId)
+			.filter((entry) => query.since === undefined || entry.occurredAt > query.since)
+			.filter((entry) => query.level === undefined || meetsLevel(entry.level, query.level));
+
+		if (matching.length <= limit) return { entries: matching, truncated: false };
+		const windowed = query.since !== undefined ? matching.slice(0, limit) : matching.slice(matching.length - limit);
+		return { entries: windowed, truncated: true };
+	}
+}

package/src/modules/logs.ts

@@ -0,0 +1,75 @@
+/**
+ * modules/logs.ts — the `log` domain as a registered Papyrus-native module.
+ *
+ * Deliberately self-contained: does not import artifact/task/rule/skill infrastructure --
+ * logs never touch the Artifact graph directly (see src/domain/log-entry.ts's own module
+ * comment on why `log` is not an Artifact kind).
+ */
+import type { JsonValue, LogLevel } from "../domain/log-entry.ts";
+import type { OperationDefinition } from "../module-registry.ts";
+import type { Logs } from "../log-service.ts";
+
+const MODULE_ID = "logs";
+
+type OperationInput = Record<string, unknown>;
+
+function string(input: OperationInput, key: string): string {
+	const value = input[key];
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${key} is required`);
+	return value;
+}
+
+function optionalString(input: OperationInput, key: string): string | undefined {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") throw new Error(`${key} must be a string`);
+	return value;
+}
+
+function optionalNumber(input: OperationInput, key: string): number | undefined {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${key} must be a number`);
+	return value;
+}
+
+function isJsonValue(value: unknown): value is JsonValue {
+	return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean"
+		|| Array.isArray(value) || (typeof value === "object");
+}
+
+function optionalFields(input: OperationInput, key: string): JsonValue | undefined {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	if (!isJsonValue(value)) throw new Error(`${key} must be JSON-serializable`);
+	return value;
+}
+
+/** This module's own operation names, the single source of truth src/service.ts's EXPECTED_OPERATION_NAMES spreads in rather than re-listing by hand. */
+export const LOGS_OPERATION_NAMES = ["logs.append", "logs.query"] as const;
+
+/** Registers every logs.* operation against one Logs instance. */
+export function logsOperations(logs: Logs): OperationDefinition[] {
+	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
+		name, moduleId: MODULE_ID, execute,
+	});
+	return [
+		define("logs.append", (input: OperationInput) => logs.append({
+			sourceId: string(input, "source_id"),
+			sourceLabel: optionalString(input, "source_label"),
+			projectRoot: optionalString(input, "project_root") ?? null,
+			level: string(input, "level") as LogLevel,
+			message: string(input, "message"),
+			fields: optionalFields(input, "fields"),
+			operationId: string(input, "operation_id"),
+			sessionId: optionalString(input, "session_id"),
+			occurredAt: optionalString(input, "occurred_at"),
+		})),
+		define("logs.query", (input: OperationInput) => logs.query({
+			sourceId: string(input, "source_id"),
+			since: optionalString(input, "since"),
+			level: optionalString(input, "level") as LogLevel | undefined,
+			limit: optionalNumber(input, "limit"),
+		})),
+	];
+}

package/src/ports/log-store.ts

@@ -0,0 +1,17 @@
+import type { LogEntry, LogSource } from "../domain/log-entry.ts";
+
+/**
+ * Persistence port for the `log` domain. Deliberately minimal, matching
+ * ConversationJournalStore's own split: this is dumb storage (idempotency-key lookup,
+ * insert, bounded-at-the-service-layer reads) plus one operation the store must own because
+ * only it knows real row counts -- retention trimming.
+ */
+export interface LogStore {
+	ensureSource(sourceId: string, label: string, projectRoot: string | null): LogSource;
+	findEntryByOperationId(sourceId: string, operationId: string): LogEntry | undefined;
+	insertEntry(entry: LogEntry): void;
+	/** All entries for one source, chronological (oldest first), unbounded at the store layer -- the service applies query bounds/filters. */
+	entriesForSource(sourceId: string): readonly LogEntry[];
+	/** Deletes the oldest entries for a source beyond `maxEntries`, returning how many were removed -- retention enforcement, not a general delete capability. */
+	trimSource(sourceId: string, maxEntries: number): number;
+}

package/src/service.ts

@@ -24,9 +24,12 @@ import {
 	listInjectableRules,
 } from "./domain-services.ts";
 import { Notes, NOTE_SUBTYPE } from "./note-service.ts";
+import { Logs } from "./log-service.ts";
+import { SQLiteLogStore } from "./adapters/sqlite-log-store.ts";
 import { OperationRegistry } from "./module-registry.ts";
 import { docsOperations, DOCS_OPERATION_NAMES } from "./modules/docs.ts";
 import { graphProjectionOperations, GRAPH_PROJECTION_OPERATION_NAMES } from "./modules/graph-projection.ts";
+import { logsOperations, LOGS_OPERATION_NAMES } from "./modules/logs.ts";
 import { notesOperations, NOTES_OPERATION_NAMES } from "./modules/notes.ts";
 import { rulesOperations, RULES_OPERATION_NAMES } from "./modules/rules.ts";
 import { skillsOperations, SKILLS_OPERATION_NAMES } from "./modules/skills.ts";
@@ -65,6 +68,7 @@ export const EXPECTED_OPERATION_NAMES = [
 	...RULES_OPERATION_NAMES,
 	...SKILLS_OPERATION_NAMES,
 	...GRAPH_PROJECTION_OPERATION_NAMES,
+	...LOGS_OPERATION_NAMES,
 ] as const;
 
 export type OperationName = typeof EXPECTED_OPERATION_NAMES[number];
@@ -371,6 +375,8 @@ function handlers(
 		},
 		"graph_projection.apply": forwardToModule("graph_projection.apply"),
 		"graph_projection.checkpoint": forwardToModule("graph_projection.checkpoint"),
+		"logs.append": forwardToModule("logs.append"),
+		"logs.query": forwardToModule("logs.query"),
 	};
 }
 
@@ -386,9 +392,11 @@ export function createPapyrusService(path: string): PapyrusService {
 	const discourse = new SQLiteDiscourseStore(db, artifacts);
 	const projections = new SQLiteGraphProjectionStore(db);
 	const artifactScopes = new SQLiteArtifactScopeStore(db);
+	const logs = new Logs(new SQLiteLogStore(db));
 	const authority = createAuthorityRegistry();
 	const moduleRegistry = new OperationRegistry();
 	moduleRegistry.registerAll(notesOperations(notes));
+	moduleRegistry.registerAll(logsOperations(logs));
 	moduleRegistry.registerAll(tasksOperations(tasks, artifacts));
 	moduleRegistry.registerAll(docsOperations(artifacts, artifactScopes, authority));
 	moduleRegistry.registerAll(rulesOperations(artifacts, artifactScopes));