@danypops/papyrus 0.33.5 → 0.34.0

package/extension/src/domain-tools.ts

@@ -6,6 +6,7 @@ import { PROOF_TYPES } from "../../src/domain/checklist.ts";
 import type { GateResult } from "../../src/domain/gate.ts";
 import type { TaskExecutionPlan } from "../../src/task-execution.ts";
 import type { TaskHistoryPage } from "../../src/domain/task-event.ts";
+import type { NoteHistoryPage } from "../../src/domain/note-event.ts";
 import type { TaskCompletion, TaskGraph } from "../../src/task-service.ts";
 import type { SkillWorkflowRunResult } from "../../src/skill-execution.ts";
 import type { DiscussionAndRounds } from "../../src/discussion-service.ts";
@@ -474,7 +475,7 @@ export function registerNotesTool(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "notes",
 		label: "Notes",
-		description: "Deferred human-intent inbox. ACTIONS: capture, list, show, consume, promote, archive. Capture stores a request without creating work. Consume marks it considered. To promote, first create the resulting Task, Doc, Rule, or Skill through its domain tool, then link it with target_id (or target_name). Archive requires an explicit disposition. PREFER `name` (the note's exact title) over `id` for show/consume/promote/archive, and `target_name` over `target_id` for promote -- all are backend implementation details, resolved from name automatically (target_name searches across every kind, since a promotion target can be a task, doc, rule, or skill).",
+		description: "Deferred human-intent inbox. ACTIONS: capture, list, show, history, consume, promote, archive. Capture stores a request without creating work. Consume marks it considered. To promote, first create the resulting Task, Doc, Rule, or Skill through its domain tool, then link it with target_id (or target_name). Archive requires an explicit disposition. history returns this note's own real append-only event log (captured/consumed/promoted/archived), not the generic cross-kind graph.history. PREFER `name` (the note's exact title) over `id` for show/history/consume/promote/archive, and `target_name` over `target_id` for promote -- all are backend implementation details, resolved from name automatically (target_name searches across every kind, since a promotion target can be a task, doc, rule, or skill).",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
@@ -516,6 +517,12 @@ export function registerNotesTool(pi: ExtensionAPI): void {
 					const artifact = await callService<Record<string, unknown>, Artifact>("notes.show", request);
 					return text(`${artifactLine(artifact)}\n\n${artifact.body}`, createArtifactDetails("notes.show", artifact));
 				}
+				if (action === "history") {
+					const page = await callService<Record<string, unknown>, NoteHistoryPage>("notes.history", request);
+					const lines = page.events.map((event) => `${event.occurredAt} ${event.type} · ${event.actor}/${event.source}${event.relatedId ? ` · ${event.relatedId}` : ""}${event.disposition ? ` · ${event.disposition}` : ""}${event.reason ? ` · ${event.reason}` : ""}`);
+					const output = lines.join("\n") || "No recorded history for this note.";
+					return text(output, createPreviewDetails("notes.history", "Note history", output));
+				}
 				const operations = { consume: "notes.consume", promote: "notes.promote", archive: "notes.archive" } as const;
 				const operation = operations[action as keyof typeof operations];
 				if (!operation) throw new Error(`unknown notes action: ${action}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.33.5",
+  "version": "0.34.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-note-event-store.ts

@@ -0,0 +1,80 @@
+import type { Db } from "../db.ts";
+import {
+	normalizeNoteHistoryQuery,
+	validateNoteEvent,
+	type AppendNoteEvent,
+	type NoteEvent,
+	type NoteEventType,
+	type NoteHistoryPage,
+	type NoteHistoryQuery,
+} from "../domain/note-event.ts";
+import type { NoteEventStore } from "../ports/note-event-store.ts";
+
+interface NoteEventRow {
+	id: number;
+	note_id: string;
+	occurred_at: string;
+	event_type: NoteEventType;
+	actor: string;
+	source: string;
+	session_id: string | null;
+	reason: string | null;
+	related_id: string | null;
+	disposition: string | null;
+	event_schema_version: 1;
+}
+
+function mapRow(row: NoteEventRow): NoteEvent {
+	return {
+		id: row.id,
+		noteId: row.note_id,
+		occurredAt: row.occurred_at,
+		type: row.event_type,
+		actor: row.actor,
+		source: row.source,
+		...(row.session_id === null ? {} : { sessionId: row.session_id }),
+		...(row.reason === null ? {} : { reason: row.reason }),
+		...(row.related_id === null ? {} : { relatedId: row.related_id }),
+		...(row.disposition === null ? {} : { disposition: row.disposition }),
+		schemaVersion: row.event_schema_version,
+	};
+}
+
+export class SQLiteNoteEventStore implements NoteEventStore {
+	constructor(private readonly db: Db) {}
+
+	append(input: AppendNoteEvent): NoteEvent {
+		const event = validateNoteEvent(input);
+		const result = this.db.prepare(`
+			INSERT INTO note_events (
+				note_id, occurred_at, event_type, actor, source, session_id, reason, related_id, disposition, event_schema_version
+			) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 1)
+		`).run(
+			event.noteId,
+			new Date().toISOString(),
+			event.type,
+			event.actor,
+			event.source,
+			event.sessionId ?? null,
+			event.reason ?? null,
+			event.relatedId ?? null,
+			event.disposition ?? null,
+		);
+		return mapRow(this.db.prepare("SELECT * FROM note_events WHERE id = ?").get(result.lastInsertRowid) as NoteEventRow);
+	}
+
+	history(noteId: string, query: NoteHistoryQuery = {}): NoteHistoryPage {
+		const { limit, direction, cursor } = normalizeNoteHistoryQuery(query);
+		const comparator = direction === "desc" ? "<" : ">";
+		const order = direction === "desc" ? "DESC" : "ASC";
+		const rows = this.db.prepare(`
+			SELECT * FROM note_events
+			WHERE note_id = ? ${cursor === undefined ? "" : `AND id ${comparator} ?`}
+			ORDER BY occurred_at ${order}, id ${order}
+			LIMIT ?
+		`).all(...(cursor === undefined ? [noteId, limit + 1] : [noteId, cursor, limit + 1])) as NoteEventRow[];
+		const hasMore = rows.length > limit;
+		const events = rows.slice(0, limit).map(mapRow);
+		return { events, ...(hasMore ? { nextCursor: events.at(-1)!.id } : {}) };
+	}
+}

package/src/cli.ts

@@ -1274,7 +1274,7 @@ export async function runNoteCli(args: string[], client: TaskCliClient, projectR
 		positional.push(argument);
 	}
 	const [action, id, target] = positional;
-	let result: CliArtifact | CliArtifact[];
+	let result: CliArtifact | CliArtifact[] | import("./domain/note-event.ts").NoteHistoryPage;
 	let human: string;
 	if (action === "capture") {
 		if (!id || target) throw new Error("notes capture requires exactly one request argument");
@@ -1288,6 +1288,13 @@ export async function runNoteCli(args: string[], client: TaskCliClient, projectR
 		if (!id || target) throw new Error("notes show requires exactly one note id");
 		result = await client.call("notes.show", { id, project_root: projectRoot }) as CliArtifact;
 		human = `${artifactLabel(result)}\n\n${result.body ?? ""}`.trimEnd();
+	} else if (action === "history") {
+		if (!id || target) throw new Error("notes history requires exactly one note id");
+		const page = await client.call<Record<string, unknown>, import("./domain/note-event.ts").NoteHistoryPage>("notes.history", { id, project_root: projectRoot, direction: "desc", ...(limit === undefined ? {} : { limit }) });
+		result = page;
+		human = page.events.length === 0
+			? `No recorded history for ${id}.`
+			: [...page.events].reverse().map((event) => `${event.occurredAt} ${event.type} · ${event.actor}/${event.source}${event.relatedId ? ` · ${event.relatedId}` : ""}${event.disposition ? ` · ${event.disposition}` : ""}${event.reason ? ` · ${event.reason}` : ""}`).join("\n");
 	} else if (action === "consume") {
 		if (!id || target) throw new Error("notes consume requires exactly one note id");
 		result = await client.call("notes.consume", { id, project_root: projectRoot, actor: "agent", source: "cli", ...(reason ? { reason } : {}) }) as CliArtifact;
@@ -1301,7 +1308,7 @@ export async function runNoteCli(args: string[], client: TaskCliClient, projectR
 		result = await client.call("notes.archive", { id, disposition: target, project_root: projectRoot, actor: "human", source: "cli", ...(reason ? { reason } : {}) }) as CliArtifact;
 		human = `Archived: ${artifactLabel(result)} · ${target}`;
 	} else {
-		throw new Error("notes action must be capture, list, show, consume, promote, or archive");
+		throw new Error("notes action must be capture, list, show, history, consume, promote, or archive");
 	}
 	return json ? JSON.stringify(result) : human;
 }

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 = 20;
+export const SQLITE_SCHEMA_VERSION = 21;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -156,9 +156,10 @@ export const NOTE_BODY_MAX_CHARACTERS = 10_000;
 export const NOTE_TITLE_MAX_CHARACTERS = 80;
 export const NOTE_LIST_DEFAULT_LIMIT = 50;
 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;
+export const NOTE_HISTORY_DEFAULT_LIMIT = 25;
+export const NOTE_HISTORY_MAX_LIMIT = 100;
 /** 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;

package/src/db.ts

@@ -266,6 +266,25 @@ CREATE TABLE IF NOT EXISTS task_leases (
 	note              TEXT
 );
 CREATE INDEX IF NOT EXISTS task_leases_expiry_idx ON task_leases(lease_expires_at);
+CREATE TABLE IF NOT EXISTS note_events (
+	id                   INTEGER PRIMARY KEY AUTOINCREMENT,
+	note_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,
+	reason               TEXT,
+	related_id           TEXT,
+	disposition          TEXT,
+	event_schema_version INTEGER NOT NULL DEFAULT 1
+);
+CREATE INDEX IF NOT EXISTS note_events_history_idx ON note_events(note_id, occurred_at, id);
+CREATE TRIGGER IF NOT EXISTS note_events_no_update BEFORE UPDATE ON note_events
+BEGIN SELECT RAISE(ABORT, 'note_events are append-only'); END;
+CREATE TRIGGER IF NOT EXISTS note_events_no_delete BEFORE DELETE ON note_events
+WHEN NOT EXISTS (SELECT 1 FROM artifact_trash WHERE artifact_id = OLD.note_id AND purge_after <= strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+BEGIN SELECT RAISE(ABORT, 'note_events are append-only except during an explicit, elapsed-grace-period artifact trash purge'); END;
 `;
 
 const SEED_SQL = `
@@ -576,6 +595,66 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 			`);
 		},
 	},
