@danypops/papyrus 0.11.4 → 0.13.0

package/src/modules/skills.ts

@@ -0,0 +1,113 @@
+/**
+ * modules/skills.ts — Skills as a Papyrus-native registered module
+ * (step 5, continued, of the incremental refactor in
+ * reducing-papyrus-consumer-change-amplification-with-modules--pvdo).
+ *
+ * skills.instantiate is intentionally NOT registered here even though its operation name
+ * starts with "skills.": when the target template's targetKind is "task" it calls
+ * tasks.create() directly instead of the generic instantiateTemplate path — a genuine
+ * cross-module concern, same category as rules.injectable (see modules/rules.ts). It
+ * stays a composition-root operation in src/service.ts.
+ *
+ * skills.run depends on the Task-domain ports (TaskEventStore, TaskScopeStore) as
+ * constructor parameters. These are shared port contracts every module may depend on,
+ * the same way every module already depends on ArtifactStore — not "another module's
+ * infrastructure" in the sense of a concrete class. skill-execution.ts already has this
+ * port dependency pre-existing; untangling it is a separate, larger concern than this
+ * extraction.
+ */
+import type { AuthorityRegistry } from "../authority-registry.ts";
+import { assignSkillProject, createArtifactTemplate, createSkill, listSkills, showSkill, skillInvocation, transitionSkill } 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";
+import type { TaskEventStore } from "../ports/task-event-store.ts";
+import type { TaskScopeStore } from "../ports/task-scope-store.ts";
+import { instantiateSkillWorkflow } from "../skill-execution.ts";
+
+const MODULE_ID = "skills";
+
+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 eventContextFor = (input: OperationInput, source: string) => {
+	const context = eventContext(input);
+	return { ...context, source: context.source ?? source };
+};
+
+const artifactFilter = (input: OperationInput) => ({
+	status: optionalString(input, "status"),
+	text: optionalString(input, "text"),
+	limit: optionalNumber(input, "limit"),
+	projectRoot: optionalString(input, "project_root"),
+});
+
+export interface SkillsModuleDeps {
+	artifacts: ArtifactStore;
+	events: TaskEventStore;
+	scopes: TaskScopeStore;
+	/** Docs/Rules/Skills project scoping (distinct from `scopes`, which is Task-run project scoping for skills.run's materialized blueprint tasks). */
+	artifactScopes: ArtifactScopeStore;
+	authority: AuthorityRegistry;
+}
+
+/** Registers every skills.* operation except skills.instantiate (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. skills.instantiate is deliberately absent -- see the module comment above. */
+export const SKILLS_OPERATION_NAMES = [
+	"skills.create", "skills.create_template", "skills.list", "skills.show", "skills.invoke", "skills.run", "skills.enable", "skills.disable", "skills.assign_project",
+] as const;
+
+export function skillsOperations({ artifacts, events, scopes, artifactScopes, authority }: SkillsModuleDeps): OperationDefinition[] {
+	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
+		name, moduleId: MODULE_ID, execute,
+	});
+	return [
+		define("skills.create", (input: OperationInput) => createSkill(artifacts, artifactScopes, {
+			title: string(input, "title"), body: optionalString(input, "body"), trigger: optionalString(input, "trigger"),
+			steps: input["steps"] as string[] | undefined, tools: input["tools"] as string[] | undefined,
+			definition: input["definition"],
+			labels: input["labels"] as string[] | undefined, extra: input["extra"] as Record<string, unknown> | undefined,
+			projectRoot: optionalString(input, "project_root"),
+		}, authority, eventContext(input))),
+		define("skills.create_template", (input: OperationInput) => createArtifactTemplate(artifacts, artifactScopes, {
+			title: string(input, "title"), targetKind: string(input, "target_kind"), defaults: input["defaults"] as Record<string, unknown> | undefined,
+			required: input["required"] as string[] | undefined, body: optionalString(input, "body"), labels: input["labels"] as string[] | undefined,
+			projectRoot: optionalString(input, "project_root"),
+		}, authority, eventContext(input))),
+		define("skills.list", (input: OperationInput) => listSkills(artifacts, artifactScopes, artifactFilter(input))),
+		define("skills.show", (input: OperationInput) => showSkill(artifacts, string(input, "id"))),
+		define("skills.invoke", (input: OperationInput) => skillInvocation(artifacts, string(input, "id"))),
+		define("skills.run", (input: OperationInput) => instantiateSkillWorkflow(artifacts, string(input, "id"), {
+			runId: optionalString(input, "run_id") ?? optionalString(input, "runId"),
+			arguments: input["arguments"] as Record<string, unknown> | undefined,
+		}, { events, scopes, projectRoot: string(input, "project_root"), context: eventContextFor(input, "skill-run") })),
+		define("skills.enable", (input: OperationInput) => transitionSkill(artifacts, string(input, "id"), "enable", eventContext(input))),
+		define("skills.disable", (input: OperationInput) => transitionSkill(artifacts, string(input, "id"), "disable", eventContext(input))),
+		define("skills.assign_project", (input: OperationInput) => assignSkillProject(artifacts, artifactScopes, string(input, "id"), optionalString(input, "project_root"))),
+	];
+}

