@danypops/papyrus 0.1.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@danypops/papyrus",
+  "version": "0.1.0",
+  "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
+  "type": "module",
+  "keywords": ["pi-package"],
+  "bin": {
+    "papyrus": "src/cli.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "cli": "bun src/cli.ts",
+    "serve": "bun src/cli.ts serve",
+    "service:install": "bun src/cli.ts service install",
+    "guard:install": "git config core.hooksPath .githooks"
+  },
+  "pi": {
+    "extensions": ["extension/src/index.ts"]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "bun-types": "latest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DanyPops/papyrus.git"
+  },
+  "homepage": "https://github.com/DanyPops/papyrus#readme",
+  "bugs": {
+    "url": "https://github.com/DanyPops/papyrus/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["src", "extension", "README.md"],
+  "dependencies": {
+    "beautiful-mermaid": "1.1.3"
+  }
+}

package/src/adapters/sqlite-artifact-store.ts

@@ -0,0 +1,64 @@
+import type { Db } from "../db.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import type {
+	Artifact,
+	ArtifactEdge,
+	ArtifactGraphOptions,
+	ArtifactLink,
+	ArtifactQuery,
+	CreateArtifactInput,
+	RelationshipQuery,
+} from "../domain/artifact.ts";
+import { createArtifact, getArtifact, linkArtifacts, queryArtifacts, updateExtra, updateStatus } from "../ops.ts";
+
+export class SQLiteArtifactStore implements ArtifactStore {
+	constructor(private readonly db: Db) {}
+
+	create(input: CreateArtifactInput): Artifact {
+		return createArtifact(this.db, input);
+	}
+
+	get(id: string, options?: ArtifactGraphOptions): Artifact | null {
+		return getArtifact(this.db, id, options);
+	}
+
+	query(filter: ArtifactQuery): Artifact[] {
+		return queryArtifacts(this.db, filter);
+	}
+
+	link(link: ArtifactLink): void {
+		linkArtifacts(this.db, link.from, link.relation, link.to);
+	}
+
+	setStatus(id: string, status: string): Artifact | null {
+		return updateStatus(this.db, id, status);
+	}
+
+	setExtra(id: string, extra: Record<string, unknown>): Artifact | null {
+		return updateExtra(this.db, id, extra);
+	}
+
+	relationships(filter: RelationshipQuery = {}): ArtifactEdge[] {
+		if (filter.artifactIds?.length === 0) return [];
+		const conditions: string[] = [];
+		const parameters: unknown[] = [];
+		if (filter.kind) {
+			conditions.push("source.kind = ? AND target.kind = ?");
+			parameters.push(filter.kind, filter.kind);
+		}
+		if (filter.artifactIds) {
+			const placeholders = filter.artifactIds.map(() => "?").join(", ");
+			conditions.push(`(edges.from_id IN (${placeholders}) OR edges.to_id IN (${placeholders}))`);
+			parameters.push(...filter.artifactIds, ...filter.artifactIds);
+		}
+		const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+		return this.db.prepare(`
+			SELECT edges.from_id AS "from", edges.relation, edges.to_id AS "to"
+			FROM edges
+			JOIN artifacts AS source ON source.id = edges.from_id
+			JOIN artifacts AS target ON target.id = edges.to_id
+			${where}
+			ORDER BY edges.rowid
+		`).all(...parameters) as ArtifactEdge[];
+	}
+}

package/src/adapters/sqlite-gate-runner.ts

@@ -0,0 +1,16 @@
+import type { Db } from "../db.ts";
+import type { GateResult } from "../domain/gate.ts";
+import type { GateRunner } from "../ports/gate-runner.ts";
+import { runGates, runGatesAsync } from "../ops.ts";
+
+export class SQLiteGateRunner implements GateRunner {
+	constructor(private readonly db: Db) {}
+
+	run(artifactId: string): GateResult[] {
+		return runGates(this.db, artifactId);
+	}
+
+	runAsync(artifactId: string): Promise<GateResult[]> {
+		return runGatesAsync(this.db, artifactId);
+	}
+}

