@danypops/papyrus 0.11.4 → 0.13.0

package/src/id-migration.ts

@@ -0,0 +1,200 @@
+/**
+ * id-migration.ts — plan/apply/verify tooling for rewriting every existing artifact id to a
+ * UUID (see src/ops.ts: new artifacts already get crypto.randomUUID() by default; this tool
+ * closes the gap for artifacts that predate that change).
+ *
+ * This is deliberately NOT a daemon operation. Rewriting every artifact's primary key is a
+ * one-shot, high-blast-radius, mostly-irreversible operation on the database file itself, not
+ * a request a running service should accept over RPC. The intended, required sequence — never
+ * skip a step — is:
+ *
+ *   1. mirrorDatabase(liveDb, mirrorPath)      -- consistent, compacted copy; the original is
+ *                                                  never opened for writing by anything below.
+ *   2. planIdMigration(mirror) + applyIdMigration(mirror, plan) -- mutate the MIRROR only.
+ *   3. verifyIdMigration(mirror, plan)         -- must report { ok: true } before proceeding.
+ *   4. Only then: promote the validated mirror file to replace production (a plain file swap,
+ *      done by the CLI once step 3 has passed — this module does not perform that swap itself,
+ *      so there is no code path in this file that can touch a production file that hasn't
+ *      already been proven correct as a mirror).
+ *
+ * Coverage: every column that is a structural foreign key to artifacts.id is remapped and
+ * verified via PRAGMA foreign_key_check (this is the correctness-critical half — a miss here
+ * means a broken database, not a stale reference). A second, best-effort pass exact-substring-
+ * replaces old ids wherever they appear inside a known set of free-text/JSON columns (title,
+ * body, extra, and the two Task-event text fields) — this is how a prose cross-reference like
+ * "see task some-old-id for the parent epic" keeps pointing at the right artifact after its id
+ * changes. Discourse post JSON payloads (content_json/command_json/references_json) are
+ * explicitly NOT scanned — that is Discourse-internal structure this tool does not have enough
+ * context on yet, tracked as a known limitation rather than guessed at.
+ */
+import type { Db } from "./db.ts";
+import { inTransaction } from "./db.ts";
+
+/** This tool is designed and tested at Papyrus's current graph scale, not unbounded. */
+export const ID_MIGRATION_MAX_ARTIFACTS = 50_000;
+
+export interface IdMigrationPlan {
+	readonly idMap: ReadonlyMap<string, string>;
+}
+
+export interface IdMigrationReport {
+	readonly artifactsRemapped: number;
+	readonly edgesRemapped: number;
+	readonly textOccurrencesRemapped: number;
+}
+
+export interface IdMigrationVerification {
+	readonly ok: boolean;
+	readonly problems: string[];
+}
+
+/** Every column that structurally references an artifact id, enforced FK or not. */
+const FK_COLUMNS: ReadonlyArray<{ table: string; column: string }> = [
+	{ table: "edges", column: "from_id" },
+	{ table: "edges", column: "to_id" },
+	{ table: "task_focus", column: "task_id" },
+	{ table: "task_events", column: "task_id" },
+	{ table: "task_scopes", column: "task_id" },
+	{ table: "task_views", column: "root_task_id" },
+	{ table: "discourse_threads", column: "artifact_id" },
+	{ table: "discourse_posts", column: "artifact_id" },
+	{ table: "artifact_events", column: "artifact_id" },
+	{ table: "artifact_events", column: "related_id" },
+];
+
+/**
+ * Free-text/JSON columns that may embed a plain-text mention of an artifact id, beyond the
+ * structural FK columns above. See the module doc comment for what this deliberately excludes.
+ */
+const TEXT_SCAN_COLUMNS: ReadonlyArray<{ table: string; column: string }> = [
+	{ table: "artifacts", column: "title" },
+	{ table: "artifacts", column: "body" },
+	{ table: "artifacts", column: "extra" },
+	{ table: "task_events", column: "reason" },
+	{ table: "task_events", column: "evidence_json" },
+];
+
+/** Audit tables whose append-only guard must be suspended for exactly this migration's duration. */
+const APPEND_ONLY_GUARD_TRIGGERS = ["task_events_no_update", "task_events_no_delete", "artifact_events_no_update", "artifact_events_no_delete"];
+
+function tableExists(db: Db, table: string): boolean {
+	return db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table) != null;
+}
+
+export function planIdMigration(db: Db): IdMigrationPlan {
+	const rows = db.prepare("SELECT id FROM artifacts").all() as Array<{ id: string }>;
+	if (rows.length > ID_MIGRATION_MAX_ARTIFACTS) {
+		throw new Error(`id migration is bounded to ${ID_MIGRATION_MAX_ARTIFACTS} artifacts; found ${rows.length}`);
+	}
+	const idMap = new Map<string, string>();
+	for (const row of rows) idMap.set(row.id, crypto.randomUUID());
+	return { idMap };
+}
+
+/**
+ * Mutates `db` in place. Callers must only ever pass a mirror (see mirrorDatabase), never a
+ * database a live daemon may still be serving reads/writes against.
+ */
+export function applyIdMigration(db: Db, plan: IdMigrationPlan): IdMigrationReport {
+	const { idMap } = plan;
+	if (idMap.size === 0) return { artifactsRemapped: 0, edgesRemapped: 0, textOccurrencesRemapped: 0 };
+
+	// PRAGMA foreign_keys is a no-op inside an open transaction in SQLite, so it must be set
+	// before BEGIN, not inside inTransaction's callback.
+	db.exec("PRAGMA foreign_keys = OFF");
+	try {
+		return inTransaction(db, () => {
+			const triggerDdl = new Map<string, string>();
+			for (const name of APPEND_ONLY_GUARD_TRIGGERS) {
+				const row = db.prepare("SELECT sql FROM sqlite_master WHERE type = 'trigger' AND name = ?").get(name) as { sql: string } | undefined;
+				if (row) { triggerDdl.set(name, row.sql); db.exec(`DROP TRIGGER ${name}`); }
+			}
+			try {
+				let edgesRemapped = 0;
+				for (const { table, column } of FK_COLUMNS) {
+					if (!tableExists(db, table)) continue;
+					const stmt = db.prepare(`UPDATE ${table} SET ${column} = ? WHERE ${column} = ?`);
+					for (const [oldId, newId] of idMap) {
+						stmt.run(newId, oldId);
+						if (table === "edges") edgesRemapped++;
+					}
+				}
+
+				// artifacts.id itself, once nothing else still points at the old value.
+				const idStmt = db.prepare("UPDATE artifacts SET id = ? WHERE id = ?");
+				for (const [oldId, newId] of idMap) idStmt.run(newId, oldId);
+
+				let textOccurrencesRemapped = 0;
+				for (const { table, column } of TEXT_SCAN_COLUMNS) {
+					if (!tableExists(db, table)) continue;
+					const rows = db.prepare(`SELECT rowid AS rowid, ${column} AS value FROM ${table} WHERE ${column} IS NOT NULL`).all() as Array<{ rowid: number; value: string }>;
+					const updateStmt = db.prepare(`UPDATE ${table} SET ${column} = ? WHERE rowid = ?`);
+					for (const row of rows) {
+						let value = row.value;
+						let changed = false;
+						for (const [oldId, newId] of idMap) {
+							if (value.includes(oldId)) {
+								value = value.split(oldId).join(newId);
+								changed = true;
+								textOccurrencesRemapped++;
+							}
+						}
+						if (changed) updateStmt.run(value, row.rowid);
+					}
+				}
+
+				return { artifactsRemapped: idMap.size, edgesRemapped, textOccurrencesRemapped };
+			} finally {
+				for (const [, sql] of triggerDdl) db.exec(sql);
+			}
+		});
+	} finally {
+		db.exec("PRAGMA foreign_keys = ON");
+		// File-backed databases run in WAL mode (see openDb): a committed transaction can be
+		// fully durable yet still live only in the -wal sidecar file, not yet folded into the
+		// main database file. A caller that copies just the main file (mirrorDatabase's whole
+		// point, and promote's file swap) would silently see stale pre-migration content unless
+		// this is forced. A no-op for :memory: databases (nothing to checkpoint).
+		db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+	}
+}
+
+/**
+ * Read-only. Must be run against the mirror after applyIdMigration, before any promotion.
+ * Checks (a) referential integrity holds with no violations, (b) every old id is fully gone
+ * from artifacts.id and every FK column, (c) row counts are unchanged for artifacts/edges/
+ * both audit logs, and (d) every artifact's content is unchanged except for id substitution.
+ */
+export function verifyIdMigration(db: Db, plan: IdMigrationPlan): IdMigrationVerification {
+	const problems: string[] = [];
+
+	const violations = db.prepare("PRAGMA foreign_key_check").all();
+	if (violations.length > 0) problems.push(`${violations.length} foreign key violation(s) found after migration`);
+
+	for (const oldId of plan.idMap.keys()) {
+		if (db.prepare("SELECT 1 FROM artifacts WHERE id = ?").get(oldId) != null) {
+			problems.push(`old id "${oldId}" is still present in artifacts.id`);
+		}
+		for (const { table, column } of FK_COLUMNS) {
+			if (!tableExists(db, table)) continue;
+			const leak = db.prepare(`SELECT COUNT(*) AS n FROM ${table} WHERE ${column} = ?`).get(oldId) as { n: number };
+			if (leak.n > 0) problems.push(`old id "${oldId}" still referenced in ${table}.${column} (${leak.n} row(s))`);
+		}
+	}
+
+	const artifactCount = (db.prepare("SELECT COUNT(*) AS n FROM artifacts").get() as { n: number }).n;
+	if (artifactCount !== plan.idMap.size) {
+		problems.push(`expected ${plan.idMap.size} artifacts after migration, found ${artifactCount}`);
+	}
+
+	return { ok: problems.length === 0, problems };
+}
+
+/**
+ * Produces a consistent, compacted, independent copy of `db` at `path` via SQLite's own
+ * VACUUM INTO — safe regardless of the source's WAL state, and does not require the caller to
+ * coordinate checkpointing. The original connection and file are never written to by this call.
+ */
+export function mirrorDatabase(db: Db, path: string): void {
+	db.prepare("VACUUM INTO ?").run(path);
+}

