@danypops/papyrus 0.11.3 → 0.12.0

package/src/domain-services.ts

@@ -1,12 +1,51 @@
+import { ARTIFACT_SCOPE_MAX_ARTIFACTS } from "./constants.ts";
 import type { Artifact, CreateArtifactInput } from "./domain/artifact.ts";
+import type { ArtifactEventContext } from "./domain/artifact-event.ts";
+import { normalizeProjectRoot } from "./domain/task-scope.ts";
 import { validateSkillDefinition } from "./domain/skill-definition.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
+import type { ArtifactScopeStore } from "./ports/artifact-scope-store.ts";
 import { NOTE_SUBTYPE } from "./note-service.ts";
+import type { AuthorityRegistry } from "./authority-registry.ts";
 
 export interface ListFilter {
 	status?: string;
 	text?: string;
 	limit?: number;
+	/** When supplied, results are limited to artifacts scoped to this project (or the unscoped bucket, for an empty string is not accepted -- use assignArtifactProject's own validation). */
+	projectRoot?: string;
+}
+
+/**
+ * Shared by listDocuments/listRules/listSkills: when filter.projectRoot is given, resolve
+ * via ArtifactScopeStore first and post-filter by kind/status/text (mirrors Tasks.list's
+ * established scoped-listing shape); otherwise fall back to the existing unscoped query
+ * path unchanged, so every caller that predates project scoping keeps working exactly as
+ * before.
+ */
+function listScoped(artifacts: ArtifactStore, scopes: ArtifactScopeStore, kind: string, filter: ListFilter, excludeSubtype?: string): Artifact[] {
+	if (filter.projectRoot === undefined) return artifacts.query({ kind, excludeSubtype, status: filter.status, text: filter.text, limit: filter.limit });
+	const limit = filter.limit ?? ARTIFACT_SCOPE_MAX_ARTIFACTS;
+	if (!Number.isInteger(limit) || limit < 1 || limit > ARTIFACT_SCOPE_MAX_ARTIFACTS) {
+		throw new Error(`list limit must be between 1 and ${ARTIFACT_SCOPE_MAX_ARTIFACTS}`);
+	}
+	const projectRoot = normalizeProjectRoot(filter.projectRoot);
+	const ids = scopes.ids(projectRoot, ARTIFACT_SCOPE_MAX_ARTIFACTS);
+	const text = filter.text?.toLowerCase();
+	return ids
+		.map((id) => artifacts.get(id))
+		.filter((artifact): artifact is Artifact => artifact?.kind === kind && artifact.subtype !== excludeSubtype)
+		.filter((artifact) => filter.status === undefined || artifact.status === filter.status)
+		.filter((artifact) => text === undefined || artifact.title.toLowerCase().includes(text) || artifact.body.toLowerCase().includes(text))
+		.sort((left, right) => right.updated_at.localeCompare(left.updated_at) || left.id.localeCompare(right.id))
+		.slice(0, limit);
+}
+
+/** Shared by assignDocumentProject/assignRuleProject/assignSkillProject. */
+function assignArtifactProject(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string, kind: string, projectRoot: string | undefined): Artifact {
+	requireKind(artifacts, id, kind);
+	scopes.assign(id, projectRoot === undefined ? undefined : normalizeProjectRoot(projectRoot), projectRoot === undefined ? "unscoped" : "explicit");
+	return artifacts.get(id)!;
 }
 
 function requireKind(artifacts: ArtifactStore, id: string, kind: string): Artifact {
@@ -25,10 +64,25 @@ function rejectsNoteTemplate(artifacts: ArtifactStore, templateId: string | unde
 		&& (defaults as Record<string, unknown>)["subtype"] === NOTE_SUBTYPE;
 }
 
-function requireNotesFacade(): never {
+/** caller never owns NOTE_SUBTYPE, so requireArtifactAllowed always throws — the trailing throw only satisfies TypeScript's control-flow analysis for a `never`-returning function. */
+function requireNotesFacade(authority: AuthorityRegistry, caller: string): never {
+	authority.requireArtifactAllowed("doc", NOTE_SUBTYPE, "create", caller);
 	throw new Error("note creation requires notes.capture");
 }
 
+function templateSubtype(artifacts: ArtifactStore, templateId: string | undefined): string | undefined {
+	if (!templateId) return undefined;
+	const defaults = artifacts.get(templateId)?.extra["defaults"];
+	if (typeof defaults !== "object" || defaults === null || Array.isArray(defaults)) return undefined;
+	const subtype = (defaults as Record<string, unknown>)["subtype"];
+	return typeof subtype === "string" ? subtype : undefined;
+}
+
+function requireMutableDocument(document: Artifact, authority: AuthorityRegistry): Artifact {
+	authority.requireArtifactAllowed(document.kind, document.subtype, "status", "docs");
+	return document;
+}
+
 export interface CreateDocumentInput {
 	title: string;
 	body?: string;
@@ -36,6 +90,8 @@ export interface CreateDocumentInput {
 	labels?: string[];
 	extra?: Record<string, unknown>;
 	templateId?: string;
+	/** Optional at creation, unlike Tasks -- omitting it leaves the Doc in the unscoped bucket, matching today's default behavior for every existing caller. */
+	projectRoot?: string;
 }
 
 export type DocumentTransition = "activate" | "archive" | "reopen";
@@ -47,21 +103,35 @@ const DOCUMENT_TRANSITIONS: Record<DocumentTransition, { from: string[]; to: str
 	reopen: { from: ["archived"], to: "draft" },
 };
 
-export function createDocument(artifacts: ArtifactStore, input: CreateDocumentInput): Artifact {
-	if (rejectsNoteTemplate(artifacts, input.templateId, input.subtype)) requireNotesFacade();
-	return artifacts.create({
+export function createDocument(artifacts: ArtifactStore, scopes: ArtifactScopeStore, input: CreateDocumentInput, authority: AuthorityRegistry, context?: ArtifactEventContext): Artifact {
+	if (rejectsNoteTemplate(artifacts, input.templateId, input.subtype)) requireNotesFacade(authority, "docs");
+	authority.requireArtifactAllowed("doc", input.subtype ?? templateSubtype(artifacts, input.templateId), "create", "docs");
+	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
+	const document = artifacts.create({
 		kind: "doc",
+		// Explicit, not defaultStatusFor's "first status row by rowid" fallback -- the same
+		// heuristic that made Task creation non-deterministic on a migrated database. Every
+		// creation path that has no caller-supplied initial status must set one explicitly.
+		status: "draft",
 		title: input.title,
 		body: input.body,
 		subtype: input.subtype,
 		labels: input.labels,
 		extra: input.extra,
 		templateId: input.templateId,
-	});
+	}, context);
+	scopes.assign(document.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
+	return document;
+}
+
+export function listDocuments(artifacts: ArtifactStore, scopes: ArtifactScopeStore, filter: ListFilter): Artifact[] {
+	return listScoped(artifacts, scopes, "doc", filter, NOTE_SUBTYPE);
 }
 
-export function listDocuments(artifacts: ArtifactStore, filter: ListFilter): Artifact[] {
-	return artifacts.query({ kind: "doc", excludeSubtype: NOTE_SUBTYPE, ...filter });
+export function assignDocumentProject(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string, projectRoot: string | undefined): Artifact {
+	requireDocument(artifacts, id); // rejects Notes -- project reassignment for notes goes through notes.* like everything else about them
+	scopes.assign(id, projectRoot === undefined ? undefined : normalizeProjectRoot(projectRoot), projectRoot === undefined ? "unscoped" : "explicit");
+	return artifacts.get(id)!;
 }
 
 function requireDocument(artifacts: ArtifactStore, id: string): Artifact {
@@ -75,17 +145,19 @@ export function showDocument(artifacts: ArtifactStore, id: string): Artifact {
 	return artifacts.get(id, { tree: true })!;
 }
 
-export function transitionDocument(artifacts: ArtifactStore, id: string, action: DocumentTransition): Artifact {
-	const document = requireDocument(artifacts, id);
+export function transitionDocument(artifacts: ArtifactStore, id: string, action: DocumentTransition, authority: AuthorityRegistry, context?: ArtifactEventContext): Artifact {
+	const document = requireMutableDocument(requireDocument(artifacts, id), authority);
 	const transition = DOCUMENT_TRANSITIONS[action];
 	if (!transition.from.includes(document.status)) throw new Error(`cannot ${action} document from ${document.status}`);
-	return artifacts.setStatus(id, transition.to)!;
+	return artifacts.setStatus(id, transition.to, context)!;
 }
 
-export function linkDocument(artifacts: ArtifactStore, id: string, relation: DocumentRelation, targetId: string): Artifact {
-	requireDocument(artifacts, id);
-	if (!artifacts.get(targetId)) throw new Error(`target artifact "${targetId}" not found`);
-	artifacts.link({ from: id, relation, to: targetId });
+export function linkDocument(artifacts: ArtifactStore, id: string, relation: DocumentRelation, targetId: string, authority: AuthorityRegistry, context?: ArtifactEventContext): Artifact {
+	requireMutableDocument(requireDocument(artifacts, id), authority);
+	const target = artifacts.get(targetId);
+	if (!target) throw new Error(`target artifact "${targetId}" not found`);
+	requireMutableDocument(target, authority);
+	artifacts.link({ from: id, relation, to: targetId }, context);
 	return showDocument(artifacts, id);
 }
 
@@ -97,13 +169,16 @@ export interface CreateRuleInput {
 	severity?: "block" | "warn" | "info";
 	labels?: string[];
 	extra?: Record<string, unknown>;
+	projectRoot?: string;
 }
 
 export type RuleTransition = "enable" | "disable";
 
-export function createRule(artifacts: ArtifactStore, input: CreateRuleInput): Artifact {
-	return artifacts.create({
+export function createRule(artifacts: ArtifactStore, scopes: ArtifactScopeStore, input: CreateRuleInput, context?: ArtifactEventContext): Artifact {
+	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
+	const rule = artifacts.create({
 		kind: "rule",
+		status: "active", // explicit; see createDocument for why defaultStatusFor is not trusted here
 		title: input.title,
 		body: input.body,
 		labels: input.labels,
@@ -113,11 +188,17 @@ export function createRule(artifacts: ArtifactStore, input: CreateRuleInput): Ar
 			...(input.action ? { action: input.action } : {}),
 			severity: input.severity ?? "info",
 		},
-	});
+	}, context);
+	scopes.assign(rule.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
+	return rule;
 }
 
-export function listRules(artifacts: ArtifactStore, filter: ListFilter): Artifact[] {
-	return artifacts.query({ kind: "rule", ...filter });
+export function listRules(artifacts: ArtifactStore, scopes: ArtifactScopeStore, filter: ListFilter): Artifact[] {
+	return listScoped(artifacts, scopes, "rule", filter);
+}
+
+export function assignRuleProject(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string, projectRoot: string | undefined): Artifact {
+	return assignArtifactProject(artifacts, scopes, id, "rule", projectRoot);
 }
 
 /** Global rules always apply; scoped workflow rules apply only while their run owns active focus. */
@@ -144,18 +225,18 @@ export function previewRule(artifacts: ArtifactStore, id: string): string {
 	return `• ${rule.title}${condition}\n  ${action}`;
 }
 
-export function transitionRule(artifacts: ArtifactStore, id: string, action: RuleTransition): Artifact {
+export function transitionRule(artifacts: ArtifactStore, id: string, action: RuleTransition, context?: ArtifactEventContext): Artifact {
 	const rule = requireKind(artifacts, id, "rule");
 	const expected = action === "enable" ? "deprecated" : "active";
 	const target = action === "enable" ? "active" : "deprecated";
 	if (rule.status !== expected) throw new Error(`cannot ${action} rule from ${rule.status}`);
-	return artifacts.setStatus(id, target)!;
+	return artifacts.setStatus(id, target, context)!;
 }
 
-export function gateTaskWithRule(artifacts: ArtifactStore, ruleId: string, taskId: string): Artifact {
+export function gateTaskWithRule(artifacts: ArtifactStore, ruleId: string, taskId: string, context?: ArtifactEventContext): Artifact {
 	requireKind(artifacts, ruleId, "rule");
 	requireKind(artifacts, taskId, "task");
-	artifacts.link({ from: ruleId, relation: "gates", to: taskId });
+	artifacts.link({ from: ruleId, relation: "gates", to: taskId }, context);
 	return showRule(artifacts, ruleId);
 }
 
@@ -168,6 +249,7 @@ export interface CreateSkillInput {
 	definition?: unknown;
 	labels?: string[];
 	extra?: Record<string, unknown>;
+	projectRoot?: string;
 }
 
 export interface CreateArtifactTemplateInput {
@@ -177,18 +259,21 @@ export interface CreateArtifactTemplateInput {
 	required?: string[];
 	body?: string;
 	labels?: string[];
+	projectRoot?: string;
 }
 
 export type SkillTransition = "enable" | "disable";
 
-export function createSkill(artifacts: ArtifactStore, input: CreateSkillInput): Artifact {
+export function createSkill(artifacts: ArtifactStore, scopes: ArtifactScopeStore, input: CreateSkillInput, authority: AuthorityRegistry, context?: ArtifactEventContext): Artifact {
 	if (input.definition !== undefined && (input.trigger !== undefined || input.steps !== undefined || input.tools !== undefined)) {
 		throw new Error("workflow Skill definition cannot be mixed with legacy trigger, steps, or tools");
 	}
 	const definition = input.definition === undefined ? undefined : validateSkillDefinition(input.definition);
-	if (definition?.blueprints.docs.some((document) => document.subtype === NOTE_SUBTYPE)) requireNotesFacade();
-	return artifacts.create({
+	if (definition?.blueprints.docs.some((document) => document.subtype === NOTE_SUBTYPE)) requireNotesFacade(authority, "skills");
+	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
+	const skill = artifacts.create({
 		kind: "skill",
+		status: "active", // explicit; see createDocument for why defaultStatusFor is not trusted here
 		subtype: definition ? "workflow" : undefined,
 		title: input.title,
 		body: input.body,
@@ -200,13 +285,17 @@ export function createSkill(artifacts: ArtifactStore, input: CreateSkillInput):
 			...(input.steps ? { steps: input.steps } : {}),
 			...(input.tools ? { tools: input.tools } : {}),
 		},
-	});
+	}, context);
+	scopes.assign(skill.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
+	return skill;
 }
 
-export function createArtifactTemplate(artifacts: ArtifactStore, input: CreateArtifactTemplateInput): Artifact {
-	if (input.targetKind === "doc" && input.defaults?.["subtype"] === NOTE_SUBTYPE) requireNotesFacade();
-	return artifacts.create({
+export function createArtifactTemplate(artifacts: ArtifactStore, scopes: ArtifactScopeStore, input: CreateArtifactTemplateInput, authority: AuthorityRegistry, context?: ArtifactEventContext): Artifact {
+	if (input.targetKind === "doc" && input.defaults?.["subtype"] === NOTE_SUBTYPE) requireNotesFacade(authority, "skills");
+	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
+	const template = artifacts.create({
 		kind: "skill",
+		status: "active", // explicit; see createDocument for why defaultStatusFor is not trusted here
 		subtype: "artifact-template",
 		title: input.title,
 		body: input.body,
@@ -216,16 +305,22 @@ export function createArtifactTemplate(artifacts: ArtifactStore, input: CreateAr
 			defaults: input.defaults ?? {},
 			required: input.required ?? ["title"],
 		},
-	});
+	}, context);
+	scopes.assign(template.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
+	return template;
+}
+
+export function instantiateTemplate(artifacts: ArtifactStore, templateId: string, input: CreateArtifactInput, authority: AuthorityRegistry, context?: ArtifactEventContext): Artifact {
+	if (rejectsNoteTemplate(artifacts, templateId, input.subtype)) requireNotesFacade(authority, "skills");
+	return artifacts.create({ ...input, templateId }, context);
 }
 
-export function instantiateTemplate(artifacts: ArtifactStore, templateId: string, input: CreateArtifactInput): Artifact {
-	if (rejectsNoteTemplate(artifacts, templateId, input.subtype)) requireNotesFacade();
-	return artifacts.create({ ...input, templateId });
+export function listSkills(artifacts: ArtifactStore, scopes: ArtifactScopeStore, filter: ListFilter): Artifact[] {
+	return listScoped(artifacts, scopes, "skill", filter);
 }
 
-export function listSkills(artifacts: ArtifactStore, filter: ListFilter): Artifact[] {
-	return artifacts.query({ kind: "skill", ...filter });
+export function assignSkillProject(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string, projectRoot: string | undefined): Artifact {
+	return assignArtifactProject(artifacts, scopes, id, "skill", projectRoot);
 }
 
 export function showSkill(artifacts: ArtifactStore, id: string): Artifact {
@@ -261,10 +356,10 @@ export function skillInvocation(artifacts: ArtifactStore, id: string): string {
 	].join("\n");
 }
 
-export function transitionSkill(artifacts: ArtifactStore, id: string, action: SkillTransition): Artifact {
+export function transitionSkill(artifacts: ArtifactStore, id: string, action: SkillTransition, context?: ArtifactEventContext): Artifact {
 	const skill = requireKind(artifacts, id, "skill");
 	const expected = action === "enable" ? "deprecated" : "active";
 	const target = action === "enable" ? "active" : "deprecated";
 	if (skill.status !== expected) throw new Error(`cannot ${action} skill from ${skill.status}`);
-	return artifacts.setStatus(id, target)!;
+	return artifacts.setStatus(id, target, context)!;
 }

package/src/graph-projection-service.ts

@@ -0,0 +1,103 @@
+/**
+ * graph-projection-service.ts — the generic graph projection protocol for external bounded
+ * contexts. See src/domain/graph-projection.ts for the batch/checkpoint shapes and the
+ * documented, deliberate scope limits of this first walking-skeleton slice.
+ */
+import { GRAPH_PROJECTION_ID_MAX_LENGTH, GRAPH_PROJECTION_MAX_ARTIFACTS_PER_BATCH, GRAPH_PROJECTION_MAX_EDGES_PER_BATCH } from "./constants.ts";
+import { GRAPH_PROJECTION_SCHEMA_VERSION, type GraphProjectionBatch, type GraphProjectionResult } from "./domain/graph-projection.ts";
+import type { ArtifactStore } from "./ports/artifact-store.ts";
+import { requireAtomicArtifactStore } from "./ports/atomic-artifact-store.ts";
+import type { GraphProjectionStore } from "./ports/graph-projection-store.ts";
+import type { AuthorityRegistry } from "./authority-registry.ts";
+
+function boundedId(value: string, label: string): string {
+	if (!value || value.length === 0) throw new Error(`${label} is required`);
+	if (value.length > GRAPH_PROJECTION_ID_MAX_LENGTH) throw new Error(`${label} exceeds ${GRAPH_PROJECTION_ID_MAX_LENGTH} characters`);
+	return value;
+}
+
+export class GraphProjection {
+	constructor(
+		private readonly artifacts: ArtifactStore,
+		private readonly store: GraphProjectionStore,
+		private readonly authority: AuthorityRegistry,
+	) {}
+
+	checkpoint(producerId: string) {
+		return this.store.getCheckpoint(boundedId(producerId, "producer_id"));
+	}
+
+	apply(batch: GraphProjectionBatch): GraphProjectionResult {
+		if (batch.schemaVersion !== GRAPH_PROJECTION_SCHEMA_VERSION) {
+			throw new Error(`unsupported graph projection schema version "${batch.schemaVersion}", expected "${GRAPH_PROJECTION_SCHEMA_VERSION}"`);
+		}
+		const producerId = boundedId(batch.producerId, "producer_id");
+		const batchId = boundedId(batch.batchId, "batch_id");
+		if (!Number.isInteger(batch.sequence) || batch.sequence < 1) throw new Error("sequence must be a positive integer");
+		if (batch.artifacts.length > GRAPH_PROJECTION_MAX_ARTIFACTS_PER_BATCH) {
+			throw new Error(`batch is bounded to ${GRAPH_PROJECTION_MAX_ARTIFACTS_PER_BATCH} artifacts; got ${batch.artifacts.length}`);
+		}
+		if (batch.edges.length > GRAPH_PROJECTION_MAX_EDGES_PER_BATCH) {
+			throw new Error(`batch is bounded to ${GRAPH_PROJECTION_MAX_EDGES_PER_BATCH} edges; got ${batch.edges.length}`);
+		}
+		for (const artifact of batch.artifacts) boundedId(artifact.externalId, "artifact externalId");
+		for (const edge of batch.edges) { boundedId(edge.from, "edge from"); boundedId(edge.to, "edge to"); }
+
+		const existingCheckpoint = this.store.getCheckpoint(producerId);
+		if (existingCheckpoint?.lastBatchId === batchId && existingCheckpoint.lastSequence === batch.sequence) {
+			return { producerId, batchId, sequence: batch.sequence, artifactsUpserted: 0, artifactsCreated: 0, edgesUpserted: 0, alreadyApplied: true };
+		}
+		if (existingCheckpoint === null) {
+			if (batch.sequence !== 1) throw new Error(`first batch for producer "${producerId}" must have sequence 1, got ${batch.sequence}`);
+		} else {
+			if (batch.sequence <= existingCheckpoint.lastSequence) {
+				throw new Error(`stale batch: sequence ${batch.sequence} is not after checkpoint sequence ${existingCheckpoint.lastSequence} for producer "${producerId}"`);
+			}
+			if (batch.sequence > existingCheckpoint.lastSequence + 1) {
+				throw new Error(`sequence gap for producer "${producerId}": expected ${existingCheckpoint.lastSequence + 1}, got ${batch.sequence}`);
+			}
+		}
+
+		// Authority up front, before any write: a producer that doesn't own a subtype/relation
+		// it's trying to project into must fail closed, not partially apply then fail midway.
+		for (const artifact of batch.artifacts) this.authority.requireArtifactAllowed(artifact.kind, artifact.subtype, "create", producerId);
+		for (const edge of batch.edges) this.authority.requireRelationAllowed(edge.relation, "link", producerId);
+
+		const atomic = requireAtomicArtifactStore(this.artifacts);
+		let artifactsCreated = 0;
+		let artifactsUpserted = 0;
+		let edgesUpserted = 0;
+		atomic.atomic(() => {
+			for (const projected of batch.artifacts) {
+				const existingId = this.store.resolveIdentity(producerId, projected.externalId);
+				if (existingId) {
+					this.artifacts.updateContent(existingId, { title: projected.title, body: projected.body, labels: projected.labels ? [...projected.labels] : undefined });
+					if (projected.extra !== undefined) this.artifacts.setExtra(existingId, projected.extra);
+				} else {
+					const created = this.artifacts.create({
+						kind: projected.kind,
+						subtype: projected.subtype,
+						title: projected.title,
+						body: projected.body,
+						labels: projected.labels ? [...projected.labels] : undefined,
+						extra: projected.extra,
+					});
+					this.store.recordIdentity(producerId, projected.externalId, created.id);
+					artifactsCreated++;
+				}
+				artifactsUpserted++;
+			}
+			for (const edge of batch.edges) {
+				const fromId = this.store.resolveIdentity(producerId, edge.from);
+				if (!fromId) throw new Error(`edge references unknown externalId "${edge.from}" for producer "${producerId}"`);
+				const toId = this.store.resolveIdentity(producerId, edge.to);
+				if (!toId) throw new Error(`edge references unknown externalId "${edge.to}" for producer "${producerId}"`);
+				this.artifacts.link({ from: fromId, relation: edge.relation, to: toId });
+				edgesUpserted++;
+			}
+			this.store.commitCheckpoint({ producerId, lastSequence: batch.sequence, lastBatchId: batchId, appliedAt: new Date().toISOString() });
+		});
+
+		return { producerId, batchId, sequence: batch.sequence, artifactsUpserted, artifactsCreated, edgesUpserted, alreadyApplied: false };
+	}
+}

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);
+}