package/src/cli.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env bun
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DAEMON_UNIT_NAME } from "./constants.ts";
+import { serveMain } from "./daemon.ts";
+
+export interface SystemdUnitOptions {
+	bunBin: string;
+	cliPath: string;
+}
+
+export function renderSystemdUnit(options: SystemdUnitOptions): string {
+	return `[Unit]
+Description=Papyrus graph artifact service
+After=default.target
+
+[Service]
+Type=simple
+ExecStart=${options.bunBin} ${options.cliPath} serve
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+function unitPath(): string {
+	const configHome = process.env["XDG_CONFIG_HOME"] ?? join(homedir(), ".config");
+	return join(configHome, "systemd", "user", DAEMON_UNIT_NAME);
+}
+
+function systemctl(...args: string[]): void {
+	execFileSync("systemctl", ["--user", ...args], { stdio: "inherit" });
+}
+
+function installService(): void {
+	const path = unitPath();
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, renderSystemdUnit({
+		bunBin: process.execPath,
+		cliPath: fileURLToPath(import.meta.url),
+	}));
+	systemctl("daemon-reload");
+	systemctl("enable", DAEMON_UNIT_NAME);
+	systemctl("restart", DAEMON_UNIT_NAME);
+}
+
+function usage(): never {
+	console.error("Usage: papyrus serve | service <install|start|stop|restart|status>");
+	process.exit(2);
+}
+
+export function main(args: string[] = process.argv.slice(2)): void {
+	const [command, action] = args;
+	if (command === "serve") { serveMain(); return; }
+	if (command !== "service") usage();
+	switch (action) {
+		case "install": installService(); break;
+		case "start": systemctl("start", DAEMON_UNIT_NAME); break;
+		case "stop": systemctl("stop", DAEMON_UNIT_NAME); break;
+		case "restart": systemctl("restart", DAEMON_UNIT_NAME); break;
+		case "status": systemctl("status", DAEMON_UNIT_NAME); break;
+		default: usage();
+	}
+}
+
+if (import.meta.main) main();

package/src/client.ts

@@ -0,0 +1,59 @@
+import { DAEMON_CLIENT_TIMEOUT_MS, DAEMON_PROBE_TIMEOUT_MS } from "./constants.ts";
+import { daemonStateDir, readDaemonHandle } from "./daemon-state.ts";
+import type { OperationName } from "./service.ts";
+
+export type FetchAdapter = (request: Request) => Promise<Response>;
+
+export class PapyrusClient {
+	constructor(
+		private readonly baseUrl: string,
+		private readonly token: string,
+		private readonly fetchAdapter: FetchAdapter = (request) => fetch(request),
+		private readonly timeoutMs: number = DAEMON_CLIENT_TIMEOUT_MS,
+	) {}
+
+	private async request<T>(path: string, init: RequestInit = {}): Promise<T> {
+		const request = new Request(`${this.baseUrl}${path}`, {
+			...init,
+			headers: {
+				authorization: `Bearer ${this.token}`,
+				"content-type": "application/json",
+				...init.headers,
+			},
+			signal: init.signal ?? AbortSignal.timeout(this.timeoutMs),
+		});
+		const response = await this.fetchAdapter(request);
+		const body = await response.json() as { error?: string } & T;
+		if (!response.ok) throw new Error(body.error ?? `Papyrus daemon HTTP ${response.status}`);
+		return body;
+	}
+
+	health(): Promise<{ ok: true; version: string }> {
+		return this.request("/health");
+	}
+
+	async operations(): Promise<OperationName[]> {
+		const body = await this.request<{ operations: OperationName[] }>("/api/v1/ops");
+		return body.operations;
+	}
+
+	async call<Input extends Record<string, unknown>, Output>(operation: OperationName, input: Input): Promise<Output> {
+		const body = await this.request<{ result: Output }>("/api/v1/ops", {
+			method: "POST",
+			body: JSON.stringify({ op: operation, input }),
+		});
+		return body.result;
+	}
+}
+
+export async function connectPapyrusClient(dir: string = daemonStateDir()): Promise<PapyrusClient> {
+	const handle = readDaemonHandle(dir);
+	if (!handle) throw new Error("Papyrus daemon is not running; install/start papyrus.service");
+	const probe = new PapyrusClient(handle.baseUrl, handle.token, (request) => fetch(request), DAEMON_PROBE_TIMEOUT_MS);
+	try {
+		await probe.health();
+		return new PapyrusClient(handle.baseUrl, handle.token);
+	} catch {
+		throw new Error("Papyrus daemon state is stale or unreachable; restart papyrus.service");
+	}
+}

package/src/constants.ts

@@ -0,0 +1,113 @@
+export const VERSION = "0.1.0";
+
+/** Long-running daemon transport and state. */
+export const DAEMON_HOST = "127.0.0.1";
+export const DAEMON_PORT_FILE = "port";
+export const DAEMON_TOKEN_FILE = "token";
+export const DAEMON_CLIENT_TIMEOUT_MS = 15_000;
+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 = 1;
+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;
+export const GATE_COMMAND_TIMEOUT_MS = 30_000;
+export const GATE_TEST_TIMEOUT_MS = 60_000;
+export const GATE_OUTPUT_LIMIT = 200;
+export const GATE_MAX_BUFFER_BYTES = 1_048_576;
+
+/** Compact task-context limits keep recurring prompt injection bounded. */
+export const TASK_CONTEXT_ACTIVE_LIMIT = 3;
+export const TASK_CONTEXT_FAILED_LIMIT = 3;
+export const TASK_WIDGET_ACTIVE_LIMIT = 3;
+export const TASK_DETAIL_MIN_VISIBLE_LINES = 8;
+export const TASK_DETAIL_MAX_VISIBLE_LINES = 24;
+export const TASK_DETAIL_RESERVED_ROWS = 8;
+export const TASK_DETAIL_HORIZONTAL_PAN_COLUMNS = 4;
+export const TASK_GRAPH_MIN_VISIBLE_LINES = 8;
+export const TASK_GRAPH_MAX_VISIBLE_LINES = 30;
+export const TASK_GRAPH_RESERVED_ROWS = 8;
+export const TASK_GRAPH_HORIZONTAL_PAN_COLUMNS = 4;
+export const GRAPH_RENDER_PADDING_X = 2;
+export const GRAPH_RENDER_PADDING_Y = 1;
+export const GRAPH_RENDER_BOX_PADDING = 0;
+
+/** Safe defaults and hard ceilings for graph expansion. */
+export const DEFAULT_GRAPH_DEPTH = 4;
+export const DEFAULT_GRAPH_MAX_NODES = 100;
+export const MAX_GRAPH_DEPTH = 20;
+export const MAX_GRAPH_NODES = 1_000;
+
+/** Bounds for recursively rendered artifact metadata. */
+export const DEFAULT_METADATA_DEPTH = 6;
+export const DEFAULT_METADATA_ITEMS = 100;
+export const MAX_METADATA_DEPTH = 12;
+export const MAX_METADATA_ITEMS = 500;
+
+/** Reconciliation instruction appended whenever Papyrus has open work. */
+export const TASK_RECONCILIATION_INSTRUCTION = [
+	"Reconcile before concluding or moving on:",
+	'• For each current task, ask: "Did we accomplish this task?"',
+	"• If yes, run its gates before marking it done; a claim is not verification.",
+	"• If no, continue with the next concrete action toward its desired state.",
+	"• Address blocked work or explicitly leave it failed with the reason.",
+].join("\n");
+
+/** $XDG_DATA_HOME/papyrus/papyrus.db */
+export function dbPath(): string {
+	const xdg = process.env["XDG_DATA_HOME"] || `${process.env["HOME"]}/.local/share`;
+	return `${xdg}/papyrus/papyrus.db`;
+}
+
+/**
+ * Four purpose-built kinds — the enforced vocabulary.
+ *
+ * doc   = Knowledge — descriptive ("here is what the architecture looks like")
+ * task  = Work — prescriptive action items with gates and checklists
+ * rule  = Governance — context injection ("when doing X, follow Y").
+ *         Maps to AGENTS.md semantics: active rules with inject:true are
+ *         appended to the system prompt on before_agent_start.
+ * skill = Procedural — "when using X,Y,Z do A,B,C" (richer SKILL.md metadata)
+ */
+export const SEED_KINDS = [
+	{ name: "doc", description: "Knowledge — descriptive reference (specs, decisions, research, designs)" },
+	{ name: "task", description: "Work — action items with gates, checklists, and dependencies" },
+	{ name: "rule", description: "Governance — context injection (when doing X, follow Y). Maps to AGENTS.md" },
+	{ name: "skill", description: "Procedural — when using X,Y,Z do A,B,C (SKILL.md metadata)" },
+] as const;
+
+export const SEED_STATUSES = [
+	{ name: "draft", kind: "doc" },
+	{ name: "active", kind: "doc" },
+	{ name: "archived", kind: "doc" },
+	{ name: "pending", kind: "task" },
+	{ name: "active", kind: "task" },
+	{ name: "done", kind: "task" },
+	{ name: "failed", kind: "task" },
+	{ name: "active", kind: "rule" },
+	{ name: "deprecated", kind: "rule" },
+	{ name: "active", kind: "skill" },
+	{ name: "deprecated", kind: "skill" },
+] as const;
+
+/**
+ * Universal relation names — any kind can link to any kind.
+ *
+ * references:  source material (doc→doc, doc→task, doc→rule)
+ * implements:  this work satisfies that (task→doc, task→rule)
+ * follows:     this work obeys that (task→rule, task→skill)
+ * depends_on:  DAG ordering (task→task)
+ * documents:   describes (doc→task, doc→rule, doc→skill)
+ * blocks:      blocking relationship (task→task)
+ * supersedes:  replaces (doc→doc, rule→rule)
+ * relates_to:  catch-all (any→any)
+ * gates:       this rule gates that task (rule→task)
+ * triggers:    this skill applies to that work (skill→task)
+ */
+export const SEED_RELATIONS = [
+	"references", "implements", "follows", "depends_on",
+	"documents", "blocks", "supersedes", "relates_to",
+	"gates", "triggers", "contains", "part_of",
+] as const;

package/src/daemon-state.ts

@@ -0,0 +1,59 @@
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+	DAEMON_DIR_ENV,
+	DAEMON_HOST,
+	DAEMON_PORT_FILE,
+	DAEMON_TOKEN_FILE,
+} from "./constants.ts";
+
+export interface DaemonHandle {
+	baseUrl: string;
+	token: string;
+}
+
+export function daemonStateDir(
+	env: Record<string, string | undefined> = process.env,
+	home: string = homedir(),
+): string {
+	if (env[DAEMON_DIR_ENV]) return env[DAEMON_DIR_ENV];
+	if (env["XDG_RUNTIME_DIR"]) return join(env["XDG_RUNTIME_DIR"], "papyrus");
+	if (env["XDG_STATE_HOME"]) return join(env["XDG_STATE_HOME"], "papyrus");
+	return join(home, ".local", "state", "papyrus");
+}
+
+export function loadOrCreateToken(dir: string): string {
+	const path = join(dir, DAEMON_TOKEN_FILE);
+	try {
+		const token = readFileSync(path, "utf8").trim();
+		if (token) return token;
+	} catch {
+		// First daemon start.
+	}
+	const token = randomBytes(32).toString("hex");
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(path, `${token}\n`, { mode: 0o600 });
+	return token;
+}
+
+export function writeDaemonPort(dir: string, port: number): void {
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(join(dir, DAEMON_PORT_FILE), `${port}\n`, { mode: 0o600 });
+}
+
+export function clearDaemonPort(dir: string): void {
+	rmSync(join(dir, DAEMON_PORT_FILE), { force: true });
+}
+
+export function readDaemonHandle(dir: string): DaemonHandle | undefined {
+	try {
+		const token = readFileSync(join(dir, DAEMON_TOKEN_FILE), "utf8").trim();
+		const port = Number(readFileSync(join(dir, DAEMON_PORT_FILE), "utf8").trim());
+		if (!token || !Number.isInteger(port) || port < 1 || port > 65_535) return undefined;
+		return { baseUrl: `http://${DAEMON_HOST}:${port}`, token };
+	} catch {
+		return undefined;
+	}
+}

