@danypops/papyrus 0.38.0 → 0.38.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.38.0",
+  "version": "0.38.2",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],
@@ -34,6 +34,7 @@
   },
   "files": ["src", "README.md"],
   "dependencies": {
-    "@danypops/daemon-kit": "^0.10.0"
+    "@danypops/vehicle-core": "^0.1.1",
+    "@danypops/vehicle-server": "^0.3.2"
   }
 }

package/src/cli.ts

@@ -1,9 +1,10 @@
 #!/usr/bin/env bun
 import { execFileSync } from "node:child_process";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createNodeServiceInstallDeps, generateSystemdUnit, installUserService, type ServiceSpec } from "@danypops/vehicle-server/service";
 import { connectPapyrusClient, type PapyrusClient } from "./client.ts";
 import { DAEMON_UNIT_NAME, TASK_EXECUTION_MAX_NODES, dbPath } from "./constants.ts";
 import { serveMain } from "./daemon.ts";
@@ -18,20 +19,36 @@ export interface SystemdUnitOptions {
 	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
+/**
+ * Pure text generator, delegating to vehicle-server's shared generateSystemdUnit -- kept as its
+ * own named export with the same options shape since this package's own tests (and any external
+ * caller) call it directly.
+ *
+ * Papyrus's own daemon.ts does not (yet) use vehicle-server's startDaemon/runDaemonProcess -- it's
+ * a bespoke Bun.serve() with its own state-file layout (daemon-state.ts) and maintenance-timer
+ * scheduling, predating that shared substrate. Only unit *generation* is migrated here; unitPath()
+ * stays a manual XDG_CONFIG_HOME construction rather than pulling in resolveDaemonPaths() for a
+ * database/token/handle layout Papyrus doesn't actually use. DAEMON_KIT_LAUNCH_PROVENANCE=service
+ * is emitted (generateSystemdUnit always adds it) but is currently inert -- Papyrus's daemon never
+ * reads it, since it has no idle-shutdown concept of its own. Migrating daemon.ts's own substrate
+ * is tracked separately.
+ */
+function papyrusServiceSpec(options: SystemdUnitOptions): ServiceSpec {
+	return {
+		name: "papyrus",
+		displayName: "Papyrus graph artifact service",
+		binPath: options.bunBin,
+		args: [options.cliPath, "serve"],
+		descriptorPath: unitPath(),
+		// Restart=always/RestartSec=2 already unconditional in the prior hand-rolled unit --
+		// preserved exactly, not a new opt-in.
+		restartOnFailure: true,
+		restartSec: 2,
+	};
+}
 
-[Install]
-WantedBy=default.target
-`;
+export function renderSystemdUnit(options: SystemdUnitOptions): string {
+	return generateSystemdUnit(papyrusServiceSpec(options));
 }
 
 function unitPath(): string {
@@ -53,14 +70,12 @@ function isDaemonActive(): boolean {
 }
 
 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);
+	const spec = papyrusServiceSpec({ bunBin: process.execPath, cliPath: fileURLToPath(import.meta.url) });
+	const result = installUserService(spec, createNodeServiceInstallDeps());
+	if (!result.installed) throw new Error(`failed to install the Papyrus service: ${result.reason}`);
+	// installUserService's Linux path is `enable --now` (starts if not already running) --
+	// an explicit restart on top ensures a re-install after an upgrade actually picks up the
+	// freshly-generated unit's new ExecStart path, not just re-enables the old one.
 	systemctl("restart", DAEMON_UNIT_NAME);
 }
 

package/src/client.ts

@@ -59,7 +59,7 @@ export async function connectPapyrusClient(dir: string = daemonStateDir()): Prom
 }
 
 export interface PushChannelTarget {
-	/** ws:// URL for the daemon's push-invalidation channel (see push-channel.ts in daemon-kit). */
+	/** ws:// URL for the daemon's push-invalidation channel (see push-channel.ts in vehicle-server). */
 	url: string;
 	token: string;
 }
@@ -78,3 +78,22 @@ export function resolvePushChannelTarget(dir: string = daemonStateDir()): PushCh
 	if (!handle) return undefined;
 	return { url: `${handle.baseUrl.replace(/^http/, "ws")}/push`, token: handle.token };
 }
+
+export interface VehicleClientTarget {
+	/** Base URL for a domain migrated onto VehicleRegistry (see src/vehicle/*.ts) -- @danypops/vehicle-client's RemoteVehicleClient mounts its own /vehicle/manifest, /vehicle/invoke, /vehicle/cancel routes under this. */
+	baseUrl: string;
+	token: string;
+}
+
+/**
+ * Narrow surface for a Vehicle-projected domain consumer -- same daemon, same
+ * handle file, same Bearer token every other Papyrus RPC call already uses (see
+ * service.ts's createApp, which mounts the Vehicle HTTP app at /vehicle/* on
+ * this same port). Returns undefined rather than throwing when the daemon has
+ * never started, matching resolvePushChannelTarget's own tolerance.
+ */
+export function resolveVehicleClientTarget(dir: string = daemonStateDir()): VehicleClientTarget | undefined {
+	const handle = readDaemonHandle(dir);
+	if (!handle) return undefined;
+	return { baseUrl: handle.baseUrl, token: handle.token };
+}

package/src/daemon.ts

@@ -1,4 +1,4 @@
-import { PushChannel } from "@danypops/daemon-kit/push-channel";
+import { PushChannel } from "@danypops/vehicle-server/push-channel";
 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";

package/src/db.ts

@@ -7,7 +7,7 @@ import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { runMigrations, type SqliteMigrationRunner } from "@danypops/daemon-kit/storage";
+import { runMigrations, type SqliteMigrationRunner } from "@danypops/vehicle-server/storage";
 import { SQLITE_BUSY_TIMEOUT_MS, SQLITE_SCHEMA_VERSION } from "./constants.ts";
 
 const require_ = createRequire(import.meta.url);
@@ -449,9 +449,10 @@ const LEGACY_MIGRATION_CHAIN_TARGET_VERSION = 13;
 
 /**
  * A migration beyond LEGACY_MIGRATION_CHAIN_TARGET_VERSION. Runs through @danypops/
- * daemon-kit's generic runMigrations engine (one transaction per migration, daemon-kit's
+ * vehicle-server's generic runMigrations engine (one transaction per migration, its
  * default) via dbMigrationRunner below, instead of a new branch appended to the legacy
- * if-chain -- the exact reuse daemon-kit's storage module was refactored (v0.2.1) to allow,
+ * if-chain -- the exact reuse the storage module was refactored (originally daemon-kit
+ * v0.2.1, now absorbed into vehicle-server) to allow,
  * since Papyrus's dual bun:sqlite/node:sqlite Db abstraction could never satisfy that
  * engine's original bun:sqlite-only signature.
  */
@@ -658,7 +659,7 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 ];
 
 /**
- * Adapts Papyrus's own Db/inTransaction to daemon-kit's storage-agnostic
+ * Adapts Papyrus's own Db/inTransaction to vehicle-server's storage-agnostic
  * SqliteMigrationRunner port, so its runMigrations engine (written against bun:sqlite's
  * concrete Database) runs unmodified against Papyrus's dual-runtime Db abstraction instead.
  */

package/src/domain/session-identity.ts

@@ -17,11 +17,13 @@
  *
  * The actual cryptographic primitive (secret generation, hashing, constant-time verify,
  * first-touch registration semantics) is NOT reimplemented here -- it lives in
- * @danypops/daemon-kit's session-identity module. That gap (a shared bearer token cannot
+ * @danypops/vehicle-server's session-identity module. That gap (a shared bearer token cannot
  * distinguish callers; a session id needs a real credential once it becomes behavior-
- * affecting) is generic to every daemon-kit-shaped daemon, not Papyrus-specific -- Papyrus's
- * own daemon.ts/service.ts predates daemon-kit and has not migrated onto it, but this one
- * capability is adopted narrowly regardless (daemon-kit's exports map is designed for
+ * affecting) is generic to every Vehicle-shaped daemon, not Papyrus-specific -- Papyrus's
+ * own daemon.ts/service.ts is a fully custom Bun.serve() composition root that has never
+ * adopted vehicle-server's own startDaemon()/paths conventions (its own daemon-state.ts
+ * hand-rolls path/token/port management instead), but this one narrow capability is adopted
+ * regardless (vehicle-server's exports map is designed for
  * exactly this: "a consumer only pulls in what it uses"). This file only wires that generic
  * primitive to Papyrus's own SQLite storage (see adapters/sqlite-session-identity-store.ts)
  * and to Task Focus specifically, the one place session_id is behavior-affecting today.

package/src/index.ts

@@ -19,7 +19,7 @@ export type { TaskViewSelection } from "./domain/task-scope.ts";
 export type { ArtifactStore } from "./ports/artifact-store.ts";
 export type { GraphRenderer } from "./ports/graph-renderer.ts";
 
-export { connectPapyrusClient, resolvePushChannelTarget, type PapyrusClient, type PushChannelTarget } from "./client.ts";
+export { connectPapyrusClient, resolvePushChannelTarget, resolveVehicleClientTarget, type PapyrusClient, type PushChannelTarget, type VehicleClientTarget } from "./client.ts";
 export type { DiscussionAndRounds } from "./discussion-service.ts";
 export { NOTE_DISPOSITIONS } from "./note-service.ts";
 export type { OperationName, SchemaState } from "./service.ts";

package/src/ports/session-identity-store.ts

@@ -1,9 +1,9 @@
-import type { SessionIdentityRecord, SessionIdentityStore as DaemonKitSessionIdentityStore } from "@danypops/daemon-kit/session-identity";
+import type { SessionIdentityRecord, SessionIdentityStore as VehicleSessionIdentityStore } from "@danypops/vehicle-server/session-identity";
 
 /**
- * Papyrus's persistence port for @danypops/daemon-kit's storage-agnostic session-identity
+ * Papyrus's persistence port for @danypops/vehicle-server's storage-agnostic session-identity
  * primitive -- re-exported under this project's own port naming convention (src/ports/*)
- * rather than importing the daemon-kit interface name directly at every call site.
+ * rather than importing the vehicle-server interface name directly at every call site.
  */
-export type SessionIdentityStore = DaemonKitSessionIdentityStore;
+export type SessionIdentityStore = VehicleSessionIdentityStore;
 export type { SessionIdentityRecord };

package/src/service.ts

@@ -28,6 +28,9 @@ import {
 	listInjectableRules,
 } from "./domain-services.ts";
 import { Notes, NOTE_SUBTYPE } from "./note-service.ts";
+import { createNotesVehicleRegistry } from "./vehicle/notes-vehicle.ts";
+import type { VehicleRegistry } from "@danypops/vehicle-server";
+import { createVehicleHttpApp } from "@danypops/vehicle-server/http";
 import { Logs } from "./log-service.ts";
 import { SQLiteLogStore } from "./adapters/sqlite-log-store.ts";
 import { SessionIdentity, InvalidSessionSecretError } from "./session-identity-service.ts";
@@ -204,6 +207,13 @@ export interface PapyrusService {
 	operationNames(): OperationName[];
 	schemaState(): SchemaState;
 	execute(operation: string, input?: OperationInput): Promise<unknown>;
+	/**
+	 * Notes projected as a real VehicleRegistry (see ./vehicle/notes-vehicle.ts) --
+	 * one honest VehicleOperation per real action, replacing the Pi extension's old
+	 * `notes(action=X)` mega-tool. The first domain migrated this way; not every
+	 * domain has one yet.
+	 */
+	readonly notesVehicle: VehicleRegistry;
 	checkpoint(): void;
 	optimize(): void;
 	/** Time-based Task Focus reclamation (see Tasks.reapStaleFocus); returns how many rows were removed, for daemon logging. */
@@ -469,6 +479,7 @@ export function createPapyrusService(path: string): PapyrusService {
 	const tasks = new Tasks(artifacts, gates, focus, events, scopes, leases);
 	const noteEvents = new SQLiteNoteEventStore(db);
 	const notes = new Notes(artifacts, noteEvents);
+	const notesVehicle = createNotesVehicleRegistry(notes, artifacts);
 	const projections = new SQLiteGraphProjectionStore(db);
 	const artifactScopes = new SQLiteArtifactScopeStore(db);
 	const logs = new Logs(new SQLiteLogStore(db));
@@ -494,6 +505,7 @@ export function createPapyrusService(path: string): PapyrusService {
 	return {
 		operationNames: () => [...EXPECTED_OPERATION_NAMES],
 		schemaState: state,
+		notesVehicle,
 		async execute(operation, input = {}) {
 			const handler = registry[operation as OperationName];
 			if (!handler) throw new UnknownOperationError(`unknown operation "${operation}"`);
@@ -553,12 +565,17 @@ export function createApp(deps: {
 	 */
 	onOperationExecuted?: (operation: string, input: OperationInput) => void;
 }): { fetch(request: Request): Promise<Response> } {
+	// Same Bearer token as the rest of this API -- a Vehicle-projected domain (see
+	// ./vehicle/notes-vehicle.ts) rides the same daemon, same auth, same port; it is
+	// not a second service to stand up or authenticate against separately.
+	const vehicleApp = createVehicleHttpApp({ registry: deps.service.notesVehicle, token: deps.token });
 	return {
 		async fetch(request: Request): Promise<Response> {
 			if (request.headers.get("authorization") !== `Bearer ${deps.token}`) {
 				return json({ error: "missing or invalid bearer token" }, { status: 401 });
 			}
 			const url = new URL(request.url);
+			if (url.pathname.startsWith("/vehicle/")) return vehicleApp.fetch(request);
 			if (request.method === "GET" && url.pathname === "/health") {
 				return json({ ok: true, version: VERSION, schema: deps.service.schemaState() });
 			}

package/src/session-identity-service.ts

@@ -1,4 +1,4 @@
-import { isSessionRegistered, registerSessionIdentity, releaseSessionIdentity, verifySessionSecret } from "@danypops/daemon-kit/session-identity";
+import { isSessionRegistered, registerSessionIdentity, releaseSessionIdentity, verifySessionSecret } from "@danypops/vehicle-server/session-identity";
 import { assertValidSessionId } from "./domain/session-identity.ts";
 import type { SessionIdentityStore } from "./ports/session-identity-store.ts";
 
@@ -11,7 +11,7 @@ export interface RegisterSessionIdentityResult {
 export class InvalidSessionSecretError extends Error {}
 
 /**
- * Thin Papyrus-side wrapper over @danypops/daemon-kit's storage-agnostic session-identity
+ * Thin Papyrus-side wrapper over @danypops/vehicle-server's storage-agnostic session-identity
  * primitive: validates input shape, binds it to Papyrus's own SQLite-backed store, and
  * exposes the exact three operations Task Focus enforcement needs (see
  * assertAuthorizedForFocus in src/modules/tasks.ts). See domain/session-identity.ts for the

package/src/vehicle/notes-vehicle.ts

@@ -0,0 +1,210 @@
+/**
+ * Notes projected as a real VehicleRegistry: one VehicleOperation per real
+ * action (capture/list/show/history/consume/promote/archive), each with its
+ * own honest effect and narrow schema -- replacing pi-papyrus's hand-rolled
+ * `notes(action=X)` mega-tool (unconstrained `action: Type.String()`, 14
+ * fields unioned across all 7 branches, the "God Parameters"/"Kitchen Sink
+ * tool" anti-pattern @danypops/vehicle's own README documents).
+ *
+ * Wraps modules/notes.ts's existing operation definitions rather than
+ * reimplementing their input parsing -- this is a projection/contract layer
+ * on top of the existing domain logic, not a second copy of it. Adds the
+ * one thing those definitions don't do: resolving a human-readable
+ * `name`/`target_name` to the `id`/`target_id` the domain logic actually
+ * needs, server-side in the same call. The Pi-extension-side
+ * `resolveNameFields` helper it replaces needed a separate round trip per
+ * name before the real call; this does it in one.
+ */
+import { defineVehicleOperation, defineVehicleSchema, bindVehicleOperation, type VehicleSchemaCodec } from "@danypops/vehicle-core";
+import { VehicleRegistry } from "@danypops/vehicle-server";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import { Notes, NOTE_DISPOSITIONS } from "../note-service.ts";
+import type { Artifact } from "../domain/artifact.ts";
+import { notesOperations } from "../modules/notes.ts";
+
+const OWNER = "notes";
+
+const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
+
+/**
+ * VehicleRegistry only ever calls a schema's own safeParse -- jsonSchema is
+ * descriptive metadata surfaced to a client/Pi projection, never itself
+ * enforced at runtime -- so a declared `enum` has to be checked here for
+ * real, or it's a documentation gesture, not an honest contract.
+ */
+function looseObjectSchema(properties: Record<string, { type: string; enum?: readonly string[] }>, required: readonly string[] = []): VehicleSchemaCodec<Record<string, unknown>> {
+	return defineVehicleSchema<Record<string, unknown>>({
+		jsonSchema: { type: "object", properties, required: [...required], additionalProperties: false },
+		safeParse(value) {
+			if (typeof value !== "object" || value === null || Array.isArray(value)) {
+				return { success: false, issues: [{ path: [], message: "input must be an object" }] };
+			}
+			const input = value as Record<string, unknown>;
+			for (const key of required) {
+				if (!(key in input)) return { success: false, issues: [{ path: [key], message: `${key} is required` }] };
+			}
+			for (const [key, schema] of Object.entries(properties)) {
+				if (!schema.enum || !(key in input)) continue;
+				if (!schema.enum.includes(input[key] as string)) {
+					return { success: false, issues: [{ path: [key], message: `${key} must be one of ${schema.enum.join(", ")}` }] };
+				}
+			}
+			return { success: true, value: input };
+		},
+	});
+}
+
+const passthroughOutput = defineVehicleSchema<unknown>({
+	jsonSchema: { type: "object" },
+	safeParse: (value) => ({ success: true, value }),
+});
+
+/** Exact match semantics as the Pi-extension helper it replaces (domain-tools.ts's matchArtifactByName) -- case-insensitive exact title match, refuses to guess between ambiguous matches. */
+function matchArtifactByName(candidates: readonly Artifact[], name: string): string {
+	const needle = name.trim().toLowerCase();
+	const matches = candidates.filter((artifact) => artifact.title.trim().toLowerCase() === needle);
+	if (matches.length === 0) throw new Error(`no artifact named "${name}" found in this scope`);
+	if (matches.length > 1) {
+		throw new Error(`${matches.length} artifacts are named "${name}": ${matches.map((a) => `${a.title} (${a.id})`).join(", ")} -- use id to disambiguate`);
+	}
+	return matches[0]!.id;
+}
+
+/** Resolves a note's id from either an explicit id or its title within projectRoot. */
+function resolveNoteId(notes: Notes, projectRoot: string, id: unknown, name: unknown): string {
+	if (typeof id === "string" && id.length > 0) return id;
+	if (typeof name !== "string" || name.length === 0) throw new Error("id or name is required");
+	return matchArtifactByName(notes.list({ projectRoot, text: name }), name);
+}
+
+/** Cross-kind equivalent for a promotion target -- a target can be a task, doc, rule, or skill, not just a note. Unscoped by project, matching the exact behavior of the artifact.query-backed resolution it replaces. */
+function resolveArtifactId(artifacts: ArtifactStore, id: unknown, name: unknown): string {
+	if (typeof id === "string" && id.length > 0) return id;
+	if (typeof name !== "string" || name.length === 0) throw new Error("target_id or target_name is required");
+	return matchArtifactByName(artifacts.query({ text: name }), name);
+}
+
+/**
+ * Builds a VehicleRegistry exposing every notes.* action as its own honest
+ * operation. `artifacts` is only needed for promote's cross-kind
+ * target_name resolution -- every other operation only ever touches notes
+ * themselves via `notes`.
+ */
+export function createNotesVehicleRegistry(notes: Notes, artifacts: ArtifactStore): VehicleRegistry {
+	const registry = new VehicleRegistry({ name: "papyrus-notes", version: "1.0.0", description: "Papyrus's deferred human-intent inbox." });
+	const moduleOperations = new Map(notesOperations(notes).map((op) => [op.name, op]));
+	const call = (name: string, input: Record<string, unknown>): unknown => moduleOperations.get(name)!.execute(input);
+
+	const define = (
+		action: string,
+		description: string,
+		effect: "read" | "local-write",
+		properties: Record<string, { type: string; enum?: readonly string[] }>,
+		required: readonly string[],
+		resolve: (input: Record<string, unknown>) => Record<string, unknown>,
+	): void => {
+		const operation = defineVehicleOperation({
+			name: `notes.${action}`,
+			version: 1,
+			description,
+			input: looseObjectSchema(properties, required),
+			output: passthroughOutput,
+			permissions: ["notes:read", "notes:write"],
+			effect,
+			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
+			limits: LIMITS,
+		});
+		registry.register(OWNER, bindVehicleOperation(operation, () => async (context) => call(`notes.${action}`, resolve(context.input))));
+	};
+
+	const stringProp = { type: "string" } as const;
+	const numberProp = { type: "number" } as const;
+
+	define(
+		"capture",
+		"Stores a deferred request without creating work. Returns the created note.",
+		"local-write",
+		{ body: stringProp, title: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		["body", "project_root"],
+		(input) => input,
+	);
+
+	define(
+		"list",
+		"Lists open (draft/active) notes, or a specific status, in a project.",
+		"read",
+		{ project_root: stringProp, status: { type: "string", enum: ["draft", "active", "archived"] }, text: stringProp, limit: numberProp },
+		["project_root"],
+		(input) => input,
+	);
+
+	define(
+		"show",
+		"Shows one note by id or title.",
+		"read",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		["project_root"],
+		(input) => ({ ...input, id: resolveNoteId(notes, input.project_root as string, input.id, input.name) }),
+	);
+
+	define(
+		"history",
+		"This note's own real append-only event log (captured/consumed/promoted/archived).",
+		"read",
+		{ id: stringProp, name: stringProp, project_root: stringProp, limit: numberProp, cursor: numberProp, direction: { type: "string", enum: ["asc", "desc"] } },
+		["project_root"],
+		(input) => ({ ...input, id: resolveNoteId(notes, input.project_root as string, input.id, input.name) }),
+	);
+
+	define(
+		"consume",
+		"Marks a note as considered.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp, reason: stringProp },
+		["project_root"],
+		(input) => ({ ...input, id: resolveNoteId(notes, input.project_root as string, input.id, input.name) }),
+	);
+
+	define(
+		"promote",
+		"Links a note to the Task, Doc, Rule, or Skill it was promoted into, then archives it.",
+		"local-write",
+		{
+			id: stringProp,
+			name: stringProp,
+			target_id: stringProp,
+			target_name: stringProp,
+			project_root: stringProp,
+			actor: stringProp,
+			source: stringProp,
+			session_id: stringProp,
+			reason: stringProp,
+		},
+		["project_root"],
+		(input) => ({
+			...input,
+			id: resolveNoteId(notes, input.project_root as string, input.id, input.name),
+			target_id: resolveArtifactId(artifacts, input.target_id, input.target_name),
+		}),
+	);
+
+	define(
+		"archive",
+		"Archives a note with an explicit disposition.",
+		"local-write",
+		{
+			id: stringProp,
+			name: stringProp,
+			project_root: stringProp,
+			disposition: { type: "string", enum: [...NOTE_DISPOSITIONS] },
+			actor: stringProp,
+			source: stringProp,
+			session_id: stringProp,
+			reason: stringProp,
+		},
+		["project_root", "disposition"],
+		(input) => ({ ...input, id: resolveNoteId(notes, input.project_root as string, input.id, input.name) }),
+	);
+
+	return registry;
+}