create-safest-tools 0.2.0

package/template/src/workflow-actions.ts

@@ -0,0 +1,782 @@
+import { canonicalJson } from "./audit";
+import { BudgetControlError, reserveBudgets, settleBudgets } from "./budget-control";
+import { ConnectionExecutionError, executeConnectionJson } from "./connection-egress";
+import { loadWorkflowExecutionContext } from "./component-executor";
+import { sha256 } from "./report-crypto";
+import { ApiError } from "./report-http";
+import { evaluateInputMapping, validateJsonSchemaValue } from "./workflow-expressions";
+import { WorkflowEffectError } from "./workflow-effects";
+import type { ActionProposalJob, OperatorSession } from "./report-types";
+import type { JsonObject, JsonValue, WorkflowAuthorityMode, WorkflowNodeV1 } from "./workflow-platform-types";
+
+interface ActionContextRow {
+  installationId: string;
+  reportId: string;
+  workflowVersionId: string;
+  policyVersionId: string | null;
+  queueId: string | null;
+  reportState: string;
+  runCreatedAt: string;
+}
+
+interface ActionComponentRow {
+  id: string;
+  definitionStatus: string;
+  effectClass: string;
+  implementationKind: string;
+  implementationReference: string;
+  connectionVersionId: string | null;
+  inputSchemaJson: string;
+  outputSchemaJson: string;
+  approvalPolicyJson: string;
+  retiredAt: string | null;
+}
+
+interface ProposalRow {
+  id: string;
+  installationId: string;
+  reportId: string;
+  runId: string;
+  stepRunId: string;
+  actionCode: string;
+  targetJson: string;
+  payloadJson: string;
+  preconditionsJson: string;
+  payloadDigest: string;
+  componentVersionId: string;
+  authorityMode: "assist" | "bounded_auto";
+  approvalPolicyJson: string;
+  state: string;
+  operationId: string;
+  workflowVersionId: string;
+  policyVersionId: string | null;
+  queueId: string | null;
+  deliveryAttemptCount: number;
+  deliveryTerminal: number;
+  lastErrorCode: string | null;
+}
+
+const ACTION_MAX_ATTEMPTS = 8;
+
+export class RetryableActionProposalError extends Error {
+  constructor(readonly delaySeconds: number) {
+    super("The action proposal delivery is scheduled for retry.");
+    this.name = "RetryableActionProposalError";
+  }
+}
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function object(value: JsonValue | undefined, code: string): JsonObject {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new WorkflowEffectError(code);
+  return value;
+}
+
+function parsedObject(value: string): JsonObject {
+  try {
+    const parsed = JSON.parse(value) as JsonValue;
+    return object(parsed, "action_stored_json_invalid");
+  } catch {
+    return {};
+  }
+}
+
+function deliveryPending(proposalId: string, payloadDigest: string, expiresAt: string): Record<string, unknown> {
+  return {
+    status: "delivery_pending",
+    proposalId,
+    payloadDigest,
+    eventType: `action.${proposalId}.delivery-resolved`,
+    timeoutMs: Math.max(1_000, Date.parse(expiresAt) - Date.now()),
+  };
+}
+
+function actionJob(proposalId: string, runId: string): ActionProposalJob {
+  return { version: 1, type: "apply_action_proposal", jobId: `action-proposal:${proposalId}`, proposalId, runId };
+}
+
+async function actionContext(db: D1Database, runId: string): Promise<ActionContextRow> {
+  const row = await db.prepare(`
+    SELECT wr.installation_id AS installationId, wr.report_id AS reportId,
+      wr.workflow_version_id AS workflowVersionId, r.policy_version_id AS policyVersionId,
+      r.queue_id AS queueId, r.state AS reportState, wr.created_at AS runCreatedAt
+    FROM workflow_runs wr JOIN reports r ON r.id = wr.report_id
+    WHERE wr.id = ?1 LIMIT 1
+  `).bind(runId).first<ActionContextRow>();
+  if (!row) throw new WorkflowEffectError("action_context_missing");
+  return row;
+}
+
+async function actionComponent(db: D1Database, id: string): Promise<ActionComponentRow> {
+  const row = await db.prepare(`
+    SELECT v.id, d.status AS definitionStatus, d.effect_class AS effectClass,
+      v.implementation_kind AS implementationKind,
+      v.implementation_reference AS implementationReference,
+      v.connection_version_id AS connectionVersionId,
+      v.input_schema_json AS inputSchemaJson, v.output_schema_json AS outputSchemaJson,
+      v.approval_policy_json AS approvalPolicyJson, v.retired_at AS retiredAt
+    FROM component_versions v JOIN component_definitions d ON d.id = v.definition_id
+    WHERE v.id = ?1 LIMIT 1
+  `).bind(id).first<ActionComponentRow>();
+  if (!row || row.retiredAt || row.definitionStatus !== "active" || row.effectClass !== "side_effecting") {
+    throw new WorkflowEffectError("action_component_unavailable");
+  }
+  if (!["webhook", "external_api"].includes(row.implementationKind) || !row.connectionVersionId) {
+    throw new WorkflowEffectError("action_component_implementation_invalid");
+  }
+  return row;
+}
+
+function approvalMode(node: WorkflowNodeV1, component: ActionComponentRow, authorityMode: WorkflowAuthorityMode): "human" | "bounded_auto" {
+  const nodePolicy = object(node.config.approval_policy, "action_approval_policy_invalid");
+  const componentPolicy = parsedObject(component.approvalPolicyJson);
+  const requested = nodePolicy.mode;
+  if (requested !== "human" && requested !== "bounded_auto") throw new WorkflowEffectError("action_approval_policy_invalid");
+  if (componentPolicy.mode !== requested) throw new WorkflowEffectError("action_approval_policy_mismatch");
+  if (requested === "bounded_auto" && authorityMode !== "bounded_auto") throw new WorkflowEffectError("action_authority_insufficient");
+  return requested;
+}
+
+export async function prepareWorkflowAction(
+  env: Env,
+  input: {
+    runId: string;
+    node: WorkflowNodeV1;
+    branchKey: string;
+    stepRunId: string;
+    authorityMode: WorkflowAuthorityMode;
+  },
+): Promise<Record<string, unknown>> {
+  if (input.authorityMode === "shadow" || input.authorityMode === "off") throw new WorkflowEffectError("action_authority_insufficient");
+  const componentVersionId = typeof input.node.config.component_version_id === "string" ? input.node.config.component_version_id : null;
+  const actionCode = typeof input.node.config.action_code === "string" ? input.node.config.action_code : null;
+  if (!componentVersionId || !actionCode) throw new WorkflowEffectError("action_configuration_invalid");
+  const [context, component, executionContext] = await Promise.all([
+    actionContext(env.DB, input.runId),
+    actionComponent(env.DB, componentVersionId),
+    loadWorkflowExecutionContext(env, input.runId, input.branchKey),
+  ]);
+  const mapped = evaluateInputMapping(input.node.inputMapping, executionContext.context);
+  if (typeof mapped.idempotency_key !== "string" || mapped.idempotency_key.length < 8 || mapped.idempotency_key.length > 200) {
+    throw new WorkflowEffectError("action_idempotency_key_invalid");
+  }
+  const target = object(mapped.target, "action_target_invalid");
+  const payload = object(mapped.payload, "action_payload_invalid");
+  const preconditions = object(mapped.preconditions ?? {}, "action_preconditions_invalid");
+  const inputErrors = validateJsonSchemaValue(payload, parsedObject(component.inputSchemaJson));
+  if (inputErrors.length) throw new WorkflowEffectError("action_payload_schema_invalid");
+  const proposalId = `${input.stepRunId}:proposal`;
+  const operationId = `action:${input.runId}:${input.node.id}:${input.branchKey || "main"}:${mapped.idempotency_key}`;
+  const existing = await env.DB.prepare(`
+    SELECT id, state, payload_digest AS payloadDigest,
+      approval_policy_json AS approvalPolicyJson,
+      delivery_terminal AS deliveryTerminal, last_error_code AS lastErrorCode
+    FROM action_proposals WHERE operation_id = ?1 LIMIT 1
+  `).bind(operationId).first<{
+    id: string; state: string; payloadDigest: string; approvalPolicyJson: string;
+    deliveryTerminal: number; lastErrorCode: string | null;
+  }>();
+  const policy = approvalMode(input.node, component, input.authorityMode);
+  const expiresSeconds = Number(input.node.config.expiry_seconds ?? 86_400);
+  if (!Number.isInteger(expiresSeconds) || expiresSeconds < 60 || expiresSeconds > 2_678_400) throw new WorkflowEffectError("action_expiry_invalid");
+  const expiresAt = new Date(Date.parse(context.runCreatedAt) + expiresSeconds * 1_000).toISOString();
+  const digestMaterial = {
+    schema_version: "1",
+    action_id: proposalId,
+    action_code: actionCode,
+    target,
+    payload,
+    preconditions,
+    component_version_id: componentVersionId,
+    workflow_version_id: context.workflowVersionId,
+    policy_version_id: context.policyVersionId,
+    expires_at: expiresAt,
+    installation_id: context.installationId,
+  };
+  const payloadDigest = `sha256:${await sha256(canonicalJson(digestMaterial))}`;
+  if (existing) {
+    if (existing.payloadDigest !== payloadDigest) throw new WorkflowEffectError("action_operation_payload_changed");
+    if (existing.state === "applied") return { port: "applied", proposalId: existing.id, payloadDigest, idempotentReplay: true };
+    if (existing.state === "rejected") return { port: "rejected", proposalId: existing.id, payloadDigest, idempotentReplay: true };
+    if (existing.state === "cancelled") return { port: "timeout", proposalId: existing.id, payloadDigest, idempotentReplay: true };
+    if (existing.state === "failed" && existing.deliveryTerminal === 1) {
+      return { port: "error", proposalId: existing.id, payloadDigest, errorCode: existing.lastErrorCode ?? "action_delivery_failed", idempotentReplay: true };
+    }
+    if (existing.state === "approval_required") {
+      const task = await env.DB.prepare(`SELECT id, due_at AS dueAt FROM human_tasks WHERE action_proposal_id = ?1 LIMIT 1`).bind(existing.id).first<{ id: string; dueAt: string }>();
+      if (!task) throw new WorkflowEffectError("action_approval_task_missing");
+      return { status: "approval_required", proposalId: existing.id, payloadDigest, eventType: `action.${existing.id}.resolved`, timeoutMs: Math.max(1_000, Date.parse(task.dueAt) - Date.now()), taskId: task.id };
+    }
+    const storedPolicy = parsedObject(existing.approvalPolicyJson);
+    const storedExpiry = typeof storedPolicy.expires_at === "string" ? storedPolicy.expires_at : expiresAt;
+    if (existing.state === "approved") {
+      await env.DB.prepare(`UPDATE action_proposals SET state = 'queued', next_attempt_at = ?2, lease_expires_at = NULL, last_error_code = NULL, delivery_terminal = 0, updated_at = ?2 WHERE id = ?1 AND state = 'approved'`)
+        .bind(existing.id, now()).run();
+    }
+    await env.DELIVERY_JOBS.send(actionJob(existing.id, input.runId), { contentType: "json" }).catch(() => {});
+    return deliveryPending(existing.id, payloadDigest, storedExpiry);
+  }
+  const timestamp = now();
+  const approvalPolicy = { ...object(input.node.config.approval_policy, "action_approval_policy_invalid"), expires_at: expiresAt };
+  const initialState = policy === "human" ? "approval_required" : "queued";
+  const statements: D1PreparedStatement[] = [env.DB.prepare(`
+    INSERT INTO action_proposals (
+      id, installation_id, report_id, run_id, step_run_id, action_code,
+      target_json, payload_json, preconditions_json, payload_digest,
+      component_version_id, authority_mode, approval_policy_json, state,
+      operation_id, created_by_type, created_by_id, next_attempt_at, created_at, updated_at
+    ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15, 'system', ?4, ?17, ?16, ?16)
+  `).bind(
+    proposalId, context.installationId, context.reportId, input.runId, input.stepRunId,
+    actionCode, canonicalJson(target), canonicalJson(payload), canonicalJson(preconditions),
+    payloadDigest, componentVersionId, input.authorityMode, canonicalJson(approvalPolicy),
+    initialState, operationId, timestamp, policy === "human" ? null : timestamp,
+  )];
+  if (policy === "human") {
+    const taskId = `${input.stepRunId}:action-approval-task`;
+    statements.push(env.DB.prepare(`
+      INSERT INTO human_tasks (
+        id, installation_id, report_id, run_id, step_run_id, task_type, state,
+        queue_id, context_json, context_digest, response_schema_json,
+        action_proposal_id, due_at, created_at, updated_at
+      ) VALUES (?1, ?2, ?3, ?4, ?5, 'approval', 'open', ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?12)
+    `).bind(
+      taskId, context.installationId, context.reportId, input.runId, input.stepRunId,
+      context.queueId, canonicalJson({ action_code: actionCode, target, payload, preconditions, payload_digest: payloadDigest }),
+      `sha256:${await sha256(canonicalJson({ action_code: actionCode, target, payload, preconditions, payload_digest: payloadDigest }))}`,
+      canonicalJson({
+        type: "object",
+        properties: { decision: { type: "string", enum: ["approved", "rejected"] }, reason: { type: "string", maxLength: 1_000 } },
+        required: ["decision"],
+        additionalProperties: false,
+      }), proposalId, expiresAt, timestamp,
+    ));
+    await env.DB.batch(statements);
+    return { status: "approval_required", proposalId, payloadDigest, eventType: `action.${proposalId}.resolved`, timeoutMs: expiresSeconds * 1_000, taskId };
+  }
+  await env.DB.batch(statements);
+  await env.DELIVERY_JOBS.send(actionJob(proposalId, input.runId), { contentType: "json" }).catch(() => {});
+  return deliveryPending(proposalId, payloadDigest, expiresAt);
+}
+
+async function loadProposal(db: D1Database, proposalId: string): Promise<ProposalRow> {
+  const proposal = await db.prepare(`
+    SELECT p.id, p.installation_id AS installationId, p.report_id AS reportId,
+      p.run_id AS runId, p.step_run_id AS stepRunId, p.action_code AS actionCode,
+      p.target_json AS targetJson, p.payload_json AS payloadJson,
+      p.preconditions_json AS preconditionsJson, p.payload_digest AS payloadDigest,
+      p.component_version_id AS componentVersionId, p.authority_mode AS authorityMode,
+      p.approval_policy_json AS approvalPolicyJson, p.state, p.operation_id AS operationId,
+      r.workflow_version_id AS workflowVersionId, rp.policy_version_id AS policyVersionId,
+      rp.queue_id AS queueId, p.delivery_attempt_count AS deliveryAttemptCount,
+      p.delivery_terminal AS deliveryTerminal, p.last_error_code AS lastErrorCode
+    FROM action_proposals p JOIN workflow_runs r ON r.id = p.run_id
+    JOIN reports rp ON rp.id = p.report_id WHERE p.id = ?1 LIMIT 1
+  `).bind(proposalId).first<ProposalRow>();
+  if (!proposal) throw new WorkflowEffectError("action_proposal_missing");
+  return proposal;
+}
+
+async function validatePreconditions(db: D1Database, proposal: ProposalRow): Promise<void> {
+  const preconditions = parsedObject(proposal.preconditionsJson);
+  const report = await db.prepare(`
+    SELECT state, queue_id AS queueId,
+      (SELECT id FROM decisions WHERE report_id = reports.id ORDER BY created_at DESC, id DESC LIMIT 1) AS latestDecisionId,
+      (SELECT target_reference FROM report_targets WHERE report_id = reports.id ORDER BY created_at, id LIMIT 1) AS targetReference
+    FROM reports WHERE id = ?1 LIMIT 1
+  `).bind(proposal.reportId).first<{ state: string; queueId: string | null; latestDecisionId: string | null; targetReference: string | null }>();
+  if (!report) throw new WorkflowEffectError("action_report_missing");
+  const checks: [JsonValue | undefined, unknown][] = [
+    [preconditions.report_state, report.state],
+    [preconditions.queue_id, report.queueId],
+    [preconditions.latest_decision_id, report.latestDecisionId],
+    [preconditions.target_reference, report.targetReference],
+  ];
+  if (checks.some(([expected, actual]) => expected !== undefined && expected !== actual)) throw new WorkflowEffectError("action_precondition_changed");
+}
+
+async function emitActionResolution(env: Env, proposal: ProposalRow): Promise<void> {
+  const eventId = `${proposal.id}:delivery-resolution`;
+  const eventType = `action.${proposal.id}.delivery-resolved`;
+  const eventKey = `action-delivery:${proposal.id}`;
+  const payload = {
+    proposal_id: proposal.id,
+    state: proposal.state,
+    payload_digest: proposal.payloadDigest,
+    error_code: proposal.lastErrorCode,
+  };
+  const payloadJson = canonicalJson(payload);
+  const timestamp = now();
+  await env.DB.batch([
+    env.DB.prepare(`
+      INSERT OR IGNORE INTO workflow_event_inbox (
+        id, run_id, event_type, event_key, source_type, source_id,
+        payload_json, payload_digest, received_at
+      ) VALUES (?1, ?2, ?3, ?4, 'system', 'action-delivery-worker', ?5, ?6, ?7)
+    `).bind(eventId, proposal.runId, eventType, eventKey, payloadJson, `sha256:${await sha256(payloadJson)}`, timestamp),
+    env.DB.prepare(`
+      INSERT OR IGNORE INTO workflow_dispatch_outbox (
+        id, run_id, operation, event_inbox_id, operation_key,
+        state, available_at, created_at, updated_at
+      ) VALUES (?1, ?2, 'event', ?1, ?3, 'pending', ?4, ?4, ?4)
+    `).bind(eventId, proposal.runId, `workflow-event:${proposal.runId}:${eventType}:${eventKey}`, timestamp),
+  ]);
+  const run = await env.DB.prepare(`SELECT cloudflare_instance_id AS instanceId FROM workflow_runs WHERE id = ?1 LIMIT 1`)
+    .bind(proposal.runId).first<{ instanceId: string | null }>();
+  if (!run?.instanceId) return;
+  try {
+    await (await env.WORKFLOWS.get(run.instanceId)).sendEvent({ type: eventType, payload });
+    await env.DB.batch([
+      env.DB.prepare(`UPDATE workflow_event_inbox SET delivered_at = ?2, delivery_attempts = delivery_attempts + 1, last_error_code = NULL WHERE id = ?1`).bind(eventId, now()),
+      env.DB.prepare(`UPDATE workflow_dispatch_outbox SET state = 'delivered', last_error_code = NULL, updated_at = ?2 WHERE id = ?1`).bind(eventId, now()),
+    ]);
+  } catch {
+    await env.DB.batch([
+      env.DB.prepare(`UPDATE workflow_event_inbox SET delivery_attempts = delivery_attempts + 1, last_error_code = 'platform_event_send_failed' WHERE id = ?1`).bind(eventId),
+      env.DB.prepare(`UPDATE workflow_dispatch_outbox SET state = 'failed', last_error_code = 'platform_event_send_failed', updated_at = ?2 WHERE id = ?1`).bind(eventId, now()),
+    ]);
+  }
+}
+
+export async function pendingActionProposalJobs(db: D1Database, limit = 50): Promise<ActionProposalJob[]> {
+  const rows = await db.prepare(`
+    SELECT id, run_id AS runId FROM action_proposals
+    WHERE delivery_terminal = 0 AND delivery_attempt_count < ?2
+      AND ((state IN ('queued','failed') AND next_attempt_at <= ?1)
+        OR (state = 'applying' AND lease_expires_at <= ?1))
+    ORDER BY next_attempt_at, id LIMIT ?3
+  `).bind(now(), ACTION_MAX_ATTEMPTS, Math.max(1, Math.min(100, limit))).all<{ id: string; runId: string }>();
+  return rows.results.map((row) => actionJob(row.id, row.runId));
+}
+
+export async function reconcileActionProposalEvents(env: Env, limit = 50): Promise<number> {
+  const rows = await env.DB.prepare(`
+    SELECT p.id FROM action_proposals p
+    WHERE (p.state = 'applied' OR (p.state = 'failed' AND p.delivery_terminal = 1))
+      AND NOT EXISTS (SELECT 1 FROM workflow_event_inbox e WHERE e.id = p.id || ':delivery-resolution')
+    ORDER BY p.updated_at, p.id LIMIT ?1
+  `).bind(Math.max(1, Math.min(100, limit))).all<{ id: string }>();
+  for (const row of rows.results) await emitActionResolution(env, await loadProposal(env.DB, row.id));
+  return rows.results.length;
+}
+
+export async function processActionProposalJob(env: Env, job: ActionProposalJob): Promise<void> {
+  const timestamp = now();
+  const leaseExpiresAt = new Date(Date.now() + 60_000).toISOString();
+  const claimed = await env.DB.prepare(`
+    UPDATE action_proposals SET state = 'applying',
+      delivery_attempt_count = delivery_attempt_count + 1,
+      lease_expires_at = ?3, updated_at = ?2
+    WHERE id = ?1 AND run_id = ?4 AND delivery_terminal = 0
+      AND ((state IN ('queued','failed') AND next_attempt_at <= ?2)
+        OR (state = 'applying' AND lease_expires_at <= ?2))
+    RETURNING id
+  `).bind(job.proposalId, timestamp, leaseExpiresAt, job.runId).first();
+  let proposal = await loadProposal(env.DB, job.proposalId);
+  if (!claimed) {
+    if (proposal.state === "applied" || (proposal.state === "failed" && proposal.deliveryTerminal === 1)) return;
+    throw new RetryableActionProposalError(5);
+  }
+  const approvalPolicy = parsedObject(proposal.approvalPolicyJson);
+  let reservations: Awaited<ReturnType<typeof reserveBudgets>> = [];
+  try {
+    if (typeof approvalPolicy.expires_at !== "string" || approvalPolicy.expires_at <= timestamp) {
+      throw new WorkflowEffectError("action_approval_expired");
+    }
+    await validatePreconditions(env.DB, proposal);
+    const component = await actionComponent(env.DB, proposal.componentVersionId);
+    const reference = /^(?:(GET|POST|PUT|PATCH|DELETE|HEAD)\s+)?(\/[^\s]*)$/u.exec(component.implementationReference.trim());
+    if (!reference || !component.connectionVersionId) throw new WorkflowEffectError("action_component_operation_invalid");
+    reservations = await reserveBudgets(env.DB, {
+      installationId: proposal.installationId,
+      scopes: [
+        { type: "workflow", id: proposal.workflowVersionId },
+        { type: "component", id: proposal.componentVersionId },
+        ...(proposal.queueId ? [{ type: "queue", id: proposal.queueId }] : []),
+      ],
+      metric: "actions", amount: 1, operationType: "action_proposal",
+      operationId: proposal.operationId, attemptId: String(proposal.deliveryAttemptCount),
+    });
+    const result = await executeConnectionJson(env, {
+      connectionVersionId: component.connectionVersionId,
+      actionProposalId: proposal.id,
+      operationId: proposal.operationId,
+      attemptNumber: proposal.deliveryAttemptCount,
+      method: reference[1] ?? "POST",
+      path: reference[2]!,
+      body: {
+        schema_version: "1",
+        action_id: proposal.id,
+        operation_id: proposal.operationId,
+        payload_digest: proposal.payloadDigest,
+        action_code: proposal.actionCode,
+        target: parsedObject(proposal.targetJson),
+        payload: parsedObject(proposal.payloadJson),
+        preconditions: parsedObject(proposal.preconditionsJson),
+        workflow_version_id: proposal.workflowVersionId,
+        policy_version_id: proposal.policyVersionId,
+      },
+    });
+    const outputErrors = validateJsonSchemaValue(result.data as JsonValue, parsedObject(component.outputSchemaJson));
+    if (outputErrors.length) throw new WorkflowEffectError("action_response_schema_invalid");
+    const finishedAt = now();
+    await env.DB.batch([
+      env.DB.prepare(`UPDATE action_proposals SET state = 'applied', delivery_terminal = 1, lease_expires_at = NULL, last_error_code = NULL, updated_at = ?2 WHERE id = ?1 AND state = 'applying'`).bind(proposal.id, finishedAt),
+      env.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, 'workflow.action_applied', 'system', ?3,
+          'action_proposal', ?4, ?5, ?6)
+      `).bind(crypto.randomUUID(), `workflow-action-applied:${proposal.operationId}`, proposal.runId, proposal.id, canonicalJson({
+        actionCode: proposal.actionCode, payloadDigest: proposal.payloadDigest,
+        connectionAttemptId: result.connectionAttemptId, responseDigest: result.responseDigest,
+      }), finishedAt),
+    ]);
+    await settleBudgets(env.DB, reservations, true).catch(() => {});
+    proposal = await loadProposal(env.DB, proposal.id);
+    await emitActionResolution(env, proposal);
+  } catch (error) {
+    const failure = error instanceof ConnectionExecutionError
+      ? new WorkflowEffectError(error.code, error.retryable, error.delaySeconds)
+      : error instanceof BudgetControlError
+        ? new WorkflowEffectError(error.code, error.retryable, error.delaySeconds)
+        : error instanceof WorkflowEffectError
+          ? error
+          : new WorkflowEffectError("action_delivery_failed", true, 15);
+    const terminal = !failure.retryable || proposal.deliveryAttemptCount >= ACTION_MAX_ATTEMPTS;
+    const delaySeconds = Math.max(1, Math.min(21_600, failure.delaySeconds * (2 ** Math.min(proposal.deliveryAttemptCount - 1, 7))));
+    await env.DB.prepare(`
+      UPDATE action_proposals SET state = 'failed', delivery_terminal = ?2,
+        next_attempt_at = ?3, lease_expires_at = NULL, last_error_code = ?4, updated_at = ?5
+      WHERE id = ?1 AND state = 'applying'
+    `).bind(
+      proposal.id, terminal ? 1 : 0,
+      new Date(Date.now() + delaySeconds * 1_000).toISOString(), failure.code, now(),
+    ).run();
+    await settleBudgets(env.DB, reservations, false);
+    proposal = await loadProposal(env.DB, proposal.id);
+    if (proposal.state === "applied") {
+      await emitActionResolution(env, proposal);
+      return;
+    }
+    if (terminal) {
+      await emitActionResolution(env, proposal);
+      return;
+    }
+    throw new RetryableActionProposalError(delaySeconds);
+  }
+}
+
+export async function acceptActionResult(
+  env: Env,
+  value: Record<string, unknown>,
+  integrationId: string,
+): Promise<{ proposalId: string; state: string; idempotentReplay: boolean }> {
+  const proposalId = typeof value.action_id === "string" ? value.action_id : "";
+  const operationId = typeof value.operation_id === "string" ? value.operation_id : "";
+  const payloadDigest = typeof value.payload_digest === "string" ? value.payload_digest : "";
+  const status = value.status;
+  if (!proposalId || proposalId.length > 500 || !operationId || operationId.length > 500
+    || !/^sha256:[a-f0-9]{64}$/u.test(payloadDigest)
+    || (status !== "applied" && status !== "failed")) {
+    throw new ApiError(400, "action_result_invalid", "action_id, operation_id, payload_digest, and a valid status are required.");
+  }
+  let proposal = await loadProposal(env.DB, proposalId);
+  if (proposal.operationId !== operationId || proposal.payloadDigest !== payloadDigest) {
+    throw new ApiError(409, "action_result_identity_mismatch", "The action result does not match the immutable proposal operation and payload digest.");
+  }
+  if (proposal.state === "applied" && status === "applied") return { proposalId, state: "applied", idempotentReplay: true };
+  if (proposal.state === "failed" && proposal.deliveryTerminal === 1 && status === "failed") return { proposalId, state: "failed", idempotentReplay: true };
+  if (!["queued", "applying", "failed"].includes(proposal.state) || proposal.deliveryTerminal === 1) {
+    throw new ApiError(409, "action_result_terminal", "The action proposal is not awaiting an asynchronous result.");
+  }
+  const timestamp = now();
+  const terminal = value.terminal !== false;
+  const errorCode = typeof value.error_code === "string" && value.error_code.length <= 200
+    ? value.error_code : "action_provider_failed";
+  const nextAttemptAt = new Date(Date.now() + Math.max(1, Math.min(21_600, Number(value.retry_after_seconds) || 30)) * 1_000).toISOString();
+  await env.DB.batch([
+    env.DB.prepare(`
+      UPDATE action_proposals SET state = ?2, delivery_terminal = ?3,
+        next_attempt_at = ?4, lease_expires_at = NULL, last_error_code = ?5,
+        updated_at = ?6 WHERE id = ?1 AND delivery_terminal = 0
+    `).bind(
+      proposalId, status === "applied" ? "applied" : "failed",
+      status === "applied" || terminal ? 1 : 0, nextAttemptAt,
+      status === "applied" ? null : errorCode, timestamp,
+    ),
+    env.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, 'workflow.action_result_received', 'service_identity', ?3,
+        'action_proposal', ?4, ?5, ?6)
+    `).bind(crypto.randomUUID(), `action-result:${operationId}:${status}`, integrationId, proposalId, canonicalJson({
+      status, payloadDigest, terminal: status === "applied" || terminal,
+      providerRequestId: typeof value.provider_request_id === "string" ? value.provider_request_id.slice(0, 500) : null,
+      errorCode: status === "failed" ? errorCode : null,
+    }), timestamp),
+  ]);
+  proposal = await loadProposal(env.DB, proposalId);
+  if (proposal.state === "applied" || proposal.deliveryTerminal === 1) await emitActionResolution(env, proposal);
+  else await env.DELIVERY_JOBS.send(actionJob(proposal.id, proposal.runId), { contentType: "json" }).catch(() => {});
+  return { proposalId, state: proposal.state, idempotentReplay: false };
+}
+
+export async function completeWorkflowAction(
+  env: Env,
+  input: { proposalId: string; eventResult: { status: "received"; event: unknown } | { status: "timed_out" } },
+): Promise<Record<string, unknown>> {
+  const proposal = await loadProposal(env.DB, input.proposalId);
+  if (proposal.state === "applied") return { port: "applied", proposalId: proposal.id, payloadDigest: proposal.payloadDigest };
+  if (proposal.state === "rejected") return { port: "rejected", proposalId: proposal.id, payloadDigest: proposal.payloadDigest };
+  if (proposal.state === "failed" && proposal.deliveryTerminal === 1) {
+    return { port: "error", proposalId: proposal.id, payloadDigest: proposal.payloadDigest, errorCode: proposal.lastErrorCode ?? "action_delivery_failed" };
+  }
+  if (input.eventResult.status === "timed_out") {
+    await env.DB.prepare(`UPDATE action_proposals SET state = 'cancelled', delivery_terminal = 1, updated_at = ?2 WHERE id = ?1 AND state IN ('approval_required','approved','queued','failed') AND delivery_terminal = 0`)
+      .bind(proposal.id, now()).run();
+    return { port: "timeout", proposalId: proposal.id, payloadDigest: proposal.payloadDigest };
+  }
+  if (["queued", "applying", "failed"].includes(proposal.state)) {
+    const approvalPolicy = parsedObject(proposal.approvalPolicyJson);
+    if (typeof approvalPolicy.expires_at !== "string") throw new WorkflowEffectError("action_approval_expiry_missing");
+    if (proposal.state !== "applying") {
+      await env.DELIVERY_JOBS.send(actionJob(proposal.id, proposal.runId), { contentType: "json" }).catch(() => {});
+    }
+    return deliveryPending(proposal.id, proposal.payloadDigest, approvalPolicy.expires_at);
+  }
+  const approval = await env.DB.prepare(`SELECT decision, payload_digest AS payloadDigest FROM action_approvals WHERE proposal_id = ?1 LIMIT 1`)
+    .bind(proposal.id).first<{ decision: "approved" | "rejected"; payloadDigest: string }>();
+  if (!approval || approval.payloadDigest !== proposal.payloadDigest) throw new WorkflowEffectError("action_approval_digest_mismatch");
+  if (approval.decision === "rejected") return { port: "rejected", proposalId: proposal.id, payloadDigest: proposal.payloadDigest };
+  const approvalPolicy = parsedObject(proposal.approvalPolicyJson);
+  if (typeof approvalPolicy.expires_at !== "string") throw new WorkflowEffectError("action_approval_expiry_missing");
+  await env.DB.prepare(`UPDATE action_proposals SET state = 'queued', next_attempt_at = ?2, lease_expires_at = NULL, last_error_code = NULL, delivery_terminal = 0, updated_at = ?2 WHERE id = ?1 AND state = 'approved'`)
+    .bind(proposal.id, now()).run();
+  await env.DELIVERY_JOBS.send(actionJob(proposal.id, proposal.runId), { contentType: "json" }).catch(() => {});
+  return deliveryPending(proposal.id, proposal.payloadDigest, approvalPolicy.expires_at);
+}
+
+export async function loadActionProposalDetail(db: D1Database, proposalId: string): Promise<Record<string, unknown> | null> {
+  const proposal = await db.prepare(`
+    SELECT p.id, p.report_id AS reportId, r.public_reference AS reportReference,
+      p.run_id AS runId, p.step_run_id AS stepRunId, p.decision_id AS decisionId,
+      p.action_code AS actionCode, p.target_json AS targetJson,
+      p.payload_json AS payloadJson, p.preconditions_json AS preconditionsJson,
+      p.payload_digest AS payloadDigest, p.component_version_id AS componentVersionId,
+      p.authority_mode AS authorityMode, p.approval_policy_json AS approvalPolicyJson,
+      p.state, p.operation_id AS operationId, p.compensates_proposal_id AS compensatesProposalId,
+      p.delivery_attempt_count AS deliveryAttemptCount, p.delivery_terminal AS deliveryTerminal,
+      p.next_attempt_at AS nextAttemptAt, p.last_error_code AS lastErrorCode,
+      p.created_by_type AS createdByType, p.created_by_id AS createdById,
+      p.created_at AS createdAt, p.updated_at AS updatedAt
+    FROM action_proposals p JOIN reports r ON r.id = p.report_id
+    WHERE p.id = ?1 LIMIT 1
+  `).bind(proposalId).first<Record<string, unknown>>();
+  if (!proposal) return null;
+  const [approval, task, attempts] = await Promise.all([
+    db.prepare(`SELECT id, task_id AS taskId, approver_id AS approverId, payload_digest AS payloadDigest, decision, reason, created_at AS createdAt FROM action_approvals WHERE proposal_id = ?1 LIMIT 1`).bind(proposalId).first(),
+    db.prepare(`SELECT id, state, assigned_operator_id AS assignedOperatorId, due_at AS dueAt, completed_at AS completedAt FROM human_tasks WHERE action_proposal_id = ?1 LIMIT 1`).bind(proposalId).first(),
+    db.prepare(`SELECT id, attempt_number AS attemptNumber, connection_version_id AS connectionVersionId, request_digest AS requestDigest, response_status AS responseStatus, response_digest AS responseDigest, response_class AS responseClass, error_code AS errorCode, started_at AS startedAt, finished_at AS finishedAt FROM connection_attempts WHERE action_proposal_id = ?1 ORDER BY attempt_number, id`).bind(proposalId).all(),
+  ]);
+  return {
+    proposal: {
+      ...proposal,
+      target: typeof proposal.targetJson === "string" ? JSON.parse(proposal.targetJson) : {},
+      payload: typeof proposal.payloadJson === "string" ? JSON.parse(proposal.payloadJson) : {},
+      preconditions: typeof proposal.preconditionsJson === "string" ? JSON.parse(proposal.preconditionsJson) : {},
+      approvalPolicy: typeof proposal.approvalPolicyJson === "string" ? JSON.parse(proposal.approvalPolicyJson) : {},
+      targetJson: undefined, payloadJson: undefined, preconditionsJson: undefined, approvalPolicyJson: undefined,
+    },
+    approval: approval ?? null,
+    task: task ?? null,
+    attempts: attempts.results,
+  };
+}
+
+async function emitApprovalEvent(
+  env: Env,
+  proposal: ProposalRow,
+  approvalId: string,
+  decision: "approved" | "rejected",
+  actorId: string,
+): Promise<void> {
+  const eventType = `action.${proposal.id}.resolved`;
+  const eventKey = `action-approval:${approvalId}`;
+  const payload = { proposal_id: proposal.id, approval_id: approvalId, decision, payload_digest: proposal.payloadDigest };
+  const payloadJson = canonicalJson(payload);
+  const timestamp = now();
+  await env.DB.batch([
+    env.DB.prepare(`
+      INSERT OR IGNORE INTO workflow_event_inbox (
+        id, run_id, event_type, event_key, source_type, source_id,
+        payload_json, payload_digest, received_at
+      ) VALUES (?1, ?2, ?3, ?4, 'operator', ?5, ?6, ?7, ?8)
+    `).bind(approvalId, proposal.runId, eventType, eventKey, actorId, payloadJson, `sha256:${await sha256(payloadJson)}`, timestamp),
+    env.DB.prepare(`
+      INSERT OR IGNORE INTO workflow_dispatch_outbox (
+        id, run_id, operation, event_inbox_id, operation_key,
+        state, available_at, created_at, updated_at
+      ) VALUES (?1, ?2, 'event', ?1, ?3, 'pending', ?4, ?4, ?4)
+    `).bind(approvalId, proposal.runId, `workflow-event:${proposal.runId}:${eventType}:${eventKey}`, timestamp),
+  ]);
+  const instance = await env.DB.prepare(`SELECT cloudflare_instance_id AS instanceId FROM workflow_runs WHERE id = ?1 LIMIT 1`)
+    .bind(proposal.runId).first<{ instanceId: string | null }>();
+  if (!instance?.instanceId) return;
+  try {
+    await (await env.WORKFLOWS.get(instance.instanceId)).sendEvent({ type: eventType, payload });
+    const deliveredAt = now();
+    await env.DB.batch([
+      env.DB.prepare(`UPDATE workflow_event_inbox SET delivered_at = ?2, delivery_attempts = delivery_attempts + 1, last_error_code = NULL WHERE id = ?1`).bind(approvalId, deliveredAt),
+      env.DB.prepare(`UPDATE workflow_dispatch_outbox SET state = 'delivered', last_error_code = NULL, updated_at = ?2 WHERE id = ?1`).bind(approvalId, deliveredAt),
+    ]);
+  } catch {
+    await env.DB.batch([
+      env.DB.prepare(`UPDATE workflow_event_inbox SET delivery_attempts = delivery_attempts + 1, last_error_code = 'platform_event_send_failed' WHERE id = ?1`).bind(approvalId),
+      env.DB.prepare(`UPDATE workflow_dispatch_outbox SET state = 'failed', last_error_code = 'platform_event_send_failed', updated_at = ?2 WHERE id = ?1`).bind(approvalId, now()),
+    ]);
+  }
+}
+
+export async function decideActionProposal(
+  env: Env,
+  proposalId: string,
+  input: { decision: "approved" | "rejected"; payloadDigest: string; reason?: string },
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ proposalId: string; approvalId: string; state: string; idempotentReplay: boolean }> {
+  const prior = await env.DB.prepare(`SELECT id, proposal_id AS proposalId, decision FROM action_approvals WHERE approver_id = ?1 AND idempotency_key = ?2 LIMIT 1`)
+    .bind(session.actor.id, idempotencyKey).first<{ id: string; proposalId: string; decision: string }>();
+  if (prior) {
+    if (prior.proposalId !== proposalId || prior.decision !== input.decision) throw new ApiError(409, "idempotency_key_reused", "This Idempotency-Key was already used for another action decision.");
+    return { proposalId, approvalId: prior.id, state: input.decision, idempotentReplay: true };
+  }
+  const proposal = await loadProposal(env.DB, proposalId);
+  if (proposal.state !== "approval_required") throw new ApiError(409, "action_not_awaiting_approval", "The action is not awaiting approval.");
+  if (input.payloadDigest !== proposal.payloadDigest) throw new ApiError(409, "action_approval_digest_mismatch", "The approval payload digest does not match the immutable proposal.");
+  if (input.reason !== undefined && (input.reason.trim().length < 3 || input.reason.length > 2_000)) {
+    throw new ApiError(400, "action_decision_reason_invalid", "The decision reason must contain 3 to 2,000 characters.");
+  }
+  const approvalId = crypto.randomUUID();
+  const timestamp = now();
+  await env.DB.batch([
+    env.DB.prepare(`
+      INSERT INTO action_approvals (
+        id, proposal_id, approver_id, payload_digest, decision,
+        reason, idempotency_key, created_at
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)
+    `).bind(approvalId, proposalId, session.actor.id, proposal.payloadDigest, input.decision, input.reason?.trim() ?? null, idempotencyKey, timestamp),
+    env.DB.prepare(`UPDATE action_proposals SET state = ?2, updated_at = ?3 WHERE id = ?1 AND state = 'approval_required'`)
+      .bind(proposalId, input.decision, timestamp),
+    env.DB.prepare(`UPDATE human_tasks SET state = 'completed', completed_at = ?2, updated_at = ?2 WHERE action_proposal_id = ?1 AND state IN ('open','claimed')`)
+      .bind(proposalId, timestamp),
+    env.DB.prepare(`UPDATE human_task_claims SET released_at = ?2, release_reason = 'direct_action_decision' WHERE task_id = (SELECT id FROM human_tasks WHERE action_proposal_id = ?1 LIMIT 1) AND released_at IS NULL`)
+      .bind(proposalId, timestamp),
+    env.DB.prepare(`
+      INSERT 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, 'action_proposal', ?6, ?7, ?8)
+    `).bind(
+      crypto.randomUUID(), `action-decision:${idempotencyKey}`,
+      input.decision === "approved" ? "action.approved" : "action.rejected",
+      session.actor.type, session.actor.id, proposalId,
+      canonicalJson({ payloadDigest: proposal.payloadDigest, reason: input.reason?.trim() ?? null }), timestamp,
+    ),
+  ]);
+  const updated = await loadProposal(env.DB, proposalId);
+  await emitApprovalEvent(env, updated, approvalId, input.decision, session.actor.id);
+  return { proposalId, approvalId, state: input.decision, idempotentReplay: false };
+}
+
+export async function retryActionProposal(
+  env: Env,
+  proposalId: string,
+  payloadDigest: string,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ proposalId: string; state: string; idempotentReplay: boolean }> {
+  const key = `action-retry:${idempotencyKey}`;
+  const prior = await env.DB.prepare(`SELECT target_id AS targetId FROM audit_events WHERE idempotency_key = ?1 AND action = 'action.retry_requested' LIMIT 1`)
+    .bind(key).first<{ targetId: string }>();
+  if (prior) {
+    if (prior.targetId !== proposalId) throw new ApiError(409, "idempotency_key_reused", "This Idempotency-Key was already used for another action retry.");
+    return { proposalId, state: "queued", idempotentReplay: true };
+  }
+  const proposal = await loadProposal(env.DB, proposalId);
+  if (proposal.payloadDigest !== payloadDigest) throw new ApiError(409, "action_retry_digest_mismatch", "Retry requires the exact immutable payload digest.");
+  if (proposal.state !== "failed" || proposal.deliveryTerminal !== 1) throw new ApiError(409, "action_not_retryable", "Only a terminal failed action can be retried.");
+  const timestamp = now();
+  await env.DB.batch([
+    env.DB.prepare(`UPDATE action_proposals SET state = 'queued', delivery_terminal = 0, delivery_attempt_count = 0, next_attempt_at = ?2, lease_expires_at = NULL, last_error_code = NULL, updated_at = ?2 WHERE id = ?1 AND state = 'failed' AND delivery_terminal = 1`)
+      .bind(proposalId, timestamp),
+    env.DB.prepare(`INSERT INTO audit_events (id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at) VALUES (?1, ?2, 'action.retry_requested', ?3, ?4, 'action_proposal', ?5, ?6, ?7)`)
+      .bind(crypto.randomUUID(), key, session.actor.type, session.actor.id, proposalId, canonicalJson({ payloadDigest }), timestamp),
+  ]);
+  await env.DELIVERY_JOBS.send(actionJob(proposalId, proposal.runId), { contentType: "json" }).catch(() => {});
+  return { proposalId, state: "queued", idempotentReplay: false };
+}
+
+export async function proposeCompensatingAction(
+  env: Env,
+  proposalId: string,
+  value: Record<string, unknown>,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ proposalId: string; payloadDigest: string; state: "approval_required"; idempotentReplay: boolean }> {
+  const original = await loadProposal(env.DB, proposalId);
+  if (original.state !== "applied" && original.state !== "compensation_required") {
+    throw new ApiError(409, "action_compensation_unavailable", "Only an applied or compensation-required action can be compensated.");
+  }
+  const componentVersionId = typeof value.component_version_id === "string" ? value.component_version_id : "";
+  const actionCode = typeof value.action_code === "string" ? value.action_code : "";
+  const target = object(value.target as JsonValue, "action_target_invalid");
+  const payload = object(value.payload as JsonValue, "action_payload_invalid");
+  const preconditions = object((value.preconditions ?? {}) as JsonValue, "action_preconditions_invalid");
+  if (!componentVersionId || !actionCode || actionCode.length > 200) throw new ApiError(400, "action_compensation_invalid", "component_version_id and action_code are required.");
+  const component = await actionComponent(env.DB, componentVersionId);
+  if (validateJsonSchemaValue(payload, parsedObject(component.inputSchemaJson)).length) {
+    throw new ApiError(422, "action_payload_schema_invalid", "The compensation payload does not match the published component schema.");
+  }
+  const operationId = `compensation:${original.operationId}:${idempotencyKey}`;
+  const existing = await env.DB.prepare(`SELECT id, payload_digest AS payloadDigest, state FROM action_proposals WHERE operation_id = ?1 LIMIT 1`)
+    .bind(operationId).first<{ id: string; payloadDigest: string; state: string }>();
+  if (existing) return { proposalId: existing.id, payloadDigest: existing.payloadDigest, state: "approval_required", idempotentReplay: true };
+  const compensationId = crypto.randomUUID();
+  const timestamp = now();
+  const expiresAt = new Date(Date.now() + 86_400_000).toISOString();
+  const digestMaterial = {
+    schema_version: "1", action_id: compensationId, action_code: actionCode,
+    target, payload, preconditions, component_version_id: componentVersionId,
+    compensates_proposal_id: proposalId, expires_at: expiresAt,
+    installation_id: original.installationId,
+  };
+  const payloadDigest = `sha256:${await sha256(canonicalJson(digestMaterial))}`;
+  await env.DB.batch([
+    env.DB.prepare(`
+      INSERT INTO action_proposals (
+        id, installation_id, report_id, run_id, step_run_id, action_code,
+        target_json, payload_json, preconditions_json, payload_digest,
+        component_version_id, authority_mode, approval_policy_json, state,
+        operation_id, compensates_proposal_id, created_by_type, created_by_id,
+        created_at, updated_at
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11,
+        'assist', ?12, 'approval_required', ?13, ?14, ?15, ?16, ?17, ?17)
+    `).bind(
+      compensationId, original.installationId, original.reportId, original.runId,
+      original.stepRunId, actionCode, canonicalJson(target), canonicalJson(payload),
+      canonicalJson(preconditions), payloadDigest, componentVersionId,
+      canonicalJson({ mode: "human", expires_at: expiresAt, compensation: true }),
+      operationId, proposalId, session.actor.type, session.actor.id, timestamp,
+    ),
+    env.DB.prepare(`UPDATE action_proposals SET state = 'compensation_required', updated_at = ?2 WHERE id = ?1 AND state = 'applied'`)
+      .bind(proposalId, timestamp),
+    env.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, 'workflow.compensation_proposed', ?3, ?4, 'action_proposal', ?5, ?6, ?7)`)
+      .bind(crypto.randomUUID(), `action-compensation:${idempotencyKey}`, session.actor.type, session.actor.id, compensationId, canonicalJson({ compensatesProposalId: proposalId, payloadDigest, actionCode }), timestamp),
+  ]);
+  return { proposalId: compensationId, payloadDigest, state: "approval_required", idempotentReplay: false };
+}