package/src/daemon.ts

@@ -0,0 +1,41 @@
+import { DAEMON_HOST, DB_OPTIMIZE_INTERVAL_MS, WAL_CHECKPOINT_INTERVAL_MS, dbPath } from "./constants.ts";
+import { clearDaemonPort, daemonStateDir, loadOrCreateToken, writeDaemonPort } from "./daemon-state.ts";
+import { createApp, createPapyrusService } from "./service.ts";
+
+/** Start the supervised, long-running Papyrus service. */
+export function serveMain(): void {
+	const stateDir = daemonStateDir();
+	const token = loadOrCreateToken(stateDir);
+	const service = createPapyrusService(dbPath());
+	const app = createApp({ service, token });
+	const server = Bun.serve({
+		hostname: DAEMON_HOST,
+		port: 0,
+		fetch: (request) => app.fetch(request),
+	});
+	if (!server.port) {
+		service.close();
+		throw new Error("Papyrus daemon failed to bind a listener");
+	}
+	writeDaemonPort(stateDir, server.port);
+	const checkpointTimer = setInterval(() => {
+		try { service.checkpoint(); } catch (error) { console.error("[papyrus] checkpoint failed", error); }
+	}, WAL_CHECKPOINT_INTERVAL_MS);
+	const optimizeTimer = setInterval(() => {
+		try { service.optimize(); } catch (error) { console.error("[papyrus] optimize failed", error); }
+	}, DB_OPTIMIZE_INTERVAL_MS);
+
+	let stopping = false;
+	const shutdown = () => {
+		if (stopping) return;
+		stopping = true;
+		clearInterval(checkpointTimer);
+		clearInterval(optimizeTimer);
+		clearDaemonPort(stateDir);
+		service.close();
+		void server.stop(true).finally(() => process.exit(0));
+	};
+	process.on("SIGINT", shutdown);
+	process.on("SIGTERM", shutdown);
+	console.error(`[papyrus] listening on ${DAEMON_HOST}:${server.port}`);
+}

