@danypops/papyrus 0.1.0

package/src/service.ts

@@ -0,0 +1,292 @@
+import { SERVICE_MAX_BODY_BYTES, VERSION } from "./constants.ts";
+import { openDb } from "./db.ts";
+import { SQLiteArtifactStore } from "./adapters/sqlite-artifact-store.ts";
+import { SQLiteGateRunner } from "./adapters/sqlite-gate-runner.ts";
+import type { CreateArtifactInput } from "./domain/artifact.ts";
+import type { Checklist } from "./domain/checklist.ts";
+import type { ArtifactStore } from "./ports/artifact-store.ts";
+import type { GateRunner } from "./ports/gate-runner.ts";
+import { Tasks } from "./task-service.ts";
+import {
+	createArtifactTemplate,
+	createDocument,
+	createRule,
+	createSkill,
+	linkDocument,
+	gateTaskWithRule,
+	instantiateTemplate,
+	listDocuments,
+	listRules,
+	listSkills,
+	previewRule,
+	showDocument,
+	showRule,
+	showSkill,
+	skillInvocation,
+	transitionDocument,
+	transitionRule,
+	transitionSkill,
+	type DocumentRelation,
+} from "./facades.ts";
+import { taskContext } from "./task-context.ts";
+
+export const EXPECTED_OPERATION_NAMES = [
+	"artifact.create",
+	"artifact.query",
+	"artifact.show",
+	"graph.link",
+	"graph.tree",
+	"graph.status",
+	"gates.run",
+	"rules.injectable",
+	"tasks.create",
+	"tasks.list",
+	"tasks.graph",
+	"tasks.show",
+	"tasks.start",
+	"tasks.complete",
+	"tasks.run_gates",
+	"tasks.set_checklist",
+	"tasks.context",
+	"tasks.fail",
+	"tasks.retry",
+	"tasks.depend",
+	"tasks.contain",
+	"docs.create",
+	"docs.list",
+	"docs.show",
+	"docs.activate",
+	"docs.archive",
+	"docs.reopen",
+	"docs.link",
+	"rules.create",
+	"rules.list",
+	"rules.show",
+	"rules.preview",
+	"rules.enable",
+	"rules.disable",
+	"rules.gate",
+	"skills.create",
+	"skills.create_template",
+	"skills.list",
+	"skills.show",
+	"skills.invoke",
+	"skills.enable",
+	"skills.disable",
+	"skills.instantiate",
+] as const;
+
+export type OperationName = typeof EXPECTED_OPERATION_NAMES[number];
+type OperationInput = Record<string, unknown>;
+type OperationHandler = (input: OperationInput) => unknown;
+
+export class UnknownOperationError extends Error {}
+export class PayloadTooLargeError extends Error {}
+
+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;
+}
+
+function normalizeCreateInput(input: OperationInput): CreateArtifactInput {
+	const { template_id, ...rest } = input;
+	return { ...rest, templateId: typeof template_id === "string" ? template_id : undefined } as CreateArtifactInput;
+}
+
+export interface PapyrusService {
+	operationNames(): OperationName[];
+	execute(operation: string, input?: OperationInput): Promise<unknown>;
+	checkpoint(): void;
+	optimize(): void;
+	close(): void;
+}
+
+function handlers(artifacts: ArtifactStore, gates: GateRunner, tasks: Tasks): Record<OperationName, OperationHandler> {
+	const taskFilter = (input: OperationInput) => ({
+		status: optionalString(input, "status"),
+		text: optionalString(input, "text"),
+		limit: optionalNumber(input, "limit"),
+	});
+	return {
+		"artifact.create": (input) => artifacts.create(normalizeCreateInput(input)),
+		"artifact.query": (input) => artifacts.query(input),
+		"artifact.show": (input) => artifacts.get(string(input, "id"), {
+			tree: input["tree"] === true,
+			depth: optionalNumber(input, "depth"),
+			maxNodes: optionalNumber(input, "max_nodes") ?? optionalNumber(input, "maxNodes"),
+		}),
+		"graph.link": (input) => {
+			artifacts.link({ from: string(input, "from"), relation: string(input, "relation"), to: string(input, "to") });
+			return { ok: true };
+		},
+		"graph.tree": (input) => artifacts.get(string(input, "id"), {
+			tree: true,
+			depth: optionalNumber(input, "depth"),
+			maxNodes: optionalNumber(input, "max_nodes") ?? optionalNumber(input, "maxNodes"),
+		}),
+		"graph.status": (input) => artifacts.setStatus(string(input, "id"), string(input, "status")),
+		"gates.run": (input) => gates.runAsync(string(input, "id")),
+		"rules.injectable": () => artifacts.query({ kind: "rule", status: "active" })
+			.map(({ id, title, body, extra }) => ({ id, title, body, extra })),
+		"tasks.create": (input) => tasks.create({
+			title: string(input, "title"),
+			body: optionalString(input, "body"),
+			status: optionalString(input, "status") as "pending" | "active" | "done" | "failed" | 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,
+		}),
+		"tasks.list": (input) => tasks.list(taskFilter(input)),
+		"tasks.graph": (input) => tasks.graph(taskFilter(input)),
+		"tasks.show": (input) => tasks.show(string(input, "id")),
+		"tasks.start": (input) => tasks.transition(string(input, "id"), "start"),
+		"tasks.complete": (input) => tasks.completeAsync(string(input, "id")),
+		"tasks.run_gates": (input) => tasks.runGates(string(input, "id")),
+		"tasks.set_checklist": (input) => tasks.setChecklist(string(input, "id"), input["checklist"] as Checklist),
+		"tasks.context": () => taskContext(artifacts),
+		"tasks.fail": (input) => tasks.transition(string(input, "id"), "fail"),
+		"tasks.retry": (input) => tasks.transition(string(input, "id"), "retry"),
+		"tasks.depend": (input) => tasks.depend(string(input, "id"), string(input, "dependency_id")),
+		"tasks.contain": (input) => tasks.contain(string(input, "parent_id"), string(input, "child_id")),
+		"docs.create": (input) => createDocument(artifacts, {
+			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"),
+		}),
+		"docs.list": (input) => listDocuments(artifacts, taskFilter(input)),
+		"docs.show": (input) => showDocument(artifacts, string(input, "id")),
+		"docs.activate": (input) => transitionDocument(artifacts, string(input, "id"), "activate"),
+		"docs.archive": (input) => transitionDocument(artifacts, string(input, "id"), "archive"),
+		"docs.reopen": (input) => transitionDocument(artifacts, string(input, "id"), "reopen"),
+		"docs.link": (input) => linkDocument(artifacts, string(input, "id"), string(input, "relation") as DocumentRelation, string(input, "target_id")),
+		"rules.create": (input) => createRule(artifacts, {
+			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,
+		}),
+		"rules.list": (input) => listRules(artifacts, taskFilter(input)),
+		"rules.show": (input) => showRule(artifacts, string(input, "id")),
+		"rules.preview": (input) => previewRule(artifacts, string(input, "id")),
+		"rules.enable": (input) => transitionRule(artifacts, string(input, "id"), "enable"),
+		"rules.disable": (input) => transitionRule(artifacts, string(input, "id"), "disable"),
+		"rules.gate": (input) => gateTaskWithRule(artifacts, string(input, "id"), string(input, "task_id")),
+		"skills.create": (input) => createSkill(artifacts, {
+			title: string(input, "title"), body: optionalString(input, "body"), trigger: optionalString(input, "trigger"),
+			steps: input["steps"] as string[] | undefined, tools: input["tools"] as string[] | undefined,
+			labels: input["labels"] as string[] | undefined, extra: input["extra"] as Record<string, unknown> | undefined,
+		}),
+		"skills.create_template": (input) => createArtifactTemplate(artifacts, {
+			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,
+		}),
+		"skills.list": (input) => listSkills(artifacts, taskFilter(input)),
+		"skills.show": (input) => showSkill(artifacts, string(input, "id")),
+		"skills.invoke": (input) => skillInvocation(artifacts, string(input, "id")),
+		"skills.enable": (input) => transitionSkill(artifacts, string(input, "id"), "enable"),
+		"skills.disable": (input) => transitionSkill(artifacts, string(input, "id"), "disable"),
+		"skills.instantiate": (input) => instantiateTemplate(artifacts, string(input, "template_id"), normalizeCreateInput(input)),
+	};
+}
+
+export function createPapyrusService(path: string): PapyrusService {
+	const db = openDb(path);
+	const artifacts = new SQLiteArtifactStore(db);
+	const gates = new SQLiteGateRunner(db);
+	const tasks = new Tasks(artifacts, gates);
+	const registry = handlers(artifacts, gates, tasks);
+	return {
+		operationNames: () => [...EXPECTED_OPERATION_NAMES],
+		async execute(operation, input = {}) {
+			const handler = registry[operation as OperationName];
+			if (!handler) throw new UnknownOperationError(`unknown operation "${operation}"`);
+			return handler(input);
+		},
+		checkpoint: () => { db.exec("PRAGMA wal_checkpoint(PASSIVE)"); },
+		optimize: () => { db.exec("PRAGMA optimize"); },
+		close: () => {
+			db.exec("PRAGMA optimize");
+			db.close();
+		},
+	};
+}
+
+function json(value: unknown, init?: ResponseInit): Response {
+	return Response.json(value, init);
+}
+
+async function readOperationBody(request: Request): Promise<{ op?: unknown; input?: unknown }> {
+	const declared = Number(request.headers.get("content-length"));
+	if (Number.isFinite(declared) && declared > SERVICE_MAX_BODY_BYTES) {
+		throw new PayloadTooLargeError(`request exceeds ${SERVICE_MAX_BODY_BYTES} bytes`);
+	}
+	if (!request.body) return {};
+	const reader = request.body.getReader();
+	const chunks: Uint8Array[] = [];
+	let size = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		size += value.byteLength;
+		if (size > SERVICE_MAX_BODY_BYTES) {
+			await reader.cancel();
+			throw new PayloadTooLargeError(`request exceeds ${SERVICE_MAX_BODY_BYTES} bytes`);
+		}
+		chunks.push(value);
+	}
+	const bytes = new Uint8Array(size);
+	let offset = 0;
+	for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+	return JSON.parse(new TextDecoder().decode(bytes)) as { op?: unknown; input?: unknown };
+}
+
+export function createApp(deps: { service: PapyrusService; token: string }): { fetch(request: Request): Promise<Response> } {
+	return {
+		async fetch(request: Request): Promise<Response> {
+			if (request.headers.get("authorization") !== `Bearer ${deps.token}`) {
+				return json({ error: "missing or invalid bearer token" }, { status: 401 });
+			}
+			const url = new URL(request.url);
+			if (request.method === "GET" && url.pathname === "/health") {
+				return json({ ok: true, version: VERSION });
+			}
+			if (request.method === "GET" && url.pathname === "/api/v1/ops") {
+				return json({ operations: deps.service.operationNames() });
+			}
+			if (request.method === "POST" && url.pathname === "/api/v1/ops") {
+				try {
+					const body = await readOperationBody(request);
+					if (typeof body.op !== "string") return json({ error: "op is required" }, { status: 400 });
+					const input = body.input === undefined ? {} : body.input;
+					if (typeof input !== "object" || input === null || Array.isArray(input)) {
+						return json({ error: "input must be an object" }, { status: 400 });
+					}
+					return json({ result: await deps.service.execute(body.op, input as OperationInput) });
+				} catch (error) {
+					const status = error instanceof PayloadTooLargeError ? 413 : error instanceof UnknownOperationError ? 404 : 400;
+					return json({ error: error instanceof Error ? error.message : String(error) }, { status });
+				}
+			}
+			return json({ error: "not found" }, { status: 404 });
+		},
+	};
+}

