@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

package/src/modules/workflows/lib/palette-drop.ts

@@ -0,0 +1,114 @@
+/**
+ * What a palette drop does to the graph (spec sections 4.2 and 4.4).
+ *
+ * Two drop targets, two effects:
+ * - a step dropped ON A ROUTE is spliced between that route's endpoints;
+ * - an action dropped ON A ROUTE is appended to that route's activities, which
+ *   is what the activity chips (#4244) then render.
+ *
+ * A step dropped on empty canvas is just an add at the cursor and needs nothing
+ * from here — `lib/node-placement.ts` already resolves the position.
+ *
+ * **Insert-on-route keeps the original route's data on the FIRST segment**
+ * (`from → new step`). A route's condition guards LEAVING its source step and
+ * its activities run on the way out, so both belong to the segment that still
+ * starts where the author put them; an error route likewise stays the error path
+ * out of that step. Just as importantly, the durable `transitionId` is what
+ * mid-flight state resolves against (`instance.pendingTransition`,
+ * `WorkflowBranchInstance.branchKey`), so it must stay attached to the segment
+ * that still leaves the same step. The second segment (`new step → to`) is a
+ * fresh, unconditional auto route.
+ *
+ * PURE: plain graph data in, plain graph data out, machine-readable rejections
+ * the editor translates.
+ */
+
+import type { Node, Edge } from '@xyflow/react'
+import { generateTransitionId } from './graph-utils'
+import { isDataMappingEdge } from './data-edge-mapping'
+import { buildWorkflowRouteEdge } from './route-edge'
+
+export type PaletteDropRejectionCode = 'unknownRoute' | 'dataMappingRoute'
+
+export type PaletteDropRejection = { ok: false; code: PaletteDropRejectionCode }
+
+export type InsertStepOnRouteResult =
+  | { ok: true; nodes: Node[]; edges: Edge[] }
+  | PaletteDropRejection
+
+export type AppendActivityToRouteResult =
+  | { ok: true; edges: Edge[] }
+  | PaletteDropRejection
+
+export interface RouteActivity {
+  activityId: string
+  activityName: string
+  activityType: string
+  config: Record<string, unknown>
+}
+
+function routeAt(edges: Edge[], edgeId: string): Edge | undefined {
+  return edges.find((edge) => edge.id === edgeId)
+}
+
+/**
+ * Splice a new step into an existing route.
+ *
+ * The original transition is retargeted at the new step and keeps everything it
+ * carried — id, label, condition, activities, priority, kind. A second,
+ * unconditional route continues from the new step to the original target.
+ */
+export function insertStepOnRoute(
+  nodes: Node[],
+  edges: Edge[],
+  edgeId: string,
+  newNode: Node,
+): InsertStepOnRouteResult {
+  const route = routeAt(edges, edgeId)
+  if (!route) return { ok: false, code: 'unknownRoute' }
+  if (isDataMappingEdge(route)) return { ok: false, code: 'dataMappingRoute' }
+
+  const continuation: Edge = buildWorkflowRouteEdge({
+    id: generateTransitionId(),
+    source: newNode.id,
+    target: route.target,
+    data: {
+      trigger: 'auto',
+      preConditions: [],
+      postConditions: [],
+      activities: [],
+      label: '',
+    },
+  })
+
+  const nextEdges = edges.flatMap((edge) =>
+    edge.id === edgeId
+      ? [{ ...edge, target: newNode.id, targetHandle: null }, continuation]
+      : [edge],
+  )
+
+  return { ok: true, nodes: [...nodes, newNode], edges: nextEdges }
+}
+
+/** Append an action to a route's activity list (the chips render it). */
+export function appendActivityToRoute(
+  edges: Edge[],
+  edgeId: string,
+  activity: RouteActivity,
+): AppendActivityToRouteResult {
+  const route = routeAt(edges, edgeId)
+  if (!route) return { ok: false, code: 'unknownRoute' }
+  if (isDataMappingEdge(route)) return { ok: false, code: 'dataMappingRoute' }
+
+  const data = (route.data ?? {}) as Record<string, unknown>
+  const existing = Array.isArray(data.activities) ? data.activities : []
+
+  return {
+    ok: true,
+    edges: edges.map((edge) =>
+      edge.id === edgeId
+        ? { ...edge, data: { ...data, activities: [...existing, activity] } }
+        : edge,
+    ),
+  }
+}

