@danypops/papyrus 0.54.2 → 0.54.4

package/src/task/task-project-scope.ts

@@ -0,0 +1,107 @@
+import type { Artifact } from "../artifact/artifact.ts";
+import { TASK_PROJECT_LIST_MAX_RESULTS } from "../constants.ts";
+import { assertRegisterProjectInputBounds } from "../domain/project-registry.ts";
+import type { AppendTaskEvent, TaskEventContext } from "../domain/task-event.ts";
+import {
+	normalizeProjectRoot,
+	type RegisterTaskProjectInput,
+	type TaskProject,
+	type TaskViewMode,
+	type TaskViewSelection,
+	taskScopeLabel,
+} from "../domain/task-scope.ts";
+import type { TaskEventStore } from "../stores/task-event-store.ts";
+import type { TaskScopeStore } from "../stores/task-scope-store.ts";
+
+export class TaskProjectNotFoundError extends Error {}
+export class TaskProjectAmbiguousError extends Error {}
+
+/**
+ * Task project-scope management (scopeSelection/setView/assignProject/projects/resolveProject/
+ * registerProject), split out of the Tasks god class as part of a SOLID-audit-driven
+ * decomposition (see task b51419a0 and the "TaskProjectScope" child of "Epic: Modularize
+ * papyrus/pi-papyrus god-files into building-block modules"), mirroring the existing
+ * TaskLeaseCoordinator/TaskMutationCoordinator/TaskFocusCoordinator precedent in this directory.
+ *
+ * list()/graph() (which stay on Tasks -- they're core query/graph-construction, not project-scope
+ * itself) still call scopeSelection() on this collaborator via Tasks' own thin delegation.
+ */
+export class TaskProjectScope {
+	constructor(
+		private readonly scopes: TaskScopeStore,
+		private readonly events: TaskEventStore,
+		/** Delegates to Tasks.require() so project-scope methods get the identical not-found/wrong-kind checks every other Tasks method already enforces, without duplicating that logic here. */
+		private readonly requireTask: (id: string) => Artifact,
+		/** Delegates to Tasks' own actor/source/sessionId/reason defaulting so every event this collaborator appends looks identical to one Tasks itself would have appended. */
+		private readonly appendEvent: (event: Omit<AppendTaskEvent, "actor" | "source">, context: TaskEventContext) => void,
+	) {}
+
+	scopeSelection(projectRoot?: string, mode?: TaskViewMode, rootTaskId?: string): TaskViewSelection {
+		if (mode !== undefined && mode !== "project" && mode !== "graph" && mode !== "all")
+			throw new Error("task scope must be project, graph, or all");
+		if (projectRoot === undefined) return { mode: "all", label: taskScopeLabel("all") };
+		const normalized = normalizeProjectRoot(projectRoot);
+		const persisted = this.scopes.view(normalized);
+		const selectedMode = mode ?? persisted.mode;
+		const selectedRoot = rootTaskId ?? (selectedMode === "graph" ? persisted.rootTaskId : undefined);
+		if (selectedMode === "graph" && !selectedRoot) throw new Error("graph scope requires root_task_id");
+		const root = selectedRoot ? this.requireTask(selectedRoot) : undefined;
+		if (root && this.scopes.get(root.id)?.projectRoot !== normalized) throw new Error(`task "${root.id}" is outside project scope`);
+		return {
+			mode: selectedMode,
+			label: taskScopeLabel(selectedMode, normalized, root?.title),
+			projectRoot: normalized,
+			...(selectedRoot === undefined ? {} : { rootTaskId: selectedRoot }),
+		};
+	}
+
+	setView(projectRoot: string, mode: TaskViewMode, rootTaskId?: string): TaskViewSelection {
+		const selection = this.scopeSelection(projectRoot, mode, rootTaskId);
+		this.scopes.setView(selection.projectRoot!, selection.mode, selection.rootTaskId);
+		return selection;
+	}
+
+	assignProject(id: string, projectRoot: string, context: TaskEventContext = {}): Artifact {
+		return this.events.atomic(() => {
+			const task = this.requireTask(id);
+			this.scopes.assign(id, normalizeProjectRoot(projectRoot), "explicit");
+			this.appendEvent({ taskId: id, type: "project_assigned", reason: context.reason }, context);
+			return task;
+		});
+	}
+
+	projects(query?: string, limit = 20): TaskProject[] {
+		if (!Number.isInteger(limit) || limit < 1 || limit > TASK_PROJECT_LIST_MAX_RESULTS) {
+			throw new Error(`project list limit must be between 1 and ${TASK_PROJECT_LIST_MAX_RESULTS}`);
+		}
+		return this.scopes.projects(query, limit);
+	}
+
+	resolveProject(reference: string): TaskProject {
+		const matches = this.scopes.matchingProjects(reference);
+		if (matches.length === 0) {
+			const candidates = this.scopes.projects(reference, 10);
+			const fallback = candidates.length === 0 ? this.scopes.projects(undefined, 10) : candidates;
+			const suffix =
+				fallback.length === 0 ? "" : ` Candidates: ${fallback.map((project) => `${project.name} (${project.projectRoot})`).join(", ")}`;
+			throw new TaskProjectNotFoundError(`no task project named or aliased "${reference}" is registered.${suffix}`);
+		}
+		if (matches.length > 1) {
+			throw new TaskProjectAmbiguousError(
+				`task project reference "${reference}" is ambiguous: ${matches
+					.slice(0, 10)
+					.map((project) => `${project.name} (${project.projectRoot})`)
+					.join(", ")}`,
+			);
+		}
+		return matches[0]!;
+	}
+
+	registerProject(input: RegisterTaskProjectInput, existingReference?: string): TaskProject {
+		const projectRoot = normalizeProjectRoot(input.projectRoot);
+		const name = input.name?.trim();
+		assertRegisterProjectInputBounds(name, input.aliases);
+		const existingId = existingReference ? this.resolveProject(existingReference).id : input.existingId;
+		return this.scopes.registerProject({ projectRoot, ...(name ? { name } : {}), aliases: input.aliases, existingId });
+	}
+}