package/src/task-context.ts

@@ -0,0 +1,52 @@
+import type { Artifact } from "./domain/artifact.ts";
+import type { ArtifactStore } from "./ports/artifact-store.ts";
+import {
+	TASK_CONTEXT_ACTIVE_LIMIT,
+	TASK_CONTEXT_FAILED_LIMIT,
+	TASK_RECONCILIATION_INSTRUCTION,
+} from "./constants.ts";
+
+interface Gate {
+	type?: unknown;
+	target?: unknown;
+	expect?: unknown;
+}
+
+function gatesFrom(task: Artifact): Gate[] {
+	const gates = task.extra["gates"];
+	return Array.isArray(gates) ? gates as Gate[] : [];
+}
+
+function renderGate(gate: Gate): string {
+	const type = typeof gate.type === "string" ? gate.type : "gate";
+	const target = typeof gate.target === "string" ? gate.target : "unspecified";
+	const expect = typeof gate.expect === "string" && gate.expect.length > 0 ? ` = ${gate.expect}` : "";
+	return `${type}: ${target}${expect}`;
+}
+
+function renderCurrent(task: Artifact): string[] {
+	const desired = task.body.trim() || task.title;
+	const gates = gatesFrom(task);
+	return [
+		`Current: ${task.title} (${task.id})`,
+		`Desired: ${desired}`,
+		`Verify: ${gates.length > 0 ? gates.map(renderGate).join("; ") : "inspect the desired outcome; no automated gates configured"}`,
+	];
+}
+
+export function taskContext(artifacts: ArtifactStore): string | null {
+	const tasks = artifacts.query({ kind: "task" }).sort((left, right) => left.updated_at.localeCompare(right.updated_at));
+	const open = tasks.filter((task) => task.status !== "done");
+	if (open.length === 0) return null;
+
+	const done = tasks.length - open.length;
+	const active = open.filter((task) => task.status === "active").slice(0, TASK_CONTEXT_ACTIVE_LIMIT);
+	const next = open.find((task) => task.status === "pending");
+	const failed = open.filter((task) => task.status === "failed").slice(0, TASK_CONTEXT_FAILED_LIMIT);
+	const lines = [`Progress: ${done}/${tasks.length} done`];
+	for (const task of active) lines.push(...renderCurrent(task));
+	if (next) lines.push(`Next: ${next.title} (${next.id})`);
+	if (failed.length > 0) lines.push(`Blocked: ${failed.map((task) => `${task.title} (${task.id})`).join(", ")}`);
+	lines.push("", TASK_RECONCILIATION_INSTRUCTION);
+	return lines.join("\n");
+}

