@danypops/papyrus 0.38.4 → 0.40.0

package/README.md

@@ -80,7 +80,7 @@ papyrus skills run <skill-id> \
   --json
 ```
 
-The existing `artifact-template` skill subtype remains a compatibility mechanism for one-artifact templates with metadata `{targetKind, defaults, required}`. Instantiate it through the `skills` tool's `instantiate` action with `template_id`; defaults merge recursively, explicit arrays replace defaults, required paths such as `extra.owner` are validated, and target-kind mismatches are rejected.
+The existing `artifact-template` skill subtype remains a compatibility mechanism for one-artifact templates with metadata `{targetKind, defaults, required}`. Instantiate it via the `skills.instantiate` operation with `template_id`; defaults merge recursively, explicit arrays replace defaults, required paths such as `extra.owner` are validated, and target-kind mismatches are rejected.
 
 ### Removing an artifact
 

package/package.json

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

package/src/modules/skills.ts

@@ -17,12 +17,15 @@
  * extraction.
  */
 import type { AuthorityRegistry } from "../authority-registry.ts";
-import { assignSkillProject, createArtifactTemplate, createSkill, listSkills, showSkill, skillInvocation, transitionSkill, updateSkill } from "../domain-services.ts";
+import type { Artifact, CreateArtifactInput } from "../domain/artifact.ts";
+import type { ArtifactEventContext } from "../domain/artifact-event.ts";
+import { assignSkillProject, createArtifactTemplate, createSkill, instantiateTemplate, listSkills, showSkill, skillInvocation, transitionSkill, updateSkill } from "../domain-services.ts";
 import type { OperationDefinition } from "../module-registry.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 { Tasks, TaskStatus } from "../task-service.ts";
 import { instantiateSkillWorkflow } from "../workflow-execution.ts";
 
 const MODULE_ID = "skills";
@@ -76,6 +79,45 @@ export interface SkillsModuleDeps {
 	authority: AuthorityRegistry;
 }
 
+function normalizeCreateInput(input: OperationInput): CreateArtifactInput {
+	const { template_id, ...rest } = input;
+	return { ...rest, templateId: typeof template_id === "string" ? template_id : undefined } as CreateArtifactInput;
+}
+
+/**
+ * skills.instantiate's own branching logic (compatibility-template creation vs. a
+ * task-target template's tasks.create() call) -- shared between service.ts's raw RPC
+ * forwarder and skills-vehicle.ts's Vehicle operation, the two real callers, instead
+ * of reimplemented in each. Takes `tasks: Tasks` directly rather than through
+ * SkillsModuleDeps: a genuine cross-module dependency, the same category as
+ * rules.injectable and the module comment's own reason skills.instantiate isn't
+ * registered as an operation here.
+ */
+export interface InstantiateSkillDeps {
+	artifacts: ArtifactStore;
+	tasks: Tasks;
+	authority: AuthorityRegistry;
+}
+
+export function instantiateSkillOrTemplate(deps: InstantiateSkillDeps, input: OperationInput, context?: ArtifactEventContext): Artifact {
+	const templateId = string(input, "template_id");
+	const template = deps.artifacts.get(templateId);
+	// Note ownership for a non-task template target is enforced inside instantiateTemplate's
+	// own rejectsNoteTemplate for the non-task branch below -- nothing else currently claims
+	// an unresolved (pre-template-resolution) kind, so there is no check to perform here.
+	if (template?.extra["targetKind"] !== "task") return instantiateTemplate(deps.artifacts, templateId, normalizeCreateInput(input), deps.authority, context);
+	return deps.tasks.create({
+		title: optionalString(input, "title") as string,
+		body: optionalString(input, "body"),
+		status: optionalString(input, "status") as TaskStatus | undefined,
+		labels: input["labels"] as string[] | undefined,
+		extra: input["extra"] as Record<string, unknown> | undefined,
+		templateId,
+		projectRoot: string(input, "project_root"),
+		projectSource: "cwd",
+	}, context);
+}
+
 /** Registers every skills.* operation except skills.instantiate (see module comment). Behavior is unchanged from the prior inline handlers in src/service.ts. */
 /** This module's own operation names, the single source of truth src/service.ts's EXPECTED_OPERATION_NAMES spreads in rather than re-listing by hand. skills.instantiate is deliberately absent -- see the module comment above. */
 export const SKILLS_OPERATION_NAMES = [

package/src/service.ts

@@ -24,11 +24,10 @@ import type { TaskEventStore } from "./ports/task-event-store.ts";
 import type { TaskScopeStore } from "./ports/task-scope-store.ts";
 import { Tasks, type TaskStatus } from "./task-service.ts";
 import {
-	instantiateTemplate,
 	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";
@@ -40,7 +39,7 @@ import { graphProjectionOperations, GRAPH_PROJECTION_OPERATION_NAMES } from "./m
 import { logsOperations, LOGS_OPERATION_NAMES } from "./modules/logs.ts";
 import { notesOperations, NOTES_OPERATION_NAMES } from "./modules/notes.ts";
 import { rulesOperations, RULES_OPERATION_NAMES } from "./modules/rules.ts";
-import { skillsOperations, SKILLS_OPERATION_NAMES } from "./modules/skills.ts";
+import { instantiateSkillOrTemplate, skillsOperations, SKILLS_OPERATION_NAMES } from "./modules/skills.ts";
 import { playbooksOperations, PLAYBOOKS_OPERATION_NAMES } from "./modules/playbooks.ts";
 import { sessionIdentityOperations, SESSION_IDENTITY_OPERATION_NAMES } from "./modules/session-identity.ts";
 import { discussOperations, DISCUSS_OPERATION_NAMES } from "./modules/discuss.ts";
@@ -208,12 +207,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. */
@@ -431,24 +431,7 @@ function handlers(
 		"playbooks.uncontain": forwardToModule("playbooks.uncontain"),
 		"playbooks.depend": forwardToModule("playbooks.depend"),
 		"playbooks.undepend": forwardToModule("playbooks.undepend"),
-		"skills.instantiate": (input) => {
-			const templateId = string(input, "template_id");
-			const template = artifacts.get(templateId);
-			// Note ownership for a non-task template target is enforced inside instantiateTemplate's
-			// own rejectsNoteTemplate for the non-task branch below -- nothing else currently claims
-			// an unresolved (pre-template-resolution) kind, so there is no check to perform here.
-			if (template?.extra["targetKind"] !== "task") return instantiateTemplate(artifacts, templateId, normalizeCreateInput(input), authority, eventContext(input));
-			return tasks.create({
-				title: optionalString(input, "title") as string,
-				body: optionalString(input, "body"),
-				status: optionalString(input, "status") as TaskStatus | undefined,
-				labels: input["labels"] as string[] | undefined,
-				extra: input["extra"] as Record<string, unknown> | undefined,
-				templateId,
-				projectRoot: string(input, "project_root"),
-				projectSource: "cwd",
-			}, eventContextFor(input, "template-instantiation"));
-		},
+		"skills.instantiate": (input) => instantiateSkillOrTemplate({ artifacts, tasks, authority }, input, eventContextFor(input, "template-instantiation")),
 		"graph_projection.apply": forwardToModule("graph_projection.apply"),
 		"graph_projection.checkpoint": forwardToModule("graph_projection.checkpoint"),
 		"logs.append": forwardToModule("logs.append"),
@@ -479,13 +462,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, events, taskScopes: scopes, tasks, sessionIdentity });
 	const moduleRegistry = new OperationRegistry();
 	moduleRegistry.registerAll(notesOperations(notes));
 	moduleRegistry.registerAll(logsOperations(logs));
@@ -505,7 +488,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 +548,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,126 @@
+/**
+ * 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, type VehicleContentBlock } from "@danypops/vehicle-core";
+import type { Artifact } from "../domain/artifact.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import type { TaskExecutionPlan } from "../task-execution.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;
+
+/** A known LLM tool-calling quirk: a nested-object field arrives JSON-stringified rather than as a real object. Mutates input[key] in place when it's a string, leaves it untouched otherwise. */
+export function normalizeJsonEncodedField(input: Record<string, unknown>, key: string): void {
+	const value = input[key];
+	if (typeof value !== "string") return;
+	try {
+		input[key] = JSON.parse(value);
+	} catch {
+		throw new Error(`${key} must be valid JSON`);
+	}
+}
+
+/** 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);
+	}
+}
+
+/** Synchronous equivalent of pi-papyrus's own artifactLabelsById -- server-side, a direct ArtifactStore.get() replaces the extra RPC round-trip that helper needed client-side. Disambiguates same-titled artifacts by appending their id. */
+export function labelsById(artifacts: ArtifactStore, ids: readonly string[]): Map<string, string> {
+	const uniqueIds = [...new Set(ids)];
+	const resolved = uniqueIds.map((id) => artifacts.get(id)).filter((artifact): artifact is Artifact => artifact !== null);
+	const titleCounts = new Map<string, number>();
+	for (const artifact of resolved) titleCounts.set(artifact.title, (titleCounts.get(artifact.title) ?? 0) + 1);
+	return new Map(resolved.map((artifact) => [artifact.id, (titleCounts.get(artifact.title) ?? 0) > 1 ? `${artifact.title} (${artifact.id})` : artifact.title]));
+}
+
+export interface WorkflowRunNarrativeInput {
+	runId: string;
+	created: { docs: readonly string[]; rules: readonly string[]; tasks: readonly string[] };
+	rootTaskIds: readonly string[];
+	execution: TaskExecutionPlan;
+}
+
+/**
+ * Shared between skills.run and playbooks.invoke's Vehicle operations -- both produce the
+ * same shaped narrative (ready roots, context docs, scoped rules, an execution tree), only
+ * the headline and whether an "entry task focused" line is present differ. Builds the model-
+ * facing `content` text directly, so the model reads a summary instead of the raw execution
+ * DAG -- the same shape pi-papyrus's own hand-rolled skills/playbooks tools built client-side,
+ * now built once here where the run result is actually produced.
+ */
+export function buildWorkflowRunContent(artifacts: ArtifactStore, headline: string, input: WorkflowRunNarrativeInput, extraLines: readonly string[] = []): VehicleContentBlock {
+	const nodeById = new Map(input.execution.nodes.map((node) => [node.id, node]));
+	const rootLabels = input.rootTaskIds.map((id) => nodeById.get(id)?.title ?? "unknown task");
+	const createdLabels = labelsById(artifacts, [...input.created.docs, ...input.created.rules]);
+	const titleCounts = new Map<string, number>();
+	for (const node of input.execution.nodes) titleCounts.set(node.title, (titleCounts.get(node.title) ?? 0) + 1);
+	const executionLines = input.execution.nodes
+		.map((node) => ((titleCounts.get(node.title) ?? 0) > 1 ? `  [${node.state}] ${node.title} (${node.id})` : `  [${node.state}] ${node.title}`))
+		.join("\n");
+	const text = [
+		headline,
+		...extraLines,
+		`Ready roots: ${rootLabels.join(", ") || "none"}.`,
+		`Context docs: ${input.created.docs.map((id) => createdLabels.get(id) ?? "unknown document").join(", ") || "none"}.`,
+		`Scoped rules: ${input.created.rules.map((id) => createdLabels.get(id) ?? "unknown rule").join(", ") || "none"}.`,
+		...(executionLines ? ["Execution:", executionLines] : []),
+	].join("\n");
+	return { type: "text", text };
+}

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