create-safest-tools 0.2.0

package/template/src/workflow-effects.ts

@@ -0,0 +1,316 @@
+import { canonicalJson } from "./audit";
+import { loadWorkflowExecutionContext } from "./component-executor";
+import { decryptReportContact, sha256 } from "./report-crypto";
+import type { DeliveryJob } from "./report-types";
+import { evaluateInputMapping } from "./workflow-expressions";
+import type { JsonObject, JsonValue, WorkflowNodeV1 } from "./workflow-platform-types";
+
+interface EffectRunRow {
+  id: string;
+  installationId: string;
+  reportId: string;
+  workflowVersionId: string;
+  authorityMode: string;
+  queueId: string | null;
+  queueVersionId: string | null;
+  publicReference: string;
+  reportState: string;
+  policyVersionId: string | null;
+  locale: string;
+}
+
+export class WorkflowEffectError extends Error {
+  constructor(readonly code: string, readonly retryable = false, readonly delaySeconds = 5) {
+    super(code);
+    this.name = "WorkflowEffectError";
+  }
+}
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+async function effectRun(db: D1Database, runId: string): Promise<EffectRunRow> {
+  const row = await db.prepare(`
+    SELECT wr.id, wr.installation_id AS installationId, wr.report_id AS reportId,
+      wr.workflow_version_id AS workflowVersionId, wr.authority_mode AS authorityMode,
+      wr.queue_id AS queueId, wr.queue_version_id AS queueVersionId,
+      r.public_reference AS publicReference, r.state AS reportState,
+      r.policy_version_id AS policyVersionId, r.locale
+    FROM workflow_runs wr JOIN reports r ON r.id = wr.report_id WHERE wr.id = ?1 LIMIT 1
+  `).bind(runId).first<EffectRunRow>();
+  if (!row) throw new WorkflowEffectError("workflow_effect_context_missing");
+  return row;
+}
+
+function primitive(value: JsonValue, name: string): string {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return String(value);
+  throw new WorkflowEffectError(`workflow_message_${name}_invalid`);
+}
+
+function renderTemplate(template: string, variables: JsonObject): string {
+  const used = new Set<string>();
+  const rendered = template.replace(/\{\{\s*([A-Za-z0-9_-]{1,80})\s*\}\}/gu, (_match, key: string) => {
+    used.add(key);
+    if (!(key in variables)) throw new WorkflowEffectError("workflow_message_variable_missing");
+    return primitive(variables[key]!, "variable");
+  });
+  if (/\{\{|\}\}/u.test(rendered)) throw new WorkflowEffectError("workflow_message_template_invalid");
+  if (rendered.trim().length < 1 || rendered.length > 10_000) throw new WorkflowEffectError("workflow_message_render_invalid");
+  if (Object.keys(variables).some((key) => !used.has(key) && key !== "body")) throw new WorkflowEffectError("workflow_message_variable_unused");
+  return rendered;
+}
+
+export async function sendWorkflowMessage(
+  env: Env,
+  input: { runId: string; node: WorkflowNodeV1; branchKey: string },
+): Promise<Record<string, unknown>> {
+  const run = await effectRun(env.DB, input.runId);
+  if (run.authorityMode === "shadow") throw new WorkflowEffectError("shadow_effect_prohibited");
+  const audience = typeof input.node.config.audience === "string" ? input.node.config.audience : null;
+  const templateVersionId = typeof input.node.config.template_version_id === "string" ? input.node.config.template_version_id : null;
+  if (!audience || !["reporter", "affected_user", "internal"].includes(audience) || !templateVersionId) throw new WorkflowEffectError("workflow_message_configuration_invalid");
+  const operationKey = `workflow-message:${run.id}:${input.node.id}:${input.branchKey || "main"}`;
+  const existing = await env.DB.prepare(`SELECT id, delivery_state AS deliveryState FROM case_messages WHERE report_id = ?1 AND idempotency_key = ?2 LIMIT 1`)
+    .bind(run.reportId, operationKey).first<{ id: string; deliveryState: string }>();
+  if (existing) return { port: "sent", messageId: existing.id, deliveryState: existing.deliveryState, idempotentReplay: true };
+  const context = await loadWorkflowExecutionContext(env, run.id, input.branchKey);
+  const variables = evaluateInputMapping(input.node.inputMapping, context.context);
+  let body: string;
+  if (audience === "internal") {
+    body = typeof variables.body === "string" ? variables.body.trim() : "";
+    if (!body || body.length > 10_000) throw new WorkflowEffectError("workflow_message_body_invalid");
+  } else {
+    const template = await env.DB.prepare(`
+      SELECT body_template AS bodyTemplate FROM message_template_versions
+      WHERE id = ?1 AND installation_id = ?2 AND audience = ?3
+        AND published_at IS NOT NULL LIMIT 1
+    `).bind(templateVersionId, run.installationId, audience).first<{ bodyTemplate: string }>();
+    if (!template) throw new WorkflowEffectError("workflow_message_template_unavailable");
+    body = renderTemplate(template.bodyTemplate, variables);
+  }
+  const participant = audience === "internal" ? null : await env.DB.prepare(`
+    SELECT id, reference, contact_mode AS contactMode, contact_ciphertext AS contactCiphertext FROM report_participants
+    WHERE report_id = ?1 AND audience = ?2 LIMIT 1
+  `).bind(run.reportId, audience).first<{ id: string; reference: string | null; contactMode: string; contactCiphertext: string | null }>();
+  const deliveryChannels = Array.isArray(input.node.config.delivery_channels)
+    ? input.node.config.delivery_channels.filter((entry): entry is string => typeof entry === "string")
+    : audience === "internal" ? [] : ["customer_webhook", "email"];
+  const emailBinding = (env as unknown as { EMAIL?: { send(message: Record<string, unknown>): Promise<{ messageId?: string }> } }).EMAIL;
+  const emailAddress = participant?.contactCiphertext
+    ? (await decryptReportContact(env.CREDENTIAL_ENCRYPTION_KEY, participant.contactCiphertext, run.reportId, audience as "reporter" | "affected_user")).trim().toLowerCase()
+    : "";
+  const emailFrom = env.EMAIL_FROM_ADDRESS?.trim().toLowerCase() ?? "";
+  const emailEnabled = Boolean(
+    audience !== "internal" && deliveryChannels.includes("email")
+    && participant?.contactMode === "customer_notification"
+    && /^[^\s@]+@[^\s@]+\.[^\s@]+$/u.test(emailAddress)
+    && /^[^\s@]+@[^\s@]+\.[^\s@]+$/u.test(emailFrom)
+    && emailBinding,
+  );
+  const notificationEnabled = !emailEnabled && deliveryChannels.includes("customer_webhook") && Boolean((participant?.reference || participant?.contactCiphertext) && participant.contactMode === "customer_notification"
+    && env.NOTIFICATION_WEBHOOK_URL?.trim() && env.NOTIFICATION_WEBHOOK_SECRET?.trim());
+  const externalDeliveryEnabled = emailEnabled || notificationEnabled;
+  const messageId = crypto.randomUUID();
+  const conversationId = `conversation:${audience}:${run.reportId}`;
+  const timestamp = now();
+  const statements: D1PreparedStatement[] = [
+    env.DB.prepare(`
+      INSERT OR IGNORE INTO conversations (
+        id, installation_id, report_id, audience, participant_id, status,
+        locale, created_at, updated_at
+      ) VALUES (?1, ?2, ?3, ?4, ?5, 'open', ?6, ?7, ?7)
+    `).bind(conversationId, run.installationId, run.reportId, audience, participant?.id ?? null, run.locale, timestamp),
+    env.DB.prepare(`
+      INSERT INTO case_messages (
+        id, report_id, audience, direction, sender_type, sender_id, body,
+        template_version_id, automated, delivery_state, created_at,
+        idempotency_key, conversation_id, workflow_run_id, audience_checked_at
+      ) VALUES (?1, ?2, ?3, ?4, 'system', ?5, ?6, ?7, 1, ?8, ?9, ?10, ?11, ?5, ?9)
+    `).bind(
+      messageId, run.reportId, audience, audience === "internal" ? "internal" : "outbound",
+      run.id, body, templateVersionId, audience === "internal" ? "not_required" : externalDeliveryEnabled ? "queued" : "suppressed",
+      timestamp, operationKey, conversationId,
+    ),
+  ];
+  let job: DeliveryJob | null = null;
+  if (audience !== "internal") {
+    const noticeId = crypto.randomUUID();
+    statements.push(env.DB.prepare(`
+      INSERT INTO notices (
+        id, report_id, audience, template_version_id, rendered_body,
+        delivery_state, created_at, updated_at, idempotency_key, message_id
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?7, ?8, ?9)
+    `).bind(
+      noticeId, run.reportId, audience, templateVersionId, body,
+      externalDeliveryEnabled ? "queued" : "suppressed", timestamp, operationKey, messageId,
+    ));
+    if (emailEnabled && participant) {
+      const emailDeliveryId = crypto.randomUUID();
+      statements.push(env.DB.prepare(`
+        INSERT INTO email_deliveries (
+          id, installation_id, message_id, audience, recipient_hash,
+          provider, state, attempt_count, next_attempt_at, created_at, updated_at
+        ) VALUES (?1, ?2, ?3, ?4, ?5, 'cloudflare_email_service', 'pending', 0, ?6, ?6, ?6)
+      `).bind(
+        emailDeliveryId, run.installationId, messageId, audience,
+        `sha256:${await sha256(`email-recipient-v1:${env.RATE_LIMIT_PEPPER}:${emailAddress}`)}`,
+        timestamp,
+      ));
+      job = { version: 1, jobId: `email:${emailDeliveryId}`, type: "deliver_email", outboxId: emailDeliveryId };
+    } else if (notificationEnabled && participant) {
+      const notificationId = crypto.randomUUID();
+      statements.push(env.DB.prepare(`
+        INSERT INTO notification_outbox (
+          id, notice_id, idempotency_key, channel, payload_json, status,
+          next_attempt_at, created_at, updated_at
+        ) VALUES (?1, ?2, ?3, 'customer_webhook', ?4, 'pending', ?5, ?5, ?5)
+      `).bind(notificationId, noticeId, `notice:${noticeId}`, canonicalJson({
+        version: 1,
+        event: "report.message.available",
+        notification_id: notificationId,
+        report_reference: run.publicReference,
+        ...(participant.reference ? { recipient_reference: participant.reference } : {}),
+        audience,
+        message: body,
+      }), timestamp));
+      job = { version: 1, jobId: `notification:${notificationId}`, type: "deliver_notification", outboxId: notificationId };
+    }
+  }
+  statements.push(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.message_created', 'system', ?3, 'message', ?4, ?5, ?6)
+  `).bind(crypto.randomUUID(), operationKey, run.id, messageId, canonicalJson({
+    reportId: run.reportId, audience, templateVersionId,
+    deliveryChannels, emailEnabled, notificationEnabled,
+  }), timestamp));
+  await env.DB.batch(statements);
+  if (job) await env.REPORT_JOBS.send(job, { contentType: "json" }).catch(() => {});
+  return { port: "sent", messageId, deliveryState: audience === "internal" ? "not_required" : externalDeliveryEnabled ? "queued" : "suppressed", idempotentReplay: false };
+}
+
+function stringList(value: JsonValue | undefined, code: string): string[] {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) throw new WorkflowEffectError(code);
+  return value as string[];
+}
+
+export async function recordWorkflowDecision(
+  env: Env,
+  input: { runId: string; node: WorkflowNodeV1; branchKey: string },
+): Promise<Record<string, unknown>> {
+  const run = await effectRun(env.DB, input.runId);
+  if (run.authorityMode === "shadow") throw new WorkflowEffectError("shadow_effect_prohibited");
+  const operationKey = `workflow-decision:${run.id}:${input.node.id}:${input.branchKey || "main"}`;
+  const existing = await env.DB.prepare(`SELECT id, decision_code AS decisionCode FROM decisions WHERE report_id = ?1 AND idempotency_key = ?2 LIMIT 1`)
+    .bind(run.reportId, operationKey).first<{ id: string; decisionCode: string }>();
+  if (existing) return { port: "recorded", decisionId: existing.id, decisionCode: existing.decisionCode, idempotentReplay: true };
+  const policyVersionId = typeof input.node.config.policy_version_id === "string" ? input.node.config.policy_version_id : null;
+  if (!policyVersionId || policyVersionId !== run.policyVersionId) throw new WorkflowEffectError("workflow_decision_policy_mismatch");
+  if (!await env.DB.prepare(`SELECT id FROM policy_versions WHERE id = ?1 AND published_at IS NOT NULL`).bind(policyVersionId).first()) {
+    throw new WorkflowEffectError("workflow_decision_policy_unavailable");
+  }
+  const context = await loadWorkflowExecutionContext(env, run.id, input.branchKey);
+  const mapped = evaluateInputMapping(input.node.inputMapping, context.context);
+  const decisionCode = typeof mapped.decision_code === "string" ? mapped.decision_code : null;
+  const policyCode = typeof mapped.policy_code === "string" ? mapped.policy_code : null;
+  const rationale = typeof mapped.rationale === "string" ? mapped.rationale.trim() : null;
+  if (!decisionCode || decisionCode.length > 100 || !policyCode || policyCode.length > 100 || !rationale || rationale.length > 2_000) {
+    throw new WorkflowEffectError("workflow_decision_input_invalid");
+  }
+  const evidenceReferences = stringList(mapped.evidence_references ?? [], "workflow_decision_evidence_invalid");
+  const findingIds = stringList(mapped.finding_ids ?? [], "workflow_decision_findings_invalid");
+  const [evidence, findings] = await Promise.all([
+    evidenceReferences.length ? env.DB.prepare(`SELECT reference FROM evidence_references WHERE report_id = ?1`).bind(run.reportId).all<{ reference: string }>() : Promise.resolve({ results: [] as { reference: string }[] }),
+    findingIds.length ? env.DB.prepare(`SELECT id FROM findings WHERE report_id = ?1 AND run_id = ?2 AND status = 'available'`).bind(run.reportId, run.id).all<{ id: string }>() : Promise.resolve({ results: [] as { id: string }[] }),
+  ]);
+  const evidenceSet = new Set(evidence.results.map((entry) => entry.reference));
+  const findingSet = new Set(findings.results.map((entry) => entry.id));
+  if (evidenceReferences.some((entry) => !evidenceSet.has(entry)) || findingIds.some((entry) => !findingSet.has(entry))) {
+    throw new WorkflowEffectError("workflow_decision_evidence_not_visible");
+  }
+  const decisionId = crypto.randomUUID();
+  const timestamp = now();
+  const nextState = typeof input.node.config.report_state === "string" ? input.node.config.report_state : null;
+  const allowedStates = ["human_review", "awaiting_reporter", "resolved_by_ai", "human_review_requested", "closed"];
+  if (nextState && !allowedStates.includes(nextState)) throw new WorkflowEffectError("workflow_decision_state_invalid");
+  const statements: D1PreparedStatement[] = [
+    env.DB.prepare(`
+      INSERT INTO decisions (
+        id, report_id, decision_code, policy_version_id, policy_code, rationale,
+        evidence_references_json, maker_type, maker_id, queue_version_id,
+        proposed_action_code, created_at, idempotency_key
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, 'ai', ?8, ?9, ?10, ?11, ?12)
+    `).bind(
+      decisionId, run.reportId, decisionCode, policyVersionId, policyCode,
+      rationale, canonicalJson([...evidenceReferences, ...findingIds.map((id) => `finding:${id}`)]),
+      `workflow:${run.id}`, run.queueVersionId,
+      typeof mapped.proposed_action_code === "string" ? mapped.proposed_action_code : null,
+      timestamp, operationKey,
+    ),
+    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.decision_recorded', 'system', ?3, 'decision', ?4, ?5, ?6)
+    `).bind(crypto.randomUUID(), operationKey, run.id, decisionId, canonicalJson({
+      reportId: run.reportId, decisionCode, policyVersionId, policyCode,
+      evidenceReferences, findingIds, authorityMode: run.authorityMode,
+    }), timestamp),
+  ];
+  if (nextState && nextState !== run.reportState) {
+    statements.push(
+      env.DB.prepare(`UPDATE reports SET state = ?2, resolved_at = CASE WHEN ?2 IN ('resolved_by_ai','closed') THEN ?3 ELSE resolved_at END, updated_at = ?3 WHERE id = ?1`)
+        .bind(run.reportId, nextState, timestamp),
+      env.DB.prepare(`
+        INSERT INTO report_state_history (
+          id, report_id, from_state, to_state, reason_code, actor_type, actor_id, created_at
+        ) VALUES (?1, ?2, ?3, ?4, ?5, 'system', ?6, ?7)
+      `).bind(crypto.randomUUID(), run.reportId, run.reportState, nextState, decisionCode, `workflow:${run.id}`, timestamp),
+    );
+  }
+  await env.DB.batch(statements);
+  return { port: "recorded", decisionId, decisionCode, idempotentReplay: false };
+}
+
+export async function handoffWorkflowReport(
+  env: Env,
+  input: { runId: string; node: WorkflowNodeV1; branchKey: string },
+): Promise<Record<string, unknown>> {
+  const run = await effectRun(env.DB, input.runId);
+  if (run.authorityMode === "shadow") throw new WorkflowEffectError("shadow_effect_prohibited");
+  const context = await loadWorkflowExecutionContext(env, run.id, input.branchKey);
+  const mapped = evaluateInputMapping(input.node.inputMapping, context.context);
+  const queueId = typeof mapped.queue_id === "string" ? mapped.queue_id : null;
+  const allowed = Array.isArray(input.node.config.allowed_queue_ids)
+    ? input.node.config.allowed_queue_ids.filter((entry): entry is string => typeof entry === "string") : [];
+  if (!queueId || !allowed.includes(queueId)) throw new WorkflowEffectError("workflow_handoff_queue_denied");
+  const queue = await env.DB.prepare(`SELECT id, active_version_id AS activeVersionId FROM queue_definitions WHERE id = ?1 AND status = 'active' LIMIT 1`)
+    .bind(queueId).first<{ id: string; activeVersionId: string | null }>();
+  if (!queue || !queue.activeVersionId) throw new WorkflowEffectError("workflow_handoff_queue_unavailable");
+  const operationKey = `workflow-handoff:${run.id}:${input.node.id}:${input.branchKey || "main"}`;
+  const existing = await env.DB.prepare(`SELECT id FROM report_queue_assignments WHERE report_id = ?1 AND assigned_by_id = ?2 LIMIT 1`)
+    .bind(run.reportId, operationKey).first<{ id: string }>();
+  if (existing) return { port: "handed_off", queueId, queueVersionId: queue.activeVersionId, assignmentId: existing.id, idempotentReplay: true };
+  const assignmentId = crypto.randomUUID();
+  const timestamp = now();
+  await env.DB.batch([
+    env.DB.prepare(`UPDATE report_queue_assignments SET ended_at = ?2 WHERE report_id = ?1 AND ended_at IS NULL`).bind(run.reportId, timestamp),
+    env.DB.prepare(`
+      INSERT INTO report_queue_assignments (
+        id, report_id, queue_id, queue_version_id, assignment_kind,
+        reason_json, assigned_by_type, assigned_by_id, assigned_at
+      ) VALUES (?1, ?2, ?3, ?4, 'handoff', ?5, 'system', ?6, ?7)
+    `).bind(assignmentId, run.reportId, queueId, queue.activeVersionId, canonicalJson({ workflow_run_id: run.id, node_id: input.node.id }), operationKey, timestamp),
+    env.DB.prepare(`UPDATE reports SET queue_id = ?2, queue_version_id = ?3, updated_at = ?4 WHERE id = ?1`)
+      .bind(run.reportId, queueId, queue.activeVersionId, timestamp),
+    env.DB.prepare(`UPDATE workflow_runs SET queue_id = ?2, queue_version_id = ?3, updated_at = ?4, revision = revision + 1 WHERE id = ?1`)
+      .bind(run.id, queueId, queue.activeVersionId, timestamp),
+  ]);
+  return { port: "handed_off", queueId, queueVersionId: queue.activeVersionId, assignmentId, idempotentReplay: false };
+}
+
+export async function outputDigest(value: unknown): Promise<string> {
+  return `sha256:${await sha256(canonicalJson(value))}`;
+}

