@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7195.1.b5efd1d51a

package/dist/modules/workflows/lib/task-visibility.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/workflows/lib/task-visibility.ts"],
+  "sourcesContent": ["/**\n * Who may see and act on a user task (PURE).\n *\n * Spec \u00A76.4: *a user (backoffice or portal) can see and act on a task iff\n * (assigned, or holds an assigned role, or claims from a role queue) AND passes\n * access checks on the task's bound entities. `workflows.tasks.*` features gate\n * administration (viewing others', reassigning) \u2014 never one's own assigned\n * work.*\n *\n * Written out:\n *\n *   visible   = SCOPE \u2227 (RELATIONSHIP \u2228 ADMINISTRATIVE) \u2227 ENTITY\n *   actable   = SCOPE \u2227 RELATIONSHIP \u2227 ENTITY \u2227 workable(status) \u2227 own-the-row\n *   claimable = actable \u2227 unassigned \u2227 unclaimed \u2227 PENDING \u2227 role overlap\n *\n * Three properties are the whole design and every change here must preserve\n * them:\n *\n * 1. **A task with no bindings passes the entity clause vacuously \u2014 for\n *    backoffice.** `[].every(...)` is `true`, and that is deliberate: every\n *    `UserTask` row written before Phase 4 carries zero bindings, so reading\n *    \"no bindings \u21D2 deny\" would make the entire existing corpus invisible to\n *    its own assignees on upgrade. That is an outage, not a narrowing. A PORTAL\n *    principal is the mirror image: they carry no org-membership grant at all,\n *    so the binding to their own record IS the authorization and an unbound\n *    task is visible to nobody.\n * 2. **Fail-closed applies to resolution failures, never to absence of data.**\n *    An unresolvable entity type, a map key the resolver never produced, and a\n *    resolver that threw all deny. An empty binding list does not.\n * 3. **Administration widens seeing, never acting.** `workflows.tasks.view_all`\n *    and superadmin admit a principal to somebody else's row; they never make\n *    it actable. To act, an administrator reassigns it to themselves first,\n *    which is audited (`reassigned_by`/`reassigned_at`/`reassign_reason` plus a\n *    `WorkflowEvent`). That is what keeps \"who approved this?\" answerable.\n *\n * PURE by contract, like `lib/task-resolution.ts` and `lib/error-routing.ts`:\n * no ORM, no DI, no React, no entity registry. Everything impure \u2014 the ACL\n * load, entity classification, portal ownership expansion, the tenant setting \u2014\n * is resolved ONCE per request by the caller and handed in as data.\n */\n\nimport { isOrganizationAccessAllowed } from '@open-mercato/shared/lib/auth/organizationAccess'\nimport { hasAllFeatures, hasFeature } from '@open-mercato/shared/security/features'\n\n/** Admits a principal to the task API. Necessary, never sufficient. */\nexport const WORKFLOWS_TASKS_VIEW_FEATURE = 'workflows.tasks.view'\n\n/** Administration: read rows you have no relationship to. Never grants act. */\nexport const WORKFLOWS_TASKS_VIEW_ALL_FEATURE = 'workflows.tasks.view_all'\n\n/** Administration: move a row to another assignee or role queue. */\nexport const WORKFLOWS_TASKS_REASSIGN_FEATURE = 'workflows.tasks.reassign'\n\n/**\n * The statuses a task can still be worked in.\n *\n * Deliberately the set `completeUserTask` accepts rather than \"not terminal\":\n * the handler filters on `status IN ('PENDING','IN_PROGRESS')`, so treating an\n * `ESCALATED` row as actable would render a Complete button that always fails.\n * The predicate and the handler must agree or the UI lies.\n */\nexport const TASK_ACTIONABLE_STATUSES: readonly string[] = ['PENDING', 'IN_PROGRESS']\n\nexport type BackofficeTaskPrincipal = {\n  kind: 'backoffice'\n  userId: string\n  tenantId: string\n  /** `null` = unrestricted operator (`resolveOrganizationScopeFilter` \u2192 `where: {}`). */\n  organizationIds: readonly string[] | null\n  /** `auth.roles` \u2014 role NAMES, server-derived, never client-supplied. */\n  roleNames: readonly string[]\n  /** `rbacService.getGrantedFeatures(...)` \u2014 MAY contain `'*'` / `'workflows.*'`. */\n  grantedFeatures: readonly string[]\n  isSuperAdmin: boolean\n}\n\nexport type PortalTaskPrincipal = {\n  kind: 'portal'\n  /** `CustomerAuthContext.sub`. */\n  principalId: string\n  tenantId: string\n  organizationId: string\n  /**\n   * Record ids this principal may legitimately be the subject of. For a plain\n   * portal user: `{customerEntityId, personEntityId}` minus nulls. For a portal\n   * admin: the same PLUS every company-member record id, resolved once per\n   * request by the route \u2014 never by this module.\n   */\n  ownedRecordIds: ReadonlySet<string>\n  isPortalAdmin: boolean\n}\n\nexport type TaskPrincipal = BackofficeTaskPrincipal | PortalTaskPrincipal\n\nexport type TaskEntityBindingFact = { entityType: string; entityId: string }\n\n/**\n * Per-entity-type answer to \"may this principal view records of this type at\n * all\", produced once per request by `lib/task-entity-access.ts`.\n *\n * A tagged union rather than the design's `string[] | null`, because that shape\n * cannot tell `denied:unknown-entity-type` (the authored type does not resolve\n * to any entity id \u2014 an author's typo) from `denied:entity-access` (it resolves\n * fine, but the caller may not view that type, or the platform has no rule for\n * it). \u00A72.3 and \u00A72.7 both need those apart: the first is a definition bug the\n * Problems panel should flag, the second is a policy decision an administrator\n * is told about. Both still deny.\n *\n * `requires` carries the REQUIRED features, not a verdict, so the wildcard-aware\n * match happens here in the one place that decides anything.\n */\nexport type TaskEntityAccessDecision =\n  | { kind: 'requires'; features: readonly string[] }\n  | { kind: 'unknown-entity-type' }\n  | { kind: 'unavailable' }\n\n/** Keyed by the binding's AUTHORED `entityType`, verbatim \u2014 see `resolveTaskEntityAccess`. */\nexport type TaskEntityAccessMap = ReadonlyMap<string, TaskEntityAccessDecision>\n\nexport type TaskFacts = {\n  id: string\n  tenantId: string\n  organizationId: string\n  status: string\n  assignedTo: string | null\n  /** `'user'` = `assignedTo` names a backoffice user; `'customer'` = a portal principal. */\n  assigneeKind: 'user' | 'customer'\n  assignedToRoles: readonly string[] | null\n  claimedBy: string | null\n  entityBindings: readonly TaskEntityBindingFact[]\n  /**\n   * ACL feature that admits a principal to this row when it is an UNASSIGNED\n   * administrative queue item rather than personal work \u2014 declared by the work\n   * inbox source that produced it (`WorkInboxSourceProvider.administrativeQueueFeature`).\n   * Absent falls back to core's own `workflows.tasks.view_all`.\n   */\n  administrativeQueueFeature?: string | null\n}\n\nexport type TaskVisibilityPolicy = {\n  /** Tenant opt-out. `true` = the \u00A76.4 model (default). `false` = legacy read filter. */\n  businessContextEnabled: boolean\n}\n\nexport type TaskVisibilityReason =\n  // admits\n  | 'assignee'\n  | 'claimant'\n  | 'role-queue'\n  | 'administrative'\n  | 'administrative-queue'\n  | 'legacy-read-filter'\n  | 'portal-assignee'\n  | 'portal-company-admin'\n  // refusals\n  | 'denied:tenant'\n  | 'denied:organization'\n  | 'denied:no-relationship'\n  | 'denied:entity-access'\n  | 'denied:unknown-entity-type'\n  | 'denied:portal-unbound'\n  | 'denied:portal-not-owner'\n  | 'denied:portal-wrong-assignee-kind'\n\nexport type TaskVisibilityDecision = {\n  visible: boolean\n  /** May complete / decide this task. */\n  actable: boolean\n  /** May claim it off a role queue. A refinement of `actable`, never wider. */\n  claimable: boolean\n  reason: TaskVisibilityReason\n  /**\n   * The binding that failed the entity clause, when one did.\n   *\n   * Set on refusals, where it powers the `view_all`-only 403-with-reason\n   * diagnostic \u2014 a task hidden by the entity gate must never disappear without\n   * trace. Also set on the `legacy-read-filter` ADMIT, which is the one path\n   * that shows a row whose entity clause failed: the opt-out restores the read\n   * and nothing else, so the act surfaces need to see that the gate is still\n   * closed underneath.\n   */\n  blockedEntityType?: string\n}\n\nfunction deny(reason: TaskVisibilityReason, blockedEntityType?: string): TaskVisibilityDecision {\n  return blockedEntityType\n    ? { visible: false, actable: false, claimable: false, reason, blockedEntityType }\n    : { visible: false, actable: false, claimable: false, reason }\n}\n\n/**\n * Both sides are role NAMES, not ids.\n *\n * `assignedToRoles` holds what the Studio picker wrote, and `roleNames` is\n * `auth.roles`, derived server-side from the session \u2014 so a client cannot forge\n * membership by claiming a role. Names are tenant-MUTABLE, though: renaming a\n * role silently orphans every assignment authored against the old name, and\n * this comparison is where that shows up. Moving to immutable ids needs a\n * coordinated data + authored-definition migration (`loadAcl` returns no role\n * ids today, so changing only this side would match nothing); it is tracked as\n * a follow-up and stated in `framework/workflows/task-visibility.mdx` \u2192\n * Known Limits.\n */\nfunction hasRoleOverlap(\n  taskRoles: readonly string[] | null,\n  roleNames: readonly string[],\n): boolean {\n  if (!taskRoles || taskRoles.length === 0 || roleNames.length === 0) return false\n  const held = new Set(roleNames)\n  return taskRoles.some((role) => held.has(role))\n}\n\n/** No assignee, no claimant and no role queue \u2014 nobody's personal work. */\nfunction isUnassignedQueueItem(task: TaskFacts): boolean {\n  return (\n    task.assignedTo === null &&\n    task.claimedBy === null &&\n    (task.assignedToRoles === null || task.assignedToRoles.length === 0)\n  )\n}\n\ntype EntityClauseResult =\n  | { ok: true }\n  | { ok: false; reason: 'denied:entity-access' | 'denied:unknown-entity-type'; entityType: string }\n\n/**\n * `every`, not `some`: a task bound to a sensitive deal AND a harmless customer\n * must not leak through the harmless one. The cost is real \u2014 a legitimately\n * assigned worker can be blinded by a binding they cannot see \u2014 and is paid for\n * by the author-time Problems check and the `denied:entity-access` diagnostic\n * rather than by weakening the rule.\n */\nfunction evaluateEntityClause(\n  principal: BackofficeTaskPrincipal,\n  task: TaskFacts,\n  entityAccess: TaskEntityAccessMap,\n): EntityClauseResult {\n  // Mirrors `assertEntityAclForRequest`'s own `if (acl?.isSuperAdmin) return`.\n  if (principal.isSuperAdmin) return { ok: true }\n  for (const binding of task.entityBindings) {\n    const decision = entityAccess.get(binding.entityType)\n    // A key the resolver never produced is a RESOLUTION FAILURE, never a pass.\n    if (!decision) {\n      return { ok: false, reason: 'denied:entity-access', entityType: binding.entityType }\n    }\n    if (decision.kind === 'unknown-entity-type') {\n      return { ok: false, reason: 'denied:unknown-entity-type', entityType: binding.entityType }\n    }\n    if (decision.kind === 'unavailable') {\n      return { ok: false, reason: 'denied:entity-access', entityType: binding.entityType }\n    }\n    if (!hasAllFeatures(principal.grantedFeatures, decision.features)) {\n      return { ok: false, reason: 'denied:entity-access', entityType: binding.entityType }\n    }\n  }\n  return { ok: true }\n}\n\n/** The queue feature that admits a principal to this row when it is unassigned. */\nfunction administrativeQueueFeatureOf(task: TaskFacts): string {\n  return task.administrativeQueueFeature ?? WORKFLOWS_TASKS_VIEW_ALL_FEATURE\n}\n\nfunction resolveRelationshipReason(\n  principal: BackofficeTaskPrincipal,\n  task: TaskFacts,\n): TaskVisibilityReason | null {\n  if (task.assigneeKind === 'user' && task.assignedTo === principal.userId) return 'assignee'\n  if (task.claimedBy !== null && task.claimedBy === principal.userId) return 'claimant'\n  if (hasRoleOverlap(task.assignedToRoles, principal.roleNames)) return 'role-queue'\n  return null\n}\n\nfunction resolveAdministrativeReason(\n  principal: BackofficeTaskPrincipal,\n  task: TaskFacts,\n): TaskVisibilityReason | null {\n  if (principal.isSuperAdmin) return 'administrative'\n  if (hasFeature(principal.grantedFeatures, WORKFLOWS_TASKS_VIEW_ALL_FEATURE)) return 'administrative'\n  if (\n    isUnassignedQueueItem(task) &&\n    hasFeature(principal.grantedFeatures, administrativeQueueFeatureOf(task))\n  ) {\n    return 'administrative-queue'\n  }\n  return null\n}\n\n/**\n * Who owns the row right now. A claim outranks an assignment because that is\n * what `completeUserTask` enforces (`claimedBy ?? assignedTo`), and the two must\n * not disagree. `null` means the row is open, and membership in its queue is\n * then what confers the right to act.\n */\nexport function currentTaskOwnerId(task: TaskFacts): string | null {\n  if (task.claimedBy !== null) return task.claimedBy\n  if (task.assigneeKind === 'user') return task.assignedTo\n  return null\n}\n\nfunction decideBackoffice(\n  principal: BackofficeTaskPrincipal,\n  task: TaskFacts,\n  entityAccess: TaskEntityAccessMap,\n  policy: TaskVisibilityPolicy,\n): TaskVisibilityDecision {\n  // Never overridden \u2014 not by superadmin, not by the tenant opt-out.\n  if (task.tenantId !== principal.tenantId) return deny('denied:tenant')\n  if (\n    !isOrganizationAccessAllowed({\n      isSuperAdmin: principal.isSuperAdmin,\n      allowedOrganizationIds: principal.organizationIds,\n      targetOrganizationId: task.organizationId,\n    })\n  ) {\n    return deny('denied:organization')\n  }\n\n  const relationshipReason = resolveRelationshipReason(principal, task)\n  const administrativeReason = relationshipReason\n    ? null\n    : resolveAdministrativeReason(principal, task)\n  const admitReason = relationshipReason ?? administrativeReason\n\n  const entity = evaluateEntityClause(principal, task, entityAccess)\n\n  // ACT is computed by the NEW rule always \u2014 the opt-out is a SELECT filter, not\n  // an authorization mode, so it can neither widen nor narrow this.\n  const owner = currentTaskOwnerId(task)\n  const ownsTheRow =\n    owner !== null\n      ? owner === principal.userId\n      : hasRoleOverlap(task.assignedToRoles, principal.roleNames)\n  const actable =\n    entity.ok &&\n    ownsTheRow &&\n    task.assigneeKind === 'user' &&\n    TASK_ACTIONABLE_STATUSES.includes(task.status)\n  const claimable =\n    actable &&\n    task.assignedTo === null &&\n    task.claimedBy === null &&\n    task.status === 'PENDING' &&\n    hasRoleOverlap(task.assignedToRoles, principal.roleNames)\n\n  if (admitReason && entity.ok) {\n    return { visible: true, actable, claimable, reason: admitReason }\n  }\n\n  // The opt-out restores the pre-change READ filter and nothing else: same rows,\n  // no entity gate, act path untouched. It is additive on purpose \u2014 it must\n  // never hide a row the new model would have shown.\n  if (\n    !policy.businessContextEnabled &&\n    hasFeature(principal.grantedFeatures, WORKFLOWS_TASKS_VIEW_FEATURE)\n  ) {\n    return {\n      visible: true,\n      actable,\n      claimable,\n      reason: 'legacy-read-filter',\n      // Reported even though the row is admitted: the read came back, the entity\n      // gate did not, and an act surface must be able to tell the difference.\n      ...(entity.ok ? {} : { blockedEntityType: entity.entityType }),\n    }\n  }\n\n  // No relationship and no administrative grant discloses less than an entity\n  // refusal does, so it is reported first: a caller with no legitimate knowledge\n  // that the row exists learns nothing about which entity blocked them.\n  if (!admitReason) return deny('denied:no-relationship')\n  if (!entity.ok) return deny(entity.reason, entity.entityType)\n  return deny('denied:no-relationship')\n}\n\nfunction decidePortal(principal: PortalTaskPrincipal, task: TaskFacts): TaskVisibilityDecision {\n  if (task.tenantId !== principal.tenantId) return deny('denied:tenant')\n  if (task.organizationId !== principal.organizationId) return deny('denied:organization')\n  // Structural: a backoffice task is not portal work, whatever the caller holds.\n  if (task.assigneeKind !== 'customer') return deny('denied:portal-wrong-assignee-kind')\n  // A portal principal carries no org-membership grant, so an unbound task has\n  // nothing tying it to them. Denying is the only correct answer, and it is what\n  // keeps every legacy (binding-free) backoffice row out of the portal.\n  if (task.entityBindings.length === 0) return deny('denied:portal-unbound')\n\n  // A data comparison, never a feature check: `isPortalAdmin` resolves to `['*']`\n  // in `customerAuth.ts` and short-circuits `userHasAllFeatures`, so a wildcard\n  // must not be able to satisfy ownership. A `Set.has` cannot be wildcarded.\n  const ownsEveryBinding = task.entityBindings.every((binding) =>\n    principal.ownedRecordIds.has(binding.entityId),\n  )\n  if (!ownsEveryBinding) return deny('denied:portal-not-owner')\n\n  if (task.assignedTo === principal.principalId) {\n    const actable = TASK_ACTIONABLE_STATUSES.includes(task.status)\n    return { visible: true, actable, claimable: false, reason: 'portal-assignee' }\n  }\n\n  // Consulted LAST, and only to widen seeing \u2014 a company admin reads their\n  // members' work, they never complete it.\n  if (principal.isPortalAdmin) {\n    return { visible: true, actable: false, claimable: false, reason: 'portal-company-admin' }\n  }\n\n  return deny('denied:portal-not-owner')\n}\n\n/**\n * The one decision point. Every surface \u2014 list, detail, claim, unclaim,\n * complete, reassign, work inbox, the record-page pending-work widget, the\n * workload aggregate and the portal routes \u2014 routes through this function. A\n * second copy of the rule anywhere is a review failure.\n */\nexport function decideTaskVisibility(\n  principal: TaskPrincipal,\n  task: TaskFacts,\n  entityAccess: TaskEntityAccessMap,\n  policy: TaskVisibilityPolicy,\n): TaskVisibilityDecision {\n  if (principal.kind === 'portal') return decidePortal(principal, task)\n  return decideBackoffice(principal, task, entityAccess, policy)\n}\n\n/**\n * The statuses `reassignUserTask` accepts (`lib/task-handler.ts`\n * `REASSIGNABLE_STATUSES`). Restated here because this module is PURE and the\n * handler is not; the two must agree or the Reassign button lies.\n */\nexport const TASK_REASSIGNABLE_STATUSES: readonly string[] = ['PENDING', 'IN_PROGRESS']\n\n/**\n * The status `releaseUserTask` accepts. It looks the row up with\n * `status: 'IN_PROGRESS'`, so a PENDING row is `TASK_NOT_FOUND` there \u2014 which is\n * narrower than `TASK_ACTIONABLE_STATUSES` and must not be widened to it.\n */\nexport const TASK_RELEASABLE_STATUS = 'IN_PROGRESS'\n\n/**\n * Why an act surface is closed to a caller who CAN read the row.\n *\n * Every value here is derivable from fields the caller already has in the same\n * response (`status`, `assignedTo`, `claimedBy`, `assignedToRoles`), so naming\n * the reason discloses nothing the payload does not. The one deliberate\n * exception is `unavailable`, below.\n */\nexport type TaskActionBlockReason =\n  /** Terminal status \u2014 the handler answers `TASK_NOT_FOUND`. */\n  | 'not-workable'\n  /** Somebody else is the assignee or the claimant \u2014 a 409 on click. */\n  | 'owned-by-another'\n  /** Open, but queued to a role the caller does not hold. */\n  | 'not-in-your-queue'\n  /** Nobody's work: no assignee, no claim, no queue \u2014 `TASK_NOT_ACTIONABLE`. */\n  | 'unowned'\n  /**\n   * Refused without a reason, on purpose.\n   *\n   * Reachable only under the tenant opt-out, which restores the READ and never\n   * the act path: the row comes back with `blockedEntityType` set and the act\n   * routes answer a bare 404 for it, because \"the entity gate blocked you\" names\n   * a binding the gate has just refused this caller. The UI must be exactly as\n   * uninformative \u2014 it says the action is unavailable and stops there.\n   */\n  | 'unavailable'\n\n/**\n * What the page may OFFER, decided here so no client re-derives \u00A76.4.\n *\n * These are booleans, not features: a `workflows.tasks.view_all` administrator\n * holds `workflows.tasks.complete` and still gets `canComplete: false`, because\n * administration widens seeing and never acting. Each flag mirrors the gate its\n * own endpoint applies (`resolveTaskActRefusal` for complete/claim/release,\n * visibility + the reassign feature for reassign), so an offered action is one\n * the server will accept.\n */\nexport type TaskAffordances = {\n  canComplete: boolean\n  canClaim: boolean\n  canRelease: boolean\n  canReassign: boolean\n  /** Why `canComplete` is false, for a caller who can read the row. */\n  actBlockedReason: TaskActionBlockReason | null\n}\n\n/**\n * Resolve the act surfaces for one already-decided row.\n *\n * PURE, and deliberately a projection of `decideTaskVisibility`'s own answer\n * rather than a second evaluation of the rule: `canComplete` IS `actable` and\n * `canClaim` IS `claimable`. Only `canRelease` and `canReassign` add anything,\n * and each adds exactly the one condition its endpoint checks beyond visibility.\n */\nexport function resolveTaskAffordances(\n  principal: BackofficeTaskPrincipal,\n  task: TaskFacts,\n  decision: TaskVisibilityDecision,\n): TaskAffordances {\n  // Set on the `legacy-read-filter` ADMIT: the opt-out restored the read and the\n  // entity gate is still shut underneath, so every act route answers 404.\n  const entityGateClosed = decision.blockedEntityType !== undefined\n  const actSurfaceOpen = decision.visible && !entityGateClosed\n\n  const canComplete = decision.visible && decision.actable\n  const canClaim = decision.visible && decision.claimable\n  const canRelease =\n    actSurfaceOpen && task.status === TASK_RELEASABLE_STATUS && task.claimedBy === principal.userId\n  const canReassign =\n    actSurfaceOpen &&\n    TASK_REASSIGNABLE_STATUSES.includes(task.status) &&\n    (principal.isSuperAdmin ||\n      hasFeature(principal.grantedFeatures, WORKFLOWS_TASKS_REASSIGN_FEATURE))\n\n  return {\n    canComplete,\n    canClaim,\n    canRelease,\n    canReassign,\n    actBlockedReason: resolveActBlockReason(principal, task, decision, {\n      canComplete,\n      entityGateClosed,\n    }),\n  }\n}\n\n/**\n * Mirrors `resolveTaskActRefusal`'s precedence exactly \u2014 entity gate, then\n * status, then ownership \u2014 so the stated reason and the refusal a click would\n * produce can never disagree.\n */\nfunction resolveActBlockReason(\n  principal: BackofficeTaskPrincipal,\n  task: TaskFacts,\n  decision: TaskVisibilityDecision,\n  state: { canComplete: boolean; entityGateClosed: boolean },\n): TaskActionBlockReason | null {\n  if (state.canComplete) return null\n  if (!decision.visible) return null\n  if (state.entityGateClosed) return 'unavailable'\n  if (!TASK_ACTIONABLE_STATUSES.includes(task.status)) return 'not-workable'\n\n  const owner = currentTaskOwnerId(task)\n  if (owner !== null) return owner === principal.userId ? 'unavailable' : 'owned-by-another'\n  if (task.assignedToRoles !== null && task.assignedToRoles.length > 0) return 'not-in-your-queue'\n  return 'unowned'\n}\n\nexport type TaskVisibilityFilterOptions = {\n  /**\n   * Queue feature for the source being filtered, when it is not core's own\n   * `workflows.tasks.view_all`. Supplying it adds the unassigned-queue arm.\n   */\n  administrativeQueueFeature?: string | null\n}\n\n/**\n * The RELATIONSHIP \u2228 ADMINISTRATIVE half of the rule as ORM conditions, for\n * pushing onto an existing `$and` array (`buildUserTaskWorkInboxWhere` composes\n * independent `$or` groups exactly this way).\n *\n * Returns `[]` when the caller may read everything in scope \u2014 an administrator,\n * a superadmin, or a tenant that has flipped the opt-out.\n *\n * **The ENTITY half is deliberately absent.** The predicate is \"no binding whose\n * type is outside my allowed set\", and the disallowed set is unbounded (authored\n * free text), so it cannot be enumerated as `$contains` negations over the\n * `entity_bindings` jsonb. It becomes a containment test against the\n * denormalized `user_tasks.entity_types` column (design D-2), emitted as one raw\n * fragment where the query is built. Do not try to express it here.\n */\nexport function buildTaskVisibilityConditions(\n  principal: BackofficeTaskPrincipal,\n  policy: TaskVisibilityPolicy,\n  options: TaskVisibilityFilterOptions = {},\n): Record<string, unknown>[] {\n  if (principal.isSuperAdmin) return []\n  if (hasFeature(principal.grantedFeatures, WORKFLOWS_TASKS_VIEW_ALL_FEATURE)) return []\n  if (\n    !policy.businessContextEnabled &&\n    hasFeature(principal.grantedFeatures, WORKFLOWS_TASKS_VIEW_FEATURE)\n  ) {\n    return []\n  }\n\n  const arms: Record<string, unknown>[] = [\n    // `assigneeKind` discriminates a backoffice user id from a portal principal\n    // id in the same column, so a customer-assigned row can never match a\n    // backoffice caller whose user id happens to collide.\n    { assignedTo: principal.userId, assigneeKind: 'user' },\n    { claimedBy: principal.userId },\n  ]\n  if (principal.roleNames.length > 0) {\n    arms.push({ assignedToRoles: { $overlap: [...principal.roleNames] } })\n  }\n\n  const queueFeature = options.administrativeQueueFeature\n  if (queueFeature && hasFeature(principal.grantedFeatures, queueFeature)) {\n    arms.push({\n      assignedTo: null,\n      claimedBy: null,\n      $or: [{ assignedToRoles: null }, { assignedToRoles: { $eq: [] } }],\n    })\n  }\n\n  return [{ $or: arms }]\n}\n\n/**\n * The full `WHERE` for a backoffice principal: tenant, organization and the\n * relationship clause. Same shape as `buildUserTaskWorkInboxWhere`'s output so\n * the two compose.\n *\n * Portal reads do not use this \u2014 they filter on `assignee_kind = 'customer'`\n * plus the caller's owned record ids, which is new surface with its own query.\n */\nexport function buildTaskVisibilityFilter(\n  principal: BackofficeTaskPrincipal,\n  policy: TaskVisibilityPolicy,\n  options: TaskVisibilityFilterOptions = {},\n): Record<string, unknown> {\n  const where: Record<string, unknown> = { tenantId: principal.tenantId }\n  if (principal.organizationIds !== null) {\n    where.organizationId = { $in: [...principal.organizationIds] }\n  }\n  const conditions = buildTaskVisibilityConditions(principal, policy, options)\n  if (conditions.length > 0) where.$and = conditions\n  return where\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/workflows/lib/timer-handler.js

@@ -161,13 +161,15 @@ async function fireTimer(em, container, options) {
     await em.flush();
     return;
   }
+  instance.status = "RUNNING";
+  await em.flush();
   const transitionResult = await transitionHandler.executeTransition(
     em,
     container,
     instance,
     instance.currentStepId,
     firstValidTransition.transition.toStepId,
-    transitionContext
+    { ...transitionContext, transitionId: firstValidTransition.transition.transitionId }
   );
   if (!transitionResult.success) {
     throw new TimerError(

package/dist/modules/workflows/lib/timer-handler.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/modules/workflows/lib/timer-handler.ts"],
-  "sourcesContent": ["/**\n * Timer Handler Service\n *\n * Fires timers for WAIT_FOR_TIMER steps: resumes a paused workflow instance\n * when its scheduled timer job is processed by the activity worker.\n */\n\nimport { EntityManager } from '@mikro-orm/core'\nimport type { EntityManager as PostgreSqlEntityManager } from '@mikro-orm/postgresql'\nimport type { AwilixContainer } from 'awilix'\nimport { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'\nimport { WorkflowInstance, WorkflowDefinition, StepInstance } from '../data/entities'\nimport type * as eventLoggerModule from './event-logger'\nimport type * as stepHandlerModule from './step-handler'\nimport type * as transitionHandlerModule from './transition-handler'\nimport type * as workflowExecutorModule from './workflow-executor'\nimport { resolveCodeDefinitionForInstance } from './find-definition'\n\nexport interface FireTimerOptions {\n  instanceId: string\n  stepInstanceId?: string\n  branchInstanceId?: string | null\n  userId?: string\n  tenantId: string\n  organizationId: string\n}\n\nexport class TimerError extends Error {\n  constructor(\n    message: string,\n    public code: string,\n    public details?: any\n  ) {\n    super(message)\n    this.name = 'TimerError'\n  }\n}\n\n/**\n * Fire a timer and resume workflow execution.\n *\n * Mirrors `sendSignal` from signal-handler.ts \u2014 verifies the instance is\n * paused at a WAIT_FOR_TIMER step, logs TIMER_FIRED, exits the step, then\n * executes auto transitions and resumes the workflow.\n */\nexport async function fireTimer(\n  em: EntityManager,\n  container: AwilixContainer,\n  options: FireTimerOptions\n): Promise<void> {\n  const { instanceId, stepInstanceId, branchInstanceId, userId, tenantId, organizationId } = options\n\n  const eventLogger = container.resolve<typeof eventLoggerModule>('eventLogger')\n  const stepHandler = container.resolve<typeof stepHandlerModule>('stepHandler')\n  const transitionHandler = container.resolve<typeof transitionHandlerModule>('transitionHandler')\n  const workflowExecutor = container.resolve<typeof workflowExecutorModule>('workflowExecutor')\n\n  // Branch-scoped timer: the instance is FORKED and the branch is PAUSED at the\n  // WAIT_FOR_TIMER step. Resume just that branch, then drive the parallel loop.\n  if (branchInstanceId) {\n    await eventLogger.logWorkflowEvent(em, {\n      workflowInstanceId: instanceId,\n      stepInstanceId,\n      branchInstanceId,\n      eventType: 'TIMER_FIRED',\n      eventData: { firedAt: new Date().toISOString(), branch: true },\n      userId,\n      tenantId,\n      organizationId,\n    })\n    const { resumeBranch } = await import('./parallel-handler')\n    const resumed = await resumeBranch(em, {\n      instanceId,\n      branchInstanceId,\n      tenantId,\n      organizationId,\n      exitStepInstanceId: stepInstanceId,\n      exitOutput: { firedAt: new Date().toISOString() },\n    })\n    if (resumed) {\n      await workflowExecutor.executeWorkflow(em, container, instanceId, { userId })\n    }\n    return\n  }\n\n  const instance = await findOneWithDecryption(\n    em as PostgreSqlEntityManager,\n    WorkflowInstance,\n    {\n      id: instanceId,\n      tenantId,\n      organizationId,\n    },\n    undefined,\n    { tenantId, organizationId },\n  )\n\n  if (!instance) {\n    throw new TimerError(\n      'Workflow instance not found',\n      'INSTANCE_NOT_FOUND',\n      { instanceId }\n    )\n  }\n\n  if (instance.status !== 'PAUSED') {\n    throw new TimerError(\n      'Workflow is not paused',\n      'WORKFLOW_NOT_PAUSED',\n      { instanceId, status: instance.status }\n    )\n  }\n\n  const definition = (await findOneWithDecryption(\n    em as PostgreSqlEntityManager,\n    WorkflowDefinition,\n    {\n      id: instance.definitionId,\n      tenantId: instance.tenantId,\n      organizationId: instance.organizationId,\n      deletedAt: null,\n    },\n    undefined,\n    { tenantId: instance.tenantId, organizationId: instance.organizationId },\n  )) ?? resolveCodeDefinitionForInstance(instance)\n  if (!definition) {\n    throw new TimerError(\n      'Workflow definition not found',\n      'DEFINITION_NOT_FOUND',\n      { definitionId: instance.definitionId }\n    )\n  }\n\n  const currentStep = definition.definition.steps.find(\n    (s: any) => s.stepId === instance.currentStepId\n  )\n\n  if (!currentStep || currentStep.stepType !== 'WAIT_FOR_TIMER') {\n    throw new TimerError(\n      'Workflow is not waiting for timer',\n      'NOT_WAITING_FOR_TIMER',\n      { instanceId, currentStepId: instance.currentStepId }\n    )\n  }\n\n  const now = new Date()\n  instance.updatedAt = now\n\n  await eventLogger.logWorkflowEvent(em, {\n    workflowInstanceId: instance.id,\n    stepInstanceId,\n    eventType: 'TIMER_FIRED',\n    eventData: {\n      stepId: instance.currentStepId,\n      firedAt: now.toISOString(),\n    },\n    userId,\n    tenantId: instance.tenantId,\n    organizationId: instance.organizationId,\n  })\n\n  const stepInstance = stepInstanceId\n    ? await findOneWithDecryption(\n        em as PostgreSqlEntityManager,\n        StepInstance,\n        {\n          id: stepInstanceId,\n          workflowInstanceId: instance.id,\n          tenantId: instance.tenantId,\n          organizationId: instance.organizationId,\n        },\n        undefined,\n        { tenantId: instance.tenantId, organizationId: instance.organizationId },\n      )\n    : await findOneWithDecryption(\n        em as PostgreSqlEntityManager,\n        StepInstance,\n        {\n          workflowInstanceId: instance.id,\n          stepId: instance.currentStepId,\n          status: 'ACTIVE',\n          tenantId: instance.tenantId,\n          organizationId: instance.organizationId,\n        },\n        undefined,\n        { tenantId: instance.tenantId, organizationId: instance.organizationId },\n      )\n\n  if (stepInstance) {\n    await stepHandler.exitStep(em, stepInstance, {\n      firedAt: now.toISOString(),\n    })\n  }\n\n  const autoTransitions = (definition.definition.transitions || []).filter(\n    (t: any) => t.fromStepId === instance.currentStepId && t.trigger === 'auto'\n  )\n\n  if (autoTransitions.length === 0) {\n    instance.status = 'RUNNING'\n    await em.flush()\n    return\n  }\n\n  const transitionContext = {\n    workflowContext: instance.context,\n    userId,\n  }\n\n  const validTransitions = await transitionHandler.findValidTransitions(\n    em,\n    instance,\n    instance.currentStepId,\n    transitionContext\n  )\n\n  const firstValidTransition = validTransitions.find((t) => t.isValid)\n\n  if (!firstValidTransition || !firstValidTransition.transition) {\n    instance.status = 'RUNNING'\n    await em.flush()\n    return\n  }\n\n  const transitionResult = await transitionHandler.executeTransition(\n    em,\n    container,\n    instance,\n    instance.currentStepId,\n    firstValidTransition.transition.toStepId,\n    transitionContext\n  )\n\n  if (!transitionResult.success) {\n    throw new TimerError(\n      'Transition failed after timer fired',\n      'TRANSITION_FAILED',\n      { error: transitionResult.error }\n    )\n  }\n\n  await workflowExecutor.executeWorkflow(em, container, instance.id, { userId })\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * Timer Handler Service\n *\n * Fires timers for WAIT_FOR_TIMER steps: resumes a paused workflow instance\n * when its scheduled timer job is processed by the activity worker.\n */\n\nimport { EntityManager } from '@mikro-orm/core'\nimport type { EntityManager as PostgreSqlEntityManager } from '@mikro-orm/postgresql'\nimport type { AwilixContainer } from 'awilix'\nimport { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'\nimport { WorkflowInstance, WorkflowDefinition, StepInstance } from '../data/entities'\nimport type * as eventLoggerModule from './event-logger'\nimport type * as stepHandlerModule from './step-handler'\nimport type * as transitionHandlerModule from './transition-handler'\nimport type * as workflowExecutorModule from './workflow-executor'\nimport { resolveCodeDefinitionForInstance } from './find-definition'\n\nexport interface FireTimerOptions {\n  instanceId: string\n  stepInstanceId?: string\n  branchInstanceId?: string | null\n  userId?: string\n  tenantId: string\n  organizationId: string\n}\n\nexport class TimerError extends Error {\n  constructor(\n    message: string,\n    public code: string,\n    public details?: any\n  ) {\n    super(message)\n    this.name = 'TimerError'\n  }\n}\n\n/**\n * Fire a timer and resume workflow execution.\n *\n * Mirrors `sendSignal` from signal-handler.ts \u2014 verifies the instance is\n * paused at a WAIT_FOR_TIMER step, logs TIMER_FIRED, exits the step, then\n * executes auto transitions and resumes the workflow.\n */\nexport async function fireTimer(\n  em: EntityManager,\n  container: AwilixContainer,\n  options: FireTimerOptions\n): Promise<void> {\n  const { instanceId, stepInstanceId, branchInstanceId, userId, tenantId, organizationId } = options\n\n  const eventLogger = container.resolve<typeof eventLoggerModule>('eventLogger')\n  const stepHandler = container.resolve<typeof stepHandlerModule>('stepHandler')\n  const transitionHandler = container.resolve<typeof transitionHandlerModule>('transitionHandler')\n  const workflowExecutor = container.resolve<typeof workflowExecutorModule>('workflowExecutor')\n\n  // Branch-scoped timer: the instance is FORKED and the branch is PAUSED at the\n  // WAIT_FOR_TIMER step. Resume just that branch, then drive the parallel loop.\n  if (branchInstanceId) {\n    await eventLogger.logWorkflowEvent(em, {\n      workflowInstanceId: instanceId,\n      stepInstanceId,\n      branchInstanceId,\n      eventType: 'TIMER_FIRED',\n      eventData: { firedAt: new Date().toISOString(), branch: true },\n      userId,\n      tenantId,\n      organizationId,\n    })\n    const { resumeBranch } = await import('./parallel-handler')\n    const resumed = await resumeBranch(em, {\n      instanceId,\n      branchInstanceId,\n      tenantId,\n      organizationId,\n      exitStepInstanceId: stepInstanceId,\n      exitOutput: { firedAt: new Date().toISOString() },\n    })\n    if (resumed) {\n      await workflowExecutor.executeWorkflow(em, container, instanceId, { userId })\n    }\n    return\n  }\n\n  const instance = await findOneWithDecryption(\n    em as PostgreSqlEntityManager,\n    WorkflowInstance,\n    {\n      id: instanceId,\n      tenantId,\n      organizationId,\n    },\n    undefined,\n    { tenantId, organizationId },\n  )\n\n  if (!instance) {\n    throw new TimerError(\n      'Workflow instance not found',\n      'INSTANCE_NOT_FOUND',\n      { instanceId }\n    )\n  }\n\n  if (instance.status !== 'PAUSED') {\n    throw new TimerError(\n      'Workflow is not paused',\n      'WORKFLOW_NOT_PAUSED',\n      { instanceId, status: instance.status }\n    )\n  }\n\n  const definition = (await findOneWithDecryption(\n    em as PostgreSqlEntityManager,\n    WorkflowDefinition,\n    {\n      id: instance.definitionId,\n      tenantId: instance.tenantId,\n      organizationId: instance.organizationId,\n      deletedAt: null,\n    },\n    undefined,\n    { tenantId: instance.tenantId, organizationId: instance.organizationId },\n  )) ?? resolveCodeDefinitionForInstance(instance)\n  if (!definition) {\n    throw new TimerError(\n      'Workflow definition not found',\n      'DEFINITION_NOT_FOUND',\n      { definitionId: instance.definitionId }\n    )\n  }\n\n  const currentStep = definition.definition.steps.find(\n    (s: any) => s.stepId === instance.currentStepId\n  )\n\n  if (!currentStep || currentStep.stepType !== 'WAIT_FOR_TIMER') {\n    throw new TimerError(\n      'Workflow is not waiting for timer',\n      'NOT_WAITING_FOR_TIMER',\n      { instanceId, currentStepId: instance.currentStepId }\n    )\n  }\n\n  const now = new Date()\n  instance.updatedAt = now\n\n  await eventLogger.logWorkflowEvent(em, {\n    workflowInstanceId: instance.id,\n    stepInstanceId,\n    eventType: 'TIMER_FIRED',\n    eventData: {\n      stepId: instance.currentStepId,\n      firedAt: now.toISOString(),\n    },\n    userId,\n    tenantId: instance.tenantId,\n    organizationId: instance.organizationId,\n  })\n\n  const stepInstance = stepInstanceId\n    ? await findOneWithDecryption(\n        em as PostgreSqlEntityManager,\n        StepInstance,\n        {\n          id: stepInstanceId,\n          workflowInstanceId: instance.id,\n          tenantId: instance.tenantId,\n          organizationId: instance.organizationId,\n        },\n        undefined,\n        { tenantId: instance.tenantId, organizationId: instance.organizationId },\n      )\n    : await findOneWithDecryption(\n        em as PostgreSqlEntityManager,\n        StepInstance,\n        {\n          workflowInstanceId: instance.id,\n          stepId: instance.currentStepId,\n          status: 'ACTIVE',\n          tenantId: instance.tenantId,\n          organizationId: instance.organizationId,\n        },\n        undefined,\n        { tenantId: instance.tenantId, organizationId: instance.organizationId },\n      )\n\n  if (stepInstance) {\n    await stepHandler.exitStep(em, stepInstance, {\n      firedAt: now.toISOString(),\n    })\n  }\n\n  const autoTransitions = (definition.definition.transitions || []).filter(\n    (t: any) => t.fromStepId === instance.currentStepId && t.trigger === 'auto'\n  )\n\n  if (autoTransitions.length === 0) {\n    instance.status = 'RUNNING'\n    await em.flush()\n    return\n  }\n\n  const transitionContext = {\n    workflowContext: instance.context,\n    userId,\n  }\n\n  const validTransitions = await transitionHandler.findValidTransitions(\n    em,\n    instance,\n    instance.currentStepId,\n    transitionContext\n  )\n\n  const firstValidTransition = validTransitions.find((t) => t.isValid)\n\n  if (!firstValidTransition || !firstValidTransition.transition) {\n    instance.status = 'RUNNING'\n    await em.flush()\n    return\n  }\n\n  // Resume from the paused wait BEFORE executing the transition, exactly as\n  // `sendSignal` does. Without it the executor's defense-in-depth PAUSED check\n  // stops the run at the very first step the timer traverses, so the instance\n  // sits at that step (typically END) as PAUSED and never completes.\n  instance.status = 'RUNNING'\n  await em.flush()\n\n  const transitionResult = await transitionHandler.executeTransition(\n    em,\n    container,\n    instance,\n    instance.currentStepId,\n    firstValidTransition.transition.toStepId,\n    { ...transitionContext, transitionId: firstValidTransition.transition.transitionId },\n  )\n\n  if (!transitionResult.success) {\n    throw new TimerError(\n      'Transition failed after timer fired',\n      'TRANSITION_FAILED',\n      { error: transitionResult.error }\n    )\n  }\n\n  await workflowExecutor.executeWorkflow(em, container, instance.id, { userId })\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/modules/workflows/lib/transition-handler.js

@@ -6,6 +6,13 @@ import * as ruleEngine from "../../business_rules/lib/rule-engine.js";
 import * as activityExecutor from "./activity-executor.js";
 import * as stepHandler from "./step-handler.js";
 import { findDefinitionForInstance } from "./find-definition.js";
+import { resolveDefinitionInterpolationMode } from "./interpolation-pipeline.js";
+import { buildSetVariableContextPatch, isSetVariableOutput } from "./set-variable.js";
+import {
+  resolveStepFailureHandling
+} from "./error-routing.js";
+import { DRY_RUN_EVENT_TYPES, isDryRunInstance } from "./dry-run.js";
+import { excludeNonNormalTransitions } from "./route-kinds.js";
 import {
   rootToken,
   tokenBranchInstanceId,
@@ -19,6 +26,33 @@ import {
 } from "./execution-token.js";
 import { createLogger } from "@open-mercato/shared/lib/logger";
 const logger = createLogger("workflows");
+function buildFailureRouting(handling, failedStepId) {
+  if (handling.kind === "route" && typeof handling.transition.toStepId === "string") {
+    return {
+      failedStepId,
+      errorRoute: {
+        transitionId: handling.transition.transitionId,
+        toStepId: handling.transition.toStepId
+      }
+    };
+  }
+  if (handling.kind === "park") {
+    return { failedStepId, parkForAttention: true };
+  }
+  if (handling.kind === "handlerStep") {
+    return { failedStepId, errorHandlerStepId: handling.stepId };
+  }
+  return {};
+}
+async function logSuppressedRuleActions(em, instance, ruleId, phase) {
+  await logTransitionEvent(em, {
+    workflowInstanceId: instance.id,
+    eventType: DRY_RUN_EVENT_TYPES.businessRuleActionsSuppressed,
+    eventData: { ruleId, phase },
+    tenantId: instance.tenantId,
+    organizationId: instance.organizationId
+  });
+}
 class TransitionError extends Error {
   constructor(message, code, details) {
     super(message);
@@ -42,7 +76,7 @@ async function evaluateTransition(em, instance, fromStepId, toStepId, context) {
     let transition;
     if (toStepId) {
       transition = transitions.find(
-        (t) => t.fromStepId === fromStepId && t.toStepId === toStepId
+        (candidate) => candidate.fromStepId === fromStepId && candidate.toStepId === toStepId && (context.transitionId === void 0 || candidate.transitionId === context.transitionId)
       );
       if (!transition) {
         return {
@@ -52,7 +86,7 @@ async function evaluateTransition(em, instance, fromStepId, toStepId, context) {
         };
       }
     } else {
-      const availableTransitions = transitions.filter(
+      const availableTransitions = excludeNonNormalTransitions(transitions).filter(
         (t) => t.fromStepId === fromStepId
       );
       if (availableTransitions.length === 0) {
@@ -108,7 +142,7 @@ async function findValidTransitions(em, instance, fromStepId, context) {
     if (!definition) {
       return [];
     }
-    const transitions = (definition.definition.transitions || []).filter((t) => t.fromStepId === fromStepId).sort((a, b) => (b.priority || 0) - (a.priority || 0));
+    const transitions = excludeNonNormalTransitions(definition.definition.transitions || []).filter((t) => t.fromStepId === fromStepId).sort((a, b) => (b.priority || 0) - (a.priority || 0));
     const results = [];
     for (const transition of transitions) {
       const conditionResult = await evaluateTransition(
@@ -116,7 +150,7 @@ async function findValidTransitions(em, instance, fromStepId, context) {
         instance,
         fromStepId,
         transition.toStepId,
-        context
+        { ...context, transitionId: transition.transitionId }
       );
       if (!conditionResult.isValid) {
         results.push(conditionResult);
@@ -222,6 +256,7 @@ async function executeTransitionForToken(em, container, token, fromStepId, toSte
     let activityOutputs = {};
     const activityResults = [];
     if (transition.activities && transition.activities.length > 0) {
+      const definitionForInterpolation = await findDefinitionForInstance(em, instance);
       const activityContext = {
         workflowInstance: instance,
         workflowContext: {
@@ -229,7 +264,8 @@ async function executeTransitionForToken(em, container, token, fromStepId, toSte
           ...context.workflowContext
         },
         branchInstanceId,
-        userId: context.userId
+        userId: context.userId,
+        interpolationMode: resolveDefinitionInterpolationMode(definitionForInterpolation?.definition)
       };
       const results = await activityExecutor.executeActivities(
         em,
@@ -240,6 +276,14 @@ async function executeTransitionForToken(em, container, token, fromStepId, toSte
       activityResults.push(...results);
       const failedActivities = results.filter((r) => !r.success);
       if (failedActivities.length > 0) {
+        const refusal = failedActivities.find((result) => result.dryRunRefused);
+        if (refusal) {
+          return {
+            success: false,
+            error: refusal.error ?? "Dry run stopped",
+            conditionsEvaluated: { preConditions: true, postConditions: false }
+          };
+        }
         const continueOnFailure = transition.continueOnActivityFailure ?? false;
         await logTransitionEvent(em, {
           workflowInstanceId: instance.id,
@@ -261,20 +305,57 @@ async function executeTransitionForToken(em, container, token, fromStepId, toSte
           organizationId: instance.organizationId
         });
         if (!continueOnFailure) {
-          return {
-            success: false,
-            error: `Activities failed: ${failedActivities.map((f) => f.error).join(", ")}`,
-            conditionsEvaluated: {
-              preConditions: true,
-              postConditions: false
+          const failureHandling = resolveStepFailureHandling(
+            definitionForInterpolation?.definition,
+            fromStepId
+          );
+          if (failureHandling.kind === "continue") {
+            await logTransitionEvent(em, {
+              workflowInstanceId: instance.id,
+              branchInstanceId,
+              eventType: "ERROR_DIRECTIVE_APPLIED",
+              eventData: {
+                stepId: fromStepId,
+                directive: "continueWithFallback",
+                transitionId: transition.transitionId || `${fromStepId}->${toStepId}`,
+                hasFallbackValue: failureHandling.fallbackValue !== void 0
+              },
+              userId: context.userId,
+              tenantId: instance.tenantId,
+              organizationId: instance.organizationId
+            });
+            if (failureHandling.fallbackValue !== void 0) {
+              activityOutputs[fromStepId] = failureHandling.fallbackValue;
             }
-          };
+          } else {
+            return {
+              success: false,
+              error: `Activities failed: ${failedActivities.map((f) => f.error).join(", ")}`,
+              conditionsEvaluated: {
+                preConditions: true,
+                postConditions: false
+              },
+              ...buildFailureRouting(failureHandling, fromStepId)
+            };
+          }
         }
       }
       results.forEach((result) => {
         if (result.success && result.output) {
-          const key = result.activityName || result.activityType;
-          activityOutputs[key] = result.output;
+          if (result.activityType === "SET_VARIABLE" && isSetVariableOutput(result.output)) {
+            const assignmentBase = {
+              ...tokenReadContext(token),
+              ...context.workflowContext,
+              ...activityOutputs
+            };
+            Object.assign(
+              activityOutputs,
+              buildSetVariableContextPatch(assignmentBase, result.output.assignments)
+            );
+          } else {
+            const key = result.activityName || result.activityType;
+            activityOutputs[key] = result.output;
+          }
         }
       });
     }
@@ -335,11 +416,37 @@ async function executeTransitionForToken(em, container, token, fromStepId, toSte
     );
     await em.flush();
     if (stepExecutionResult.status === "FAILED") {
-      return {
-        success: false,
-        error: stepExecutionResult.error || "Step execution failed"
-      };
+      const definitionForFailure = await findDefinitionForInstance(em, instance);
+      const failureHandling = resolveStepFailureHandling(definitionForFailure?.definition, toStepId);
+      if (failureHandling.kind === "continue") {
+        await logTransitionEvent(em, {
+          workflowInstanceId: instance.id,
+          branchInstanceId,
+          eventType: "ERROR_DIRECTIVE_APPLIED",
+          eventData: {
+            stepId: toStepId,
+            directive: "continueWithFallback",
+            transitionId: transition.transitionId || `${fromStepId}->${toStepId}`,
+            error: stepExecutionResult.error,
+            hasFallbackValue: failureHandling.fallbackValue !== void 0
+          },
+          userId: context.userId,
+          tenantId: instance.tenantId,
+          organizationId: instance.organizationId
+        });
+        if (failureHandling.fallbackValue !== void 0) {
+          mergeTokenContext(token, { [toStepId]: failureHandling.fallbackValue });
+          await em.flush();
+        }
+      } else {
+        return {
+          success: false,
+          error: stepExecutionResult.error || "Step execution failed",
+          ...buildFailureRouting(failureHandling, toStepId)
+        };
+      }
     }
+    const stepPaused = stepExecutionResult.status === "WAITING" && stepExecutionResult.waitReason !== "FORK";
     const postConditionsResult = await evaluatePostConditions(
       em,
       instance,
@@ -385,6 +492,7 @@ async function executeTransitionForToken(em, container, token, fromStepId, toSte
     return {
       success: true,
       nextStepId: toStepId,
+      paused: stepPaused,
       conditionsEvaluated: {
         preConditions: true,
         postConditions: postConditionsResult.allowed
@@ -463,6 +571,7 @@ async function evaluatePreConditions(em, instance, transition, context, eventBus
         totalExecutionTime: 0
       };
     }
+    const dryRun = isDryRunInstance(instance);
     const startTime = Date.now();
     const executedRules = [];
     const errors = [];
@@ -488,8 +597,17 @@ async function evaluatePreConditions(em, instance, transition, context, eventBus
         executedBy: context.userId,
         entityType: `workflow:${definition.workflowId}:transition`,
         entityId: transition.transitionId || `${transition.fromStepId}->${transition.toStepId}`,
-        eventType: "pre_transition"
+        eventType: "pre_transition",
+        // Dry run (spec section 8.2): the rule engine's own `dryRun` only
+        // suppresses its execution LOG — a rule's success/failure ACTIONS run
+        // regardless — so a side-effect-free run has to ask for `skipActions`.
+        // The conditions still evaluate, so the run takes the routes it really
+        // would; only the ACTION arm is withheld, and it is reported.
+        skipActions: dryRun
       });
+      if (dryRun && result.actionsExecuted === null) {
+        await logSuppressedRuleActions(em, instance, condition.ruleId, "pre_transition");
+      }
       const ruleResult = {
         rule: {
           ruleId: result.ruleId,
@@ -551,6 +669,7 @@ async function evaluatePostConditions(em, instance, transition, context, eventBu
         totalExecutionTime: 0
       };
     }
+    const dryRun = isDryRunInstance(instance);
     const startTime = Date.now();
     const executedRules = [];
     const errors = [];
@@ -576,8 +695,17 @@ async function evaluatePostConditions(em, instance, transition, context, eventBu
         executedBy: context.userId,
         entityType: `workflow:${definition.workflowId}:transition`,
         entityId: transition.transitionId || `${transition.fromStepId}->${transition.toStepId}`,
-        eventType: "post_transition"
+        eventType: "post_transition",
+        // Dry run (spec section 8.2): the rule engine's own `dryRun` only
+        // suppresses its execution LOG — a rule's success/failure ACTIONS run
+        // regardless — so a side-effect-free run has to ask for `skipActions`.
+        // The conditions still evaluate, so the run takes the routes it really
+        // would; only the ACTION arm is withheld, and it is reported.
+        skipActions: dryRun
       });
+      if (dryRun && result.actionsExecuted === null) {
+        await logSuppressedRuleActions(em, instance, condition.ruleId, "post_transition");
+      }
       const ruleResult = {
         rule: {
           ruleId: result.ruleId,