@danypops/papyrus 0.17.2 → 0.18.0

package/README.md

@@ -100,6 +100,12 @@ papyrus skills run <skill-id> \
 
 The existing `artifact-template` skill subtype remains a compatibility mechanism for one-artifact templates with metadata `{targetKind, defaults, required}`. Instantiate it through `papyrus_create` with `template_id`; defaults merge recursively, explicit arrays replace defaults, required paths such as `extra.owner` are validated, and target-kind mismatches are rejected.
 
+### Removing an artifact
+
+Artifacts are never hard-deleted on request: every artifact gets a permanent, immutable `created` row in the mutation event log the moment it exists, so removal is a real, time-gated trash rather than a status flip. `remove` (any of the `tasks`/`docs`/`rules`/`skills` domain tools, or `papyrus artifact remove <id> [--reason <text>]`) moves an artifact to the trash: it is immediately excluded from every list/query, still directly reachable by id, and fully recoverable via `restore` until its purge deadline (30 days later) passes. `remove` refuses a Task that is the live Task Focus in any scope.
+
+Once the deadline passes, the daemon's periodic sweep performs a real, cascading, irreversible deletion — the one deliberate, narrow exception to Papyrus's otherwise-absolute append-only history, enforced by the database itself (not merely application code) via a trigger condition checked at delete time.
+
 ## Tools
 
 The `papyrus_*` tools are the low-level graph-store API:

package/extension/src/domain-tools.ts

@@ -31,6 +31,26 @@ function artifactLine(artifact: Artifact): string {
 	return `${artifact.id} [${artifact.status}] ${artifact.title}`;
 }
 
+/**
+ * Shared "remove"/"restore" dispatch for every domain tool (tasks/docs/rules/skills) --
+ * artifact.remove/restore are kind-agnostic composition-root operations (see service.ts),
+ * not owned by any one domain module, so every domain tool exposes the same two actions
+ * over the same two operations rather than reinventing trash semantics four times.
+ * Returns null when action is neither, so callers fall through to their own dispatch.
+ */
+async function handleArtifactRemoveRestore(action: unknown, params: Record<string, unknown>): Promise<ReturnType<typeof text> | null> {
+	if (action === "remove") {
+		const record = await callService<Record<string, unknown>, { artifactId: string; trashedAt: string; purgeAfter: string; reason?: string }>("artifact.remove", params);
+		return text(`Trashed ${record.artifactId}, eligible for purge at ${record.purgeAfter}.`, createPreviewDetails("artifact.remove", "Trashed", record.artifactId));
+	}
+	if (action === "restore") {
+		const outcome = await callService<Record<string, unknown>, { restored: boolean }>("artifact.restore", params);
+		const output = outcome.restored ? `Restored ${params["id"]}.` : `${params["id"]} was not trashed.`;
+		return text(output, createPreviewDetails("artifact.restore", "Restored", output));
+	}
+	return null;
+}
+
 const proofReferenceSchema = Type.Object({
 	type: Type.Union(PROOF_TYPES.map((type) => Type.Literal(type))),
 	target: Type.String(),
@@ -45,7 +65,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "tasks",
 		label: "Tasks",
-		description: "Task domain tool. ACTIONS: create, update, list, show, history, scope, set_scope, assign_project, graph, plan, active, focused, focus, pause, unpause, clear_focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, depend, undepend, contain, uncontain. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. update can recover a Task accidentally created terminal by setting status=todo with a reason, but cannot rewrite legitimate lifecycle history. Active focus is independent and identifies the one task auto-drive continues. Completion runs gates and checklist-proof review, then focuses one deterministic ready successor without claiming effort. Dependency cycles are rejected. undepend/uncontain are idempotent for an already-absent relationship and never start, complete, or focus work merely because an edge disappeared; uncontain removes both contains and part_of edges atomically. Prefer this over low-level papyrus_* tools for task work.",
+		description: "Task domain tool. ACTIONS: create, update, list, show, history, scope, set_scope, assign_project, graph, plan, active, focused, focus, pause, unpause, clear_focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, depend, undepend, contain, uncontain, remove, restore. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. update can recover a Task accidentally created terminal by setting status=todo with a reason, but cannot rewrite legitimate lifecycle history. Active focus is independent and identifies the one task auto-drive continues. Completion runs gates and checklist-proof review, then focuses one deterministic ready successor without claiming effort. Dependency cycles are rejected. undepend/uncontain are idempotent for an already-absent relationship and never start, complete, or focus work merely because an edge disappeared; uncontain removes both contains and part_of edges atomically. remove moves a Task to a time-gated trash (restorable via restore until the purge deadline; refuses if it is the live Task Focus). Prefer this over low-level papyrus_* tools for task work.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
@@ -181,6 +201,8 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 						}))),
 					);
 				}
