@danypops/papyrus 0.11.4 → 0.13.0

package/src/domain/artifact-event.ts

@@ -0,0 +1,99 @@
+/**
+ * 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.
+ *
+ * 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
+ * any caller. Here, actor/source default to explicit sentinels ("system"/"unknown")
+ * rather than being silently blank, and the event is appended by the same choke point
+ * that performs the mutation (src/ops.ts), so no domain call site can skip it.
+ */
+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"] 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. */
+export interface ArtifactEventContext {
+	actor?: string;
+	source?: string;
+	sessionId?: string;
+}
+
+export interface ArtifactEvent {
+	id: number;
+	artifactId: string;
+	occurredAt: string;
+	type: ArtifactEventType;
+	actor: string;
+	source: string;
+	sessionId?: string;
+	fromStatus?: string;
+	toStatus?: string;
+	relation?: string;
+	relatedId?: string;
+	schemaVersion: 1;
+}
+
+export interface AppendArtifactEvent {
+	artifactId: string;
+	type: ArtifactEventType;
+	actor?: string;
+	source?: string;
+	sessionId?: string;
+	fromStatus?: string;
+	toStatus?: string;
+	relation?: string;
+	relatedId?: string;
+}
+
+export interface ArtifactEventQuery {
+	artifactId?: string;
+	actor?: string;
+	sessionId?: string;
+	since?: string;
+	limit?: number;
+	cursor?: number;
+	direction?: ArtifactEventDirection;
+}
+
+export interface ArtifactEventPage {
+	events: ArtifactEvent[];
+	nextCursor?: number;
+}
+
+/** No caller-supplied identity defaults to these explicit sentinels — never a silent blank. */
+export const ARTIFACT_EVENT_DEFAULT_ACTOR = "system";
+export const ARTIFACT_EVENT_DEFAULT_SOURCE = "unknown";
+
+function boundedString(value: string, field: string, maximum: number): string {
+	if (value.length === 0 || value.length > maximum) throw new Error(`${field} must be between 1 and ${maximum} characters`);
+	return value;
+}
+
+/** Fills defaults and enforces bounds. The one place every appended event is normalized. */
+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);
+	if (input.sessionId !== undefined) boundedString(input.sessionId, "sessionId", ARTIFACT_EVENT_ACTOR_MAX_LENGTH);
+	return { ...input, actor, source };
+}
+
+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");
+	}
+	const limit = query.limit ?? ARTIFACT_EVENT_HISTORY_DEFAULT_LIMIT;
+	if (!Number.isInteger(limit) || limit < 1 || limit > ARTIFACT_EVENT_HISTORY_MAX_LIMIT) {
+		throw new Error(`artifact event limit must be between 1 and ${ARTIFACT_EVENT_HISTORY_MAX_LIMIT}`);
+	}
+	if (query.cursor !== undefined && (!Number.isInteger(query.cursor) || query.cursor < 1)) {
+		throw new Error("artifact event cursor must be a positive integer");
+	}
+	if (query.direction !== undefined && query.direction !== "asc" && query.direction !== "desc") {
+		throw new Error("artifact event direction must be asc or desc");
+	}
+	return { ...query, limit, direction: query.direction ?? "desc" };
+}

package/src/domain/conversation-journal.ts

