@danypops/papyrus 0.38.3 → 0.39.0

package/package.json

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

package/src/client.ts

@@ -1,5 +1,8 @@
-import { DAEMON_CLIENT_TIMEOUT_MS, DAEMON_PROBE_TIMEOUT_MS } from "./constants.ts";
-import { daemonStateDir, readDaemonHandle } from "./daemon-state.ts";
+import { spawn as spawnProcess } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { connectWithPolicy, spawnDetachedDaemon } from "@danypops/vehicle-client/daemon-client";
+import { DAEMON_CLIENT_TIMEOUT_MS, DAEMON_DIR_ENV, DAEMON_PROBE_TIMEOUT_MS } from "./constants.ts";
+import { daemonStateDir, readDaemonHandle, type DaemonHandle } from "./daemon-state.ts";
 import type { OperationName, SchemaState } from "./service.ts";
 
 export type FetchAdapter = (request: Request) => Promise<Response>;
@@ -46,9 +49,7 @@ export class PapyrusClient {
 	}
 }
 
-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");
+async function probedPapyrusClient(handle: DaemonHandle): Promise<PapyrusClient> {
 	const probe = new PapyrusClient(handle.baseUrl, handle.token, (request) => fetch(request), DAEMON_PROBE_TIMEOUT_MS);
 	try {
 		await probe.health();
@@ -58,6 +59,54 @@ export async function connectPapyrusClient(dir: string = daemonStateDir()): Prom
 	}
 }
 
