@danypops/papyrus 0.40.0 → 0.42.0

package/src/domain/skill-definition.ts

@@ -1,270 +0,0 @@
-import {
-	SEED_RELATIONS,
-	SKILL_MAX_BLUEPRINTS,
-	SKILL_MAX_ENUM_VALUES,
-	SKILL_MAX_INPUTS,
-	SKILL_MAX_LINKS,
-} from "../constants.ts";
-
-export type SkillArgumentValue = string | number | boolean;
-export type SkillInputType = "string" | "number" | "boolean";
-
-export interface SkillInputDefinition {
-	type: SkillInputType;
-	required?: boolean;
-	default?: SkillArgumentValue;
-	enum?: SkillArgumentValue[];
-}
-
-export interface SkillDocBlueprint {
-	ref: string;
-	title: string;
-	body?: string;
-	subtype?: string;
-	labels?: string[];
-	extra?: Record<string, unknown>;
-}
-
-export interface SkillRuleBlueprint {
-	ref: string;
-	title: string;
-	body?: string;
-	condition?: string;
-	action?: string;
-	severity?: "block" | "warn" | "info";
-	labels?: string[];
-	extra?: Record<string, unknown>;
-}
-
-export interface SkillTaskBlueprint {
-	ref: string;
-	title: string;
-	body?: string;
-	dependsOn?: string[];
-	parent?: string;
-	labels?: string[];
-	extra?: Record<string, unknown>;
-}
-
-/**
- * A pipeline step that nests another workflow Skill's run inside this one -- the Jenkins
- * "trigger downstream job and wait" / Ansible "include_tasks" primitive. `skillId` is late-
- * bound: existence and workflow-subtype are checked at execution time (workflow-execution.ts),
- * not here, since this validator has no store access. `dependsOn`/`parent` place this step in
- * the SAME dependency graph as ordinary task blueprints -- a task can depend on a skill-call
- * ref (meaning: depend on every task the nested run creates), and a skill-call's own `parent`
- * contains the nested run's root tasks under an outer task.
- */
-export interface SkillCallBlueprint {
-	ref: string;
-	title: string;
-	skillId: string;
-	arguments?: Record<string, unknown>;
-	dependsOn?: string[];
-	parent?: string;
-}
-
-export interface SkillBlueprints {
-	docs: SkillDocBlueprint[];
-	rules: SkillRuleBlueprint[];
-	tasks: SkillTaskBlueprint[];
-	skills: SkillCallBlueprint[];
-}
-
-export interface SkillBlueprintLink {
-	from: string;
-	relation: string;
-	to: string;
-}
-
-export interface SkillDefinition {
-	version: 1;
-	inputs: Record<string, SkillInputDefinition>;
-	blueprints: SkillBlueprints;
-	links: SkillBlueprintLink[];
-}
-
-const NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
-const PLACEHOLDER_PATTERN = /{{\s*([A-Za-z][A-Za-z0-9_-]{0,63})\s*}}/g;
-const INPUT_TYPES = new Set<SkillInputType>(["string", "number", "boolean"]);
-const RESERVED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
-const RELATIONS = new Set<string>(SEED_RELATIONS);
-
-function record(value: unknown, label: string): Record<string, unknown> {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${label} must be an object`);
-	return value as Record<string, unknown>;
-}
-
-function array(value: unknown, label: string): unknown[] {
-	if (!Array.isArray(value)) throw new Error(`${label} must be an array`);
-	return value;
-}
-
-function string(value: unknown, label: string): string {
-	if (typeof value !== "string" || value.length === 0) throw new Error(`${label} must be a non-empty string`);
-	return value;
-}
-
-function validateArgumentValue(name: string, type: SkillInputType, value: unknown): SkillArgumentValue {
-	if (typeof value !== type || (type === "number" && !Number.isFinite(value))) {
-		throw new Error(`skill argument "${name}" must be a ${type}`);
-	}
-	return value as SkillArgumentValue;
-}
-
-function validateInputs(value: unknown): Record<string, SkillInputDefinition> {
-	const source = record(value ?? {}, "skill inputs");
-	const entries = Object.entries(source);
-	if (entries.length > SKILL_MAX_INPUTS) throw new Error(`skill inputs exceed ${SKILL_MAX_INPUTS}`);
-	const result: Record<string, SkillInputDefinition> = {};
-	for (const [name, raw] of entries) {
-		if (RESERVED_KEYS.has(name)) throw new Error(`reserved skill input name "${name}"`);
-		if (!NAME_PATTERN.test(name)) throw new Error(`invalid skill input name "${name}"`);
-		const input = record(raw, `skill input "${name}"`);
-		if (!INPUT_TYPES.has(input["type"] as SkillInputType)) throw new Error(`skill input "${name}" has unsupported type`);
-		const type = input["type"] as SkillInputType;
-		if (input["required"] !== undefined && typeof input["required"] !== "boolean") {
-			throw new Error(`skill input "${name}" required must be boolean`);
-		}
-		const normalized: SkillInputDefinition = { type };
-		if (input["required"] !== undefined) normalized.required = input["required"] as boolean;
-		if (input["default"] !== undefined) normalized.default = validateArgumentValue(name, type, input["default"]);
-		if (input["enum"] !== undefined) {
-			const values = array(input["enum"], `skill input "${name}" enum`);
-			if (values.length === 0 || values.length > SKILL_MAX_ENUM_VALUES) throw new Error(`skill input "${name}" enum must contain 1-${SKILL_MAX_ENUM_VALUES} values`);
-			normalized.enum = values.map((entry) => validateArgumentValue(name, type, entry));
-			if (normalized.default !== undefined && !normalized.enum.includes(normalized.default)) {
-				throw new Error(`skill input "${name}" default must be one of its enum values`);
-			}
-		}
-		result[name] = normalized;
-	}
-	return result;
-}
-
-function validateBlueprint<T extends { ref: string; title: string }>(value: unknown, kind: string): T {
-	const source = record(value, `skill ${kind} blueprint`);
-	const ref = string(source["ref"], `skill ${kind} blueprint ref`);
-	if (!NAME_PATTERN.test(ref)) throw new Error(`invalid skill blueprint ref "${ref}"`);
-	const title = string(source["title"], `skill ${kind} blueprint title`);
-	return { ...source, ref, title } as T;
-}
-
-function placeholders(value: unknown, result: Set<string> = new Set()): Set<string> {
-	if (typeof value === "string") {
-		for (const match of value.matchAll(PLACEHOLDER_PATTERN)) result.add(match[1]!);
-	} else if (Array.isArray(value)) {
-		for (const entry of value) placeholders(entry, result);
-	} else if (typeof value === "object" && value !== null) {
-		for (const entry of Object.values(value)) placeholders(entry, result);
-	}
-	return result;
-}
-
-/** Steps sharing one dependency graph: ordinary tasks and skill-call pipeline steps alike. */
-interface DependentStep {
-	ref: string;
-	dependsOn?: string[];
-}
-
-function assertAcyclic(steps: DependentStep[]): void {
-	const byRef = new Map(steps.map((step) => [step.ref, step]));
-	const visiting = new Set<string>();
-	const visited = new Set<string>();
-	const visit = (ref: string): void => {
-		if (visiting.has(ref)) throw new Error(`skill step dependency cycle includes "${ref}"`);
-		if (visited.has(ref)) return;
-		visiting.add(ref);
-		for (const dependency of byRef.get(ref)?.dependsOn ?? []) visit(dependency);
-		visiting.delete(ref);
-		visited.add(ref);
-	};
-	for (const step of steps) visit(step.ref);
-}
-
-function validateSkillCallBlueprint(value: unknown): SkillCallBlueprint {
-	const source = record(value, "skill call blueprint");
-	const ref = string(source["ref"], "skill call blueprint ref");
-	if (!NAME_PATTERN.test(ref)) throw new Error(`invalid skill blueprint ref "${ref}"`);
-	const title = string(source["title"], "skill call blueprint title");
-	const skillId = string(source["skillId"], "skill call blueprint skillId");
-	return { ...source, ref, title, skillId } as SkillCallBlueprint;
-}
-
-export function validateSkillDefinition(value: unknown): SkillDefinition {
-	const source = record(value, "skill definition");
-	if (source["version"] !== 1) throw new Error("skill definition version must be 1");
-	const inputs = validateInputs(source["inputs"]);
-	const rawBlueprints = record(source["blueprints"], "skill blueprints");
-	const docs = array(rawBlueprints["docs"] ?? [], "skill doc blueprints").map((entry) => validateBlueprint<SkillDocBlueprint>(entry, "doc"));
-	const rules = array(rawBlueprints["rules"] ?? [], "skill rule blueprints").map((entry) => validateBlueprint<SkillRuleBlueprint>(entry, "rule"));
-	const tasks = array(rawBlueprints["tasks"] ?? [], "skill task blueprints").map((entry) => validateBlueprint<SkillTaskBlueprint>(entry, "task"));
-	const skillCalls = array(rawBlueprints["skills"] ?? [], "skill call blueprints").map(validateSkillCallBlueprint);
-	const all = [...docs, ...rules, ...tasks, ...skillCalls];
-	if (all.length === 0 || all.length > SKILL_MAX_BLUEPRINTS) throw new Error(`skill blueprints must contain 1-${SKILL_MAX_BLUEPRINTS} artifacts`);
-	const refs = new Set<string>();
-	for (const blueprint of all) {
-		if (refs.has(blueprint.ref)) throw new Error(`duplicate skill blueprint ref "${blueprint.ref}"`);
-		refs.add(blueprint.ref);
-	}
-	// Tasks and skill-call pipeline steps share one dependency graph: a task may depend on a
-	// skill-call ref (meaning: depend on every task that nested run creates), and vice versa.
-	const stepRefs = new Set<string>([...tasks.map((task) => task.ref), ...skillCalls.map((call) => call.ref)]);
-	for (const task of tasks) {
-		if (task.dependsOn !== undefined && !Array.isArray(task.dependsOn)) throw new Error(`skill task "${task.ref}" dependsOn must be an array`);
-		for (const dependency of task.dependsOn ?? []) {
-			if (!stepRefs.has(dependency)) throw new Error(`unknown skill task dependency ref "${dependency}"`);
-		}
-		// parent stays task-only: containment under a skill-call step's exploded task SET has no
-		// single natural parent, so parent must name an actual task blueprint.
-		if (task.parent !== undefined && !tasks.some((candidate) => candidate.ref === task.parent)) {
-			throw new Error(`unknown skill task parent ref "${task.parent}"`);
-		}
-	}
-	for (const call of skillCalls) {
-		if (call.dependsOn !== undefined && !Array.isArray(call.dependsOn)) throw new Error(`skill call "${call.ref}" dependsOn must be an array`);
-		for (const dependency of call.dependsOn ?? []) {
-			if (!stepRefs.has(dependency)) throw new Error(`unknown skill call dependency ref "${dependency}"`);
-		}
-		if (call.parent !== undefined && !tasks.some((candidate) => candidate.ref === call.parent)) {
-			throw new Error(`unknown skill call parent ref "${call.parent}"`);
-		}
-	}
-	assertAcyclic([...tasks, ...skillCalls]);
-	for (const name of placeholders(all)) {
-		if (!Object.hasOwn(inputs, name)) throw new Error(`unknown skill input placeholder "${name}"`);
-	}
-	const links = array(source["links"] ?? [], "skill links").map((entry) => {
-		const link = record(entry, "skill link");
-		const from = string(link["from"], "skill link from");
-		const relation = string(link["relation"], "skill link relation");
-		const to = string(link["to"], "skill link to");
-		if (!refs.has(from)) throw new Error(`unknown skill blueprint ref "${from}"`);
-		if (!refs.has(to)) throw new Error(`unknown skill blueprint ref "${to}"`);
-		if (!RELATIONS.has(relation)) throw new Error(`unknown skill link relation "${relation}"`);
-		return { from, relation, to };
-	});
-	if (links.length > SKILL_MAX_LINKS) throw new Error(`skill links exceed ${SKILL_MAX_LINKS}`);
-	return { version: 1, inputs, blueprints: { docs, rules, tasks, skills: skillCalls }, links };
-}
-
-export function resolveSkillArguments(definition: SkillDefinition, value: unknown): Record<string, SkillArgumentValue> {
-	const source = record(value ?? {}, "skill arguments");
-	for (const name of Object.keys(source)) {
-		if (!Object.hasOwn(definition.inputs, name)) throw new Error(`unknown skill argument "${name}"`);
-	}
-	const result: Record<string, SkillArgumentValue> = {};
-	for (const [name, input] of Object.entries(definition.inputs)) {
-		const raw = source[name] ?? input.default;
-		if (raw === undefined) {
-			if (input.required) throw new Error(`missing required skill argument "${name}"`);
-			continue;
-		}
-		const normalized = validateArgumentValue(name, input.type, raw);
-		if (input.enum && !input.enum.includes(normalized)) {
-			throw new Error(`skill argument "${name}" must be one of: ${input.enum.join(", ")}`);
-		}
-		result[name] = normalized;
-	}
-	return result;
-}

package/src/modules/skills.ts

@@ -1,158 +0,0 @@
-/**
- * modules/skills.ts — Skills as a Papyrus-native registered module
- * (step 5, continued, of the incremental refactor in
- * reducing-papyrus-consumer-change-amplification-with-modules--pvdo).
- *
- * skills.instantiate is intentionally NOT registered here even though its operation name
- * starts with "skills.": when the target template's targetKind is "task" it calls
- * tasks.create() directly instead of the generic instantiateTemplate path — a genuine
- * cross-module concern, same category as rules.injectable (see modules/rules.ts). It
- * stays a composition-root operation in src/service.ts.
- *
- * skills.run depends on the Task-domain ports (TaskEventStore, TaskScopeStore) as
- * constructor parameters. These are shared port contracts every module may depend on,
- * the same way every module already depends on ArtifactStore — not "another module's
- * infrastructure" in the sense of a concrete class. workflow-execution.ts already has this
- * port dependency pre-existing; untangling it is a separate, larger concern than this
- * extraction.
- */
-import type { AuthorityRegistry } from "../authority-registry.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";
-
-type OperationInput = Record<string, unknown>;
-
-function string(input: OperationInput, key: string): string {
-	const value = input[key];
-	if (typeof value !== "string" || value.length === 0) throw new Error(`${key} is required`);
-	return value;
-}
-
-function optionalString(input: OperationInput, key: string): string | undefined {
-	const value = input[key];
-	if (value === undefined) return undefined;
-	if (typeof value !== "string") throw new Error(`${key} must be a string`);
-	return value;
-}
-
-function optionalNumber(input: OperationInput, key: string): number | undefined {
-	const value = input[key];
-	if (value === undefined) return undefined;
-	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${key} must be a number`);
-	return value;
-}
-
-const eventContext = (input: OperationInput) => ({
-	actor: optionalString(input, "actor"),
-	source: optionalString(input, "source"),
-	sessionId: optionalString(input, "session_id") ?? optionalString(input, "sessionId"),
-});
-
-const eventContextFor = (input: OperationInput, source: string) => {
-	const context = eventContext(input);
-	return { ...context, source: context.source ?? source };
-};
-
-const artifactFilter = (input: OperationInput) => ({
-	status: optionalString(input, "status"),
-	text: optionalString(input, "text"),
-	limit: optionalNumber(input, "limit"),
-	projectRoot: optionalString(input, "project_root"),
-});
-
-export interface SkillsModuleDeps {
-	artifacts: ArtifactStore;
-	events: TaskEventStore;
-	scopes: TaskScopeStore;
-	/** Docs/Rules/Skills project scoping (distinct from `scopes`, which is Task-run project scoping for skills.run's materialized blueprint tasks). */
-	artifactScopes: ArtifactScopeStore;
-	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 = [
-	"skills.create", "skills.create_template", "skills.list", "skills.show", "skills.invoke", "skills.run", "skills.enable", "skills.disable", "skills.assign_project", "skills.update",
-] as const;
-
-export function skillsOperations({ artifacts, events, scopes, artifactScopes, authority }: SkillsModuleDeps): OperationDefinition[] {
-	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
-		name, moduleId: MODULE_ID, execute,
-	});
-	return [
-		define("skills.create", (input: OperationInput) => createSkill(artifacts, artifactScopes, {
-			title: string(input, "title"), body: optionalString(input, "body"), trigger: optionalString(input, "trigger"),
-			steps: input["steps"] as string[] | undefined, tools: input["tools"] as string[] | undefined,
-			definition: input["definition"],
-			labels: input["labels"] as string[] | undefined, extra: input["extra"] as Record<string, unknown> | undefined,
-			projectRoot: optionalString(input, "project_root"),
-		}, authority, eventContext(input))),
-		define("skills.create_template", (input: OperationInput) => createArtifactTemplate(artifacts, artifactScopes, {
-			title: string(input, "title"), targetKind: string(input, "target_kind"), defaults: input["defaults"] as Record<string, unknown> | undefined,
-			required: input["required"] as string[] | undefined, body: optionalString(input, "body"), labels: input["labels"] as string[] | undefined,
-			projectRoot: optionalString(input, "project_root"),
-		}, authority, eventContext(input))),
-		define("skills.list", (input: OperationInput) => listSkills(artifacts, artifactScopes, artifactFilter(input))),
-		define("skills.show", (input: OperationInput) => showSkill(artifacts, string(input, "id"))),
-		define("skills.invoke", (input: OperationInput) => skillInvocation(artifacts, string(input, "id"))),
-		define("skills.run", (input: OperationInput) => instantiateSkillWorkflow(artifacts, string(input, "id"), {
-			runId: optionalString(input, "run_id") ?? optionalString(input, "runId"),
-			arguments: input["arguments"] as Record<string, unknown> | undefined,
-		}, { events, scopes, projectRoot: string(input, "project_root"), context: eventContextFor(input, "skill-run") })),
-		define("skills.enable", (input: OperationInput) => transitionSkill(artifacts, string(input, "id"), "enable", eventContext(input))),
-		define("skills.disable", (input: OperationInput) => transitionSkill(artifacts, string(input, "id"), "disable", eventContext(input))),
-		define("skills.assign_project", (input: OperationInput) => assignSkillProject(artifacts, artifactScopes, string(input, "id"), optionalString(input, "project_root"))),
-		define("skills.update", (input: OperationInput) => updateSkill(artifacts, string(input, "id"), {
-			title: optionalString(input, "title"), body: optionalString(input, "body"), labels: input["labels"] as string[] | undefined,
-		}, eventContext(input))),
-	];
-}

