@danypops/papyrus 0.38.4 → 0.40.0

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,48 @@
+/**
+ * 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.*, skills.*, playbooks.*,
+ * artifact.*), so merging costs nothing and avoids a separate registry/mount/client
+ * per domain.
+ *
+ * discuss and tasks still register via pi-papyrus's own pi.registerTool() in
+ * domain-tools.ts, not here -- see the papyrus Vehicle migration task for why.
+ */
+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 type { SessionIdentity } from "../session-identity-service.ts";
+import type { TaskEventStore } from "../ports/task-event-store.ts";
+import type { TaskScopeStore } from "../ports/task-scope-store.ts";
+import type { Tasks } from "../task-service.ts";
+import { registerArtifactTrashOperations } from "./artifact-trash-vehicle.ts";
+import { registerDocsVehicleOperations } from "./docs-vehicle.ts";
+import { registerNotesVehicleOperations } from "./notes-vehicle.ts";
+import { registerPlaybooksVehicleOperations } from "./playbooks-vehicle.ts";
+import { registerRulesVehicleOperations } from "./rules-vehicle.ts";
+import { registerSkillsVehicleOperations } from "./skills-vehicle.ts";
+
+export interface PapyrusVehicleDeps {
+	artifacts: ArtifactStore & ArtifactTrashStore;
+	scopes: ArtifactScopeStore;
+	authority: AuthorityRegistry;
+	notes: Notes;
+	events: TaskEventStore;
+	taskScopes: TaskScopeStore;
+	tasks: Tasks;
+	sessionIdentity: SessionIdentity;
+}
+
+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);
+	registerSkillsVehicleOperations(registry, { artifacts: deps.artifacts, events: deps.events, scopes: deps.taskScopes, artifactScopes: deps.scopes, authority: deps.authority, tasks: deps.tasks });
+	registerPlaybooksVehicleOperations(registry, { artifacts: deps.artifacts, events: deps.events, scopes: deps.taskScopes, artifactScopes: deps.scopes, tasks: deps.tasks, sessionIdentity: deps.sessionIdentity });
+	registerArtifactTrashOperations(registry, deps.artifacts);
+	return registry;
+}

package/src/vehicle/playbooks-vehicle.ts

