@danypops/papyrus 0.17.2 → 0.19.0

package/src/ops.ts

@@ -6,8 +6,10 @@ import { createRequire } from "node:module";
 import { exec } from "node:child_process";
 import type { Db } from "./db.ts";
 import { inTransaction } from "./db.ts";
-import { DEFAULT_STATUS_BY_KIND } from "./constants.ts";
+import { ARTIFACT_TRASH_RETENTION_MS, DEFAULT_STATUS_BY_KIND } from "./constants.ts";
 import type { Artifact, ArtifactQuery, CreateArtifactInput, UpdateArtifactInput } from "./domain/artifact.ts";
+import type { ArtifactTrashRecord } from "./domain/artifact-trash.ts";
+export type { ArtifactTrashRecord } from "./domain/artifact-trash.ts";
 import type { Gate, GateResult, GateRunOptions } from "./domain/gate.ts";
 import {
 	normalizeArtifactEventQuery,
@@ -288,6 +290,7 @@ export function queryArtifacts(db: Db, filter: ArtifactQuery): Artifact[] {
 	let sql = "SELECT * FROM artifacts";
 	const conditions: string[] = [];
 	const params: unknown[] = [];
+	if (!filter.includeTrashed) conditions.push("id NOT IN (SELECT artifact_id FROM artifact_trash)");
 	if (filter.kind) { conditions.push("kind = ?"); params.push(filter.kind); }
 	if (filter.status) { conditions.push("status = ?"); params.push(filter.status); }
 	if (filter.statuses) {
@@ -318,6 +321,108 @@ export function queryArtifacts(db: Db, filter: ArtifactQuery): Artifact[] {
 	return rows.map(rowToArtifact);
 }
 
+function rowToTrashRecord(row: Record<string, unknown>): ArtifactTrashRecord {
+	return {
+		artifactId: row["artifact_id"] as string,
+		trashedAt: row["trashed_at"] as string,
+		purgeAfter: row["purge_after"] as string,
+		...(row["reason"] == null ? {} : { reason: row["reason"] as string }),
+	};
+}
+
+export function getArtifactTrash(db: Db, id: string): ArtifactTrashRecord | null {
+	const row = db.prepare("SELECT artifact_id, trashed_at, purge_after, reason FROM artifact_trash WHERE artifact_id = ?").get(id) as Record<string, unknown> | null;
+	return row ? rowToTrashRecord(row) : null;
+}
+
+export function listArtifactTrash(db: Db): ArtifactTrashRecord[] {
+	const rows = db.prepare("SELECT artifact_id, trashed_at, purge_after, reason FROM artifact_trash ORDER BY purge_after ASC").all() as Record<string, unknown>[];
+	return rows.map(rowToTrashRecord);
+}
+
+/**
+ * Moves an artifact to the trash: it becomes ineligible for purge_after ms (see
+ * ARTIFACT_TRASH_RETENTION_MS), immediately excluded from queryArtifacts by default, still
+ * directly reachable via getArtifact, and fully restorable via restoreArtifact until the
+ * daemon's periodic sweep (purgeDueArtifacts) actually deletes it. Re-removing an
+ * already-trashed artifact resets its clock rather than erroring -- the same "most recent
+ * intent wins" semantics as registerSessionIdentity's rotation.
+ *
+ * Refuses to trash a Task that is the live Task Focus in any scope: Focus is active,
+ * behavior-affecting state, and trashing out from under it would silently discard work a
+ * caller is not necessarily looking at right now. No other kind has an analogous "currently
+ * in use" signal to check.
+ */
+export function trashArtifact(db: Db, id: string, options?: { reason?: string; now?: () => string; context?: ArtifactEventContext }): ArtifactTrashRecord {
+	const artifact = getArtifact(db, id);
+	if (!artifact) throw new Error(`artifact "${id}" not found`);
+	const focusedScope = db.prepare("SELECT scope FROM task_focus WHERE task_id = ? LIMIT 1").get(id) as { scope: string } | null;
+	if (focusedScope) throw new Error(`artifact "${id}" is the active Task Focus in scope "${focusedScope.scope}"; clear focus before removing it`);
+	const now = options?.now ?? (() => new Date().toISOString());
+	const trashedAt = now();
+	const purgeAfter = new Date(new Date(trashedAt).getTime() + ARTIFACT_TRASH_RETENTION_MS).toISOString();
+	const record: ArtifactTrashRecord = { artifactId: id, trashedAt, purgeAfter, ...(options?.reason ? { reason: options.reason } : {}) };
+	inTransaction(db, () => {
+		db.prepare(`
+			INSERT INTO artifact_trash (artifact_id, trashed_at, purge_after, reason) VALUES (?, ?, ?, ?)
+			ON CONFLICT (artifact_id) DO UPDATE SET trashed_at = excluded.trashed_at, purge_after = excluded.purge_after, reason = excluded.reason
+		`).run(record.artifactId, record.trashedAt, record.purgeAfter, record.reason ?? null);
+		appendArtifactEvent(db, { artifactId: id, type: "trashed", ...(options?.context ?? {}) });
+	});
+	return record;
+}
+
+/** Idempotent: restoring an artifact that is not currently trashed is a real no-op, not an error -- mirrors releaseSessionIdentity's idempotence. */
+export function restoreArtifact(db: Db, id: string, context?: ArtifactEventContext): { restored: boolean } {
+	const wasTrashed = getArtifactTrash(db, id) !== null;
+	if (!wasTrashed) return { restored: false };
+	inTransaction(db, () => {
+		db.prepare("DELETE FROM artifact_trash WHERE artifact_id = ?").run(id);
+		appendArtifactEvent(db, { artifactId: id, type: "restored", ...(context ?? {}) });
+	});
+	return { restored: true };
+}
+
+/**
+ * Real, cascading, irreversible deletion of every artifact whose purge_after has passed.
+ * Never called with anything but the real current time in production -- see daemon.ts's
+ * periodic sweep; a directly-injected `now` exists only so tests can exercise this without
+ * waiting out ARTIFACT_TRASH_RETENTION_MS for real.
+ *
+ * Deletes, in FK-safe order, every row across every table that can reference artifacts(id)
+ * (see the grep-verified list in domain/artifact-trash.ts's design comment): edges (both
+ * directions), task_focus, task_scopes, task_views (by root_task_id), graph_projection_
+ * identities, artifact_scopes, then task_events and artifact_events -- the latter two
+ * succeed only because the artifact_trash row placed here by trashArtifact still exists
+ * with an elapsed purge_after, which is exactly what db.ts's task_events_no_delete /
+ * artifact_events_no_delete trigger carve-outs check themselves. Only THEN artifact_trash's
+ * own row (it is itself a child of artifacts via a real FK, so it must go before artifacts,
+ * but only after the event tables that depend on its continued presence), and artifacts
+ * itself last of all. One artifact at a time in its own transaction, so one failure never
+ * blocks any other due artifact.
+ */
+export function purgeDueArtifacts(db: Db, now: () => string = () => new Date().toISOString()): number {
+	const nowIso = now();
+	const due = (db.prepare("SELECT artifact_id FROM artifact_trash WHERE purge_after <= ?").all(nowIso) as Array<{ artifact_id: string }>).map((row) => row.artifact_id);
+	let purged = 0;
+	for (const id of due) {
+		inTransaction(db, () => {
+			db.prepare("DELETE FROM edges WHERE from_id = ? OR to_id = ?").run(id, id);
+			db.prepare("DELETE FROM task_focus WHERE task_id = ?").run(id);
+			db.prepare("DELETE FROM task_scopes WHERE task_id = ?").run(id);
+			db.prepare("DELETE FROM task_views WHERE root_task_id = ?").run(id);
+			db.prepare("DELETE FROM graph_projection_identities WHERE artifact_id = ?").run(id);
+			db.prepare("DELETE FROM artifact_scopes WHERE artifact_id = ?").run(id);
+			db.prepare("DELETE FROM task_events WHERE task_id = ?").run(id);
+			db.prepare("DELETE FROM artifact_events WHERE artifact_id = ?").run(id);
+			db.prepare("DELETE FROM artifact_trash WHERE artifact_id = ?").run(id);
+			db.prepare("DELETE FROM artifacts WHERE id = ?").run(id);
+		});
+		purged += 1;
+	}
+	return purged;
+}
+
 export function linkArtifacts(db: Db, fromId: string, relation: string, toId: string, context?: ArtifactEventContext): void {
 	const fromArt = getArtifact(db, fromId);
 	const toArt = getArtifact(db, toId);

package/src/ports/artifact-store.ts

@@ -9,6 +9,7 @@ import type {
 	UpdateArtifactInput,
 } from "../domain/artifact.ts";
 import type { ArtifactEventContext, ArtifactEventPage, ArtifactEventQuery } from "../domain/artifact-event.ts";
+import type { ArtifactTrashRecord } from "../domain/artifact-trash.ts";
 
 export interface ArtifactStore {
 	create(input: CreateArtifactInput, context?: ArtifactEventContext): Artifact;
@@ -23,4 +24,12 @@ export interface ArtifactStore {
 	relationships(filter?: RelationshipQuery): ArtifactEdge[];
 	/** Bounded query over the generic mutation event log shared by every kind. */
 	events(query: ArtifactEventQuery): ArtifactEventPage;
+	/** See domain/artifact-trash.ts. Moves an artifact to the trash; throws if it does not exist or is the live Task Focus in any scope. */
+	trash(id: string, options?: { reason?: string; context?: ArtifactEventContext }): ArtifactTrashRecord;
+	/** Idempotent: restoring an artifact that is not currently trashed is a real no-op. */
+	restore(id: string, context?: ArtifactEventContext): { restored: boolean };
+	trashStatus(id: string): ArtifactTrashRecord | null;
+	listTrash(): ArtifactTrashRecord[];
+	/** Real, cascading, irreversible deletion of every artifact past its purge deadline; returns how many were purged. */
+	purgeDueTrash(): number;
 }

package/src/ports/discussion-round-store.ts

@@ -0,0 +1,8 @@
+import type { AppendDiscussionRound, DiscussionRound, DiscussionRoundQuery } from "../domain/discussion.ts";
+
+/** Persistence port for a Discussion's append-only rounds (see domain/discussion.ts). */
+export interface DiscussionRoundStore {
+	append(round: AppendDiscussionRound, occurredAt: string): DiscussionRound;
+	list(query: DiscussionRoundQuery): DiscussionRound[];
+	count(discussionId: string): number;
+}

package/src/service.ts

@@ -34,7 +34,10 @@ import { notesOperations, NOTES_OPERATION_NAMES } from "./modules/notes.ts";
 import { rulesOperations, RULES_OPERATION_NAMES } from "./modules/rules.ts";
 import { skillsOperations, SKILLS_OPERATION_NAMES } from "./modules/skills.ts";
 import { sessionIdentityOperations, SESSION_IDENTITY_OPERATION_NAMES } from "./modules/session-identity.ts";
+import { discussOperations, DISCUSS_OPERATION_NAMES } from "./modules/discuss.ts";
 import { tasksOperations, TASKS_OPERATION_NAMES } from "./modules/tasks.ts";
+import { Discussions } from "./discussion-service.ts";
+import { SQLiteDiscussionRoundStore } from "./adapters/sqlite-discussion-round-store.ts";
 
 /**
  * Operations with no registered module: the generic, cross-cutting kernel surface
@@ -49,6 +52,7 @@ import { tasksOperations, TASKS_OPERATION_NAMES } from "./modules/tasks.ts";
  */
 const COMPOSITION_ROOT_OPERATION_NAMES = [
 	"system.migrate", "artifact.create", "artifact.query", "artifact.show",
+	"artifact.remove", "artifact.restore", "artifact.trash_status", "artifact.trash_list",
 	"graph.link", "graph.unlink", "graph.tree", "graph.status", "graph.history", "gates.run",
 	"rules.injectable", "skills.instantiate",
 ] as const;
@@ -72,6 +76,7 @@ export const EXPECTED_OPERATION_NAMES = [
 	...GRAPH_PROJECTION_OPERATION_NAMES,
 	...LOGS_OPERATION_NAMES,
 	...SESSION_IDENTITY_OPERATION_NAMES,
+	...DISCUSS_OPERATION_NAMES,
 ] as const;
 
 export type OperationName = typeof EXPECTED_OPERATION_NAMES[number];
@@ -173,6 +178,8 @@ export interface PapyrusService {
 	optimize(): void;
 	/** Time-based Task Focus reclamation (see Tasks.reapStaleFocus); returns how many rows were removed, for daemon logging. */
 	reapStaleFocus(): number;
+	/** Real, cascading deletion of every artifact past its trash purge deadline (see domain/artifact-trash.ts); returns how many were purged, for daemon logging. */
+	purgeDueTrash(): number;
 	close(): void;
 }
 
@@ -241,6 +248,10 @@ function handlers(
 			depth: optionalNumber(input, "depth"),
 			maxNodes: optionalNumber(input, "max_nodes") ?? optionalNumber(input, "maxNodes"),
 		}),
+		"artifact.remove": (input) => artifacts.trash(string(input, "id"), { reason: optionalString(input, "reason"), context: eventContext(input) }),
+		"artifact.restore": (input) => artifacts.restore(string(input, "id"), eventContext(input)),
+		"artifact.trash_status": (input) => artifacts.trashStatus(string(input, "id")),
+		"artifact.trash_list": () => artifacts.listTrash(),
 		"graph.link": (input) => {
 			const from = string(input, "from");
 			const relation = string(input, "relation");
@@ -376,6 +387,16 @@ function handlers(
 		"logs.query": forwardToModule("logs.query"),
 		"session.register": forwardToModule("session.register"),
 		"session.release": forwardToModule("session.release"),
+		"discuss.open": forwardToModule("discuss.open"),
+		"discuss.reply": forwardToModule("discuss.reply"),
+		"discuss.defer": forwardToModule("discuss.defer"),
+		"discuss.resume": forwardToModule("discuss.resume"),
+		"discuss.settle": forwardToModule("discuss.settle"),
+		"discuss.block": forwardToModule("discuss.block"),
+		"discuss.unblock": forwardToModule("discuss.unblock"),
+		"discuss.show": forwardToModule("discuss.show"),
+		"discuss.rounds": forwardToModule("discuss.rounds"),
+		"discuss.list": forwardToModule("discuss.list"),
 	};
 }
 
@@ -392,11 +413,13 @@ export function createPapyrusService(path: string): PapyrusService {
 	const artifactScopes = new SQLiteArtifactScopeStore(db);
 	const logs = new Logs(new SQLiteLogStore(db));
 	const sessionIdentity = new SessionIdentity(new SQLiteSessionIdentityStore(db));
+	const discussions = new Discussions(artifacts, new SQLiteDiscussionRoundStore(db));
 	const authority = createAuthorityRegistry();
 	const moduleRegistry = new OperationRegistry();
 	moduleRegistry.registerAll(notesOperations(notes));
 	moduleRegistry.registerAll(logsOperations(logs));
 	moduleRegistry.registerAll(sessionIdentityOperations(sessionIdentity));
+	moduleRegistry.registerAll(discussOperations(discussions));
 	moduleRegistry.registerAll(tasksOperations(tasks, artifacts, sessionIdentity));
 	moduleRegistry.registerAll(docsOperations(artifacts, artifactScopes, authority));
 	moduleRegistry.registerAll(rulesOperations(artifacts, artifactScopes));
@@ -421,6 +444,7 @@ export function createPapyrusService(path: string): PapyrusService {
 		checkpoint: () => { db.exec("PRAGMA wal_checkpoint(PASSIVE)"); },
 		optimize: () => { db.exec("PRAGMA optimize"); },
 		reapStaleFocus: () => tasks.reapStaleFocus(),
+		purgeDueTrash: () => artifacts.purgeDueTrash(),
 		close: () => {
 			db.exec("PRAGMA optimize");
 			db.close();

package/src/task-service.ts

@@ -11,6 +11,7 @@ import {
 } from "./constants.ts";
 import type { Artifact } from "./domain/artifact.ts";
 import { checklistEntries, validateChecklist, type Checklist, type ProofReference } from "./domain/checklist.ts";
+import { isDiscussionArtifact, readDiscussionExtra } from "./domain/discussion.ts";
 import type { Gate, GateResult } from "./domain/gate.ts";
 import type { AppendTaskEvent, TaskEventContext, TaskHistoryPage, TaskHistoryQuery, TaskLifecycleStatus } from "./domain/task-event.ts";
 import { normalizeProjectRoot, taskScopeLabel, type TaskScopeSource, type TaskViewMode, type TaskViewSelection } from "./domain/task-scope.ts";
@@ -419,6 +420,7 @@ export class Tasks {
 
 	complete(id: string, context: TaskEventContext = {}, options: TaskCompletionOptions = {}): TaskCompletion {
 		const task = this.requireReview(id);
+		this.requireNotBlocked(id);
 		const attemptId = crypto.randomUUID();
 		this.events.atomic(() => this.appendEvent({ taskId: id, type: "completion_attempted", fromStatus: "review", toStatus: "review", attemptId }, context));
 		const checklist = this.reviewChecklist(task);
@@ -428,6 +430,7 @@ export class Tasks {
 
 	async completeAsync(id: string, context: TaskEventContext = {}, options: TaskCompletionOptions = {}): Promise<TaskCompletion> {
 		const task = this.requireReview(id);
+		this.requireNotBlocked(id);
 		const attemptId = crypto.randomUUID();
 		this.events.atomic(() => this.appendEvent({ taskId: id, type: "completion_attempted", fromStatus: "review", toStatus: "review", attemptId }, context));
 		const checklist = this.reviewChecklist(task);
@@ -678,4 +681,28 @@ export class Tasks {
 		if (task.status !== "review") throw new Error(`cannot complete task from ${task.status}`);
 		return task;
 	}
+
+	/**
+	 * Discuss's forcing behavior (see domain/discussion.ts): an active Discussion doc that
+	 * `blocks` this task refuses its completion until settled or deferred. A discussion whose
+	 * extra.discussion shape is missing or corrupt is treated as non-blocking rather than
+	 * crashing completion -- the same fail-open posture Task Focus's opt-in armor uses for an
+	 * unrecognized shape.
+	 */
+	private blockingDiscussions(id: string): Artifact[] {
+		return this.artifacts.relationships({ artifactIds: [id] })
+			.filter((edge) => edge.relation === "blocks" && edge.to === id)
+			.map((edge) => this.artifacts.get(edge.from))
+			.filter((source): source is Artifact => source !== null && isDiscussionArtifact(source))
+			.filter((discussion) => {
+				try { return readDiscussionExtra(discussion.extra).state === "active"; } catch { return false; }
+			});
+	}
+
+	private requireNotBlocked(id: string): void {
+		const blockers = this.blockingDiscussions(id);
+		if (blockers.length > 0) {
+			throw new Error(`task "${id}" is blocked by ${blockers.length} active Discussion(s): ${blockers.map((discussion) => discussion.id).join(", ")}`);
+		}
+	}
 }