create-safest-tools 0.2.0

package/template/src/component-executor.ts

@@ -0,0 +1,845 @@
+import { canonicalJson } from "./audit";
+import { reserveBudgets as reserveScopedBudgets, settleBudgets as settleScopedBudgets } from "./budget-control";
+import { ConnectionExecutionError, executeConnectionJson } from "./connection-egress";
+import { sha256 } from "./report-crypto";
+import { evaluateInputMapping, validateJsonSchemaValue } from "./workflow-expressions";
+import type { JsonObject, JsonValue, WorkflowNodeV1 } from "./workflow-platform-types";
+
+interface ComponentVersionRow {
+  id: string;
+  componentId: string;
+  componentKey: string;
+  componentKind: string;
+  effectClass: "read_only" | "side_effecting";
+  definitionStatus: string;
+  implementationKind: "built_in" | "webhook" | "external_api" | "workers_ai" | "specialist_agent" | "message_template";
+  implementationReference: string;
+  inputSchemaJson: string;
+  outputSchemaJson: string;
+  allowedInputFieldsJson: string;
+  dataClassificationsJson: string;
+  connectionVersionId: string | null;
+  cachePolicyJson: string;
+  budgetPolicyJson: string;
+  toolManifestJson: string;
+  retiredAt: string | null;
+}
+
+interface ComponentRunReplayRow {
+  id: string;
+  state: string;
+  outputJson: string | null;
+  findingId: string | null;
+  attemptCount: number;
+  inputDigest: string;
+}
+
+interface RunContextRow {
+  runId: string;
+  installationId: string;
+  reportId: string;
+  workflowVersionId: string;
+  queueId: string | null;
+  queueVersionId: string | null;
+  authorityMode: string;
+  runInputJson: string;
+  publicReference: string;
+  source: string;
+  reportState: string;
+  priority: number;
+  reasonCode: string;
+  locale: string;
+  formVersionId: string | null;
+  policyVersionId: string | null;
+  routingRuleVersionId: string | null;
+  submittedAt: string;
+  receivedAt: string;
+}
+
+interface ComponentImplementationResult {
+  data: JsonObject;
+  provider?: string;
+  providerRequestId?: string;
+  connectionAttemptId?: string;
+  inputUnits?: number | null;
+  outputUnits?: number | null;
+}
+
+interface BudgetReservation {
+  id: string;
+  policyId: string;
+  windowStart: string;
+}
+
+export class ComponentExecutionError extends Error {
+  constructor(
+    readonly code: string,
+    readonly retryable: boolean,
+    readonly delaySeconds = 5,
+  ) {
+    super(code);
+    this.name = "ComponentExecutionError";
+  }
+}
+
+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 asJsonObject(value: unknown, code: string): JsonObject {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new ComponentExecutionError(code, false);
+  try {
+    return JSON.parse(canonicalJson(value)) as JsonObject;
+  } catch {
+    throw new ComponentExecutionError(code, false);
+  }
+}
+
+function safeJsonObject(value: string): JsonObject {
+  try {
+    return asJsonObject(JSON.parse(value), "stored_json_invalid");
+  } catch {
+    return {};
+  }
+}
+
+function expressionPaths(value: JsonValue, output = new Set<string>()): Set<string> {
+  if (typeof value === "string") {
+    for (const match of value.matchAll(/\$\.([A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*)/gu)) output.add(match[1]!);
+    return output;
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) expressionPaths(entry, output);
+    return output;
+  }
+  if (value && typeof value === "object") {
+    for (const entry of Object.values(value)) expressionPaths(entry, output);
+  }
+  return output;
+}
+
+export function assertMappedFieldsAllowed(mapping: Record<string, JsonValue>, allowedFields: string[]): void {
+  const normalized = allowedFields.map((field) => field.replace(/^\$\./u, "")).filter(Boolean);
+  for (const path of expressionPaths(mapping)) {
+    if (!normalized.some((allowed) => allowed === path || path.startsWith(`${allowed}.`))) {
+      throw new ComponentExecutionError("component_input_field_denied", false);
+    }
+  }
+}
+
+function isPublicUrlHost(hostname: string): boolean {
+  const host = hostname.toLowerCase().replace(/^\[|\]$/gu, "").replace(/\.$/u, "");
+  if (!host || host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal")) return false;
+  const octets = host.split(".").map(Number);
+  if (octets.length === 4 && octets.every((part) => Number.isInteger(part) && part >= 0 && part <= 255)) {
+    const [a, b] = octets as [number, number, number, number];
+    return !(a === 0 || a === 10 || a === 127 || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 100 && b >= 64 && b <= 127) || a >= 224);
+  }
+  return !host.includes(":") || !(host === "::" || host === "::1" || /^(?:fc|fd|fe8|fe9|fea|feb)/u.test(host) || host.startsWith("::ffff:"));
+}
+
+export async function executeBuiltInComponent(reference: string, input: JsonObject): Promise<ComponentImplementationResult> {
+  if (reference === "identity-v1") return { data: input, provider: "safest_builtin" };
+  if (reference === "url-normalize-v1" || reference === "phishing-url-v1") {
+    if (typeof input.url !== "string" || input.url.length > 2_048) throw new ComponentExecutionError("component_url_invalid", false);
+    let url: URL;
+    try {
+      url = new URL(input.url);
+    } catch {
+      throw new ComponentExecutionError("component_url_invalid", false);
+    }
+    if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || !isPublicUrlHost(url.hostname)) {
+      throw new ComponentExecutionError("component_url_unsafe", false);
+    }
+    url.hash = "";
+    const normalized = url.href;
+    const host = url.hostname.toLowerCase();
+    const signals = [
+      ...(host.startsWith("xn--") || host.includes(".xn--") ? ["punycode_hostname"] : []),
+      ...(/\b(?:login|verify|secure|account|password|wallet|invoice)\b/iu.test(`${host}${url.pathname}`) ? ["credential_lure_term"] : []),
+      ...(url.protocol !== "https:" ? ["plaintext_transport"] : []),
+      ...(host.split(".").length > 5 ? ["deep_subdomain"] : []),
+    ];
+    const data: JsonObject = {
+      normalized_url: normalized,
+      normalized_url_hash: `sha256:${await sha256(normalized)}`,
+      hostname_hash: `sha256:${await sha256(host)}`,
+      scheme: url.protocol.slice(0, -1),
+      signals,
+    };
+    if (reference === "phishing-url-v1") {
+      data.conclusion = signals.length >= 3 ? "likely_phishing" : signals.length >= 1 ? "suspicious" : "no_phishing_signal";
+      data.summary = signals.length ? `Observed ${signals.length} deterministic phishing-risk signal(s).` : "No deterministic phishing signal was observed; reputation and content checks were not available.";
+      data.uncertainty = ["dns_reputation_and_content_not_checked"];
+      data.confidence = signals.length ? Math.min(0.85, 0.45 + signals.length * 0.12) : 0.25;
+    }
+    return { data, provider: "safest_builtin" };
+  }
+  throw new ComponentExecutionError("component_implementation_unsupported", false);
+}
+
+function unwrapAiResponse(value: unknown): { data: JsonObject; inputUnits: number | null; outputUnits: number | null; requestId?: string } {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new ComponentExecutionError("component_ai_response_invalid", false);
+  const response = value as Record<string, unknown>;
+  const usage = response.usage && typeof response.usage === "object" && !Array.isArray(response.usage) ? response.usage as Record<string, unknown> : {};
+  let output = response.response;
+  if (output === undefined && Array.isArray(response.choices)) {
+    const choice = response.choices[0] as Record<string, unknown> | undefined;
+    const message = choice?.message && typeof choice.message === "object" && !Array.isArray(choice.message) ? choice.message as Record<string, unknown> : null;
+    output = message?.content;
+  }
+  if (typeof output === "string") {
+    try {
+      output = JSON.parse(output);
+    } catch {
+      throw new ComponentExecutionError("component_ai_response_invalid", false);
+    }
+  }
+  const unit = (candidate: unknown): number | null => typeof candidate === "number" && Number.isInteger(candidate) && candidate >= 0 ? candidate : null;
+  return {
+    data: asJsonObject(output, "component_ai_response_invalid"),
+    inputUnits: unit(usage.prompt_tokens ?? usage.input_tokens ?? usage.input_units),
+    outputUnits: unit(usage.completion_tokens ?? usage.output_tokens ?? usage.output_units),
+    ...(typeof response.request_id === "string" ? { requestId: response.request_id.slice(0, 200) } : {}),
+  };
+}
+
+async function executeImplementation(
+  env: Env,
+  component: ComponentVersionRow,
+  input: JsonObject,
+  componentRunId: string,
+  attempt: number,
+): Promise<ComponentImplementationResult> {
+  if (component.implementationKind === "built_in" || component.implementationKind === "specialist_agent") {
+    return executeBuiltInComponent(component.implementationReference, input);
+  }
+  if (component.implementationKind === "webhook" || component.implementationKind === "external_api") {
+    if (!component.connectionVersionId) throw new ComponentExecutionError("component_connection_missing", false);
+    const reference = component.implementationReference.trim();
+    const match = /^(?:(GET|POST|PUT|PATCH|DELETE|HEAD)\s+)?(\/[^\s]*)$/u.exec(reference);
+    if (!match) throw new ComponentExecutionError("component_operation_reference_invalid", false);
+    try {
+      const result = await executeConnectionJson(env, {
+        connectionVersionId: component.connectionVersionId,
+        componentRunId,
+        operationId: `${componentRunId}:egress`,
+        attemptNumber: attempt,
+        method: match[1] ?? "POST",
+        path: match[2]!,
+        body: { schema_version: "1", operation_id: componentRunId, component_version_id: component.id, input },
+      });
+      return { data: asJsonObject(result.data, "component_output_invalid"), connectionAttemptId: result.connectionAttemptId, provider: "connection" };
+    } catch (error) {
+      if (error instanceof ConnectionExecutionError) throw new ComponentExecutionError(error.code, error.retryable, error.delaySeconds);
+      throw error;
+    }
+  }
+  if (component.implementationKind === "workers_ai") {
+    if (!component.implementationReference.startsWith("@cf/")) throw new ComponentExecutionError("component_ai_model_invalid", false);
+    const ai = (env as unknown as { AI?: { run(model: string, input: Record<string, unknown>): Promise<unknown> } }).AI;
+    if (!ai) throw new ComponentExecutionError("component_ai_binding_unavailable", true, 30);
+    const outputSchema = parsedJson<JsonObject>(component.outputSchemaJson, {});
+    let result: unknown;
+    try {
+      result = await ai.run(component.implementationReference, {
+        messages: [
+          { role: "system", content: "You are a bounded safety enrichment. Use only the supplied JSON. Return only an object matching the provided schema. Never propose or execute an external action." },
+          { role: "user", content: canonicalJson(input) },
+        ],
+        response_format: { type: "json_schema", json_schema: outputSchema },
+      });
+    } catch {
+      throw new ComponentExecutionError("component_ai_provider_error", true, 15);
+    }
+    const unwrapped = unwrapAiResponse(result);
+    return { data: unwrapped.data, provider: "workers_ai", providerRequestId: unwrapped.requestId, inputUnits: unwrapped.inputUnits, outputUnits: unwrapped.outputUnits };
+  }
+  throw new ComponentExecutionError("component_implementation_unsupported", false);
+}
+
+export async function loadWorkflowExecutionContext(env: Env, runId: string, branchKey: string): Promise<{ row: RunContextRow; context: JsonObject; subjectType: string; subjectReference: string }> {
+  const row = await env.DB.prepare(`
+    SELECT wr.id AS runId, wr.installation_id AS installationId, wr.report_id AS reportId,
+      wr.workflow_version_id AS workflowVersionId, wr.queue_id AS queueId,
+      wr.queue_version_id AS queueVersionId, wr.authority_mode AS authorityMode,
+      wr.input_json AS runInputJson, r.public_reference AS publicReference,
+      r.source, r.state AS reportState, r.priority, r.reason_code AS reasonCode,
+      r.locale, r.form_version_id AS formVersionId, r.policy_version_id AS policyVersionId,
+      r.routing_rule_version_id AS routingRuleVersionId, r.submitted_at AS submittedAt,
+      r.received_at AS receivedAt
+    FROM workflow_runs wr JOIN reports r ON r.id = wr.report_id
+    WHERE wr.id = ?1 LIMIT 1
+  `).bind(runId).first<RunContextRow>();
+  if (!row) throw new ComponentExecutionError("component_report_context_missing", false);
+  const [targetResult, answersResult, stepsResult, findingsResult] = await Promise.all([
+    env.DB.prepare(`SELECT target_type, target_reference, owner_reference, customer_url, signed_facts_json FROM report_targets WHERE report_id = ?1 ORDER BY created_at, id LIMIT 50`).bind(row.reportId).all<{
+      target_type: string; target_reference: string; owner_reference: string | null; customer_url: string | null; signed_facts_json: string;
+    }>(),
+    env.DB.prepare(`SELECT field_key, value_json FROM report_answers WHERE report_id = ?1 ORDER BY field_key LIMIT 200`).bind(row.reportId).all<{ field_key: string; value_json: string }>(),
+    env.DB.prepare(`
+      SELECT s.node_id, o.inline_json FROM workflow_step_runs s
+      JOIN workflow_step_outputs o ON o.step_run_id = s.id
+      WHERE s.run_id = ?1 AND s.state = 'succeeded' AND s.branch_key IN ('', ?2)
+      ORDER BY s.finished_at, s.node_id
+    `).bind(row.runId, branchKey).all<{ node_id: string; inline_json: string | null }>(),
+    env.DB.prepare(`
+      SELECT finding_type, data_json FROM findings
+      WHERE report_id = ?1 AND status = 'available' AND (run_id = ?2 OR run_id IS NULL)
+      ORDER BY created_at, id LIMIT 100
+    `).bind(row.reportId, row.runId).all<{ finding_type: string; data_json: string }>(),
+  ]);
+  const targets = targetResult.results.map((target) => ({
+    type: target.target_type,
+    reference: target.target_reference,
+    owner_reference: target.owner_reference,
+    customer_url: target.customer_url,
+    signed_facts: safeJsonObject(target.signed_facts_json),
+  })) as JsonValue[];
+  const answers: JsonObject = {};
+  for (const answer of answersResult.results) {
+    try {
+      answers[answer.field_key] = JSON.parse(answer.value_json) as JsonValue;
+    } catch {
+      answers[answer.field_key] = null;
+    }
+  }
+  const steps: JsonObject = {};
+  for (const step of stepsResult.results) if (step.inline_json) steps[step.node_id] = safeJsonObject(step.inline_json);
+  const findings: JsonObject = {};
+  for (const finding of findingsResult.results) if (!(finding.finding_type in findings)) findings[finding.finding_type] = safeJsonObject(finding.data_json);
+  const context: JsonObject = {
+    run: { id: row.runId, workflow_version_id: row.workflowVersionId, authority_mode: row.authorityMode, input: safeJsonObject(row.runInputJson) },
+    report: {
+      id: row.reportId, public_reference: row.publicReference, source: row.source,
+      state: row.reportState, priority: row.priority, reason_code: row.reasonCode,
+      locale: row.locale, submitted_at: row.submittedAt, received_at: row.receivedAt,
+      form_version_id: row.formVersionId, policy_version_id: row.policyVersionId,
+      routing_rule_version_id: row.routingRuleVersionId,
+    },
+    queue: { id: row.queueId, version_id: row.queueVersionId },
+    target: targets[0] ?? null,
+    targets,
+    answers,
+    steps,
+    findings,
+  };
+  const firstTarget = targetResult.results[0];
+  return {
+    row,
+    context,
+    subjectType: firstTarget?.target_type ?? "report",
+    subjectReference: firstTarget?.target_reference ?? row.publicReference,
+  };
+}
+
+async function loadComponent(db: D1Database, componentVersionId: string): Promise<ComponentVersionRow> {
+  const row = await db.prepare(`
+    SELECT v.id, v.definition_id AS componentId, d.component_key AS componentKey,
+      d.component_kind AS componentKind, d.effect_class AS effectClass,
+      d.status AS definitionStatus, v.implementation_kind AS implementationKind,
+      v.implementation_reference AS implementationReference,
+      v.input_schema_json AS inputSchemaJson, v.output_schema_json AS outputSchemaJson,
+      v.allowed_input_fields_json AS allowedInputFieldsJson,
+      v.data_classifications_json AS dataClassificationsJson,
+      v.connection_version_id AS connectionVersionId, v.cache_policy_json AS cachePolicyJson,
+      v.budget_policy_json AS budgetPolicyJson, v.tool_manifest_json AS toolManifestJson,
+      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(componentVersionId).first<ComponentVersionRow>();
+  if (!row || row.retiredAt || row.definitionStatus !== "active") throw new ComponentExecutionError("component_version_unavailable", false);
+  if (row.effectClass !== "read_only") throw new ComponentExecutionError("component_effect_not_read_only", false);
+  return row;
+}
+
+async function reserveComponentBudgets(
+  db: D1Database,
+  component: ComponentVersionRow,
+  installationId: string,
+  workflowRunId: string,
+  operationId: string,
+  attempt: number,
+): Promise<BudgetReservation[]> {
+  const componentPolicy = parsedJson<Record<string, unknown>>(component.budgetPolicyJson, {});
+  if (Number.isInteger(componentPolicy.max_calls_per_run) && Number(componentPolicy.max_calls_per_run) >= 0) {
+    const used = await db.prepare(`
+      SELECT COUNT(*) AS count FROM component_runs
+      WHERE workflow_run_id = ?1 AND component_version_id = ?2 AND state IN ('running','succeeded')
+    `).bind(workflowRunId, component.id).first<{ count: number }>();
+    if (Number(used?.count ?? 0) > Number(componentPolicy.max_calls_per_run)) throw new ComponentExecutionError("component_run_budget_exhausted", false);
+  }
+  const policies = await db.prepare(`
+    SELECT id, limit_value AS limitValue, window_seconds AS windowSeconds,
+      behavior FROM budget_policies
+    WHERE installation_id = ?1 AND metric = 'calls' AND retired_at IS NULL
+      AND ((scope_type = 'installation' AND scope_id = ?1)
+        OR (scope_type = 'component' AND scope_id IN (?2, ?3)))
+    ORDER BY CASE scope_type WHEN 'component' THEN 0 ELSE 1 END, published_at DESC, id
+  `).bind(installationId, component.componentId, component.id).all<{
+    id: string; limitValue: number; windowSeconds: number; behavior: string;
+  }>();
+  const reservations: BudgetReservation[] = [];
+  try {
+    for (const policy of policies.results) {
+      const epochSeconds = Math.floor(Date.now() / 1_000);
+      const windowEpoch = Math.floor(epochSeconds / policy.windowSeconds) * policy.windowSeconds;
+      const windowStart = new Date(windowEpoch * 1_000).toISOString();
+      const reservationId = `${policy.id}:${operationId}:${attempt}`;
+      const existing = await db.prepare(`SELECT status FROM budget_reservations WHERE id = ?1 LIMIT 1`).bind(reservationId).first<{ status: string }>();
+      if (existing?.status === "reserved" || existing?.status === "committed") {
+        reservations.push({ id: reservationId, policyId: policy.id, windowStart });
+        continue;
+      }
+      await db.prepare(`
+        INSERT INTO budget_usage (policy_id, window_start, reserved_value, consumed_value, revision, updated_at)
+        VALUES (?1, ?2, 0, 0, 1, ?3) ON CONFLICT(policy_id, window_start) DO NOTHING
+      `).bind(policy.id, windowStart, now()).run();
+      const reserved = await db.prepare(`
+        UPDATE budget_usage SET reserved_value = reserved_value + 1,
+          revision = revision + 1, updated_at = ?3
+        WHERE policy_id = ?1 AND window_start = ?2
+          AND reserved_value + consumed_value + 1 <= ?4
+      `).bind(policy.id, windowStart, now(), policy.limitValue).run();
+      if (reserved.meta.changes !== 1) {
+        const retryable = policy.behavior === "defer";
+        throw new ComponentExecutionError(
+          policy.behavior === "fallback" ? "component_budget_fallback_required" : "component_budget_exhausted",
+          retryable,
+          retryable ? Math.max(5, policy.windowSeconds) : 5,
+        );
+      }
+      await db.prepare(`
+        INSERT INTO budget_reservations (
+          id, policy_id, window_start, operation_type, operation_id,
+          attempt_id, reserved_value, status, expires_at, created_at, updated_at
+        ) VALUES (?1, ?2, ?3, 'component', ?4, ?5, 1, 'reserved', ?6, ?7, ?7)
+      `).bind(
+        reservationId, policy.id, windowStart, operationId, String(attempt),
+        new Date(Date.now() + 15 * 60_000).toISOString(), now(),
+      ).run();
+      reservations.push({ id: reservationId, policyId: policy.id, windowStart });
+    }
+    return reservations;
+  } catch (error) {
+    await settleComponentBudgets(db, reservations, false);
+    throw error;
+  }
+}
+
+async function settleComponentBudgets(db: D1Database, reservations: BudgetReservation[], commit: boolean): Promise<void> {
+  const timestamp = now();
+  for (const reservation of reservations) {
+    const changed = await db.prepare(`
+      UPDATE budget_reservations SET status = ?2, committed_value = ?3, updated_at = ?4
+      WHERE id = ?1 AND status = 'reserved'
+    `).bind(reservation.id, commit ? "committed" : "released", commit ? 1 : null, timestamp).run();
+    if (changed.meta.changes !== 1) continue;
+    await db.prepare(`
+      UPDATE budget_usage SET reserved_value = MAX(0, reserved_value - 1),
+        consumed_value = consumed_value + ?3, revision = revision + 1, updated_at = ?4
+      WHERE policy_id = ?1 AND window_start = ?2
+    `).bind(reservation.policyId, reservation.windowStart, commit ? 1 : 0, timestamp).run();
+  }
+}
+
+async function ensureStepAndAttempt(
+  env: Env,
+  input: { runId: string; node: WorkflowNodeV1; branchKey: string; stepRunId: string; inputDigest: string },
+): Promise<number> {
+  const timestamp = now();
+  await env.DB.prepare(`
+    INSERT INTO workflow_step_runs (
+      id, run_id, node_id, node_type, branch_key, occurrence, state,
+      input_digest, started_at, updated_at
+    ) VALUES (?1, ?2, ?3, ?4, ?5, 1, 'running', ?6, ?7, ?7)
+    ON CONFLICT(run_id, node_id, branch_key, occurrence) DO UPDATE SET
+      state = 'running', input_digest = excluded.input_digest,
+      started_at = COALESCE(workflow_step_runs.started_at, excluded.started_at),
+      updated_at = excluded.updated_at
+  `).bind(input.stepRunId, input.runId, input.node.id, input.node.kind, input.branchKey, input.inputDigest, timestamp).run();
+  const latest = await env.DB.prepare(`SELECT COALESCE(MAX(attempt), 0) AS attempt FROM workflow_step_attempts WHERE step_run_id = ?1`)
+    .bind(input.stepRunId).first<{ attempt: number }>();
+  const attempt = Number(latest?.attempt ?? 0) + 1;
+  await env.DB.prepare(`
+    INSERT INTO workflow_step_attempts (
+      id, step_run_id, attempt, operation_id, status, request_digest, started_at
+    ) VALUES (?1, ?2, ?3, ?4, 'running', ?5, ?6)
+  `).bind(crypto.randomUUID(), input.stepRunId, attempt, `${input.stepRunId}:attempt:${attempt}`, input.inputDigest, timestamp).run();
+  return attempt;
+}
+
+async function finishStepAttempt(
+  db: D1Database,
+  stepRunId: string,
+  attempt: number,
+  input: { status: "succeeded" | "retryable_failed" | "permanent_failed"; outputDigest?: string; errorCode?: string },
+): Promise<void> {
+  const timestamp = now();
+  await db.batch([
+    db.prepare(`
+      UPDATE workflow_step_attempts SET status = ?3, response_digest = ?4,
+        error_code = ?5, error_class = ?6, finished_at = ?7
+      WHERE step_run_id = ?1 AND attempt = ?2
+    `).bind(
+      stepRunId, attempt, input.status, input.outputDigest ?? null, input.errorCode ?? null,
+      input.status === "retryable_failed" ? "retryable" : input.status === "permanent_failed" ? "permanent" : null,
+      timestamp,
+    ),
+    ...(input.status === "succeeded" ? [] : [db.prepare(`
+      UPDATE workflow_step_runs SET state = 'failed', updated_at = ?2 WHERE id = ?1
+    `).bind(stepRunId, timestamp)]),
+  ]);
+}
+
+function findingSummary(data: JsonObject, componentKey: string): string {
+  if (typeof data.summary === "string" && data.summary.trim()) return data.summary.trim().slice(0, 1_000);
+  if (typeof data.conclusion === "string") return `${componentKey} concluded ${data.conclusion}.`.slice(0, 1_000);
+  return `${componentKey} completed successfully.`;
+}
+
+function confidence(data: JsonObject): number | null {
+  return typeof data.confidence === "number" && data.confidence >= 0 && data.confidence <= 1 ? data.confidence : null;
+}
+
+export async function executeReadOnlyComponent(
+  env: Env,
+  input: { runId: string; node: WorkflowNodeV1; branchKey: string; stepRunId: string },
+): Promise<Record<string, unknown>> {
+  const componentVersionId = typeof input.node.config.component_version_id === "string" ? input.node.config.component_version_id : null;
+  if (!componentVersionId) throw new ComponentExecutionError("component_version_required", false);
+  const [component, runtime] = await Promise.all([
+    loadComponent(env.DB, componentVersionId),
+    loadWorkflowExecutionContext(env, input.runId, input.branchKey),
+  ]);
+  const allowedFields = parsedJson<string[]>(component.allowedInputFieldsJson, []);
+  assertMappedFieldsAllowed(input.node.inputMapping, allowedFields);
+  const mappedInput = evaluateInputMapping(input.node.inputMapping, runtime.context);
+  const inputSchema = parsedJson<JsonObject>(component.inputSchemaJson, {});
+  const inputErrors = validateJsonSchemaValue(mappedInput, inputSchema);
+  if (inputErrors.length) throw new ComponentExecutionError("component_input_schema_invalid", false);
+  const inputJson = canonicalJson(mappedInput);
+  const inputDigest = `sha256:${await sha256(inputJson)}`;
+  const componentRunId = `${input.stepRunId}:component`;
+  const replay = await env.DB.prepare(`
+    SELECT id, state, output_json AS outputJson, finding_id AS findingId,
+      attempt_count AS attemptCount, input_digest AS inputDigest
+    FROM component_runs WHERE operation_id = ?1 LIMIT 1
+  `).bind(componentRunId).first<ComponentRunReplayRow>();
+  if (replay && replay.inputDigest !== inputDigest) throw new ComponentExecutionError("component_operation_input_changed", false);
+  if (replay?.state === "succeeded" && replay.outputJson && replay.findingId) {
+    const data = safeJsonObject(replay.outputJson);
+    return { port: "success", componentRunId: replay.id, findingId: replay.findingId, cacheHit: false, data };
+  }
+  const attempt = await ensureStepAndAttempt(env, { ...input, inputDigest });
+  const timestamp = now();
+  await env.DB.prepare(`
+    INSERT INTO component_runs (
+      id, installation_id, report_id, workflow_run_id, step_run_id,
+      component_version_id, operation_id, effect_class, state, input_json,
+      input_digest, attempt_count, started_at, created_at, updated_at
+    ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?1, 'read_only', 'running', ?7, ?8, 1, ?9, ?9, ?9)
+    ON CONFLICT(operation_id) DO UPDATE SET state = 'running',
+      attempt_count = component_runs.attempt_count + 1,
+      error_code = NULL, started_at = COALESCE(component_runs.started_at, excluded.started_at),
+      updated_at = excluded.updated_at
+  `).bind(
+    componentRunId, runtime.row.installationId, runtime.row.reportId, runtime.row.runId,
+    input.stepRunId, component.id, inputJson, inputDigest, timestamp,
+  ).run();
+  const cachePolicy = parsedJson<Record<string, unknown>>(component.cachePolicyJson, {});
+  const subjectKeyHash = `sha256:${await sha256(`${runtime.subjectType}:${runtime.subjectReference}`)}`;
+  if (cachePolicy.enabled === true && input.node.config.cache_use !== "fresh_only") {
+    const cached = await env.DB.prepare(`
+      SELECT c.output_json AS outputJson, c.output_digest AS outputDigest, c.finding_id AS findingId
+      FROM component_cache_entries c JOIN findings f ON f.id = c.finding_id
+      WHERE c.component_version_id = ?1 AND c.subject_key_hash = ?2 AND c.input_digest = ?3
+        AND c.expires_at > ?4 AND f.status = 'available' LIMIT 1
+    `).bind(component.id, subjectKeyHash, inputDigest, timestamp).first<{ outputJson: string; outputDigest: string; findingId: string }>();
+    if (cached) {
+      await env.DB.batch([
+        env.DB.prepare(`
+          UPDATE component_runs SET state = 'succeeded', output_json = ?2, output_digest = ?3,
+            finding_id = ?4, cache_hit = 1, finished_at = ?5, updated_at = ?5 WHERE id = ?1
+        `).bind(componentRunId, cached.outputJson, cached.outputDigest, cached.findingId, timestamp),
+        env.DB.prepare(`UPDATE workflow_step_attempts SET status = 'succeeded', response_digest = ?3, finished_at = ?4 WHERE step_run_id = ?1 AND attempt = ?2`)
+          .bind(input.stepRunId, attempt, cached.outputDigest, timestamp),
+      ]);
+      return { port: "success", componentRunId, findingId: cached.findingId, cacheHit: true, data: safeJsonObject(cached.outputJson) };
+    }
+  }
+  if (component.implementationKind === "workers_ai" && runtime.row.authorityMode === "off") {
+    throw new ComponentExecutionError("component_ai_authority_disabled", false);
+  }
+  const budgetReservations = await reserveComponentBudgets(
+    env.DB,
+    component,
+    runtime.row.installationId,
+    runtime.row.runId,
+    componentRunId,
+    attempt,
+  );
+  const aiRunId = component.implementationKind === "workers_ai" ? `${componentRunId}:ai` : null;
+  if (aiRunId) {
+    const outputSchemaDigest = `sha256:${await sha256(component.outputSchemaJson)}`;
+    await env.DB.prepare(`
+      INSERT INTO workflow_ai_runs (
+        id, installation_id, report_id, workflow_run_id, step_run_id,
+        component_version_id, authority_mode, provider, model, prompt_version_id,
+        output_schema_digest, status, input_digest, started_at
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, 'workers_ai', ?8, ?9, ?10, 'running', ?11, ?12)
+      ON CONFLICT(id) DO UPDATE SET
+        status = CASE WHEN workflow_ai_runs.status = 'succeeded' THEN 'succeeded' ELSE 'running' END,
+        started_at = COALESCE(workflow_ai_runs.started_at, excluded.started_at),
+        finished_at = CASE WHEN workflow_ai_runs.status = 'succeeded' THEN workflow_ai_runs.finished_at ELSE NULL END
+    `).bind(
+      aiRunId, runtime.row.installationId, runtime.row.reportId, runtime.row.runId,
+      input.stepRunId, component.id, runtime.row.authorityMode,
+      component.implementationReference, `component:${component.id}:system-v1`,
+      outputSchemaDigest, inputDigest, timestamp,
+    ).run();
+  }
+  try {
+    const implementation = await executeImplementation(env, component, mappedInput, componentRunId, attempt);
+    const outputJson = canonicalJson(implementation.data);
+    if (new TextEncoder().encode(outputJson).byteLength > 262_144) throw new ComponentExecutionError("component_output_too_large", false);
+    const outputErrors = validateJsonSchemaValue(implementation.data, parsedJson<JsonObject>(component.outputSchemaJson, {}));
+    if (outputErrors.length) throw new ComponentExecutionError("component_output_schema_invalid", false);
+    const outputDigest = `sha256:${await sha256(outputJson)}`;
+    const findingId = crypto.randomUUID();
+    const finishedAt = now();
+    const expiresAt = cachePolicy.enabled === true && Number.isInteger(cachePolicy.ttl_seconds) && Number(cachePolicy.ttl_seconds) > 0
+      ? new Date(Date.now() + Math.min(Number(cachePolicy.ttl_seconds), 2_678_400) * 1_000).toISOString() : null;
+    const provenance = {
+      schema_version: "1", component_version_id: component.id, component_run_id: componentRunId,
+      implementation_kind: component.implementationKind, provider: implementation.provider ?? "unknown",
+      ...(implementation.connectionAttemptId ? { connection_attempt_id: implementation.connectionAttemptId } : {}),
+      ...(implementation.providerRequestId ? { provider_request_id: implementation.providerRequestId } : {}),
+      input_units: implementation.inputUnits ?? null, output_units: implementation.outputUnits ?? null,
+    };
+    const uncertainty = Array.isArray(implementation.data.uncertainty) ? implementation.data.uncertainty : [];
+    const statements: D1PreparedStatement[] = [
+      env.DB.prepare(`
+        INSERT INTO findings (
+          id, installation_id, report_id, run_id, step_run_id, component_version_id,
+          finding_type, subject_type, subject_reference, status, confidence, summary,
+          data_json, provenance_json, uncertainty_json, input_digest, output_digest,
+          expires_at, created_at
+        ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, 'available', ?10, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18)
+      `).bind(
+        findingId, runtime.row.installationId, runtime.row.reportId, runtime.row.runId,
+        input.stepRunId, component.id, component.componentKey, runtime.subjectType,
+        runtime.subjectReference, confidence(implementation.data), findingSummary(implementation.data, component.componentKey),
+        outputJson, canonicalJson(provenance), canonicalJson(uncertainty), inputDigest, outputDigest,
+        expiresAt, finishedAt,
+      ),
+      env.DB.prepare(`
+        UPDATE component_runs SET state = 'succeeded', output_json = ?2, output_digest = ?3,
+          finding_id = ?4, finished_at = ?5, updated_at = ?5 WHERE id = ?1
+      `).bind(componentRunId, outputJson, outputDigest, findingId, finishedAt),
+    ];
+    if (expiresAt) statements.push(env.DB.prepare(`
+      INSERT INTO component_cache_entries (
+        id, installation_id, component_version_id, subject_key_hash, input_digest,
+        finding_id, output_json, output_digest, created_at, expires_at
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)
+      ON CONFLICT(component_version_id, subject_key_hash, input_digest) DO UPDATE SET
+        finding_id = excluded.finding_id, output_json = excluded.output_json,
+        output_digest = excluded.output_digest, created_at = excluded.created_at,
+        expires_at = excluded.expires_at
+    `).bind(
+      crypto.randomUUID(), runtime.row.installationId, component.id, subjectKeyHash,
+      inputDigest, findingId, outputJson, outputDigest, finishedAt, expiresAt,
+    ));
+    await env.DB.batch(statements);
+    if (aiRunId) {
+      await env.DB.prepare(`
+        UPDATE workflow_ai_runs SET status = 'succeeded', output_json = ?2,
+          output_digest = ?3, validation_errors_json = '[]', input_units = ?4,
+          output_units = ?5, provider_request_id = ?6, finished_at = ?7
+        WHERE id = ?1
+      `).bind(
+        aiRunId, outputJson, outputDigest, implementation.inputUnits ?? null,
+        implementation.outputUnits ?? null, implementation.providerRequestId ?? null,
+        finishedAt,
+      ).run();
+    }
+    await settleComponentBudgets(env.DB, budgetReservations, true);
+    await finishStepAttempt(env.DB, input.stepRunId, attempt, { status: "succeeded", outputDigest });
+    return { port: "success", componentRunId, findingId, cacheHit: false, data: implementation.data };
+  } catch (error) {
+    const failure = error instanceof ComponentExecutionError
+      ? error : new ComponentExecutionError("component_execution_failed", true, 5);
+    const finishedAt = now();
+    await env.DB.prepare(`
+      UPDATE component_runs SET state = 'failed', error_code = ?2, finished_at = ?3,
+        updated_at = ?3 WHERE id = ?1
+    `).bind(componentRunId, failure.code, finishedAt).run();
+    if (aiRunId) {
+      const invalid = ["component_ai_response_invalid", "component_output_schema_invalid", "component_output_invalid"].includes(failure.code);
+      await env.DB.prepare(`
+        UPDATE workflow_ai_runs SET status = ?2, validation_errors_json = ?3,
+          finished_at = ?4 WHERE id = ?1 AND status != 'succeeded'
+      `).bind(
+        aiRunId, invalid ? "invalid" : "failed",
+        canonicalJson([{ code: failure.code }]), finishedAt,
+      ).run();
+    }
+    await finishStepAttempt(env.DB, input.stepRunId, attempt, {
+      status: failure.retryable ? "retryable_failed" : "permanent_failed",
+      errorCode: failure.code,
+    });
+    await settleComponentBudgets(env.DB, budgetReservations, false);
+    throw failure;
+  }
+}
+
+export async function executeAssistantReadOnlyComponent(
+  env: Env,
+  input: {
+    reportId: string;
+    componentVersionId: string;
+    componentInput: JsonObject;
+    operationId: string;
+    actorId: string;
+    source?: "assistant" | "operator" | "routing";
+  },
+): Promise<{ componentRunId: string; findingId: string; data: JsonObject; idempotentReplay: boolean }> {
+  const [component, report] = await Promise.all([
+    loadComponent(env.DB, input.componentVersionId),
+    env.DB.prepare(`
+      SELECT r.id, r.installation_id AS installationId, r.queue_id AS queueId,
+        r.public_reference AS publicReference,
+        (SELECT target_type FROM report_targets WHERE report_id = r.id ORDER BY created_at, id LIMIT 1) AS subjectType,
+        (SELECT target_reference FROM report_targets WHERE report_id = r.id ORDER BY created_at, id LIMIT 1) AS subjectReference
+      FROM reports r WHERE r.id = ?1 LIMIT 1
+    `).bind(input.reportId).first<{
+      id: string; installationId: string; queueId: string | null; publicReference: string;
+      subjectType: string | null; subjectReference: string | null;
+    }>(),
+  ]);
+  if (!report) throw new ComponentExecutionError("component_report_context_missing", false);
+  const inputErrors = validateJsonSchemaValue(input.componentInput, parsedJson<JsonObject>(component.inputSchemaJson, {}));
+  if (inputErrors.length) throw new ComponentExecutionError("component_input_schema_invalid", false);
+  const inputJson = canonicalJson(input.componentInput);
+  if (new TextEncoder().encode(inputJson).byteLength > 131_072) throw new ComponentExecutionError("component_input_too_large", false);
+  const inputDigest = `sha256:${await sha256(inputJson)}`;
+  const source = input.source ?? "assistant";
+  const componentRunId = `${source}:${input.operationId}:component`;
+  const replay = await env.DB.prepare(`SELECT id, state, output_json AS outputJson, finding_id AS findingId, input_digest AS inputDigest FROM component_runs WHERE operation_id = ?1 LIMIT 1`)
+    .bind(componentRunId).first<{ id: string; state: string; outputJson: string | null; findingId: string | null; inputDigest: string }>();
+  if (replay && replay.inputDigest !== inputDigest) throw new ComponentExecutionError("component_operation_input_changed", false);
+  if (replay?.state === "succeeded" && replay.outputJson && replay.findingId) {
+    return { componentRunId: replay.id, findingId: replay.findingId, data: safeJsonObject(replay.outputJson), idempotentReplay: true };
+  }
+  const timestamp = now();
+  await env.DB.prepare(`
+    INSERT INTO component_runs (
+      id, installation_id, report_id, component_version_id, operation_id,
+      effect_class, state, input_json, input_digest, attempt_count,
+      started_at, created_at, updated_at
+    ) VALUES (?1, ?2, ?3, ?4, ?1, 'read_only', 'running', ?5, ?6, 1, ?7, ?7, ?7)
+    ON CONFLICT(operation_id) DO UPDATE SET
+      state = 'running', attempt_count = component_runs.attempt_count + 1,
+      error_code = NULL, updated_at = excluded.updated_at
+  `).bind(componentRunId, report.installationId, report.id, component.id, inputJson, inputDigest, timestamp).run();
+  const current = await env.DB.prepare(`SELECT attempt_count AS attempt FROM component_runs WHERE id = ?1`).bind(componentRunId).first<{ attempt: number }>();
+  const attempt = Number(current?.attempt ?? 1);
+  const reservations = await reserveScopedBudgets(env.DB, {
+    installationId: report.installationId,
+    scopes: [
+      ...(source === "assistant" ? [{ type: "assistant" as const, id: input.actorId }] : []),
+      { type: "component", id: component.id },
+      ...(report.queueId ? [{ type: "queue", id: report.queueId }] : []),
+    ],
+    metric: "calls", amount: 1, operationType: `${source}_component`,
+    operationId: componentRunId, attemptId: String(attempt),
+  });
+  try {
+    const implementation = await executeImplementation(env, component, input.componentInput, componentRunId, attempt);
+    const outputJson = canonicalJson(implementation.data);
+    if (new TextEncoder().encode(outputJson).byteLength > 262_144) throw new ComponentExecutionError("component_output_too_large", false);
+    if (validateJsonSchemaValue(implementation.data, parsedJson<JsonObject>(component.outputSchemaJson, {})).length) {
+      throw new ComponentExecutionError("component_output_schema_invalid", false);
+    }
+    const outputDigest = `sha256:${await sha256(outputJson)}`;
+    const findingId = crypto.randomUUID();
+    const finishedAt = now();
+    await env.DB.batch([
+      env.DB.prepare(`
+        INSERT INTO findings (
+          id, installation_id, report_id, component_version_id,
+          finding_type, subject_type, subject_reference, status, confidence,
+          summary, data_json, provenance_json, uncertainty_json,
+          input_digest, output_digest, created_at
+        ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, 'available', ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15)
+      `).bind(
+        findingId, report.installationId, report.id, component.id, component.componentKey,
+        report.subjectType ?? "report", report.subjectReference ?? report.publicReference,
+        confidence(implementation.data), findingSummary(implementation.data, component.componentKey),
+        outputJson, canonicalJson({
+          schema_version: "1",
+          source: source === "assistant" ? "assistant_safe_enrichment" : source === "routing" ? "routing_intake_enrichment" : "operator_explicit_enrichment",
+          actor_id: input.actorId,
+          component_version_id: component.id, component_run_id: componentRunId,
+          implementation_kind: component.implementationKind, provider: implementation.provider ?? "unknown",
+          connection_attempt_id: implementation.connectionAttemptId ?? null,
+          provider_request_id: implementation.providerRequestId ?? null,
+          input_units: implementation.inputUnits ?? null, output_units: implementation.outputUnits ?? null,
+        }), canonicalJson(Array.isArray(implementation.data.uncertainty) ? implementation.data.uncertainty : []),
+        inputDigest, outputDigest, finishedAt,
+      ),
+      env.DB.prepare(`UPDATE component_runs SET state = 'succeeded', output_json = ?2, output_digest = ?3, finding_id = ?4, finished_at = ?5, updated_at = ?5 WHERE id = ?1`)
+        .bind(componentRunId, outputJson, outputDigest, findingId, 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, ?3, ?4, ?5, 'finding', ?6, ?7, ?8)`)
+        .bind(
+          crypto.randomUUID(), `${source}-enrichment:${componentRunId}`,
+          source === "assistant" ? "assistant.enrichment_executed" : source === "routing" ? "routing.intake_enrichment_executed" : "report.enrichment_executed",
+          source === "routing" ? "system" : "operator_user", input.actorId, findingId,
+          canonicalJson({ reportId: report.id, componentVersionId: component.id, componentRunId, outputDigest }),
+          finishedAt,
+        ),
+    ]);
+    await settleScopedBudgets(env.DB, reservations, true);
+    return { componentRunId, findingId, data: implementation.data, idempotentReplay: false };
+  } catch (error) {
+    const failure = error instanceof ComponentExecutionError ? error : new ComponentExecutionError("component_execution_failed", true, 5);
+    await env.DB.prepare(`UPDATE component_runs SET state = 'failed', error_code = ?2, finished_at = ?3, updated_at = ?3 WHERE id = ?1`)
+      .bind(componentRunId, failure.code, now()).run();
+    await settleScopedBudgets(env.DB, reservations, false);
+    throw failure;
+  }
+}
+
+export async function executeRoutingReadOnlyComponent(
+  env: Env,
+  input: {
+    reportId: string;
+    componentVersionId: string;
+    inputMapping: Record<string, JsonValue>;
+    context: JsonObject;
+    operationId: string;
+  },
+): Promise<{ componentKey: string; componentRunId: string; findingId: string; data: JsonObject; idempotentReplay: boolean }> {
+  const component = await loadComponent(env.DB, input.componentVersionId);
+  assertMappedFieldsAllowed(input.inputMapping, parsedJson<string[]>(component.allowedInputFieldsJson, []));
+  const componentInput = evaluateInputMapping(input.inputMapping, input.context);
+  const result = await executeAssistantReadOnlyComponent(env, {
+    reportId: input.reportId,
+    componentVersionId: component.id,
+    componentInput,
+    operationId: input.operationId,
+    actorId: "routing-service",
+    source: "routing",
+  });
+  return { componentKey: component.componentKey, ...result };
+}