@@ -0,0 +1,168 @@
+/**
+ * domain/conversation-journal.ts — host-neutral ConversationJournal domain.
+ *
+ * See decision-discourse-as-a-layer-above-sessions-separate-conver-p832 and
+ * pis-tree-implementation-concrete-lessons-for-the-discourse-s-wnrs (Papyrus docs) for the
+ * design this implements and the concrete lessons behind each choice below.
+ *
+ * A Thread is the conversation's own stable identity, independent of whichever host
+ * process/session recorded any given Post into it. This module and its package source
+ * must never mention host runtime names (no "Pi") -- sourceSessionId is a generic
+ * provenance field on a Post, not a host-specific concept, and the host decides what
+ * value to put there.
+ */
+
+export const CONVERSATION_JOURNAL_CONTENT_MAX_CHARACTERS = 20_000;
+export const CONVERSATION_JOURNAL_SOURCE_ID_MAX_LENGTH = 256;
+export const CONVERSATION_JOURNAL_MAX_REFERENCES_PER_POST = 50;
+/** Bounds a single readThread call; retention/eviction beyond this is a host/persistence concern, not this domain's. */
+export const CONVERSATION_JOURNAL_READ_MAX_POSTS = 500;
+/** Bounds reply-chain traversal so a cycle (accidental or adversarial) cannot infinite-loop a tree build -- see the Pi /tree lessons doc for why this must not be assumed away. */
+export const CONVERSATION_JOURNAL_MAX_TRAVERSAL_DEPTH = 10_000;
+
+export type JournalAuthor = "human" | "agent";
+
+/** A reference to an artifact owned outside this journal -- verified by the host, never asserted. */
+export interface ArtifactReference {
+	readonly kind: string;
+	readonly id: string;
+}
+
+export interface JournalThread {
+	readonly id: string;
+	readonly createdAt: string;
+}
+
+export interface JournalPost {
+	readonly id: string;
+	readonly threadId: string;
+	/** Absent only for a thread's first post. */
+	readonly replyToPostId?: string;
+	readonly authorId: JournalAuthor;
+	readonly content: string;
+	/** True when content was cut to CONVERSATION_JOURNAL_CONTENT_MAX_CHARACTERS -- never silently. */
+	readonly truncated: boolean;
+	readonly timestamp: string;
+	/** Which host session/process recorded this post. Provenance, never this domain's top-level container -- see the layering decision doc. */
+	readonly sourceSessionId: string;
+	/**
+	 * Idempotency key. Must be a composite of (sourceSessionId, a host-local entry id),
+	 * constructed by the caller -- never a bare host entry id alone. A host's own entry
+	 * ids are commonly unique only within one recording session, not globally; using one
+	 * alone as a global idempotency key risks a false dedup collision between two
+	 * unrelated sessions. See the Pi /tree lessons doc for the concrete case this
+	 * generalizes from.
+	 */
+	readonly operationId: string;
+	readonly references: readonly ArtifactReference[];
+}
+
+export interface AppendPostCommand {
+	readonly threadId: string;
+	readonly replyToPostId?: string;
+	readonly authorId: JournalAuthor;
+	readonly content: string;
+	readonly sourceSessionId: string;
+	readonly operationId: string;
+	readonly references?: readonly ArtifactReference[];
+}
+
+export interface AppendPostResult {
+	readonly post: JournalPost;
+	/** True when this exact operationId was already journaled and this call was a safe no-op replay. */
+	readonly replayed: boolean;
+}
+
+export interface ReadThreadQuery {
+	readonly threadId: string;
+	readonly limit: number;
+}
+
+export interface ThreadPage {
+	readonly posts: readonly JournalPost[];
+	/** True when more posts exist beyond `limit` -- never silently drop the tail without saying so. */
+	readonly truncated: boolean;
+}
+
+/** One node of a reconstructed reply tree; see buildThreadTree. */
+export interface ThreadTreeNode {
+	readonly post: JournalPost;
+	readonly children: ThreadTreeNode[];
+}
+
+function requireBounded(value: string, label: string, maxLength: number): string {
+	if (value.length === 0) throw new Error(`${label} is required`);
+	if (value.length > maxLength) throw new Error(`${label} exceeds ${maxLength} characters`);
+	return value;
+}
+
+export function validateAppendPostCommand(command: AppendPostCommand): void {
+	requireBounded(command.threadId, "threadId", CONVERSATION_JOURNAL_SOURCE_ID_MAX_LENGTH);
+	requireBounded(command.sourceSessionId, "sourceSessionId", CONVERSATION_JOURNAL_SOURCE_ID_MAX_LENGTH);
+	requireBounded(command.operationId, "operationId", CONVERSATION_JOURNAL_SOURCE_ID_MAX_LENGTH * 2);
+	if (command.content.length === 0) throw new Error("content is required");
+	if (command.authorId !== "human" && command.authorId !== "agent") throw new Error('authorId must be "human" or "agent"');
+	const references = command.references ?? [];
+	if (references.length > CONVERSATION_JOURNAL_MAX_REFERENCES_PER_POST) {
+		throw new Error(`a post is bounded to ${CONVERSATION_JOURNAL_MAX_REFERENCES_PER_POST} references; got ${references.length}`);
+	}
+}
+
+/** Applies the explicit truncation bound. Never silently drops the truncation fact -- callers must surface `truncated`. */
+export function boundContent(content: string): { content: string; truncated: boolean } {
+	if (content.length <= CONVERSATION_JOURNAL_CONTENT_MAX_CHARACTERS) return { content, truncated: false };
+	return { content: content.slice(0, CONVERSATION_JOURNAL_CONTENT_MAX_CHARACTERS), truncated: true };
+}
+
+/**
+ * Reconstructs the reply tree from a flat list of posts (as returned by one bounded
+ * readThread call). A post whose replyToPostId does not resolve within this same list --
+ * because it is genuinely a thread root, or because an ancestor aged out under a
+ * retention policy -- degrades to being treated as a root of its own sub-tree, exactly
+ * like Pi's own getTree() treats an orphaned entry. This never throws on that account.
+ *
+ * Bounded and cycle-safe: a post already visited while walking up cannot be revisited,
+ * so a malformed or adversarial replyToPostId cycle cannot infinite-loop this function --
+ * see the Pi /tree lessons doc for why that guard must be explicit, not assumed.
+ */
+export function buildThreadTree(posts: readonly JournalPost[]): ThreadTreeNode[] {
+	const nodesById = new Map<string, ThreadTreeNode>();
+	for (const post of posts) nodesById.set(post.id, { post, children: [] });
+
+	const roots: ThreadTreeNode[] = [];
+	for (const post of posts) {
+		const node = nodesById.get(post.id)!;
+		const parent = post.replyToPostId ? nodesById.get(post.replyToPostId) : undefined;
+		if (parent) parent.children.push(node);
+		else roots.push(node);
+	}
+
+	for (const node of nodesById.values()) {
+		node.children.sort((left, right) => left.post.timestamp.localeCompare(right.post.timestamp) || left.post.id.localeCompare(right.post.id));
+	}
+	roots.sort((left, right) => left.post.timestamp.localeCompare(right.post.timestamp) || left.post.id.localeCompare(right.post.id));
+	return roots;
+}
+
+/**
+ * Walks from a post back toward its thread root via replyToPostId, root-first order --
+ * the host-neutral equivalent of Pi's getBranch(). Bounded by
+ * CONVERSATION_JOURNAL_MAX_TRAVERSAL_DEPTH and tracks visited ids explicitly so a cycle
+ * cannot infinite-loop this walk, unlike Pi's own getBranch() (a documented gap in Pi,
+ * not something to assume away here).
+ */
+export function ancestorChain(postId: string, postsById: ReadonlyMap<string, JournalPost>): JournalPost[] {
+	const chain: JournalPost[] = [];
+	const visited = new Set<string>();
+	let currentId: string | undefined = postId;
+	while (currentId !== undefined) {
+		if (visited.has(currentId)) break; // cycle guard
+		if (chain.length >= CONVERSATION_JOURNAL_MAX_TRAVERSAL_DEPTH) break; // depth guard
+		visited.add(currentId);
+		const post = postsById.get(currentId);
+		if (!post) break; // orphan: stop here, do not error
+		chain.push(post);
+		currentId = post.replyToPostId;
+	}
+	return chain.reverse();
+}