package/src/task-graph-view.ts

@@ -0,0 +1,34 @@
+import type { DisplayGraph, DisplayGraphEdge } from "./domain/display-graph.ts";
+import type { TaskGraph } from "./task-service.ts";
+
+export type TaskGraphView = "dependencies" | "composition";
+
+export function projectTaskGraph(graph: TaskGraph, view: TaskGraphView): DisplayGraph {
+	const edges: DisplayGraphEdge[] = [];
+	const seen = new Set<string>();
+	const addEdge = (edge: DisplayGraphEdge): void => {
+		const key = `${edge.from}\u0000${edge.to}\u0000${edge.label ?? ""}`;
+		if (seen.has(key)) return;
+		seen.add(key);
+		edges.push(edge);
+	};
+
+	for (const node of graph.nodes) {
+		if (view === "dependencies") {
+			for (const dependencyId of node.dependencyIds) {
+				addEdge({ from: dependencyId, to: node.task.id, label: "unlocks" });
+			}
+		} else {
+			for (const childId of node.childIds) addEdge({ from: node.task.id, to: childId });
+		}
+	}
+
+	const connected = new Set(edges.flatMap((edge) => [edge.from, edge.to]));
+	return {
+		direction: "TD",
+		nodes: graph.nodes
+			.filter((node) => connected.has(node.task.id))
+			.map((node) => ({ id: node.task.id, label: node.task.title, status: node.task.status })),
+		edges: edges.filter((edge) => connected.has(edge.from) && connected.has(edge.to)),
+	};
+}