package/src/modules/tasks.ts

@@ -0,0 +1,164 @@
+/**
+ * modules/tasks.ts — Tasks as the second Papyrus-native registered module
+ * (step 5, continued, of the incremental refactor in
+ * reducing-papyrus-consumer-change-amplification-with-modules--pvdo).
+ *
+ * Deliberately more representative than modules/notes.ts: Tasks owns real schema
+ * (task_events, task_focus, task_scopes and their migrations, still in src/db.ts for
+ * this slice — module-owned migrations are a separate follow-up,
+ * add-a-module-migration-ledger-keyed-by-moduleid-version-with-3e7k), a much larger
+ * operation surface, and cross-module edges (rules.gate links a rule to a task;
+ * graph.link routes depends_on through Tasks.depend for cycle safety — those two
+ * remain in src/service.ts since they are graph.* / rules.* operations, not tasks.*).
+ *
+ * Task-domain-internal files (task-context.ts, task-execution.ts, domain/task-event.ts,
+ * domain/task-scope.ts) are imported directly — they belong to this bounded context,
+ * unlike a different module's infrastructure. Generic input-parsing helpers are
+ * duplicated locally rather than imported from src/service.ts, matching the precedent
+ * set by modules/notes.ts: a module does not import another module's infrastructure,
+ * including the composition root's own helpers.
+ */
+import type { Checklist } from "../domain/checklist.ts";
+import type { TaskEventContext, TaskEventDirection } from "../domain/task-event.ts";
+import type { TaskViewMode } from "../domain/task-scope.ts";
+import type { OperationDefinition } from "../module-registry.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import { taskContext } from "../task-context.ts";
+import { projectTaskExecution } from "../task-execution.ts";
+import { Tasks, type TaskStatus } from "../task-service.ts";
+
+const MODULE_ID = "tasks";
+
+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 optionalStringArray(input: OperationInput, key: string): string[] | undefined {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) throw new Error(`${key} must be an array of strings`);
+	return value as string[];
+}
+
+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): TaskEventContext => ({
+	actor: optionalString(input, "actor"),
+	source: optionalString(input, "source"),
+	sessionId: optionalString(input, "session_id") ?? optionalString(input, "sessionId"),
+	reason: optionalString(input, "reason"),
+});
+
+const taskFilter = (input: OperationInput) => ({
+	status: optionalString(input, "status"),
+	text: optionalString(input, "text"),
+	limit: optionalNumber(input, "limit"),
+	projectRoot: string(input, "project_root"),
+	scope: optionalString(input, "scope") as TaskViewMode | undefined,
+	rootTaskId: optionalString(input, "root_task_id"),
+	sessionId: optionalString(input, "session_id") ?? optionalString(input, "sessionId"),
+});
+
+/**
+ * Registers every tasks.* operation against one Tasks instance. Behavior is unchanged from
+ * the prior inline handlers in src/service.ts. tasks.context needs the raw ArtifactStore
+ * port directly (taskContext is a plain-artifact query, not a Tasks method), so the
+ * composition root passes the same artifacts port it already constructs Tasks with —
+ * this is not "another module's infrastructure", it is the shared port every module writes
+ * through.
+ */
+/** 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 TASKS_OPERATION_NAMES = [
+	"tasks.create", "tasks.update", "tasks.list", "tasks.graph", "tasks.plan", "tasks.show", "tasks.history",
+	"tasks.scope", "tasks.set_scope", "tasks.assign_project", "tasks.active", "tasks.focused", "tasks.focus",
+	"tasks.pause", "tasks.unpause", "tasks.clear_focus", "tasks.start", "tasks.submit", "tasks.complete",
+	"tasks.run_gates", "tasks.set_checklist", "tasks.context", "tasks.reject", "tasks.retry", "tasks.cancel",
+	"tasks.depend", "tasks.undepend", "tasks.contain", "tasks.uncontain",
+] as const;
+
+export function tasksOperations(tasks: Tasks, artifacts: ArtifactStore): OperationDefinition[] {
+	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
+		name, moduleId: MODULE_ID, execute,
+	});
+	return [
+		define("tasks.create", (input: OperationInput) => tasks.create({
+			title: string(input, "title"),
+			body: optionalString(input, "body"),
+			status: optionalString(input, "status") as TaskStatus | undefined,
+			labels: input["labels"] as string[] | undefined,
+			extra: input["extra"] as Record<string, unknown> | undefined,
+			gates: input["gates"] as Parameters<Tasks["create"]>[0]["gates"],
+			checklist: input["checklist"] as Checklist | undefined,
+			templateId: optionalString(input, "template_id") ?? optionalString(input, "templateId"),
+			parentId: optionalString(input, "parent_id") ?? optionalString(input, "parentId"),
+			dependsOn: (input["depends_on"] ?? input["dependsOn"]) as string[] | undefined,
+			projectRoot: string(input, "project_root"),
+			projectSource: "cwd",
+		}, eventContext(input))),
+		define("tasks.update", (input: OperationInput) => tasks.update(string(input, "id"), {
+			...(input["title"] !== undefined ? { title: optionalString(input, "title")! } : {}),
+			...(input["body"] !== undefined ? { body: optionalString(input, "body")! } : {}),
+			...(input["labels"] !== undefined ? { labels: optionalStringArray(input, "labels")! } : {}),
+			...(input["status"] !== undefined ? { status: string(input, "status") as "todo" } : {}),
+		}, eventContext(input))),
+		define("tasks.list", (input: OperationInput) => tasks.list(taskFilter(input))),
+		define("tasks.graph", (input: OperationInput) => tasks.graph(taskFilter(input))),
+		define("tasks.plan", (input: OperationInput) => projectTaskExecution(tasks.graph(taskFilter(input)))),
+		define("tasks.show", (input: OperationInput) => tasks.show(string(input, "id"))),
+		define("tasks.history", (input: OperationInput) => tasks.history(string(input, "id"), {
+			limit: optionalNumber(input, "limit"),
+			cursor: optionalNumber(input, "cursor"),
+			direction: optionalString(input, "direction") as TaskEventDirection | undefined,
+		})),
+		define("tasks.scope", (input: OperationInput) => tasks.scopeSelection(string(input, "project_root"))),
+		define("tasks.set_scope", (input: OperationInput) => tasks.setView(
+			string(input, "project_root"),
+			string(input, "scope") as TaskViewMode,
+			optionalString(input, "root_task_id"),
+		)),
+		define("tasks.assign_project", (input: OperationInput) => tasks.assignProject(
+			string(input, "id"),
+			string(input, "project_root"),
+			eventContext(input),
+		)),
+		define("tasks.active", (input: OperationInput) => tasks.active(taskFilter(input))),
+		define("tasks.focused", (input: OperationInput) => tasks.focused(taskFilter(input))),
+		define("tasks.focus", (input: OperationInput) => tasks.focus(string(input, "id"), eventContext(input))),
+		define("tasks.pause", (input: OperationInput) => tasks.pauseFocus(eventContext(input))),
+		define("tasks.unpause", (input: OperationInput) => tasks.unpauseFocus(eventContext(input))),
+		define("tasks.clear_focus", (input: OperationInput) => tasks.clearFocus(eventContext(input))),
+		define("tasks.start", (input: OperationInput) => tasks.transition(string(input, "id"), "start", eventContext(input))),
+		define("tasks.submit", (input: OperationInput) => tasks.transition(string(input, "id"), "submit", eventContext(input))),
+		define("tasks.complete", (input: OperationInput) => tasks.completeAsync(string(input, "id"), eventContext(input))),
+		define("tasks.run_gates", (input: OperationInput) => tasks.runGates(string(input, "id"), eventContext(input))),
+		define("tasks.set_checklist", (input: OperationInput) => tasks.setChecklist(string(input, "id"), input["checklist"] as Checklist)),
+		define("tasks.context", (input: OperationInput) => taskContext(
+			artifacts,
+			tasks.active(taskFilter(input))?.id,
+			new Set(tasks.list(taskFilter(input)).map((task) => task.id)),
+		)),
+		define("tasks.reject", (input: OperationInput) => tasks.transition(string(input, "id"), "reject", eventContext(input))),
+		define("tasks.retry", (input: OperationInput) => tasks.transition(string(input, "id"), "retry", eventContext(input))),
+		define("tasks.cancel", (input: OperationInput) => tasks.transition(string(input, "id"), "cancel", eventContext(input))),
+		define("tasks.depend", (input: OperationInput) => tasks.depend(string(input, "id"), string(input, "dependency_id"), eventContext(input))),
+		define("tasks.undepend", (input: OperationInput) => tasks.undepend(string(input, "id"), string(input, "dependency_id"), eventContext(input))),
+		define("tasks.contain", (input: OperationInput) => tasks.contain(string(input, "parent_id"), string(input, "child_id"), eventContext(input))),
+		define("tasks.uncontain", (input: OperationInput) => tasks.uncontain(string(input, "parent_id"), string(input, "child_id"), eventContext(input))),
+	];
+}

package/src/ops.ts

@@ -9,6 +9,16 @@ import { inTransaction } from "./db.ts";
 import { DEFAULT_STATUS_BY_KIND } from "./constants.ts";
 import type { Artifact, ArtifactQuery, CreateArtifactInput, UpdateArtifactInput } from "./domain/artifact.ts";
 import type { Gate, GateResult, GateRunOptions } from "./domain/gate.ts";
+import {
+	normalizeArtifactEventQuery,
+	resolveArtifactEvent,
+	type AppendArtifactEvent,
+	type ArtifactEvent,
+	type ArtifactEventContext,
+	type ArtifactEventPage,
+	type ArtifactEventQuery,
+	type ArtifactEventType,
+} from "./domain/artifact-event.ts";
 export type { Artifact } from "./domain/artifact.ts";
 export type { Gate, GateResult } from "./domain/gate.ts";
 export type CreateInput = CreateArtifactInput;
@@ -93,15 +103,6 @@ function resolveCreateInput(db: Db, input: CreateInput): ResolvedCreateInput {
 	return merged as ResolvedCreateInput;
 }
 
-function slugify(s: string): string {
-	return s
-		.toLowerCase()
-		.replace(/[^a-z0-9\s-]/g, "")
-		.trim()
-		.replace(/\s+/g, "-")
-		.slice(0, 60) + "-" + Math.random().toString(36).slice(2, 6);
-}
-
 function defaultStatusFor(db: Db, kind: string): string {
 	// Explicit per-kind mapping, never row order -- see DEFAULT_STATUS_BY_KIND's doc comment
 	// for the production defect this replaced (row order is not a semantic guarantee).
@@ -127,9 +128,114 @@ function rowToArtifact(row: Record<string, unknown>): Artifact {
 	};
 }
 
-export function createArtifact(db: Db, input: CreateInput): Artifact {
+/**
+ * Appends one immutable row to the generic, kind-agnostic mutation event log.
+ * This is the one choke point every ArtifactStore mutation funnels through, so every
+ * kind (doc, task, rule, skill) gets an audit trail for free — no domain call site
+ * can skip it. See src/domain/artifact-event.ts for why actor/source always default
+ * to explicit sentinels rather than a silently blank column.
+ */
+export function appendArtifactEvent(db: Db, input: AppendArtifactEvent): ArtifactEvent {
+	const event = resolveArtifactEvent(input);
+	const now = new Date().toISOString();
+	let id: number | bigint = 0;
+	inTransaction(db, () => {
+		const result = db.prepare(`
+			INSERT INTO artifact_events (
+				artifact_id, occurred_at, event_type, actor, source, session_id,
+				from_status, to_status, relation, related_id, event_schema_version
+			) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1)
+		`).run(
+			event.artifactId,
+			now,
+			event.type,
+			event.actor,
+			event.source,
+			event.sessionId ?? null,
+			event.fromStatus ?? null,
+			event.toStatus ?? null,
+			event.relation ?? null,
+			event.relatedId ?? null,
+		);
+		id = result.lastInsertRowid;
+	});
+	return {
+		id: Number(id),
+		artifactId: event.artifactId,
+		occurredAt: now,
+		type: event.type,
+		actor: event.actor,
+		source: event.source,
+		...(event.sessionId === undefined ? {} : { sessionId: event.sessionId }),
+		...(event.fromStatus === undefined ? {} : { fromStatus: event.fromStatus }),
+		...(event.toStatus === undefined ? {} : { toStatus: event.toStatus }),
+		...(event.relation === undefined ? {} : { relation: event.relation }),
+		...(event.relatedId === undefined ? {} : { relatedId: event.relatedId }),
+		schemaVersion: 1,
+	};
+}
+
+interface ArtifactEventRow {
+	id: number;
+	artifact_id: string;
+	occurred_at: string;
+	event_type: ArtifactEventType;
+	actor: string;
+	source: string;
+	session_id: string | null;
+	from_status: string | null;
+	to_status: string | null;
+	relation: string | null;
+	related_id: string | null;
+	event_schema_version: 1;
+}
+
+function mapArtifactEventRow(row: ArtifactEventRow): ArtifactEvent {
+	return {
+		id: row.id,
+		artifactId: row.artifact_id,
+		occurredAt: row.occurred_at,
+		type: row.event_type,
+		actor: row.actor,
+		source: row.source,
+		...(row.session_id === null ? {} : { sessionId: row.session_id }),
+		...(row.from_status === null ? {} : { fromStatus: row.from_status }),
+		...(row.to_status === null ? {} : { toStatus: row.to_status }),
+		...(row.relation === null ? {} : { relation: row.relation }),
+		...(row.related_id === null ? {} : { relatedId: row.related_id }),
+		schemaVersion: row.event_schema_version,
+	};
+}
+
+/** Bounded query over the generic mutation event log — requires artifactId, actor, or sessionId to stay indexed. */
+export function queryArtifactEvents(db: Db, query: ArtifactEventQuery): ArtifactEventPage {
+	const { artifactId, actor, sessionId, since, limit, direction, cursor } = normalizeArtifactEventQuery(query);
+	const conditions: string[] = [];
+	const params: unknown[] = [];
+	if (artifactId) { conditions.push("(artifact_id = ? OR related_id = ?)"); params.push(artifactId, artifactId); }
+	if (actor) { conditions.push("actor = ?"); params.push(actor); }
+	if (sessionId) { conditions.push("session_id = ?"); params.push(sessionId); }
+	if (since) { conditions.push("occurred_at >= ?"); params.push(since); }
+	const comparator = direction === "desc" ? "<" : ">";
+	if (cursor !== undefined) { conditions.push(`id ${comparator} ?`); params.push(cursor); }
+	const order = direction === "desc" ? "DESC" : "ASC";
+	const rows = db.prepare(`
+		SELECT * FROM artifact_events
+		WHERE ${conditions.join(" AND ")}
+		ORDER BY occurred_at ${order}, id ${order}
+		LIMIT ?
+	`).all(...params, limit + 1) as ArtifactEventRow[];
+	const hasMore = rows.length > limit;
+	const events = rows.slice(0, limit).map(mapArtifactEventRow);
+	return { events, ...(hasMore ? { nextCursor: events.at(-1)!.id } : {}) };
+}
+
+export function createArtifact(db: Db, input: CreateInput, context?: ArtifactEventContext): Artifact {
 	const resolved = resolveCreateInput(db, input);
-	const id = resolved.id ?? slugify(resolved.title);
+	// id is an opaque backend identity, never derived from title -- a title-derived slug
+	// conflated "identity" with "human-readable label" and leaked a bit of randomness into
+	// both. crypto.randomUUID() is native to Bun/Node; no dependency needed for this.
+	const id = resolved.id ?? crypto.randomUUID();
 	const status = resolved.status ?? defaultStatusFor(db, resolved.kind);
 	const now = new Date().toISOString();
 	const labels = JSON.stringify(resolved.labels ?? []);
@@ -140,6 +246,7 @@ export function createArtifact(db: Db, input: CreateInput): Artifact {
 			"INSERT INTO artifacts (id, kind, title, status, subtype, body, labels, extra, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
 		);
 		stmt.run(id, resolved.kind, resolved.title, status, subtype, resolved.body ?? "", labels, extra, now, now);
+		appendArtifactEvent(db, { artifactId: id, type: "created", toStatus: status, ...context });
 	});
 	return getArtifact(db, id)!;
 }