package/template/src/workflow-expressions.ts

@@ -0,0 +1,191 @@
+import type { JsonObject, JsonValue } from "./workflow-platform-types";
+
+export class WorkflowExpressionError extends Error {
+  constructor(readonly code: string) {
+    super(code);
+    this.name = "WorkflowExpressionError";
+  }
+}
+
+const pathPattern = /^\$\.(?:[A-Za-z0-9_-]+)(?:\.[A-Za-z0-9_-]+)*$/u;
+const interpolationPattern = /\{\{\s*(\$\.(?:[A-Za-z0-9_-]+)(?:\.[A-Za-z0-9_-]+)*)\s*\}\}/gu;
+const prohibitedSegments = new Set(["__proto__", "prototype", "constructor"]);
+
+function directPath(context: JsonObject, path: string): JsonValue | undefined {
+  if (!pathPattern.test(path)) throw new WorkflowExpressionError("expression_path_invalid");
+  let current: JsonValue | undefined = context;
+  for (const segment of path.slice(2).split(".")) {
+    if (prohibitedSegments.has(segment) || !current || typeof current !== "object" || Array.isArray(current)) return undefined;
+    current = current[segment];
+  }
+  return current;
+}
+
+function primitive(value: JsonValue, code: string): string | number | boolean | null {
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+  throw new WorkflowExpressionError(code);
+}
+
+function numeric(value: JsonValue, code: string): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) throw new WorkflowExpressionError(code);
+  return value;
+}
+
+function truth(value: JsonValue): boolean {
+  if (typeof value !== "boolean") throw new WorkflowExpressionError("expression_boolean_required");
+  return value;
+}
+
+function operatorObject(value: JsonObject): [string, JsonValue] | null {
+  const entries = Object.entries(value);
+  return entries.length === 1 && entries[0]![0].startsWith("$") ? entries[0]! : null;
+}
+
+export function evaluateWorkflowExpression(
+  expression: JsonValue,
+  context: JsonObject,
+  depth = 0,
+): JsonValue {
+  if (depth > 20) throw new WorkflowExpressionError("expression_depth_exceeded");
+  if (expression === null || typeof expression === "number" || typeof expression === "boolean") return expression;
+  if (typeof expression === "string") {
+    if (expression.startsWith("$.") && pathPattern.test(expression)) return directPath(context, expression) ?? null;
+    if (expression.length > 10_000) throw new WorkflowExpressionError("expression_string_too_long");
+    return expression.replace(interpolationPattern, (_match, path: string) => {
+      const value = directPath(context, path);
+      const result = value === undefined || value === null ? "" : primitive(value, "expression_interpolation_primitive_required");
+      return String(result);
+    });
+  }
+  if (Array.isArray(expression)) {
+    if (expression.length > 100) throw new WorkflowExpressionError("expression_array_too_large");
+    return expression.map((entry) => evaluateWorkflowExpression(entry, context, depth + 1));
+  }
+  const operation = operatorObject(expression);
+  if (!operation) {
+    const output: JsonObject = {};
+    for (const [key, value] of Object.entries(expression)) {
+      if (prohibitedSegments.has(key)) throw new WorkflowExpressionError("expression_property_prohibited");
+      output[key] = evaluateWorkflowExpression(value, context, depth + 1);
+    }
+    return output;
+  }
+  const [operator, operand] = operation;
+  if (operator === "$literal") return operand;
+  if (operator === "$path") {
+    if (typeof operand !== "string") throw new WorkflowExpressionError("expression_path_invalid");
+    return directPath(context, operand) ?? null;
+  }
+  const list = Array.isArray(operand) ? operand : [operand];
+  const values = () => list.map((entry) => evaluateWorkflowExpression(entry, context, depth + 1));
+  if (operator === "$coalesce") return values().find((entry) => entry !== null) ?? null;
+  if (operator === "$concat") return values().map((entry) => String(primitive(entry, "expression_concat_primitive_required") ?? "")).join("");
+  if (operator === "$lower" || operator === "$upper") {
+    const value = evaluateWorkflowExpression(operand, context, depth + 1);
+    if (typeof value !== "string") throw new WorkflowExpressionError("expression_string_required");
+    return operator === "$lower" ? value.toLocaleLowerCase("en-US") : value.toLocaleUpperCase("en-US");
+  }
+  if (operator === "$length") {
+    const value = evaluateWorkflowExpression(operand, context, depth + 1);
+    if (typeof value !== "string" && !Array.isArray(value)) throw new WorkflowExpressionError("expression_length_value_invalid");
+    return value.length;
+  }
+  if (operator === "$not") return !truth(evaluateWorkflowExpression(operand, context, depth + 1));
+  if (operator === "$and" || operator === "$or") {
+    const booleans = values().map(truth);
+    return operator === "$and" ? booleans.every(Boolean) : booleans.some(Boolean);
+  }
+  if (["$eq", "$neq", "$gt", "$gte", "$lt", "$lte"].includes(operator)) {
+    const [left, right, ...rest] = values();
+    if (left === undefined || right === undefined || rest.length) throw new WorkflowExpressionError("expression_binary_arity_invalid");
+    if (operator === "$eq" || operator === "$neq") {
+      const equal = JSON.stringify(left) === JSON.stringify(right);
+      return operator === "$eq" ? equal : !equal;
+    }
+    const a = numeric(left, "expression_numeric_required");
+    const b = numeric(right, "expression_numeric_required");
+    if (operator === "$gt") return a > b;
+    if (operator === "$gte") return a >= b;
+    if (operator === "$lt") return a < b;
+    return a <= b;
+  }
+  if (operator === "$in") {
+    const [needle, haystack, ...rest] = values();
+    if (needle === undefined || !Array.isArray(haystack) || rest.length || haystack.length > 100) throw new WorkflowExpressionError("expression_membership_invalid");
+    return haystack.some((entry) => JSON.stringify(entry) === JSON.stringify(needle));
+  }
+  if (["$add", "$subtract", "$multiply", "$divide"].includes(operator)) {
+    const numbers = values().map((entry) => numeric(entry, "expression_numeric_required"));
+    if (numbers.length < 2 || numbers.length > 20) throw new WorkflowExpressionError("expression_arithmetic_arity_invalid");
+    let result = numbers[0]!;
+    for (const value of numbers.slice(1)) {
+      if (operator === "$add") result += value;
+      else if (operator === "$subtract") result -= value;
+      else if (operator === "$multiply") result *= value;
+      else {
+        if (value === 0) throw new WorkflowExpressionError("expression_division_by_zero");
+        result /= value;
+      }
+      if (!Number.isFinite(result) || Math.abs(result) > Number.MAX_SAFE_INTEGER) throw new WorkflowExpressionError("expression_numeric_overflow");
+    }
+    return result;
+  }
+  throw new WorkflowExpressionError("expression_operator_unsupported");
+}
+
+export function evaluateInputMapping(
+  mapping: Record<string, JsonValue>,
+  context: JsonObject,
+): JsonObject {
+  const output: JsonObject = {};
+  for (const [key, expression] of Object.entries(mapping)) output[key] = evaluateWorkflowExpression(expression, context);
+  return output;
+}
+
+export function validateJsonSchemaValue(
+  value: JsonValue,
+  schema: JsonObject,
+  path = "$",
+  errors: string[] = [],
+): string[] {
+  const type = schema.type;
+  const matches = type === undefined
+    || (type === "object" && value !== null && typeof value === "object" && !Array.isArray(value))
+    || (type === "array" && Array.isArray(value))
+    || (type === "string" && typeof value === "string")
+    || (type === "number" && typeof value === "number" && Number.isFinite(value))
+    || (type === "integer" && typeof value === "number" && Number.isInteger(value))
+    || (type === "boolean" && typeof value === "boolean")
+    || (type === "null" && value === null);
+  if (!matches) {
+    errors.push(`${path}:type`);
+    return errors;
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.some((entry) => JSON.stringify(entry) === JSON.stringify(value))) errors.push(`${path}:enum`);
+  if (typeof value === "string") {
+    if (typeof schema.minLength === "number" && value.length < schema.minLength) errors.push(`${path}:minLength`);
+    if (typeof schema.maxLength === "number" && value.length > schema.maxLength) errors.push(`${path}:maxLength`);
+  }
+  if (typeof value === "number") {
+    if (typeof schema.minimum === "number" && value < schema.minimum) errors.push(`${path}:minimum`);
+    if (typeof schema.maximum === "number" && value > schema.maximum) errors.push(`${path}:maximum`);
+  }
+  if (Array.isArray(value)) {
+    if (typeof schema.maxItems === "number" && value.length > schema.maxItems) errors.push(`${path}:maxItems`);
+    if (schema.items && typeof schema.items === "object" && !Array.isArray(schema.items)) {
+      value.forEach((entry, index) => validateJsonSchemaValue(entry, schema.items as JsonObject, `${path}[${index}]`, errors));
+    }
+  }
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    const properties = schema.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties)
+      ? schema.properties as JsonObject : {};
+    const required = Array.isArray(schema.required) ? schema.required.filter((entry): entry is string => typeof entry === "string") : [];
+    for (const key of required) if (!(key in value)) errors.push(`${path}.${key}:required`);
+    for (const [key, entry] of Object.entries(value)) {
+      const propertySchema = properties[key];
+      if (propertySchema && typeof propertySchema === "object" && !Array.isArray(propertySchema)) validateJsonSchemaValue(entry, propertySchema, `${path}.${key}`, errors);
+      else if (schema.additionalProperties === false) errors.push(`${path}.${key}:additionalProperty`);
+    }
+  }
+  return errors;
+}

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