package/src/vehicle/skills-vehicle.ts

@@ -1,194 +0,0 @@
-/**
- * Skills projected as a real VehicleRegistry: one VehicleOperation per real action.
- * Wraps modules/skills.ts's operation definitions plus skills.instantiate (composition-
- * root-only in the module -- see instantiateSkillOrTemplate's own doc comment).
- * remove/restore/remove_subtree are not duplicated here -- see ./artifact-trash-vehicle.ts.
- *
- * skills.run'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 -- the model reads a summary, not the raw node/layer/
- * cycleId structure.
- */
-import { bindVehicleOperation, defineVehicleOperation } from "@danypops/vehicle-core";
-import type { VehicleRegistry } from "@danypops/vehicle-server";
-import type { AuthorityRegistry } from "../authority-registry.ts";
-import { listSkills } from "../domain-services.ts";
-import { instantiateSkillOrTemplate, skillsOperations } from "../modules/skills.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 } from "../task-service.ts";
-import type { WorkflowRunResult } from "../workflow-execution.ts";
-import { buildWorkflowRunContent, looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp } from "./artifact-vehicle-shared.ts";
-
-const OWNER = "skills";
-const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
-
-export interface SkillsVehicleDeps {
-	artifacts: ArtifactStore;
-	events: TaskEventStore;
-	scopes: TaskScopeStore;
-	artifactScopes: ArtifactScopeStore;
-	authority: AuthorityRegistry;
-	/** Only for skills.instantiate's task-target branch -- see instantiateSkillOrTemplate. */
-	tasks: Tasks;
-}
-
-function resolveSkillId(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,
-		() => listSkills(artifacts, scopes, { text: name, projectRoot }),
-		projectRoot === undefined ? undefined : () => listSkills(artifacts, scopes, { text: name }),
-	);
-}
-
-function resolveTemplateId(artifacts: ArtifactStore, scopes: ArtifactScopeStore, 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,
-		() => listSkills(artifacts, scopes, { text: name, projectRoot }),
-		projectRoot === undefined ? undefined : () => listSkills(artifacts, scopes, { text: name }),
-	);
-}
-
-export function registerSkillsVehicleOperations(registry: VehicleRegistry, deps: SkillsVehicleDeps): void {
-	const { artifacts, events, scopes, artifactScopes, authority, tasks } = deps;
-	const moduleOperations = new Map(skillsOperations({ artifacts, events, scopes, artifactScopes, 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>,
-		execute?: (input: Record<string, unknown>) => unknown,
-	): void => {
-		const operation = defineVehicleOperation({
-			name: `skills.${action}`,
-			version: 1,
-			description,
-			input: looseObjectSchema(properties, required),
-			output: passthroughOutput,
-			permissions: ["skills:read", "skills:write"],
-			effect,
-			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
-			limits: LIMITS,
-		});
-		registry.register(OWNER, bindVehicleOperation(operation, () => async (context) => (execute ?? ((input: Record<string, unknown>) => call(`skills.${action}`, input)))(resolve(context.input))));
-	};
-
-	define(
-		"create",
-		"Creates a Skill -- a parameterized Task/Rule/Doc bundle, distinct from a prompt-only skill. project_root is optional (omitted = unscoped).",
-		"local-write",
-		{ title: stringProp, body: stringProp, trigger: stringProp, steps: { type: "array" }, tools: { type: "array" }, definition: { type: "object" }, labels: { type: "array" }, extra: { type: "object" }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
-		["title"],
-		(input) => input,
-	);
-
-	define(
-		"create_template",
-		"Creates a compatibility artifact-template (defaults/required fields for a target kind), distinct from a workflow Skill.",
-		"local-write",
-		{ title: stringProp, target_kind: stringProp, defaults: { type: "object" }, required: { type: "array" }, body: stringProp, labels: { type: "array" }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
-		["title", "target_kind"],
-		(input) => input,
-	);
-
-	define(
-		"list",
-		"Lists Skills 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 Skill by id or title.",
-		"read",
-		{ id: stringProp, name: stringProp, project_root: stringProp },
-		[],
-		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
-	);
-
-	define(
-		"invoke",
-		"Renders a Skill's own preview text with no side effects.",
-		"read",
-		{ id: stringProp, name: stringProp, project_root: stringProp },
-		[],
-		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
-	);
-
-	define(
-		"run",
-		"Validates arguments and atomically creates one scoped workflow run: real Tasks/Rules/Docs wired with dependsOn, one step surfacing at a time as it becomes focused -- no text dump. project_root is required here (no ambient cwd server-side); pass it explicitly.",
-		"local-write",
-		{ id: stringProp, name: stringProp, run_id: stringProp, arguments: { type: "object" }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
-		["project_root"],
-		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
-		(input) => {
-			const run = call("skills.run", input) as WorkflowRunResult;
-			const content = buildWorkflowRunContent(artifacts, `Created Skill run ${run.runId}: ${run.created.tasks.length} tasks, ${run.created.rules.length} rules, ${run.created.docs.length} docs.`, run);
-			return { ...run, content: [content] };
-		},
-	);
-
-	define(
-		"enable",
-		"Enables a Skill.",
-		"local-write",
-		{ id: stringProp, name: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
-		[],
-		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
-	);
-
-	define(
-		"disable",
-		"Disables a Skill.",
-		"local-write",
-		{ id: stringProp, name: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
-		[],
-		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
-	);
-
-	define(
-		"instantiate",
-		"Instantiates a compatibility artifact-template (template_id/template_name) -- a task-target template calls tasks.create() directly; any other target creates a plain artifact. project_root is required here (no ambient cwd server-side).",
-		"local-write",
-		{ template_id: stringProp, template_name: stringProp, title: stringProp, body: stringProp, status: stringProp, labels: { type: "array" }, extra: { type: "object" }, subtype: stringProp, kind: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
-		["title", "project_root"],
-		(input) => {
-			const templateId = resolveTemplateId(artifacts, artifactScopes, input.project_root as string | undefined, input.template_id, input.template_name);
-			if (!templateId) throw new Error("template_id or template_name is required");
-			return { ...input, template_id: templateId };
-		},
-		(input) => instantiateSkillOrTemplate({ artifacts, tasks, authority }, input, { actor: input.actor as string | undefined, source: input.source as string | undefined, sessionId: (input.session_id ?? input.sessionId) as string | undefined }),
-	);
-
-	define(
-		"assign_project",
-		"Reassigns a Skill's project_root, or unscopes it when project_root is omitted.",
-		"local-write",
-		{ id: stringProp, name: stringProp, project_root: stringProp },
-		[],
-		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, undefined, input.id, input.name) }),
-	);
-
-	define(
-		"update",
-		"Changes a Skill'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" }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
-		[],
-		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
-	);
-}