package/src/modules/workflows/lib/parallel-handler.ts

@@ -31,7 +31,8 @@ import {
 } from '../data/entities'
 import { logWorkflowEvent } from './event-logger'
 import * as stepHandler from './step-handler'
-import { branchToken } from './execution-token'
+import { branchToken, mergeTokenContext, type ExecutionToken } from './execution-token'
+import { WORKFLOW_ERROR_CONTEXT_KEY, buildErrorContextEntry } from './error-routing'
 
 export interface AdvanceBranchesResult {
   outcome: 'joined' | 'waiting' | 'failed'
@@ -392,10 +393,29 @@ async function advanceOneBranch(
       token,
       selected.fromStepId,
       selected.toStepId,
-      evalContext,
+      { ...evalContext, transitionId: selected.transitionId },
     )
 
     if (!transitionResult.success) {
+      // Error routing (spec 5.9) inside a branch: a wired error route is taken
+      // in the branch itself, so only unhandled failures propagate to the
+      // instance. The failure-queue directive is deliberately instance-level and
+      // is not honored per branch — such a branch keeps failing as it does today.
+      const routed = await followBranchErrorRoute(
+        em,
+        container,
+        instance,
+        branch,
+        token,
+        transitionResult,
+        evalContext,
+      )
+      if (routed) {
+        if (branch.currentStepId === branch.joinStepId) {
+          await completeBranchAtJoin(em, instance, branch)
+        }
+        return 'advanced'
+      }
       await failBranch(em, instance, branch, transitionResult.error || 'Branch transition failed')
       return 'failed'
     }
@@ -413,6 +433,63 @@ async function advanceOneBranch(
   }
 }
 