+	{
+		version: 21,
+		name: "note-events",
+		// See domain/note-event.ts. Retires extra.noteHistory (a bounded array inside a mutable
+		// JSON field, which a later setExtra from a concurrent operation could silently overwrite)
+		// in favor of a real append-only table, mirroring task_events' already-proven shape.
+		up: (db) => {
+			db.exec(`
+				CREATE TABLE IF NOT EXISTS note_events (
+					id                   INTEGER PRIMARY KEY AUTOINCREMENT,
+					note_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,
+					reason               TEXT,
+					related_id           TEXT,
+					disposition          TEXT,
+					event_schema_version INTEGER NOT NULL DEFAULT 1
+				);
+				CREATE INDEX IF NOT EXISTS note_events_history_idx ON note_events(note_id, occurred_at, id);
+				CREATE TRIGGER IF NOT EXISTS note_events_no_update BEFORE UPDATE ON note_events
+				BEGIN SELECT RAISE(ABORT, 'note_events are append-only'); END;
+				CREATE TRIGGER IF NOT EXISTS note_events_no_delete BEFORE DELETE ON note_events
+				WHEN NOT EXISTS (SELECT 1 FROM artifact_trash WHERE artifact_id = OLD.note_id AND purge_after <= strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+				BEGIN SELECT RAISE(ABORT, 'note_events are append-only except during an explicit, elapsed-grace-period artifact trash purge'); END;
+			`);
+			const rows = db.prepare("SELECT id, extra FROM artifacts WHERE kind = 'doc' AND subtype = 'note'").all() as Array<{ id: string; extra: string }>;
+			const insert = db.prepare(`
+				INSERT INTO note_events (note_id, occurred_at, event_type, actor, source, session_id, reason, related_id, disposition, event_schema_version)
+				VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 1)
+			`);
+			const strip = db.prepare("UPDATE artifacts SET extra = ? WHERE id = ?");
+			for (const row of rows) {
+				const extra = JSON.parse(row.extra) as Record<string, unknown>;
+				const noteHistory = extra["noteHistory"];
+				if (Array.isArray(noteHistory)) {
+					for (const raw of noteHistory) {
+						const entry = raw as Record<string, unknown>;
+						insert.run(
+							row.id,
+							typeof entry["at"] === "string" ? entry["at"] : new Date().toISOString(),
+							typeof entry["action"] === "string" ? entry["action"] : "captured",
+							typeof entry["actor"] === "string" ? entry["actor"] : "system",
+							typeof entry["source"] === "string" ? entry["source"] : "unknown",
+							typeof entry["sessionId"] === "string" ? entry["sessionId"] : null,
+							typeof entry["reason"] === "string" ? entry["reason"] : null,
+							typeof entry["targetId"] === "string" ? entry["targetId"] : null,
+							typeof entry["disposition"] === "string" ? entry["disposition"] : null,
+						);
+					}
+				}
+				if ("noteHistory" in extra) {
+					const { noteHistory: _drop, ...rest } = extra;
+					strip.run(JSON.stringify(rest), row.id);
+				}
+			}
+		},
+	},
 ];
 
 /**

package/src/domain/note-event.ts

@@ -0,0 +1,71 @@
+/**
+ * Notes' own append-only event log, mirroring task-event.ts's proven shape. Replaces the
+ * previous extra.noteHistory: a bounded array inside a mutable JSON field, which a later
+ * setExtra from a concurrent operation could overwrite -- a real record can't do that.
+ */
+import { NOTE_HISTORY_DEFAULT_LIMIT, NOTE_HISTORY_MAX_LIMIT, NOTE_PROVENANCE_MAX_LENGTH, NOTE_REASON_MAX_CHARACTERS } from "../constants.ts";
+
+export const NOTE_EVENT_TYPES = ["captured", "consumed", "promoted", "archived"] as const;
+export type NoteEventType = typeof NOTE_EVENT_TYPES[number];
+export type NoteEventDirection = "asc" | "desc";
+
+export interface NoteEvent {
+	id: number;
+	noteId: string;
+	occurredAt: string;
+	type: NoteEventType;
+	actor: string;
+	source: string;
+	sessionId?: string;
+	reason?: string;
+	/** Promotion target, when type is "promoted". */
+	relatedId?: string;
+	/** Archive disposition, or "promoted" -- mirrors the summary already kept at extra.disposition. */
+	disposition?: string;
+	schemaVersion: 1;
+}
+
+export interface AppendNoteEvent {
+	noteId: string;
+	type: NoteEventType;
+	actor: string;
+	source: string;
+	sessionId?: string;
+	reason?: string;
+	relatedId?: string;
+	disposition?: string;
+}
+
+export interface NoteHistoryQuery {
+	limit?: number;
+	cursor?: number;
+	direction?: NoteEventDirection;
+}
+
+export interface NoteHistoryPage {
+	events: NoteEvent[];
+	nextCursor?: number;
+}
+
+export function normalizeNoteHistoryQuery(query: NoteHistoryQuery = {}): Required<Pick<NoteHistoryQuery, "limit" | "direction">> & Pick<NoteHistoryQuery, "cursor"> {
+	const limit = query.limit ?? NOTE_HISTORY_DEFAULT_LIMIT;
+	if (!Number.isInteger(limit) || limit < 1 || limit > NOTE_HISTORY_MAX_LIMIT) {
+		throw new Error(`note history limit must be between 1 and ${NOTE_HISTORY_MAX_LIMIT}`);
+	}
+	if (query.cursor !== undefined && (!Number.isInteger(query.cursor) || query.cursor < 1)) {
+		throw new Error("note history cursor must be a positive integer");
+	}
+	if (query.direction !== undefined && query.direction !== "asc" && query.direction !== "desc") {
+		throw new Error("note history direction must be asc or desc");
+	}
+	return { limit, direction: query.direction ?? "desc", ...(query.cursor === undefined ? {} : { cursor: query.cursor }) };
+}
+
+export function validateNoteEvent(event: AppendNoteEvent): AppendNoteEvent {
+	for (const [field, value] of [["actor", event.actor], ["source", event.source]] as const) {
+		if (!value || value.length > NOTE_PROVENANCE_MAX_LENGTH) throw new Error(`${field} must be between 1 and ${NOTE_PROVENANCE_MAX_LENGTH} characters`);
+	}
+	if (event.sessionId !== undefined && event.sessionId.length > NOTE_PROVENANCE_MAX_LENGTH) throw new Error(`sessionId cannot exceed ${NOTE_PROVENANCE_MAX_LENGTH} characters`);
+	if (event.reason !== undefined && event.reason.length > NOTE_REASON_MAX_CHARACTERS) throw new Error(`reason cannot exceed ${NOTE_REASON_MAX_CHARACTERS} characters`);
+	return event;
+}

