@danypops/papyrus 0.41.0 → 0.42.1

package/src/discussion-service.ts

@@ -4,8 +4,13 @@
  * design rationale.
  */
 import { DISCUSSION_LIST_DEFAULT_LIMIT, DISCUSSION_LIST_MAX_LIMIT, DISCUSSION_MAX_ROUNDS } from "./constants.ts";
+import type { Artifact } from "./domain/artifact.ts";
+import type { ArtifactEventContext } from "./domain/artifact-event.ts";
 import {
 	DISCUSSION_SUBTYPE,
+	type DiscussionExtra,
+	type DiscussionOptionsMode,
+	type DiscussionRound,
 	isDiscussionArtifact,
 	readDiscussionExtra,
 	validateDeferReason,
@@ -14,12 +19,7 @@ import {
 	validateDiscussionOptions,
 	validateSelectedOptions,
 	validateSettlement,
-	type DiscussionExtra,
-	type DiscussionOptionsMode,
-	type DiscussionRound,
 } from "./domain/discussion.ts";
-import type { Artifact } from "./domain/artifact.ts";
-import type { ArtifactEventContext } from "./domain/artifact-event.ts";
 import type { AtomicArtifactStore } from "./ports/atomic-artifact-store.ts";
 import type { DiscussionRoundStore } from "./ports/discussion-round-store.ts";
 
@@ -72,7 +72,11 @@ export class Discussions {
 	}
 
 	/** Validates a freshly-posed choice; undefined when neither field is given (nothing posed), since both/neither is the only valid shape. */
-	private validatePosedOptions(options: string[] | undefined, optionsMode: DiscussionOptionsMode | undefined, optionDescriptions: string[] | undefined): { options: string[]; mode: DiscussionOptionsMode; optionDescriptions?: string[] } | undefined {
+	private validatePosedOptions(
+		options: string[] | undefined,
+		optionsMode: DiscussionOptionsMode | undefined,
+		optionDescriptions: string[] | undefined,
+	): { options: string[]; mode: DiscussionOptionsMode; optionDescriptions?: string[] } | undefined {
 		if (options === undefined && optionsMode === undefined) return undefined;
 		return validateDiscussionOptions(options ?? [], optionsMode ?? "", optionDescriptions);
 	}
@@ -82,25 +86,46 @@ export class Discussions {
 		const content = validateDiscussionContent(input.content);
 		const posed = this.validatePosedOptions(input.options, input.optionsMode, input.optionDescriptions);
 		return this.artifacts.atomic(() => {
-			const discussion = this.artifacts.create({
-				kind: "task",
-				subtype: DISCUSSION_SUBTYPE,
-				title: input.title,
-				body: input.body ?? "",
-				status: "in-progress",
-				labels: input.labels,
-				extra: {
-					discussion: {
-						state: "active",
-						roundCount: 1,
-						...(posed ? { pendingOptions: posed.options, pendingOptionsMode: posed.mode, ...(posed.optionDescriptions ? { pendingOptionDescriptions: posed.optionDescriptions } : {}) } : {}),
+			const discussion = this.artifacts.create(
+				{
+					kind: "task",
+					subtype: DISCUSSION_SUBTYPE,
+					title: input.title,
+					body: input.body ?? "",
+					status: "in-progress",
+					labels: input.labels,
+					extra: {
+						discussion: {
+							state: "active",
+							roundCount: 1,
+							...(posed
+								? {
+										pendingOptions: posed.options,
+										pendingOptionsMode: posed.mode,
+										...(posed.optionDescriptions ? { pendingOptionDescriptions: posed.optionDescriptions } : {}),
+									}
+								: {}),
+						},
 					},
 				},
-			}, context);
-			const round = this.rounds.append({
-				discussionId: discussion.id, roundNumber: 1, actor, content,
-				...(posed ? { options: posed.options, optionsMode: posed.mode, ...(posed.optionDescriptions ? { optionDescriptions: posed.optionDescriptions } : {}) } : {}),
-			}, new Date().toISOString());
+				context,
+			);
+			const round = this.rounds.append(
+				{
+					discussionId: discussion.id,
+					roundNumber: 1,
+					actor,
+					content,
+					...(posed
+						? {
+								options: posed.options,
+								optionsMode: posed.mode,
+								...(posed.optionDescriptions ? { optionDescriptions: posed.optionDescriptions } : {}),
+							}
+						: {}),
+				},
+				new Date().toISOString(),
+			);
 			for (const taskId of input.blocksTaskIds ?? []) this.block(discussion.id, taskId, context);
 			return { discussion: this.artifacts.get(discussion.id)!, rounds: [round] };
 		});
@@ -114,24 +139,49 @@ export class Discussions {
 			const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
 			const state = this.extra(discussion);
 			if (state.state !== "active") throw new DiscussionError(`discussion "${discussionId}" is ${state.state}; resume it before replying`);
-			if (state.roundCount >= DISCUSSION_MAX_ROUNDS) throw new DiscussionError(`discussion "${discussionId}" has reached its ${DISCUSSION_MAX_ROUNDS}-round limit; settle or defer it`);
-			const selected = input.selected !== undefined ? validateSelectedOptions(input.selected, state.pendingOptions, state.pendingOptionsMode) : undefined;
+			if (state.roundCount >= DISCUSSION_MAX_ROUNDS)
+				throw new DiscussionError(`discussion "${discussionId}" has reached its ${DISCUSSION_MAX_ROUNDS}-round limit; settle or defer it`);
+			const selected =
+				input.selected !== undefined ? validateSelectedOptions(input.selected, state.pendingOptions, state.pendingOptionsMode) : undefined;
 			const nextRound = state.roundCount + 1;
-			const round = this.rounds.append({
-				discussionId, roundNumber: nextRound, actor: validActor, content: validContent,
-				...(posed ? { options: posed.options, optionsMode: posed.mode, ...(posed.optionDescriptions ? { optionDescriptions: posed.optionDescriptions } : {}) } : {}),
-				...(selected ? { selected } : {}),
-			}, new Date().toISOString());
+			const round = this.rounds.append(
+				{
+					discussionId,
+					roundNumber: nextRound,
+					actor: validActor,
+					content: validContent,
+					...(posed
+						? {
+								options: posed.options,
+								optionsMode: posed.mode,
+								...(posed.optionDescriptions ? { optionDescriptions: posed.optionDescriptions } : {}),
+							}
+						: {}),
+					...(selected ? { selected } : {}),
+				},
+				new Date().toISOString(),
+			);
 			// Whenever this round answers the pending choice OR poses a new one, the base must drop ALL
 			// three pending* fields first -- otherwise a re-pose that omits descriptions this time would
 			// leave a stale pendingOptionDescriptions array (sized for the OLD options) spread through
 			// unchanged, no longer aligned 1:1 with the new pendingOptions. Only a plain reply that
 			// neither answers nor re-poses leaves the existing pending state untouched.
-			const { pendingOptions: _clearedOptions, pendingOptionsMode: _clearedMode, pendingOptionDescriptions: _clearedDescriptions, ...withoutPending } = state;
+			const {
+				pendingOptions: _clearedOptions,
+				pendingOptionsMode: _clearedMode,
+				pendingOptionDescriptions: _clearedDescriptions,
+				...withoutPending
+			} = state;
 			const nextState = {
 				...(selected || posed ? withoutPending : state),
 				roundCount: nextRound,
-				...(posed ? { pendingOptions: posed.options, pendingOptionsMode: posed.mode, ...(posed.optionDescriptions ? { pendingOptionDescriptions: posed.optionDescriptions } : {}) } : {}),
+				...(posed
+					? {
+							pendingOptions: posed.options,
+							pendingOptionsMode: posed.mode,
+							...(posed.optionDescriptions ? { pendingOptionDescriptions: posed.optionDescriptions } : {}),
+						}
+					: {}),
 			};
 			const updated = this.artifacts.setExtra(discussionId, { ...discussion.extra, discussion: nextState }, context)!;
 			return { discussion: updated, rounds: [round] };
@@ -143,11 +193,16 @@ export class Discussions {
 		return this.artifacts.atomic(() => {
 			const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
 			const state = this.extra(discussion);
-			if (state.state !== "active") throw new DiscussionError(`discussion "${discussionId}" is ${state.state}; only an active Discussion can be deferred`);
-			return this.artifacts.setExtra(discussionId, {
-				...discussion.extra,
-				discussion: { ...state, state: "deferred", ...(validReason === undefined ? {} : { deferredReason: validReason }) },
-			}, context)!;
+			if (state.state !== "active")
+				throw new DiscussionError(`discussion "${discussionId}" is ${state.state}; only an active Discussion can be deferred`);
+			return this.artifacts.setExtra(
+				discussionId,
+				{
+					...discussion.extra,
+					discussion: { ...state, state: "deferred", ...(validReason === undefined ? {} : { deferredReason: validReason }) },
+				},
+				context,
+			)!;
 		});
 	}
 
@@ -155,7 +210,8 @@ export class Discussions {
 		return this.artifacts.atomic(() => {
 			const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
 			const state = this.extra(discussion);
-			if (state.state !== "deferred") throw new DiscussionError(`discussion "${discussionId}" is ${state.state}; only a deferred Discussion can be resumed`);
+			if (state.state !== "deferred")
+				throw new DiscussionError(`discussion "${discussionId}" is ${state.state}; only a deferred Discussion can be resumed`);
 			const { deferredReason: _deferredReason, ...rest } = state;
 			return this.artifacts.setExtra(discussionId, { ...discussion.extra, discussion: { ...rest, state: "active" } }, context)!;
 		});
@@ -167,10 +223,14 @@ export class Discussions {
 			const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
 			const state = this.extra(discussion);
 			if (state.state === "settled") throw new DiscussionError(`discussion "${discussionId}" is already settled`);
-			const updated = this.artifacts.setExtra(discussionId, {
-				...discussion.extra,
-				discussion: { ...state, state: "settled", settlement: validSettlement, settledAt: new Date().toISOString() },
-			}, context)!;
+			const updated = this.artifacts.setExtra(
+				discussionId,
+				{
+					...discussion.extra,
+					discussion: { ...state, state: "settled", settlement: validSettlement, settledAt: new Date().toISOString() },
+				},
+				context,
+			)!;
 			return this.artifacts.setStatus(discussionId, "done", context) ?? updated;
 		});
 	}
@@ -178,7 +238,8 @@ export class Discussions {
 	/** Links an existing active Discussion to a Task it blocks; refuses a non-task target or an already-settled Discussion. */
 	block(discussionId: string, taskId: string, context?: ArtifactEventContext): void {
 		const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
-		if (this.extra(discussion).state === "settled") throw new DiscussionError(`discussion "${discussionId}" is settled; it can no longer block anything`);
+		if (this.extra(discussion).state === "settled")
+			throw new DiscussionError(`discussion "${discussionId}" is settled; it can no longer block anything`);
 		const task = this.artifacts.get(taskId);
 		if (!task) throw new DiscussionError(`task "${taskId}" not found`);
 		if (task.kind !== "task" || isDiscussionArtifact(task)) throw new DiscussionError(`artifact "${taskId}" is not a task`);
@@ -211,7 +272,11 @@ export class Discussions {
 		const rows = this.artifacts.query({ kind: "task", subtype: DISCUSSION_SUBTYPE, limit });
 		if (!filter.state) return rows;
 		return rows.filter((row) => {
-			try { return this.extra(row).state === filter.state; } catch { return false; }
+			try {
+				return this.extra(row).state === filter.state;
+			} catch {
+				return false;
+			}
 		});
 	}
 }

package/src/domain/artifact-event.ts

@@ -1,6 +1,6 @@
 /**
  * Generic, kind-agnostic mutation event log — the "who did what, when" answer
- * shared by every artifact kind (doc, task, rule, skill), not reinvented per domain.
+ * shared by every artifact kind (doc, task, rule, playbook), not reinvented per domain.
  *
  * Modeled after scribe's parchment.Event/EventFilter/GetEvents shape, but avoids its
  * known gap: there, the Actor column is defined and filterable yet never populated by
@@ -10,8 +10,17 @@
  */
 import { ARTIFACT_EVENT_ACTOR_MAX_LENGTH, ARTIFACT_EVENT_HISTORY_DEFAULT_LIMIT, ARTIFACT_EVENT_HISTORY_MAX_LIMIT } from "../constants.ts";
 
-export const ARTIFACT_EVENT_TYPES = ["created", "updated", "status_changed", "extra_set", "linked", "unlinked", "trashed", "restored"] as const;
-export type ArtifactEventType = typeof ARTIFACT_EVENT_TYPES[number];
+export const ARTIFACT_EVENT_TYPES = [
+	"created",
+	"updated",
+	"status_changed",
+	"extra_set",
+	"linked",
+	"unlinked",
+	"trashed",
+	"restored",
+] as const;
+export type ArtifactEventType = (typeof ARTIFACT_EVENT_TYPES)[number];
 export type ArtifactEventDirection = "asc" | "desc";
 
 /** Caller-supplied identity for a mutation. All fields are advisory (self-reported), not cryptographically verified. */
@@ -73,7 +82,9 @@ function boundedString(value: string, field: string, maximum: number): string {
 }
 
 /** Fills defaults and enforces bounds. The one place every appended event is normalized. */
-export function resolveArtifactEvent(input: AppendArtifactEvent): Required<Pick<AppendArtifactEvent, "actor" | "source">> & AppendArtifactEvent {
+export function resolveArtifactEvent(
+	input: AppendArtifactEvent,
+): Required<Pick<AppendArtifactEvent, "actor" | "source">> & AppendArtifactEvent {
 	if (!input.artifactId) throw new Error("artifactId is required");
 	const actor = boundedString(input.actor ?? ARTIFACT_EVENT_DEFAULT_ACTOR, "actor", ARTIFACT_EVENT_ACTOR_MAX_LENGTH);
 	const source = boundedString(input.source ?? ARTIFACT_EVENT_DEFAULT_SOURCE, "source", ARTIFACT_EVENT_ACTOR_MAX_LENGTH);
@@ -81,7 +92,9 @@ export function resolveArtifactEvent(input: AppendArtifactEvent): Required<Pick<
 	return { ...input, actor, source };
 }
 
-export function normalizeArtifactEventQuery(query: ArtifactEventQuery): Required<Pick<ArtifactEventQuery, "limit" | "direction">> & ArtifactEventQuery {
+export function normalizeArtifactEventQuery(
+	query: ArtifactEventQuery,
+): Required<Pick<ArtifactEventQuery, "limit" | "direction">> & ArtifactEventQuery {
 	if (!query.artifactId && !query.actor && !query.sessionId) {
 		throw new Error("artifact event query requires artifactId, actor, or sessionId to stay bounded");
 	}

package/src/domain/artifact.ts

@@ -94,7 +94,9 @@ export function externalSourceOf(artifact: Pick<Artifact, "labels">): string | u
 export function requireLocallyOwnedContent(artifact: Artifact): Artifact {
 	const system = externalSourceOf(artifact);
 	if (system !== undefined) {
-		throw new Error(`"${artifact.title}" is a read-only projection from ${system}; edit it there, or capture a correction as a new linked Doc, until a write-back capability is integrated`);
+		throw new Error(
+			`"${artifact.title}" is a read-only projection from ${system}; edit it there, or capture a correction as a new linked Doc, until a write-back capability is integrated`,
+		);
 	}
 	return artifact;
 }

package/src/domain/blueprint-definition.ts

@@ -0,0 +1,268 @@
+import { SEED_RELATIONS, SKILL_MAX_BLUEPRINTS, SKILL_MAX_ENUM_VALUES, SKILL_MAX_INPUTS, SKILL_MAX_LINKS } from "../constants.ts";
+
+export type BlueprintArgumentValue = string | number | boolean;
+export type BlueprintInputType = "string" | "number" | "boolean";
+
+export interface BlueprintInputDefinition {
+	type: BlueprintInputType;
+	required?: boolean;
+	default?: BlueprintArgumentValue;
+	enum?: BlueprintArgumentValue[];
+}
+
+export interface DocBlueprint {
+	ref: string;
+	title: string;
+	body?: string;
+	subtype?: string;
+	labels?: string[];
+	extra?: Record<string, unknown>;
+}
+
+export interface RuleBlueprint {
+	ref: string;
+	title: string;
+	body?: string;
+	condition?: string;
+	action?: string;
+	severity?: "block" | "warn" | "info";
+	labels?: string[];
+	extra?: Record<string, unknown>;
+}
+
+export interface TaskBlueprint {
+	ref: string;
+	title: string;
+	body?: string;
+	dependsOn?: string[];
+	parent?: string;
+	labels?: string[];
+	extra?: Record<string, unknown>;
+}
+
+/**
+ * A pipeline step that nests another run inside this one -- the Jenkins "trigger downstream
+ * job and wait" / Ansible "include_tasks" primitive. The target named by `targetId` can be
+ * either a workflow-definition Playbook or an ordinary steps/trigger-shaped Playbook
+ * (workflow-execution.ts resolves which, by the target artifact's own subtype); existence and
+ * eligibility are both checked at execution time, 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 call ref (meaning: depend on every task the nested run
+ * creates), and a call's own `parent` contains the nested run's root tasks under an outer task.
+ */
+export interface CallBlueprint {
+	ref: string;
+	title: string;
+	targetId: string;
+	arguments?: Record<string, unknown>;
+	dependsOn?: string[];
+	parent?: string;
+}
+
+export interface Blueprints {
+	docs: DocBlueprint[];
+	rules: RuleBlueprint[];
+	tasks: TaskBlueprint[];
+	skills: CallBlueprint[];
+}
+
+export interface BlueprintLink {
+	from: string;
+	relation: string;
+	to: string;
+}
+
+export interface BlueprintDefinition {
+	version: 1;
+	inputs: Record<string, BlueprintInputDefinition>;
+	blueprints: Blueprints;
+	links: BlueprintLink[];
+}
+
+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;
+/** Exported so any other caller declaring typed inputs against this same shape (e.g. Playbook arguments) validates and rejects exactly the same way, instead of re-deriving its own type-checking logic. */
+export const BLUEPRINT_INPUT_TYPES = new Set<BlueprintInputType>(["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;
+}
+
+/** Exported for reuse by any other typed-argument declaration against this same value shape (e.g. Playbook arguments), rather than re-deriving this exact check elsewhere. */
+export function validateArgumentValue(name: string, type: BlueprintInputType, value: unknown): BlueprintArgumentValue {
+	if (typeof value !== type || (type === "number" && !Number.isFinite(value))) {
+		throw new Error(`argument "${name}" must be a ${type}`);
+	}
+	return value as BlueprintArgumentValue;
+}
+
+function validateInputs(value: unknown): Record<string, BlueprintInputDefinition> {
+	const source = record(value ?? {}, "inputs");
+	const entries = Object.entries(source);
+	if (entries.length > SKILL_MAX_INPUTS) throw new Error(`inputs exceed ${SKILL_MAX_INPUTS}`);
+	const result: Record<string, BlueprintInputDefinition> = {};
+	for (const [name, raw] of entries) {
+		if (RESERVED_KEYS.has(name)) throw new Error(`reserved input name "${name}"`);
+		if (!NAME_PATTERN.test(name)) throw new Error(`invalid input name "${name}"`);
+		const input = record(raw, `input "${name}"`);
+		if (!BLUEPRINT_INPUT_TYPES.has(input.type as BlueprintInputType)) throw new Error(`input "${name}" has unsupported type`);
+		const type = input.type as BlueprintInputType;
+		if (input.required !== undefined && typeof input.required !== "boolean") {
+			throw new Error(`input "${name}" required must be boolean`);
+		}
+		const normalized: BlueprintInputDefinition = { 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, `input "${name}" enum`);
+			if (values.length === 0 || values.length > SKILL_MAX_ENUM_VALUES)
+				throw new Error(`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(`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, `${kind} blueprint`);
+	const ref = string(source.ref, `${kind} blueprint ref`);
+	if (!NAME_PATTERN.test(ref)) throw new Error(`invalid blueprint ref "${ref}"`);
+	const title = string(source.title, `${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 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(`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 validateCallBlueprint(value: unknown): CallBlueprint {
+	const source = record(value, "call blueprint");
+	const ref = string(source.ref, "call blueprint ref");
+	if (!NAME_PATTERN.test(ref)) throw new Error(`invalid blueprint ref "${ref}"`);
+	const title = string(source.title, "call blueprint title");
+	const targetId = string(source.targetId ?? source.skillId, "call blueprint targetId");
+	return { ...source, ref, title, targetId } as CallBlueprint;
+}
+
+export function validateBlueprintDefinition(value: unknown): BlueprintDefinition {
+	const source = record(value, "blueprint definition");
+	if (source.version !== 1) throw new Error("blueprint definition version must be 1");
+	const inputs = validateInputs(source.inputs);
+	const rawBlueprints = record(source.blueprints, "blueprints");
+	const docs = array(rawBlueprints.docs ?? [], "doc blueprints").map((entry) => validateBlueprint<DocBlueprint>(entry, "doc"));
+	const rules = array(rawBlueprints.rules ?? [], "rule blueprints").map((entry) => validateBlueprint<RuleBlueprint>(entry, "rule"));
+	const tasks = array(rawBlueprints.tasks ?? [], "task blueprints").map((entry) => validateBlueprint<TaskBlueprint>(entry, "task"));
+	const calls = array(rawBlueprints.skills ?? [], "call blueprints").map(validateCallBlueprint);
+	const all = [...docs, ...rules, ...tasks, ...calls];
+	if (all.length === 0 || all.length > SKILL_MAX_BLUEPRINTS) throw new Error(`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 blueprint ref "${blueprint.ref}"`);
+		refs.add(blueprint.ref);
+	}
+	// Tasks and call pipeline steps share one dependency graph: a task may depend on a call ref
+	// (meaning: depend on every task that nested run creates), and vice versa.
+	const stepRefs = new Set<string>([...tasks.map((task) => task.ref), ...calls.map((call) => call.ref)]);
+	for (const task of tasks) {
+		if (task.dependsOn !== undefined && !Array.isArray(task.dependsOn)) throw new Error(`task "${task.ref}" dependsOn must be an array`);
+		for (const dependency of task.dependsOn ?? []) {
+			if (!stepRefs.has(dependency)) throw new Error(`unknown task dependency ref "${dependency}"`);
+		}
+		// parent stays task-only: containment under a 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 task parent ref "${task.parent}"`);
+		}
+	}
+	for (const call of calls) {
+		if (call.dependsOn !== undefined && !Array.isArray(call.dependsOn)) throw new Error(`call "${call.ref}" dependsOn must be an array`);
+		for (const dependency of call.dependsOn ?? []) {
+			if (!stepRefs.has(dependency)) throw new Error(`unknown call dependency ref "${dependency}"`);
+		}
+		if (call.parent !== undefined && !tasks.some((candidate) => candidate.ref === call.parent)) {
+			throw new Error(`unknown call parent ref "${call.parent}"`);
+		}
+	}
+	assertAcyclic([...tasks, ...calls]);
+	for (const name of placeholders(all)) {
+		if (!Object.hasOwn(inputs, name)) throw new Error(`unknown input placeholder "${name}"`);
+	}
+	const links = array(source.links ?? [], "links").map((entry) => {
+		const link = record(entry, "link");
+		const from = string(link.from, "link from");
+		const relation = string(link.relation, "link relation");
+		const to = string(link.to, "link to");
+		if (!refs.has(from)) throw new Error(`unknown blueprint ref "${from}"`);
+		if (!refs.has(to)) throw new Error(`unknown blueprint ref "${to}"`);
+		if (!RELATIONS.has(relation)) throw new Error(`unknown link relation "${relation}"`);
+		return { from, relation, to };
+	});
+	if (links.length > SKILL_MAX_LINKS) throw new Error(`links exceed ${SKILL_MAX_LINKS}`);
+	return { version: 1, inputs, blueprints: { docs, rules, tasks, skills: calls }, links };
+}
+
+export function resolveBlueprintArguments(definition: BlueprintDefinition, value: unknown): Record<string, BlueprintArgumentValue> {
+	const source = record(value ?? {}, "arguments");
+	for (const name of Object.keys(source)) {
+		if (!Object.hasOwn(definition.inputs, name)) throw new Error(`unknown argument "${name}"`);
+	}
+	const result: Record<string, BlueprintArgumentValue> = {};
+	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 argument "${name}"`);
+			continue;
+		}
+		const normalized = validateArgumentValue(name, input.type, raw);
+		if (input.enum && !input.enum.includes(normalized)) {
+			throw new Error(`argument "${name}" must be one of: ${input.enum.join(", ")}`);
+		}
+		result[name] = normalized;
+	}
+	return result;
+}

package/src/domain/checklist.ts

@@ -1,6 +1,6 @@
 export const PROOF_TYPES = ["file", "symbol", "code", "test", "command", "artifact", "url"] as const;
 
-export type ProofType = typeof PROOF_TYPES[number];
+export type ProofType = (typeof PROOF_TYPES)[number];
 
 export interface ProofReference {
 	type: ProofType;
@@ -25,13 +25,13 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 }
 
 function proofReference(value: unknown): ProofReference | undefined {
-	if (!isRecord(value) || !PROOF_TYPES.includes(value["type"] as ProofType)) return undefined;
-	if (typeof value["target"] !== "string" || value["target"].trim().length === 0) return undefined;
-	if (value["expect"] !== undefined && typeof value["expect"] !== "string") return undefined;
+	if (!isRecord(value) || !PROOF_TYPES.includes(value.type as ProofType)) return undefined;
+	if (typeof value.target !== "string" || value.target.trim().length === 0) return undefined;
+	if (value.expect !== undefined && typeof value.expect !== "string") return undefined;
 	return {
-		type: value["type"] as ProofType,
-		target: value["target"],
-		...(typeof value["expect"] === "string" ? { expect: value["expect"] } : {}),
+		type: value.type as ProofType,
+		target: value.target,
+		...(typeof value.expect === "string" ? { expect: value.expect } : {}),
 	};
 }
 
@@ -40,10 +40,10 @@ export function validateChecklist(value: unknown): Checklist {
 	const checklist: Checklist = {};
 	for (const [item, criterion] of Object.entries(value)) {
 		if (item.trim().length === 0) throw new Error("checklist item must not be empty");
-		if (!isRecord(criterion) || !Array.isArray(criterion["proof"]) || criterion["proof"].length === 0) {
+		if (!isRecord(criterion) || !Array.isArray(criterion.proof) || criterion.proof.length === 0) {
 			throw new Error(`checklist item "${item}" requires at least one proof reference`);
 		}
-		const proof = criterion["proof"].map(proofReference);
+		const proof = criterion.proof.map(proofReference);
 		if (proof.some((reference) => reference === undefined)) {
 			throw new Error(`checklist item "${item}" requires a typed, non-empty proof target`);
 		}
@@ -54,17 +54,20 @@ export function validateChecklist(value: unknown): Checklist {
 
 export function checklistEntries(value: unknown): ChecklistEntry[] {
 	if (Array.isArray(value)) {
-		return value.flatMap((item) => typeof item === "string"
-			? [{ item, proof: [], legacy: true }]
-			: isRecord(item) && typeof item["title"] === "string"
-				? [{ item: item["title"], proof: [], legacy: true }]
-				: []);
+		return value.flatMap((item) =>
+			typeof item === "string"
+				? [{ item, proof: [], legacy: true }]
+				: isRecord(item) && typeof item.title === "string"
+					? [{ item: item.title, proof: [], legacy: true }]
+					: [],
+		);
 	}
 	if (!isRecord(value)) return [];
 	return Object.entries(value).map(([item, criterion]) => {
-		const references = isRecord(criterion) && Array.isArray(criterion["proof"])
-			? criterion["proof"].map(proofReference).filter((proof): proof is ProofReference => proof !== undefined)
-			: [];
+		const references =
+			isRecord(criterion) && Array.isArray(criterion.proof)
+				? criterion.proof.map(proofReference).filter((proof): proof is ProofReference => proof !== undefined)
+				: [];
 		return { item, proof: references, legacy: false };
 	});
 }