+/** packages/papyrus/src/cli.ts, resolved relative to this file's own installed location, not require.resolve('@danypops/papyrus') -- this module IS that package, no cross-package lookup needed. */
+function papyrusCliPath(): string {
+	return fileURLToPath(new URL("cli.ts", import.meta.url));
+}
+
+export interface ConnectPapyrusClientOptions {
+	/**
+	 * Environment passed to an auto-spawned daemon child. Defaults to the current
+	 * process.env. Always carries DAEMON_DIR_ENV=dir so the spawned child computes
+	 * the exact same state directory this call itself reads/polls -- without this,
+	 * a caller-supplied `dir` (every real test; production always uses the default
+	 * daemonStateDir(), which the child would derive identically on its own) would
+	 * silently diverge from wherever the child actually starts writing its handle.
+	 */
+	env?: Record<string, string | undefined>;
+}
+
+/**
+ * Transparently starts the daemon first if it is not already running -- matches
+ * every other daemon-backed ecosystem package that opted into auto-start (see
+ * @danypops/vehicle-client's connectWithPolicy doc comment: web-spider opts in,
+ * lector/pi-packed fail closed by design). Papyrus previously failed closed with
+ * "install/start papyrus.service", requiring a human to separately discover and
+ * run `papyrus service install` before the very first tool call could succeed.
+ * A handle file that exists but points at a dead/unreachable daemon is a distinct
+ * failure (stale, not "never started") and is NOT auto-recovered here -- it still
+ * throws its own actionable "restart manually" error, unchanged from before.
+ */
+export async function connectPapyrusClient(dir: string = daemonStateDir(), options: ConnectPapyrusClientOptions = {}): Promise<PapyrusClient> {
+	return connectWithPolicy({
+		readHandle: () => readDaemonHandle(dir) ?? null,
+		buildClient: probedPapyrusClient,
+		autoStart: true,
+		spawn: () => {
+			spawnDetachedDaemon({
+				binPath: papyrusCliPath(),
+				args: ["serve"],
+				env: { ...(options.env ?? process.env), [DAEMON_DIR_ENV]: dir },
+				spawn: (command, args, spawnOptions) => {
+					const child = spawnProcess(command, args, spawnOptions);
+					child.unref();
+				},
+			});
+		},
+		fallbackMessage: "Papyrus daemon failed to start automatically; run `papyrus service install` or `papyrus serve` manually.",
+	});
+}
+
 export interface PushChannelTarget {
 	/** ws:// URL for the daemon's push-invalidation channel (see push-channel.ts in vehicle-server). */
 	url: string;

package/src/daemon-state.ts

@@ -12,6 +12,9 @@ import {
 export interface DaemonHandle {
 	baseUrl: string;
 	token: string;
+	host: string;
+	port: number;
+	pid: number;
 }
 
 export function daemonStateDir(
@@ -38,9 +41,9 @@ export function loadOrCreateToken(dir: string): string {
 	return token;
 }
 
-export function writeDaemonPort(dir: string, port: number): void {
+export function writeDaemonPort(dir: string, port: number, pid: number = process.pid): void {
 	mkdirSync(dir, { recursive: true });
-	writeFileSync(join(dir, DAEMON_PORT_FILE), `${port}\n`, { mode: 0o600 });
+	writeFileSync(join(dir, DAEMON_PORT_FILE), `${port}\n${pid}\n`, { mode: 0o600 });
 }
 
 export function clearDaemonPort(dir: string): void {
@@ -50,9 +53,14 @@ export function clearDaemonPort(dir: string): void {
 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());
+		const lines = readFileSync(join(dir, DAEMON_PORT_FILE), "utf8").trim().split("\n");
+		const port = Number(lines[0]);
+		// pid is absent for a handle written before this field existed -- 0 is a safe
+		// "unknown" sentinel (never a real pid), not a crash. Nothing currently reads
+		// pid to make a kill/staleness decision, so a stale 0 is inert, not unsafe.
+		const pid = lines[1] ? Number(lines[1]) : 0;
 		if (!token || !Number.isInteger(port) || port < 1 || port > 65_535) return undefined;
-		return { baseUrl: `http://${DAEMON_HOST}:${port}`, token };
+		return { baseUrl: `http://${DAEMON_HOST}:${port}`, token, host: DAEMON_HOST, port, pid };
 	} catch {
 		return undefined;
 	}

package/src/service.ts

@@ -28,7 +28,7 @@ import {
 	listInjectableRules,
 } from "./domain-services.ts";
 import { Notes, NOTE_SUBTYPE } from "./note-service.ts";
-import { createNotesVehicleRegistry } from "./vehicle/notes-vehicle.ts";
+import { createPapyrusVehicleRegistry } from "./vehicle/papyrus-vehicle.ts";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
 import { createVehicleHttpApp } from "@danypops/vehicle-server/http";
 import { Logs } from "./log-service.ts";
@@ -208,12 +208,13 @@ export interface PapyrusService {
 	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.
+	 * Every domain migrated onto Vehicle, merged into one registry/one HTTP mount
+	 * (see ./vehicle/papyrus-vehicle.ts) -- one honest VehicleOperation per real
+	 * action, replacing the Pi extension's old `<domain>(action=X)` mega-tools.
+	 * Not every domain is migrated yet -- see papyrus-vehicle.ts's own doc comment
+	 * for what still isn't and why.
 	 */
-	readonly notesVehicle: VehicleRegistry;
+	readonly vehicle: VehicleRegistry;
 	checkpoint(): void;
 	optimize(): void;
 	/** Time-based Task Focus reclamation (see Tasks.reapStaleFocus); returns how many rows were removed, for daemon logging. */
@@ -479,13 +480,13 @@ 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));
 	const sessionIdentity = new SessionIdentity(new SQLiteSessionIdentityStore(db));
 	const discussions = new Discussions(artifacts, new SQLiteDiscussionRoundStore(db));
 	const authority = createAuthorityRegistry();
+	const vehicle = createPapyrusVehicleRegistry({ artifacts, scopes: artifactScopes, authority, notes });
 	const moduleRegistry = new OperationRegistry();
 	moduleRegistry.registerAll(notesOperations(notes));
 	moduleRegistry.registerAll(logsOperations(logs));
@@ -505,7 +506,7 @@ export function createPapyrusService(path: string): PapyrusService {
 	return {
 		operationNames: () => [...EXPECTED_OPERATION_NAMES],
 		schemaState: state,
-		notesVehicle,
+		vehicle,
 		async execute(operation, input = {}) {
 			const handler = registry[operation as OperationName];
 			if (!handler) throw new UnknownOperationError(`unknown operation "${operation}"`);
@@ -565,10 +566,8 @@ 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 });
+	// Same Bearer token, daemon, and port as the rest of this API -- see ./vehicle/papyrus-vehicle.ts.
+	const vehicleApp = createVehicleHttpApp({ registry: deps.service.vehicle, token: deps.token });
 	return {
 		async fetch(request: Request): Promise<Response> {
 			if (request.headers.get("authorization") !== `Bearer ${deps.token}`) {

package/src/vehicle/artifact-trash-vehicle.ts

@@ -0,0 +1,95 @@
+/**
+ * artifact.* -- show/remove/remove_subtree/restore, identical regardless of an
+ * artifact's kind. Registered once here, shared by every domain, instead of
+ * duplicated as rules.remove/docs.remove/etc.
+ */
+import { defineVehicleOperation, bindVehicleOperation } from "@danypops/vehicle-core";
+import type { VehicleRegistry } from "@danypops/vehicle-server";
+import { removeArtifactSubtree } from "../artifact-subtree.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import type { ArtifactTrashStore } from "../ports/artifact-trash-store.ts";
+import { looseObjectSchema, numberProp, passthroughOutput, stringProp } from "./artifact-vehicle-shared.ts";
+
+const OWNER = "artifact";
+const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
+
+function eventContext(input: Record<string, unknown>): { actor?: string; source?: string; sessionId?: string } {
+	const actor = input["actor"];
+	const source = input["source"];
+	const sessionId = input["session_id"] ?? input["sessionId"];
+	return {
+		actor: typeof actor === "string" ? actor : undefined,
+		source: typeof source === "string" ? source : undefined,
+		sessionId: typeof sessionId === "string" ? sessionId : undefined,
+	};
+}
+
+function requireId(input: Record<string, unknown>): string {
+	const id = input["id"];
+	if (typeof id !== "string" || id.length === 0) throw new Error("id is required");
+	return id;
+}
+
+export function registerArtifactTrashOperations(registry: VehicleRegistry, artifacts: ArtifactStore & ArtifactTrashStore): void {
+	const define = (
+		action: string,
+		description: string,
+		effect: "read" | "local-write" | "destructive",
+		properties: Record<string, { type: string; enum?: readonly string[] }>,
+		required: readonly string[],
+		execute: (input: Record<string, unknown>) => unknown,
+	): void => {
+		const operation = defineVehicleOperation({
+			name: `artifact.${action}`,
+			version: 1,
+			description,
+			input: looseObjectSchema(properties, required),
+			output: passthroughOutput,
+			permissions: ["artifact:read", "artifact:write"],
+			effect,
+			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
+			limits: LIMITS,
+		});
+		registry.register(OWNER, bindVehicleOperation(operation, () => async (context) => execute(context.input)));
+	};
+
+	define(
+		"show",
+		"Shows any artifact (doc, task, rule, skill, playbook) by id, regardless of kind.",
+		"read",
+		{ id: stringProp, tree: { type: "boolean" } as unknown as { type: string }, depth: numberProp, max_nodes: numberProp },
+		["id"],
+		(input) => artifacts.get(requireId(input), {
+			tree: input["tree"] === true,
+			depth: typeof input["depth"] === "number" ? input["depth"] : undefined,
+			maxNodes: typeof input["max_nodes"] === "number" ? input["max_nodes"] : undefined,
+		}),
+	);
+
+	define(
+		"remove",
+		"Moves any artifact to a time-gated trash, excluded from list/query but still directly showable, restorable via artifact.restore until the purge deadline.",
+		"local-write",
+		{ id: stringProp, reason: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		["id"],
+		(input) => artifacts.trash(requireId(input), { reason: typeof input["reason"] === "string" ? input["reason"] : undefined, context: eventContext(input) }),
+	);
+
+	define(
+		"remove_subtree",
+		"Trashes an artifact and its whole `contains` subtree in one call, skipping already-trashed nodes.",
+		"local-write",
+		{ id: stringProp, reason: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		["id"],
+		(input) => removeArtifactSubtree(artifacts, requireId(input), { reason: typeof input["reason"] === "string" ? input["reason"] : undefined, context: eventContext(input) }),
+	);
+
+	define(
+		"restore",
+		"Restores a trashed artifact. Idempotent: restoring one that isn't trashed is a real no-op, not an error.",
+		"local-write",
+		{ id: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		["id"],
+		(input) => artifacts.restore(requireId(input), eventContext(input)),
+	);
+}

package/src/vehicle/artifact-vehicle-shared.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared schema helpers and name->id resolution for every per-domain
+ * VehicleRegistry projection (notes-vehicle.ts, rules-vehicle.ts, docs-vehicle.ts,
+ * artifact-trash-vehicle.ts).
+ */
+import { defineVehicleSchema, type VehicleSchemaCodec } from "@danypops/vehicle-core";
+import type { Artifact } from "../domain/artifact.ts";
+
+/**
+ * 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.
+ */
+export 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 };
+		},
+	});
+}
+
+export const passthroughOutput: VehicleSchemaCodec<unknown> = defineVehicleSchema<unknown>({
+	jsonSchema: { type: "object" },
+	safeParse: (value) => ({ success: true, value }),
+});
+
+export const stringProp = { type: "string" } as const;
+export const numberProp = { type: "number" } as const;
+
+/** Exact match semantics as the Pi-extension helper this replaces (domain-tools.ts's matchArtifactByName) -- case-insensitive exact title match, refuses to guess between ambiguous matches. */
+export 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 name to an id, retrying against `fetchWidened` (an unscoped/cross-project
+ * search) only when `fetchCandidates` finds nothing. Owns the match-or-widen control
+ * flow only -- the caller supplies its own scoped/widened list calls, since scoping
+ * differs per domain. Omit `fetchWidened` when there is no wider scope to retry.
+ */
+export function resolveArtifactIdWidened(name: string, fetchCandidates: () => readonly Artifact[], fetchWidened?: () => readonly Artifact[]): string {
+	try {
+		return matchArtifactByName(fetchCandidates(), name);
+	} catch (error) {
+		if (!(error instanceof Error) || !error.message.startsWith("no artifact named") || !fetchWidened) throw error;
+		return matchArtifactByName(fetchWidened(), name);
+	}
+}

package/src/vehicle/docs-vehicle.ts

@@ -0,0 +1,145 @@
+/**
+ * Docs projected as a real VehicleRegistry: one VehicleOperation per real action.
+ * Wraps modules/docs.ts's operation definitions. remove/restore/remove_subtree
+ * are not duplicated here -- see ./artifact-trash-vehicle.ts.
+ */
+import { defineVehicleOperation, bindVehicleOperation } from "@danypops/vehicle-core";
+import type { VehicleRegistry } from "@danypops/vehicle-server";
+import type { AuthorityRegistry } from "../authority-registry.ts";
+import { listDocuments } from "../domain-services.ts";
+import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import { docsOperations } from "../modules/docs.ts";
+import { looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp } from "./artifact-vehicle-shared.ts";
+
+const OWNER = "docs";
+const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
+
+function resolveDocId(artifacts: ArtifactStore, scopes: ArtifactScopeStore, projectRoot: string | undefined, 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 resolveArtifactIdWidened(
+		name,
+		() => listDocuments(artifacts, scopes, { text: name, projectRoot }),
+		projectRoot === undefined ? undefined : () => listDocuments(artifacts, scopes, { text: name }),
+	);
+}
+
+/** Cross-kind resolution for a link target -- can be a doc, task, rule, or skill. Unscoped, matching the exact behavior of the artifact.query-backed resolution it replaces. */
+function resolveTargetId(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 resolveArtifactIdWidened(name, () => artifacts.query({ text: name }));
+}
+
+export function registerDocsVehicleOperations(registry: VehicleRegistry, artifacts: ArtifactStore, scopes: ArtifactScopeStore, authority: AuthorityRegistry): void {
+	const moduleOperations = new Map(docsOperations(artifacts, scopes, authority).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: `docs.${action}`,
+			version: 1,
+			description,
+			input: looseObjectSchema(properties, required),
+			output: passthroughOutput,
+			permissions: ["docs:read", "docs:write"],
+			effect,
+			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
+			limits: LIMITS,
+		});
+		registry.register(OWNER, bindVehicleOperation(operation, () => async (context) => call(`docs.${action}`, resolve(context.input))));
+	};
+
+	define(
+		"create",
+		"Creates a Doc -- descriptive knowledge, not actionable work. project_root is optional (omitted = unscoped).",
+		"local-write",
+		{ title: stringProp, body: stringProp, subtype: stringProp, labels: { type: "array" } as unknown as { type: string }, extra: { type: "object" } as unknown as { type: string }, template_id: stringProp, project_root: stringProp },
+		["title"],
+		(input) => input,
+	);
+
+	define(
+		"list",
+		"Lists Docs matching an optional status/text filter, scoped to project_root when given.",
+		"read",
+		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp },
+		[],
+		(input) => input,
+	);
+
+	define(
+		"show",
+		"Shows one Doc by id or title.",
+		"read",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"activate",
+		"Activates a draft Doc.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"archive",
+		"Archives an active Doc.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"reopen",
+		"Reopens an archived Doc back to active.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"link",
+		"Links a Doc to another artifact via a typed relation. Prefer target_name over target_id -- resolved server-side, searching every kind since a link target can be a doc, task, rule, or skill.",
+		"local-write",
+		{ id: stringProp, name: stringProp, relation: { type: "string", enum: ["references", "documents", "supersedes", "relates_to", "contains", "part_of"] }, target_id: stringProp, target_name: stringProp, project_root: stringProp },
+		["relation"],
+		(input) => ({
+			...input,
+			id: resolveDocId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name),
+			target_id: resolveTargetId(artifacts, input.target_id, input.target_name),
+		}),
+	);
+
+	define(
+		"assign_project",
+		"Reassigns a Doc's project_root, or unscopes it when project_root is omitted.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, undefined, input.id, input.name) }),
+	);
+
+	define(
+		"update",
+		"Changes a Doc's title/body/labels (at least one required). Refused for a read-only external projection (e.g. web-spider-ingested Docs) -- capture a correction as a new linked Doc instead.",
+		"local-write",
+		{ id: stringProp, name: stringProp, title: stringProp, body: stringProp, labels: { type: "array" } as unknown as { type: string }, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+}

package/src/vehicle/notes-vehicle.ts

@@ -1,97 +1,46 @@
 /**
- * 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).
+ * Notes projected as a real VehicleRegistry: one VehicleOperation per real action
+ * (capture/list/show/history/consume/promote/archive), each with its own effect
+ * and narrow schema, instead of one `action: Type.String()` dispatch tool.
  *
- * 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.
+ * Wraps modules/notes.ts's operation definitions rather than reimplementing their
+ * input parsing. Resolves `name`/`target_name` to `id`/`target_id` server-side, in
+ * the same call -- avoids a separate round trip per name before the real call.
  */
-import { defineVehicleOperation, defineVehicleSchema, bindVehicleOperation, type VehicleSchemaCodec } from "@danypops/vehicle-core";
-import { VehicleRegistry } from "@danypops/vehicle-server";
+import { defineVehicleOperation, bindVehicleOperation } from "@danypops/vehicle-core";
+import type { 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";
+import { looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp } from "./artifact-vehicle-shared.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);
+	return resolveArtifactIdWidened(name, () => notes.list({ projectRoot, text: 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);
+	return resolveArtifactIdWidened(name, () => artifacts.query({ text: 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`.
+ * Registers every notes.* action as its own honest VehicleOperation onto an
+ * existing registry (see ./papyrus-vehicle.ts for the composition root that
+ * merges every domain's operations into one registry/one HTTP mount).
+ * `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." });
+export function registerNotesVehicleOperations(registry: VehicleRegistry, notes: Notes, artifacts: ArtifactStore): void {
 	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);
 
@@ -117,9 +66,6 @@ export function createNotesVehicleRegistry(notes: Notes, artifacts: ArtifactStor
 		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.",
@@ -205,6 +151,4 @@ export function createNotesVehicleRegistry(notes: Notes, artifacts: ArtifactStor
 		["project_root", "disposition"],
 		(input) => ({ ...input, id: resolveNoteId(notes, input.project_root as string, input.id, input.name) }),
 	);
-
-	return registry;
 }

package/src/vehicle/papyrus-vehicle.ts

@@ -0,0 +1,35 @@
+/**
+ * Composition root for every domain projected onto Vehicle -- one VehicleRegistry,
+ * one HTTP mount (see service.ts's createApp). Operation names are already globally
+ * unique via their own dotted prefix (notes.*, rules.*, docs.*, artifact.*), so
+ * merging costs nothing and avoids a separate registry/mount/client per domain.
+ *
+ * skills, playbooks, discuss, and tasks still register via pi-papyrus's own
+ * pi.registerTool() in domain-tools.ts, not here.
+ */
+import { VehicleRegistry } from "@danypops/vehicle-server";
+import type { AuthorityRegistry } from "../authority-registry.ts";
+import type { Notes } from "../note-service.ts";
+import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import type { ArtifactTrashStore } from "../ports/artifact-trash-store.ts";
+import { registerArtifactTrashOperations } from "./artifact-trash-vehicle.ts";
+import { registerDocsVehicleOperations } from "./docs-vehicle.ts";
+import { registerNotesVehicleOperations } from "./notes-vehicle.ts";
+import { registerRulesVehicleOperations } from "./rules-vehicle.ts";
+
+export interface PapyrusVehicleDeps {
+	artifacts: ArtifactStore & ArtifactTrashStore;
+	scopes: ArtifactScopeStore;
+	authority: AuthorityRegistry;
+	notes: Notes;
+}
+
+export function createPapyrusVehicleRegistry(deps: PapyrusVehicleDeps): VehicleRegistry {
+	const registry = new VehicleRegistry({ name: "papyrus", version: "1.0.0", description: "Papyrus's graph-artifact domains, one honest operation per real action." });
+	registerNotesVehicleOperations(registry, deps.notes, deps.artifacts);
+	registerRulesVehicleOperations(registry, deps.artifacts, deps.scopes);
+	registerDocsVehicleOperations(registry, deps.artifacts, deps.scopes, deps.authority);
+	registerArtifactTrashOperations(registry, deps.artifacts);
+	return registry;
+}

package/src/vehicle/rules-vehicle.ts

@@ -0,0 +1,153 @@
+/**
+ * Rules projected as a real VehicleRegistry: one VehicleOperation per real action.
+ * Wraps modules/rules.ts's operation definitions (rules.injectable stays a
+ * composition-root-only concern, absent here too). remove/restore/remove_subtree
+ * are not duplicated here -- see ./artifact-trash-vehicle.ts.
+ */
+import { defineVehicleOperation, bindVehicleOperation } from "@danypops/vehicle-core";
+import type { VehicleRegistry } from "@danypops/vehicle-server";
+import { listRules } from "../domain-services.ts";
+import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import { rulesOperations } from "../modules/rules.ts";
+import { looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp } from "./artifact-vehicle-shared.ts";
+
+const OWNER = "rules";
+const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
+
+/** Resolves a rule's id from either an explicit id or its title, widened past project_root when unscoped-vs-scoped search finds nothing. */
+function resolveRuleId(artifacts: ArtifactStore, scopes: ArtifactScopeStore, projectRoot: string | undefined, 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 resolveArtifactIdWidened(
+		name,
+		() => listRules(artifacts, scopes, { text: name, projectRoot }),
+		projectRoot === undefined ? undefined : () => listRules(artifacts, scopes, { text: name }),
+	);
+}
+
+/**
+ * Resolves a task's id from its title for rules.gate. No ambient cwd to default
+ * project_root to server-side -- pass project_root explicitly, or this searches
+ * unscoped.
+ */
+function resolveTaskId(artifacts: ArtifactStore, projectRoot: string | undefined, id: unknown, name: unknown): string | undefined {
+	if (typeof id === "string" && id.length > 0) return id;
+	if (typeof name !== "string" || name.length === 0) return undefined;
+	return resolveArtifactIdWidened(
+		name,
+		() => artifacts.query({ kind: "task", text: name }),
+	);
+}
+
+export function registerRulesVehicleOperations(registry: VehicleRegistry, artifacts: ArtifactStore, scopes: ArtifactScopeStore): void {
+	const moduleOperations = new Map(rulesOperations(artifacts, scopes).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: `rules.${action}`,
+			version: 1,
+			description,
+			input: looseObjectSchema(properties, required),
+			output: passthroughOutput,
+			permissions: ["rules:read", "rules:write"],
+			effect,
+			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
+			limits: LIMITS,
+		});
+		registry.register(OWNER, bindVehicleOperation(operation, () => async (context) => call(`rules.${action}`, resolve(context.input))));
+	};
+
+	define(
+		"create",
+		"Creates a Rule -- a standing constraint injected into the agent system prompt while active. project_root is optional (omitted = unscoped).",
+		"local-write",
+		{ title: stringProp, body: stringProp, condition: stringProp, rule_action: stringProp, severity: { type: "string", enum: ["block", "warn", "info"] }, labels: { type: "array" } as unknown as { type: string }, extra: { type: "object" } as unknown as { type: string }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		["title"],
+		(input) => input,
+	);
+
+	define(
+		"list",
+		"Lists Rules matching an optional status/text filter, scoped to project_root when given.",
+		"read",
+		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp },
+		[],
+		(input) => input,
+	);
+
+	define(
+		"show",
+		"Shows one Rule by id or title.",
+		"read",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveRuleId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"preview",
+		"Renders a Rule's own condition/action/body preview text with no side effects.",
+		"read",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveRuleId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"enable",
+		"Enables a Rule so it starts injecting into the agent system prompt.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveRuleId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"disable",
+		"Disables a Rule; it stops injecting into the agent system prompt.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveRuleId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"gate",
+		"Attaches a Rule as a gate condition on a Task. Prefer task_name over task_id -- resolved server-side (unscoped if project_root is omitted, since there is no ambient cwd to default to here).",
+		"local-write",
+		{ id: stringProp, name: stringProp, task_id: stringProp, task_name: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => {
+			const taskId = resolveTaskId(artifacts, input.project_root as string | undefined, input.task_id, input.task_name);
+			if (!taskId) throw new Error("task_id or task_name is required");
+			return { ...input, id: resolveRuleId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name), task_id: taskId };
+		},
+	);
+
+	define(
+		"assign_project",
+		"Reassigns a Rule's project_root, or unscopes it when project_root is omitted.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveRuleId(artifacts, scopes, undefined, input.id, input.name) }),
+	);
+
+	define(
+		"update",
+		"Changes a Rule's title/body/labels (at least one required). Body updates still enforce the same combined condition+action+body context-tax bound as creation.",
+		"local-write",
+		{ id: stringProp, name: stringProp, title: stringProp, body: stringProp, labels: { type: "array" } as unknown as { type: string }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveRuleId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+}