create-safest-tools 0.6.0 → 0.7.0

package/template/src/workflow-platform-validation.ts

@@ -1,5 +1,6 @@
 import { canonicalJson } from "./audit";
 import { ApiError } from "./report-http";
+import { compilePlaybook, parsePlaybook, playbookAuthority, PlaybookInputError } from "../shared/playbooks";
 import type {
   JsonObject,
   JsonValue,
@@ -162,7 +163,7 @@ export function parseWorkflowGraph(value: unknown): WorkflowGraphV1 {
   const input = object(value, "workflow");
   knownFields(input, [
     "schema_version", "purpose", "entry_node_id", "nodes", "edges", "input_schema",
-    "terminal_codes", "default_policies",
+    "terminal_codes", "default_policies", "playbook",
   ], "workflow");
   if (input.schema_version !== "1") throw new ApiError(400, "unsupported_workflow_schema", "workflow.schema_version must be 1.", { path: "workflow.schema_version" });
   if (typeof input.purpose !== "string" || !purposes.has(input.purpose as WorkflowGraphV1["purpose"])) {
@@ -181,7 +182,16 @@ export function parseWorkflowGraph(value: unknown): WorkflowGraphV1 {
   if (new Set(terminalCodes).size !== terminalCodes.length) throw new ApiError(400, "invalid_workflow", "workflow.terminal_codes contains duplicates.");
   const defaults = object(input.default_policies ?? {}, "workflow.default_policies");
   knownFields(defaults, ["timeout", "retry", "data_retention_class"], "workflow.default_policies");
+  let playbook: WorkflowGraphV1["playbook"];
+  if (input.playbook !== undefined) {
+    try { playbook = parsePlaybook(input.playbook); }
+    catch (error) {
+      if (error instanceof PlaybookInputError) throw new ApiError(400, "invalid_playbook", error.message, { path: error.path });
+      throw error;
+    }
+  }
   return {
+    ...(playbook ? { playbook } : {}),
     schemaVersion: "1",
     purpose: input.purpose as WorkflowGraphV1["purpose"],
     entryNodeId: identifier(input.entry_node_id, "workflow.entry_node_id"),
@@ -276,6 +286,17 @@ function capabilityManifest(graph: WorkflowGraphV1, estimatedMaximumSteps: numbe
 export function validateWorkflowGraph(graph: WorkflowGraphV1, authorityMode: WorkflowAuthorityMode = "assist"): WorkflowValidationResult {
   const errors: WorkflowValidationIssue[] = [];
   const warnings: WorkflowValidationIssue[] = [];
+  if (graph.playbook) {
+    const guide = graph.playbook;
+    if (guide.editing_mode === "guided") {
+      const structure = (candidate: WorkflowGraphV1): string => canonicalWorkflowGraph({ ...candidate, nodes: candidate.nodes.map(({ metadata: _metadata, ...node }) => node) });
+      if (structure(graph) !== structure(parseWorkflowGraph(compilePlaybook(guide)))) errors.push(issue("playbook_graph_mismatch", "The workflow differs from its guide. Save the matching guide or explicitly switch to advanced workflow editing."));
+      if (playbookAuthority(guide) !== authorityMode) errors.push(issue("playbook_authority_mismatch", "Publication authority must match the playbook's selected rollout mode."));
+      if (!guide.summary || !guide.policy_text || !guide.policy_code || !guide.outcomes.decision_codes.length) errors.push(issue("playbook_rules_incomplete", "Describe the situation, applicable policy and permitted outcomes before publishing."));
+      if (guide.rollout === "automate" && (!guide.investigation.enabled || !guide.outcomes.delegated_decision_codes.length)) errors.push(issue("playbook_automation_incomplete", "Automation requires an investigator and explicitly delegated outcomes."));
+      if (guide.rollout !== "automate" && guide.outcomes.actions.some(action => action.approval !== "human")) errors.push(issue("playbook_action_approval_required", "Actions in Assist require human approval."));
+    } else warnings.push(issue("playbook_advanced_workflow", "This playbook uses advanced workflow editing. Its guide is reference material; inspect the workflow for executable behaviour."));
+  }
   const nodeById = new Map<string, WorkflowNodeV1>();
   const edgeIds = new Set<string>();
   const outgoing = new Map<string, WorkflowEdgeV1[]>();
@@ -500,6 +521,7 @@ export function parseWorkflowPublish(value: unknown): WorkflowPublishInput {
 
 export function graphForStorage(graph: WorkflowGraphV1): Record<string, unknown> {
   return {
+    ...(graph.playbook ? { playbook: graph.playbook } : {}),
     schema_version: graph.schemaVersion,
     purpose: graph.purpose,
     entry_node_id: graph.entryNodeId,

package/template/src/workflow-repository.ts

@@ -1,3 +1,4 @@
+import { noticeTemplateVariables } from "../shared/notice-inputs";
 import { canonicalJson } from "./audit";
 import { sha256 } from "./report-crypto";
 import { ApiError } from "./report-http";
@@ -20,6 +21,7 @@ import { simulateWorkflow, simulationMatchesExpected } from "./workflow-simulato
 import type { JsonObject } from "./workflow-platform-types";
 
 interface WorkflowListRow {
+  graphJson: string | null;
   id: string;
   key: string;
   name: string;
@@ -72,6 +74,7 @@ function parsedJson<T>(value: string | null, fallback: T): T {
 
 function workflowFromRow(row: WorkflowListRow): Record<string, unknown> {
   return {
+    playbook: parsedJson<{ playbook?: unknown }>(row.graphJson, {}).playbook ?? null,
     id: row.id,
     key: row.key,
     name: row.name,
@@ -144,6 +147,7 @@ export async function listWorkflowDefinitions(
     SELECT w.id, w.workflow_key AS key, w.name, w.description, w.purpose, w.status,
       w.active_version_id AS activeVersionId, w.created_by AS createdBy,
       w.created_at AS createdAt, w.updated_at AS updatedAt,
+      COALESCE(d.graph_json, v.graph_json) AS graphJson,
       d.id AS draftId, d.revision AS draftRevision, d.validation_status AS validationStatus,
       d.validation_json AS validationJson, v.version, v.authority_mode AS authorityMode,
       v.published_at AS publishedAt,
@@ -166,6 +170,7 @@ export async function loadWorkflowDefinition(
     SELECT w.id, w.workflow_key AS key, w.name, w.description, w.purpose, w.status,
       w.active_version_id AS activeVersionId, w.created_by AS createdBy,
       w.created_at AS createdAt, w.updated_at AS updatedAt,
+      COALESCE(d.graph_json, v.graph_json) AS graphJson,
       d.id AS draftId, d.revision AS draftRevision, d.validation_status AS validationStatus,
       d.validation_json AS validationJson, v.version, v.authority_mode AS authorityMode,
       v.published_at AS publishedAt,
@@ -194,7 +199,7 @@ export async function loadWorkflowDefinition(
       WHERE v.workflow_id = ?1 ORDER BY v.version DESC, v.id DESC
     `).bind(workflowId).all<Record<string, unknown>>(),
     db.prepare(`
-      SELECT id, name, input_json AS inputJson, expected_json AS expectedJson,
+      SELECT id, name, revision, input_json AS inputJson, expected_json AS expectedJson,
         failure_injection_json AS failureInjectionJson, updated_at AS updatedAt
       FROM workflow_fixtures WHERE workflow_id = ?1 ORDER BY name, id
     `).bind(workflowId).all<Record<string, unknown>>(),
@@ -337,6 +342,13 @@ export async function validateWorkflowDraft(
   if (!draft) throw new ApiError(404, "workflow_not_found", "The workflow does not exist.");
   const graph = parseWorkflowGraph(parsedJson(draft.graph_json, null));
   const validation = validateWorkflowGraph(graph, authorityMode);
+  for (const dependency of validation.dependencies) {
+    if (!await dependencyAvailable(db, dependency)) {
+      validation.errors.push({ code: "workflow_dependency_unavailable", message: `Select a published ${dependency.type} for ${dependency.key}. Version “${dependency.versionId}” is unavailable.`, path: dependency.key });
+    }
+  }
+  validation.errors.push(...await workflowNoticeInputIssues(db, graph));
+  validation.valid = validation.errors.length === 0;
   const validationJson = canonicalJson(validation);
   await db.prepare(`
     UPDATE workflow_drafts SET validation_json = ?2, validation_digest = ?3,
@@ -350,7 +362,7 @@ export async function validateWorkflowDraft(
 
 export async function listWorkflowFixtures(db: D1Database, workflowId: string): Promise<Record<string, unknown>[]> {
   const rows = await db.prepare(`
-    SELECT id, name, input_json AS inputJson, component_results_json AS componentResultsJson,
+    SELECT id, name, revision, input_json AS inputJson, component_results_json AS componentResultsJson,
       human_responses_json AS humanResponsesJson, expected_json AS expectedJson,
       failure_injection_json AS failureInjectionJson, created_by AS createdBy,
       created_at AS createdAt, updated_at AS updatedAt
@@ -371,6 +383,12 @@ export async function listWorkflowFixtures(db: D1Database, workflowId: string):
   }));
 }
 
+function normalizedFixtureName(value: string): string {
+  const name = value.trim();
+  if (name.length < 2 || name.length > 120 || /[\u0000-\u001f\u007f]/u.test(name)) throw new ApiError(400, "workflow_fixture_name_invalid", "Use an example name between 2 and 120 characters, without control characters.");
+  return name;
+}
+
 export async function createWorkflowFixture(
   db: D1Database,
   workflowId: string,
@@ -390,7 +408,7 @@ export async function createWorkflowFixture(
   if (!await db.prepare(`SELECT id FROM workflow_definitions WHERE id = ?1 AND status != 'archived'`).bind(workflowId).first()) {
     throw new ApiError(404, "workflow_not_found", "The workflow does not exist.");
   }
-  if (!/^[A-Za-z0-9][A-Za-z0-9 _.-]{1,119}$/u.test(input.name)) throw new ApiError(400, "workflow_fixture_name_invalid", "Fixture name must contain 2 to 120 safe characters.");
+  input = { ...input, name: normalizedFixtureName(input.name) };
   if (await db.prepare(`SELECT id FROM workflow_fixtures WHERE workflow_id = ?1 AND name = ?2`).bind(workflowId, input.name).first()) {
     throw new ApiError(409, "workflow_fixture_exists", "A fixture with this name already exists.");
   }
@@ -432,6 +450,7 @@ export async function updateWorkflowFixture(
   workflowId: string,
   fixtureId: string,
   input: {
+    expectedRevision: number;
     name: string;
     input: JsonObject;
     componentResults: JsonObject;
@@ -444,31 +463,36 @@ export async function updateWorkflowFixture(
 ): Promise<{ fixtureId: string; idempotentReplay: boolean }> {
   const replay = await mutationReplay(db, idempotencyKey, "workflow.fixture.update", session.actor.id);
   if (replay) return { fixtureId: String(replay.fixtureId), idempotentReplay: true };
-  if (!/^[A-Za-z0-9][A-Za-z0-9 _.-]{1,119}$/u.test(input.name)) throw new ApiError(400, "workflow_fixture_name_invalid", "Fixture name must contain 2 to 120 safe characters.");
-  const fixture = await db.prepare(`SELECT id FROM workflow_fixtures WHERE id = ?1 AND workflow_id = ?2 LIMIT 1`)
-    .bind(fixtureId, workflowId).first();
+  input = { ...input, name: normalizedFixtureName(input.name) };
+  const fixture = await db.prepare(`SELECT id, revision FROM workflow_fixtures WHERE id = ?1 AND workflow_id = ?2 LIMIT 1`)
+    .bind(fixtureId, workflowId).first<{ id: string; revision: number }>();
   if (!fixture) throw new ApiError(404, "workflow_fixture_not_found", "The workflow fixture does not exist.");
+  if (fixture.revision !== input.expectedRevision) throw new ApiError(409, "workflow_fixture_revision_conflict", "This example changed after you opened it. Reload the saved example before editing again.");
+  if (await db.prepare(`SELECT id FROM workflow_fixtures WHERE workflow_id = ?1 AND name = ?2 AND id != ?3`).bind(workflowId, input.name, fixtureId).first()) throw new ApiError(409, "workflow_fixture_exists", "An example with this name already exists.");
   const timestamp = now();
   const response = { fixtureId };
-  await db.batch([
+  try { await db.batch([
     db.prepare(`
       UPDATE workflow_fixtures SET name = ?3, input_json = ?4,
         component_results_json = ?5, human_responses_json = ?6,
-        expected_json = ?7, failure_injection_json = ?8, updated_at = ?9
-      WHERE id = ?1 AND workflow_id = ?2
+        expected_json = ?7, failure_injection_json = ?8, updated_at = ?9, revision = revision + 1
+      WHERE id = ?1 AND workflow_id = ?2 AND revision = ?10
     `).bind(
       fixtureId, workflowId, input.name, canonicalJson(input.input),
       canonicalJson(input.componentResults), canonicalJson(input.humanResponses),
-      canonicalJson(input.expected), canonicalJson(input.failureInjection), timestamp,
+      canonicalJson(input.expected), canonicalJson(input.failureInjection), timestamp, input.expectedRevision,
     ),
-    db.prepare(`INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at) VALUES (?1, 'workflow.fixture.update', ?2, ?3, ?4, ?5)`)
-      .bind(idempotencyKey, session.actor.id, fixtureId, canonicalJson(response), timestamp),
+    db.prepare(`INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at) VALUES (?1, 'workflow.fixture.update', ?2, (SELECT id FROM workflow_fixtures WHERE id = ?3 AND revision = ?6 AND changes() = 1), ?4, ?5)`)
+      .bind(idempotencyKey, session.actor.id, fixtureId, canonicalJson(response), timestamp, input.expectedRevision + 1),
     auditStatement(db, {
       idempotencyKey: `workflow-fixture-update:${idempotencyKey}`,
       action: "workflow.fixture_updated", session, targetType: "workflow_fixture",
       targetId: fixtureId, details: { workflowId, name: input.name }, createdAt: timestamp,
     }),
-  ]);
+  ]); } catch (error) {
+    if (String(error).includes("configuration_mutations.target_id")) throw new ApiError(409, "workflow_fixture_revision_conflict", "This example changed while it was being saved. Reload the saved example before editing again.");
+    throw error;
+  }
   return { fixtureId, idempotentReplay: false };
 }
 
@@ -509,12 +533,12 @@ export async function runWorkflowFixtureTest(
     db.prepare(`SELECT graph_json AS graphJson, graph_digest AS graphDigest FROM workflow_drafts WHERE workflow_id = ?1 LIMIT 1`)
       .bind(workflowId).first<{ graphJson: string; graphDigest: string }>(),
     db.prepare(`
-      SELECT input_json AS inputJson, component_results_json AS componentResultsJson,
+      SELECT revision, name, input_json AS inputJson, component_results_json AS componentResultsJson,
         human_responses_json AS humanResponsesJson, expected_json AS expectedJson,
         failure_injection_json AS failureInjectionJson
       FROM workflow_fixtures WHERE id = ?1 AND workflow_id = ?2 LIMIT 1
     `).bind(fixtureId, workflowId).first<{
-      inputJson: string; componentResultsJson: string; humanResponsesJson: string;
+      revision: number; name: string; inputJson: string; componentResultsJson: string; humanResponsesJson: string;
       expectedJson: string; failureInjectionJson: string;
     }>(),
   ]);
@@ -528,7 +552,9 @@ export async function runWorkflowFixtureTest(
     failureInjection: parsedJson(fixture.failureInjectionJson, {}),
   });
   const expected = parsedJson<JsonObject>(fixture.expectedJson, {});
-  const passed = simulation.status === "passed" && simulationMatchesExpected(simulation, expected);
+  const hasExpectation = !graph.playbook || (typeof expected.terminal_code === "string" && graph.nodes.some(node => node.kind === "end" && node.config.terminal_code === expected.terminal_code));
+  const simulationError = simulation.error ?? (!hasExpectation ? { code: "example_expected_outcome_required" } : null);
+  const passed = hasExpectation && simulation.status === "passed" && simulationMatchesExpected(simulation, expected);
   const status = passed ? "passed" : "failed";
   const testRunId = crypto.randomUUID();
   const timestamp = now();
@@ -536,22 +562,45 @@ export async function runWorkflowFixtureTest(
     status,
     terminalCode: simulation.terminalCode,
     steps: simulation.steps,
-    expectedMatched: passed,
+    expectedMatched: hasExpectation && simulationMatchesExpected(simulation, expected),
+    expected,
+    fixtureSnapshot: {
+      name: fixture.name, revision: fixture.revision,
+      input: parsedJson(fixture.inputJson, {}),
+      component_results: parsedJson(fixture.componentResultsJson, {}),
+      human_responses: parsedJson(fixture.humanResponsesJson, {}),
+      expected,
+      failure_injection: parsedJson(fixture.failureInjectionJson, {}),
+    },
+    error: simulationError,
     resultDigest: `sha256:${await sha256(simulation.canonicalResult)}`,
   };
   await db.prepare(`
     INSERT INTO workflow_test_runs (
       id, workflow_id, fixture_id, graph_digest, mode, status,
-      result_json, error_json, started_by, started_at, finished_at
-    ) VALUES (?1, ?2, ?3, ?4, 'simulation', ?5, ?6, ?7, ?8, ?9, ?9)
+      result_json, error_json, started_by, started_at, finished_at, fixture_revision
+    ) VALUES (?1, ?2, ?3, ?4, 'simulation', ?5, ?6, ?7, ?8, ?9, ?9, ?10)
   `).bind(
     testRunId, workflowId, fixtureId, draft.graphDigest, status,
-    canonicalJson(result), simulation.error ? canonicalJson(simulation.error) : null,
-    session.actor.id, timestamp,
+    canonicalJson(result), simulationError ? canonicalJson(simulationError) : null,
+    session.actor.id, timestamp, fixture.revision,
   ).run();
   return { testRunId, status, graphDigest: draft.graphDigest, result };
 }
 
+export async function listWorkflowTestRuns(db: D1Database, workflowId: string): Promise<Record<string, unknown>[]> {
+  const rows = await db.prepare(`
+    SELECT t.id AS testRunId, t.fixture_id AS fixtureId, t.fixture_revision AS fixtureRevision,
+      t.graph_digest AS graphDigest, t.status, t.finished_at AS finishedAt, t.result_json AS resultJson
+    FROM workflow_test_runs t WHERE t.workflow_id = ?1
+      AND t.id = (SELECT latest.id FROM workflow_test_runs latest
+        WHERE latest.workflow_id = ?1 AND latest.fixture_id = t.fixture_id
+        ORDER BY latest.rowid DESC LIMIT 1)
+    ORDER BY t.finished_at DESC, t.id DESC
+  `).bind(workflowId).all<Record<string, unknown>>();
+  return rows.results.map(({ resultJson, ...row }) => ({ ...row, result: parsedJson(String(resultJson ?? ""), {}) }));
+}
+
 export async function loadWorkflowTestRun(
   db: D1Database,
   workflowId: string,
@@ -559,7 +608,7 @@ export async function loadWorkflowTestRun(
 ): Promise<Record<string, unknown> | null> {
   const row = await db.prepare(`
     SELECT id, workflow_id AS workflowId, workflow_version_id AS workflowVersionId,
-      fixture_id AS fixtureId, graph_digest AS graphDigest, mode, status,
+      fixture_id AS fixtureId, fixture_revision AS fixtureRevision, graph_digest AS graphDigest, mode, status,
       result_json AS resultJson, error_json AS errorJson, started_by AS startedBy,
       started_at AS startedAt, finished_at AS finishedAt
     FROM workflow_test_runs WHERE id = ?1 AND workflow_id = ?2 LIMIT 1
@@ -624,6 +673,7 @@ export async function diffWorkflowVersion(
     againstId = prior?.id;
   }
   const against = againstId ? await loadWorkflowVersion(db, workflowId, againstId) : null;
+  if (againstId && !against) throw new ApiError(404, "workflow_version_not_found", "The comparison version does not belong to this playbook.");
   const targetGraph = target.graph as WorkflowGraphV1;
   const againstGraph = against?.graph as WorkflowGraphV1 | undefined;
   const targetNodes = new Map((targetGraph?.nodes ?? []).map((node) => [node.id, canonicalJson(node)]));
@@ -637,6 +687,8 @@ export async function diffWorkflowVersion(
     againstVersionId: against?.id ?? null,
     graphDigestChanged: target.graphDigest !== against?.graphDigest,
     nodes: { added, removed, changed },
+    guide: Object.keys(targetGraph?.playbook ?? {}).filter(key => canonicalJson((targetGraph.playbook as unknown as Record<string, unknown>)[key]) !== canonicalJson((againstGraph?.playbook as unknown as Record<string, unknown> | undefined)?.[key] ?? null)),
+    edgesChanged: canonicalJson(targetGraph.edges) !== canonicalJson(againstGraph?.edges ?? []),
     authorityMode: { from: against?.authorityMode ?? null, to: target.authorityMode },
     dependencies: { from: against?.dependencyManifest ?? [], to: target.dependencyManifest ?? [] },
   };
@@ -705,6 +757,23 @@ async function requireDependencies(db: D1Database, dependencies: WorkflowDepende
   if (missing.length) throw new ApiError(409, "workflow_dependency_unavailable", "The workflow references unpublished, paused, retired, missing, or incompatible dependencies.", { dependencies: missing });
 }
 
+export async function workflowNoticeInputIssues(db: D1Database, graph: WorkflowGraphV1) {
+  const issues: { code: string; message: string; path: string }[] = [];
+  for (const node of graph.nodes.filter(node => node.kind === "send_message" && node.config.audience !== "internal")) {
+    const template = await db.prepare(`SELECT body_template AS body, audience FROM message_template_versions WHERE id = ?1 AND published_at IS NOT NULL`)
+      .bind(String(node.config.template_version_id ?? "")).first<{ body: string; audience: string }>();
+    if (!template || template.audience !== node.config.audience) {
+      issues.push({ code: "notice_template_audience_mismatch", message: `${node.name}: choose a published template for this audience.`, path: node.id });
+      continue;
+    }
+    const names = noticeTemplateVariables(template.body);
+    const missing = names.filter(name => node.inputMapping[name] === undefined || node.inputMapping[name] === "" || (typeof node.inputMapping[name] === "object" && node.inputMapping[name] !== null && !Array.isArray(node.inputMapping[name]) && (node.inputMapping[name] as JsonObject).$literal === ""));
+    const extra = Object.keys(node.inputMapping).filter(name => name !== "body" && !names.includes(name));
+    if (missing.length || extra.length) issues.push({ code: "notice_inputs_required", message: `${node.name}: ${missing.length ? `provide notice content for ${missing.join(", ")}.` : `remove unused notice inputs ${extra.join(", ")}.`}`, path: node.id });
+  }
+  return issues;
+}
+
 async function persistArtifact(
   db: D1Database,
   bucket: R2Bucket,
@@ -783,9 +852,33 @@ export async function publishWorkflowDraft(
   if (!testRun || testRun.status !== "passed" || testRun.graphDigest !== graphDigest) {
     throw new ApiError(409, "workflow_tests_required", "A passing server-recorded fixture test for this exact draft is required before publication.");
   }
+  const suiteEvidence: string[] = [];
+  const exampleRecords: { test_run_id: string; name: string; revision: number }[] = [];
+  if (graph.playbook) {
+    const suite = await db.prepare(`
+      SELECT f.id, f.name, f.revision, t.id AS testRunId, t.status
+      FROM workflow_fixtures f LEFT JOIN workflow_test_runs t ON t.id = (
+        SELECT latest.id FROM workflow_test_runs latest
+        WHERE latest.fixture_id = f.id AND latest.workflow_id = ?1
+          AND latest.graph_digest = ?2 AND latest.fixture_revision = f.revision
+        ORDER BY latest.rowid DESC LIMIT 1
+      ) WHERE f.workflow_id = ?1 ORDER BY f.name
+    `).bind(workflowId, graphDigest).all<{ id: string; name: string; revision: number; testRunId: string | null; status: string | null }>();
+    const missing = suite.results.filter(example => example.status !== "passed" || !example.testRunId);
+    if (!suite.results.length || missing.length) throw new ApiError(409, "playbook_examples_required", "Every saved example must pass against this exact playbook draft before publication.", { examples: missing.map(example => ({ id: example.id, name: example.name })) });
+    suiteEvidence.push(...suite.results.map(example => example.testRunId!));
+    exampleRecords.push(...suite.results.map(example => ({ test_run_id: example.testRunId!, name: example.name, revision: example.revision })));
+  }
   const validation = validateWorkflowGraph(graph, input.authorityMode);
   if (!validation.valid) throw new ApiError(400, "workflow_validation_failed", "The workflow draft has publication errors.", { errors: validation.errors, warnings: validation.warnings });
   await requireDependencies(db, validation.dependencies);
+  const noticeIssues = await workflowNoticeInputIssues(db, graph);
+  if (noticeIssues.length) throw new ApiError(409, "notice_inputs_required", "Review participant notice content before publishing.", { errors: noticeIssues });
+  for(const node of graph.nodes.filter(candidate=>candidate.config.investigator===true)) {
+    const approved=await db.prepare(`SELECT v.id FROM agent_versions v JOIN model_alias_versions m ON m.id=v.model_alias_version_id JOIN model_aliases a ON a.id=m.alias_id JOIN prompt_versions p ON p.id=v.prompt_version_id
+      WHERE v.id=?1 AND m.provider='workers_ai' AND m.model LIKE '@cf/%' AND m.retired_at IS NULL AND a.status='active' AND p.status='published'`).bind(String(node.config.agent_version_id)).first();
+    if(!approved)throw new ApiError(409,"investigation_model_adapter_unavailable","Choose an active investigator with a published prompt and an approved Workers AI model. Other providers need an explicit investigator adapter.");
+  }
   const compiled = await compileWorkflowGraph(graph, input.authorityMode, compatibilityDate);
   const artifactId = await persistArtifact(db, bucket, compiled);
   const latest = await db.prepare(`SELECT COALESCE(MAX(version), 0) AS version FROM workflow_versions WHERE workflow_id = ?1`)
@@ -799,13 +892,13 @@ export async function publishWorkflowDraft(
       INSERT INTO workflow_versions (
         id, workflow_id, version, graph_json, graph_digest, input_schema_json,
         output_schema_json, authority_mode, dependency_manifest_json, capability_manifest_json,
-        artifact_id, compiler_version, test_evidence_json, published_by, published_at
-      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, '{"type":"object"}', ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14)
+        artifact_id, compiler_version, test_evidence_json, published_by, published_at, source_draft_revision
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, '{"type":"object"}', ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15)
     `).bind(
       versionId, workflowId, version, canonicalWorkflowGraph(graph), compiled.graphDigest,
       canonicalJson(graph.inputSchema), input.authorityMode, canonicalJson(compiled.dependencyManifest),
       canonicalJson(compiled.capabilityManifest), artifactId, compiled.compilerVersion,
-      canonicalJson({ test_run_id: testRun.id, passed: true, graph_digest: testRun.graphDigest }), session.actor.id, publishedAt,
+      canonicalJson({ test_run_id: testRun.id, ...(suiteEvidence.length ? { example_test_run_ids: suiteEvidence, examples: exampleRecords } : {}), passed: true, graph_digest: testRun.graphDigest }), session.actor.id, publishedAt, workflow.revision,
     ),
     db.prepare(`UPDATE workflow_definitions SET active_version_id = ?2, updated_at = ?3 WHERE id = ?1 AND status = 'active'`)
       .bind(workflowId, versionId, publishedAt),
@@ -834,7 +927,12 @@ export async function publishWorkflowDraft(
       ) VALUES (?1, ?2, ?3, ?4)
     `).bind(versionId, dependency.type, dependency.key, dependency.versionId));
   }
-  await db.batch(statements);
+  try { await db.batch(statements); } catch (error) {
+    if (String(error).includes("workflow_publication_conflict")) throw new ApiError(409, "workflow_revision_conflict", "The draft changed during publication. Reload it and test the latest changes.");
+    if (String(error).includes("playbook_publication_evidence_changed")) throw new ApiError(409, "playbook_examples_required", "The saved examples or their results changed during publication. Run the examples again.");
+    if (String(error).includes("workflow_versions.workflow_id, workflow_versions.version")) throw new ApiError(409, "workflow_publication_conflict", "Another author published a version at the same time. Reload the version history.");
+    throw error;
+  }
   return { ...response, idempotentReplay: false };
 }
 
@@ -859,7 +957,7 @@ export async function loadQueueWorkflowPins(db: D1Database, queueId: string): Pr
 export async function pinQueueWorkflow(
   db: D1Database,
   queueId: string,
-  input: { workflowVersionId: string; mode: "shadow" | "primary"; rollbackOfPinId?: string },
+  input: { workflowVersionId: string; mode: "shadow" | "primary"; rollbackOfPinId?: string; expectedPinId?: string | null },
   session: OperatorSession,
   idempotencyKey: string,
 ): Promise<{ pinId: string; workflowVersionId: string; mode: string; idempotentReplay: boolean }> {
@@ -885,6 +983,8 @@ export async function pinQueueWorkflow(
   const current = await db.prepare(`
     SELECT id FROM queue_workflow_pins WHERE queue_id = ?1 AND mode = ?2 AND deactivated_at IS NULL LIMIT 1
   `).bind(queueId, input.mode).first<{ id: string }>();
+  if (input.expectedPinId !== undefined && input.expectedPinId !== (current?.id ?? null)) throw new ApiError(409, "workflow_pin_conflict", "This queue activation changed. Reload the active version before trying again.");
+  if (input.rollbackOfPinId && input.rollbackOfPinId !== current?.id) throw new ApiError(409, "workflow_pin_conflict", "The activation being replaced is no longer current.");
   const pinId = crypto.randomUUID();
   const activatedAt = now();
   const response = { pinId, workflowVersionId: input.workflowVersionId, mode: input.mode };
@@ -911,6 +1011,9 @@ export async function pinQueueWorkflow(
       createdAt: activatedAt,
     }),
   );
-  await db.batch(statements);
+  try { await db.batch(statements); } catch (error) {
+    if (String(error).includes("queue_workflow_pins.queue_id, queue_workflow_pins.mode")) throw new ApiError(409, "workflow_pin_conflict", "This queue activation changed while saving. Reload the active version before trying again.");
+    throw error;
+  }
   return { ...response, idempotentReplay: false };
 }

package/template/src/workflow-runs.ts

@@ -3,6 +3,8 @@ import { sha256 } from "./report-crypto";
 import { ApiError } from "./report-http";
 import type { OperatorSession, WorkflowDispatchJob } from "./report-types";
 import { startDynamicWorkflow } from "./workflow-dynamic-runtime";
+import { canRequeueUnavailableWorkflowDispatch } from "./workflow-loader-code";
+import { workflowRunEventType } from "./workflow-event-transport";
 import type { JsonObject } from "./workflow-platform-types";
 
 interface MutationRow {
@@ -392,7 +394,7 @@ export async function processWorkflowDispatchJob(
     if (dispatch.operation === "event") {
       if (!dispatch.instanceId || !dispatch.eventType || !dispatch.eventPayloadJson) throw new Error("workflow_event_dispatch_not_ready");
       const instance = await env.WORKFLOWS.get(dispatch.instanceId);
-      await instance.sendEvent({ type: dispatch.eventType, payload: parsedJson(dispatch.eventPayloadJson, {}) });
+      await instance.sendEvent({ type: await workflowRunEventType(env.DB, dispatch.runId, dispatch.eventType), payload: parsedJson(dispatch.eventPayloadJson, {}) });
       const deliveredAt = now();
       await env.DB.batch([
         env.DB.prepare(`
@@ -428,13 +430,21 @@ export async function processWorkflowDispatchJob(
   } catch (error) {
     const delaySeconds = Math.min(900, 5 * (2 ** Math.min(dispatch.attemptCount, 7)));
     const timestamp = now();
+    const errorMessage = error instanceof Error ? error.message.slice(0, 200) : "workflow_dispatch_failed";
+    console.error(JSON.stringify({
+      message: "workflow dispatch attempt failed",
+      runId: dispatch.runId,
+      outboxId: dispatch.outboxId,
+      attemptCount: dispatch.attemptCount,
+      error: errorMessage,
+    }));
     await env.DB.prepare(`
       UPDATE workflow_dispatch_outbox SET state = CASE WHEN attempt_count >= 8 THEN 'dead_letter' ELSE 'failed' END,
         lease_expires_at = NULL, available_at = ?2, last_error_code = ?3, updated_at = ?4
       WHERE id = ?1 AND state = 'leased'
     `).bind(
       dispatch.outboxId, new Date(Date.now() + delaySeconds * 1_000).toISOString(),
-      error instanceof Error ? error.message.slice(0, 200) : "workflow_dispatch_failed", timestamp,
+      errorMessage, timestamp,
     ).run();
     if (dispatch.attemptCount >= 8) {
       await env.DB.prepare(`
@@ -450,7 +460,7 @@ export async function processWorkflowDispatchJob(
 
 export async function listWorkflowRuns(
   db: D1Database,
-  input: { reportId?: string; state?: string; allowedQueueIds?: string[] | null; limit: number },
+  input: { reportId?: string; workflowId?: string; state?: string; allowedQueueIds?: string[] | null; limit: number },
 ): Promise<Record<string, unknown>[]> {
   const rows = await db.prepare(`
     SELECT r.id, r.report_id AS reportId, r.appeal_id AS appealId,
@@ -458,9 +468,12 @@ export async function listWorkflowRuns(
       r.queue_id AS queueId, r.run_kind AS runKind, r.authority_mode AS authorityMode,
       r.state, r.cloudflare_instance_id AS cloudflareInstanceId,
       r.current_node_id AS currentNodeId, r.error_code AS errorCode,
+      (SELECT json_extract(step.value, '$.name') FROM json_each(v.graph_json, '$.nodes') step
+        WHERE json_extract(step.value, '$.id') = r.current_node_id LIMIT 1) AS currentNodeName,
       r.started_at AS startedAt, r.waiting_at AS waitingAt,
       r.finished_at AS finishedAt, r.created_at AS createdAt, r.updated_at AS updatedAt,
       w.workflow_key AS workflowKey, w.name AS workflowName, v.version,
+      (SELECT public_reference FROM reports WHERE id = r.report_id) AS publicReference,
       (SELECT COUNT(*) FROM workflow_step_runs s WHERE s.run_id = r.id) AS stepCount,
       (SELECT COUNT(*) FROM human_tasks t WHERE t.run_id = r.id AND t.state IN ('open','claimed')) AS openTaskCount
     FROM workflow_runs r
@@ -468,11 +481,12 @@ export async function listWorkflowRuns(
     JOIN workflow_definitions w ON w.id = v.workflow_id
     WHERE (?1 IS NULL OR r.report_id = ?1) AND (?2 IS NULL OR r.state = ?2)
       AND (?3 = 1 OR r.queue_id IN (SELECT value FROM json_each(?4)))
+    AND (?6 IS NULL OR w.id = ?6)
     ORDER BY r.created_at DESC, r.id DESC LIMIT ?5
   `).bind(
     input.reportId ?? null, input.state ?? null,
     input.allowedQueueIds === null || input.allowedQueueIds === undefined ? 1 : 0,
-    canonicalJson(input.allowedQueueIds ?? []), Math.max(1, Math.min(input.limit, 100)),
+    canonicalJson(input.allowedQueueIds ?? []), Math.max(1, Math.min(input.limit, 100)), input.workflowId ?? null,
   ).all<Record<string, unknown>>();
   return rows.results;
 }
@@ -535,7 +549,7 @@ export async function sendWorkflowEvent(
   if (!run.cloudflare_instance_id) return { eventId, idempotentReplay: false, delivered: false };
   try {
     const instance = await env.WORKFLOWS.get(run.cloudflare_instance_id);
-    await instance.sendEvent({ type: input.eventType, payload: input.payload });
+    await instance.sendEvent({ type: await workflowRunEventType(env.DB, runId, input.eventType), payload: input.payload });
     const deliveredAt = now();
     await env.DB.batch([
       env.DB.prepare(`UPDATE workflow_event_inbox SET delivered_at = ?2, delivery_attempts = delivery_attempts + 1 WHERE id = ?1`).bind(eventId, deliveredAt),
@@ -592,8 +606,8 @@ export async function reconcileWorkflowRun(
       idempotentReplay: true,
     };
   }
-  const run = await env.DB.prepare(`SELECT id, state, cloudflare_instance_id AS instanceId FROM workflow_runs WHERE id = ?1 LIMIT 1`)
-    .bind(runId).first<{ id: string; state: string; instanceId: string | null }>();
+  const run = await env.DB.prepare(`SELECT id, state, cloudflare_instance_id AS instanceId, error_code AS errorCode FROM workflow_runs WHERE id = ?1 LIMIT 1`)
+    .bind(runId).first<{ id: string; state: string; instanceId: string | null; errorCode: string | null }>();
   if (!run) throw new ApiError(404, "workflow_run_not_found", "The workflow run does not exist.");
   const timestamp = now();
   let state = run.state;
@@ -618,14 +632,48 @@ export async function reconcileWorkflowRun(
       }
     }
   } else {
-    let status: InstanceStatus;
+    let status: InstanceStatus | null = null;
     try {
       status = await (await env.WORKFLOWS.get(run.instanceId)).status();
     } catch {
-      throw new ApiError(503, "workflow_platform_status_unavailable", "The Workflow platform status is temporarily unavailable.");
+      const dispatchFailure = run.state === "repair_required"
+        ? await env.DB.prepare(`
+            SELECT o.id AS outboxId,
+              (SELECT COUNT(*) FROM workflow_step_runs s WHERE s.run_id = ?1) AS stepCount
+            FROM workflow_dispatch_outbox o
+            WHERE o.run_id = ?1 AND o.operation = 'start'
+              AND o.state IN ('failed','dead_letter','leased')
+            ORDER BY o.updated_at DESC LIMIT 1
+          `).bind(runId).first<{ outboxId: string; stepCount: number }>()
+        : null;
+      if (!dispatchFailure || !canRequeueUnavailableWorkflowDispatch({
+        state: run.state,
+        errorCode: run.errorCode,
+        stepCount: dispatchFailure.stepCount,
+      })) {
+        throw new ApiError(503, "workflow_platform_status_unavailable", "The Workflow platform status is temporarily unavailable.");
+      }
+      const reset = await env.DB.prepare(`
+        UPDATE workflow_dispatch_outbox SET state = 'pending', attempt_count = 0,
+          available_at = ?2, lease_expires_at = NULL, last_error_code = NULL, updated_at = ?2
+        WHERE id = ?1 AND state IN ('failed','dead_letter','leased')
+      `).bind(dispatchFailure.outboxId, timestamp).run();
+      if (reset.meta.changes !== 1) {
+        throw new ApiError(503, "workflow_platform_status_unavailable", "The Workflow platform status is temporarily unavailable.");
+      }
+      state = "dispatch_pending";
+      repairApplied = true;
+      statements.push(
+        env.DB.prepare(`
+          UPDATE workflow_runs SET state = 'dispatch_pending', cloudflare_instance_id = NULL,
+            error_code = NULL, error_summary = NULL, updated_at = ?2, revision = revision + 1
+          WHERE id = ?1 AND state = 'repair_required'
+        `).bind(runId, timestamp),
+      );
     }
-    platformState = status.status;
-    const mapped = status.status === "complete" ? "succeeded"
+    platformState = status?.status ?? null;
+    const mapped = !status ? null
+      : status.status === "complete" ? "succeeded"
       : status.status === "errored" ? "failed"
         : status.status === "terminated" ? "terminated"
           : status.status === "waiting" || status.status === "waitingForPause" ? "waiting"
@@ -642,7 +690,7 @@ export async function reconcileWorkflowRun(
             waiting_at = CASE WHEN ?2 = 'waiting' THEN COALESCE(waiting_at, ?4) ELSE NULL END,
             finished_at = CASE WHEN ?2 IN ('succeeded','failed','terminated') THEN COALESCE(finished_at, ?4) ELSE finished_at END,
             updated_at = ?4, revision = revision + 1 WHERE id = ?1
-        `).bind(runId, mapped, status.error?.message?.slice(0, 500) ?? null, timestamp),
+        `).bind(runId, mapped, status?.error?.message?.slice(0, 500) ?? null, timestamp),
       );
     } else if (mapped && terminal && mapped !== run.state) {
       const incidentKey = `workflow-state-mismatch:${runId}:${run.state}:${mapped}`;
@@ -657,7 +705,7 @@ export async function reconcileWorkflowRun(
           last_seen_at = excluded.last_seen_at, metadata_json = excluded.metadata_json
       `).bind(
         crypto.randomUUID(), incidentKey, "A terminal D1 workflow state differs from the Cloudflare Workflow instance state.",
-        runId, timestamp, canonicalJson({ d1State: run.state, platformState: mapped, platformRawState: status.status }),
+        runId, timestamp, canonicalJson({ d1State: run.state, platformState: mapped, platformRawState: status?.status ?? null }),
       ));
     }
   }

package/template/src/workflow-simulator.ts

@@ -1,5 +1,5 @@
 import { canonicalJson } from "./audit";
-import { evaluateInputMapping, evaluateWorkflowExpression } from "./workflow-expressions";
+import { evaluateInputMapping, evaluateWorkflowExpression, validateJsonSchemaValue } from "./workflow-expressions";
 import type { JsonObject, JsonValue, WorkflowGraphV1, WorkflowNodeV1 } from "./workflow-platform-types";
 
 export interface WorkflowSimulationFixture {
@@ -63,7 +63,8 @@ export function simulateWorkflow(graph: WorkflowGraphV1, fixture: WorkflowSimula
   const outgoing = new Map(graph.nodes.map((node) => [node.id, graph.edges.filter((edge) => edge.from.nodeId === node.id)]));
   const steps: WorkflowSimulationStep[] = [];
   const stepOutputs: JsonObject = {};
-  const baseContext: JsonObject = { input: fixture.input, steps: stepOutputs, findings: {} };
+  // Fixtures use the same named context and wait payload shape as the runtime.
+  const baseContext: JsonObject = { ...fixture.input, input: fixture.input, run: fixture.input.run ?? { id: "fixture-run" }, steps: stepOutputs, findings: fixture.input.findings ?? {} };
 
   const record = (node: WorkflowNodeV1, branchKey: string, state: WorkflowSimulationStep["state"], port: string, output: JsonObject) => {
     const entry = { nodeId: node.id, kind: node.kind, branchKey, state, port, output };
@@ -134,7 +135,9 @@ export function simulateWorkflow(graph: WorkflowGraphV1, fixture: WorkflowSimula
           state = "timed_out";
           last = { port: "timeout", status: "timed_out" };
         } else {
-          last = { port: "completed", status: "received", response };
+          const errors = validateJsonSchemaValue(response, object(node.config.response_schema));
+          if (errors.length) throw new SimulationFailure("simulation_human_response_invalid", node.id);
+          last = { port: "completed", status: "received", event: { task_id: `fixture:${node.id}`, response_id: `fixture-response:${node.id}`, response } };
         }
       } else if (node.kind === "wait_for_event") {
         const response = fixture.humanResponses[node.id];
@@ -150,7 +153,7 @@ export function simulateWorkflow(graph: WorkflowGraphV1, fixture: WorkflowSimula
         last = { port: "sent", simulated: true, audience: node.config.audience ?? null };
       } else if (node.kind === "decision") {
         state = "simulated";
-        last = { port: "recorded", simulated: true, decision: mapped };
+        last = { port: "recorded", simulated: true, decisionId: `fixture:${node.id}`, decisionCode: mapped.decision_code ?? null, decision: mapped };
       } else if (node.kind === "action") {
         state = "simulated";
         last = { port: "applied", simulated: true, action: mapped };