package/src/task-relationship-view.ts

@@ -0,0 +1,39 @@
+import type { Artifact, ArtifactEdge } from "./domain/artifact.ts";
+import type { DisplayGraph, DisplayGraphEdge, DisplayGraphNode } from "./domain/display-graph.ts";
+import type { TaskGraph } from "./task-service.ts";
+
+function normalizeEdge(edge: ArtifactEdge): DisplayGraphEdge {
+	if (edge.relation === "part_of") return { from: edge.to, to: edge.from };
+	if (edge.relation === "depends_on") return { from: edge.to, to: edge.from, label: "unlocks" };
+	if (edge.relation === "contains") return { from: edge.from, to: edge.to };
+	return { from: edge.from, to: edge.to, label: edge.relation };
+}
+
+function fallbackLabel(id: string): string {
+	return id.replace(/-[a-z0-9]{4}$/i, "").replaceAll("-", " ");
+}
+
+export function projectTaskRelationships(task: Artifact, graph?: TaskGraph): DisplayGraph {
+	const taskNodes = new Map(graph?.nodes.map((node) => [node.task.id, node.task]) ?? []);
+	taskNodes.set(task.id, task);
+	const edges: DisplayGraphEdge[] = [];
+	const seenEdges = new Set<string>();
+	const nodeIds = new Set<string>();
+	for (const artifactEdge of task.edges ?? []) {
+		const edge = normalizeEdge(artifactEdge);
+		const key = `${edge.from}\u0000${edge.to}\u0000${edge.label ?? ""}`;
+		if (!seenEdges.has(key)) {
+			seenEdges.add(key);
+			edges.push(edge);
+		}
+		nodeIds.add(edge.from);
+		nodeIds.add(edge.to);
+	}
+	const nodes: DisplayGraphNode[] = [...nodeIds].map((id) => {
+		const artifact = taskNodes.get(id);
+		return artifact
+			? { id, label: artifact.title, status: artifact.status }
+			: { id, label: fallbackLabel(id) };
+	});
+	return { direction: "LR", nodes, edges };
+}

