create-safest-tools 0.2.0

package/template/src/workflow-repository.ts

@@ -0,0 +1,916 @@
+import { canonicalJson } from "./audit";
+import { sha256 } from "./report-crypto";
+import { ApiError } from "./report-http";
+import type { OperatorSession } from "./report-types";
+import { compileWorkflowGraph } from "./workflow-compiler";
+import type {
+  WorkflowAuthorityMode,
+  WorkflowDefinitionInput,
+  WorkflowDependencyReference,
+  WorkflowGraphV1,
+  WorkflowPublishInput,
+  WorkflowValidationResult,
+} from "./workflow-platform-types";
+import {
+  canonicalWorkflowGraph,
+  parseWorkflowGraph,
+  validateWorkflowGraph,
+} from "./workflow-platform-validation";
+import { simulateWorkflow, simulationMatchesExpected } from "./workflow-simulator";
+import type { JsonObject } from "./workflow-platform-types";
+
+interface WorkflowListRow {
+  id: string;
+  key: string;
+  name: string;
+  description: string;
+  purpose: string;
+  status: string;
+  activeVersionId: string | null;
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+  draftId: string | null;
+  draftRevision: number | null;
+  validationStatus: string | null;
+  validationJson: string | null;
+  version: number | null;
+  authorityMode: string | null;
+  publishedAt: string | null;
+  activePinCount: number;
+}
+
+interface DraftRow {
+  id: string;
+  workflow_id: string;
+  graph_json: string;
+  graph_digest: string;
+  revision: number;
+  validation_json: string;
+  validation_status: "unvalidated" | "valid" | "invalid";
+  updated_at: string;
+}
+
+interface MutationRow {
+  action: string;
+  actor_id: string;
+  response_json: string;
+}
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function parsedJson<T>(value: string | null, fallback: T): T {
+  if (!value) return fallback;
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+function workflowFromRow(row: WorkflowListRow): Record<string, unknown> {
+  return {
+    id: row.id,
+    key: row.key,
+    name: row.name,
+    description: row.description,
+    purpose: row.purpose,
+    status: row.status,
+    activeVersionId: row.activeVersionId,
+    createdBy: row.createdBy,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+    draft: row.draftId ? {
+      id: row.draftId,
+      revision: row.draftRevision,
+      validationStatus: row.validationStatus,
+      validation: parsedJson(row.validationJson, { valid: false, errors: [], warnings: [] }),
+    } : null,
+    activeVersion: row.activeVersionId ? {
+      id: row.activeVersionId,
+      version: row.version,
+      authorityMode: row.authorityMode,
+      publishedAt: row.publishedAt,
+    } : null,
+    activePinCount: Number(row.activePinCount),
+  };
+}
+
+async function mutationReplay(
+  db: D1Database,
+  idempotencyKey: string,
+  action: string,
+  actorId: string,
+): Promise<Record<string, unknown> | null> {
+  const row = await db.prepare(`
+    SELECT action, actor_id, response_json FROM configuration_mutations WHERE idempotency_key = ?1 LIMIT 1
+  `).bind(idempotencyKey).first<MutationRow>();
+  if (!row) return null;
+  if (row.action !== action || row.actor_id !== actorId) {
+    throw new ApiError(409, "idempotency_key_reused", "This Idempotency-Key was already used for another workflow mutation.");
+  }
+  return parsedJson<Record<string, unknown>>(row.response_json, {});
+}
+
+function auditStatement(
+  db: D1Database,
+  input: {
+    idempotencyKey: string;
+    action: string;
+    session: OperatorSession;
+    targetType: string;
+    targetId: string;
+    details: unknown;
+    createdAt: string;
+  },
+): D1PreparedStatement {
+  return db.prepare(`
+    INSERT OR IGNORE INTO audit_events (
+      id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at
+    ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)
+  `).bind(
+    crypto.randomUUID(), input.idempotencyKey, input.action, input.session.actor.type,
+    input.session.actor.id, input.targetType, input.targetId, canonicalJson(input.details), input.createdAt,
+  );
+}
+
+export async function listWorkflowDefinitions(
+  db: D1Database,
+  includeArchived = false,
+): Promise<Record<string, unknown>[]> {
+  const rows = await db.prepare(`
+    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,
+      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,
+      (SELECT COUNT(*) FROM queue_workflow_pins p
+       WHERE p.workflow_version_id = w.active_version_id AND p.deactivated_at IS NULL) AS activePinCount
+    FROM workflow_definitions w
+    LEFT JOIN workflow_drafts d ON d.workflow_id = w.id
+    LEFT JOIN workflow_versions v ON v.id = w.active_version_id
+    WHERE (?1 = 1 OR w.status != 'archived')
+    ORDER BY w.name, w.id
+  `).bind(includeArchived ? 1 : 0).all<WorkflowListRow>();
+  return rows.results.map(workflowFromRow);
+}
+
+export async function loadWorkflowDefinition(
+  db: D1Database,
+  workflowId: string,
+): Promise<Record<string, unknown> | null> {
+  const row = await db.prepare(`
+    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,
+      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,
+      (SELECT COUNT(*) FROM queue_workflow_pins p
+       WHERE p.workflow_version_id = w.active_version_id AND p.deactivated_at IS NULL) AS activePinCount
+    FROM workflow_definitions w
+    LEFT JOIN workflow_drafts d ON d.workflow_id = w.id
+    LEFT JOIN workflow_versions v ON v.id = w.active_version_id
+    WHERE w.id = ?1 LIMIT 1
+  `).bind(workflowId).first<WorkflowListRow>();
+  if (!row) return null;
+  const [draft, versions, fixtures] = await Promise.all([
+    db.prepare(`
+      SELECT id, workflow_id, graph_json, graph_digest, revision, validation_json, validation_status, updated_at
+      FROM workflow_drafts WHERE workflow_id = ?1 LIMIT 1
+    `).bind(workflowId).first<DraftRow>(),
+    db.prepare(`
+      SELECT v.id, v.version, v.graph_digest AS graphDigest, v.authority_mode AS authorityMode,
+        v.dependency_manifest_json AS dependencyManifestJson,
+        v.capability_manifest_json AS capabilityManifestJson,
+        v.artifact_id AS artifactId, v.compiler_version AS compilerVersion,
+        v.test_evidence_json AS testEvidenceJson, v.published_by AS publishedBy,
+        v.published_at AS publishedAt, v.retired_at AS retiredAt,
+        a.bundle_digest AS bundleDigest, a.status AS artifactStatus
+      FROM workflow_versions v JOIN workflow_artifacts a ON a.id = v.artifact_id
+      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,
+        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>>(),
+  ]);
+  return {
+    ...workflowFromRow(row),
+    draft: draft ? {
+      id: draft.id,
+      revision: draft.revision,
+      graphDigest: draft.graph_digest,
+      graph: parsedJson(draft.graph_json, null),
+      validationStatus: draft.validation_status,
+      validation: parsedJson(draft.validation_json, { valid: false, errors: [], warnings: [] }),
+      updatedAt: draft.updated_at,
+    } : null,
+    versions: versions.results.map((version) => ({
+      ...version,
+      dependencyManifest: parsedJson(String(version.dependencyManifestJson ?? ""), []),
+      capabilityManifest: parsedJson(String(version.capabilityManifestJson ?? ""), {}),
+      testEvidence: parsedJson(String(version.testEvidenceJson ?? ""), {}),
+      dependencyManifestJson: undefined,
+      capabilityManifestJson: undefined,
+      testEvidenceJson: undefined,
+    })),
+    fixtures: fixtures.results.map((fixture) => ({
+      ...fixture,
+      input: parsedJson(String(fixture.inputJson ?? ""), {}),
+      expected: parsedJson(String(fixture.expectedJson ?? ""), {}),
+      failureInjection: parsedJson(String(fixture.failureInjectionJson ?? ""), {}),
+      inputJson: undefined,
+      expectedJson: undefined,
+      failureInjectionJson: undefined,
+    })),
+  };
+}
+
+export async function createWorkflowDefinition(
+  db: D1Database,
+  input: WorkflowDefinitionInput,
+  graph: WorkflowGraphV1,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ workflowId: string; draftId: string; revision: number; idempotentReplay: boolean }> {
+  const replay = await mutationReplay(db, idempotencyKey, "workflow.create", session.actor.id);
+  if (replay) return {
+    workflowId: String(replay.workflowId), draftId: String(replay.draftId), revision: Number(replay.revision), idempotentReplay: true,
+  };
+  if (graph.purpose !== input.purpose) throw new ApiError(400, "workflow_purpose_mismatch", "The workflow definition and graph purposes must match.");
+  const conflict = await db.prepare(`
+    SELECT id FROM workflow_definitions WHERE installation_id = 'default' AND workflow_key = ?1 LIMIT 1
+  `).bind(input.key).first<{ id: string }>();
+  if (conflict) throw new ApiError(409, "workflow_key_exists", "A workflow with this key already exists.");
+  const workflowId = crypto.randomUUID();
+  const draftId = crypto.randomUUID();
+  const createdAt = now();
+  const graphJson = canonicalWorkflowGraph(graph);
+  const graphDigest = `sha256:${await sha256(graphJson)}`;
+  const validation = validateWorkflowGraph(graph);
+  const response = { workflowId, draftId, revision: 1 };
+  await db.batch([
+    db.prepare(`
+      INSERT INTO workflow_definitions (
+        id, installation_id, workflow_key, name, description, purpose, status,
+        created_by, created_at, updated_at
+      ) VALUES (?1, 'default', ?2, ?3, ?4, ?5, 'active', ?6, ?7, ?7)
+    `).bind(workflowId, input.key, input.name, input.description, input.purpose, session.actor.id, createdAt),
+    db.prepare(`
+      INSERT INTO workflow_drafts (
+        id, workflow_id, graph_json, graph_digest, revision, validation_json,
+        validation_digest, validation_status, created_by, updated_by, created_at, updated_at
+      ) VALUES (?1, ?2, ?3, ?4, 1, ?5, ?6, ?7, ?8, ?8, ?9, ?9)
+    `).bind(
+      draftId, workflowId, graphJson, graphDigest, canonicalJson(validation),
+      `sha256:${await sha256(canonicalJson(validation))}`, validation.valid ? "valid" : "invalid",
+      session.actor.id, createdAt,
+    ),
+    db.prepare(`
+      INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at)
+      VALUES (?1, 'workflow.create', ?2, ?3, ?4, ?5)
+    `).bind(idempotencyKey, session.actor.id, workflowId, canonicalJson(response), createdAt),
+    auditStatement(db, {
+      idempotencyKey: `workflow-create:${idempotencyKey}`, action: "workflow.created", session,
+      targetType: "workflow", targetId: workflowId,
+      details: { key: input.key, purpose: input.purpose, draftId, graphDigest }, createdAt,
+    }),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+export async function replaceWorkflowDraft(
+  db: D1Database,
+  workflowId: string,
+  graph: WorkflowGraphV1,
+  expectedRevision: number,
+  session: OperatorSession,
+): Promise<{ draftId: string; revision: number; graphDigest: string; validation: WorkflowValidationResult }> {
+  const draft = await db.prepare(`
+    SELECT d.id, d.workflow_id, d.graph_json, d.graph_digest, d.revision,
+      d.validation_json, d.validation_status, d.updated_at
+    FROM workflow_drafts d JOIN workflow_definitions w ON w.id = d.workflow_id
+    WHERE d.workflow_id = ?1 AND w.status != 'archived' LIMIT 1
+  `).bind(workflowId).first<DraftRow>();
+  if (!draft) throw new ApiError(404, "workflow_not_found", "The workflow does not exist or is archived.");
+  if (draft.revision !== expectedRevision) throw new ApiError(409, "workflow_revision_conflict", "The workflow draft changed after it was loaded.", {
+    expected_revision: expectedRevision, current_revision: draft.revision,
+  });
+  const purpose = await db.prepare(`SELECT purpose FROM workflow_definitions WHERE id = ?1`).bind(workflowId).first<{ purpose: string }>();
+  if (!purpose || graph.purpose !== purpose.purpose) throw new ApiError(400, "workflow_purpose_mismatch", "The workflow definition and graph purposes must match.");
+  const graphJson = canonicalWorkflowGraph(graph);
+  const graphDigest = `sha256:${await sha256(graphJson)}`;
+  const validation = validateWorkflowGraph(graph);
+  const validationJson = canonicalJson(validation);
+  const updatedAt = now();
+  const revision = draft.revision + 1;
+  const result = await db.prepare(`
+    UPDATE workflow_drafts
+    SET graph_json = ?2, graph_digest = ?3, revision = ?4,
+      validation_json = ?5, validation_digest = ?6, validation_status = ?7,
+      updated_by = ?8, updated_at = ?9
+    WHERE id = ?1 AND revision = ?10
+  `).bind(
+    draft.id, graphJson, graphDigest, revision, validationJson,
+    `sha256:${await sha256(validationJson)}`, validation.valid ? "valid" : "invalid",
+    session.actor.id, updatedAt, expectedRevision,
+  ).run();
+  if (result.meta.changes !== 1) throw new ApiError(409, "workflow_revision_conflict", "The workflow draft changed while it was being saved.");
+  return { draftId: draft.id, revision, graphDigest, validation };
+}
+
+export async function validateWorkflowDraft(
+  db: D1Database,
+  workflowId: string,
+  authorityMode: WorkflowAuthorityMode,
+): Promise<{ revision: number; graphDigest: string; validation: WorkflowValidationResult }> {
+  const draft = await db.prepare(`
+    SELECT id, workflow_id, graph_json, graph_digest, revision,
+      validation_json, validation_status, updated_at
+    FROM workflow_drafts WHERE workflow_id = ?1 LIMIT 1
+  `).bind(workflowId).first<DraftRow>();
+  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);
+  const validationJson = canonicalJson(validation);
+  await db.prepare(`
+    UPDATE workflow_drafts SET validation_json = ?2, validation_digest = ?3,
+      validation_status = ?4, updated_at = ?5 WHERE id = ?1 AND revision = ?6
+  `).bind(
+    draft.id, validationJson, `sha256:${await sha256(validationJson)}`,
+    validation.valid ? "valid" : "invalid", now(), draft.revision,
+  ).run();
+  return { revision: draft.revision, graphDigest: draft.graph_digest, validation };
+}
+
+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,
+      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
+    FROM workflow_fixtures WHERE workflow_id = ?1 ORDER BY name, id
+  `).bind(workflowId).all<Record<string, unknown>>();
+  return rows.results.map((row) => ({
+    ...row,
+    input: parsedJson(String(row.inputJson ?? ""), {}),
+    componentResults: parsedJson(String(row.componentResultsJson ?? ""), {}),
+    humanResponses: parsedJson(String(row.humanResponsesJson ?? ""), {}),
+    expected: parsedJson(String(row.expectedJson ?? ""), {}),
+    failureInjection: parsedJson(String(row.failureInjectionJson ?? ""), {}),
+    inputJson: undefined,
+    componentResultsJson: undefined,
+    humanResponsesJson: undefined,
+    expectedJson: undefined,
+    failureInjectionJson: undefined,
+  }));
+}
+
+export async function createWorkflowFixture(
+  db: D1Database,
+  workflowId: string,
+  input: {
+    name: string;
+    input: JsonObject;
+    componentResults: JsonObject;
+    humanResponses: JsonObject;
+    expected: JsonObject;
+    failureInjection: JsonObject;
+  },
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ fixtureId: string; idempotentReplay: boolean }> {
+  const replay = await mutationReplay(db, idempotencyKey, "workflow.fixture.create", session.actor.id);
+  if (replay) return { fixtureId: String(replay.fixtureId), idempotentReplay: true };
+  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.");
+  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.");
+  }
+  const fixtureId = crypto.randomUUID();
+  const createdAt = now();
+  const response = { fixtureId };
+  await db.batch([
+    db.prepare(`
+      INSERT INTO workflow_fixtures (
+        id, workflow_id, name, input_json, component_results_json,
+        human_responses_json, expected_json, failure_injection_json,
+        created_by, created_at, updated_at
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?10)
+    `).bind(
+      fixtureId, workflowId, input.name, canonicalJson(input.input),
+      canonicalJson(input.componentResults), canonicalJson(input.humanResponses),
+      canonicalJson(input.expected), canonicalJson(input.failureInjection),
+      session.actor.id, createdAt,
+    ),
+    db.prepare(`
+      INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at)
+      VALUES (?1, 'workflow.fixture.create', ?2, ?3, ?4, ?5)
+    `).bind(idempotencyKey, session.actor.id, fixtureId, canonicalJson(response), createdAt),
+    auditStatement(db, {
+      idempotencyKey: `workflow-fixture:${idempotencyKey}`,
+      action: "workflow.fixture_created",
+      session,
+      targetType: "workflow_fixture",
+      targetId: fixtureId,
+      details: { workflowId, name: input.name },
+      createdAt,
+    }),
+  ]);
+  return { fixtureId, idempotentReplay: false };
+}
+
+export async function updateWorkflowFixture(
+  db: D1Database,
+  workflowId: string,
+  fixtureId: string,
+  input: {
+    name: string;
+    input: JsonObject;
+    componentResults: JsonObject;
+    humanResponses: JsonObject;
+    expected: JsonObject;
+    failureInjection: JsonObject;
+  },
+  session: OperatorSession,
+  idempotencyKey: string,
+): 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();
+  if (!fixture) throw new ApiError(404, "workflow_fixture_not_found", "The workflow fixture does not exist.");
+  const timestamp = now();
+  const response = { fixtureId };
+  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
+    `).bind(
+      fixtureId, workflowId, input.name, canonicalJson(input.input),
+      canonicalJson(input.componentResults), canonicalJson(input.humanResponses),
+      canonicalJson(input.expected), canonicalJson(input.failureInjection), timestamp,
+    ),
+    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),
+    auditStatement(db, {
+      idempotencyKey: `workflow-fixture-update:${idempotencyKey}`,
+      action: "workflow.fixture_updated", session, targetType: "workflow_fixture",
+      targetId: fixtureId, details: { workflowId, name: input.name }, createdAt: timestamp,
+    }),
+  ]);
+  return { fixtureId, idempotentReplay: false };
+}
+
+export async function deleteWorkflowFixture(
+  db: D1Database,
+  workflowId: string,
+  fixtureId: string,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ fixtureId: string; deleted: true; idempotentReplay: boolean }> {
+  const replay = await mutationReplay(db, idempotencyKey, "workflow.fixture.delete", session.actor.id);
+  if (replay) return { fixtureId: String(replay.fixtureId), deleted: true, idempotentReplay: true };
+  const fixture = await db.prepare(`SELECT name FROM workflow_fixtures WHERE id = ?1 AND workflow_id = ?2 LIMIT 1`)
+    .bind(fixtureId, workflowId).first<{ name: string }>();
+  if (!fixture) throw new ApiError(404, "workflow_fixture_not_found", "The workflow fixture does not exist.");
+  const timestamp = now();
+  const response = { fixtureId, deleted: true as const };
+  await db.batch([
+    db.prepare(`DELETE FROM workflow_fixtures WHERE id = ?1 AND workflow_id = ?2`).bind(fixtureId, workflowId),
+    db.prepare(`INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at) VALUES (?1, 'workflow.fixture.delete', ?2, ?3, ?4, ?5)`)
+      .bind(idempotencyKey, session.actor.id, fixtureId, canonicalJson(response), timestamp),
+    auditStatement(db, {
+      idempotencyKey: `workflow-fixture-delete:${idempotencyKey}`,
+      action: "workflow.fixture_deleted", session, targetType: "workflow_fixture",
+      targetId: fixtureId, details: { workflowId, name: fixture.name }, createdAt: timestamp,
+    }),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+export async function runWorkflowFixtureTest(
+  db: D1Database,
+  workflowId: string,
+  fixtureId: string,
+  session: OperatorSession,
+): Promise<{ testRunId: string; status: "passed" | "failed"; graphDigest: string; result: Record<string, unknown> }> {
+  const [draft, fixture] = await Promise.all([
+    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,
+        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;
+      expectedJson: string; failureInjectionJson: string;
+    }>(),
+  ]);
+  if (!draft) throw new ApiError(404, "workflow_not_found", "The workflow draft does not exist.");
+  if (!fixture) throw new ApiError(404, "workflow_fixture_not_found", "The workflow fixture does not exist.");
+  const graph = parseWorkflowGraph(parsedJson(draft.graphJson, null));
+  const simulation = simulateWorkflow(graph, {
+    input: parsedJson(fixture.inputJson, {}),
+    componentResults: parsedJson(fixture.componentResultsJson, {}),
+    humanResponses: parsedJson(fixture.humanResponsesJson, {}),
+    failureInjection: parsedJson(fixture.failureInjectionJson, {}),
+  });
+  const expected = parsedJson<JsonObject>(fixture.expectedJson, {});
+  const passed = simulation.status === "passed" && simulationMatchesExpected(simulation, expected);
+  const status = passed ? "passed" : "failed";
+  const testRunId = crypto.randomUUID();
+  const timestamp = now();
+  const result = {
+    status,
+    terminalCode: simulation.terminalCode,
+    steps: simulation.steps,
+    expectedMatched: passed,
+    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)
+  `).bind(
+    testRunId, workflowId, fixtureId, draft.graphDigest, status,
+    canonicalJson(result), simulation.error ? canonicalJson(simulation.error) : null,
+    session.actor.id, timestamp,
+  ).run();
+  return { testRunId, status, graphDigest: draft.graphDigest, result };
+}
+
+export async function loadWorkflowTestRun(
+  db: D1Database,
+  workflowId: string,
+  testRunId: string,
+): 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,
+      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
+  `).bind(testRunId, workflowId).first<Record<string, unknown>>();
+  if (!row) return null;
+  return {
+    ...row,
+    result: parsedJson(String(row.resultJson ?? ""), null),
+    error: parsedJson(String(row.errorJson ?? ""), null),
+    resultJson: undefined,
+    errorJson: undefined,
+  };
+}
+
+export async function loadWorkflowVersion(
+  db: D1Database,
+  workflowId: string,
+  versionId: string,
+): Promise<Record<string, unknown> | null> {
+  const row = await db.prepare(`
+    SELECT v.id, v.workflow_id AS workflowId, v.version, v.graph_json AS graphJson,
+      v.graph_digest AS graphDigest, v.input_schema_json AS inputSchemaJson,
+      v.output_schema_json AS outputSchemaJson, v.authority_mode AS authorityMode,
+      v.dependency_manifest_json AS dependencyManifestJson,
+      v.capability_manifest_json AS capabilityManifestJson,
+      v.artifact_id AS artifactId, v.compiler_version AS compilerVersion,
+      v.test_evidence_json AS testEvidenceJson, v.published_by AS publishedBy,
+      v.published_at AS publishedAt, v.retired_at AS retiredAt,
+      a.bundle_digest AS bundleDigest, a.manifest_digest AS manifestDigest,
+      a.status AS artifactStatus, a.compatibility_date AS compatibilityDate
+    FROM workflow_versions v JOIN workflow_artifacts a ON a.id = v.artifact_id
+    WHERE v.id = ?1 AND v.workflow_id = ?2 LIMIT 1
+  `).bind(versionId, workflowId).first<Record<string, unknown>>();
+  if (!row) return null;
+  return {
+    ...row,
+    graph: parsedJson(String(row.graphJson ?? ""), null),
+    inputSchema: parsedJson(String(row.inputSchemaJson ?? ""), {}),
+    outputSchema: parsedJson(String(row.outputSchemaJson ?? ""), {}),
+    dependencyManifest: parsedJson(String(row.dependencyManifestJson ?? ""), []),
+    capabilityManifest: parsedJson(String(row.capabilityManifestJson ?? ""), {}),
+    testEvidence: parsedJson(String(row.testEvidenceJson ?? ""), {}),
+    graphJson: undefined, inputSchemaJson: undefined, outputSchemaJson: undefined,
+    dependencyManifestJson: undefined, capabilityManifestJson: undefined, testEvidenceJson: undefined,
+  };
+}
+
+export async function diffWorkflowVersion(
+  db: D1Database,
+  workflowId: string,
+  versionId: string,
+  againstVersionId?: string,
+): Promise<Record<string, unknown>> {
+  const target = await loadWorkflowVersion(db, workflowId, versionId);
+  if (!target) throw new ApiError(404, "workflow_version_not_found", "The workflow version does not exist.");
+  let againstId = againstVersionId;
+  if (!againstId) {
+    const prior = await db.prepare(`
+      SELECT id FROM workflow_versions WHERE workflow_id = ?1 AND version < ?2
+      ORDER BY version DESC, id DESC LIMIT 1
+    `).bind(workflowId, Number(target.version)).first<{ id: string }>();
+    againstId = prior?.id;
+  }
+  const against = againstId ? await loadWorkflowVersion(db, workflowId, againstId) : null;
+  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)]));
+  const againstNodes = new Map((againstGraph?.nodes ?? []).map((node) => [node.id, canonicalJson(node)]));
+  const added = [...targetNodes.keys()].filter((id) => !againstNodes.has(id));
+  const removed = [...againstNodes.keys()].filter((id) => !targetNodes.has(id));
+  const changed = [...targetNodes.keys()].filter((id) => againstNodes.has(id) && againstNodes.get(id) !== targetNodes.get(id));
+  return {
+    workflowId,
+    versionId,
+    againstVersionId: against?.id ?? null,
+    graphDigestChanged: target.graphDigest !== against?.graphDigest,
+    nodes: { added, removed, changed },
+    authorityMode: { from: against?.authorityMode ?? null, to: target.authorityMode },
+    dependencies: { from: against?.dependencyManifest ?? [], to: target.dependencyManifest ?? [] },
+  };
+}
+
+export async function retireWorkflowVersion(
+  db: D1Database,
+  workflowId: string,
+  versionId: string,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ workflowId: string; versionId: string; retiredAt: string; idempotentReplay: boolean }> {
+  const replay = await mutationReplay(db, idempotencyKey, "workflow.version.retire", session.actor.id);
+  if (replay) return {
+    workflowId: String(replay.workflowId), versionId: String(replay.versionId),
+    retiredAt: String(replay.retiredAt), idempotentReplay: true,
+  };
+  const version = await db.prepare(`
+    SELECT v.id, v.retired_at AS retiredAt, w.active_version_id AS activeVersionId
+    FROM workflow_versions v JOIN workflow_definitions w ON w.id = v.workflow_id
+    WHERE v.id = ?1 AND v.workflow_id = ?2 LIMIT 1
+  `).bind(versionId, workflowId).first<{ id: string; retiredAt: string | null; activeVersionId: string | null }>();
+  if (!version) throw new ApiError(404, "workflow_version_not_found", "The workflow version does not exist.");
+  if (version.retiredAt) return { workflowId, versionId, retiredAt: version.retiredAt, idempotentReplay: true };
+  if (version.activeVersionId === versionId) throw new ApiError(409, "workflow_active_version_cannot_retire", "Publish or select a replacement before retiring the active version.");
+  const dependent = await db.prepare(`
+    SELECT
+      EXISTS(SELECT 1 FROM queue_workflow_pins WHERE workflow_version_id = ?1 AND deactivated_at IS NULL) AS pinned,
+      EXISTS(SELECT 1 FROM workflow_runs WHERE workflow_version_id = ?1 AND state IN ('created','dispatch_pending','queued','running','waiting','paused','repair_required')) AS running
+  `).bind(versionId).first<{ pinned: number; running: number }>();
+  if (dependent?.pinned || dependent?.running) throw new ApiError(409, "workflow_version_in_use", "Active pins or runs still depend on this workflow version.");
+  const retiredAt = now();
+  const response = { workflowId, versionId, retiredAt };
+  await db.batch([
+    db.prepare(`UPDATE workflow_versions SET retired_at = ?2 WHERE id = ?1 AND retired_at IS NULL`).bind(versionId, retiredAt),
+    db.prepare(`INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at) VALUES (?1, 'workflow.version.retire', ?2, ?3, ?4, ?5)`)
+      .bind(idempotencyKey, session.actor.id, versionId, canonicalJson(response), retiredAt),
+    auditStatement(db, {
+      idempotencyKey: `workflow-version-retire:${idempotencyKey}`,
+      action: "workflow.version_retired", session, targetType: "workflow_version",
+      targetId: versionId, details: { workflowId }, createdAt: retiredAt,
+    }),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+async function dependencyAvailable(db: D1Database, dependency: WorkflowDependencyReference): Promise<boolean> {
+  const queryByType: Record<WorkflowDependencyReference["type"], string> = {
+    component: `SELECT v.id FROM component_versions v JOIN component_definitions d ON d.id = v.definition_id WHERE v.id = ?1 AND v.published_at IS NOT NULL AND v.retired_at IS NULL AND d.status IN ('active','deprecated')`,
+    connection: `SELECT v.id FROM connection_versions v JOIN connection_definitions d ON d.id = v.connection_id WHERE v.id = ?1 AND v.published_at IS NOT NULL AND v.retired_at IS NULL AND d.status = 'active'`,
+    policy: `SELECT id FROM policy_versions WHERE id = ?1 AND published_at IS NOT NULL`,
+    template: `SELECT id FROM message_template_versions WHERE id = ?1 AND published_at IS NOT NULL`,
+    model_alias: `SELECT v.id FROM model_alias_versions v JOIN model_aliases a ON a.id = v.alias_id WHERE v.id = ?1 AND v.published_at IS NOT NULL AND v.retired_at IS NULL AND a.status = 'active'`,
+    agent: `SELECT v.id FROM agent_versions v JOIN agent_definitions a ON a.id = v.agent_id WHERE v.id = ?1 AND v.published_at IS NOT NULL AND v.retired_at IS NULL AND a.status = 'active'`,
+    workflow: `SELECT v.id FROM workflow_versions v JOIN workflow_artifacts a ON a.id = v.artifact_id WHERE v.id = ?1 AND v.retired_at IS NULL AND a.status = 'ready'`,
+  };
+  return Boolean(await db.prepare(queryByType[dependency.type]).bind(dependency.versionId).first());
+}
+
+async function requireDependencies(db: D1Database, dependencies: WorkflowDependencyReference[]): Promise<void> {
+  const availability = await Promise.all(dependencies.map(async (dependency) => ({
+    dependency,
+    available: await dependencyAvailable(db, dependency),
+  })));
+  const missing = availability.filter((entry) => !entry.available).map((entry) => entry.dependency);
+  if (missing.length) throw new ApiError(409, "workflow_dependency_unavailable", "The workflow references unpublished, paused, retired, missing, or incompatible dependencies.", { dependencies: missing });
+}
+
+async function persistArtifact(
+  db: D1Database,
+  bucket: R2Bucket,
+  compiled: Awaited<ReturnType<typeof compileWorkflowGraph>>,
+): Promise<string> {
+  const existing = await db.prepare(`
+    SELECT id, status FROM workflow_artifacts
+    WHERE installation_id = 'default' AND bundle_digest = ?1 LIMIT 1
+  `).bind(compiled.bundleDigest).first<{ id: string; status: string }>();
+  if (existing?.status === "ready") return existing.id;
+  if (existing) throw new ApiError(409, "workflow_artifact_unavailable", "An artifact with this digest exists but is not ready.");
+  const artifactId = crypto.randomUUID();
+  const objectKey = `workflow-artifacts/${compiled.bundleDigest.slice("sha256:".length, "sha256:".length + 2)}/${compiled.bundleDigest.slice("sha256:".length)}.mjs`;
+  await bucket.put(objectKey, compiled.source, {
+    httpMetadata: { contentType: "text/javascript; charset=utf-8" },
+    customMetadata: {
+      compiler: compiled.compilerVersion,
+      graphDigest: compiled.graphDigest,
+      bundleDigest: compiled.bundleDigest,
+    },
+  });
+  const readBack = await bucket.get(objectKey);
+  if (!readBack) throw new ApiError(503, "workflow_artifact_write_failed", "The compiled workflow artifact could not be read back.");
+  const readBackSource = await readBack.text();
+  if (`sha256:${await sha256(readBackSource)}` !== compiled.bundleDigest) {
+    throw new ApiError(503, "workflow_artifact_digest_mismatch", "The compiled workflow artifact failed digest verification.");
+  }
+  const createdAt = now();
+  await db.prepare(`
+    INSERT INTO workflow_artifacts (
+      id, installation_id, compiler_version, compatibility_date, graph_digest,
+      source_digest, bundle_digest, manifest_digest, bundle_r2_key, bundle_size_bytes,
+      capability_manifest_json, compiler_warnings_json, status, created_at, verified_at
+    ) VALUES (?1, 'default', ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, 'ready', ?12, ?12)
+  `).bind(
+    artifactId, compiled.compilerVersion, compiled.compatibilityDate, compiled.graphDigest,
+    compiled.sourceDigest, compiled.bundleDigest, compiled.manifestDigest, objectKey,
+    new TextEncoder().encode(compiled.source).byteLength,
+    canonicalJson(compiled.capabilityManifest), canonicalJson(compiled.warnings), createdAt,
+  ).run();
+  return artifactId;
+}
+
+export async function publishWorkflowDraft(
+  db: D1Database,
+  bucket: R2Bucket,
+  workflowId: string,
+  input: WorkflowPublishInput,
+  session: OperatorSession,
+  idempotencyKey: string,
+  compatibilityDate: string,
+): Promise<{ workflowId: string; versionId: string; version: number; artifactId: string; bundleDigest: string; idempotentReplay: boolean }> {
+  const replay = await mutationReplay(db, idempotencyKey, "workflow.publish", session.actor.id);
+  if (replay) return {
+    workflowId: String(replay.workflowId), versionId: String(replay.versionId), version: Number(replay.version),
+    artifactId: String(replay.artifactId), bundleDigest: String(replay.bundleDigest), idempotentReplay: true,
+  };
+  const workflow = await db.prepare(`
+    SELECT w.status, w.purpose, d.id AS draft_id, d.graph_json, d.revision
+    FROM workflow_definitions w JOIN workflow_drafts d ON d.workflow_id = w.id
+    WHERE w.id = ?1 LIMIT 1
+  `).bind(workflowId).first<{ status: string; purpose: string; draft_id: string; graph_json: string; revision: number }>();
+  if (!workflow) throw new ApiError(404, "workflow_not_found", "The workflow does not exist.");
+  if (workflow.status !== "active") throw new ApiError(409, "workflow_not_active", "Only an active workflow can be published.");
+  if (workflow.revision !== input.expectedRevision) throw new ApiError(409, "workflow_revision_conflict", "The workflow draft changed after validation.", {
+    expected_revision: input.expectedRevision, current_revision: workflow.revision,
+  });
+  const graph = parseWorkflowGraph(parsedJson(workflow.graph_json, null));
+  if (graph.purpose !== workflow.purpose) throw new ApiError(409, "workflow_purpose_mismatch", "The stored workflow definition and graph purposes do not match.");
+  const graphDigest = `sha256:${await sha256(canonicalWorkflowGraph(graph))}`;
+  const testRunId = typeof input.testEvidence.test_run_id === "string" ? input.testEvidence.test_run_id : null;
+  const testRun = testRunId ? await db.prepare(`
+    SELECT id, graph_digest AS graphDigest, status FROM workflow_test_runs
+    WHERE id = ?1 AND workflow_id = ?2 AND mode = 'simulation' LIMIT 1
+  `).bind(testRunId, workflowId).first<{ id: string; graphDigest: string; status: string }>() : null;
+  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 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 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`)
+    .bind(workflowId).first<{ version: number }>();
+  const version = Number(latest?.version ?? 0) + 1;
+  const versionId = crypto.randomUUID();
+  const publishedAt = now();
+  const response = { workflowId, versionId, version, artifactId, bundleDigest: compiled.bundleDigest };
+  const statements: D1PreparedStatement[] = [
+    db.prepare(`
+      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)
+    `).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,
+    ),
+    db.prepare(`UPDATE workflow_definitions SET active_version_id = ?2, updated_at = ?3 WHERE id = ?1 AND status = 'active'`)
+      .bind(workflowId, versionId, publishedAt),
+    db.prepare(`
+      UPDATE workflow_drafts SET validation_json = ?2, validation_digest = ?3,
+        validation_status = 'valid', updated_at = ?4 WHERE id = ?1 AND revision = ?5
+    `).bind(
+      workflow.draft_id, canonicalJson(validation), `sha256:${await sha256(canonicalJson(validation))}`,
+      publishedAt, workflow.revision,
+    ),
+    db.prepare(`
+      INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at)
+      VALUES (?1, 'workflow.publish', ?2, ?3, ?4, ?5)
+    `).bind(idempotencyKey, session.actor.id, versionId, canonicalJson(response), publishedAt),
+    auditStatement(db, {
+      idempotencyKey: `workflow-publish:${idempotencyKey}`, action: "workflow.version_published", session,
+      targetType: "workflow", targetId: workflowId,
+      details: { versionId, version, artifactId, bundleDigest: compiled.bundleDigest, authorityMode: input.authorityMode },
+      createdAt: publishedAt,
+    }),
+  ];
+  for (const dependency of compiled.dependencyManifest) {
+    statements.push(db.prepare(`
+      INSERT INTO workflow_dependencies (
+        workflow_version_id, dependency_type, dependency_key, dependency_version_id
+      ) VALUES (?1, ?2, ?3, ?4)
+    `).bind(versionId, dependency.type, dependency.key, dependency.versionId));
+  }
+  await db.batch(statements);
+  return { ...response, idempotentReplay: false };
+}
+
+export async function loadQueueWorkflowPins(db: D1Database, queueId: string): Promise<Record<string, unknown>[]> {
+  const rows = await db.prepare(`
+    SELECT p.id, p.queue_id AS queueId, p.queue_version_id AS queueVersionId,
+      p.workflow_version_id AS workflowVersionId, p.mode, p.rollback_of_pin_id AS rollbackOfPinId,
+      p.activated_by AS activatedBy, p.activated_at AS activatedAt,
+      p.deactivated_at AS deactivatedAt, w.workflow_key AS workflowKey,
+      w.name AS workflowName, v.version, v.authority_mode AS authorityMode,
+      a.bundle_digest AS bundleDigest, a.status AS artifactStatus
+    FROM queue_workflow_pins p
+    JOIN workflow_versions v ON v.id = p.workflow_version_id
+    JOIN workflow_definitions w ON w.id = v.workflow_id
+    JOIN workflow_artifacts a ON a.id = v.artifact_id
+    WHERE p.queue_id = ?1
+    ORDER BY (p.deactivated_at IS NULL) DESC, p.activated_at DESC, p.id DESC
+  `).bind(queueId).all<Record<string, unknown>>();
+  return rows.results;
+}
+
+export async function pinQueueWorkflow(
+  db: D1Database,
+  queueId: string,
+  input: { workflowVersionId: string; mode: "shadow" | "primary"; rollbackOfPinId?: string },
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ pinId: string; workflowVersionId: string; mode: string; idempotentReplay: boolean }> {
+  const replay = await mutationReplay(db, idempotencyKey, "queue.workflow_pin", session.actor.id);
+  if (replay) return {
+    pinId: String(replay.pinId), workflowVersionId: String(replay.workflowVersionId), mode: String(replay.mode), idempotentReplay: true,
+  };
+  const target = await db.prepare(`
+    SELECT q.id AS queue_id, q.active_version_id AS queue_version_id,
+      v.id AS workflow_version_id, v.authority_mode, a.status AS artifact_status
+    FROM queue_definitions q CROSS JOIN workflow_versions v
+    JOIN workflow_artifacts a ON a.id = v.artifact_id
+    WHERE q.id = ?1 AND q.status = 'active' AND v.id = ?2 AND v.retired_at IS NULL
+    LIMIT 1
+  `).bind(queueId, input.workflowVersionId).first<{
+    queue_id: string; queue_version_id: string | null; workflow_version_id: string;
+    authority_mode: WorkflowAuthorityMode; artifact_status: string;
+  }>();
+  if (!target) throw new ApiError(404, "queue_or_workflow_not_found", "The active queue or workflow version does not exist.");
+  if (target.artifact_status !== "ready") throw new ApiError(409, "workflow_artifact_not_ready", "The workflow artifact is not verified and ready.");
+  if (input.mode === "primary" && target.authority_mode === "shadow") throw new ApiError(409, "shadow_workflow_not_primary", "A shadow-authority workflow cannot be pinned as primary.");
+  if (input.mode === "shadow" && target.authority_mode !== "shadow") throw new ApiError(409, "shadow_pin_authority_required", "A shadow pin must reference a version compiled with shadow authority.");
+  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 }>();
+  const pinId = crypto.randomUUID();
+  const activatedAt = now();
+  const response = { pinId, workflowVersionId: input.workflowVersionId, mode: input.mode };
+  const statements: D1PreparedStatement[] = [];
+  if (current) statements.push(db.prepare(`UPDATE queue_workflow_pins SET deactivated_at = ?2 WHERE id = ?1 AND deactivated_at IS NULL`).bind(current.id, activatedAt));
+  statements.push(
+    db.prepare(`
+      INSERT INTO queue_workflow_pins (
+        id, queue_id, queue_version_id, workflow_version_id, mode,
+        rollback_of_pin_id, activated_by, activated_at
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)
+    `).bind(
+      pinId, queueId, target.queue_version_id, input.workflowVersionId, input.mode,
+      input.rollbackOfPinId ?? current?.id ?? null, session.actor.id, activatedAt,
+    ),
+    db.prepare(`
+      INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at)
+      VALUES (?1, 'queue.workflow_pin', ?2, ?3, ?4, ?5)
+    `).bind(idempotencyKey, session.actor.id, pinId, canonicalJson(response), activatedAt),
+    auditStatement(db, {
+      idempotencyKey: `queue-workflow-pin:${idempotencyKey}`, action: "queue.workflow_pinned", session,
+      targetType: "queue", targetId: queueId,
+      details: { pinId, workflowVersionId: input.workflowVersionId, mode: input.mode, priorPinId: current?.id },
+      createdAt: activatedAt,
+    }),
+  );
+  await db.batch(statements);
+  return { ...response, idempotentReplay: false };
+}