@danypops/papyrus 0.3.0 → 0.5.0

package/src/adapters/sqlite-task-event-store.ts

@@ -0,0 +1,92 @@
+import type { Db } from "../db.ts";
+import { inTransaction } from "../db.ts";
+import {
+	normalizeTaskHistoryQuery,
+	validateTaskEvent,
+	type AppendTaskEvent,
+	type TaskEvent,
+	type TaskEventEvidence,
+	type TaskEventType,
+	type TaskHistoryPage,
+	type TaskHistoryQuery,
+	type TaskLifecycleStatus,
+} from "../domain/task-event.ts";
+import type { TaskEventStore } from "../ports/task-event-store.ts";
+
+interface TaskEventRow {
+	id: number;
+	task_id: string;
+	occurred_at: string;
+	event_type: TaskEventType;
+	actor: string;
+	source: string;
+	session_id: string | null;
+	reason: string | null;
+	from_status: TaskLifecycleStatus | null;
+	to_status: TaskLifecycleStatus | null;
+	attempt_id: string | null;
+	evidence_json: string | null;
+	event_schema_version: 1;
+}
+
+function mapRow(row: TaskEventRow): TaskEvent {
+	return {
+		id: row.id,
+		taskId: row.task_id,
+		occurredAt: row.occurred_at,
+		type: row.event_type,
+		actor: row.actor,
+		source: row.source,
+		...(row.session_id === null ? {} : { sessionId: row.session_id }),
+		...(row.reason === null ? {} : { reason: row.reason }),
+		...(row.from_status === null ? {} : { fromStatus: row.from_status }),
+		...(row.to_status === null ? {} : { toStatus: row.to_status }),
+		...(row.attempt_id === null ? {} : { attemptId: row.attempt_id }),
+		...(row.evidence_json === null ? {} : { evidence: JSON.parse(row.evidence_json) as TaskEventEvidence }),
+		schemaVersion: row.event_schema_version,
+	};
+}
+
+export class SQLiteTaskEventStore implements TaskEventStore {
+	constructor(private readonly db: Db) {}
+
+	atomic<T>(operation: () => T): T { return inTransaction(this.db, operation); }
+
+	append(input: AppendTaskEvent): TaskEvent {
+		const event = validateTaskEvent(input);
+		const result = this.db.prepare(`
+			INSERT INTO task_events (
+				task_id, occurred_at, event_type, actor, source, session_id, reason,
+				from_status, to_status, attempt_id, evidence_json, event_schema_version
+			) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1)
+		`).run(
+			event.taskId,
+			new Date().toISOString(),
+			event.type,
+			event.actor,
+			event.source,
+			event.sessionId ?? null,
+			event.reason ?? null,
+			event.fromStatus ?? null,
+			event.toStatus ?? null,
+			event.attemptId ?? null,
+			event.evidence === undefined ? null : JSON.stringify(event.evidence),
+		);
+		return mapRow(this.db.prepare("SELECT * FROM task_events WHERE id = ?").get(result.lastInsertRowid) as TaskEventRow);
+	}
+
+	history(taskId: string, query: TaskHistoryQuery = {}): TaskHistoryPage {
+		const { limit, direction, cursor } = normalizeTaskHistoryQuery(query);
+		const comparator = direction === "desc" ? "<" : ">";
+		const order = direction === "desc" ? "DESC" : "ASC";
+		const rows = this.db.prepare(`
+			SELECT * FROM task_events
+			WHERE task_id = ? ${cursor === undefined ? "" : `AND id ${comparator} ?`}
+			ORDER BY occurred_at ${order}, id ${order}
+			LIMIT ?
+		`).all(...(cursor === undefined ? [taskId, limit + 1] : [taskId, cursor, limit + 1])) as TaskEventRow[];
+		const hasMore = rows.length > limit;
+		const events = rows.slice(0, limit).map(mapRow);
+		return { events, ...(hasMore ? { nextCursor: events.at(-1)!.id } : {}) };
+	}
+}

package/src/cli.ts

@@ -5,7 +5,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { connectPapyrusClient, type PapyrusClient } from "./client.ts";
-import { DAEMON_UNIT_NAME } from "./constants.ts";
+import { DAEMON_UNIT_NAME, TASK_EXECUTION_MAX_NODES } from "./constants.ts";
 import { serveMain } from "./daemon.ts";
 import type { GateResult } from "./domain/gate.ts";
 import type { TaskExecutionPlan } from "./task-execution.ts";