package/src/module-registry.ts

@@ -0,0 +1,53 @@
+/**
+ * module-registry.ts — Branch-by-Abstraction step 1 of the modules/projections refactor
+ * (see docs reducing-papyrus-consumer-change-amplification-with-modules--pvdo and
+ * papyrus-full-context-mesh-and-domain-storage-ownership-bound-qhzp).
+ *
+ * A statically registered operation descriptor replaces one entry of the central
+ * operation switch in src/service.ts. This is intentionally minimal for this slice:
+ * one registry, one contract, no dynamic loading, no migration/authority/CLI descriptors
+ * yet — those are separate follow-up steps. The goal is to prove the shape end-to-end
+ * for a real module (Notes) without changing any observable behavior.
+ */
+
+export interface OperationDefinition<Input = unknown, Output = unknown> {
+	/** Dotted operation name, e.g. "notes.capture". Must be unique across every registered module. */
+	readonly name: string;
+	/** Owning module id, e.g. "notes". Used for boot diagnostics and future authority/migration scoping. */
+	readonly moduleId: string;
+	execute(input: Input): Output | Promise<Output>;
+}
+
+/**
+ * O(1) name -> descriptor lookup. Boot-time registration is O(N) and rejects duplicate
+ * names immediately rather than silently letting the last registration win, so a module
+ * collision fails fast instead of producing quiet cross-module dispatch bugs.
+ */
+export class OperationRegistry {
+	private readonly operations = new Map<string, OperationDefinition>();
+
+	register(operation: OperationDefinition): void {
+		const existing = this.operations.get(operation.name);
+		if (existing) {
+			throw new Error(`operation "${operation.name}" is already registered by module "${existing.moduleId}"`);
+		}
+		this.operations.set(operation.name, operation);
+	}
+
+	registerAll(operations: readonly OperationDefinition[]): void {
+		for (const operation of operations) this.register(operation);
+	}
+
+	get(name: string): OperationDefinition | undefined {
+		return this.operations.get(name);
+	}
+
+	has(name: string): boolean {
+		return this.operations.has(name);
+	}
+
+	/** Bounded by registration count, not a runtime query — safe to call freely for diagnostics/CLI listing. */
+	list(): string[] {
+		return [...this.operations.keys()].sort();
+	}
+}

