@danypops/papyrus 0.45.3 → 0.46.0

package/src/{domain-services.ts → playbook/playbook-service.ts}

@@ -1,453 +1,10 @@
-import { type Artifact, requireLocallyOwnedContent } from "./artifact/artifact.ts";
-import type { ArtifactEventContext } from "./artifact/artifact-event.ts";
-import type { ArtifactScopeStore } from "./artifact/artifact-scope-store.ts";
-import type { ArtifactStore } from "./artifact/artifact-store.ts";
-import type { ArtifactAction, AuthorityRegistry } from "./authority-registry.ts";
-import {
-	ARTIFACT_BODY_MAX_LENGTH,
-	ARTIFACT_LABEL_MAX_COUNT,
-	ARTIFACT_LABEL_MAX_LENGTH,
-	ARTIFACT_SCOPE_MAX_ARTIFACTS,
-	ARTIFACT_TITLE_MAX_LENGTH,
-	PLAYBOOK_ARGUMENT_DESCRIPTION_MAX_LENGTH,
-	PLAYBOOK_ARGUMENT_MAX_COUNT,
-	PLAYBOOK_ARGUMENT_NAME_MAX_LENGTH,
-	PLAYBOOK_INVOCATION_MAX_CALL_DEPTH,
-	PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS,
-	PLAYBOOK_MAX_STEPS,
-	RULE_TEXT_HARD_LIMIT_CHARACTERS,
-	RULE_TEXT_SOFT_TARGET_CHARACTERS,
-	SKILL_MAX_ENUM_VALUES,
-} from "./constants.ts";
-import {
-	BLUEPRINT_INPUT_TYPES,
-	type BlueprintArgumentValue,
-	type BlueprintInputType,
-	validateArgumentValue,
-} from "./domain/blueprint-definition.ts";
-import { normalizeProjectRoot } from "./domain/task-scope.ts";
-import { NOTE_SUBTYPE } from "./note/note-service.ts";
-
-export interface UpdateContentInput {
-	title?: string;
-	body?: string;
-	labels?: string[];
-}
-
-function requireContentUpdateFields(input: UpdateContentInput): void {
-	if (input.title === undefined && input.body === undefined && input.labels === undefined) {
-		throw new Error("update requires title, body, or labels");
-	}
-}
-
-function assertTitleBounds(title: string | undefined): void {
-	if (title !== undefined && (title.trim().length === 0 || title.length > ARTIFACT_TITLE_MAX_LENGTH)) {
-		throw new Error(`title must be between 1 and ${ARTIFACT_TITLE_MAX_LENGTH} characters`);
-	}
-}
-
-function assertBodyBounds(body: string | undefined): void {
-	if (body !== undefined && body.length > ARTIFACT_BODY_MAX_LENGTH)
-		throw new Error(`body cannot exceed ${ARTIFACT_BODY_MAX_LENGTH} characters`);
-}
-
-function assertLabelsBounds(labels: string[] | undefined): void {
-	if (labels === undefined) return;
-	if (labels.length > ARTIFACT_LABEL_MAX_COUNT) throw new Error(`labels cannot exceed ${ARTIFACT_LABEL_MAX_COUNT} entries`);
-	if (labels.some((label) => label.length === 0 || label.length > ARTIFACT_LABEL_MAX_LENGTH)) {
-		throw new Error(`each label must be between 1 and ${ARTIFACT_LABEL_MAX_LENGTH} characters`);
-	}
-}
-
-export interface ListFilter {
-	status?: string;
-	text?: string;
-	limit?: number;
-	/** When supplied, results are limited to artifacts scoped to this project (or the unscoped bucket, for an empty string is not accepted -- use assignArtifactProject's own validation). */
-	projectRoot?: string;
-}
-
-/**
- * Shared by listDocuments/listRules/listPlaybooks: when filter.projectRoot is given, resolve
- * via ArtifactScopeStore first and post-filter by kind/status/text (mirrors Tasks.list's
- * established scoped-listing shape); otherwise fall back to the existing unscoped query
- * path unchanged, so every caller that predates project scoping keeps working exactly as
- * before.
- */
-function listScoped(
-	artifacts: ArtifactStore,
-	scopes: ArtifactScopeStore,
-	kind: string,
-	filter: ListFilter,
-	excludeSubtype?: string,
-): Artifact[] {
-	if (filter.projectRoot === undefined)
-		return artifacts.query({ kind, excludeSubtype, status: filter.status, text: filter.text, limit: filter.limit });
-	const limit = filter.limit ?? ARTIFACT_SCOPE_MAX_ARTIFACTS;
-	if (!Number.isInteger(limit) || limit < 1 || limit > ARTIFACT_SCOPE_MAX_ARTIFACTS) {
-		throw new Error(`list limit must be between 1 and ${ARTIFACT_SCOPE_MAX_ARTIFACTS}`);
-	}
-	const projectRoot = normalizeProjectRoot(filter.projectRoot);
-	const ids = scopes.ids(projectRoot, ARTIFACT_SCOPE_MAX_ARTIFACTS);
-	const text = filter.text?.toLowerCase();
-	return ids
-		.map((id) => artifacts.get(id))
-		.filter((artifact): artifact is Artifact => artifact?.kind === kind && artifact.subtype !== excludeSubtype)
-		.filter((artifact) => filter.status === undefined || artifact.status === filter.status)
-		.filter((artifact) => text === undefined || artifact.title.toLowerCase().includes(text) || artifact.body.toLowerCase().includes(text))
-		.sort((left, right) => right.updated_at.localeCompare(left.updated_at) || left.id.localeCompare(right.id))
-		.slice(0, limit);
-}
-
-/** Shared by assignDocumentProject/assignRuleProject/assignPlaybookProject. */
-function assignArtifactProject(
-	artifacts: ArtifactStore,
-	scopes: ArtifactScopeStore,
-	id: string,
-	kind: string,
-	projectRoot: string | undefined,
-): Artifact {
-	requireKind(artifacts, id, kind);
-	scopes.assign(
-		id,
-		projectRoot === undefined ? undefined : normalizeProjectRoot(projectRoot),
-		projectRoot === undefined ? "unscoped" : "explicit",
-	);
-	return artifacts.get(id)!;
-}
-
-function requireKind(artifacts: ArtifactStore, id: string, kind: string): Artifact {
-	const artifact = artifacts.get(id);
-	if (!artifact) throw new Error(`${kind} artifact "${id}" not found`);
-	if (artifact.kind !== kind) throw new Error(`artifact "${id}" is not a ${kind}`);
-	return artifact;
-}
-
-function rejectsNoteTemplate(artifacts: ArtifactStore, templateId: string | undefined, subtype: string | undefined): boolean {
-	if (subtype === NOTE_SUBTYPE) return true;
-	if (!templateId) return false;
-	const template = artifacts.get(templateId);
-	const defaults = template?.extra.defaults;
-	return (
-		typeof defaults === "object" &&
-		defaults !== null &&
-		!Array.isArray(defaults) &&
-		(defaults as Record<string, unknown>).subtype === NOTE_SUBTYPE
-	);
-}
-
-/** caller never owns NOTE_SUBTYPE, so requireArtifactAllowed always throws — the trailing throw only satisfies TypeScript's control-flow analysis for a `never`-returning function. */
-function requireNotesFacade(authority: AuthorityRegistry, caller: string): never {
-	authority.requireArtifactAllowed("doc", NOTE_SUBTYPE, "create", caller);
-	throw new Error("note creation requires notes.capture");
-}
-
-function templateSubtype(artifacts: ArtifactStore, templateId: string | undefined): string | undefined {
-	if (!templateId) return undefined;
-	const defaults = artifacts.get(templateId)?.extra.defaults;
-	if (typeof defaults !== "object" || defaults === null || Array.isArray(defaults)) return undefined;
-	const subtype = (defaults as Record<string, unknown>).subtype;
-	return typeof subtype === "string" ? subtype : undefined;
-}
-
-// No default action: linkDocument's own bug (both target and source checks silently defaulting to
-// "status" here) was exactly what let a plain reference edge to a Task trip the tasks.* lifecycle
-// guard, which is scoped to actual status changes only. Every call site now names its real action.
-function requireMutableDocument(document: Artifact, authority: AuthorityRegistry, action: ArtifactAction): Artifact {
-	authority.requireArtifactAllowed(document.kind, document.subtype, action, "docs");
-	return document;
-}
-
-export interface CreateDocumentInput {
-	title: string;
-	body?: string;
-	subtype?: string;
-	labels?: string[];
-	extra?: Record<string, unknown>;
-	templateId?: string;
-	/** Optional at creation, unlike Tasks -- omitting it leaves the Doc in the unscoped bucket, matching today's default behavior for every existing caller. */
-	projectRoot?: string;
-}
-
-export type UpdateDocumentInput = UpdateContentInput;
-
-export type DocumentTransition = "activate" | "archive" | "reopen";
-export type DocumentRelation = "references" | "documents" | "supersedes" | "relates_to" | "contains" | "part_of";
-
-const DOCUMENT_TRANSITIONS: Record<DocumentTransition, { from: string[]; to: string }> = {
-	activate: { from: ["draft"], to: "active" },
-	archive: { from: ["draft", "active"], to: "archived" },
-	reopen: { from: ["archived"], to: "draft" },
-};
-
-export function createDocument(
-	artifacts: ArtifactStore,
-	scopes: ArtifactScopeStore,
-	input: CreateDocumentInput,
-	authority: AuthorityRegistry,
-	context?: ArtifactEventContext,
-): Artifact {
-	if (rejectsNoteTemplate(artifacts, input.templateId, input.subtype)) requireNotesFacade(authority, "docs");
-	authority.requireArtifactAllowed("doc", input.subtype ?? templateSubtype(artifacts, input.templateId), "create", "docs");
-	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
-	const document = artifacts.create(
-		{
-			kind: "doc",
-			// Explicit, not defaultStatusFor's "first status row by rowid" fallback -- the same
-			// heuristic that made Task creation non-deterministic on a migrated database. Every
-			// creation path that has no caller-supplied initial status must set one explicitly.
-			status: "draft",
-			title: input.title,
-			body: input.body,
-			subtype: input.subtype,
-			labels: input.labels,
-			extra: input.extra,
-			templateId: input.templateId,
-		},
-		context,
-	);
-	scopes.assign(document.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
-	return document;
-}
-
-export function listDocuments(artifacts: ArtifactStore, scopes: ArtifactScopeStore, filter: ListFilter): Artifact[] {
-	return listScoped(artifacts, scopes, "doc", filter, NOTE_SUBTYPE);
-}
-
-export function assignDocumentProject(
-	artifacts: ArtifactStore,
-	scopes: ArtifactScopeStore,
-	id: string,
-	projectRoot: string | undefined,
-): Artifact {
-	requireDocument(artifacts, id); // rejects Notes -- project reassignment for notes goes through notes.* like everything else about them
-	scopes.assign(
-		id,
-		projectRoot === undefined ? undefined : normalizeProjectRoot(projectRoot),
-		projectRoot === undefined ? "unscoped" : "explicit",
-	);
-	return artifacts.get(id)!;
-}
-
-function requireDocument(artifacts: ArtifactStore, id: string): Artifact {
-	const document = requireKind(artifacts, id, "doc");
-	if (document.subtype === NOTE_SUBTYPE) throw new Error("note access requires a notes.* operation");
-	return document;
-}
-
-export function showDocument(artifacts: ArtifactStore, id: string): Artifact {
-	requireDocument(artifacts, id);
-	return artifacts.get(id, { tree: true })!;
-}
-
-export function transitionDocument(
-	artifacts: ArtifactStore,
-	id: string,
-	action: DocumentTransition,
-	authority: AuthorityRegistry,
-	context?: ArtifactEventContext,
-): Artifact {
-	const document = requireLocallyOwnedContent(requireMutableDocument(requireDocument(artifacts, id), authority, "status"));
-	const transition = DOCUMENT_TRANSITIONS[action];
-	if (!transition.from.includes(document.status)) throw new Error(`cannot ${action} document from ${document.status}`);
-	return artifacts.setStatus(id, transition.to, context)!;
-}
-
-/**
- * Docs are immutable-by-convention only in the sense that no path existed to change them --
- * this is that path. A read-only external projection (see requireLocallyOwnedContent) still
- * refuses, on purpose: rewriting it here would silently fork from whatever system actually
- * owns it (e.g. web-spider's ingested pages), with nothing to ever reconcile the two again.
- */
-export function updateDocument(
-	artifacts: ArtifactStore,
-	id: string,
-	input: UpdateDocumentInput,
-	authority: AuthorityRegistry,
-	context?: ArtifactEventContext,
-): Artifact {
-	requireContentUpdateFields(input);
-	assertTitleBounds(input.title);
-	assertBodyBounds(input.body);
-	assertLabelsBounds(input.labels);
-	const _document = requireLocallyOwnedContent(requireMutableDocument(requireDocument(artifacts, id), authority, "update"));
-	const updated = artifacts.updateContent(id, input, context);
-	if (!updated) throw new Error(`document "${id}" not found`);
-	return updated;
-}
-
-export function linkDocument(
-	artifacts: ArtifactStore,
-	id: string,
-	relation: DocumentRelation,
-	targetId: string,
-	authority: AuthorityRegistry,
-	context?: ArtifactEventContext,
-): Artifact {
-	requireLocallyOwnedContent(requireMutableDocument(requireDocument(artifacts, id), authority, "link"));
-	const target = artifacts.get(targetId);
-	if (!target) throw new Error(`target artifact "${targetId}" not found`);
-	requireLocallyOwnedContent(requireMutableDocument(target, authority, "link"));
-	artifacts.link({ from: id, relation, to: targetId }, context);
-	return showDocument(artifacts, id);
-}
-
-export interface CreateRuleInput {
-	title: string;
-	body?: string;
-	condition?: string;
-	action?: string;
-	severity?: "block" | "warn" | "info";
-	labels?: string[];
-	extra?: Record<string, unknown>;
-	projectRoot?: string;
-}
-
-export type RuleTransition = "enable" | "disable";
-
-/**
- * A Rule's condition+action+body is injected into every relevant turn for the rule's entire
- * lifetime -- a permanent tax on every future turn's context budget, not a one-time cost.
- * Rejects (rather than silently truncating or merely warning) once a rule is unambiguously
- * bloated, since a silently-truncated rule would inject different text than what its author
- * reviewed, and a warning nobody reads is not a bound. See RULE_TEXT_HARD_LIMIT_CHARACTERS's
- * own comment in constants.ts for the research this threshold is grounded in.
- */
-export function ruleCombinedLength(condition: string | undefined, action: string | undefined, body: string | undefined): number {
-	return (condition ?? "").length + (action ?? "").length + (body ?? "").length;
-}
-
-/**
- * Non-blocking counterpart to assertRuleTextWithinBounds's hard rejection: the same combined
- * length, informational once it crosses the soft target, so a caller doesn't have to self-police
- * with a manual character count before every rules.create/update. Returns undefined at or under
- * the target -- the common case, not worth a field only ever seen as "undefined" on the wire.
- */
-export function ruleCombinedLengthWarning(combinedLength: number): string | undefined {
-	if (combinedLength <= RULE_TEXT_SOFT_TARGET_CHARACTERS) return undefined;
-	return (
-		`condition+action+body is ${combinedLength} characters, over the ${RULE_TEXT_SOFT_TARGET_CHARACTERS}-character soft target ` +
-		`(hard limit ${RULE_TEXT_HARD_LIMIT_CHARACTERS}) -- consider moving detail into a linked Doc.`
-	);
-}
-
-function assertRuleTextWithinBounds(condition: string | undefined, action: string | undefined, body: string | undefined): void {
-	const combined = ruleCombinedLength(condition, action, body);
-	if (combined > RULE_TEXT_HARD_LIMIT_CHARACTERS) {
-		throw new Error(
-			`rule condition+action+body is ${combined} characters, exceeding the ${RULE_TEXT_HARD_LIMIT_CHARACTERS}-character bound. ` +
-				"A Rule is injected into every relevant turn for its entire lifetime -- this is a permanent context-budget tax, not a one-time cost. " +
-				"Split it: keep a short Rule (the condition and the invariant itself), and move the full reasoning, examples, and research into a linked Doc.",
-		);
-	}
-}
-
-export function createRule(
-	artifacts: ArtifactStore,
-	scopes: ArtifactScopeStore,
-	input: CreateRuleInput,
-	context?: ArtifactEventContext,
-): Artifact {
-	assertRuleTextWithinBounds(input.condition, input.action, input.body);
-	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
-	const rule = artifacts.create(
-		{
-			kind: "rule",
-			status: "active", // explicit; see createDocument for why defaultStatusFor is not trusted here
-			title: input.title,
-			body: input.body,
-			labels: input.labels,
-			extra: {
-				...(input.extra ?? {}),
-				...(input.condition ? { condition: input.condition } : {}),
-				...(input.action ? { action: input.action } : {}),
-				severity: input.severity ?? "info",
-			},
-		},
-		context,
-	);
-	scopes.assign(rule.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
-	return rule;
-}
-
-export function listRules(artifacts: ArtifactStore, scopes: ArtifactScopeStore, filter: ListFilter): Artifact[] {
-	return listScoped(artifacts, scopes, "rule", filter);
-}
-
-export function assignRuleProject(
-	artifacts: ArtifactStore,
-	scopes: ArtifactScopeStore,
-	id: string,
-	projectRoot: string | undefined,
-): Artifact {
-	return assignArtifactProject(artifacts, scopes, id, "rule", projectRoot);
-}
-
-/**
- * Global rules always apply; scoped workflow-run rules apply only while their run owns active
- * focus. Both a workflow-definition target's own run scope ("skill-run", written by
- * workflow-execution.ts's runWorkflowSteps for that target kind) and a Playbook's own run scope
- * ("playbook-run", same call for a Playbook target) are recognized -- confirmed live that only
- * "skill-run" was ever checked here, silently breaking Playbook-run-scoped rule injection since
- * Playbook gained its own doc/rule structured steps.
- */
-export function listInjectableRules(artifacts: ArtifactStore, activeTaskId?: string): Artifact[] {
-	return artifacts.query({ kind: "rule", status: "active" }).filter((rule) => {
-		const scope = rule.extra.scope;
-		if (scope === undefined) return true;
-		if (typeof scope !== "object" || scope === null || Array.isArray(scope)) return false;
-		const value = scope as Record<string, unknown>;
-		if ((value.type !== "skill-run" && value.type !== "playbook-run") || !Array.isArray(value.taskIds)) return false;
-		return activeTaskId !== undefined && value.taskIds.some((id) => id === activeTaskId);
-	});
-}
-
-export function showRule(artifacts: ArtifactStore, id: string): Artifact {
-	requireKind(artifacts, id, "rule");
-	return artifacts.get(id, { tree: true })!;
-}
-
-export function previewRule(artifacts: ArtifactStore, id: string): string {
-	const rule = requireKind(artifacts, id, "rule");
-	const condition = typeof rule.extra.condition === "string" ? ` (when: ${rule.extra.condition})` : "";
-	const action = rule.body || (typeof rule.extra.action === "string" ? rule.extra.action : "");
-	return `• ${rule.title}${condition}\n  ${action}`;
-}
-
-export function transitionRule(artifacts: ArtifactStore, id: string, action: RuleTransition, context?: ArtifactEventContext): Artifact {
-	const rule = requireLocallyOwnedContent(requireKind(artifacts, id, "rule"));
-	const expected = action === "enable" ? "deprecated" : "active";
-	const target = action === "enable" ? "active" : "deprecated";
-	if (rule.status !== expected) throw new Error(`cannot ${action} rule from ${rule.status}`);
-	return artifacts.setStatus(id, target, context)!;
-}
-
-export type UpdateRuleInput = UpdateContentInput;
-
-/** A Rule's body update stays under the same combined condition+action+body ceiling as creation -- a permanent per-turn injection cost doesn't get looser just because it's an edit, not a create. */
-export function updateRule(artifacts: ArtifactStore, id: string, input: UpdateRuleInput, context?: ArtifactEventContext): Artifact {
-	requireContentUpdateFields(input);
-	assertTitleBounds(input.title);
-	assertLabelsBounds(input.labels);
-	const rule = requireLocallyOwnedContent(requireKind(artifacts, id, "rule"));
-	if (input.body !== undefined) {
-		const condition = typeof rule.extra.condition === "string" ? rule.extra.condition : undefined;
-		const action = typeof rule.extra.action === "string" ? rule.extra.action : undefined;
-		assertRuleTextWithinBounds(condition, action, input.body);
-	}
-	const updated = artifacts.updateContent(id, input, context);
-	if (!updated) throw new Error(`rule "${id}" not found`);
-	return updated;
-}
-
-export function gateTaskWithRule(artifacts: ArtifactStore, ruleId: string, taskId: string, context?: ArtifactEventContext): Artifact {
-	requireLocallyOwnedContent(requireKind(artifacts, ruleId, "rule"));
-	requireKind(artifacts, taskId, "task");
-	artifacts.link({ from: ruleId, relation: "gates", to: taskId }, context);
-	return showRule(artifacts, ruleId);
-}
-
 /**
+ * Playbook domain composition logic (create/list/show/update/transition/contain/depend/invoke),
+ * split out of the former domain-services.ts into its own per-domain file alongside
+ * docs/docs-service.ts and rules/rules-service.ts. Shared, kind-agnostic helpers live in
+ * ../domain-service-shared.ts. Distinct from playbook-definition.ts/playbook-execution.ts in
+ * this same directory, which compile/invoke a Playbook via the shared blueprint engine.
+ *
  * Playbooks: a trigger and an ordered list of steps -- authored as prose. But playbooks.invoke
  * (playbook-execution.ts) recycles the shared blueprint materialization engine: it compiles a
  * Playbook into a BlueprintDefinition and mechanically instantiates real Tasks from it.
@@ -464,6 +21,43 @@ export function gateTaskWithRule(artifacts: ArtifactStore, ruleId: string, taskI
  * time, while invoke's compiler (playbook-definition.ts) treats a cycle as a hard error --
  * real Tasks would otherwise be created in an infinite loop, unlike text rendering.
  */
+
+import type { Artifact } from "../artifact/artifact.ts";
+import { requireLocallyOwnedContent } from "../artifact/artifact.ts";
+import type { ArtifactEventContext } from "../artifact/artifact-event.ts";
+import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import {
+	ARTIFACT_TITLE_MAX_LENGTH,
+	PLAYBOOK_ARGUMENT_DESCRIPTION_MAX_LENGTH,
+	PLAYBOOK_ARGUMENT_MAX_COUNT,
+	PLAYBOOK_ARGUMENT_NAME_MAX_LENGTH,
+	PLAYBOOK_INVOCATION_MAX_CALL_DEPTH,
+	PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS,
+	PLAYBOOK_MAX_STEPS,
+	SKILL_MAX_ENUM_VALUES,
+} from "../constants.ts";
+import {
+	BLUEPRINT_INPUT_TYPES,
+	type BlueprintArgumentValue,
+	type BlueprintInputType,
+	validateArgumentValue,
+} from "../domain/blueprint-definition.ts";
+import { normalizeProjectRoot } from "../domain/task-scope.ts";
+import {
+	assertBodyBounds,
+	assertLabelsBounds,
+	assertTitleBounds,
+	assignArtifactProject,
+	type ListFilter,
+	listScoped,
+	requireContentUpdateFields,
+	requireKind,
+	runTransition,
+	type TransitionTable,
+	type UpdateContentInput,
+} from "../domain-service-shared.ts";
+
 export interface PlaybookArgument {
 	name: string;
 	description?: string;
@@ -621,14 +215,21 @@ export interface CreatePlaybookInput {
 	tools?: string[];
 	/** Declares named arguments this Playbook needs -- see playbookInvocation for how a missing required one surfaces. */
 	arguments?: unknown;
+	subtype?: string;
 	labels?: string[];
 	extra?: Record<string, unknown>;
+	templateId?: string;
 	projectRoot?: string;
 }
 
 export type PlaybookTransition = "enable" | "disable";
 export type UpdatePlaybookInput = UpdateContentInput;
 
+const PLAYBOOK_TRANSITIONS: TransitionTable<PlaybookTransition, string> = {
+	enable: { from: ["deprecated"], to: "active" },
+	disable: { from: ["active"], to: "deprecated" },
+};
+
 export function createPlaybook(
 	artifacts: ArtifactStore,
 	scopes: ArtifactScopeStore,
@@ -644,6 +245,7 @@ export function createPlaybook(
 			status: "active", // explicit; see createDocument for why defaultStatusFor is not trusted here
 			title: input.title,
 			body: input.body,
+			subtype: input.subtype,
 			labels: input.labels,
 			extra: {
 				...(input.extra ?? {}),
@@ -652,6 +254,7 @@ export function createPlaybook(
 				...(input.tools ? { tools: input.tools } : {}),
 				...(declaredArguments ? { arguments: declaredArguments } : {}),
 			},
+			templateId: input.templateId,
 		},
 		context,
 	);
@@ -695,10 +298,7 @@ export function transitionPlaybook(
 	context?: ArtifactEventContext,
 ): Artifact {
 	const playbook = requireLocallyOwnedContent(requireKind(artifacts, id, "playbook"));
-	const expected = action === "enable" ? "deprecated" : "active";
-	const target = action === "enable" ? "active" : "deprecated";
-	if (playbook.status !== expected) throw new Error(`cannot ${action} playbook from ${playbook.status}`);
-	return artifacts.setStatus(id, target, context)!;
+	return runTransition(artifacts, playbook, "playbook", action, PLAYBOOK_TRANSITIONS, context);
 }
 
 /** Idempotent (INSERT OR IGNORE at the storage layer): containing an already-nested child is a no-op, not an error. Both contains/part_of edges are written atomically -- matches tasks.contain's own shape. */