package/src/task/task-service.ts

@@ -9,17 +9,14 @@ import {
 	TASK_EXECUTION_MAX_DEGREE,
 	TASK_EXECUTION_MAX_EDGES,
 	TASK_EXECUTION_MAX_NODES,
-	TASK_FOCUS_STALE_AFTER_MS,
 	TASK_LABEL_MAX_COUNT,
 	TASK_LABEL_MAX_LENGTH,
-	TASK_PROJECT_LIST_MAX_RESULTS,
 	TASK_SCOPE_MAX_TASKS,
 	TASK_TITLE_MAX_LENGTH,
 } from "../constants.ts";
 import { type Checklist, checklistEntries, type ProofReference, validateChecklist } from "../domain/checklist.ts";
 import { DISCUSSION_SUBTYPE, isDiscussionArtifact, readDiscussionExtra } from "../domain/discussion.ts";
 import { type Gate, type GateResult, validateGates } from "../domain/gate.ts";
-import { assertRegisterProjectInputBounds } from "../domain/project-registry.ts";
 import type {
 	AppendTaskEvent,
 	TaskEventContext,
@@ -57,16 +54,29 @@ import {
 	type TaskMutationRequestStore,
 } from "../stores/task-mutation-request-store.ts";
 import { InMemoryTaskScopeStore, type TaskScopeStore } from "../stores/task-scope-store.ts";
-import { assertDependencyEdgeAllowed, TaskExecutionBoundExceededError } from "./task-execution.ts";
+import { TaskEdges } from "./task-edges.ts";
+import { TaskExecutionBoundExceededError } from "./task-execution.ts";
+import { type TaskFocus, TaskFocusCoordinator, type TaskFocusMutationResult } from "./task-focus-coordinator.ts";
 import { TaskLeaseCoordinator } from "./task-lease-coordinator.ts";
+import { TaskInvalidTransitionError } from "./task-lifecycle-errors.ts";
 import {
 	TaskMutationCoordinator,
 	TaskMutationReceiptNotFoundError,
 	type TaskMutationReceiptView,
 	type TaskMutationRequestContext,
 } from "./task-mutation-coordinator.ts";
+import { TaskProjectAmbiguousError, TaskProjectNotFoundError, TaskProjectScope } from "./task-project-scope.ts";
 
-export { TaskMutationReceiptNotFoundError, type TaskMutationReceiptView, type TaskMutationRequestContext };
+export {
+	type TaskFocus,
+	type TaskFocusMutationResult,
+	TaskInvalidTransitionError,
+	TaskMutationReceiptNotFoundError,
+	type TaskMutationReceiptView,
+	type TaskMutationRequestContext,
+	TaskProjectAmbiguousError,
+	TaskProjectNotFoundError,
+};
 
 export interface UpdateTaskInput {
 	title?: string;
@@ -90,21 +100,6 @@ export interface TaskFilter {
 
 export type TaskStatus = TaskLifecycleStatus;
 
-export class TaskProjectNotFoundError extends Error {}
-export class TaskProjectAmbiguousError extends Error {}
-
-export class TaskInvalidTransitionError extends Error {
-	constructor(
-		readonly operation: string,
-		readonly currentStatus: string,
-		readonly intendedStatus: string,
-		readonly allowedActions: readonly string[],
-		readonly recovery: string,
-	) {
-		super(`cannot ${operation} task from ${currentStatus}; intended status is ${intendedStatus}`);
-	}
-}
-
 export interface TaskMutationMetadata {
 	changed: boolean;
 	operation: string;
@@ -152,15 +147,6 @@ export interface ChecklistReview {
 	reason?: string;
 }
 
-export interface TaskFocus {
-	artifact: Artifact;
-	status: TaskFocusStatus;
-	updatedAt: string;
-	pauseReason?: string;
-}
-
-export type TaskFocusMutationResult = TaskFocus & TaskMutationMetadata;
-
 export interface TaskCompletionOptions {
 	focusSuccessor?: boolean;
 	gateDeadlineMs?: number;
@@ -234,11 +220,39 @@ export class Tasks {
 	) {
 		this.leaseCoordinator = new TaskLeaseCoordinator(this.leases, (id) => this.require(id));
 		this.mutationCoordinator = new TaskMutationCoordinator(this.mutationRequests, this.artifacts);
+		this.focusCoordinator = new TaskFocusCoordinator(
+			this.artifacts,
+			this.focusStore,
+			this.events,
+			this.mutationCoordinator,
+			(id) => this.require(id),
+			(filter) => this.list(filter),
+			(event, context) => this.appendEvent(event, context),
+		);
+		this.projectScope = new TaskProjectScope(
+			this.scopes,
+			this.events,
+			(id) => this.require(id),
+			(event, context) => this.appendEvent(event, context),
+		);
+		this.taskEdges = new TaskEdges(
+			this.artifacts,
+			this.events,
+			(id) => this.require(id),
+			(id) => this.show(id),
+			(event, context) => this.appendEvent(event, context),
+			(id, dependencyId) => this.dependencyCheckGraph(id, dependencyId),
+			(id) => this.dependencyIds(id),
+			(id) => this.relationships(id),
+		);
 	}
 
 	private readonly completionFlights = new Map<string, Promise<TaskCompletion>>();
 	private readonly leaseCoordinator: TaskLeaseCoordinator;
 	private readonly mutationCoordinator: TaskMutationCoordinator;
+	private readonly focusCoordinator: TaskFocusCoordinator;
+	private readonly projectScope: TaskProjectScope;
+	private readonly taskEdges: TaskEdges;
 
 	private require(id: string): Artifact {
 		const artifact = this.artifacts.get(id);
@@ -375,7 +389,7 @@ export class Tasks {
 	}
 
 	list(filter: TaskFilter = {}): Artifact[] {
-		const selection = this.scopeSelection(filter.projectRoot, filter.scope, filter.rootTaskId);
+		const selection = this.projectScope.scopeSelection(filter.projectRoot, filter.scope, filter.rootTaskId);
 		const limit = filter.limit ?? TASK_SCOPE_MAX_TASKS;
 		if (!Number.isInteger(limit) || limit < 1 || limit > TASK_SCOPE_MAX_TASKS + 1) {
 			throw new Error(`task list limit must be between 1 and ${TASK_SCOPE_MAX_TASKS + 1}`);
@@ -415,41 +429,19 @@ export class Tasks {
 	}
 
 	scopeSelection(projectRoot?: string, mode?: TaskViewMode, rootTaskId?: string): TaskViewSelection {
-		if (mode !== undefined && mode !== "project" && mode !== "graph" && mode !== "all")
-			throw new Error("task scope must be project, graph, or all");
-		if (projectRoot === undefined) return { mode: "all", label: taskScopeLabel("all") };
-		const normalized = normalizeProjectRoot(projectRoot);
-		const persisted = this.scopes.view(normalized);
-		const selectedMode = mode ?? persisted.mode;
-		const selectedRoot = rootTaskId ?? (selectedMode === "graph" ? persisted.rootTaskId : undefined);
-		if (selectedMode === "graph" && !selectedRoot) throw new Error("graph scope requires root_task_id");
-		const root = selectedRoot ? this.require(selectedRoot) : undefined;
-		if (root && this.scopes.get(root.id)?.projectRoot !== normalized) throw new Error(`task "${root.id}" is outside project scope`);
-		return {
-			mode: selectedMode,
-			label: taskScopeLabel(selectedMode, normalized, root?.title),
-			projectRoot: normalized,
-			...(selectedRoot === undefined ? {} : { rootTaskId: selectedRoot }),
-		};
+		return this.projectScope.scopeSelection(projectRoot, mode, rootTaskId);
 	}
 
 	setView(projectRoot: string, mode: TaskViewMode, rootTaskId?: string): TaskViewSelection {
-		const selection = this.scopeSelection(projectRoot, mode, rootTaskId);
-		this.scopes.setView(selection.projectRoot!, selection.mode, selection.rootTaskId);
-		return selection;
+		return this.projectScope.setView(projectRoot, mode, rootTaskId);
 	}
 
 	assignProject(id: string, projectRoot: string, context: TaskEventContext = {}): Artifact {
-		return this.events.atomic(() => {
-			const task = this.require(id);
-			this.scopes.assign(id, normalizeProjectRoot(projectRoot), "explicit");
-			this.appendEvent({ taskId: id, type: "project_assigned", reason: context.reason }, context);
-			return task;
-		});
+		return this.projectScope.assignProject(id, projectRoot, context);
 	}
 
 	graph(filter: TaskFilter = {}): TaskGraph {
-		const scope = this.scopeSelection(filter.projectRoot, filter.scope, filter.rootTaskId);
+		const scope = this.projectScope.scopeSelection(filter.projectRoot, filter.scope, filter.rootTaskId);
 		const requestedLimit = filter.limit ?? TASK_EXECUTION_MAX_NODES + 1;
 		if (!Number.isInteger(requestedLimit) || requestedLimit < 1 || requestedLimit > TASK_EXECUTION_MAX_NODES + 1) {
 			throw new Error(`task graph limit must be between 1 and ${TASK_EXECUTION_MAX_NODES + 1}`);
@@ -512,38 +504,15 @@ export class Tasks {
 	}
 
 	projects(query?: string, limit = 20): TaskProject[] {
-		if (!Number.isInteger(limit) || limit < 1 || limit > TASK_PROJECT_LIST_MAX_RESULTS) {
-			throw new Error(`project list limit must be between 1 and ${TASK_PROJECT_LIST_MAX_RESULTS}`);
-		}
-		return this.scopes.projects(query, limit);
+		return this.projectScope.projects(query, limit);
 	}
 
 	resolveProject(reference: string): TaskProject {
-		const matches = this.scopes.matchingProjects(reference);
-		if (matches.length === 0) {
-			const candidates = this.scopes.projects(reference, 10);
-			const fallback = candidates.length === 0 ? this.scopes.projects(undefined, 10) : candidates;
-			const suffix =
-				fallback.length === 0 ? "" : ` Candidates: ${fallback.map((project) => `${project.name} (${project.projectRoot})`).join(", ")}`;
-			throw new TaskProjectNotFoundError(`no task project named or aliased "${reference}" is registered.${suffix}`);
-		}
-		if (matches.length > 1) {
-			throw new TaskProjectAmbiguousError(
-				`task project reference "${reference}" is ambiguous: ${matches
-					.slice(0, 10)
-					.map((project) => `${project.name} (${project.projectRoot})`)
-					.join(", ")}`,
-			);
-		}
-		return matches[0]!;
+		return this.projectScope.resolveProject(reference);
 	}
 
 	registerProject(input: RegisterTaskProjectInput, existingReference?: string): TaskProject {
-		const projectRoot = normalizeProjectRoot(input.projectRoot);
-		const name = input.name?.trim();
-		assertRegisterProjectInputBounds(name, input.aliases);
-		const existingId = existingReference ? this.resolveProject(existingReference).id : input.existingId;
-		return this.scopes.registerProject({ projectRoot, ...(name ? { name } : {}), aliases: input.aliases, existingId });
+		return this.projectScope.registerProject(input, existingReference);
 	}
 
 	show(id: string): Artifact {
@@ -552,142 +521,32 @@ export class Tasks {
 	}
 
 	focused(filter?: TaskFilter): TaskFocus | null {
-		const focus = this.focusStore.get(filter?.sessionId);
-		if (!focus) return null;
-		const task = this.artifacts.get(focus.taskId);
-		if (task?.kind !== "task" || task.status === "done" || task.status === "canceled") {
-			this.focusStore.clear(focus.taskId, filter?.sessionId);
-			return null;
-		}
-		if (filter?.projectRoot && !this.list(filter).some((candidate) => candidate.id === task.id)) return null;
-		return {
-			artifact: task,
-			status: focus.status,
-			updatedAt: focus.updatedAt,
-			...(focus.pauseReason ? { pauseReason: focus.pauseReason } : {}),
-		};
+		return this.focusCoordinator.focused(filter);
 	}
 
 	active(filter?: TaskFilter): Artifact | null {
-		const focus = this.focused(filter);
-		return focus?.status === "active" ? focus.artifact : null;
+		return this.focusCoordinator.active(filter);
 	}
 
 	focus(id: string, context: TaskEventContext = {}): Artifact {
-		return this.events.atomic(() => {
-			const task = this.require(id);
-			if (task.status === "done" || task.status === "canceled") throw new Error(`cannot focus task from ${task.status}`);
-			this.focusStore.set(id, context.sessionId);
-			this.appendEvent({ taskId: id, type: "focus_set" }, context);
-			return task;
-		});
+		return this.focusCoordinator.focus(id, context);
 	}
 
 	pauseFocus(context: TaskEventContext = {}, request: TaskMutationRequestContext = {}): TaskFocusMutationResult {
-		const inspection = this.prepareMutation<TaskFocusMutationResult>("pause", undefined, context, request, false);
-		if (inspection.replay) return inspection.replay;
-		const focus = this.focused({ sessionId: context.sessionId });
-		if (!focus) {
-			throw new TaskInvalidTransitionError(
-				"pause",
-				"none",
-				"paused",
-				["focus"],
-				"Focus a non-terminal task before pausing; do not blindly retry pause.",
-			);
-		}
-		const prepared = inspection.pending
-			? inspection
-			: this.prepareMutation<TaskFocusMutationResult>("pause", undefined, context, request, true, () => validateEventContext(context));
-		if (focus.status === "paused") {
-			return this.completeMutation(prepared.record, {
-				...focus,
-				changed: false,
-				operation: "pause",
-				currentStatus: "paused",
-				intendedStatus: "paused",
-				...(prepared.record ? { receiptId: prepared.record.receiptId } : {}),
-			});
-		}
-		return this.events.atomic(() => {
-			const state = this.focusStore.pause(focus.artifact.id, context.reason, context.sessionId);
-			this.appendEvent({ taskId: focus.artifact.id, type: "focus_paused" }, context);
-			return this.completeMutation(prepared.record, {
-				artifact: focus.artifact,
-				status: state.status,
-				updatedAt: state.updatedAt,
-				...(state.pauseReason ? { pauseReason: state.pauseReason } : {}),
-				changed: true,
-				operation: "pause",
-				currentStatus: "paused",
-				intendedStatus: "paused",
-				...(prepared.record ? { receiptId: prepared.record.receiptId } : {}),
-			});
-		});
+		return this.focusCoordinator.pauseFocus(context, request);
 	}
 
 	unpauseFocus(context: TaskEventContext = {}, request: TaskMutationRequestContext = {}): TaskFocusMutationResult {
-		const inspection = this.prepareMutation<TaskFocusMutationResult>("unpause", undefined, context, request, false);
-		if (inspection.replay) return inspection.replay;
-		const focus = this.focused({ sessionId: context.sessionId });
-		if (!focus) {
-			throw new TaskInvalidTransitionError(
-				"unpause",
-				"none",
-				"active",
-				["focus"],
-				"Focus a non-terminal task before resuming; do not blindly retry unpause.",
-			);
-		}
-		const prepared = inspection.pending
-			? inspection
-			: this.prepareMutation<TaskFocusMutationResult>("unpause", undefined, context, request, true, () => validateEventContext(context));
-		if (focus.status === "active") {
-			return this.completeMutation(prepared.record, {
-				...focus,
-				changed: false,
-				operation: "unpause",
-				currentStatus: "active",
-				intendedStatus: "active",
-				...(prepared.record ? { receiptId: prepared.record.receiptId } : {}),
-			});
-		}
-		return this.events.atomic(() => {
-			const state = this.focusStore.unpause(focus.artifact.id, context.sessionId);
-			this.appendEvent({ taskId: focus.artifact.id, type: "focus_unpaused" }, context);
-			return this.completeMutation(prepared.record, {
-				artifact: focus.artifact,
-				status: state.status,
-				updatedAt: state.updatedAt,
-				changed: true,
-				operation: "unpause",
-				currentStatus: "active",
-				intendedStatus: "active",
-				...(prepared.record ? { receiptId: prepared.record.receiptId } : {}),
-			});
-		});
+		return this.focusCoordinator.unpauseFocus(context, request);
 	}
 
 	clearFocus(context: TaskEventContext = {}): { cleared: boolean } {
-		return this.events.atomic(() => {
-			const focus = this.focusStore.get(context.sessionId);
-			if (focus) this.appendEvent({ taskId: focus.taskId, type: "focus_cleared" }, context);
-			this.focusStore.clear(undefined, context.sessionId);
-			return { cleared: focus !== undefined };
-		});
+		return this.focusCoordinator.clearFocus(context);
 	}
 
-	/**
-	 * Time-based reclamation of Focus scopes nobody has touched in TASK_FOCUS_STALE_AFTER_MS,
-	 * independent of and in addition to the TASK_FOCUS_MAX_SCOPES hard cap -- see
-	 * clean-up-stale-per-session-task-focus-rows-on-real-session-l-9i7s and constants.ts's
-	 * comment on why this is deliberately not driven by session_start/session_shutdown.
-	 * No task-lifecycle event is appended: this is daemon housekeeping, not a caller-driven
-	 * mutation, and there is no longer a specific session/actor to attribute it to.
-	 */
-	reapStaleFocus(now: () => string = () => new Date().toISOString()): number {
-		const cutoff = new Date(new Date(now()).getTime() - TASK_FOCUS_STALE_AFTER_MS).toISOString();
-		return this.focusStore.reapStale(cutoff);
+	/** Delegates to TaskFocusCoordinator -- see its own doc comment on TASK_FOCUS_STALE_AFTER_MS/TASK_FOCUS_MAX_SCOPES. */
+	reapStaleFocus(now?: () => string): number {
+		return this.focusCoordinator.reapStaleFocus(now);
 	}
 
 	/** A lease is orthogonal to lifecycle and Focus: claiming a task does not start it, and does not require it to be Focused. */
@@ -974,24 +833,7 @@ export class Tasks {
 	}
 
 	depend(id: string, dependencyId: string, context: TaskEventContext = {}): Artifact {
-		return this.events.atomic(() => {
-			this.require(id);
-			this.require(dependencyId);
-			const graph = this.dependencyCheckGraph(id, dependencyId);
-			assertDependencyEdgeAllowed(graph, id, dependencyId);
-			const node = graph.nodes.find((entry) => entry.task.id === id)!;
-			if (node.dependencyIds.includes(dependencyId)) return this.show(id);
-			if (node.dependencyIds.length >= TASK_EXECUTION_MAX_DEGREE) {
-				throw new TaskExecutionBoundExceededError(`task "${id}" cannot exceed ${TASK_EXECUTION_MAX_DEGREE} prerequisites`);
-			}
-			const successorCount = graph.nodes.filter((entry) => entry.dependencyIds.includes(dependencyId)).length;
-			if (successorCount >= TASK_EXECUTION_MAX_DEGREE) {
-				throw new TaskExecutionBoundExceededError(`task "${dependencyId}" cannot exceed ${TASK_EXECUTION_MAX_DEGREE} successors`);
-			}
-			this.artifacts.link({ from: id, relation: "depends_on", to: dependencyId }, context);
-			this.appendEvent({ taskId: id, type: "dependency_added", reason: context.reason }, context);
-			return this.show(id);
-		});
+		return this.taskEdges.depend(id, dependencyId, context);
 	}
 
 	/**
@@ -1025,45 +867,16 @@ export class Tasks {
 
 	/** Idempotent: undepending an already-absent dependency is a no-op. Never starts, completes, or focuses work — only removes the edge. */
 	undepend(id: string, dependencyId: string, context: TaskEventContext = {}): Artifact {
-		return this.events.atomic(() => {
-			const task = this.require(id);
-			const dependency = this.require(dependencyId);
-			const removed = this.artifacts.unlink({ from: id, relation: "depends_on", to: dependencyId }, context);
-			if (removed) this.appendEvent({ taskId: id, type: "dependency_removed", reason: context.reason }, context);
-			// Only meaningful if the removed edge was itself unmet -- removing an already-satisfied
-			// dependency, or removing one from a task that was already unblocked, changes nothing.
-			if (removed && task.status === "todo" && dependency.status !== "done") {
-				const stillBlocking = this.dependencyIds(id).filter((remainingId) => this.require(remainingId).status !== "done");
-				if (stillBlocking.length === 0) this.appendEvent({ taskId: id, type: "became_ready" }, context);
-			}
-			return this.show(id);
-		});
+		return this.taskEdges.undepend(id, dependencyId, context);
 	}
 
 	contain(parentId: string, childId: string, context: TaskEventContext = {}): Artifact {
-		return this.events.atomic(() => {
-			this.require(parentId);
-			this.require(childId);
-			const alreadyContained = this.relationships(parentId).some(
-				(edge) => edge.relation === "contains" && edge.from === parentId && edge.to === childId,
-			);
-			this.artifacts.link({ from: parentId, relation: "contains", to: childId }, context);
-			this.artifacts.link({ from: childId, relation: "part_of", to: parentId }, context);
-			if (!alreadyContained) this.appendEvent({ taskId: parentId, type: "containment_added", reason: context.reason }, context);
-			return this.show(parentId);
-		});
+		return this.taskEdges.contain(parentId, childId, context);
 	}
 
 	/** Idempotent: removing an already-absent containment is a no-op. Both contains/part_of edges are removed atomically. */
 	uncontain(parentId: string, childId: string, context: TaskEventContext = {}): Artifact {
-		return this.events.atomic(() => {
-			this.require(parentId);
-			this.require(childId);
-			const removedContains = this.artifacts.unlink({ from: parentId, relation: "contains", to: childId }, context);
-			this.artifacts.unlink({ from: childId, relation: "part_of", to: parentId }, context);
-			if (removedContains) this.appendEvent({ taskId: parentId, type: "containment_removed", reason: context.reason }, context);
-			return this.show(parentId);
-		});
+		return this.taskEdges.uncontain(parentId, childId, context);
 	}
 
 	private descendantIds(rootTaskId: string, projectTaskIds: string[]): Set<string> {