@@ -56,9 +56,12 @@ function installService(): void {
 const USAGE = `Usage:
   papyrus serve
   papyrus service <install|start|stop|restart|status>
-  papyrus migrate task-lifecycle [--json]
+  papyrus migrate task-history [--json]
+  papyrus skills run <id> [--arguments-json <json>] [--run-id <id>] [--json]
   papyrus tasks plan [--json]
+  papyrus tasks graph [--json]
   papyrus tasks active [--json]
+  papyrus tasks history <id> [--json]
   papyrus tasks focus <id> [--json]
   papyrus tasks complete <id> [--json]
   papyrus tasks start <id> [--json]
@@ -104,8 +107,8 @@ function planText(plan: TaskExecutionPlan): string {
 export async function runMigrationCli(args: string[], client: TaskCliClient): Promise<string> {
 	const json = args.includes("--json");
 	const positional = args.filter((arg) => arg !== "--json");
-	if (positional.length !== 1 || positional[0] !== "task-lifecycle") {
-		throw new Error("migrate requires exactly `task-lifecycle`");
+	if (positional.length !== 1 || positional[0] !== "task-history") {
+		throw new Error("migrate requires exactly `task-history`");
 	}
 	const result = await client.call<Record<string, never>, MigrationResult>("system.migrate", {});
 	if (json) return JSON.stringify(result);
@@ -113,6 +116,51 @@ export async function runMigrationCli(args: string[], client: TaskCliClient): Pr
 	return `Migrated schema ${result.from} → ${result.to}: ${result.applied.join(", ")}`;
 }
 
+export async function runSkillCli(args: string[], client: TaskCliClient): Promise<string> {
+	const json = args.includes("--json");
+	const positional: string[] = [];
+	let runId: string | undefined;
+	let arguments_: Record<string, unknown> = {};
+	for (let index = 0; index < args.length; index++) {
+		const argument = args[index]!;
+		if (argument === "--json") continue;
+		if (argument === "--run-id") {
+			runId = args[++index];
+			if (!runId) throw new Error("--run-id requires a value");
+			continue;
+		}
+		if (argument === "--arguments-json") {
+			const source = args[++index];
+			if (!source) throw new Error("--arguments-json requires a JSON object");
+			const parsed = JSON.parse(source) as unknown;
+			if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+				throw new Error("--arguments-json must be a JSON object");
+			}
+			arguments_ = parsed as Record<string, unknown>;
+			continue;
+		}
+		if (argument.startsWith("--")) throw new Error(`unknown skills option ${argument}`);
+		positional.push(argument);
+	}
+	if (positional.length !== 2 || positional[0] !== "run") throw new Error("skills requires `run <id>`");
+	const input: Record<string, unknown> = { id: positional[1], arguments: arguments_ };
+	if (runId) input["run_id"] = runId;
+	const result = await client.call<Record<string, unknown>, {
+		runId: string;
+		created: { tasks: string[]; rules: string[]; docs: string[] };
+		rootTaskIds: string[];
+		execution: TaskExecutionPlan;
+	}>("skills.run", input);
+	if (json) return JSON.stringify(result);
+	return [
+		`Created Skill run ${result.runId}: ${result.created.tasks.length} tasks, ${result.created.rules.length} rules, ${result.created.docs.length} docs`,
+		`Ready roots: ${result.rootTaskIds.join(", ") || "none"}`,
+		`Context docs: ${result.created.docs.join(", ") || "none"}`,
+		`Scoped rules: ${result.created.rules.join(", ") || "none"}`,
+		...result.execution.nodes.map((node) => `[${node.state}] ${node.id} ${node.title}`),
+	].join("\n");
+}
+
 export async function runTaskCli(args: string[], client: TaskCliClient): Promise<string> {
 	const json = args.includes("--json");
 	const positional = args.filter((arg) => arg !== "--json");
@@ -127,6 +175,15 @@ export async function runTaskCli(args: string[], client: TaskCliClient): Promise
 			human = active ? `Active: ${artifactLabel(active)}` : "No active task.";
 			break;
 		}
+		case "history": {
+			if (!id || dependencyId) throw new Error("tasks history requires exactly one task id");
+			const page = await client.call<{ id: string; direction: "desc" }, import("./domain/task-event.ts").TaskHistoryPage>("tasks.history", { id, direction: "desc" });
+			result = page;
+			human = page.events.length === 0
+				? `No recorded history for ${id}.`
+				: [...page.events].reverse().map((event) => `${event.occurredAt} ${event.type} ${event.fromStatus ?? "∅"} → ${event.toStatus ?? "∅"} · ${event.actor}/${event.source}${event.reason ? ` · ${event.reason}` : ""}`).join("\n");
+			break;
+		}
 		case "focus": {
 			if (!id || dependencyId) throw new Error("tasks focus requires exactly one task id");
 			const active = await client.call<{ id: string }, CliArtifact>("tasks.focus", { id });
@@ -134,6 +191,18 @@ export async function runTaskCli(args: string[], client: TaskCliClient): Promise
 			human = `Active: ${artifactLabel(active)}`;
 			break;
 		}
+		case "graph": {
+			if (id) throw new Error("tasks graph accepts no positional arguments");
+			const graph = await client.call<{ limit: number }, {
+				nodes: Array<{ dependencyIds: string[]; childIds: string[] }>;
+				rootIds: string[];
+			}>("tasks.graph", { limit: TASK_EXECUTION_MAX_NODES + 1 });
+			result = graph;
+			const dependencies = graph.nodes.reduce((count, node) => count + node.dependencyIds.length, 0);
+			const children = graph.nodes.reduce((count, node) => count + node.childIds.length, 0);
+			human = `Task graph: ${graph.nodes.length} nodes, ${graph.rootIds.length} roots, ${dependencies} dependencies, ${children} containment edges`;
+			break;
+		}
 		case "plan": {
 			if (id) throw new Error("tasks plan accepts no positional arguments");
 			const plan = await client.call<Record<string, never>, TaskExecutionPlan>("tasks.plan", {});
@@ -143,7 +212,7 @@ export async function runTaskCli(args: string[], client: TaskCliClient): Promise
 		}
 		case "complete": {
 			if (!id || dependencyId) throw new Error("tasks complete requires exactly one task id");
-			const completion = await client.call<{ id: string }, CliCompletion>("tasks.complete", { id });
+			const completion = await client.call<Record<string, string>, CliCompletion>("tasks.complete", { id, actor: "user", source: "cli" });
 			result = completion;
 			const lines = [`${completion.completed ? "Completed" : "Rejected"}: ${artifactLabel(completion.artifact)}`];
 			if (completion.focused) lines.push(`Active: ${artifactLabel(completion.focused)}`);
@@ -156,7 +225,7 @@ export async function runTaskCli(args: string[], client: TaskCliClient): Promise
 		}
 		case "start": {
 			if (!id || dependencyId) throw new Error("tasks start requires exactly one task id");
-			const artifact = await client.call<{ id: string }, CliArtifact>("tasks.start", { id });
+			const artifact = await client.call<Record<string, string>, CliArtifact>("tasks.start", { id, actor: "user", source: "cli" });
 			result = artifact;
 			human = `Started: ${artifactLabel(artifact)}`;
 			break;
@@ -167,7 +236,7 @@ export async function runTaskCli(args: string[], client: TaskCliClient): Promise
 		case "cancel": {
 			if (!id || dependencyId) throw new Error(`tasks ${action} requires exactly one task id`);
 			const operation = `tasks.${action}` as "tasks.submit" | "tasks.reject" | "tasks.retry" | "tasks.cancel";
-			const artifact = await client.call<{ id: string }, CliArtifact>(operation, { id });
+			const artifact = await client.call<Record<string, string>, CliArtifact>(operation, { id, actor: "user", source: "cli" });
 			result = artifact;
 			human = `${action[0]!.toUpperCase()}${action.slice(1)}: ${artifactLabel(artifact)}`;
 			break;
@@ -183,7 +252,7 @@ export async function runTaskCli(args: string[], client: TaskCliClient): Promise
 			break;
 		}
 		default:
-			throw new Error("tasks action must be active, focus, plan, complete, start, submit, reject, retry, cancel, or depend");
+			throw new Error("tasks action must be active, focus, graph, plan, history, complete, start, submit, reject, retry, cancel, or depend");
 	}
 	return json ? JSON.stringify(result) : human;
 }
@@ -196,6 +265,11 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
 		console.log(await runTaskCli(args.slice(1), client));
 		return;
 	}
+	if (command === "skills") {
+		const client = await connectPapyrusClient();
+		console.log(await runSkillCli(args.slice(1), client));
+		return;
+	}
 	if (command === "migrate") {
 		const client = await connectPapyrusClient();
 		console.log(await runMigrationCli(args.slice(1), client));

package/src/constants.ts

@@ -7,7 +7,7 @@ export const DAEMON_PROBE_TIMEOUT_MS = 800;
 export const DAEMON_UNIT_NAME = "papyrus.service";
 export const DAEMON_DIR_ENV = "PAPYRUS_DAEMON_DIR";
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
-export const SQLITE_SCHEMA_VERSION = 2;
+export const SQLITE_SCHEMA_VERSION = 3;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
 export const DB_OPTIMIZE_INTERVAL_MS = 24 * 60 * 60_000;
@@ -32,12 +32,29 @@ export const TASK_GRAPH_HORIZONTAL_PAN_COLUMNS = 4;
 export const TASK_EXECUTION_MAX_NODES = 1_000;
 export const TASK_EXECUTION_MAX_EDGES = 10_000;
 export const TASK_EXECUTION_MAX_DEGREE = 100;
+/** Bounded parameterized Skill definitions and rendered workflow runs. */
+export const SKILL_MAX_INPUTS = 32;
+export const SKILL_MAX_ENUM_VALUES = 32;
+export const SKILL_MAX_BLUEPRINTS = 100;
+export const SKILL_MAX_LINKS = 500;
+export const SKILL_MAX_RENDERED_BYTES = 1_048_576;
+export const SKILL_RUN_ID_MAX_LENGTH = 64;
 /** Bounded automatic Pi continuations while a focused Papyrus Task remains. */
 export const TASK_DRIVER_MAX_TURNS = 20;
 export const TASK_DRIVER_MAX_UNCHANGED_TURNS = 6;
+/** Append-only Task chronology query and evidence bounds. */
+export const TASK_HISTORY_DEFAULT_LIMIT = 25;
+export const TASK_HISTORY_MAX_LIMIT = 100;
+export const TASK_EVENT_MAX_EVIDENCE_BYTES = 65_536;
+export const TASK_EVENT_ACTOR_MAX_LENGTH = 128;
+export const TASK_EVENT_REASON_MAX_LENGTH = 2_000;
 export const GRAPH_RENDER_PADDING_X = 2;
 export const GRAPH_RENDER_PADDING_Y = 1;
 export const GRAPH_RENDER_BOX_PADDING = 0;
+/** beautiful-mermaid routed layouts become unsafe on larger task graphs; use bounded line fallback. */
+export const GRAPH_RENDER_MAX_ROUTED_NODES = 48;
+export const GRAPH_RENDER_MAX_ROUTED_EDGES = 96;
+export const GRAPH_RENDER_MAX_FALLBACK_LINES = 200;
 
 /** Safe defaults and hard ceilings for graph expansion. */
 export const DEFAULT_GRAPH_DEPTH = 4;

package/src/db.ts

@@ -29,15 +29,38 @@ export interface Db {
 	close(): void;
 }
 
+const TRANSACTION_DEPTH = new WeakMap<object, number>();
+
 export function inTransaction<T>(db: Db, fn: () => T): T {
+	const depth = TRANSACTION_DEPTH.get(db as object) ?? 0;
+	if (depth > 0) {
+		const savepoint = `papyrus_nested_${depth}`;
+		db.exec(`SAVEPOINT ${savepoint}`);
+		TRANSACTION_DEPTH.set(db as object, depth + 1);
+		try {
+			const result = fn();
+			db.exec(`RELEASE SAVEPOINT ${savepoint}`);
+			return result;
+		} catch (error) {
+			db.exec(`ROLLBACK TO SAVEPOINT ${savepoint}`);
+			db.exec(`RELEASE SAVEPOINT ${savepoint}`);
+			throw error;
+		} finally {
+			TRANSACTION_DEPTH.set(db as object, depth);
+		}
+	}
+
 	db.exec("BEGIN IMMEDIATE");
+	TRANSACTION_DEPTH.set(db as object, 1);
 	try {
 		const result = fn();
 		db.exec("COMMIT");
 		return result;
-	} catch (e) {
+	} catch (error) {
 		db.exec("ROLLBACK");
-		throw e;
+		throw error;
+	} finally {
+		TRANSACTION_DEPTH.delete(db as object);
 	}
 }
 
@@ -79,6 +102,26 @@ CREATE TABLE IF NOT EXISTS task_focus (
 	task_id     TEXT NOT NULL UNIQUE REFERENCES artifacts(id),
 	updated_at  TEXT NOT NULL
 );
+CREATE TABLE IF NOT EXISTS task_events (
+	id                   INTEGER PRIMARY KEY AUTOINCREMENT,
+	task_id              TEXT NOT NULL REFERENCES artifacts(id),
+	occurred_at           TEXT NOT NULL,
+	event_type            TEXT NOT NULL,
+	actor                 TEXT NOT NULL,
+	source                TEXT NOT NULL,
+	session_id            TEXT,
+	reason                TEXT,
+	from_status           TEXT,
+	to_status             TEXT,
+	attempt_id             TEXT,
+	evidence_json         TEXT,
+	event_schema_version  INTEGER NOT NULL DEFAULT 1
+);
+CREATE INDEX IF NOT EXISTS task_events_history_idx ON task_events(task_id, occurred_at, id);
+CREATE TRIGGER IF NOT EXISTS task_events_no_update BEFORE UPDATE ON task_events
+BEGIN SELECT RAISE(ABORT, 'task_events are append-only'); END;
+CREATE TRIGGER IF NOT EXISTS task_events_no_delete BEFORE DELETE ON task_events
+BEGIN SELECT RAISE(ABORT, 'task_events are append-only'); END;
 `;
 
 const SEED_SQL = `
@@ -142,36 +185,66 @@ export function migrateDb(db: Db): MigrationResult {
 		throw new Error(`database schema ${from} is newer than supported ${SQLITE_SCHEMA_VERSION}`);
 	}
 	if (from === SQLITE_SCHEMA_VERSION) return { from, to: from, applied: [] };
-	if (from !== 1) throw new Error(`no explicit migration path from database schema ${from}`);
+	if (from !== 1 && from !== 2) throw new Error(`no explicit migration path from database schema ${from}`);
+	const applied: string[] = [];
 
 	inTransaction(db, () => {
-		db.exec(`
-			INSERT OR IGNORE INTO statuses VALUES ('todo','task');
-			INSERT OR IGNORE INTO statuses VALUES ('in-progress','task');
-			INSERT OR IGNORE INTO statuses VALUES ('review','task');
-			INSERT OR IGNORE INTO statuses VALUES ('rejected','task');
-			INSERT OR IGNORE INTO statuses VALUES ('done','task');
-			INSERT OR IGNORE INTO statuses VALUES ('canceled','task');
-			CREATE TABLE task_focus (
-				scope TEXT PRIMARY KEY CHECK (scope = 'global'),
-				task_id TEXT NOT NULL UNIQUE REFERENCES artifacts(id),
-				updated_at TEXT NOT NULL
-			);
-			INSERT INTO task_focus (scope, task_id, updated_at)
-			SELECT 'global', id, strftime('%Y-%m-%dT%H:%M:%fZ','now')
-			FROM artifacts WHERE kind = 'task' AND status = 'active'
-			ORDER BY updated_at DESC, id ASC LIMIT 1;
-			UPDATE artifacts SET status = CASE status
-				WHEN 'pending' THEN 'todo'
-				WHEN 'active' THEN 'in-progress'
-				WHEN 'failed' THEN 'rejected'
-				ELSE status END
-			WHERE kind = 'task';
-			DELETE FROM statuses WHERE kind = 'task' AND name IN ('pending', 'active', 'failed');
-			PRAGMA user_version = 2;
-		`);
+		if (schemaVersion(db) === 1) {
+			db.exec(`
+				INSERT OR IGNORE INTO statuses VALUES ('todo','task');
+				INSERT OR IGNORE INTO statuses VALUES ('in-progress','task');
+				INSERT OR IGNORE INTO statuses VALUES ('review','task');
+				INSERT OR IGNORE INTO statuses VALUES ('rejected','task');
+				INSERT OR IGNORE INTO statuses VALUES ('done','task');
+				INSERT OR IGNORE INTO statuses VALUES ('canceled','task');
+				CREATE TABLE task_focus (
+					scope TEXT PRIMARY KEY CHECK (scope = 'global'),
+					task_id TEXT NOT NULL UNIQUE REFERENCES artifacts(id),
+					updated_at TEXT NOT NULL
+				);
+				INSERT INTO task_focus (scope, task_id, updated_at)
+				SELECT 'global', id, strftime('%Y-%m-%dT%H:%M:%fZ','now')
+				FROM artifacts WHERE kind = 'task' AND status = 'active'
+				ORDER BY updated_at DESC, id ASC LIMIT 1;
+				UPDATE artifacts SET status = CASE status
+					WHEN 'pending' THEN 'todo'
+					WHEN 'active' THEN 'in-progress'
+					WHEN 'failed' THEN 'rejected'
+					ELSE status END
+				WHERE kind = 'task';
+				DELETE FROM statuses WHERE kind = 'task' AND name IN ('pending', 'active', 'failed');
+				PRAGMA user_version = 2;
+			`);
+			applied.push("task-lifecycle-and-focus");
+		}
+		if (schemaVersion(db) === 2) {
+			db.exec(`
+				CREATE TABLE task_events (
+					id INTEGER PRIMARY KEY AUTOINCREMENT,
+					task_id TEXT NOT NULL REFERENCES artifacts(id),
+					occurred_at TEXT NOT NULL,
+					event_type TEXT NOT NULL,
+					actor TEXT NOT NULL,
+					source TEXT NOT NULL,
+					session_id TEXT,
+					reason TEXT,
+					from_status TEXT,
+					to_status TEXT,
+					attempt_id TEXT,
+					evidence_json TEXT,
+					event_schema_version INTEGER NOT NULL DEFAULT 1
+				);
+				CREATE INDEX task_events_history_idx ON task_events(task_id, occurred_at, id);
+				CREATE TRIGGER task_events_no_update BEFORE UPDATE ON task_events
+				BEGIN SELECT RAISE(ABORT, 'task_events are append-only'); END;
+				CREATE TRIGGER task_events_no_delete BEFORE DELETE ON task_events
+				BEGIN SELECT RAISE(ABORT, 'task_events are append-only'); END;
+				PRAGMA user_version = 3;
+			`);
+			applied.push("task-history");
+		}
 	});
-	return { from, to: SQLITE_SCHEMA_VERSION, applied: ["task-lifecycle-and-focus"] };
+	return { from, to: schemaVersion(db), applied };
 }
 
 export function openDb(path: string): Db {

package/src/domain/skill-definition.ts

@@ -1,4 +1,10 @@
-import { SEED_RELATIONS } from "../constants.ts";
+import {
+	SEED_RELATIONS,
+	SKILL_MAX_BLUEPRINTS,
+	SKILL_MAX_ENUM_VALUES,
+	SKILL_MAX_INPUTS,
+	SKILL_MAX_LINKS,
+} from "../constants.ts";
 
 export type SkillArgumentValue = string | number | boolean;
 export type SkillInputType = "string" | "number" | "boolean";
@@ -59,13 +65,10 @@ export interface SkillDefinition {
 	links: SkillBlueprintLink[];
 }
 
-const MAX_INPUTS = 32;
-const MAX_ENUM_VALUES = 32;
-const MAX_BLUEPRINTS = 100;
-const MAX_LINKS = 500;
 const NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
 const PLACEHOLDER_PATTERN = /{{\s*([A-Za-z][A-Za-z0-9_-]{0,63})\s*}}/g;
 const INPUT_TYPES = new Set<SkillInputType>(["string", "number", "boolean"]);
+const RESERVED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 const RELATIONS = new Set<string>(SEED_RELATIONS);
 
 function record(value: unknown, label: string): Record<string, unknown> {
@@ -93,9 +96,10 @@ function validateArgumentValue(name: string, type: SkillInputType, value: unknow
 function validateInputs(value: unknown): Record<string, SkillInputDefinition> {
 	const source = record(value ?? {}, "skill inputs");
 	const entries = Object.entries(source);
-	if (entries.length > MAX_INPUTS) throw new Error(`skill inputs exceed ${MAX_INPUTS}`);
+	if (entries.length > SKILL_MAX_INPUTS) throw new Error(`skill inputs exceed ${SKILL_MAX_INPUTS}`);
 	const result: Record<string, SkillInputDefinition> = {};
 	for (const [name, raw] of entries) {
+		if (RESERVED_KEYS.has(name)) throw new Error(`reserved skill input name "${name}"`);
 		if (!NAME_PATTERN.test(name)) throw new Error(`invalid skill input name "${name}"`);
 		const input = record(raw, `skill input "${name}"`);
 		if (!INPUT_TYPES.has(input["type"] as SkillInputType)) throw new Error(`skill input "${name}" has unsupported type`);
@@ -108,7 +112,7 @@ function validateInputs(value: unknown): Record<string, SkillInputDefinition> {
 		if (input["default"] !== undefined) normalized.default = validateArgumentValue(name, type, input["default"]);
 		if (input["enum"] !== undefined) {
 			const values = array(input["enum"], `skill input "${name}" enum`);
-			if (values.length === 0 || values.length > MAX_ENUM_VALUES) throw new Error(`skill input "${name}" enum must contain 1-${MAX_ENUM_VALUES} values`);
+			if (values.length === 0 || values.length > SKILL_MAX_ENUM_VALUES) throw new Error(`skill input "${name}" enum must contain 1-${SKILL_MAX_ENUM_VALUES} values`);
 			normalized.enum = values.map((entry) => validateArgumentValue(name, type, entry));
 			if (normalized.default !== undefined && !normalized.enum.includes(normalized.default)) {
 				throw new Error(`skill input "${name}" default must be one of its enum values`);
@@ -162,7 +166,7 @@ export function validateSkillDefinition(value: unknown): SkillDefinition {
 	const rules = array(rawBlueprints["rules"] ?? [], "skill rule blueprints").map((entry) => validateBlueprint<SkillRuleBlueprint>(entry, "rule"));
 	const tasks = array(rawBlueprints["tasks"] ?? [], "skill task blueprints").map((entry) => validateBlueprint<SkillTaskBlueprint>(entry, "task"));
 	const all = [...docs, ...rules, ...tasks];
-	if (all.length === 0 || all.length > MAX_BLUEPRINTS) throw new Error(`skill blueprints must contain 1-${MAX_BLUEPRINTS} artifacts`);
+	if (all.length === 0 || all.length > SKILL_MAX_BLUEPRINTS) throw new Error(`skill blueprints must contain 1-${SKILL_MAX_BLUEPRINTS} artifacts`);
 	const refs = new Set<string>();
 	for (const blueprint of all) {
 		if (refs.has(blueprint.ref)) throw new Error(`duplicate skill blueprint ref "${blueprint.ref}"`);
@@ -179,7 +183,7 @@ export function validateSkillDefinition(value: unknown): SkillDefinition {
 	}
 	assertAcyclic(tasks);
 	for (const name of placeholders(all)) {
-		if (!(name in inputs)) throw new Error(`unknown skill input placeholder "${name}"`);
+		if (!Object.hasOwn(inputs, name)) throw new Error(`unknown skill input placeholder "${name}"`);
 	}
 	const links = array(source["links"] ?? [], "skill links").map((entry) => {
 		const link = record(entry, "skill link");
@@ -191,14 +195,14 @@ export function validateSkillDefinition(value: unknown): SkillDefinition {
 		if (!RELATIONS.has(relation)) throw new Error(`unknown skill link relation "${relation}"`);
 		return { from, relation, to };
 	});
-	if (links.length > MAX_LINKS) throw new Error(`skill links exceed ${MAX_LINKS}`);
+	if (links.length > SKILL_MAX_LINKS) throw new Error(`skill links exceed ${SKILL_MAX_LINKS}`);
 	return { version: 1, inputs, blueprints: { docs, rules, tasks }, links };
 }
 
 export function resolveSkillArguments(definition: SkillDefinition, value: unknown): Record<string, SkillArgumentValue> {
 	const source = record(value ?? {}, "skill arguments");
 	for (const name of Object.keys(source)) {
-		if (!(name in definition.inputs)) throw new Error(`unknown skill argument "${name}"`);
+		if (!Object.hasOwn(definition.inputs, name)) throw new Error(`unknown skill argument "${name}"`);
 	}
 	const result: Record<string, SkillArgumentValue> = {};
 	for (const [name, input] of Object.entries(definition.inputs)) {

package/src/domain/task-event.ts

@@ -0,0 +1,102 @@
+import {
+	TASK_EVENT_ACTOR_MAX_LENGTH,
+	TASK_EVENT_MAX_EVIDENCE_BYTES,
+	TASK_EVENT_REASON_MAX_LENGTH,
+	TASK_HISTORY_DEFAULT_LIMIT,
+	TASK_HISTORY_MAX_LIMIT,
+} from "../constants.ts";
+export type TaskLifecycleStatus = "todo" | "in-progress" | "review" | "rejected" | "done" | "canceled";
+
+export const TASK_EVENT_TYPES = [
+	"created",
+	"started",
+	"submitted",
+	"completion_attempted",
+	"gates_evaluated",
+	"review_rejected",
+	"retried",
+	"completed",
+	"canceled",
+] as const;
+
+export type TaskEventType = typeof TASK_EVENT_TYPES[number];
+export type TaskEventDirection = "asc" | "desc";
+
+export interface TaskEventContext {
+	actor?: string;
+	source?: string;
+	sessionId?: string;
+	reason?: string;
+}
+
+export interface TaskEventEvidence {
+	gates?: unknown;
+	checklist?: unknown;
+	result?: string;
+}
+
+export interface TaskEvent {
+	id: number;
+	taskId: string;
+	occurredAt: string;
+	type: TaskEventType;
+	actor: string;
+	source: string;
+	sessionId?: string;
+	reason?: string;
+	fromStatus?: TaskLifecycleStatus;
+	toStatus?: TaskLifecycleStatus;
+	attemptId?: string;
+	evidence?: TaskEventEvidence;
+	schemaVersion: 1;
+}
+
+export interface AppendTaskEvent {
+	taskId: string;
+	type: TaskEventType;
+	actor: string;
+	source: string;
+	sessionId?: string;
+	reason?: string;
+	fromStatus?: TaskLifecycleStatus;
+	toStatus?: TaskLifecycleStatus;
+	attemptId?: string;
+	evidence?: TaskEventEvidence;
+}
+
+export interface TaskHistoryQuery {
+	limit?: number;
+	cursor?: number;
+	direction?: TaskEventDirection;
+}
+
+export interface TaskHistoryPage {
+	events: TaskEvent[];
+	nextCursor?: number;
+}
+
+export function normalizeTaskHistoryQuery(query: TaskHistoryQuery = {}): Required<Pick<TaskHistoryQuery, "limit" | "direction">> & Pick<TaskHistoryQuery, "cursor"> {
+	const limit = query.limit ?? TASK_HISTORY_DEFAULT_LIMIT;
+	if (!Number.isInteger(limit) || limit < 1 || limit > TASK_HISTORY_MAX_LIMIT) {
+		throw new Error(`task history limit must be between 1 and ${TASK_HISTORY_MAX_LIMIT}`);
+	}
+	if (query.cursor !== undefined && (!Number.isInteger(query.cursor) || query.cursor < 1)) {
+		throw new Error("task history cursor must be a positive integer");
+	}
+	if (query.direction !== undefined && query.direction !== "asc" && query.direction !== "desc") {
+		throw new Error("task history direction must be asc or desc");
+	}
+	return { limit, direction: query.direction ?? "desc", ...(query.cursor === undefined ? {} : { cursor: query.cursor }) };
+}
+
+export function validateTaskEvent(event: AppendTaskEvent): AppendTaskEvent {
+	for (const [field, value] of [["actor", event.actor], ["source", event.source]] as const) {
+		if (!value || value.length > TASK_EVENT_ACTOR_MAX_LENGTH) throw new Error(`${field} must be between 1 and ${TASK_EVENT_ACTOR_MAX_LENGTH} characters`);
+	}
+	if (event.sessionId !== undefined && event.sessionId.length > TASK_EVENT_ACTOR_MAX_LENGTH) throw new Error(`sessionId cannot exceed ${TASK_EVENT_ACTOR_MAX_LENGTH} characters`);
+	if (event.reason !== undefined && event.reason.length > TASK_EVENT_REASON_MAX_LENGTH) throw new Error(`reason cannot exceed ${TASK_EVENT_REASON_MAX_LENGTH} characters`);
+	if (event.evidence !== undefined && new TextEncoder().encode(JSON.stringify(event.evidence)).byteLength > TASK_EVENT_MAX_EVIDENCE_BYTES) {
+		throw new Error(`task event evidence cannot exceed ${TASK_EVENT_MAX_EVIDENCE_BYTES} bytes`);
+	}
+	return event;
+}