@danypops/papyrus 0.2.0 → 0.3.0

package/src/service.ts

@@ -1,14 +1,15 @@
-import { SERVICE_MAX_BODY_BYTES } from "./constants.ts";
+import { SERVICE_MAX_BODY_BYTES, SQLITE_SCHEMA_VERSION } from "./constants.ts";
 import { VERSION } from "./version.ts";
-import { openDb } from "./db.ts";
+import { migrateDb, openDb, schemaVersion } from "./db.ts";
 import { SQLiteArtifactStore } from "./adapters/sqlite-artifact-store.ts";
 import { SQLiteGateRunner } from "./adapters/sqlite-gate-runner.ts";
+import { SQLiteTaskFocusStore } from "./adapters/sqlite-task-focus-store.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 { projectTaskExecution } from "./task-execution.ts";
-import { Tasks } from "./task-service.ts";
+import { Tasks, type TaskStatus } from "./task-service.ts";
 import {
 	createArtifactTemplate,
 	createDocument,
@@ -33,6 +34,7 @@ import {
 import { taskContext } from "./task-context.ts";
 
 export const EXPECTED_OPERATION_NAMES = [
+	"system.migrate",
 	"artifact.create",
 	"artifact.query",
 	"artifact.show",
@@ -46,13 +48,17 @@ export const EXPECTED_OPERATION_NAMES = [
 	"tasks.graph",
 	"tasks.plan",
 	"tasks.show",
+	"tasks.active",
+	"tasks.focus",
 	"tasks.start",
+	"tasks.submit",
 	"tasks.complete",
 	"tasks.run_gates",
 	"tasks.set_checklist",
 	"tasks.context",
-	"tasks.fail",
+	"tasks.reject",
 	"tasks.retry",
+	"tasks.cancel",
 	"tasks.depend",
 	"tasks.contain",
 	"docs.create",
@@ -84,6 +90,7 @@ type OperationInput = Record<string, unknown>;
 type OperationHandler = (input: OperationInput) => unknown;
 
 export class UnknownOperationError extends Error {}
+export class MigrationRequiredError extends Error {}
 export class PayloadTooLargeError extends Error {}
 
 function string(input: OperationInput, key: string): string {
@@ -111,21 +118,34 @@ function normalizeCreateInput(input: OperationInput): CreateArtifactInput {
 	return { ...rest, templateId: typeof template_id === "string" ? template_id : undefined } as CreateArtifactInput;
 }
 
+export interface SchemaState {
+	current: number;
+	required: number;
+	migrationRequired: boolean;
+}
+
 export interface PapyrusService {
 	operationNames(): OperationName[];
+	schemaState(): SchemaState;
 	execute(operation: string, input?: OperationInput): Promise<unknown>;
 	checkpoint(): void;
 	optimize(): void;
 	close(): void;
 }
 
-function handlers(artifacts: ArtifactStore, gates: GateRunner, tasks: Tasks): Record<OperationName, OperationHandler> {
+function handlers(
+	artifacts: ArtifactStore,
+	gates: GateRunner,
+	tasks: Tasks,
+	migrate: () => unknown,
+): Record<OperationName, OperationHandler> {
 	const taskFilter = (input: OperationInput) => ({
 		status: optionalString(input, "status"),
 		text: optionalString(input, "text"),
 		limit: optionalNumber(input, "limit"),
 	});
 	return {
+		"system.migrate": () => migrate(),
 		"artifact.create": (input) => artifacts.create(normalizeCreateInput(input)),
 		"artifact.query": (input) => artifacts.query(input),
 		"artifact.show": (input) => artifacts.get(string(input, "id"), {
@@ -156,7 +176,7 @@ function handlers(artifacts: ArtifactStore, gates: GateRunner, tasks: Tasks): Re
 		"tasks.create": (input) => tasks.create({
 			title: string(input, "title"),
 			body: optionalString(input, "body"),
-			status: optionalString(input, "status") as "pending" | "active" | "done" | "failed" | undefined,
+			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"],
@@ -169,13 +189,17 @@ function handlers(artifacts: ArtifactStore, gates: GateRunner, tasks: Tasks): Re
 		"tasks.graph": (input) => tasks.graph(taskFilter(input)),
 		"tasks.plan": (input) => projectTaskExecution(tasks.graph(taskFilter(input))),
 		"tasks.show": (input) => tasks.show(string(input, "id")),
+		"tasks.active": () => tasks.active(),
+		"tasks.focus": (input) => tasks.focus(string(input, "id")),
 		"tasks.start": (input) => tasks.transition(string(input, "id"), "start"),
+		"tasks.submit": (input) => tasks.transition(string(input, "id"), "submit"),
 		"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.context": () => taskContext(artifacts, tasks.active()?.id),
+		"tasks.reject": (input) => tasks.transition(string(input, "id"), "reject"),
 		"tasks.retry": (input) => tasks.transition(string(input, "id"), "retry"),
+		"tasks.cancel": (input) => tasks.transition(string(input, "id"), "cancel"),
 		"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, {
@@ -223,13 +247,22 @@ 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);
+	const focus = new SQLiteTaskFocusStore(db);
+	const tasks = new Tasks(artifacts, gates, focus);
+	const registry = handlers(artifacts, gates, tasks, () => migrateDb(db));
+	const state = (): SchemaState => {
+		const current = schemaVersion(db);
+		return { current, required: SQLITE_SCHEMA_VERSION, migrationRequired: current !== SQLITE_SCHEMA_VERSION };
+	};
 	return {
 		operationNames: () => [...EXPECTED_OPERATION_NAMES],
+		schemaState: state,
 		async execute(operation, input = {}) {
 			const handler = registry[operation as OperationName];
 			if (!handler) throw new UnknownOperationError(`unknown operation "${operation}"`);
+			if (operation !== "system.migrate" && state().migrationRequired) {
+				throw new MigrationRequiredError("database migration required; run `papyrus migrate task-lifecycle`");
+			}
 			return handler(input);
 		},
 		checkpoint: () => { db.exec("PRAGMA wal_checkpoint(PASSIVE)"); },
@@ -278,7 +311,7 @@ export function createApp(deps: { service: PapyrusService; token: string }): { f
 			}
 			const url = new URL(request.url);
 			if (request.method === "GET" && url.pathname === "/health") {
-				return json({ ok: true, version: VERSION });
+				return json({ ok: true, version: VERSION, schema: deps.service.schemaState() });
 			}
 			if (request.method === "GET" && url.pathname === "/api/v1/ops") {
 				return json({ operations: deps.service.operationNames() });

package/src/task-context.ts

@@ -1,8 +1,8 @@
 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_CONTEXT_CURRENT_LIMIT,
+	TASK_CONTEXT_REJECTED_LIMIT,
 	TASK_RECONCILIATION_INSTRUCTION,
 } from "./constants.ts";
 
@@ -34,19 +34,20 @@ function renderCurrent(task: Artifact): string[] {
 	];
 }
 
-export function taskContext(artifacts: ArtifactStore): string | null {
+export function taskContext(artifacts: ArtifactStore, activeTaskId?: string): 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");
+	const open = tasks.filter((task) => task.status !== "done" && task.status !== "canceled");
 	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 active = activeTaskId ? open.find((task) => task.id === activeTaskId) : undefined;
+	const current = active ? [active] : open.filter((task) => task.status === "in-progress" || task.status === "review").slice(0, TASK_CONTEXT_CURRENT_LIMIT);
+	const next = open.find((task) => task.status === "todo");
+	const rejected = open.filter((task) => task.status === "rejected").slice(0, TASK_CONTEXT_REJECTED_LIMIT);
 	const lines = [`Progress: ${done}/${tasks.length} done`];
-	for (const task of active) lines.push(...renderCurrent(task));
+	for (const task of current) 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(", ")}`);
+	if (rejected.length > 0) lines.push(`Rejected: ${rejected.map((task) => `${task.title} (${task.id})`).join(", ")}`);
 	lines.push("", TASK_RECONCILIATION_INSTRUCTION);
 	return lines.join("\n");
 }

package/src/task-execution.ts

@@ -1,12 +1,22 @@
 import { TASK_EXECUTION_MAX_DEGREE, TASK_EXECUTION_MAX_EDGES, TASK_EXECUTION_MAX_NODES } from "./constants.ts";
 import type { TaskGraph } from "./task-service.ts";
 
-export type TaskExecutionState = "done" | "active" | "ready" | "blocked" | "failed" | "invalid";
+export type TaskExecutionState =
+	| "todo"
+	| "in-progress"
+	| "review"
+	| "rejected"
+	| "done"
+	| "canceled"
+	| "ready"
+	| "blocked"
+	| "invalid";
 
 export interface TaskExecutionNode {
 	id: string;
 	title: string;
 	status: string;
+	active: boolean;
 	state: TaskExecutionState;
 	layer: number | null;
 	prerequisiteIds: string[];
@@ -21,8 +31,10 @@ export interface TaskExecutionPlan {
 
 function executionState(status: string, invalid: boolean, prerequisitesDone: boolean): TaskExecutionState {
 	if (invalid) return "invalid";
-	if (status === "done" || status === "active" || status === "failed") return status;
-	if (status === "pending" && prerequisitesDone) return "ready";
+	if (status === "todo") return prerequisitesDone ? "ready" : "blocked";
+	if (["in-progress", "review", "rejected", "done", "canceled"].includes(status)) {
+		return status as TaskExecutionState;
+	}
 	return "blocked";
 }
 
@@ -96,6 +108,7 @@ export function projectTaskExecution(graph: TaskGraph): TaskExecutionPlan {
 				id: node.task.id,
 				title: node.task.title,
 				status: node.task.status,
+				active: node.active === true,
 				state,
 				layer: layerById.get(node.task.id) ?? null,
 				prerequisiteIds,

package/src/task-graph-view.ts

@@ -5,11 +5,14 @@ import type { TaskGraph } from "./task-service.ts";
 export type TaskGraphView = "execution" | "dependencies" | "composition";
 
 const EXECUTION_GLYPHS: Record<TaskExecutionState, string> = {
+	todo: "○",
+	"in-progress": "●",
+	review: "◆",
+	rejected: "▲",
 	done: "■",
-	active: "●",
+	canceled: "×",
 	ready: "◇",
 	blocked: "○",
-	failed: "▲",
 	invalid: "!",
 };
 
@@ -39,7 +42,7 @@ export function projectTaskGraph(graph: TaskGraph, view: TaskGraphView): Display
 	const nodes = view === "execution"
 		? projectTaskExecution(graph).nodes.map((node) => ({
 			id: node.id,
-			label: `${EXECUTION_GLYPHS[node.state]} ${node.title} · ${node.layer === null ? "no layer" : `layer ${node.layer + 1}`} · ${node.state}`,
+			label: `${node.active ? "▶ " : ""}${EXECUTION_GLYPHS[node.state]} ${node.title} · ${node.layer === null ? "no layer" : `layer ${node.layer + 1}`} · ${node.state}`,
 			status: node.state,
 		}))
 		: graph.nodes

package/src/task-service.ts

@@ -1,9 +1,10 @@
 import { TASK_EXECUTION_MAX_DEGREE, TASK_EXECUTION_MAX_EDGES, TASK_EXECUTION_MAX_NODES } from "./constants.ts";
 import type { Artifact } from "./domain/artifact.ts";
-import { validateChecklist, type Checklist } from "./domain/checklist.ts";
+import { checklistEntries, validateChecklist, type Checklist, type ProofReference } 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";
+import { InMemoryTaskFocusStore, type TaskFocusStore } from "./ports/task-focus-store.ts";
 import { assertDependencyEdgeAllowed } from "./task-execution.ts";
 
 export interface TaskFilter {
@@ -12,10 +13,12 @@ export interface TaskFilter {
 	limit?: number;
 }
 
+export type TaskStatus = "todo" | "in-progress" | "review" | "rejected" | "done" | "canceled";
+
 export interface CreateTaskInput {
 	title: string;
 	body?: string;
-	status?: "pending" | "active" | "done" | "failed";
+	status?: TaskStatus;
 	labels?: string[];
 	extra?: Record<string, unknown>;
 	gates?: Gate[];
@@ -25,23 +28,32 @@ export interface CreateTaskInput {
 	dependsOn?: string[];
 }
 
-export type TaskTransition = "start" | "fail" | "retry";
+export type TaskTransition = "start" | "submit" | "reject" | "retry" | "cancel";
 
 export interface TaskBlockage {
 	artifact: Artifact;
 	dependencyIds: string[];
 }
 
+export interface ChecklistReview {
+	item: string;
+	proof: ProofReference[];
+	accepted: boolean;
+	reason?: string;
+}
+
 export interface TaskCompletion {
 	artifact: Artifact;
 	gates: GateResult[];
+	checklist: ChecklistReview[];
 	completed: boolean;
-	started: Artifact[];
+	focused: Artifact | null;
 	blocked: TaskBlockage[];
 }
 
 export interface TaskNode {
 	task: Artifact;
+	active?: boolean;
 	parentIds: string[];
 	childIds: string[];
 	dependencyIds: string[];
@@ -52,16 +64,19 @@ export interface TaskGraph {
 	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" },
+const TASK_TRANSITIONS: Record<TaskTransition, { from: TaskStatus[]; to: TaskStatus }> = {
+	start: { from: ["todo"], to: "in-progress" },
+	submit: { from: ["in-progress"], to: "review" },
+	reject: { from: ["review"], to: "rejected" },
+	retry: { from: ["rejected"], to: "in-progress" },
+	cancel: { from: ["todo", "in-progress", "review", "rejected"], to: "canceled" },
 };
 
 export class Tasks {
 	constructor(
 		private readonly artifacts: ArtifactStore,
 		private readonly gates: GateRunner,
+		private readonly focusStore: TaskFocusStore = new InMemoryTaskFocusStore(),
 	) {}
 
 	private require(id: string): Artifact {
@@ -108,8 +123,10 @@ export class Tasks {
 			throw new Error(`task execution graph exceeds ${TASK_EXECUTION_MAX_NODES} nodes`);
 		}
 		const byId = new Map(tasks.map((task) => [task.id, task]));
+		const focusedId = this.focusStore.get();
 		const nodes = new Map(tasks.map((task) => [task.id, {
 			task,
+			active: task.id === focusedId,
 			parentIds: [] as string[],
 			childIds: [] as string[],
 			dependencyIds: [] as string[],
@@ -148,34 +165,63 @@ export class Tasks {
 		return this.artifacts.get(id, { tree: true })!;
 	}
 
+	active(): Artifact | null {
+		const id = this.focusStore.get();
+		if (!id) return null;
+		const task = this.artifacts.get(id);
+		if (!task || task.kind !== "task" || task.status === "done" || task.status === "canceled") {
+			this.focusStore.clear(id);
+			return null;
+		}
+		return task;
+	}
+
+	focus(id: string): Artifact {
+		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);
+		return task;
+	}
+
 	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}`);
+		if (!transition.from.includes(task.status as TaskStatus)) throw new Error(`cannot ${action} task from ${task.status}`);
 		if (action === "start") {
 			const blocking = this.dependencyIds(id).filter((dependencyId) => this.require(dependencyId).status !== "done");
 			if (blocking.length > 0) throw new Error(`task "${id}" is blocked by dependencies: ${blocking.join(", ")}`);
+			this.focusStore.set(id);
 		}
-		return this.artifacts.setStatus(id, transition.to)!;
+		const updated = this.artifacts.setStatus(id, transition.to)!;
+		if (action === "start" || action === "retry") this.propagateProgressToAncestors(id);
+		if (action === "retry") this.focusStore.set(id);
+		if (action === "cancel") this.focusStore.clear(id);
+		return updated;
 	}
 
 	complete(id: string): TaskCompletion {
-		const task = this.requireActive(id);
+		const task = this.requireReview(id);
+		const checklist = this.reviewChecklist(task);
 		const results = this.gates.run(id);
-		if (results.some((gate) => !gate.passed)) {
-			return { artifact: task, gates: results, completed: false, started: [], blocked: [] };
+		if (results.some((gate) => !gate.passed) || checklist.some((item) => !item.accepted)) {
+			const artifact = this.artifacts.setStatus(id, "rejected")!;
+			return { artifact, gates: results, checklist, completed: false, focused: this.active(), blocked: [] };
 		}
-		return this.finish(id, results);
+		return this.finish(id, results, checklist);
 	}
 
 	async completeAsync(id: string): Promise<TaskCompletion> {
-		this.requireActive(id);
+		const task = this.requireReview(id);
+		const checklist = this.reviewChecklist(task);
 		const results = await this.gates.runAsync(id);
-		if (results.some((gate) => !gate.passed)) {
-			return { artifact: this.require(id), gates: results, completed: false, started: [], blocked: [] };
+		if (results.some((gate) => !gate.passed) || checklist.some((item) => !item.accepted)) {
+			const artifact = this.artifacts.setStatus(id, "rejected")!;
+			return { artifact, gates: results, checklist, completed: false, focused: this.active(), blocked: [] };
 		}
-		const current = this.requireActive(id);
-		return this.finish(current.id, results);
+		const current = this.requireReview(id);
+		return this.finish(current.id, results, checklist);
 	}
 
 	runGates(id: string): Promise<GateResult[]> {
@@ -226,6 +272,39 @@ export class Tasks {
 		return relationships;
 	}
 
+	private parentIds(id: string): string[] {
+		return this.relationships(id)
+			.flatMap((edge) => {
+				if (edge.relation === "part_of" && edge.from === id) return [edge.to];
+				if (edge.relation === "contains" && edge.to === id) return [edge.from];
+				return [];
+			})
+			.filter((parentId, index, ids) => ids.indexOf(parentId) === index);
+	}
+
+	private propagateProgressToAncestors(id: string): void {
+		const pending = this.parentIds(id);
+		const visited = new Set<string>();
+		while (pending.length > 0) {
+			const parentId = pending.shift()!;
+			if (visited.has(parentId)) continue;
+			if (visited.size >= TASK_EXECUTION_MAX_NODES) throw new Error("task ancestry exceeds execution node bound");
+			visited.add(parentId);
+			const parent = this.require(parentId);
+			if (parent.status === "todo") this.artifacts.setStatus(parentId, "in-progress");
+			pending.push(...this.parentIds(parentId));
+		}
+	}
+
+	private reviewChecklist(task: Artifact): ChecklistReview[] {
+		return checklistEntries(task.extra["checklist"]).map((entry) => ({
+			item: entry.item,
+			proof: entry.proof,
+			accepted: !entry.legacy && entry.proof.length > 0,
+			...((entry.legacy || entry.proof.length === 0) ? { reason: "typed proof reference required" } : {}),
+		}));
+	}
+
 	private dependencyIds(id: string): string[] {
 		const ids = this.relationships(id)
 			.filter((edge) => edge.relation === "depends_on" && edge.from === id)
@@ -236,7 +315,7 @@ export class Tasks {
 		return ids;
 	}
 
-	private finish(id: string, gates: GateResult[]): TaskCompletion {
+	private finish(id: string, gates: GateResult[], checklist: ChecklistReview[]): TaskCompletion {
 		const successorIds = this.relationships(id)
 			.filter((edge) => edge.relation === "depends_on" && edge.to === id)
 			.map((edge) => edge.from);
@@ -244,25 +323,29 @@ export class Tasks {
 			throw new Error(`task "${id}" exceeds ${TASK_EXECUTION_MAX_DEGREE} successors`);
 		}
 		const artifact = this.artifacts.setStatus(id, "done")!;
-		const started: Artifact[] = [];
+		this.focusStore.clear(id);
 		const blocked: TaskBlockage[] = [];
-		for (const successorId of successorIds) {
+		let focused: Artifact | null = null;
+		for (const successorId of [...successorIds].sort()) {
 			const successor = this.require(successorId);
-			if (successor.status !== "pending") continue;
+			if (successor.status === "done" || successor.status === "canceled") continue;
 			const dependencyIds = this.dependencyIds(successorId)
 				.filter((dependencyId) => this.require(dependencyId).status !== "done");
 			if (dependencyIds.length > 0) {
 				blocked.push({ artifact: successor, dependencyIds });
 				continue;
 			}
-			started.push(this.artifacts.setStatus(successorId, "active")!);
+			if (!focused) {
+				this.focusStore.set(successor.id);
+				focused = successor;
+			}
 		}
-		return { artifact, gates, completed: true, started, blocked };
+		return { artifact, gates, checklist, completed: true, focused, blocked };
 	}
 
-	private requireActive(id: string): Artifact {
+	private requireReview(id: string): Artifact {
 		const task = this.require(id);
-		if (task.status !== "active") throw new Error(`cannot complete task from ${task.status}`);
+		if (task.status !== "review") throw new Error(`cannot complete task from ${task.status}`);
 		return task;
 	}
 }