@@ -0,0 +1,243 @@
+/**
+ * Playbooks projected as a real VehicleRegistry: one VehicleOperation per real action.
+ * Wraps modules/playbooks.ts's operation definitions. remove/restore/remove_subtree are
+ * not duplicated here -- see ./artifact-trash-vehicle.ts.
+ *
+ * playbooks.invoke's own module handler calls tasks.focus() directly (bypassing the
+ * guarded tasks.focus operation, per modules/playbooks.ts's own doc comment) and re-runs
+ * that exact guard itself via sessionIdentity.assertAuthorized(session_id, session_secret).
+ * Those two fields never belong in this operation's model-visible inputSchema -- a model
+ * has no business knowing or supplying a session secret. Instead they travel through
+ * VehicleInvocationOptions.principal.claims, populated by pi-papyrus's own
+ * resolveInvocation hook (see vehicle-notes-client.ts) from its own already-cached
+ * session_secret, the same value the hand-rolled tool used to thread through as a raw
+ * input field. A caller with no cached secret for this session (unregistered, or a non-Pi
+ * Vehicle client) simply gets the guard's own no-op-when-unset default, unchanged.
+ *
+ * invoke's output carries its own `content` block (see @danypops/vehicle-core's
+ * WithVehicleContent) built from the same execution-DAG summary pi-papyrus's hand-rolled
+ * tool used to build client-side.
+ */
+import { bindVehicleOperation, defineVehicleOperation, type VehicleOperationContext } from "@danypops/vehicle-core";
+import type { VehicleRegistry } from "@danypops/vehicle-server";
+import { listPlaybooks } from "../domain-services.ts";
+import { playbooksOperations } from "../modules/playbooks.ts";
+import type { PlaybookInvocationResult, PlaybookMissingArguments } from "../playbook-execution.ts";
+import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import type { TaskEventStore } from "../ports/task-event-store.ts";
+import type { TaskScopeStore } from "../ports/task-scope-store.ts";
+import type { SessionIdentity } from "../session-identity-service.ts";
+import type { Tasks } from "../task-service.ts";
+import { buildWorkflowRunContent, looseObjectSchema, normalizeJsonEncodedField, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp } from "./artifact-vehicle-shared.ts";
+
+const OWNER = "playbooks";
+const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
+
+export interface PlaybooksVehicleDeps {
+	artifacts: ArtifactStore;
+	events: TaskEventStore;
+	scopes: TaskScopeStore;
+	artifactScopes: ArtifactScopeStore;
+	tasks: Tasks;
+	sessionIdentity: SessionIdentity;
+}
+
+/** Unscoped resolution -- a Playbook is commonly cross-project (e.g. a lab-deploy playbook), matching the hand-rolled tool's own resolutionRequest choice. */
+function resolvePlaybookId(artifacts: ArtifactStore, scopes: ArtifactScopeStore, 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, () => listPlaybooks(artifacts, scopes, { text: name }));
+}
+
+export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, deps: PlaybooksVehicleDeps): void {
+	const { artifacts, events, scopes, artifactScopes, tasks, sessionIdentity } = deps;
+	const moduleOperations = new Map(playbooksOperations({ artifacts, events, scopes, artifactScopes, tasks, sessionIdentity }).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>,
+		execute?: (input: Record<string, unknown>, context: VehicleOperationContext<Record<string, unknown>>) => unknown,
+	): void => {
+		const operation = defineVehicleOperation({
+			name: `playbooks.${action}`,
+			version: 1,
+			description,
+			input: looseObjectSchema(properties, required),
+			output: passthroughOutput,
+			permissions: ["playbooks:read", "playbooks:write"],
+			effect,
+			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
+			limits: LIMITS,
+		});
+		registry.register(OWNER, bindVehicleOperation(operation, () => async (context) => (execute ?? ((input: Record<string, unknown>) => call(`playbooks.${action}`, input)))(resolve(context.input), context)));
+	};
+
+	define(
+		"create",
+		"Creates a Playbook -- prose: a trigger and an ordered list of steps. `arguments` declares named inputs: [{name, description?, required?}] (required defaults true), referenced in step text as {{name}}. project_root is optional (omitted = unscoped).",
+		"local-write",
+		{ title: stringProp, body: stringProp, trigger: stringProp, steps: { type: "array" }, tools: { type: "array" }, arguments: { type: "array" }, labels: { type: "array" }, extra: { type: "object" }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		["title"],
+		(input) => {
+			normalizeJsonEncodedField(input, "arguments");
+			return input;
+		},
+	);
+
+	define(
+		"list",
+		"Lists Playbooks 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 Playbook by id or title.",
+		"read",
+		{ id: stringProp, name: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"preview",
+		"Renders a Playbook's whole composition tree as text, with no side effects.",
+		"read",
+		{ id: stringProp, name: stringProp, arguments: { type: "object" } },
+		[],
+		(input) => {
+			normalizeJsonEncodedField(input, "arguments");
+			return { ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) };
+		},
+	);
+
+	define(
+		"invoke",
+		"Compiles the Playbook's steps and composition tree into real Tasks wired with dependsOn, and focuses the first one -- one step surfaces at a time as it becomes focused, exactly like any other Task. `arguments` supplies known values as {name: value}; if a declared REQUIRED argument is still missing, nothing is created and missingArguments is returned instead -- ask the human for these (discuss tool, live:true) and invoke again, never guess. Drive the returned entryTaskId forward with the tasks tool (start/submit/complete).",
+		"local-write",
+		{ id: stringProp, name: stringProp, run_id: stringProp, arguments: { type: "object" }, project_root: stringProp },
+		[],
+		(input) => {
+			normalizeJsonEncodedField(input, "arguments");
+			return { ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) };
+		},
+		(input, context) => {
+			const claims = context.principal?.claims as { sessionId?: string; sessionSecret?: string } | undefined;
+			const invocation = call("playbooks.invoke", {
+				...input,
+				session_id: claims?.sessionId,
+				session_secret: claims?.sessionSecret,
+			}) as PlaybookInvocationResult | PlaybookMissingArguments;
+			if ("missingArguments" in invocation) {
+				const text = `Missing required argument(s): ${invocation.missingArguments.join(", ")}. Nothing was created -- ask the human for these (discuss tool, live:true), then invoke again.`;
+				return { ...invocation, content: [{ type: "text" as const, text }] };
+			}
+			const nodeById = new Map(invocation.execution.nodes.map((node) => [node.id, node]));
+			const entryLabel = nodeById.get(invocation.entryTaskId)?.title ?? invocation.entryTaskId;
+			const content = buildWorkflowRunContent(
+				artifacts,
+				`Invoked playbook run ${invocation.runId}: ${invocation.created.tasks.length} task(s), ${invocation.created.rules.length} rule(s), ${invocation.created.docs.length} doc(s) created.`,
+				invocation,
+				[`Entry task now focused: ${entryLabel}. Drive it forward with the tasks tool (start/submit/complete) -- contains/depends_on wiring auto-focuses each next step.`],
+			);
+			return { ...invocation, content: [content] };
+		},
+	);
+
+	define(
+		"enable",
+		"Enables a Playbook.",
+		"local-write",
+		{ id: stringProp, name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"disable",
+		"Disables a Playbook.",
+		"local-write",
+		{ id: stringProp, name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"assign_project",
+		"Reassigns a Playbook's project_root, or unscopes it when project_root is omitted.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"update",
+		"Changes a Playbook's title/body/labels (at least one required). Refused for a read-only external projection.",
+		"local-write",
+		{ id: stringProp, name: stringProp, title: stringProp, body: stringProp, labels: { type: "array" }, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"contain",
+		"Nests a child Playbook inside a parent -- the child's steps run AFTER the parent's own. Prefer parent_name/child_name over parent_id/child_id -- resolved server-side.",
+		"local-write",
+		{ parent_id: stringProp, parent_name: stringProp, child_id: stringProp, child_name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({
+			...input,
+			parent_id: resolvePlaybookId(artifacts, artifactScopes, input.parent_id, input.parent_name),
+			child_id: resolvePlaybookId(artifacts, artifactScopes, input.child_id, input.child_name),
+		}),
+	);
+
+	define(
+		"uncontain",
+		"Removes a parent/child Playbook nesting. Idempotent -- a no-op if the edge is already absent.",
+		"local-write",
+		{ parent_id: stringProp, parent_name: stringProp, child_id: stringProp, child_name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({
+			...input,
+			parent_id: resolvePlaybookId(artifacts, artifactScopes, input.parent_id, input.parent_name),
+			child_id: resolvePlaybookId(artifacts, artifactScopes, input.child_id, input.child_name),
+		}),
+	);
+
+	define(
+		"depend",
+		"Chains a prerequisite Playbook before another -- it must fully complete FIRST. Prefer dependency_name over dependency_id.",
+		"local-write",
+		{ id: stringProp, name: stringProp, dependency_id: stringProp, dependency_name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({
+			...input,
+			id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name),
+			dependency_id: resolvePlaybookId(artifacts, artifactScopes, input.dependency_id, input.dependency_name),
+		}),
+	);
+
+	define(
+		"undepend",
+		"Removes a Playbook dependency. Idempotent -- a no-op if the edge is already absent.",
+		"local-write",
+		{ id: stringProp, name: stringProp, dependency_id: stringProp, dependency_name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({
+			...input,
+			id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name),
+			dependency_id: resolvePlaybookId(artifacts, artifactScopes, input.dependency_id, input.dependency_name),
+		}),
+	);
+}

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) }),
+	);
+}