package/src/modules/notes.ts

@@ -13,6 +13,7 @@
  * module's infrastructure" constraint.
  */
 import type { OperationDefinition } from "../module-registry.ts";
+import type { NoteEventDirection } from "../domain/note-event.ts";
 import { Notes, type NoteDisposition } from "../note-service.ts";
 
 const MODULE_ID = "notes";
@@ -41,7 +42,7 @@ function optionalNumber(input: OperationInput, key: string): number | undefined
 
 /** 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 NOTES_OPERATION_NAMES = [
-	"notes.capture", "notes.list", "notes.show", "notes.consume", "notes.promote", "notes.archive",
+	"notes.capture", "notes.list", "notes.show", "notes.history", "notes.consume", "notes.promote", "notes.archive",
 ] as const;
 
 /** Registers every notes.* operation against one Notes instance. Behavior is unchanged from the prior inline handlers in src/service.ts. */
@@ -59,6 +60,9 @@ export function notesOperations(notes: Notes): OperationDefinition[] {
 			text: optionalString(input, "text"), limit: optionalNumber(input, "limit"),
 		})),
 		define("notes.show", (input: OperationInput) => notes.show(string(input, "id"), string(input, "project_root"))),
+		define("notes.history", (input: OperationInput) => notes.history(string(input, "id"), string(input, "project_root"), {
+			limit: optionalNumber(input, "limit"), cursor: optionalNumber(input, "cursor"), direction: optionalString(input, "direction") as NoteEventDirection | undefined,
+		})),
 		define("notes.consume", (input: OperationInput) => notes.consume(string(input, "id"), {
 			projectRoot: string(input, "project_root"), actor: optionalString(input, "actor"), source: optionalString(input, "source"),
 			sessionId: optionalString(input, "session_id"), reason: optionalString(input, "reason"),

package/src/note-service.ts

@@ -1,6 +1,5 @@
 import {
 	NOTE_BODY_MAX_CHARACTERS,
-	NOTE_HISTORY_MAX_EVENTS,
 	NOTE_LIST_DEFAULT_LIMIT,
 	NOTE_LIST_MAX_LIMIT,
 	NOTE_PROVENANCE_MAX_LENGTH,
@@ -9,6 +8,8 @@ import {
 	TASK_PROJECT_ROOT_MAX_LENGTH,
 } from "./constants.ts";
 import type { Artifact } from "./domain/artifact.ts";
+import type { AppendNoteEvent, NoteEventType, NoteHistoryPage, NoteHistoryQuery } from "./domain/note-event.ts";
+import { InMemoryNoteEventStore, type NoteEventStore } from "./ports/note-event-store.ts";
 import { requireAtomicArtifactStore } from "./ports/atomic-artifact-store.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
 
@@ -41,17 +42,6 @@ export interface ArchiveNoteInput extends NoteProvenance {
 	disposition: NoteDisposition;
 }
 
-interface NoteHistoryEvent {
-	action: "captured" | "consumed" | "promoted" | "archived";
-	at: string;
-	actor: string;
-	source: string;
-	sessionId?: string;
-	reason?: string;
-	targetId?: string;
-	disposition?: NoteDisposition | "promoted";
-}
-
 function requiredBounded(value: string, field: string, maximum: number): string {
 	const normalized = value.trim();
 	if (!normalized) throw new Error(`${field} is required`);
@@ -70,7 +60,7 @@ function noteTitle(body: string, requested?: string): string {
 	return firstLine.slice(0, NOTE_TITLE_MAX_CHARACTERS) || "Deferred note";
 }
 
-function provenance(input: NoteProvenance, defaults: { actor: string; source: string }): Omit<NoteHistoryEvent, "action" | "at"> {
+function provenance(input: NoteProvenance, defaults: { actor: string; source: string }): Omit<AppendNoteEvent, "noteId" | "type" | "relatedId" | "disposition"> {
 	return {
 		actor: optionalBounded(input.actor, "note actor", NOTE_PROVENANCE_MAX_LENGTH) ?? defaults.actor,
 		source: optionalBounded(input.source, "note source", NOTE_PROVENANCE_MAX_LENGTH) ?? defaults.source,
@@ -79,44 +69,26 @@ function provenance(input: NoteProvenance, defaults: { actor: string; source: st
 	};
 }
 
-function history(artifact: Artifact): NoteHistoryEvent[] {
-	const value = artifact.extra["noteHistory"];
-	if (!Array.isArray(value)) return [];
-	return value.filter((entry): entry is NoteHistoryEvent => typeof entry === "object" && entry !== null && !Array.isArray(entry));
-}
-
-function appendHistory(artifact: Artifact, event: NoteHistoryEvent): Record<string, unknown> {
-	return {
-		...artifact.extra,
-		noteHistory: [...history(artifact), event].slice(-NOTE_HISTORY_MAX_EVENTS),
-	};
-}
-
-function event(action: NoteHistoryEvent["action"], input: NoteProvenance, extra: Partial<NoteHistoryEvent> = {}): NoteHistoryEvent {
-	return {
-		action,
-		at: new Date().toISOString(),
-		...provenance(input, { actor: action === "captured" ? "human" : "agent", source: "notes" }),
-		...extra,
-	};
-}
-
 export class Notes {
-	constructor(private readonly artifacts: ArtifactStore) {}
+	constructor(
+		private readonly artifacts: ArtifactStore,
+		private readonly events: NoteEventStore = new InMemoryNoteEventStore(),
+	) {}
 
 	capture(input: CaptureNoteInput): Artifact {
 		const projectRoot = requiredBounded(input.projectRoot, "project_root", TASK_PROJECT_ROOT_MAX_LENGTH);
 		const body = requiredBounded(input.body, "note body", NOTE_BODY_MAX_CHARACTERS);
-		const captured = event("captured", input);
-		return this.artifacts.create({
+		const created = this.artifacts.create({
 			kind: "doc",
 			subtype: NOTE_SUBTYPE,
 			status: "draft",
 			title: noteTitle(body, input.title),
 			body,
 			labels: ["note", "inbox"],
-			extra: { projectRoot, noteHistory: [captured] },
+			extra: { projectRoot },
 		});
+		this.appendEvent(created.id, "captured", input, { actor: "human", source: "notes" });
+		return created;
 	}
 
 	list(input: ListNotesInput): Artifact[] {
@@ -141,6 +113,13 @@ export class Notes {
 		return this.artifacts.get(id, { tree: true })!;
 	}
 
+	/** Real append-only event history for this note -- see domain/note-event.ts. */
+	history(id: string, projectRoot: string, query?: NoteHistoryQuery): NoteHistoryPage {
+		const note = this.requireNote(id);
+		this.requireProject(note, projectRoot);
+		return this.events.history(id, query);
+	}
+
 	consume(id: string, input: NoteProvenance & { projectRoot: string }): Artifact {
 		const atomic = requireAtomicArtifactStore(this.artifacts);
 		return atomic.atomic(() => {
@@ -148,7 +127,7 @@ export class Notes {
 			this.requireProject(note, input.projectRoot);
 			if (note.status === "archived") throw new Error("cannot consume an archived note");
 			if (note.status === "active") return this.artifacts.get(id, { tree: true })!;
-			this.artifacts.setExtra(id, appendHistory(note, event("consumed", input)));
+			this.appendEvent(id, "consumed", input, { actor: "agent", source: "notes" });
 			this.artifacts.setStatus(id, "active");
 			return this.artifacts.get(id, { tree: true })!;
 		});
@@ -162,12 +141,12 @@ export class Notes {
 			if (note.status === "archived") throw new Error("cannot promote an archived note");
 			if (targetId === id) throw new Error("a note cannot promote to itself");
 			if (!this.artifacts.get(targetId)) throw new Error(`promotion target "${targetId}" not found`);
-			const promoted = event("promoted", input, { disposition: "promoted", targetId });
-			const disposition = { kind: "promoted", targetId, ...(promoted.reason ? { reason: promoted.reason } : {}) };
+			const reason = optionalBounded(input.reason, "note reason", NOTE_REASON_MAX_CHARACTERS);
 			this.artifacts.link({ from: id, relation: "relates_to", to: targetId });
+			this.appendEvent(id, "promoted", input, { actor: "agent", source: "notes" }, { relatedId: targetId, disposition: "promoted" });
 			this.artifacts.setExtra(id, {
-				...appendHistory(note, promoted),
-				disposition,
+				...note.extra,
+				disposition: { kind: "promoted", targetId, ...(reason ? { reason } : {}) },
 			});
 			this.artifacts.setStatus(id, "archived");
 			return this.artifacts.get(id, { tree: true })!;
@@ -181,17 +160,27 @@ export class Notes {
 			const note = this.requireNote(id);
 			this.requireProject(note, input.projectRoot);
 			if (note.status === "archived") throw new Error("note is already archived");
-			const archived = event("archived", input, { disposition: input.disposition });
-			const details = { kind: input.disposition, ...(archived.reason ? { reason: archived.reason } : {}) };
+			const reason = optionalBounded(input.reason, "note reason", NOTE_REASON_MAX_CHARACTERS);
+			this.appendEvent(id, "archived", input, { actor: "agent", source: "notes" }, { disposition: input.disposition });
 			this.artifacts.setExtra(id, {
-				...appendHistory(note, archived),
-				disposition: details,
+				...note.extra,
+				disposition: { kind: input.disposition, ...(reason ? { reason } : {}) },
 			});
 			this.artifacts.setStatus(id, "archived");
 			return this.artifacts.get(id, { tree: true })!;
 		});
 	}
 
+	private appendEvent(
+		noteId: string,
+		type: NoteEventType,
+		input: NoteProvenance,
+		defaults: { actor: string; source: string },
+		extra: Partial<Pick<AppendNoteEvent, "relatedId" | "disposition">> = {},
+	): void {
+		this.events.append({ noteId, type, ...provenance(input, defaults), ...extra });
+	}
+
 	private requireNote(id: string): Artifact {
 		const artifact = this.artifacts.get(id);
 		if (!artifact || artifact.kind !== "doc" || artifact.subtype !== NOTE_SUBTYPE) throw new Error(`note "${id}" not found`);

package/src/ops.ts

@@ -391,10 +391,10 @@ export function restoreArtifact(db: Db, id: string, context?: ArtifactEventConte
  * Deletes, in FK-safe order, every row across every table that can reference artifacts(id)
  * (see the grep-verified list in domain/artifact-trash.ts's design comment): edges (both
  * directions), task_focus, task_scopes, task_views (by root_task_id), graph_projection_
- * identities, artifact_scopes, then task_events and artifact_events -- the latter two
- * succeed only because the artifact_trash row placed here by trashArtifact still exists
- * with an elapsed purge_after, which is exactly what db.ts's task_events_no_delete /
- * artifact_events_no_delete trigger carve-outs check themselves. Only THEN artifact_trash's
+ * identities, artifact_scopes, then task_events, note_events, and artifact_events -- the
+ * latter three succeed only because the artifact_trash row placed here by trashArtifact
+ * still exists with an elapsed purge_after, which is exactly what db.ts's task_events_no_delete /
+ * note_events_no_delete / artifact_events_no_delete trigger carve-outs check themselves. Only THEN artifact_trash's
  * own row (it is itself a child of artifacts via a real FK, so it must go before artifacts,
  * but only after the event tables that depend on its continued presence), and artifacts
  * itself last of all. One artifact at a time in its own transaction, so one failure never
@@ -413,6 +413,7 @@ export function purgeDueArtifacts(db: Db, now: () => string = () => new Date().t
 			db.prepare("DELETE FROM graph_projection_identities WHERE artifact_id = ?").run(id);
 			db.prepare("DELETE FROM artifact_scopes WHERE artifact_id = ?").run(id);
 			db.prepare("DELETE FROM task_events WHERE task_id = ?").run(id);
+			db.prepare("DELETE FROM note_events WHERE note_id = ?").run(id);
 			db.prepare("DELETE FROM artifact_events WHERE artifact_id = ?").run(id);
 			db.prepare("DELETE FROM artifact_trash WHERE artifact_id = ?").run(id);
 			db.prepare("DELETE FROM artifacts WHERE id = ?").run(id);

package/src/ports/note-event-store.ts

@@ -0,0 +1,38 @@
+import {
+	normalizeNoteHistoryQuery,
+	validateNoteEvent,
+	type AppendNoteEvent,
+	type NoteEvent,
+	type NoteHistoryPage,
+	type NoteHistoryQuery,
+} from "../domain/note-event.ts";
+
+export interface NoteEventStore {
+	append(event: AppendNoteEvent): NoteEvent;
+	history(noteId: string, query?: NoteHistoryQuery): NoteHistoryPage;
+}
+
+export class InMemoryNoteEventStore implements NoteEventStore {
+	private events: NoteEvent[] = [];
+	private nextId = 1;
+
+	append(event: AppendNoteEvent): NoteEvent {
+		const stored: NoteEvent = {
+			...validateNoteEvent(event),
+			id: this.nextId++,
+			occurredAt: new Date().toISOString(),
+			schemaVersion: 1,
+		};
+		this.events.push(stored);
+		return stored;
+	}
+
+	history(noteId: string, query: NoteHistoryQuery = {}): NoteHistoryPage {
+		const { direction, limit, cursor } = normalizeNoteHistoryQuery(query);
+		const ordered = this.events
+			.filter((event) => event.noteId === noteId && (cursor === undefined || (direction === "desc" ? event.id < cursor : event.id > cursor)))
+			.sort((left, right) => direction === "desc" ? right.id - left.id : left.id - right.id);
+		const events = ordered.slice(0, limit);
+		return { events, ...(ordered.length > limit ? { nextCursor: events.at(-1)!.id } : {}) };
+	}
+}

package/src/service.ts

@@ -8,6 +8,7 @@ import { SQLiteGraphProjectionStore } from "./adapters/sqlite-graph-projection-s
 import { SQLiteTaskFocusStore } from "./adapters/sqlite-task-focus-store.ts";
 import { SQLiteTaskLeaseStore } from "./adapters/sqlite-task-lease-store.ts";
 import { SQLiteTaskEventStore } from "./adapters/sqlite-task-event-store.ts";
+import { SQLiteNoteEventStore } from "./adapters/sqlite-note-event-store.ts";
 import { SQLiteTaskScopeStore } from "./adapters/sqlite-task-scope-store.ts";
 import { SQLiteSessionIdentityStore } from "./adapters/sqlite-session-identity-store.ts";
 import type { CreateArtifactInput } from "./domain/artifact.ts";
@@ -381,6 +382,7 @@ function handlers(
 		"notes.capture": forwardToModule("notes.capture"),
 		"notes.list": forwardToModule("notes.list"),
 		"notes.show": forwardToModule("notes.show"),
+		"notes.history": forwardToModule("notes.history"),
 		"notes.consume": forwardToModule("notes.consume"),
 		"notes.promote": forwardToModule("notes.promote"),
 		"notes.archive": forwardToModule("notes.archive"),
@@ -457,7 +459,8 @@ export function createPapyrusService(path: string): PapyrusService {
 	const scopes = new SQLiteTaskScopeStore(db);
 	const leases = new SQLiteTaskLeaseStore(db);
 	const tasks = new Tasks(artifacts, gates, focus, events, scopes, leases);
-	const notes = new Notes(artifacts);
+	const noteEvents = new SQLiteNoteEventStore(db);
+	const notes = new Notes(artifacts, noteEvents);
 	const projections = new SQLiteGraphProjectionStore(db);
 	const artifactScopes = new SQLiteArtifactScopeStore(db);
 	const logs = new Logs(new SQLiteLogStore(db));