+				const trashResult = await handleArtifactRemoveRestore(action, params);
+				if (trashResult) return trashResult;
 				const operations = {
 					focus: "tasks.focus",
 					start: "tasks.start",
@@ -257,7 +279,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "docs",
 		label: "Documents",
-		description: "Document domain tool. ACTIONS: create, list, show, activate, archive, reopen, link, assign_project. project_root is optional at creation (omitted = unscoped); assign_project reassigns it later, or unscopes when project_root is omitted. Prefer this over low-level papyrus_* tools for document work.",
+		description: "Document domain tool. ACTIONS: create, list, show, activate, archive, reopen, link, assign_project, remove, restore. project_root is optional at creation (omitted = unscoped); assign_project reassigns it later, or unscopes when project_root is omitted. remove moves a Doc to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline. Prefer this over low-level papyrus_* tools for document work.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
@@ -273,6 +295,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 			relation: Type.Optional(Type.String()),
 			target_id: Type.Optional(Type.String()),
 			project_root: Type.Optional(Type.String()),
+			reason: Type.Optional(Type.String()),
 		}),
 		renderCall(args, theme) { return renderPapyrusToolCall("Documents", args, theme); },
 		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
@@ -291,6 +314,8 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 					const artifact = await callService<Record<string, unknown>, Artifact>("docs.show", params);
 					return text(`${artifactLine(artifact)}\n\n${artifact.body}`, createArtifactDetails("docs.show", artifact));
 				}
+				const trashResult = await handleArtifactRemoveRestore(action, params);
+				if (trashResult) return trashResult;
 				const operations = { activate: "docs.activate", archive: "docs.archive", reopen: "docs.reopen", link: "docs.link", assign_project: "docs.assign_project" } as const;
 				const operation = operations[action as keyof typeof operations];
 				if (!operation) throw new Error(`unknown docs action: ${action}`);
@@ -305,14 +330,14 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "rules",
 		label: "Rules",
-		description: "Rule domain tool. ACTIONS: create, list, show, preview, enable, disable, gate, assign_project. project_root is optional at creation (omitted = unscoped); assign_project reassigns it later, or unscopes when project_root is omitted. Active rules inject into the agent system prompt.",
+		description: "Rule domain tool. ACTIONS: create, list, show, preview, enable, disable, gate, assign_project, remove, restore. project_root is optional at creation (omitted = unscoped); assign_project reassigns it later, or unscopes when project_root is omitted. Active rules inject into the agent system prompt. remove moves a Rule to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline.",
 		parameters: Type.Object({
 			action: Type.String(), id: Type.Optional(Type.String()), title: Type.Optional(Type.String()),
 			body: Type.Optional(Type.String()), condition: Type.Optional(Type.String()), rule_action: Type.Optional(Type.String()),
 			severity: Type.Optional(Type.String()), labels: Type.Optional(Type.Array(Type.String())),
 			extra: Type.Optional(Type.Record(Type.String(), Type.Unknown())), status: Type.Optional(Type.String()),
 			text: Type.Optional(Type.String()), limit: Type.Optional(Type.Number()), task_id: Type.Optional(Type.String()),
-			project_root: Type.Optional(Type.String()),
+			project_root: Type.Optional(Type.String()), reason: Type.Optional(Type.String()),
 		}),
 		renderCall(args, theme) { return renderPapyrusToolCall("Rules", args, theme); },
 		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
@@ -331,6 +356,8 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 					const preview = await callService<Record<string, unknown>, string>("rules.preview", params);
 					return text(preview, createPreviewDetails("rules.preview", "Rule preview", preview));
 				}