+/**
+ * Follow a branch step's wired error route with the branch token, so the branch
+ * keeps its own cursor and context namespace. Returns false when the transition
+ * result carries no route or the route could not be taken.
+ */
+async function followBranchErrorRoute(
+  em: EntityManager,
+  container: AwilixContainer,
+  instance: WorkflowInstance,
+  branch: WorkflowBranchInstance,
+  token: ExecutionToken,
+  transitionResult: { failedStepId?: string; errorRoute?: { transitionId?: string; toStepId: string }; error?: string },
+  evalContext: { workflowContext: Record<string, any>; userId?: string },
+): Promise<boolean> {
+  const { failedStepId, errorRoute } = transitionResult
+  if (!failedStepId || !errorRoute) return false
+
+  const error = transitionResult.error || 'Branch transition failed'
+  await logWorkflowEvent(em, {
+    workflowInstanceId: instance.id,
+    branchInstanceId: branch.id,
+    eventType: 'ERROR_ROUTED',
+    eventData: {
+      failedStepId,
+      toStepId: errorRoute.toStepId,
+      transitionId: errorRoute.transitionId,
+      branchKey: branch.branchKey,
+      error,
+    },
+    tenantId: instance.tenantId,
+    organizationId: instance.organizationId,
+  })
+
+  const errorEntry = buildErrorContextEntry(failedStepId, error)
+  mergeTokenContext(token, { [WORKFLOW_ERROR_CONTEXT_KEY]: errorEntry })
+  await em.flush()
+
+  const transitionHandler = await import('./transition-handler')
+  const routedResult = await transitionHandler.executeTransitionForToken(
+    em,
+    container,
+    token,
+    failedStepId,
+    errorRoute.toStepId,
+    {
+      ...evalContext,
+      workflowContext: {
+        ...evalContext.workflowContext,
+        [WORKFLOW_ERROR_CONTEXT_KEY]: errorEntry,
+      },
+      transitionId: errorRoute.transitionId,
+    },
+  )
+
+  return routedResult.success === true
+}
+
 async function completeBranchAtJoin(
   em: EntityManager,
   instance: WorkflowInstance,

package/src/modules/workflows/lib/port-contract.ts

@@ -0,0 +1,107 @@
+/**
+ * Workflows Module - Sub-workflow Port Contract Validation
+ *
+ * Coerces and validates a flat values object against a declared list of port
+ * fields (the `definition.io.inputs` / `definition.io.outputs` contract). Used
+ * at the SUB_WORKFLOW boundary so mapped inputs entering a child and mapped
+ * outputs leaving it conform to the child's declared, business-user-authored
+ * contract.
+ *
+ * Validation is opt-in by contract presence: the caller only invokes this when
+ * a child declares ports, so legacy untyped sub-workflows are unaffected.
+ *
+ * Coercion is intentionally permissive on representation (numeric strings,
+ * boolean tokens, ISO/epoch dates) but strict on validity — an uncoercible
+ * value or a missing required port produces an error rather than silently
+ * dropping the field.
+ */
+
+import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
+import type { PortField } from '../data/validators'
+
+export interface PortValidationError {
+  port: string
+  message: string
+}
+
+export interface PortValidationResult {
+  coerced: Record<string, any>
+  errors: PortValidationError[]
+}
+
+/**
+ * Validate and coerce `values` against the declared `ports`.
+ *
+ * Declared ports are coerced into the contract's type; keys not covered by a
+ * port pass through unchanged (so a partial contract does not strip unrelated
+ * context). A required port that is absent, or a value that cannot be coerced
+ * to its declared type, is reported as an error.
+ */
+export function validateAgainstPorts(
+  values: Record<string, any> | null | undefined,
+  ports: PortField[],
+): PortValidationResult {
+  const source = values ?? {}
+  const coerced: Record<string, any> = { ...source }
+  const errors: PortValidationError[] = []
+
+  for (const port of ports) {
+    const raw = source[port.name]
+    const isAbsent = raw === undefined || raw === null || raw === ''
+
+    if (isAbsent) {
+      if (port.required) {
+        errors.push({ port: port.name, message: `Required port "${port.name}" is missing` })
+      }
+      continue
+    }
+
+    const result = coercePortValue(raw, port)
+    if (result.error) {
+      errors.push({ port: port.name, message: result.error })
+      continue
+    }
+    coerced[port.name] = result.value
+  }
+
+  return { coerced, errors }
+}
+
+function coercePortValue(raw: any, port: PortField): { value?: any; error?: string } {
+  switch (port.type) {
+    case 'text':
+      return { value: String(raw) }
+
+    case 'number': {
+      const parsed = typeof raw === 'number' ? raw : Number(raw)
+      return Number.isNaN(parsed)
+        ? { error: `Port "${port.name}" expects a number` }
+        : { value: parsed }
+    }
+
+    case 'boolean': {
+      const parsed = typeof raw === 'boolean' ? raw : parseBooleanToken(typeof raw === 'string' ? raw : String(raw))
+      return parsed === null
+        ? { error: `Port "${port.name}" expects a boolean` }
+        : { value: parsed }
+    }
+
+    case 'select': {
+      const text = String(raw)
+      if (port.options && port.options.length > 0 && !port.options.includes(text)) {
+        return { error: `Port "${port.name}" must be one of: ${port.options.join(', ')}` }
+      }
+      return { value: text }
+    }
+
+    case 'date': {
+      const date = raw instanceof Date ? raw : new Date(typeof raw === 'number' ? raw : String(raw))
+      return Number.isNaN(date.getTime())
+        ? { error: `Port "${port.name}" expects a valid date` }
+        : { value: date.toISOString() }
+    }
+
+    default:
+      return { value: raw }
+  }
+}

package/src/modules/workflows/lib/portal-task-access.ts

@@ -0,0 +1,220 @@
+/**
+ * Per-request wiring for the §6.4 rule on the PORTAL side.
+ *
+ * The counterpart to `lib/task-visibility-request.ts`. Same contract: the pure
+ * predicate (`lib/task-visibility.ts`) decides, this module only assembles its
+ * inputs and turns the expressible half into a `WHERE`. A second copy of the
+ * rule anywhere is a review failure.
+ *
+ * ## Three things this file exists to get exactly right
+ *
+ * **1. A task with no bindings DENIES.** The backoffice branch passes an empty
+ * binding set vacuously, because a backoffice principal already carries an
+ * org-membership grant and being assigned a task inside your own tenant is a
+ * complete authorization story. A portal principal carries no such grant: the
+ * binding to their own record *is* the entire authorization, so with no binding
+ * there is nothing to authorize against. The predicate answers
+ * `denied:portal-unbound`; this module additionally excludes those rows in SQL
+ * (`entity_types IS NOT NULL`) so `pagination.total` does not count rows the
+ * predicate then drops.
+ *
+ * **2. `isPortalAdmin` buys nothing.** `customerAuth.ts` replaces a portal
+ * admin's grants with the literal `['*']`, and `CustomerRbacService` short-
+ * circuits `userHasAllFeatures` before any matching, so *every* feature check
+ * passes for them. Therefore no feature check may take part in the ownership
+ * decision: `PortalTaskPrincipal` carries no feature array at all, ownership is
+ * a `Set.has` against `ownedRecordIds`, and `isPortalAdmin` is consulted last
+ * and only to widen `visible` — never `actable`, never ownership.
+ *
+ * **3. The two id spaces are not interchangeable.** `assignedTo` on a portal
+ * task names a `CustomerUser.id` (the JWT `sub`). A binding's `entityId` names a
+ * customer/person ENTITY RECORD. They are resolved from the same company query
+ * and used in different places: user ids drive the SQL assignee arm, record ids
+ * drive the ownership `Set.has`. Feeding one where the other belongs would make
+ * a portal admin's own user id "own" a record.
+ *
+ * ## Company scoping
+ *
+ * Copied from `customer_accounts/api/portal/users.ts` verbatim, including its
+ * hard precondition: no `customerEntityId` ⇒ 403 "No company association" and
+ * an empty owned set. A portal user who belongs to no company owns nothing, so
+ * they see nothing, admin or not.
+ *
+ * Note `customerEntityId` / `personEntityId` are JWT claims read straight off
+ * the token and not re-verified per request, so a user moved between companies
+ * keeps stale ownership until their token turns over (design §9 item 8).
+ */
+
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { CustomerAuthContext } from '@open-mercato/core/modules/customer_accounts/lib/customerAuth'
+import { CustomerUser } from '@open-mercato/core/modules/customer_accounts/data/entities'
+import { UserTask } from '../data/entities'
+import {
+  decideTaskVisibility,
+  type PortalTaskPrincipal,
+  type TaskEntityAccessMap,
+  type TaskVisibilityDecision,
+  type TaskVisibilityPolicy,
+} from './task-visibility'
+import { toTaskFacts } from './task-visibility-request'
+
+/** Portal ACL features. New ids on an ADDITIVE-ONLY surface — nothing renamed. */
+export const PORTAL_TASKS_VIEW_FEATURE = 'portal.tasks.view'
+export const PORTAL_TASKS_COMPLETE_FEATURE = 'portal.tasks.complete'
+
+/**
+ * The portal branch reads NEITHER of these — it decides on structure, tenant,
+ * organization, `assignee_kind` and record ownership alone. They exist because
+ * `decideTaskVisibility` takes one shape for both principals. Frozen here so no
+ * route invents a map that could accidentally start meaning something.
+ */
+const PORTAL_ENTITY_ACCESS: TaskEntityAccessMap = new Map()
+const PORTAL_POLICY: TaskVisibilityPolicy = { businessContextEnabled: true }
+
+export type PortalTaskPrincipalResolution =
+  | { ok: true; principal: PortalTaskPrincipal; assigneeIds: readonly string[] }
+  | { ok: false; status: 403; body: Record<string, unknown> }
+
+/**
+ * Refusal body copied verbatim from `portal/users.ts` so the whole portal
+ * answers a company-less principal the same way.
+ */
+export const PORTAL_NO_COMPANY_BODY: Record<string, unknown> = {
+  ok: false,
+  error: 'No company association',
+}
+
+export const PORTAL_TASK_NOT_FOUND_BODY: Record<string, unknown> = {
+  ok: false,
+  error: 'Task not found',
+}
+
+function pushIfPresent(target: Set<string>, value: string | null | undefined): void {
+  if (typeof value === 'string' && value.length > 0) target.add(value)
+}
+
+/**
+ * Assemble the portal principal for this request.
+ *
+ * `assigneeIds` is the set of `CustomerUser.id` values whose tasks this
+ * principal may be shown — themselves, plus every company member when they are
+ * a portal admin. It is the SQL arm; `ownedRecordIds` is the ownership check.
+ * Both come from the one company query.
+ */
+export async function resolvePortalTaskPrincipal(input: {
+  auth: CustomerAuthContext
+  em: EntityManager
+  isPortalAdmin: boolean
+}): Promise<PortalTaskPrincipalResolution> {
+  const { auth, em, isPortalAdmin } = input
+
+  if (!auth.customerEntityId) {
+    return { ok: false, status: 403, body: PORTAL_NO_COMPANY_BODY }
+  }
+
+  const ownedRecordIds = new Set<string>()
+  pushIfPresent(ownedRecordIds, auth.customerEntityId)
+  pushIfPresent(ownedRecordIds, auth.personEntityId)
+
+  const assigneeIds = new Set<string>([auth.sub])
+
+  if (isPortalAdmin) {
+    // The exact filter `portal/users.ts` uses, so "my company" means the same
+    // thing on both surfaces.
+    const members = await findWithDecryption<CustomerUser>(
+      em,
+      CustomerUser,
+      {
+        customerEntityId: auth.customerEntityId,
+        tenantId: auth.tenantId,
+        deletedAt: null,
+      },
+      { fields: ['id', 'personEntityId', 'customerEntityId'] },
+      { tenantId: auth.tenantId, organizationId: auth.orgId },
+    )
+    for (const member of members) {
+      assigneeIds.add(member.id)
+      pushIfPresent(ownedRecordIds, member.personEntityId)
+      pushIfPresent(ownedRecordIds, member.customerEntityId)
+    }
+  }
+
+  return {
+    ok: true,
+    principal: {
+      kind: 'portal',
+      principalId: auth.sub,
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+      ownedRecordIds,
+      isPortalAdmin,
+    },
+    assigneeIds: [...assigneeIds],
+  }
+}
+
+/**
+ * The expressible half of the portal rule as ORM conditions.
+ *
+ * Three structural filters and no fourth:
+ *
+ * - `assignee_kind = 'customer'` keeps every backoffice row out of the portal
+ *   result set entirely, independent of the predicate. It is defence 3 of 4
+ *   against the `['*']` wildcard.
+ * - `assigned_to IN (…)` narrows to this principal (plus their company members
+ *   for an admin). Ownership is still checked afterwards by the predicate — this
+ *   only avoids fetching rows that cannot survive it.
+ * - `entity_types IS NOT NULL` drops unbound rows, which the predicate denies
+ *   anyway. Doing it in SQL is what keeps `pagination.total` honest.
+ *
+ * Ownership itself is NOT expressible: it is a containment test over the
+ * `entity_bindings` jsonb against a per-principal id set. The predicate answers
+ * it, and any row it drops that SQL admitted is an authoring anomaly, not a
+ * routine case.
+ */
+export function buildPortalTaskConditions(input: {
+  principal: PortalTaskPrincipal
+  assigneeIds: readonly string[]
+}): Record<string, unknown> {
+  return {
+    tenantId: input.principal.tenantId,
+    organizationId: input.principal.organizationId,
+    assigneeKind: 'customer',
+    assignedTo: { $in: [...input.assigneeIds] },
+    entityTypes: { $ne: null },
+  }
+}
+
+/** The predicate's answer for one already-loaded row, portal side. */
+export function decidePortalTaskAccess(
+  principal: PortalTaskPrincipal,
+  task: UserTask,
+): TaskVisibilityDecision {
+  return decideTaskVisibility(principal, toTaskFacts(task), PORTAL_ENTITY_ACCESS, PORTAL_POLICY)
+}
+
+/**
+ * The rows of an already-filtered page the predicate agrees are visible.
+ *
+ * The SQL above is not the whole rule — ownership is not expressible — so unlike
+ * the backoffice list this genuinely drops rows: a task assigned to a company
+ * member but bound to a record outside the company. Dropping is the correct
+ * direction, and the caller logs the divergence rather than hiding it.
+ */
+export function filterVisiblePortalTasks(
+  principal: PortalTaskPrincipal,
+  tasks: readonly UserTask[],
+): UserTask[] {
+  return tasks.filter((task) => decidePortalTaskAccess(principal, task).visible)
+}
+
+/**
+ * Every portal refusal is the same 404 with the same body.
+ *
+ * There is no portal analogue of the backoffice `view_all` diagnostic: no portal
+ * principal has a legitimate reason to learn that a row they cannot read exists,
+ * and a portal admin least of all — telling them "this task exists but is not
+ * yours" is precisely the cross-customer disclosure the ownership check prevents.
+ */
+export const PORTAL_TASK_REFUSAL = { status: 404 as const, body: PORTAL_TASK_NOT_FOUND_BODY }

package/src/modules/workflows/lib/rerun-from-step.ts

@@ -0,0 +1,140 @@
+/**
+ * Rerun from step (spec §8.4) — the eligibility decision, PURE.
+ *
+ * > "**Rerun from failed step**, optionally with edited context — audited as
+ * > `STEP_RERUN { editedContextDiff, by }`, gated by its own ACL feature."
+ *
+ * **This does NOT change the step state machine.** `workflows/AGENTS.md` says a
+ * step goes `PENDING → ACTIVE → COMPLETED|FAILED|SKIPPED|CANCELLED` and is
+ * never set out of order, so reviving the terminal `StepInstance` is out of the
+ * question. It never happens here: the terminal row is read for its recorded
+ * `stepType` and then left exactly as it is, and the new attempt gets a FRESH
+ * row — which is what the engine already does on every step entry
+ * (`lib/step-handler.ts` `enterStep` unconditionally
+ * `em.create(StepInstance, { … status: 'ACTIVE' … })`). Both attempts stay in
+ * the audit trail, and no status transition is invented.
+ *
+ * The cursor move plus `executeStep` is the same shape the definition-level
+ * error handler already uses (`enterErrorHandlerStep` in
+ * `lib/workflow-executor.ts`), so no transition record is invented either.
+ */
+
+/** Step-instance statuses that mean the attempt is over and a new one is safe. */
+const TERMINAL_STEP_STATUSES = new Set(['COMPLETED', 'FAILED', 'SKIPPED', 'CANCELLED'])
+
+/**
+ * Instance statuses a rerun may act on. A RUNNING instance is excluded on
+ * purpose: the engine is mid-advance and moving its cursor underneath it would
+ * race the execution loop.
+ */
+const RERUNNABLE_INSTANCE_STATUSES = new Set(['FAILED', 'PAUSED'])
+
+export type RerunRefusalCode =
+  | 'WORKFLOW_INSTANCE_NOT_RERUNNABLE'
+  | 'WORKFLOW_STEP_NOT_IN_DEFINITION'
+  | 'WORKFLOW_STEP_TYPE_CHANGED'
+  | 'WORKFLOW_STEP_NEVER_EXECUTED'
+  | 'WORKFLOW_STEP_STILL_PARKED'
+
+export type RerunStepExecutionInput = {
+  id: string
+  stepId: string
+  stepType: string
+  status: string
+  enteredAt?: string | Date | null
+  createdAt?: string | Date | null
+}
+
+export type RerunEligibility =
+  | { ok: true; supersededStepInstanceId: string; stepType: string }
+  | { ok: false; code: RerunRefusalCode; message: string }
+
+function orderKey(execution: RerunStepExecutionInput): number {
+  const raw = execution.enteredAt ?? execution.createdAt
+  if (!raw) return 0
+  const parsed = raw instanceof Date ? raw.getTime() : new Date(raw).getTime()
+  return Number.isNaN(parsed) ? 0 : parsed
+}
+
+export function resolveRerunEligibility(input: {
+  instanceStatus: string
+  stepId: string
+  definitionSteps: ReadonlyArray<{ stepId: string; stepType: string }>
+  stepExecutions: ReadonlyArray<RerunStepExecutionInput>
+}): RerunEligibility {
+  if (!RERUNNABLE_INSTANCE_STATUSES.has(input.instanceStatus)) {
+    return {
+      ok: false,
+      code: 'WORKFLOW_INSTANCE_NOT_RERUNNABLE',
+      message: `Cannot rerun a step of a ${input.instanceStatus} instance. Only FAILED or PAUSED instances can be rerun.`,
+    }
+  }
+
+  const definitionStep = input.definitionSteps.find((step) => step.stepId === input.stepId)
+  if (!definitionStep) {
+    return {
+      ok: false,
+      code: 'WORKFLOW_STEP_NOT_IN_DEFINITION',
+      message: `Step ${input.stepId} is no longer part of this workflow definition.`,
+    }
+  }
+
+  const executions = input.stepExecutions.filter((execution) => execution.stepId === input.stepId)
+  if (executions.length === 0) {
+    return {
+      ok: false,
+      code: 'WORKFLOW_STEP_NEVER_EXECUTED',
+      message: `Step ${input.stepId} has not executed in this run, so there is nothing to rerun.`,
+    }
+  }
+
+  const latest = [...executions].sort((left, right) => orderKey(right) - orderKey(left))[0]
+
+  if (!TERMINAL_STEP_STATUSES.has(latest.status)) {
+    // The step is still parked: a queue job and, for an agent step, a pending
+    // proposal are still addressed to THIS attempt. Rerunning would leave both
+    // orphaned and able to resume the run a second time. Lifting this needs
+    // §7.4's addressable resume token.
+    return {
+      ok: false,
+      code: 'WORKFLOW_STEP_STILL_PARKED',
+      message: `Step ${input.stepId} is still ${latest.status}. Cancel or resolve the pending attempt before rerunning it.`,
+    }
+  }
+
+  if (latest.stepType !== definitionStep.stepType) {
+    // The instance pins `definitionId` and the engine re-reads that row, so a
+    // FAILED instance's definition can be edited in place — the structural-edit
+    // guard only refuses while instances are ACTIVE. Replaying a step whose
+    // type changed underneath would execute something the run never ran.
+    return {
+      ok: false,
+      code: 'WORKFLOW_STEP_TYPE_CHANGED',
+      message: `Step ${input.stepId} changed from ${latest.stepType} to ${definitionStep.stepType} since this run started. Start a new instance instead.`,
+    }
+  }
+
+  return { ok: true, supersededStepInstanceId: latest.id, stepType: latest.stepType }
+}
+
+export type ContextDiffEntry = { from: unknown; to: unknown }
+
+/**
+ * The `editedContextDiff` the `STEP_RERUN` event records. Only the keys the
+ * caller actually changed appear — a patch that re-sends an identical value is
+ * not an edit, and recording it would make the audit unreadable.
+ */
+export function computeContextDiff(
+  before: Record<string, unknown> | null | undefined,
+  patch: Record<string, unknown> | null | undefined
+): Record<string, ContextDiffEntry> {
+  const diff: Record<string, ContextDiffEntry> = {}
+  if (!patch) return diff
+  const source = before ?? {}
+  for (const [key, next] of Object.entries(patch)) {
+    const current = source[key]
+    if (JSON.stringify(current) === JSON.stringify(next)) continue
+    diff[key] = { from: current ?? null, to: next }
+  }
+  return diff
+}