package/src/domain/discourse-store.ts

@@ -0,0 +1,142 @@
+import {
+	DISCOURSE_CONTENT_MAX_BYTES,
+	DISCOURSE_EVENT_RETENTION_DEFAULT,
+	DISCOURSE_EVENT_RETENTION_MAX,
+	DISCOURSE_QUERY_MAX_LIMIT,
+} from "../constants.ts";
+
+/** Papyrus-owned Doc subtypes reserved for the Discourse persistence adapter. */
+export const DISCOURSE_THREAD_SUBTYPE = "context-thread";
+export const DISCOURSE_MESSAGE_SUBTYPE = "context-message";
+export const DISCOURSE_RELATIONS = new Set(["reply_to", "discusses"]);
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+export interface ArtifactReference { kind: string; id: string }
+export interface ThreadAddress { forumId: string; topicId: string; threadId: string }
+export interface AppendPostCommand extends ThreadAddress {
+	schemaVersion: "discourse.command.v1";
+	operationId: string;
+	authorId: string;
+	content: JsonValue;
+	correlationId?: string;
+	causationId?: string;
+	replyToPostId?: string;
+	references?: ArtifactReference[];
+}
+export interface Post extends ThreadAddress {
+	id: string;
+	authorId: string;
+	content: JsonValue;
+	timestamp: number;
+	sequence: number;
+	operationId: string;
+	correlationId?: string;
+	causationId?: string;
+	replyToPostId?: string;
+	references: ArtifactReference[];
+}
+export type DiscourseEventType = "post-added" | "thread-changed" | "question-opened" | "question-answered" | "subscription-resync-required";
+export interface DiscourseEvent extends ThreadAddress {
+	schemaVersion: "discourse.event.v1";
+	type: DiscourseEventType;
+	sequence: number;
+	timestamp: number;
+	postId?: string;
+	operationId?: string;
+	correlationId?: string;
+	causationId?: string;
+	responseId?: string;
+	retainedFromSequence?: number;
+}
+export interface Page<T> {
+	items: T[];
+	truncated: boolean;
+	nextSequence?: number;
+	completeness: "complete" | "truncated";
+}
+export interface TopicSummary { forumId: string; topicId: string; threadCount: number; postCount: number; lastActivity: number }
+export interface ThreadSummary extends ThreadAddress { postCount: number; participantIds: string[]; lastActivity: number }
+export interface OpenQuestion { responseId: string; post: Post }
+export interface ProjectionRecord { sequence: number; post: Post }
+
+export function isDiscourseSubtype(subtype: string | undefined): boolean {
+	return subtype === DISCOURSE_THREAD_SUBTYPE || subtype === DISCOURSE_MESSAGE_SUBTYPE;
+}
+
+function record(value: unknown, name: string): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${name} must be an object`);
+	return value as Record<string, unknown>;
+}
+
+export function requiredString(value: unknown, name: string): string {
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${name} is required`);
+	return value;
+}
+
+export function optionalString(value: unknown, name: string): string | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${name} must be a non-empty string`);
+	return value;
+}
+
+export function nonNegativeInteger(value: unknown, name: string): number {
+	if (!Number.isSafeInteger(value) || (value as number) < 0) throw new Error(`${name} must be a non-negative safe integer`);
+	return value as number;
+}
+
+export function queryLimit(value: unknown): number {
+	const limit = nonNegativeInteger(value, "limit");
+	if (limit < 1 || limit > DISCOURSE_QUERY_MAX_LIMIT) throw new Error(`limit must be between 1 and ${DISCOURSE_QUERY_MAX_LIMIT}`);
+	return limit;
+}
+
+export function eventRetention(value: unknown): number {
+	if (value === undefined) return DISCOURSE_EVENT_RETENTION_DEFAULT;
+	const retention = nonNegativeInteger(value, "event_retention");
+	if (retention < 1 || retention > DISCOURSE_EVENT_RETENTION_MAX) {
+		throw new Error(`event_retention must be between 1 and ${DISCOURSE_EVENT_RETENTION_MAX}`);
+	}
+	return retention;
+}
+
+function jsonValue(value: unknown, name: string): JsonValue {
+	const encoded = JSON.stringify(value);
+	if (encoded === undefined) throw new Error(`${name} must be JSON-serializable`);
+	if (new TextEncoder().encode(encoded).byteLength > DISCOURSE_CONTENT_MAX_BYTES) {
+		throw new Error(`${name} cannot exceed ${DISCOURSE_CONTENT_MAX_BYTES} bytes`);
+	}
+	return JSON.parse(encoded) as JsonValue;
+}
+
+export function appendCommand(value: unknown): AppendPostCommand {
+	const input = record(value, "command");
+	if (input["schemaVersion"] !== "discourse.command.v1") throw new Error("unsupported Discourse command schema");
+	const referencesValue = input["references"] ?? [];
+	if (!Array.isArray(referencesValue)) throw new Error("references must be an array");
+	const references = referencesValue.map((entry, index) => {
+		const reference = record(entry, `references[${index}]`);
+		return { kind: requiredString(reference["kind"], `references[${index}].kind`), id: requiredString(reference["id"], `references[${index}].id`) };
+	});
+	return {
+		schemaVersion: "discourse.command.v1",
+		operationId: requiredString(input["operationId"], "operationId"),
+		forumId: requiredString(input["forumId"], "forumId"),
+		topicId: requiredString(input["topicId"], "topicId"),
+		threadId: requiredString(input["threadId"], "threadId"),
+		authorId: requiredString(input["authorId"], "authorId"),
+		content: jsonValue(input["content"], "content"),
+		...(optionalString(input["correlationId"], "correlationId") ? { correlationId: input["correlationId"] as string } : {}),
+		...(optionalString(input["causationId"], "causationId") ? { causationId: input["causationId"] as string } : {}),
+		...(optionalString(input["replyToPostId"], "replyToPostId") ? { replyToPostId: input["replyToPostId"] as string } : {}),
+		references,
+	};
+}
+
+export function threadAddress(value: Record<string, unknown>): ThreadAddress {
+	return {
+		forumId: requiredString(value["forumId"], "forumId"),
+		topicId: requiredString(value["topicId"], "topicId"),
+		threadId: requiredString(value["threadId"], "threadId"),
+	};
+}

package/src/domain/graph-projection.ts

@@ -0,0 +1,74 @@
+/**
+ * domain/graph-projection.ts — the generic graph projection protocol for external bounded
+ * contexts (step 6 of the incremental refactor in
+ * reducing-papyrus-consumer-change-amplification-with-modules--pvdo), sketched in
+ * papyrus-full-context-mesh-and-domain-storage-ownership-bound-qhzp.
+ *
+ * An external bounded context owns its own operational state and command authority. It
+ * never becomes a Papyrus-native module just to appear in the graph. Instead it publishes
+ * bounded, sequenced batches of the context-bearing identities and edges it wants durably
+ * materialized in the Context Mesh. Papyrus is an idempotent materialized read model for
+ * that producer's data, not its command database.
+ *
+ * Deliberately out of scope for this walking skeleton, each a separate follow-up:
+ * - Producer identity is a request field (`producerId`), not yet derived from scoped
+ *   authentication -- the decision doc's constraint that "producer identity comes from
+ *   scoped authentication, not request payloads" is not yet met, since Papyrus's daemon
+ *   auth model today is one shared bearer token, not per-caller identity. Tracked as a
+ *   known gap, not silently assumed solved.
+ * - Edges reference other artifacts only via an externalId already projected by the SAME
+ *   producer in this batch or a prior one. Linking a projected artifact to an existing
+ *   Papyrus-native artifact (e.g. "this Discourse thread discusses this Task") is not yet
+ *   supported here -- a real, needed capability, but a second batch shape / edge kind, not
+ *   assumed away.
+ * - "Lag" is reported as Papyrus's own last-applied checkpoint; Papyrus has no way to know
+ *   a producer's true current sequence, so relative lag must be computed by the caller
+ *   (who does know its own latest sequence) by diffing against this checkpoint.
+ */
+
+export const GRAPH_PROJECTION_SCHEMA_VERSION = "papyrus.graph-projection/v1";
+
+export interface ProjectedArtifact {
+	/** The producer's own stable identity for this entity -- never a Papyrus artifact id. */
+	readonly externalId: string;
+	readonly kind: string;
+	readonly subtype?: string;
+	readonly title: string;
+	readonly body?: string;
+	readonly labels?: readonly string[];
+	readonly extra?: Record<string, unknown>;
+}
+
+export interface ProjectedEdge {
+	readonly from: string; // externalId, resolved against this producer's identity map
+	readonly relation: string;
+	readonly to: string; // externalId, resolved against this producer's identity map
+}
+
+export interface GraphProjectionBatch {
+	readonly schemaVersion: typeof GRAPH_PROJECTION_SCHEMA_VERSION;
+	readonly producerId: string;
+	readonly batchId: string;
+	/** Monotonic per-producer sequence, starting at 1. Enforced gapless -- see GraphProjection.apply. */
+	readonly sequence: number;
+	readonly artifacts: readonly ProjectedArtifact[];
+	readonly edges: readonly ProjectedEdge[];
+}
+
+export interface ProjectionCheckpoint {
+	readonly producerId: string;
+	readonly lastSequence: number;
+	readonly lastBatchId: string;
+	readonly appliedAt: string;
+}
+
+export interface GraphProjectionResult {
+	readonly producerId: string;
+	readonly batchId: string;
+	readonly sequence: number;
+	readonly artifactsUpserted: number;
+	readonly artifactsCreated: number;
+	readonly edgesUpserted: number;
+	/** True only when this exact batch was already applied and this call was a safe no-op replay. */
+	readonly alreadyApplied: boolean;
+}

package/src/domain/skill-definition.ts

@@ -46,10 +46,29 @@ export interface SkillTaskBlueprint {
 	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 (skill-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 {
@@ -142,19 +161,34 @@ function placeholders(value: unknown, result: Set<string> = new Set()): Set<stri
 	return result;
 }
 
-function assertAcyclic(tasks: SkillTaskBlueprint[]): void {
-	const byRef = new Map(tasks.map((task) => [task.ref, task]));
+/** 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 task dependency cycle includes "${ref}"`);
+		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 task of tasks) visit(task.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 {
@@ -165,23 +199,38 @@ export function validateSkillDefinition(value: unknown): SkillDefinition {
 	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 all = [...docs, ...rules, ...tasks];
+	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 (!tasks.some((candidate) => candidate.ref === dependency)) throw new Error(`unknown skill task dependency ref "${dependency}"`);
+			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}"`);
 		}
 	}
-	assertAcyclic(tasks);
+	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}"`);
 	}
@@ -196,7 +245,7 @@ export function validateSkillDefinition(value: unknown): SkillDefinition {
 		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 }, links };
+	return { version: 1, inputs, blueprints: { docs, rules, tasks, skills: skillCalls }, links };
 }
 
 export function resolveSkillArguments(definition: SkillDefinition, value: unknown): Record<string, SkillArgumentValue> {

package/src/domain/task-event.ts

@@ -24,6 +24,10 @@ export const TASK_EVENT_TYPES = [
 	"retried",
 	"completed",
 	"canceled",
+	"dependency_added",
+	"dependency_removed",
+	"containment_added",
+	"containment_removed",
 ] as const;
 
 export type TaskEventType = typeof TASK_EVENT_TYPES[number];