@@ -0,0 +1,121 @@
+export type WorkflowPurpose = "report" | "appeal" | "quality" | "operations";
+export type WorkflowAuthorityMode = "off" | "shadow" | "assist" | "bounded_auto";
+export type WorkflowNodeKind =
+  | "start"
+  | "enrichment"
+  | "parallel_group"
+  | "join"
+  | "condition"
+  | "ai_proposal"
+  | "human_task"
+  | "send_message"
+  | "wait_for_event"
+  | "delay"
+  | "delay_until"
+  | "decision"
+  | "action"
+  | "handoff"
+  | "start_linked_workflow"
+  | "end";
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+export type JsonObject = { [key: string]: JsonValue };
+
+export interface WorkflowNodeV1 {
+  id: string;
+  kind: WorkflowNodeKind;
+  name: string;
+  description?: string;
+  inputMapping: Record<string, JsonValue>;
+  timeoutPolicy?: JsonObject;
+  retryPolicy?: JsonObject;
+  errorPort?: string;
+  config: JsonObject;
+  metadata?: { x?: number; y?: number; groupId?: string };
+}
+
+export interface WorkflowEdgeV1 {
+  id: string;
+  from: { nodeId: string; port: string };
+  to: { nodeId: string; port: string };
+  label?: string;
+}
+
+export interface WorkflowGraphV1 {
+  schemaVersion: "1";
+  purpose: WorkflowPurpose;
+  entryNodeId: string;
+  nodes: WorkflowNodeV1[];
+  edges: WorkflowEdgeV1[];
+  inputSchema: JsonObject;
+  terminalCodes: string[];
+  defaultPolicies: {
+    timeout?: JsonValue;
+    retry?: JsonObject;
+    dataRetentionClass?: string;
+  };
+}
+
+export interface WorkflowValidationIssue {
+  code: string;
+  message: string;
+  path?: string;
+  nodeId?: string;
+  edgeId?: string;
+}
+
+export interface WorkflowDependencyReference {
+  type: "component" | "connection" | "policy" | "template" | "model_alias" | "agent" | "workflow";
+  key: string;
+  versionId: string;
+}
+
+export interface WorkflowCapabilityManifest {
+  version: 1;
+  capabilities: string[];
+  components: string[];
+  connections: string[];
+  eventTypes: string[];
+  audiences: string[];
+  actionCodes: string[];
+  maximumParallelBranches: number;
+  maximumStepExecutions: number;
+}
+
+export interface WorkflowValidationResult {
+  valid: boolean;
+  errors: WorkflowValidationIssue[];
+  warnings: WorkflowValidationIssue[];
+  dependencies: WorkflowDependencyReference[];
+  capabilityManifest: WorkflowCapabilityManifest;
+  reachableNodeIds: string[];
+  topologicalOrder: string[];
+  estimatedMaximumSteps: number;
+}
+
+export interface CompiledWorkflowArtifact {
+  compilerVersion: string;
+  compatibilityDate: string;
+  graphDigest: string;
+  sourceDigest: string;
+  bundleDigest: string;
+  manifestDigest: string;
+  source: string;
+  capabilityManifest: WorkflowCapabilityManifest;
+  dependencyManifest: WorkflowDependencyReference[];
+  warnings: WorkflowValidationIssue[];
+}
+
+export interface WorkflowDefinitionInput {
+  key: string;
+  name: string;
+  description: string;
+  purpose: WorkflowPurpose;
+}
+
+export interface WorkflowPublishInput {
+  expectedRevision: number;
+  authorityMode: WorkflowAuthorityMode;
+  testEvidence: JsonObject;
+}