+				const trashResult = await handleArtifactRemoveRestore(action, params);
+				if (trashResult) return trashResult;
 				const operations = { show: "rules.show", enable: "rules.enable", disable: "rules.disable", gate: "rules.gate", assign_project: "rules.assign_project" } as const;
 				const operation = operations[action as keyof typeof operations];
 				if (!operation) throw new Error(`unknown rules action: ${action}`);
@@ -345,7 +372,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "skills",
 		label: "Skills",
-		description: "Papyrus Skill workflow and compatibility-template domain tool. Papyrus Skills are parameterized Task/Rule/Doc bundles, distinct from prompt-only skills. ACTIONS: create, create_template, list, show, invoke, run, enable, disable, instantiate, assign_project. run validates arguments and atomically creates one scoped workflow run. project_root is optional at creation (omitted = unscoped) for create/create_template; assign_project reassigns it later, or unscopes when project_root is omitted.",
+		description: "Papyrus Skill workflow and compatibility-template domain tool. Papyrus Skills are parameterized Task/Rule/Doc bundles, distinct from prompt-only skills. ACTIONS: create, create_template, list, show, invoke, run, enable, disable, instantiate, assign_project, remove, restore. run validates arguments and atomically creates one scoped workflow run. project_root is optional at creation (omitted = unscoped) for create/create_template; assign_project reassigns it later, or unscopes when project_root is omitted. remove moves a Skill to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline.",
 		parameters: Type.Object({
 			action: Type.String(), id: Type.Optional(Type.String()), title: Type.Optional(Type.String()),
 			body: Type.Optional(Type.String()), trigger: Type.Optional(Type.String()), steps: Type.Optional(Type.Array(Type.String())),
@@ -356,7 +383,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 			text: Type.Optional(Type.String()), limit: Type.Optional(Type.Number()), template_id: Type.Optional(Type.String()),
 			target_kind: Type.Optional(Type.String()), defaults: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
 			required: Type.Optional(Type.Array(Type.String())), kind: Type.Optional(Type.String()), subtype: Type.Optional(Type.String()),
-			project_root: Type.Optional(Type.String()),
+			project_root: Type.Optional(Type.String()), reason: Type.Optional(Type.String()),
 		}),
 		renderCall(args, theme) { return renderPapyrusToolCall("Skills", args, theme); },
 		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
@@ -393,6 +420,8 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 						roots: run.rootTaskIds,
 					}));
 				}