package/src/db.ts

@@ -0,0 +1,138 @@
+/**
+ * db.ts — enforced-schema SQLite store for Papyrus.
+ * Dual-runtime: bun:sqlite (Bun) / node:sqlite (Node/pi host).
+ * Four kinds (doc/task/rule/skill) are FK-enforced; relations are universal (any→any).
+ */
+import { createRequire } from "node:module";
+import { mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { SQLITE_BUSY_TIMEOUT_MS, SQLITE_SCHEMA_VERSION } from "./constants.ts";
+
+const require_ = createRequire(import.meta.url);
+const IS_BUN = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
+const backend = IS_BUN
+	? (require_("bun:sqlite") as typeof import("bun:sqlite"))
+	: (require_("node:sqlite") as unknown as typeof import("bun:sqlite"));
+
+const DatabaseCtor = (
+	"DatabaseSync" in backend ? (backend as { DatabaseSync: unknown }).DatabaseSync : backend.Database
+) as new (path: string, opts?: { create?: boolean }) => Db;
+
+export interface DbStatement {
+	run(...params: unknown[]): { lastInsertRowid: number | bigint };
+	get(...params: unknown[]): unknown;
+	all(...params: unknown[]): unknown[];
+}
+export interface Db {
+	exec(sql: string): unknown;
+	prepare(sql: string): DbStatement;
+	close(): void;
+}
+
+export function inTransaction<T>(db: Db, fn: () => T): T {
+	db.exec("BEGIN IMMEDIATE");
+	try {
+		const result = fn();
+		db.exec("COMMIT");
+		return result;
+	} catch (e) {
+		db.exec("ROLLBACK");
+		throw e;
+	}
+}
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS kinds (
+	name        TEXT PRIMARY KEY,
+	description TEXT
+);
+CREATE TABLE IF NOT EXISTS statuses (
+	name        TEXT NOT NULL,
+	kind        TEXT NOT NULL REFERENCES kinds(name),
+	PRIMARY KEY (name, kind)
+);
+CREATE TABLE IF NOT EXISTS artifacts (
+	id          TEXT PRIMARY KEY,
+	kind        TEXT NOT NULL REFERENCES kinds(name),
+	title       TEXT NOT NULL,
+	status      TEXT NOT NULL,
+	subtype     TEXT DEFAULT '',
+	body        TEXT DEFAULT '',
+	labels      TEXT DEFAULT '[]',
+	extra       TEXT DEFAULT '{}',
+	created_at  TEXT NOT NULL,
+	updated_at  TEXT NOT NULL,
+	FOREIGN KEY (kind, status) REFERENCES statuses(kind, name)
+);
+CREATE TABLE IF NOT EXISTS edges (
+	from_id     TEXT NOT NULL REFERENCES artifacts(id),
+	relation    TEXT NOT NULL REFERENCES relation_names(name),
+	to_id       TEXT NOT NULL REFERENCES artifacts(id),
+	PRIMARY KEY (from_id, relation, to_id)
+);
+CREATE TABLE IF NOT EXISTS relation_names (
+	name        TEXT PRIMARY KEY,
+	description TEXT
+);
+`;
+
+const SEED_SQL = `
+INSERT OR IGNORE INTO kinds VALUES ('doc','Knowledge — what we know (specs, decisions, research, designs)');
+INSERT OR IGNORE INTO kinds VALUES ('task','Work — what we are doing (goals, steps, checklists)');
+INSERT OR IGNORE INTO kinds VALUES ('rule','Governance — when doing X, follow Y');
+INSERT OR IGNORE INTO kinds VALUES ('skill','Procedural — when using X,Y,Z do A,B,C');
+INSERT OR IGNORE INTO statuses VALUES ('draft','doc');
+INSERT OR IGNORE INTO statuses VALUES ('active','doc');
+INSERT OR IGNORE INTO statuses VALUES ('archived','doc');
+INSERT OR IGNORE INTO statuses VALUES ('pending','task');
+INSERT OR IGNORE INTO statuses VALUES ('active','task');
+INSERT OR IGNORE INTO statuses VALUES ('done','task');
+INSERT OR IGNORE INTO statuses VALUES ('failed','task');
+INSERT OR IGNORE INTO statuses VALUES ('active','rule');
+INSERT OR IGNORE INTO statuses VALUES ('deprecated','rule');
+INSERT OR IGNORE INTO statuses VALUES ('active','skill');
+INSERT OR IGNORE INTO statuses VALUES ('deprecated','skill');
+INSERT OR IGNORE INTO relation_names VALUES ('references','Source material (doc→doc, doc→task, doc→rule)');
+INSERT OR IGNORE INTO relation_names VALUES ('implements','This work satisfies that (task→doc, task→rule)');
+INSERT OR IGNORE INTO relation_names VALUES ('follows','This work obeys that (task→rule, task→skill)');
+INSERT OR IGNORE INTO relation_names VALUES ('depends_on','DAG ordering (task→task)');
+INSERT OR IGNORE INTO relation_names VALUES ('documents','Describes (doc→task, doc→rule, doc→skill)');
+INSERT OR IGNORE INTO relation_names VALUES ('blocks','Blocking relationship (task→task)');
+INSERT OR IGNORE INTO relation_names VALUES ('supersedes','Replaces (doc→doc, rule→rule)');
+INSERT OR IGNORE INTO relation_names VALUES ('relates_to','Catch-all (any→any)');
+INSERT OR IGNORE INTO relation_names VALUES ('gates','This rule gates that task (rule→task)');
+INSERT OR IGNORE INTO relation_names VALUES ('triggers','This skill applies to that work (skill→task)');
+INSERT OR IGNORE INTO relation_names VALUES ('contains','Parent contains a nested artifact (any→any)');
+INSERT OR IGNORE INTO relation_names VALUES ('part_of','Artifact belongs to a parent artifact (any→any)');
+CREATE INDEX IF NOT EXISTS edges_to_id_idx ON edges(to_id);
+`;
+
+function migrate(db: Db): void {
+	const row = db.prepare("PRAGMA user_version").get() as { user_version: number };
+	let version = row.user_version;
+	if (version > SQLITE_SCHEMA_VERSION) {
+		throw new Error(`database schema ${version} is newer than supported ${SQLITE_SCHEMA_VERSION}`);
+	}
+	if (version < 1) {
+		inTransaction(db, () => {
+			db.exec(SCHEMA);
+			db.exec(SEED_SQL);
+			db.exec("PRAGMA user_version = 1");
+		});
+		version = 1;
+	}
+	if (version !== SQLITE_SCHEMA_VERSION) {
+		throw new Error(`missing migration from schema ${version} to ${SQLITE_SCHEMA_VERSION}`);
+	}
+}
+
+export function openDb(path: string): Db {
+	if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
+	const db = IS_BUN ? new DatabaseCtor(path, { create: true }) : new DatabaseCtor(path);
+	db.exec("PRAGMA foreign_keys = ON");
+	db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
+	if (path !== ":memory:") db.exec("PRAGMA journal_mode = WAL");
+	migrate(db);
+	db.exec("PRAGMA optimize=0x10002");
+	return db;
+}

package/src/domain/artifact.ts

@@ -0,0 +1,56 @@
+export interface ArtifactEdge {
+	from: string;
+	relation: string;
+	to: string;
+}
+
+export interface Artifact {
+	id: string;
+	kind: string;
+	title: string;
+	status: string;
+	subtype: string;
+	body: string;
+	labels: string[];
+	extra: Record<string, unknown>;
+	created_at: string;
+	updated_at: string;
+	edges?: ArtifactEdge[];
+}
+
+export interface CreateArtifactInput {
+	kind?: string;
+	title?: string;
+	status?: string;
+	body?: string;
+	labels?: string[];
+	extra?: Record<string, unknown>;
+	id?: string;
+	subtype?: string;
+	templateId?: string;
+}
+
+export interface ArtifactQuery {
+	kind?: string;
+	status?: string;
+	text?: string;
+	labels?: string[];
+	limit?: number;
+}
+
+export interface ArtifactGraphOptions {
+	tree?: boolean;
+	depth?: number;
+	maxNodes?: number;
+}
+
+export interface ArtifactLink {
+	from: string;
+	relation: string;
+	to: string;
+}
+
+export interface RelationshipQuery {
+	kind?: string;
+	artifactIds?: string[];
+}