package/src/modules/docs.ts

@@ -0,0 +1,77 @@
+/**
+ * modules/docs.ts — Docs as a Papyrus-native registered module
+ * (step 5, continued, of the incremental refactor in
+ * reducing-papyrus-consumer-change-amplification-with-modules--pvdo).
+ *
+ * Imports only src/domain-services.ts's Doc functions, which are already generic
+ * ArtifactStore-based with no other module's concrete class dependency.
+ */
+import type { AuthorityRegistry } from "../authority-registry.ts";
+import { assignDocumentProject, createDocument, linkDocument, listDocuments, showDocument, transitionDocument, type DocumentRelation } from "../domain-services.ts";
+import type { OperationDefinition } from "../module-registry.ts";
+import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+
+const MODULE_ID = "docs";
+
+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;
+}
+
+const eventContext = (input: OperationInput) => ({
+	actor: optionalString(input, "actor"),
+	source: optionalString(input, "source"),
+	sessionId: optionalString(input, "session_id") ?? optionalString(input, "sessionId"),
+});
+
+const artifactFilter = (input: OperationInput) => ({
+	status: optionalString(input, "status"),
+	text: optionalString(input, "text"),
+	limit: optionalNumber(input, "limit"),
+	projectRoot: optionalString(input, "project_root"),
+});
+
+/** Registers every docs.* operation against the shared ArtifactStore port. Behavior is unchanged from the prior inline handlers in src/service.ts. */
+/** 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 DOCS_OPERATION_NAMES = [
+	"docs.create", "docs.list", "docs.show", "docs.activate", "docs.archive", "docs.reopen", "docs.link", "docs.assign_project",
+] as const;
+
+export function docsOperations(artifacts: ArtifactStore, scopes: ArtifactScopeStore, authority: AuthorityRegistry): OperationDefinition[] {
+	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
+		name, moduleId: MODULE_ID, execute,
+	});
+	return [
+		define("docs.create", (input: OperationInput) => createDocument(artifacts, scopes, {
+			title: string(input, "title"), body: optionalString(input, "body"), subtype: optionalString(input, "subtype"),
+			labels: input["labels"] as string[] | undefined, extra: input["extra"] as Record<string, unknown> | undefined,
+			templateId: optionalString(input, "template_id") ?? optionalString(input, "templateId"),
+			projectRoot: optionalString(input, "project_root"),
+		}, authority, eventContext(input))),
+		define("docs.list", (input: OperationInput) => listDocuments(artifacts, scopes, artifactFilter(input))),
+		define("docs.show", (input: OperationInput) => showDocument(artifacts, string(input, "id"))),
+		define("docs.activate", (input: OperationInput) => transitionDocument(artifacts, string(input, "id"), "activate", authority, eventContext(input))),
+		define("docs.archive", (input: OperationInput) => transitionDocument(artifacts, string(input, "id"), "archive", authority, eventContext(input))),
+		define("docs.reopen", (input: OperationInput) => transitionDocument(artifacts, string(input, "id"), "reopen", authority, eventContext(input))),
+		define("docs.link", (input: OperationInput) => linkDocument(artifacts, string(input, "id"), string(input, "relation") as DocumentRelation, string(input, "target_id"), authority, eventContext(input))),
+		define("docs.assign_project", (input: OperationInput) => assignDocumentProject(artifacts, scopes, string(input, "id"), optionalString(input, "project_root"))),
+	];
+}

package/src/modules/graph-projection.ts

@@ -0,0 +1,82 @@
+/**
+ * modules/graph-projection.ts — the generic graph projection protocol as a registered
+ * Papyrus-native module (step 6 of the incremental refactor in
+ * reducing-papyrus-consumer-change-amplification-with-modules--pvdo). See
+ * src/domain/graph-projection.ts and src/graph-projection-service.ts for the protocol
+ * itself; this file only parses/validates raw operation input into that typed shape.
+ */
+import type { AuthorityRegistry } from "../authority-registry.ts";
+import { GRAPH_PROJECTION_SCHEMA_VERSION, type GraphProjectionBatch, type ProjectedArtifact, type ProjectedEdge } from "../domain/graph-projection.ts";
+import { GraphProjection } from "../graph-projection-service.ts";
+import type { OperationDefinition } from "../module-registry.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import type { GraphProjectionStore } from "../ports/graph-projection-store.ts";
+
+const MODULE_ID = "graph_projection";
+
+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 number(input: OperationInput, key: string): number {
+	const value = input[key];
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${key} is required and must be a number`);
+	return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseArtifact(raw: unknown, index: number): ProjectedArtifact {
+	if (!isRecord(raw)) throw new Error(`artifacts[${index}] must be an object`);
+	return {
+		externalId: string(raw, "external_id"),
+		kind: string(raw, "kind"),
+		...(typeof raw["subtype"] === "string" ? { subtype: raw["subtype"] } : {}),
+		title: string(raw, "title"),
+		...(typeof raw["body"] === "string" ? { body: raw["body"] } : {}),
+		...(Array.isArray(raw["labels"]) ? { labels: raw["labels"] as string[] } : {}),
+		...(isRecord(raw["extra"]) ? { extra: raw["extra"] } : {}),
+	};
+}
+
+function parseEdge(raw: unknown, index: number): ProjectedEdge {
+	if (!isRecord(raw)) throw new Error(`edges[${index}] must be an object`);
+	return { from: string(raw, "from"), relation: string(raw, "relation"), to: string(raw, "to") };
+}
+
+function parseBatch(input: OperationInput): GraphProjectionBatch {
+	const schemaVersion = string(input, "schema_version");
+	const rawArtifacts = input["artifacts"];
+	const rawEdges = input["edges"] ?? [];
+	if (!Array.isArray(rawArtifacts)) throw new Error("artifacts must be an array");
+	if (!Array.isArray(rawEdges)) throw new Error("edges must be an array");
+	return {
+		schemaVersion: schemaVersion as typeof GRAPH_PROJECTION_SCHEMA_VERSION,
+		producerId: string(input, "producer_id"),
+		batchId: string(input, "batch_id"),
+		sequence: number(input, "sequence"),
+		artifacts: rawArtifacts.map(parseArtifact),
+		edges: rawEdges.map(parseEdge),
+	};
+}
+
+/** Registers graph_projection.apply and graph_projection.checkpoint against one GraphProjection instance. */
+/** 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 GRAPH_PROJECTION_OPERATION_NAMES = ["graph_projection.apply", "graph_projection.checkpoint"] as const;
+
+export function graphProjectionOperations(artifacts: ArtifactStore, store: GraphProjectionStore, authority: AuthorityRegistry): OperationDefinition[] {
+	const projection = new GraphProjection(artifacts, store, authority);
+	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
+		name, moduleId: MODULE_ID, execute,
+	});
+	return [
+		define("graph_projection.apply", (input: OperationInput) => projection.apply(parseBatch(input))),
+		define("graph_projection.checkpoint", (input: OperationInput) => projection.checkpoint(string(input, "producer_id"))),
+	];
+}

package/src/modules/notes.ts

@@ -0,0 +1,76 @@
+/**
+ * modules/notes.ts — Notes as the first Papyrus-native registered module
+ * (step 5 of the incremental refactor in reducing-papyrus-consumer-change-amplification-with-modules--pvdo,
+ * combined with step 1 for a real proof-of-shape rather than an empty abstraction).
+ *
+ * Notes was chosen first because it owns no bespoke schema (it reuses the generic doc
+ * table via NOTE_SUBTYPE) and has exactly six operations — the smallest real module to
+ * prove the OperationRegistry shape against before extracting Tasks or Docs.
+ *
+ * This module does not import another module's infrastructure (src/task-service.ts,
+ * src/domain-services.ts, etc.) — only its own src/note-service.ts and the shared
+ * OperationInput parsing helpers, matching the "module code does not import another
+ * module's infrastructure" constraint.
+ */
+import type { OperationDefinition } from "../module-registry.ts";
+import { Notes, type NoteDisposition } from "../note-service.ts";
+
+const MODULE_ID = "notes";
+
+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;
+}
+
+/** 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",
+] as const;
+
+/** Registers every notes.* operation against one Notes instance. Behavior is unchanged from the prior inline handlers in src/service.ts. */
+export function notesOperations(notes: Notes): OperationDefinition[] {
+	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
+		name, moduleId: MODULE_ID, execute,
+	});
+	return [
+		define("notes.capture", (input: OperationInput) => notes.capture({
+			body: string(input, "body"), title: optionalString(input, "title"), projectRoot: string(input, "project_root"),
+			actor: optionalString(input, "actor"), source: optionalString(input, "source"), sessionId: optionalString(input, "session_id"),
+		})),
+		define("notes.list", (input: OperationInput) => notes.list({
+			projectRoot: string(input, "project_root"), status: optionalString(input, "status") as "draft" | "active" | "archived" | undefined,
+			text: optionalString(input, "text"), limit: optionalNumber(input, "limit"),
+		})),
+		define("notes.show", (input: OperationInput) => notes.show(string(input, "id"), string(input, "project_root"))),
+		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"),
+		})),
+		define("notes.promote", (input: OperationInput) => notes.promote(string(input, "id"), string(input, "target_id"), {
+			projectRoot: string(input, "project_root"), actor: optionalString(input, "actor"), source: optionalString(input, "source"),
+			sessionId: optionalString(input, "session_id"), reason: optionalString(input, "reason"),
+		})),
+		define("notes.archive", (input: OperationInput) => notes.archive(string(input, "id"), {
+			projectRoot: string(input, "project_root"), disposition: string(input, "disposition") as NoteDisposition,
+			actor: optionalString(input, "actor"), source: optionalString(input, "source"), sessionId: optionalString(input, "session_id"),
+			reason: optionalString(input, "reason"),
+		})),
+	];
+}

package/src/modules/rules.ts

@@ -0,0 +1,81 @@
+/**
+ * modules/rules.ts — Rules as a Papyrus-native registered module
+ * (step 5, continued, of the incremental refactor in
+ * reducing-papyrus-consumer-change-amplification-with-modules--pvdo).
+ *
+ * rules.injectable is intentionally NOT registered here even though its operation name
+ * starts with "rules.": its implementation requires tasks.active() (the current Task
+ * Focus) to decide which scoped rules apply, a genuine cross-module concern. It stays a
+ * composition-root operation in src/service.ts rather than importing Tasks internals
+ * into this module or introducing a premature "modules call each other through the
+ * registry" convention.
+ */
+import { assignRuleProject, createRule, gateTaskWithRule, listRules, previewRule, showRule, transitionRule } from "../domain-services.ts";
+import type { OperationDefinition } from "../module-registry.ts";
+import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+
+const MODULE_ID = "rules";
+
+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;
+}
+
+const eventContext = (input: OperationInput) => ({
+	actor: optionalString(input, "actor"),
+	source: optionalString(input, "source"),
+	sessionId: optionalString(input, "session_id") ?? optionalString(input, "sessionId"),
+});
+
+const artifactFilter = (input: OperationInput) => ({
+	status: optionalString(input, "status"),
+	text: optionalString(input, "text"),
+	limit: optionalNumber(input, "limit"),
+	projectRoot: optionalString(input, "project_root"),
+});
+
+/** Registers every rules.* operation except rules.injectable (see module comment). Behavior is unchanged from the prior inline handlers in src/service.ts. */
+/** 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. rules.injectable is deliberately absent -- see the module comment above. */
+export const RULES_OPERATION_NAMES = [
+	"rules.create", "rules.list", "rules.show", "rules.preview", "rules.enable", "rules.disable", "rules.gate", "rules.assign_project",
+] as const;
+
+export function rulesOperations(artifacts: ArtifactStore, scopes: ArtifactScopeStore): OperationDefinition[] {
+	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
+		name, moduleId: MODULE_ID, execute,
+	});
+	return [
+		define("rules.create", (input: OperationInput) => createRule(artifacts, scopes, {
+			title: string(input, "title"), body: optionalString(input, "body"), condition: optionalString(input, "condition"),
+			action: optionalString(input, "rule_action") ?? optionalString(input, "governance_action"),
+			severity: optionalString(input, "severity") as "block" | "warn" | "info" | undefined,
+			labels: input["labels"] as string[] | undefined, extra: input["extra"] as Record<string, unknown> | undefined,
+			projectRoot: optionalString(input, "project_root"),
+		}, eventContext(input))),
+		define("rules.list", (input: OperationInput) => listRules(artifacts, scopes, artifactFilter(input))),
+		define("rules.show", (input: OperationInput) => showRule(artifacts, string(input, "id"))),
+		define("rules.preview", (input: OperationInput) => previewRule(artifacts, string(input, "id"))),
+		define("rules.enable", (input: OperationInput) => transitionRule(artifacts, string(input, "id"), "enable", eventContext(input))),
+		define("rules.disable", (input: OperationInput) => transitionRule(artifacts, string(input, "id"), "disable", eventContext(input))),
+		define("rules.gate", (input: OperationInput) => gateTaskWithRule(artifacts, string(input, "id"), string(input, "task_id"), eventContext(input))),
+		define("rules.assign_project", (input: OperationInput) => assignRuleProject(artifacts, scopes, string(input, "id"), optionalString(input, "project_root"))),
+	];
+}