+				const trashResult = await handleArtifactRemoveRestore(action, params);
+				if (trashResult) return trashResult;
 				const operations = { show: "skills.show", enable: "skills.enable", disable: "skills.disable", instantiate: "skills.instantiate", assign_project: "skills.assign_project" } as const;
 				const operation = operations[action as keyof typeof operations];
 				if (!operation) throw new Error(`unknown skills action: ${action}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

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

@@ -12,7 +12,23 @@ import type {
 	UpdateArtifactInput,
 } from "../domain/artifact.ts";
 import type { ArtifactEventContext, ArtifactEventPage, ArtifactEventQuery } from "../domain/artifact-event.ts";
-import { createArtifact, getArtifact, linkArtifacts, queryArtifactEvents, queryArtifacts, unlinkArtifacts, updateArtifactContent, updateExtra, updateStatus } from "../ops.ts";
+import type { ArtifactTrashRecord } from "../domain/artifact-trash.ts";
+import {
+	createArtifact,
+	getArtifact,
+	getArtifactTrash,
+	linkArtifacts,
+	listArtifactTrash,
+	purgeDueArtifacts,
+	queryArtifactEvents,
+	queryArtifacts,
+	restoreArtifact,
+	trashArtifact,
+	unlinkArtifacts,
+	updateArtifactContent,
+	updateExtra,
+	updateStatus,
+} from "../ops.ts";
 
 export class SQLiteArtifactStore implements AtomicArtifactStore {
 	constructor(private readonly db: Db) {}
@@ -57,6 +73,26 @@ export class SQLiteArtifactStore implements AtomicArtifactStore {
 		return queryArtifactEvents(this.db, query);
 	}
 
+	trash(id: string, options?: { reason?: string; context?: ArtifactEventContext }): ArtifactTrashRecord {
+		return trashArtifact(this.db, id, { reason: options?.reason, context: options?.context });
+	}
+
+	restore(id: string, context?: ArtifactEventContext): { restored: boolean } {
+		return restoreArtifact(this.db, id, context);
+	}
+
+	trashStatus(id: string): ArtifactTrashRecord | null {
+		return getArtifactTrash(this.db, id);
+	}
+
+	listTrash(): ArtifactTrashRecord[] {
+		return listArtifactTrash(this.db);
+	}
+
+	purgeDueTrash(): number {
+		return purgeDueArtifacts(this.db);
+	}
+
 	relationships(filter: RelationshipQuery = {}): ArtifactEdge[] {
 		if (filter.artifactIds?.length === 0) return [];
 		const conditions: string[] = [];

package/src/cli.ts

@@ -82,6 +82,10 @@ const USAGE = `Usage:
   papyrus artifact create --kind <kind> [--title <title>] [--status <status>] [--subtype <subtype>] [--body <body>] [--labels-json <json>] [--extra-json <json>] [--template-id <id>] [--json]
   papyrus artifact query [--kind <kind>] [--status <status>] [--text <query>] [--limit <count>] [--json]
   papyrus artifact show <id> [--depth <n>] [--max-nodes <n>] [--json]
+  papyrus artifact remove <id> [--reason <text>] [--json]
+  papyrus artifact restore <id> [--json]
+  papyrus artifact trash-status <id> [--json]
+  papyrus artifact trash-list [--json]
   papyrus docs create --title <title> [--body <body>] [--subtype <subtype>] [--labels-json <json>] [--extra-json <json>] [--template-id <id>] [--project-root <path>] [--json]
   papyrus docs list [--status <status>] [--text <query>] [--limit <count>] [--project-root <path>] [--json]
   papyrus docs show <id> [--json]
@@ -738,6 +742,7 @@ export async function runArtifactCli(args: string[], client: TaskCliClient, proj
 	let labels: string[] | undefined;
 	let extra: Record<string, unknown> | undefined;
 	let templateId: string | undefined;
+	let reason: string | undefined;
 	let text: string | undefined;
 	let limit: number | undefined;
 	let depth: number | undefined;
@@ -753,6 +758,7 @@ export async function runArtifactCli(args: string[], client: TaskCliClient, proj
 		if (argument === "--labels-json") { labels = parseJsonStringArrayFlag(args[++index], "--labels-json"); continue; }
 		if (argument === "--extra-json") { extra = parseJsonObjectFlag(args[++index], "--extra-json"); continue; }
 		if (argument === "--template-id") { templateId = args[++index]; if (!templateId) throw new Error("--template-id requires a value"); continue; }
+		if (argument === "--reason") { reason = args[++index]; if (reason === undefined) throw new Error("--reason requires a value"); continue; }
 		if (argument === "--text") { text = args[++index]; if (text === undefined) throw new Error("--text requires a value"); continue; }
 		if (argument === "--limit") {
 			const value = args[++index];
@@ -804,8 +810,36 @@ export async function runArtifactCli(args: string[], client: TaskCliClient, proj
 			human = `${artifactLabel(artifact)}\n\n${artifact.body ?? ""}`;
 			break;
 		}
+		case "remove": {
+			if (!id) throw new Error("artifact remove requires exactly one artifact id");
+			const record = await client.call<Record<string, unknown>, { artifactId: string; trashedAt: string; purgeAfter: string; reason?: string }>("artifact.remove", { id, reason });
+			result = record;
+			human = `Trashed ${record.artifactId}: eligible for purge at ${record.purgeAfter}`;
+			break;
+		}
+		case "restore": {
+			if (!id) throw new Error("artifact restore requires exactly one artifact id");
+			const outcome = await client.call<Record<string, unknown>, { restored: boolean }>("artifact.restore", { id });
+			result = outcome;
+			human = outcome.restored ? `Restored ${id}` : `${id} was not trashed`;
+			break;
+		}
+		case "trash-status": {
+			if (!id) throw new Error("artifact trash-status requires exactly one artifact id");
+			const record = await client.call<Record<string, unknown>, { artifactId: string; trashedAt: string; purgeAfter: string; reason?: string } | null>("artifact.trash_status", { id });
+			result = record;
+			human = record ? `${record.artifactId}: trashed at ${record.trashedAt}, purge eligible at ${record.purgeAfter}` : `${id} is not trashed`;
+			break;
+		}
+		case "trash-list": {
+			if (id) throw new Error("artifact trash-list accepts no positional arguments");
+			const rows = await client.call<Record<string, unknown>, Array<{ artifactId: string; trashedAt: string; purgeAfter: string; reason?: string }>>("artifact.trash_list", {});
+			result = rows;
+			human = rows.length === 0 ? "Trash is empty." : rows.map((row) => `${row.artifactId}: purge eligible at ${row.purgeAfter}`).join("\n");
+			break;
+		}
 		default:
-			throw new Error("artifact action must be create, query, or show");
+			throw new Error("artifact action must be create, query, show, remove, restore, trash-status, or trash-list");
 	}
 	return json ? JSON.stringify(result) : human;
 }

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 = 13;
+export const SQLITE_SCHEMA_VERSION = 14;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -159,6 +159,15 @@ export const TASK_FOCUS_MAX_SCOPES = 500;
 export const TASK_FOCUS_STALE_AFTER_MS = 30 * 24 * 60 * 60 * 1000;
 /** Hard cap on registered session_identities rows (see domain/session-identity.ts); oldest-seen identity is evicted beyond this, mirroring TASK_FOCUS_MAX_SCOPES. */
 export const SESSION_IDENTITY_MAX_ROWS = 2_000;
+/**
+ * Grace period between artifact.remove (trash) and artifact purge eligibility -- see
+ * domain/artifact-trash.ts. 30 days, matching TASK_FOCUS_STALE_AFTER_MS's convention: long
+ * enough that a mistaken removal is still recoverable via artifact.restore, short enough to
+ * actually bound trash accumulation. Enforced twice: the daemon's periodic sweep only
+ * selects rows past this deadline, and the SQLite triggers that otherwise forbid deleting
+ * artifact_events/task_events independently re-check the same deadline at delete time.
+ */
+export const ARTIFACT_TRASH_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 /** Persisted project and focused-graph Task view bounds. */
 export const TASK_SCOPE_MAX_TASKS = 1_000;
 /** Docs/Rules/Skills project scope listing bound, mirroring TASK_SCOPE_MAX_TASKS. */

package/src/daemon.ts

@@ -34,6 +34,14 @@ export function serveMain(): void {
 			if (removed > 0) logEvent("info", "stale_focus_reaped", { removed });
 		} catch (error) { logEvent("error", "reap_stale_focus_failed", { message: error instanceof Error ? error.message : String(error) }); }
 	}, DB_OPTIMIZE_INTERVAL_MS);
