ai-delivery-workflow 0.2.2 → 0.4.0

package/lib/workflow-manager-facts.mjs

@@ -0,0 +1,778 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  commitWorkflowManagerAction,
+  prepareWorkflowManagerFormalTransaction,
+  preflightWorkflowManagerAction,
+  workflowManagerChecksum,
+} from "./workflow-manager-transaction.mjs";
+
+const runtimeRoot = path.dirname(fileURLToPath(import.meta.url));
+const installedYaml = path.join(runtimeRoot, "..", "state", "vendor", "yaml", "dist", "index.js");
+const require = createRequire(import.meta.url);
+const YAML = require(fs.existsSync(installedYaml) ? installedYaml : "yaml");
+const installedStateRuntime = path.join(runtimeRoot, "..", "state", "delivery-state.mjs");
+const packageStateRuntime = path.join(runtimeRoot, "delivery-state.mjs");
+const stateRuntime = fs.existsSync(installedStateRuntime) ? installedStateRuntime : packageStateRuntime;
+const { executeDeliveryStateCommand } = await import(pathToFileURL(stateRuntime).href);
+
+export const WORKFLOW_MANAGER_FACTS_SCHEMA_VERSION = "workflow-manager-facts.v1";
+
+const COLLECTIONS = Object.freeze({
+  requirements: [".workflow/product/requirements.yaml", ".workflow/product/requirements.yml"],
+  test_cases: [".workflow/quality/test-cases.yaml", ".workflow/quality/test-cases.yml"],
+  test_runs: [".workflow/quality/test-runs.yaml", ".workflow/quality/test-runs.yml"],
+  relations: [".workflow/control/relations.yaml", ".workflow/control/relations.yml"],
+});
+
+const COLLECTION_DEFINITIONS = Object.freeze({
+  requirements: {
+    relative: ".workflow/product/requirements.yaml",
+    arrayKey: "requirements",
+    identity: "requirement_id",
+    entityType: "requirement",
+  },
+  test_cases: {
+    relative: ".workflow/quality/test-cases.yaml",
+    arrayKey: "test_cases",
+    identity: "test_case_id",
+    entityType: "test-case",
+  },
+  test_runs: {
+    relative: ".workflow/quality/test-runs.yaml",
+    arrayKey: "test_runs",
+    identity: "test_run_id",
+    entityType: "test-run",
+  },
+});
+
+const REQUIREMENT_STATUSES = new Set(["draft", "accepted", "implemented", "verified", "retired", "superseded"]);
+const TEST_CASE_KINDS = new Set(["ui", "api", "integration", "unit", "security", "performance"]);
+const TEST_CASE_STATUSES = new Set(["draft", "ready", "retired"]);
+const TEST_RUN_OUTCOMES = new Set(["passed", "failed", "blocked", "skipped"]);
+
+function sha256(bytes) {
+  return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+
+function readYamlFile(root, candidates) {
+  for (const relative of candidates) {
+    const file = path.resolve(root, relative);
+    if (!isInside(file, root)) throw new Error(`Fact path escapes project root: ${relative}`);
+    if (fs.existsSync(file) && fs.statSync(file).isFile()) {
+      const bytes = fs.readFileSync(file);
+      return { file, relative, checksum: sha256(bytes), value: YAML.parse(bytes.toString("utf8")) || {} };
+    }
+  }
+  return null;
+}
+
+function isInside(candidate, root) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function arrayValue(value, keys) {
+  for (const key of keys) if (Array.isArray(value?.[key])) return value[key];
+  return [];
+}
+
+function collection(root, key, keys, identity) {
+  const source = readYamlFile(root, COLLECTIONS[key]);
+  const items = arrayValue(source?.value, keys).filter((item) => item && typeof item === "object").map((item) => ({
+    ...item,
+    entity_type: key === "requirements" ? "requirement" : key === "test_cases" ? "test-case" : key === "test_runs" ? "test-run" : item.entity_type || "relation",
+    entity_id: item[identity] || item.id || item.entity_id || null,
+    mutability: item.mutability || (key === "test_runs" ? "immutable" : key === "test_cases" ? "versioned" : key === "requirements" ? "governed" : "governed-relation"),
+  }));
+  return {
+    registration_status: source ? "registered" : "not-registered",
+    mutability: key === "test_runs" ? "append-only" : key === "relations" ? "governed" : "governed",
+    source: source ? { path: source.relative, revision: source.value.revision ?? 0, checksum: source.checksum } : null,
+    items,
+  };
+}
+
+function artifactCollection(root) {
+  const relative = ".workflow/delivery/artifact-registry.yaml";
+  const file = path.resolve(root, relative);
+  if (!isInside(file, root) || !fs.existsSync(file)) return { registration_status: "not-registered", source: null, items: [] };
+  const bytes = fs.readFileSync(file);
+  const value = YAML.parse(bytes.toString("utf8")) || {};
+  const items = arrayValue(value, ["artifacts"]).map((item) => ({
+    ...item,
+    entity_type: "artifact",
+    entity_id: item.artifact_id || item.id || item.entity_id || null,
+    mutability: "formal-state-governed",
+  }));
+  return { registration_status: "registered", mutability: "formal-state-governed", source: { path: relative, revision: value.revision ?? 0, checksum: sha256(bytes) }, items };
+}
+
+function eventCollection(root) {
+  const relatives = [
+    ".workflow/delivery/state-events.jsonl",
+    ".workflow/control/events/workflow-manager-events.jsonl",
+  ];
+  const sources = [];
+  const items = [];
+  const identities = new Set();
+  for (const relative of relatives) {
+    const file = path.resolve(root, relative);
+    if (!isInside(file, root) || !fs.existsSync(file)) continue;
+    const bytes = fs.readFileSync(file);
+    const sourceItems = bytes.toString("utf8").split(/\r?\n/).filter(Boolean).map((line, index) => {
+      let item;
+      try {
+        item = JSON.parse(line);
+      } catch {
+        return {
+          entity_type: "event",
+          entity_id: `${relative}:${index + 1}`,
+          source_path: relative,
+          source_line: index + 1,
+          mutability: "immutable",
+          parse_error: true,
+        };
+      }
+      const identity = item.event_id || item.id || `${relative}:${index + 1}`;
+      if (identities.has(identity)) throw new Error(`Duplicate event identity across Workflow Manager streams: ${identity}`);
+      identities.add(identity);
+      return {
+        ...item,
+        entity_type: "event",
+        entity_id: identity,
+        source_path: relative,
+        source_line: index + 1,
+        mutability: "immutable",
+      };
+    });
+    items.push(...sourceItems);
+    sources.push({ path: relative, revision: sourceItems.length, checksum: sha256(bytes) });
+  }
+  items.sort((left, right) => String(right.occurred_at || "").localeCompare(String(left.occurred_at || ""))
+    || String(left.entity_id).localeCompare(String(right.entity_id)));
+  return {
+    registration_status: sources.length ? "registered" : "not-registered",
+    mutability: "immutable",
+    source: sources.length ? {
+      path: sources.map((source) => source.path).join(" + "),
+      paths: sources,
+      revision: sources.reduce((total, source) => total + source.revision, 0),
+      checksum: workflowManagerChecksum(sources.map((source) => source.checksum)),
+    } : null,
+    items,
+  };
+}
+
+function decisionCollection(root) {
+  const file = path.resolve(root, ".workflow/delivery/workflow-state.yaml");
+  if (!isInside(file, root) || !fs.existsSync(file)) return { pending: [], history: [], source: null };
+  const bytes = fs.readFileSync(file);
+  const value = YAML.parse(bytes.toString("utf8")) || {};
+  const scope = value.development_state || value;
+  const pending = Array.isArray(scope.pending_gates) ? scope.pending_gates : [];
+  const history = Array.isArray(scope.gate_decisions) ? scope.gate_decisions.map((item) => ({
+    ...item,
+    comment: item.comment || (/^Workflow Manager (approved|rejected) decision for /.test(item.rationale || "")
+      ? null
+      : item.rationale || null),
+    entity_type: "decision",
+    entity_id: item.decision_id || item.gate_id || null,
+  })) : [];
+  return { pending, history, source: { path: ".workflow/delivery/workflow-state.yaml", revision: scope.revision ?? value.revision ?? 0, checksum: sha256(bytes) } };
+}
+
+function normalizeRelation(item, index) {
+  return {
+    ...item,
+    relation_id: item.relation_id || item.id || `REL-${String(index + 1).padStart(4, "0")}`,
+    from: item.from || item.source || item.from_id || null,
+    to: item.to || item.target || item.to_id || null,
+    from_entity_type: item.from_entity_type || item.source_entity_type || null,
+    to_entity_type: item.to_entity_type || item.target_entity_type || null,
+    relation_type: item.relation_type || item.type || "related-to",
+    relation_state: item.relation_state || item.status || "suggested",
+  };
+}
+
+function attachRelations(collections, relations) {
+  const byTypedId = new Map();
+  const byId = new Map();
+  for (const bucket of Object.values(collections)) {
+    for (const item of bucket.items || []) {
+      if (!item.entity_id) continue;
+      byTypedId.set(`${item.entity_type}:${item.entity_id}`, item);
+      byId.set(item.entity_id, [...(byId.get(item.entity_id) || []), item]);
+    }
+  }
+  const resolve = (identity, declaredType) => declaredType
+    ? byTypedId.get(`${declaredType}:${identity}`)
+    : byId.get(identity)?.length === 1 ? byId.get(identity)[0] : null;
+  for (const relation of relations.items) {
+    const related = (left, direction) => {
+      const targetId = direction === "out" ? left.to : left.from;
+      const declaredType = direction === "out" ? left.to_entity_type : left.from_entity_type;
+      const target = resolve(targetId, declaredType);
+      return {
+        entity_id: targetId,
+        entity_type: target?.entity_type || declaredType || "unknown",
+        relation_id: left.relation_id,
+        relation_type: left.relation_type,
+        relation_state: left.relation_state,
+      };
+    };
+    const from = resolve(relation.from, relation.from_entity_type);
+    const to = resolve(relation.to, relation.to_entity_type);
+    if (from) (from.related_items ||= []).push(related(relation, "out"));
+    if (to) (to.related_items ||= []).push(related(relation, "in"));
+  }
+  for (const bucket of Object.values(collections)) {
+    for (const item of bucket.items || []) {
+      item.related_items = (item.related_items || []).sort((a, b) => String(a.entity_id).localeCompare(String(b.entity_id)));
+      item.related_requirements = item.related_items.filter((related) => related.entity_type === "requirement");
+    }
+  }
+}
+
+function tasksCollection(root, relations) {
+  const directory = path.resolve(root, ".workflow/control/tasks");
+  if (!isInside(directory, root) || !fs.existsSync(directory)) return { registration_status: "not-registered", mutability: "task-writer-governed", source: null, items: [] };
+  const files = fs.readdirSync(directory).filter((name) => /\.(yaml|yml|json)$/i.test(name)).sort();
+  const items = [];
+  for (const name of files) {
+    const file = path.join(directory, name);
+    const bytes = fs.readFileSync(file);
+    const item = name.endsWith(".json") ? JSON.parse(bytes.toString("utf8")) : YAML.parse(bytes.toString("utf8"));
+    if (!item || typeof item !== "object") continue;
+    items.push({ ...item, entity_type: "task", entity_id: item.task_id || item.id || null, mutability: "task-writer-governed" });
+  }
+  return { registration_status: "registered", mutability: "task-writer-governed", source: { path: ".workflow/control/tasks", revision: files.length, checksum: sha256(files.map((name) => fs.readFileSync(path.join(directory, name))).reduce((all, bytes) => Buffer.concat([all, bytes]), Buffer.alloc(0))) }, items };
+}
+
+export function inspectWorkflowManagerFacts(projectRoot) {
+  const root = path.resolve(projectRoot);
+  const collections = {
+    requirements: collection(root, "requirements", ["requirements", "items"], "requirement_id"),
+    tasks: tasksCollection(root),
+    test_cases: collection(root, "test_cases", ["test_cases", "items"], "test_case_id"),
+    test_runs: collection(root, "test_runs", ["test_runs", "items"], "test_run_id"),
+    artifacts: artifactCollection(root),
+    events: eventCollection(root),
+  };
+  const relationBucket = collection(root, "relations", ["relations", "items"], "relation_id");
+  relationBucket.items = relationBucket.items.map(normalizeRelation);
+  attachRelations(collections, relationBucket);
+  return {
+    schema_version: WORKFLOW_MANAGER_FACTS_SCHEMA_VERSION,
+    mutability: "mixed-governed",
+    requirements: collections.requirements,
+    tasks: collections.tasks,
+    test_cases: collections.test_cases,
+    test_runs: collections.test_runs,
+    artifacts: collections.artifacts,
+    events: collections.events,
+    decisions: decisionCollection(root),
+    relations: relationBucket,
+  };
+}
+
+function requiredText(value, label) {
+  const normalized = typeof value === "string" ? value.trim() : "";
+  if (!normalized) throw new Error(`${label} is required`);
+  return normalized;
+}
+
+function requiredActor(value) {
+  const actor = requiredText(value, "actor");
+  if (!/^(human|agent):[A-Za-z0-9._@/-]+$/.test(actor)) {
+    throw new Error("actor must identify a human or agent");
+  }
+  return actor;
+}
+
+function allowedValue(value, allowed, label) {
+  const normalized = requiredText(value, label);
+  if (!allowed.has(normalized)) throw new Error(`${label} is not supported: ${normalized}`);
+  return normalized;
+}
+
+function safeIdentity(value, label) {
+  const normalized = requiredText(value, label);
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(normalized)) {
+    throw new Error(`${label} is invalid`);
+  }
+  return normalized;
+}
+
+function stringList(value, label) {
+  if (!Array.isArray(value) || value.length === 0) throw new Error(`${label} must be a non-empty array`);
+  const normalized = [...new Set(value.map((item) => requiredText(item, label)))];
+  return normalized;
+}
+
+function readWritableCollection(root, definition) {
+  const file = path.resolve(root, definition.relative);
+  if (!isInside(file, root)) throw new Error(`Fact path escapes project root: ${definition.relative}`);
+  if (!fs.existsSync(file)) {
+    return { file, revision: 0, checksum: null, value: { schema_version: 1, revision: 0, [definition.arrayKey]: [] } };
+  }
+  const bytes = fs.readFileSync(file);
+  const value = YAML.parse(bytes.toString("utf8")) || {};
+  if (value.schema_version !== 1 || !Number.isInteger(value.revision) || value.revision < 0
+      || !Array.isArray(value[definition.arrayKey] ?? value.items)) {
+    throw new Error(`${definition.arrayKey} collection must declare schema_version 1, a non-negative revision, and an item array`);
+  }
+  return {
+    file,
+    revision: Number(value.revision || 0),
+    checksum: sha256(bytes),
+    value: { ...value, [definition.arrayKey]: arrayValue(value, [definition.arrayKey, "items"]) },
+  };
+}
+
+function assertCollectionVersion(collection, input) {
+  if (!Number.isInteger(input.expected_revision) || input.expected_revision < 0) {
+    throw new Error("expected_revision must be a non-negative integer");
+  }
+  if (input.expected_revision !== collection.revision) {
+    throw new Error(`Collection revision conflict: expected ${input.expected_revision}, found ${collection.revision}`);
+  }
+  const expectedChecksum = input.expected_checksum ?? null;
+  if (expectedChecksum !== collection.checksum) {
+    throw new Error("Collection checksum conflict");
+  }
+}
+
+export function applyWorkflowManagerRequirement(projectRoot, input = {}) {
+  const root = path.resolve(projectRoot);
+  const definition = COLLECTION_DEFINITIONS.requirements;
+  const requirementId = safeIdentity(input.requirement_id, "requirement_id");
+  const operation = input.operation;
+  if (!new Set(["create", "update"]).has(operation)) throw new Error("operation must be create or update");
+  requiredActor(input.actor);
+  requiredText(input.idempotency_key, "idempotency_key");
+  const replay = preflightWorkflowManagerAction(root, {
+    action: "requirement-apply",
+    subject: requirementId,
+    input,
+  });
+  if (replay) return { outcome: "idempotent-replay", receipt: replay, result: replay.result };
+
+  const collection = readWritableCollection(root, definition);
+  assertCollectionVersion(collection, input);
+  const existingIndex = collection.value[definition.arrayKey]
+    .findIndex((item) => item?.[definition.identity] === requirementId);
+  if (operation === "create" && existingIndex >= 0) throw new Error(`Requirement already exists: ${requirementId}`);
+  if (operation === "update" && existingIndex < 0) throw new Error(`Requirement not found: ${requirementId}`);
+
+  const current = existingIndex >= 0 ? collection.value[definition.arrayKey][existingIndex] : null;
+  if (operation === "update") {
+    if (!Number.isInteger(input.expected_entity_revision) || input.expected_entity_revision !== Number(current.revision || 0)) {
+      throw new Error(`Requirement entity revision conflict for ${requirementId}`);
+    }
+  }
+  const requirement = {
+    requirement_id: requirementId,
+    iteration_id: operation === "create"
+      ? safeIdentity(input.iteration_id, "iteration_id")
+      : current.iteration_id,
+    title: requiredText(input.title, "title"),
+    summary: requiredText(input.summary, "summary"),
+    status: allowedValue(input.status, REQUIREMENT_STATUSES, "status"),
+    acceptance: stringList(input.acceptance, "acceptance"),
+    revision: Number(current?.revision || 0) + 1,
+  };
+  const items = [...collection.value[definition.arrayKey]];
+  if (existingIndex < 0) items.push(requirement);
+  else items[existingIndex] = requirement;
+  items.sort((left, right) => String(left.requirement_id).localeCompare(String(right.requirement_id)));
+  const next = {
+    ...collection.value,
+    schema_version: 1,
+    revision: collection.revision + 1,
+    [definition.arrayKey]: items,
+  };
+  const content = YAML.stringify(next, { lineWidth: 0 });
+  const outputChecksum = sha256(content);
+  const result = { requirement, collection_revision: next.revision, collection_checksum: outputChecksum };
+  return commitWorkflowManagerAction(root, {
+    action: "requirement-apply",
+    subject: requirementId,
+    input,
+    result,
+    detail: {
+      input_revision: collection.revision,
+      input_checksum: collection.checksum,
+      output_revision: next.revision,
+      output_checksum: outputChecksum,
+      affected_identities: [requirementId],
+    },
+    writes: [{ file: collection.file, content }],
+    receiptPrefix: "WM-REQ",
+  });
+}
+
+export function applyWorkflowManagerTestCase(projectRoot, input = {}) {
+  const root = path.resolve(projectRoot);
+  const definition = COLLECTION_DEFINITIONS.test_cases;
+  const testCaseId = safeIdentity(input.test_case_id, "test_case_id");
+  const operation = input.operation;
+  if (!new Set(["create", "update"]).has(operation)) throw new Error("operation must be create or update");
+  requiredActor(input.actor);
+  requiredText(input.idempotency_key, "idempotency_key");
+  const replay = preflightWorkflowManagerAction(root, {
+    action: "test-case-apply",
+    subject: testCaseId,
+    input,
+  });
+  if (replay) return { outcome: "idempotent-replay", receipt: replay, result: replay.result };
+
+  const collection = readWritableCollection(root, definition);
+  assertCollectionVersion(collection, input);
+  const existingIndex = collection.value[definition.arrayKey]
+    .findIndex((item) => item?.[definition.identity] === testCaseId);
+  if (operation === "create" && existingIndex >= 0) throw new Error(`Test case already exists: ${testCaseId}`);
+  if (operation === "update" && existingIndex < 0) throw new Error(`Test case not found: ${testCaseId}`);
+  const current = existingIndex >= 0 ? collection.value[definition.arrayKey][existingIndex] : null;
+  if (operation === "update") {
+    const currentRevision = Number(current.version || current.revision || 0);
+    if (!Number.isInteger(input.expected_entity_revision) || input.expected_entity_revision !== currentRevision) {
+      throw new Error(`Test case entity revision conflict for ${testCaseId}`);
+    }
+  }
+  const version = Number(current?.version || current?.revision || 0) + 1;
+  const timestamp = new Date().toISOString();
+  const versionDefinition = {
+    version,
+    title: requiredText(input.title, "title"),
+    kind: allowedValue(input.kind, TEST_CASE_KINDS, "kind"),
+    status: allowedValue(input.status, TEST_CASE_STATUSES, "status"),
+    steps: stringList(input.steps, "steps"),
+    expected_result: requiredText(input.expected_result, "expected_result"),
+    recorded_at: timestamp,
+  };
+  versionDefinition.checksum = workflowManagerChecksum(versionDefinition);
+  const previousVersions = Array.isArray(current?.versions)
+    ? current.versions
+    : current
+      ? [{
+        version: Number(current.version || current.revision || 1),
+        title: current.title,
+        kind: current.kind,
+        status: current.status,
+        steps: current.steps,
+        expected_result: current.expected_result,
+        recorded_at: current.updated_at || current.created_at || null,
+        checksum: current.definition_checksum || null,
+      }]
+      : [];
+  const testCase = {
+    test_case_id: testCaseId,
+    iteration_id: operation === "create"
+      ? safeIdentity(input.iteration_id, "iteration_id")
+      : safeIdentity(current.iteration_id, "iteration_id"),
+    title: versionDefinition.title,
+    kind: versionDefinition.kind,
+    status: versionDefinition.status,
+    steps: versionDefinition.steps,
+    expected_result: versionDefinition.expected_result,
+    version,
+    revision: version,
+    definition_checksum: versionDefinition.checksum,
+    created_at: current?.created_at || timestamp,
+    updated_at: timestamp,
+    versions: [...previousVersions, versionDefinition],
+  };
+  const items = [...collection.value[definition.arrayKey]];
+  if (existingIndex < 0) items.push(testCase);
+  else items[existingIndex] = testCase;
+  items.sort((left, right) => String(left.test_case_id).localeCompare(String(right.test_case_id)));
+  const next = {
+    ...collection.value,
+    schema_version: 1,
+    revision: collection.revision + 1,
+    [definition.arrayKey]: items,
+  };
+  const content = YAML.stringify(next, { lineWidth: 0 });
+  const outputChecksum = sha256(content);
+  const result = { test_case: testCase, collection_revision: next.revision, collection_checksum: outputChecksum };
+  return commitWorkflowManagerAction(root, {
+    action: "test-case-apply",
+    subject: testCaseId,
+    input,
+    result,
+    detail: {
+      input_revision: collection.revision,
+      input_checksum: collection.checksum,
+      output_revision: next.revision,
+      output_checksum: outputChecksum,
+      affected_identities: [testCaseId],
+    },
+    writes: [{ file: collection.file, content }],
+    receiptPrefix: "WM-TC",
+  });
+}
+
+export function recordWorkflowManagerTestRun(projectRoot, input = {}) {
+  const root = path.resolve(projectRoot);
+  const definition = COLLECTION_DEFINITIONS.test_runs;
+  const testRunId = safeIdentity(input.test_run_id, "test_run_id");
+  requiredActor(input.actor);
+  requiredText(input.idempotency_key, "idempotency_key");
+  const replay = preflightWorkflowManagerAction(root, {
+    action: "test-run-record",
+    subject: testRunId,
+    input,
+  });
+  if (replay) return { outcome: "idempotent-replay", receipt: replay, result: replay.result };
+
+  const collection = readWritableCollection(root, definition);
+  assertCollectionVersion(collection, input);
+  if (collection.value[definition.arrayKey].some((item) => item?.[definition.identity] === testRunId)) {
+    throw new Error(`Test run already exists: ${testRunId}`);
+  }
+  const testCaseId = safeIdentity(input.test_case_id, "test_case_id");
+  const testCaseSource = readWritableCollection(root, COLLECTION_DEFINITIONS.test_cases);
+  const testCase = testCaseSource.value.test_cases.find((item) => item?.test_case_id === testCaseId);
+  if (!testCase) throw new Error(`Test case not found: ${testCaseId}`);
+  if (!Number.isInteger(input.test_case_version)
+      || input.test_case_version !== Number(testCase.version || testCase.revision || 0)) {
+    throw new Error(`Test case version conflict for ${testCaseId}`);
+  }
+  const testRun = {
+    test_run_id: testRunId,
+    test_case_id: testCaseId,
+    test_case_version: input.test_case_version,
+    iteration_id: safeIdentity(input.iteration_id, "iteration_id"),
+    candidate_id: safeIdentity(input.candidate_id, "candidate_id"),
+    outcome: allowedValue(input.outcome, TEST_RUN_OUTCOMES, "outcome"),
+    evidence: stringList(input.evidence, "evidence"),
+    recorded_at: new Date().toISOString(),
+  };
+  const items = [...collection.value[definition.arrayKey], testRun]
+    .sort((left, right) => String(left.test_run_id).localeCompare(String(right.test_run_id)));
+  const next = {
+    ...collection.value,
+    schema_version: 1,
+    revision: collection.revision + 1,
+    [definition.arrayKey]: items,
+  };
+  const content = YAML.stringify(next, { lineWidth: 0 });
+  const outputChecksum = sha256(content);
+  const result = { test_run: testRun, collection_revision: next.revision, collection_checksum: outputChecksum };
+  return commitWorkflowManagerAction(root, {
+    action: "test-run-record",
+    subject: testRunId,
+    input,
+    result,
+    detail: {
+      input_revision: collection.revision,
+      input_checksum: collection.checksum,
+      output_revision: next.revision,
+      output_checksum: outputChecksum,
+      affected_identities: [testRunId, testCaseId, testRun.candidate_id],
+    },
+    writes: [{ file: collection.file, content }],
+    receiptPrefix: "WM-TR",
+  });
+}
+
+function appendArg(argv, flag, value) {
+  if (value === undefined || value === null || value === "") return;
+  argv.push(flag, String(value));
+}
+
+function appendArgs(argv, flag, values) {
+  for (const value of Array.isArray(values) ? values : []) appendArg(argv, flag, value);
+}
+
+function defaultTaskWriter(projectRoot, argv, descriptor, options = {}) {
+  const script = path.join(
+    projectRoot,
+    ".agents", "skills", "ai-delivery-checkpoint-task", "scripts", "task-state.mjs",
+  );
+  if (!fs.existsSync(script)) throw new Error(`Installed task writer is missing: ${script}`);
+  const written = spawnSync(process.execPath, [script, ...argv, "--manager-transaction"], {
+    cwd: projectRoot,
+    encoding: "utf8",
+    input: JSON.stringify(descriptor),
+    env: {
+      ...process.env,
+      ...(options.taskTransactionFailureSuffix
+        ? { AI_DELIVERY_TEST_TASK_TRANSACTION_FAILURE_SUFFIX: options.taskTransactionFailureSuffix }
+        : {}),
+    },
+    windowsHide: true,
+  });
+  if (written.error || written.status !== 0) {
+    throw new Error(written.error?.message || written.stderr.trim() || "Task writer failed");
+  }
+  return JSON.parse(written.stdout);
+}
+
+function taskWriterArgs(root, input) {
+  const operation = input.operation;
+  if (!new Set(["create", "activate", "checkpoint", "finish"]).has(operation)) {
+    throw new Error("operation must be create, activate, checkpoint, or finish");
+  }
+  const taskId = safeIdentity(input.task_id, "task_id");
+  const command = operation === "create" ? "init" : operation;
+  const argv = [command, "--root", root, "--state-root", root, "--task-id", taskId];
+  if (operation === "create") {
+    appendArg(argv, "--iteration-id", safeIdentity(input.iteration_id, "iteration_id"));
+    appendArg(argv, "--node", safeIdentity(input.node, "node"));
+    appendArg(argv, "--skill", safeIdentity(input.skill, "skill"));
+    appendArg(argv, "--goal", requiredText(input.goal, "goal"));
+    appendArg(argv, "--responsibility", requiredText(input.responsibility, "responsibility"));
+    appendArgs(argv, "--scope", input.scope);
+    appendArgs(argv, "--acceptance", input.acceptance);
+    appendArgs(argv, "--depends-on", input.depends_on);
+    appendArg(argv, "--next-action", requiredText(input.next_action, "next_action"));
+    appendArg(argv, "--next-action-owner", requiredText(input.next_action_owner, "next_action_owner"));
+    appendArg(argv, "--status", "queued");
+    appendArg(argv, "--sequence", input.sequence);
+    appendArg(argv, "--derived-from", input.derived_from);
+    appendArg(argv, "--supersedes", input.supersedes);
+    return { argv, taskId };
+  }
+  if (operation === "activate") {
+    appendArg(argv, "--status", input.status || "running");
+    appendArg(argv, "--phase", input.phase);
+    if (input.new_attempt === true) argv.push("--new-attempt");
+  } else {
+    appendArg(argv, "--status", requiredText(input.status, "status"));
+    appendArg(argv, "--phase", input.phase);
+    appendArgs(argv, "--completed-step", input.completed_steps);
+    appendArgs(argv, "--blocker", input.blockers);
+    appendArgs(argv, "--evidence", input.evidence);
+    appendArgs(argv, "--actual-output", input.actual_outputs);
+  }
+  appendArg(argv, "--next-action", requiredText(input.next_action, "next_action"));
+  appendArg(argv, "--next-action-owner", input.next_action_owner);
+  return { argv, taskId };
+}
+
+export function applyWorkflowManagerTask(projectRoot, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  requiredActor(input.actor);
+  requiredText(input.idempotency_key, "idempotency_key");
+  if (!Number.isInteger(input.expected_shared_revision) || input.expected_shared_revision < 0) {
+    throw new Error("expected_shared_revision must be a non-negative integer");
+  }
+  const { argv, taskId } = taskWriterArgs(root, input);
+  const replay = preflightWorkflowManagerAction(root, {
+    action: "task-apply",
+    subject: taskId,
+    input,
+  });
+  if (replay) return { outcome: "idempotent-replay", receipt: replay, result: replay.result };
+  const descriptor = { schema_version: 1, action: "task-apply", subject: taskId, input };
+  const taskWriter = options.taskWriter
+    || ((writerArgv) => defaultTaskWriter(root, writerArgv, descriptor, options));
+  const written = taskWriter(argv);
+  const task = written && typeof written === "object" ? { ...written } : written;
+  const managerTransaction = task?.manager_transaction || null;
+  if (task) delete task.manager_transaction;
+  if (!task || task.task_id !== taskId) throw new Error("Task writer returned an unexpected identity");
+  const result = { task };
+  if (!options.taskWriter) {
+    if (!managerTransaction?.receipt || managerTransaction.receipt.result?.task?.task_id !== taskId) {
+      throw new Error("Task writer did not return its governed Manager transaction evidence");
+    }
+    return {
+      outcome: managerTransaction.outcome,
+      result,
+      receipt: managerTransaction.receipt,
+      event: managerTransaction.event,
+    };
+  }
+  return commitWorkflowManagerAction(root, {
+    action: "task-apply",
+    subject: taskId,
+    input,
+    result,
+    detail: {
+      output_revision: Number(task.shared_revision || 0),
+      affected_identities: [taskId],
+      delegated_writer: "task-state.mjs",
+    },
+    receiptPrefix: "WM-TASK",
+  });
+}
+
+export function applyWorkflowManagerArtifact(projectRoot, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  const artifactId = safeIdentity(input.artifact_id, "artifact_id");
+  requiredActor(input.actor);
+  requiredText(input.idempotency_key, "idempotency_key");
+  if (!Number.isInteger(input.expected_revision) || input.expected_revision < 0) {
+    throw new Error("expected_revision must be a non-negative integer");
+  }
+  const replay = preflightWorkflowManagerAction(root, {
+    action: "artifact-register",
+    subject: artifactId,
+    input,
+  });
+  if (replay) return { outcome: "idempotent-replay", receipt: replay, result: replay.result };
+  const argv = [
+    "artifact", "register", "--project", root,
+    "--expected-revision", String(input.expected_revision),
+    "--id", artifactId,
+    "--artifact-type", requiredText(input.artifact_type, "artifact_type"),
+    "--path", requiredText(input.path, "path"),
+    "--node", safeIdentity(input.node, "node"),
+    "--status", requiredText(input.status, "status"),
+  ];
+  appendArg(argv, "--version", input.version);
+  appendArg(argv, "--producer-skill", input.producer_skill);
+  appendArg(argv, "--candidate-id", input.candidate_id);
+  appendArg(argv, "--supersedes", input.supersedes);
+  const stateWriter = options.stateWriter
+    || ((writerArgv, writerOptions) => executeDeliveryStateCommand(writerArgv, { yaml: YAML, ...writerOptions }));
+  if (options.stateWriter) {
+    const formal = stateWriter(argv, options.stateOptions || {});
+    if (formal?.artifact?.artifact_id !== artifactId) throw new Error("Formal state writer returned an unexpected artifact identity");
+    const result = { artifact: formal.artifact, artifact_registry_revision: formal.revision };
+    return commitWorkflowManagerAction(root, {
+      action: "artifact-register",
+      subject: artifactId,
+      input,
+      result,
+      detail: {
+        input_revision: input.expected_revision,
+        output_revision: formal.revision,
+        affected_identities: [artifactId],
+        delegated_writer: "delivery-state.artifact-register",
+      },
+      receiptPrefix: "WM-ART",
+    });
+  }
+  const transaction = prepareWorkflowManagerFormalTransaction(root, {
+    action: "artifact-register",
+    subject: artifactId,
+    input,
+    resultFactory: ({ mutations }) => {
+      const mutation = mutations.find((item) => item.stream === "artifact-registry");
+      const artifact = mutation?.value?.artifacts?.find((item) => item.artifact_id === artifactId);
+      if (!artifact) throw new Error("Formal state transaction did not register the expected artifact");
+      return { artifact, artifact_registry_revision: mutation.value.revision };
+    },
+    detailFactory: (_formal, result) => ({
+      input_revision: input.expected_revision,
+      output_revision: result.artifact_registry_revision,
+      affected_identities: [artifactId],
+      delegated_writer: "delivery-state.artifact-register",
+    }),
+    receiptPrefix: "WM-ART",
+  });
+  const formal = stateWriter(argv, {
+    ...(options.stateOptions || {}),
+    managerTransactionWriteFactory: transaction.factory,
+  });
+  if (formal?.artifact?.artifact_id !== artifactId) throw new Error("Formal state writer returned an unexpected artifact identity");
+  return transaction.result();
+}