@@ -211,7 +318,7 @@ export function queryArtifacts(db: Db, filter: ArtifactQuery): Artifact[] {
 	return rows.map(rowToArtifact);
 }
 
-export function linkArtifacts(db: Db, fromId: string, relation: string, toId: string): void {
+export function linkArtifacts(db: Db, fromId: string, relation: string, toId: string, context?: ArtifactEventContext): void {
 	const fromArt = getArtifact(db, fromId);
 	const toArt = getArtifact(db, toId);
 	if (!fromArt || !toArt) throw new Error("artifact not found");
@@ -219,11 +326,28 @@ export function linkArtifacts(db: Db, fromId: string, relation: string, toId: st
 	const allowed = db.prepare("SELECT 1 FROM relation_names WHERE name = ?").get(relation);
 	if (!allowed) throw new Error(`unknown relation "${relation}" — register it first`);
 	inTransaction(db, () => {
+		const existed = db.prepare("SELECT 1 FROM edges WHERE from_id = ? AND relation = ? AND to_id = ?").get(fromId, relation, toId);
 		db.prepare("INSERT OR IGNORE INTO edges (from_id, relation, to_id) VALUES (?, ?, ?)").run(fromId, relation, toId);
+		if (!existed) {
+			appendArtifactEvent(db, { artifactId: fromId, type: "linked", relation, relatedId: toId, ...context });
+		}
+	});
+}
+
+/** Idempotent: removing an already-absent relationship is a no-op that returns false, not an error. */
+export function unlinkArtifacts(db: Db, fromId: string, relation: string, toId: string, context?: ArtifactEventContext): boolean {
+	let removed = false;
+	inTransaction(db, () => {
+		const existed = db.prepare("SELECT 1 FROM edges WHERE from_id = ? AND relation = ? AND to_id = ?").get(fromId, relation, toId);
+		if (!existed) return;
+		db.prepare("DELETE FROM edges WHERE from_id = ? AND relation = ? AND to_id = ?").run(fromId, relation, toId);
+		appendArtifactEvent(db, { artifactId: fromId, type: "unlinked", relation, relatedId: toId, ...context });
+		removed = true;
 	});
+	return removed;
 }
 
-export function updateArtifactContent(db: Db, id: string, input: UpdateArtifactInput): Artifact | null {
+export function updateArtifactContent(db: Db, id: string, input: UpdateArtifactInput, context?: ArtifactEventContext): Artifact | null {
 	const artifact = getArtifact(db, id);
 	if (!artifact) return null;
 	const now = new Date().toISOString();
@@ -235,11 +359,12 @@ export function updateArtifactContent(db: Db, id: string, input: UpdateArtifactI
 			now,
 			id,
 		);
+		appendArtifactEvent(db, { artifactId: id, type: "updated", ...context });
 	});
 	return getArtifact(db, id);
 }
 
-export function updateStatus(db: Db, id: string, status: string): Artifact | null {
+export function updateStatus(db: Db, id: string, status: string, context?: ArtifactEventContext): Artifact | null {
 	const art = getArtifact(db, id);
 	if (!art) return null;
 	// Validate status is registered for this kind
@@ -248,15 +373,17 @@ export function updateStatus(db: Db, id: string, status: string): Artifact | nul
 	const now = new Date().toISOString();
 	inTransaction(db, () => {
 		db.prepare("UPDATE artifacts SET status = ?, updated_at = ? WHERE id = ?").run(status, now, id);
+		appendArtifactEvent(db, { artifactId: id, type: "status_changed", fromStatus: art.status, toStatus: status, ...context });
 	});
 	return getArtifact(db, id);
 }
 
-export function updateExtra(db: Db, id: string, extra: Record<string, unknown>): Artifact | null {
+export function updateExtra(db: Db, id: string, extra: Record<string, unknown>, context?: ArtifactEventContext): Artifact | null {
 	if (!getArtifact(db, id)) return null;
 	const now = new Date().toISOString();
 	inTransaction(db, () => {
 		db.prepare("UPDATE artifacts SET extra = ?, updated_at = ? WHERE id = ?").run(JSON.stringify(extra), now, id);
+		appendArtifactEvent(db, { artifactId: id, type: "extra_set", ...context });
 	});
 	return getArtifact(db, id);
 }

package/src/ports/artifact-scope-store.ts

@@ -0,0 +1,20 @@
+import type { TaskScopeSource } from "../domain/task-scope.ts";
+
+/**
+ * Project scoping for Docs/Rules/Skills, mirroring TaskScopeStore's shape (task_scopes) but
+ * kept as its own table/port rather than folding non-Task kinds into Task-named
+ * infrastructure. TaskScopeSource ("cwd" | "explicit" | "unscoped") is already kind-agnostic
+ * and reused as-is -- no reason to redefine the same three values under a new name.
+ */
+export interface ArtifactScope {
+	artifactId: string;
+	projectRoot?: string;
+	source: TaskScopeSource;
+}
+
+export interface ArtifactScopeStore {
+	assign(artifactId: string, projectRoot: string | undefined, source: TaskScopeSource): ArtifactScope;
+	get(artifactId: string): ArtifactScope | undefined;
+	/** Bounded id listing for one project (or the unscoped bucket when projectRoot is undefined). */
+	ids(projectRoot: string | undefined, limit: number): string[];
+}

package/src/ports/artifact-store.ts

@@ -8,14 +8,19 @@ import type {
 	RelationshipQuery,
 	UpdateArtifactInput,
 } from "../domain/artifact.ts";
+import type { ArtifactEventContext, ArtifactEventPage, ArtifactEventQuery } from "../domain/artifact-event.ts";
 
 export interface ArtifactStore {
-	create(input: CreateArtifactInput): Artifact;
+	create(input: CreateArtifactInput, context?: ArtifactEventContext): Artifact;
 	get(id: string, options?: ArtifactGraphOptions): Artifact | null;
 	query(filter: ArtifactQuery): Artifact[];
-	link(link: ArtifactLink): void;
-	setStatus(id: string, status: string): Artifact | null;
-	setExtra(id: string, extra: Record<string, unknown>): Artifact | null;
-	updateContent(id: string, input: UpdateArtifactInput): Artifact | null;
+	link(link: ArtifactLink, context?: ArtifactEventContext): void;
+	/** Idempotent: removing an already-absent relationship is a no-op that returns false, not an error. */
+	unlink(link: ArtifactLink, context?: ArtifactEventContext): boolean;
+	setStatus(id: string, status: string, context?: ArtifactEventContext): Artifact | null;
+	setExtra(id: string, extra: Record<string, unknown>, context?: ArtifactEventContext): Artifact | null;
+	updateContent(id: string, input: UpdateArtifactInput, context?: ArtifactEventContext): Artifact | null;
 	relationships(filter?: RelationshipQuery): ArtifactEdge[];
+	/** Bounded query over the generic mutation event log shared by every kind. */
+	events(query: ArtifactEventQuery): ArtifactEventPage;
 }

package/src/ports/conversation-journal-store.ts

@@ -0,0 +1,17 @@
+import type { JournalPost, JournalThread } from "../domain/conversation-journal.ts";
+
+/**
+ * Persistence port for ConversationJournal. Deliberately minimal and host-neutral: no
+ * mention of any host runtime, no query beyond what a bounded thread read needs. Idempotency
+ * (checking operationId before insert) is the service's job, not the store's -- this port is
+ * dumb storage, matching Discourse's own store/service split (see the layering decision doc).
+ */
+export interface ConversationJournalStore {
+	ensureThread(threadId: string): JournalThread;
+	getThread(threadId: string): JournalThread | undefined;
+	findPostByOperationId(operationId: string): JournalPost | undefined;
+	insertPost(post: JournalPost): void;
+	getPost(id: string): JournalPost | undefined;
+	/** All posts for one thread, unbounded at the store layer -- the service applies the read bound. */
+	postsForThread(threadId: string): readonly JournalPost[];
+}

package/src/ports/graph-projection-store.ts

@@ -0,0 +1,15 @@
+import type { ProjectionCheckpoint } from "../domain/graph-projection.ts";
+
+/**
+ * Producer-scoped state a graph projection consumer needs beyond the generic ArtifactStore:
+ * the (producerId, externalId) -> Papyrus artifact id identity map, and the per-producer
+ * checkpoint. This is projection-specific bookkeeping, not Context Mesh content itself, so
+ * it is its own small port rather than bloating ArtifactStore.
+ */
+export interface GraphProjectionStore {
+	getCheckpoint(producerId: string): ProjectionCheckpoint | null;
+	resolveIdentity(producerId: string, externalId: string): string | undefined;
+	/** Idempotent: recording the same (producerId, externalId) -> artifactId mapping twice is a no-op. */
+	recordIdentity(producerId: string, externalId: string, artifactId: string): void;
+	commitCheckpoint(checkpoint: ProjectionCheckpoint): void;
+}