+	// Same daily cadence: ARTIFACT_TRASH_RETENTION_MS is 30 days, so a daily sweep finds newly
+	// due artifacts promptly without needing its own tighter interval -- see domain/artifact-trash.ts.
+	const purgeTrashTimer = setInterval(() => {
+		try {
+			const purged = service.purgeDueTrash();
+			if (purged > 0) logEvent("info", "artifact_trash_purged", { purged });
+		} catch (error) { logEvent("error", "purge_trash_failed", { message: error instanceof Error ? error.message : String(error) }); }
+	}, DB_OPTIMIZE_INTERVAL_MS);
 	let stopping = false;
 	const shutdown = () => {
 		if (stopping) return;
@@ -41,6 +49,7 @@ export function serveMain(): void {
 		clearInterval(checkpointTimer);
 		clearInterval(optimizeTimer);
 		clearInterval(reapFocusTimer);
+		clearInterval(purgeTrashTimer);
 		clearDaemonPort(stateDir);
 		service.close();
 		void server.stop(true).finally(() => process.exit(0));

package/src/db.ts

@@ -134,7 +134,8 @@ CREATE INDEX IF NOT EXISTS task_events_history_idx ON task_events(task_id, occur
 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;
+WHEN NOT EXISTS (SELECT 1 FROM artifact_trash WHERE artifact_id = OLD.task_id AND purge_after <= strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+BEGIN SELECT RAISE(ABORT, 'task_events are append-only except during an explicit, elapsed-grace-period artifact trash purge'); END;
 CREATE TABLE IF NOT EXISTS task_scopes (
 	task_id       TEXT PRIMARY KEY REFERENCES artifacts(id),
 	project_root  TEXT,
@@ -170,7 +171,8 @@ CREATE INDEX IF NOT EXISTS artifact_events_session_idx ON artifact_events(sessio
 CREATE TRIGGER IF NOT EXISTS artifact_events_no_update BEFORE UPDATE ON artifact_events
 BEGIN SELECT RAISE(ABORT, 'artifact_events are append-only'); END;
 CREATE TRIGGER IF NOT EXISTS artifact_events_no_delete BEFORE DELETE ON artifact_events
-BEGIN SELECT RAISE(ABORT, 'artifact_events are append-only'); END;
+WHEN NOT EXISTS (SELECT 1 FROM artifact_trash WHERE artifact_id = OLD.artifact_id AND purge_after <= strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+BEGIN SELECT RAISE(ABORT, 'artifact_events are append-only except during an explicit, elapsed-grace-period artifact trash purge'); END;
 CREATE TABLE IF NOT EXISTS graph_projection_checkpoints (
 	producer_id    TEXT PRIMARY KEY,
 	last_sequence  INTEGER NOT NULL,
@@ -218,6 +220,13 @@ CREATE TABLE IF NOT EXISTS session_identities (
 	registered_at TEXT NOT NULL,
 	last_seen_at  TEXT NOT NULL
 );
+CREATE TABLE IF NOT EXISTS artifact_trash (
+	artifact_id  TEXT PRIMARY KEY REFERENCES artifacts(id),
+	trashed_at   TEXT NOT NULL,
+	purge_after  TEXT NOT NULL,
+	reason       TEXT
+);
+CREATE INDEX IF NOT EXISTS artifact_trash_purge_idx ON artifact_trash(purge_after);
 `;
 
 const SEED_SQL = `
@@ -296,6 +305,7 @@ const CORE_LEDGER_VERSIONS: ReadonlyArray<{ version: number; name: string; check
 	{ version: 3, name: "log-domain", checksum: "c87f43c22b2608619ada9a529d7899ae74b7f38cd554135c8034116fc96e1eff" },
 	{ version: 4, name: "remove-discourse", checksum: "b923f41c44460f0aaeb2f4e60e28f8b8e1425d03f527955bd991434b46de4c82" },
 	{ version: 5, name: "session-identity", checksum: "1c6a165bbe37f82a100fd34762db70c3f8ab15ff20c3a53c2e60448edc815a5e" },
+	{ version: 6, name: "artifact-trash", checksum: "4a75dbec2892deb54bcc1afdf0d51d81f03a8d10861787d083784a29e5c7e8f9" },
 ];
 
 export function migrationLedger(db: Db): ModuleMigrationRow[] {
@@ -388,8 +398,34 @@ export interface PapyrusMigration {
 	up: (db: Db) => void;
 }
 
-/** Currently empty -- no schema version beyond LEGACY_MIGRATION_CHAIN_TARGET_VERSION exists yet. The next migration is appended here, never as a new branch in the legacy chain above. */
-const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [];
+const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
+	{
+		version: 14,
+		name: "artifact-trash",
+		// See domain/artifact-trash.ts for the full design rationale. The two trigger bodies here
+		// must match SCHEMA's fresh-bootstrap versions of the same triggers byte-for-byte -- DROP
+		// then CREATE is required since SQLite has no ALTER TRIGGER.
+		up: (db) => {
+			db.exec(`
+				CREATE TABLE IF NOT EXISTS artifact_trash (
+					artifact_id  TEXT PRIMARY KEY REFERENCES artifacts(id),
+					trashed_at   TEXT NOT NULL,
+					purge_after  TEXT NOT NULL,
+					reason       TEXT
+				);
+				CREATE INDEX IF NOT EXISTS artifact_trash_purge_idx ON artifact_trash(purge_after);
+				DROP TRIGGER IF EXISTS task_events_no_delete;
+				CREATE TRIGGER task_events_no_delete BEFORE DELETE ON task_events
+				WHEN NOT EXISTS (SELECT 1 FROM artifact_trash WHERE artifact_id = OLD.task_id AND purge_after <= strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+				BEGIN SELECT RAISE(ABORT, 'task_events are append-only except during an explicit, elapsed-grace-period artifact trash purge'); END;
+				DROP TRIGGER IF EXISTS artifact_events_no_delete;
+				CREATE TRIGGER artifact_events_no_delete BEFORE DELETE ON artifact_events
+				WHEN NOT EXISTS (SELECT 1 FROM artifact_trash WHERE artifact_id = OLD.artifact_id AND purge_after <= strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+				BEGIN SELECT RAISE(ABORT, 'artifact_events are append-only except during an explicit, elapsed-grace-period artifact trash purge'); END;
+			`);
+		},
+	},
+];
 
 /**
  * Adapts Papyrus's own Db/inTransaction to daemon-kit's storage-agnostic

package/src/domain/artifact-event.ts

@@ -10,7 +10,7 @@
  */
 import { ARTIFACT_EVENT_ACTOR_MAX_LENGTH, ARTIFACT_EVENT_HISTORY_DEFAULT_LIMIT, ARTIFACT_EVENT_HISTORY_MAX_LIMIT } from "../constants.ts";
 
-export const ARTIFACT_EVENT_TYPES = ["created", "updated", "status_changed", "extra_set", "linked", "unlinked"] as const;
+export const ARTIFACT_EVENT_TYPES = ["created", "updated", "status_changed", "extra_set", "linked", "unlinked", "trashed", "restored"] as const;
 export type ArtifactEventType = typeof ARTIFACT_EVENT_TYPES[number];
 export type ArtifactEventDirection = "asc" | "desc";
 

package/src/domain/artifact-trash.ts

@@ -0,0 +1,29 @@
+/**
+ * Artifact trash: Option B from the design discussion (Doc-worthy decision, recorded here
+ * since there is no other durable home for it yet) -- `artifact.remove` is a real, narrow,
+ * time-gated exception to Papyrus's otherwise-absolute append-only invariant, not a mere
+ * status flip.
+ *
+ * The constraint that shaped this design: every artifact gets a mandatory "created" row in
+ * artifact_events at creation time (see ops.ts's createArtifact), and artifact_events is
+ * DB-trigger-enforced immutable (no UPDATE, no DELETE, ever). That means a literal
+ * `DELETE FROM artifacts` can never succeed for ANY artifact while that FK and that trigger
+ * both hold unconditionally -- there is no such thing as an artifact with "no history to
+ * protect". A real purge therefore requires the DB's own append-only triggers to carry an
+ * explicit, narrow carve-out (see db.ts's artifact_events_no_delete / task_events_no_delete),
+ * gated on the exact same elapsed-time deadline recorded here -- enforced by the database
+ * itself, not merely by application-code discipline, so a bug in the purge sweep cannot
+ * delete history before its own stated deadline.
+ *
+ * Removing an artifact does not touch it immediately: it inserts one row here recording when
+ * it becomes eligible, and from that moment the artifact is excluded from ordinary listings
+ * (see ops.ts's queryArtifacts) but still directly reachable by id (get/show) and fully
+ * restorable via artifact.restore, until purgeAfter passes and the daemon's periodic sweep
+ * (see daemon.ts) performs the real, cascading, irreversible deletion.
+ */
+export interface ArtifactTrashRecord {
+	artifactId: string;
+	trashedAt: string;
+	purgeAfter: string;
+	reason?: string;
+}

package/src/domain/artifact.ts

@@ -46,6 +46,8 @@ export interface ArtifactQuery {
 	labels?: string[];
 	extraEquals?: Record<string, string | number | boolean>;
 	limit?: number;
+	/** Trashed artifacts (see artifact-trash.ts) are excluded from every query by default; set true to include them, e.g. for a trash-listing view. */
+	includeTrashed?: boolean;
 }
 
 export interface ArtifactGraphOptions {

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/service.ts

@@ -49,6 +49,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;
@@ -173,6 +174,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 +244,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");
@@ -421,6 +428,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();