package/src/task-service.ts

@@ -0,0 +1,176 @@
+import type { Artifact } from "./domain/artifact.ts";
+import { validateChecklist, type Checklist } from "./domain/checklist.ts";
+import type { Gate, GateResult } from "./domain/gate.ts";
+import type { ArtifactStore } from "./ports/artifact-store.ts";
+import type { GateRunner } from "./ports/gate-runner.ts";
+
+export interface TaskFilter {
+	status?: string;
+	text?: string;
+	limit?: number;
+}
+
+export interface CreateTaskInput {
+	title: string;
+	body?: string;
+	status?: "pending" | "active" | "done" | "failed";
+	labels?: string[];
+	extra?: Record<string, unknown>;
+	gates?: Gate[];
+	checklist?: Checklist;
+	templateId?: string;
+	parentId?: string;
+	dependsOn?: string[];
+}
+
+export type TaskTransition = "start" | "fail" | "retry";
+
+export interface TaskCompletion {
+	artifact: Artifact;
+	gates: GateResult[];
+	completed: boolean;
+}
+
+export interface TaskNode {
+	task: Artifact;
+	parentIds: string[];
+	childIds: string[];
+	dependencyIds: string[];
+}
+
+export interface TaskGraph {
+	nodes: TaskNode[];
+	rootIds: string[];
+}
+
+const TASK_TRANSITIONS: Record<TaskTransition, { from: string[]; to: string }> = {
+	start: { from: ["pending"], to: "active" },
+	fail: { from: ["pending", "active"], to: "failed" },
+	retry: { from: ["failed"], to: "pending" },
+};
+
+export class Tasks {
+	constructor(
+		private readonly artifacts: ArtifactStore,
+		private readonly gates: GateRunner,
+	) {}
+
+	private require(id: string): Artifact {
+		const artifact = this.artifacts.get(id);
+		if (!artifact) throw new Error(`task artifact "${id}" not found`);
+		if (artifact.kind !== "task") throw new Error(`artifact "${id}" is not a task`);
+		return artifact;
+	}
+
+	create(input: CreateTaskInput): Artifact {
+		if (input.parentId) this.require(input.parentId);
+		for (const dependency of input.dependsOn ?? []) this.require(dependency);
+		const extra: Record<string, unknown> = { ...(input.extra ?? {}) };
+		if (input.gates !== undefined) extra["gates"] = input.gates;
+		if (input.checklist !== undefined) extra["checklist"] = validateChecklist(input.checklist);
+		const task = this.artifacts.create({
+			kind: "task",
+			title: input.title,
+			body: input.body,
+			status: input.status,
+			labels: input.labels,
+			extra,
+			templateId: input.templateId,
+		});
+		if (input.parentId) this.contain(input.parentId, task.id);
+		for (const dependency of input.dependsOn ?? []) this.depend(task.id, dependency);
+		return this.show(task.id);
+	}
+
+	list(filter: TaskFilter = {}): Artifact[] {
+		return this.artifacts.query({ kind: "task", ...filter });
+	}
+
+	graph(filter: TaskFilter = {}): TaskGraph {
+		const tasks = this.list(filter);
+		const byId = new Map(tasks.map((task) => [task.id, task]));
+		const nodes = new Map(tasks.map((task) => [task.id, {
+			task,
+			parentIds: [] as string[],
+			childIds: [] as string[],
+			dependencyIds: [] as string[],
+		}]));
+		for (const edge of this.artifacts.relationships({ kind: "task", artifactIds: [...byId.keys()] })) {
+			if (!byId.has(edge.from) || !byId.has(edge.to)) continue;
+			const parentId = edge.relation === "contains" ? edge.from : edge.relation === "part_of" ? edge.to : undefined;
+			const childId = edge.relation === "contains" ? edge.to : edge.relation === "part_of" ? edge.from : undefined;
+			if (parentId && childId && parentId !== childId) {
+				const parent = nodes.get(parentId)!;
+				const child = nodes.get(childId)!;
+				if (!parent.childIds.includes(childId)) parent.childIds.push(childId);
+				if (!child.parentIds.includes(parentId)) child.parentIds.push(parentId);
+			}
+			if (edge.relation === "depends_on") {
+				const node = nodes.get(edge.from)!;
+				if (!node.dependencyIds.includes(edge.to)) node.dependencyIds.push(edge.to);
+			}
+		}
+		return {
+			nodes: tasks.map((task) => nodes.get(task.id)!),
+			rootIds: tasks.filter((task) => nodes.get(task.id)!.parentIds.length === 0).map((task) => task.id),
+		};
+	}
+
+	show(id: string): Artifact {
+		this.require(id);
+		return this.artifacts.get(id, { tree: true })!;
+	}
+
+	transition(id: string, action: TaskTransition): Artifact {
+		const task = this.require(id);
+		const transition = TASK_TRANSITIONS[action];
+		if (!transition.from.includes(task.status)) throw new Error(`cannot ${action} task from ${task.status}`);
+		return this.artifacts.setStatus(id, transition.to)!;
+	}
+
+	complete(id: string): TaskCompletion {
+		const task = this.requireActive(id);
+		const results = this.gates.run(id);
+		if (results.some((gate) => !gate.passed)) return { artifact: task, gates: results, completed: false };
+		return { artifact: this.artifacts.setStatus(id, "done")!, gates: results, completed: true };
+	}
+
+	async completeAsync(id: string): Promise<TaskCompletion> {
+		this.requireActive(id);
+		const results = await this.gates.runAsync(id);
+		if (results.some((gate) => !gate.passed)) return { artifact: this.require(id), gates: results, completed: false };
+		const current = this.requireActive(id);
+		return { artifact: this.artifacts.setStatus(current.id, "done")!, gates: results, completed: true };
+	}
+
+	runGates(id: string): Promise<GateResult[]> {
+		this.require(id);
+		return this.gates.runAsync(id);
+	}
+
+	setChecklist(id: string, checklist: Checklist): Artifact {
+		const task = this.require(id);
+		return this.artifacts.setExtra(id, { ...task.extra, checklist: validateChecklist(checklist) })!;
+	}
+
+	depend(id: string, dependencyId: string): Artifact {
+		this.require(id);
+		this.require(dependencyId);
+		this.artifacts.link({ from: id, relation: "depends_on", to: dependencyId });
+		return this.show(id);
+	}
+
+	contain(parentId: string, childId: string): Artifact {
+		this.require(parentId);
+		this.require(childId);
+		this.artifacts.link({ from: parentId, relation: "contains", to: childId });
+		this.artifacts.link({ from: childId, relation: "part_of", to: parentId });
+		return this.show(parentId);
+	}
+
+	private requireActive(id: string): Artifact {
+		const task = this.require(id);
+		if (task.status !== "active") throw new Error(`cannot complete task from ${task.status}`);
+		return task;
+	}
+}