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

package/src/modules/workflows/lib/subgraph-clipboard.ts

@@ -0,0 +1,214 @@
+/**
+ * Portable-JSON subgraph clipboard (spec section 4.5).
+ *
+ * "Multi-select → portable-JSON subgraph on the clipboard; paste re-IDs and
+ * splices; works across workflows and into the Code view."
+ *
+ * The payload speaks the DEFINITION vocabulary (`steps` + `transitions`), not
+ * React Flow's nodes and edges: the Code view renders the definition JSON, so a
+ * fragment copied from the canvas has to be the same shape a fragment copied out
+ * of the Code view is — otherwise the two surfaces could not exchange anything.
+ * Positions ride along as `_editorPosition`, exactly as a saved definition
+ * carries them.
+ *
+ * Only transitions INTERNAL to the selection travel. A route with one endpoint
+ * outside the selection describes a connection to a step that is not in the
+ * payload, so pasting it could only invent a dangling id.
+ *
+ * PURE: plain data in, plain data out. Clipboard access, translation and flash
+ * messages belong to the page.
+ */
+
+import type { Node, Edge } from '@xyflow/react'
+import type { WorkflowDefinition } from '../data/entities'
+import { definitionToGraph, generateStepId, generateTransitionId, graphToDefinition } from './graph-utils'
+import { isDataMappingEdge } from './data-edge-mapping'
+import { isAnnotationNode } from './editor-annotations'
+
+/** Format discriminator. Written by the canvas and by the Code view alike. */
+export const WORKFLOW_SUBGRAPH_CLIPBOARD_KIND = 'open-mercato.workflow-subgraph'
+
+/** Bumped only for a breaking payload change; readers refuse what they do not know. */
+export const WORKFLOW_SUBGRAPH_CLIPBOARD_VERSION = 1
+
+/** How far a pasted copy lands from the original, in flow units. */
+export const SUBGRAPH_PASTE_OFFSET = { x: 48, y: 48 }
+
+type DefinitionStep = WorkflowDefinition['definition']['steps'][number]
+type DefinitionTransition = WorkflowDefinition['definition']['transitions'][number]
+
+export interface WorkflowSubgraphClipboard {
+  kind: typeof WORKFLOW_SUBGRAPH_CLIPBOARD_KIND
+  version: typeof WORKFLOW_SUBGRAPH_CLIPBOARD_VERSION
+  steps: DefinitionStep[]
+  transitions: DefinitionTransition[]
+}
+
+export type SubgraphClipboardParseFailure =
+  | { ok: false; code: 'invalidJson' }
+  | { ok: false; code: 'unsupportedFormat' }
+  | { ok: false; code: 'empty' }
+
+export type SubgraphClipboardParseResult =
+  | { ok: true; payload: WorkflowSubgraphClipboard }
+  | SubgraphClipboardParseFailure
+
+export interface SubgraphPasteResult {
+  nodes: Node[]
+  edges: Edge[]
+  /** Ids of the freshly minted steps, so the caller can select what it pasted. */
+  pastedNodeIds: string[]
+}
+
+/**
+ * Serialize the selected steps and the routes strictly between them.
+ *
+ * Returns `null` when the selection holds no step: a clipboard payload with no
+ * steps has nothing to splice, and writing one would silently clear whatever the
+ * author copied earlier.
+ */
+export function serializeWorkflowSubgraph(
+  nodes: Node[],
+  edges: Edge[],
+  selectedNodeIds: string[],
+): WorkflowSubgraphClipboard | null {
+  const selected = new Set(selectedNodeIds)
+  // Annotations never travel on the clipboard: the payload speaks the definition
+  // vocabulary, and a note has no definition form to speak.
+  const selectedNodes = nodes.filter((node) => selected.has(node.id) && !isAnnotationNode(node))
+  if (selectedNodes.length === 0) return null
+
+  const internalEdges = edges.filter(
+    (edge) => selected.has(edge.source) && selected.has(edge.target) && !isDataMappingEdge(edge),
+  )
+  const definition = graphToDefinition(selectedNodes, internalEdges, { includePositions: true })
+
+  return {
+    kind: WORKFLOW_SUBGRAPH_CLIPBOARD_KIND,
+    version: WORKFLOW_SUBGRAPH_CLIPBOARD_VERSION,
+    steps: definition.steps,
+    transitions: definition.transitions,
+  }
+}
+
+export function stringifyWorkflowSubgraph(payload: WorkflowSubgraphClipboard): string {
+  return JSON.stringify(payload, null, 2)
+}
+
+/** Read a clipboard payload, refusing anything that is not this exact format. */
+export function parseWorkflowSubgraph(text: string): SubgraphClipboardParseResult {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    return { ok: false, code: 'invalidJson' }
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { ok: false, code: 'unsupportedFormat' }
+  }
+  const candidate = parsed as Record<string, unknown>
+  if (candidate.kind !== WORKFLOW_SUBGRAPH_CLIPBOARD_KIND) {
+    return { ok: false, code: 'unsupportedFormat' }
+  }
+  if (candidate.version !== WORKFLOW_SUBGRAPH_CLIPBOARD_VERSION) {
+    return { ok: false, code: 'unsupportedFormat' }
+  }
+  const steps = candidate.steps
+  const transitions = candidate.transitions
+  if (!Array.isArray(steps) || !Array.isArray(transitions)) {
+    return { ok: false, code: 'unsupportedFormat' }
+  }
+  if (steps.length === 0) return { ok: false, code: 'empty' }
+
+  return {
+    ok: true,
+    payload: {
+      kind: WORKFLOW_SUBGRAPH_CLIPBOARD_KIND,
+      version: WORKFLOW_SUBGRAPH_CLIPBOARD_VERSION,
+      steps: steps as DefinitionStep[],
+      transitions: transitions as DefinitionTransition[],
+    },
+  }
+}
+
+/**
+ * Keep the meaningful part of a generated step id so a paste of `userTask_1753…`
+ * stays recognisably a user task instead of turning into `step_…`, without the
+ * id growing a suffix on every paste.
+ */
+function deriveStepIdPrefix(stepId: string): string {
+  const withoutGeneratedSuffix = stepId.replace(/_\d{9,}_[a-z0-9]+$/i, '')
+  const prefix = withoutGeneratedSuffix.trim()
+  return prefix.length > 0 ? prefix : 'step'
+}
+
+export interface SubgraphPasteOptions {
+  /** Flow-space translation applied to every pasted step. */
+  offset?: { x: number; y: number }
+}
+
+/**
+ * Splice a clipboard payload into the graph.
+ *
+ * Every step and every transition is re-IDed, so pasting into the workflow the
+ * fragment came from can never collide with — or silently merge into — the
+ * original. Internal routes are rewired onto the new ids; the copies land offset
+ * from the originals so the paste is visible rather than hidden underneath them.
+ */
+export function pasteWorkflowSubgraph(
+  nodes: Node[],
+  edges: Edge[],
+  payload: WorkflowSubgraphClipboard,
+  options: SubgraphPasteOptions = {},
+): SubgraphPasteResult {
+  const offset = options.offset ?? SUBGRAPH_PASTE_OFFSET
+  const existingIds = new Set(nodes.map((node) => node.id))
+
+  const stepIdMap = new Map<string, string>()
+  for (const step of payload.steps) {
+    let nextId = generateStepId(deriveStepIdPrefix(step.stepId))
+    while (existingIds.has(nextId) || stepIdMap.has(nextId)) {
+      nextId = generateStepId(deriveStepIdPrefix(step.stepId))
+    }
+    existingIds.add(nextId)
+    stepIdMap.set(step.stepId, nextId)
+  }
+
+  const rebasedSteps = payload.steps.map((step) => ({
+    ...step,
+    stepId: stepIdMap.get(step.stepId) as string,
+  }))
+
+  const rebasedTransitions = payload.transitions
+    .filter((transition) => stepIdMap.has(transition.fromStepId) && stepIdMap.has(transition.toStepId))
+    .map((transition) => ({
+      ...transition,
+      transitionId: generateTransitionId(),
+      fromStepId: stepIdMap.get(transition.fromStepId) as string,
+      toStepId: stepIdMap.get(transition.toStepId) as string,
+    }))
+
+  const graph = definitionToGraph({
+    steps: rebasedSteps,
+    transitions: rebasedTransitions,
+  } as WorkflowDefinition['definition'])
+
+  const pastedNodes = graph.nodes.map((node) => {
+    // The running step number is derived from a node's index in the whole graph,
+    // so a fragment's own numbering would be a lie once it is spliced in.
+    const data = { ...(node.data as Record<string, unknown>) }
+    delete data.stepNumber
+    return {
+      ...node,
+      position: { x: node.position.x + offset.x, y: node.position.y + offset.y },
+      selected: true,
+      data,
+    }
+  })
+
+  return {
+    nodes: [...nodes.map((node) => (node.selected ? { ...node, selected: false } : node)), ...pastedNodes],
+    edges: [...edges, ...graph.edges],
+    pastedNodeIds: pastedNodes.map((node) => node.id),
+  }
+}

package/src/modules/workflows/lib/task-decision-context.ts

@@ -0,0 +1,76 @@
+/**
+ * Re-resolving a task's decision buttons from its instance's pinned definition.
+ *
+ * Separated from the pure `lib/task-decisions.ts` because it needs the ORM: the
+ * task surfaces (a client page, a record-page widget) import the pure half, and
+ * only the server imports this one.
+ */
+
+import type { EntityManager } from '@mikro-orm/core'
+import { StepInstance, WorkflowInstance } from '../data/entities'
+import type { UserTask } from '../data/entities'
+import { findDefinitionForInstance } from './find-definition'
+import { readAuthoredTaskDecisions } from './task-decisions'
+import { resolveTaskDecisions } from './task-resolution'
+import type { ResolvedTaskDecision, TaskInterpolate } from './task-resolution'
+
+export type TaskDecisionContext = {
+  stepId: string | null
+  decisions: ResolvedTaskDecision[]
+  /**
+   * Authored `userTaskConfig.formKey`, resolved the same way the decisions are:
+   * from the instance's PINNED definition, never from a column. A task form is
+   * a rendering choice, so re-reading it per request is what lets a definition
+   * that gains a renderer key start using it — and it needs no migration.
+   */
+  formKey: string | null
+}
+
+export const EMPTY_TASK_DECISION_CONTEXT: TaskDecisionContext = {
+  stepId: null,
+  decisions: [],
+  formKey: null,
+}
+
+/**
+ * Re-resolve a task's decision buttons from its instance's pinned definition.
+ *
+ * Degrades to an empty list at every step — a task whose instance, step or
+ * definition has gone missing still completes through the plain form, which is
+ * exactly how every task behaved before decisions existed.
+ */
+export async function loadTaskDecisionContext(
+  em: EntityManager,
+  task: Pick<UserTask, 'workflowInstanceId' | 'stepInstanceId'>,
+): Promise<TaskDecisionContext> {
+  const instance = await em.findOne(WorkflowInstance, { id: task.workflowInstanceId })
+  if (!instance) return EMPTY_TASK_DECISION_CONTEXT
+
+  const stepInstance = await em.findOne(StepInstance, { id: task.stepInstanceId })
+  if (!stepInstance) return EMPTY_TASK_DECISION_CONTEXT
+
+  const definition = await findDefinitionForInstance(em, instance)
+  if (!definition) return { stepId: stepInstance.stepId, decisions: [], formKey: null }
+
+  const formKey = readAuthoredTaskFormKey(definition.definition, stepInstance.stepId)
+  const authored = readAuthoredTaskDecisions(definition.definition, stepInstance.stepId)
+  if (!authored.length) return { stepId: stepInstance.stepId, decisions: [], formKey }
+
+  const { interpolateVariables } = await import('./activity-executor')
+  const interpolate: TaskInterpolate = (value) =>
+    interpolateVariables(value, instance.context ?? {}, instance)
+
+  return {
+    stepId: stepInstance.stepId,
+    decisions: resolveTaskDecisions(authored, interpolate),
+    formKey,
+  }
+}
+
+function readAuthoredTaskFormKey(definition: unknown, stepId: string): string | null {
+  const steps = (definition as { steps?: { stepId?: string; userTaskConfig?: { formKey?: unknown } }[] })
+    ?.steps
+  const step = (steps ?? []).find((candidate) => candidate.stepId === stepId)
+  const formKey = step?.userTaskConfig?.formKey
+  return typeof formKey === 'string' && formKey.length > 0 ? formKey : null
+}

package/src/modules/workflows/lib/task-decisions.ts

@@ -0,0 +1,117 @@
+/**
+ * Decision buttons on a task: the CHOICE and the routing rules (PURE).
+ *
+ * Rendering the list and recording the press are two different requirements
+ * wearing one name, and they are stored differently on purpose (run checkpoint
+ * 2, decision #2):
+ *
+ * - **The list is derived state.** A task reaches its config through
+ *   `workflowInstanceId -> definition -> step.userTaskConfig.decisions`, and an
+ *   instance PINS its definition row, so re-resolving it per request is always
+ *   correct and needs no column. `lib/task-decision-context.ts` does that
+ *   resolution (it needs the ORM); everything here stays free of it so the task
+ *   surfaces can import the reserved key and the readers without dragging the
+ *   entity graph into a client bundle.
+ * - **The choice is an audit fact about the completion**, with a different
+ *   lifetime from the list. It is written into the completion payload that
+ *   already exists (`user_tasks.form_data`, under `TASK_DECISION_FORM_KEY`) and
+ *   into the `USER_TASK_COMPLETED` event, rather than into a new column.
+ */
+
+import type { TaskDecision } from '../data/validators'
+import { excludeNonNormalTransitions } from './route-kinds'
+import type { ResolvedTaskDecision } from './task-resolution'
+
+/**
+ * Reserved key the chosen decision id is recorded under inside the completion
+ * `formData`. Prefixed like the engine's other reserved context key
+ * (`context.__error`) so it cannot collide with an authored form field, and so
+ * a downstream route condition can branch on the operator's choice once the
+ * form data is merged into the run context.
+ */
+export const TASK_DECISION_FORM_KEY = '__decision'
+
+export type TaskDecisionTransitionLike = {
+  transitionId?: string
+  fromStepId?: string
+  toStepId?: string
+  kind?: string
+}
+
+export function findTaskDecision(
+  decisions: ResolvedTaskDecision[],
+  decisionId: string,
+): ResolvedTaskDecision | null {
+  return decisions.find((decision) => decision.id === decisionId) ?? null
+}
+
+/**
+ * The outgoing route a decision selects.
+ *
+ * Matched on the transition's DURABLE id and constrained to routes leaving the
+ * step the task is parked on — a decision may never send the run down a route
+ * that does not start where the run currently is. Error routes are excluded for
+ * the same reason every other routing lookup excludes them: they are reachable
+ * only from a failure, never from a button.
+ */
+export function findTaskDecisionTransition<T extends TaskDecisionTransitionLike>(
+  transitions: T[] | undefined | null,
+  transitionId: string,
+  fromStepId: string,
+): T | null {
+  if (!transitions?.length) return null
+  const candidates = excludeNonNormalTransitions(transitions)
+  return (
+    candidates.find(
+      (transition) =>
+        transition.transitionId === transitionId && transition.fromStepId === fromStepId,
+    ) ?? null
+  )
+}
+
+/** Record the chosen decision inside the completion payload that already exists. */
+export function withRecordedDecision(
+  formData: Record<string, unknown>,
+  decisionId: string | null | undefined,
+): Record<string, unknown> {
+  if (!decisionId) return formData
+  return { ...formData, [TASK_DECISION_FORM_KEY]: decisionId }
+}
+
+/** The decision id a completed task recorded, when it recorded one. */
+export function readRecordedDecision(formData: unknown): string | null {
+  if (!formData || typeof formData !== 'object' || Array.isArray(formData)) return null
+  const value = (formData as Record<string, unknown>)[TASK_DECISION_FORM_KEY]
+  return typeof value === 'string' && value.length > 0 ? value : null
+}
+
+/**
+ * Decisions as authored, narrowed structurally.
+ *
+ * A definition row is validated on save, but code-registry definitions never
+ * pass through zod, so an entry missing its id or its route binding is dropped
+ * here rather than rendered as a button that can only fail.
+ */
+export function readAuthoredTaskDecisions(definitionData: unknown, stepId: string): TaskDecision[] {
+  if (!definitionData || typeof definitionData !== 'object') return []
+  const steps = (definitionData as { steps?: unknown }).steps
+  if (!Array.isArray(steps)) return []
+  const step = steps.find(
+    (candidate) =>
+      !!candidate &&
+      typeof candidate === 'object' &&
+      (candidate as { stepId?: unknown }).stepId === stepId,
+  ) as { userTaskConfig?: { decisions?: unknown } } | undefined
+  const authored = step?.userTaskConfig?.decisions
+  if (!Array.isArray(authored)) return []
+
+  const decisions: TaskDecision[] = []
+  for (const entry of authored) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue
+    const candidate = entry as Record<string, unknown>
+    if (typeof candidate.id !== 'string' || !candidate.id.length) continue
+    if (typeof candidate.transitionId !== 'string' || !candidate.transitionId.length) continue
+    decisions.push(candidate as unknown as TaskDecision)
+  }
+  return decisions
+}

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

@@ -0,0 +1,181 @@
+/**
+ * Builds the `TaskEntityAccessMap` the visibility predicate consumes — the
+ * impure half of the entity gate.
+ *
+ * ## What "entity access" means here, exactly
+ *
+ * **Entity TYPE plus scope. There is no record-level ACL in this platform and
+ * this resolver does not add one.** The query engine's public interface is
+ * `query(entity, opts)` with no ACL seam anywhere in it, and the only per-record
+ * rule in the repo is `assertCanAccessChannel`, a bespoke owner comparison over
+ * an already-loaded row. So the guarantee this makes is: *you may see a task
+ * about a deal iff you may see deals at all, and the task is inside your tenant
+ * and organization.* A user who can see deals can see a task about ANY deal in
+ * their organization, including one they would never have opened themselves.
+ * Do not read more into it, and do not let a caller document it as row-level.
+ *
+ * Verifying each BOUND RECORD's own organization would cost one query per
+ * (entity type, id) per row, and there is no generic `(entityType, recordId) →
+ * record` resolver to do it with. Accepted residual risk, on the review
+ * checklist. The portal path does not accept it — there the record identity is
+ * compared directly against the caller's owned ids.
+ *
+ * ## Cost
+ *
+ * ONE `loadAcl` and ONE classification pass per REQUEST, keyed on the distinct
+ * entity types across the whole page. `assertEntityAclForRequest` calls
+ * `rbac.loadAcl` on every invocation, so calling it per binding would issue ~100
+ * ACL loads for a 50-row inbox page with two bindings each.
+ *
+ * ## Failure
+ *
+ * Nothing here is caught. A resolver that throws must fail the whole request —
+ * degrading to an empty map would leave the predicate with no key for any
+ * binding, and while that denies today, "swallow the error and carry on" is the
+ * shape of bug that later becomes "swallow the error and pass". Absence of data
+ * is not failure: a task with no bindings asks nothing of this map.
+ */
+
+import type { EntityManager } from '@mikro-orm/core'
+import { classifyRecordsEntity } from '@open-mercato/core/modules/entities/lib/entityClassification'
+import { resolveEntityAclRequirement } from '@open-mercato/core/modules/entities/lib/entityAcl'
+import {
+  RECORDS_VIEW_FEATURE,
+  deriveCustomEntityRecordFeature,
+} from '@open-mercato/core/modules/entities/lib/recordFeatures'
+import {
+  normalizeTaskEntityTypeSpelling,
+  normalizeTaskEntityTypeToEntityId,
+} from './task-entity-types'
+import type { TaskEntityAccessDecision, TaskEntityAccessMap } from './task-visibility'
+
+export type TaskEntityAccessScope = { tenantId: string | null; organizationId: string | null }
+
+export type TaskEntityAccessAcl = {
+  isSuperAdmin: boolean
+  features: string[]
+}
+
+/** The slice of `RbacService` this resolver needs, so tests need no container. */
+export type TaskEntityAccessRbacService = {
+  loadAcl(userId: string, scope: TaskEntityAccessScope): Promise<TaskEntityAccessAcl | null>
+}
+
+export type ResolveTaskEntityAccessInput = {
+  /** Distinct authored `entityType` values across the page. Deduped here. */
+  entityTypes: Iterable<string>
+  em: EntityManager
+  rbac: TaskEntityAccessRbacService
+  userId: string
+  scope: TaskEntityAccessScope
+}
+
+export type TaskEntityAccessResult = {
+  map: TaskEntityAccessMap
+  /**
+   * Returned alongside the map because the caller needs both to build the
+   * principal, and loading the ACL twice per request is the cost this resolver
+   * exists to avoid.
+   */
+  isSuperAdmin: boolean
+  grantedFeatures: string[]
+}
+
+type BoundTask = { entityBindings?: readonly { entityType?: unknown }[] | null }
+
+/**
+ * The distinct authored entity types across a page of tasks, verbatim.
+ *
+ * Verbatim matters: the map is keyed on exactly the string the binding carries,
+ * so the predicate's lookup is an identity match and "no key" unambiguously
+ * means the resolver never saw that type. Normalization happens INSIDE the
+ * resolver, where a normalization failure has a `unknown-entity-type` answer to
+ * record.
+ */
+export function collectTaskEntityTypes(tasks: Iterable<BoundTask>): string[] {
+  const seen = new Set<string>()
+  for (const task of tasks) {
+    for (const binding of task.entityBindings ?? []) {
+      const entityType = binding?.entityType
+      if (typeof entityType === 'string' && entityType.length > 0) seen.add(entityType)
+    }
+  }
+  return [...seen]
+}
+
+/**
+ * Mirrors `assertEntityAclForRequest`: an unrestricted custom entity is
+ * authorized by the coarse route-level feature alone; a restricted one also
+ * needs its synthesized per-entity grant.
+ */
+function customEntityRequirement(entityId: string, restricted: boolean): TaskEntityAccessDecision {
+  return restricted
+    ? {
+        kind: 'requires',
+        features: [RECORDS_VIEW_FEATURE, deriveCustomEntityRecordFeature(entityId, 'view')],
+      }
+    : { kind: 'requires', features: [RECORDS_VIEW_FEATURE] }
+}
+
+async function decideEntityType(
+  entityType: string,
+  em: EntityManager,
+  scope: TaskEntityAccessScope,
+): Promise<TaskEntityAccessDecision> {
+  const entityId = normalizeTaskEntityTypeToEntityId(entityType)
+
+  if (!entityId) {
+    // A TENANT-CREATED custom entity (a `custom_entities` row, not a module's
+    // `ce.ts`) is absent from the generated registry, so normalization cannot
+    // vouch for it and refusing here would hide every task bound to one. Ask the
+    // classifier instead: a real registration inside the caller's own scope is
+    // proof enough, and anything the classifier does not recognize either is a
+    // genuine authored typo — reported as its own reason so the Problems panel
+    // can name it rather than leaving an author staring at an invisible task.
+    const spelling = normalizeTaskEntityTypeSpelling(entityType)
+    const fallback = await classifyRecordsEntity(em, spelling, scope)
+    if (fallback.kind !== 'custom') return { kind: 'unknown-entity-type' }
+    return customEntityRequirement(spelling, fallback.restricted)
+  }
+
+  const classification = await classifyRecordsEntity(em, entityId, scope)
+
+  if (classification.kind === 'custom') return customEntityRequirement(entityId, classification.restricted)
+
+  if (classification.kind === 'system') {
+    const requirement = resolveEntityAclRequirement(entityId)
+    // No entry, or a platform-only entity: `entityAcl.ts` answers 403 for both,
+    // and so does this.
+    if (!requirement || requirement.platformOnly) return { kind: 'unavailable' }
+    return { kind: 'requires', features: requirement.view }
+  }
+
+  return { kind: 'unavailable' }
+}
+
+/**
+ * Resolve, once per request, what each bound entity type requires of the caller.
+ *
+ * The map carries REQUIREMENTS, not verdicts — the wildcard-aware match happens
+ * in the predicate, so there is exactly one place that decides anything. A
+ * superadmin is the single exception: they short-circuit the entity gate in
+ * `entityAcl.ts` too, so every type resolves to an empty requirement.
+ */
+export async function resolveTaskEntityAccess(
+  input: ResolveTaskEntityAccessInput,
+): Promise<TaskEntityAccessResult> {
+  const distinct = [...new Set(input.entityTypes)]
+  const acl = await input.rbac.loadAcl(input.userId, input.scope)
+  const isSuperAdmin = acl?.isSuperAdmin === true
+  const grantedFeatures = acl?.features ?? []
+
+  const map = new Map<string, TaskEntityAccessDecision>()
+  for (const entityType of distinct) {
+    map.set(
+      entityType,
+      isSuperAdmin ? { kind: 'requires', features: [] } : await decideEntityType(entityType, input.em, input.scope),
+    )
+  }
+
+  return { map, isSuperAdmin, grantedFeatures }
+}

package/src/modules/workflows/lib/task-entity-aliases.ts

@@ -0,0 +1,77 @@
+/**
+ * The ONE alias dictionary for authored task `entityType` values (PURE — zero
+ * imports, safe in a client bundle).
+ *
+ * A binding's `entityType` is free text: the inspector offers `customers:person`
+ * as a placeholder and stores whatever the author typed, while the ACL
+ * requirement table and the entity registry are keyed on the GENERATED id
+ * (`customers:customer_person_profile`). Two consumers need the same spellings —
+ * `task-entity-types.ts` resolves them to an entity id for the visibility gate,
+ * `work-inbox/entity-links.ts` resolves them to a record deep link — and they
+ * read this table rather than each keeping a copy. The repo already carries
+ * divergent alias tables in `customers/ai-agents-context.ts` and the
+ * optimistic-lock `resourceKind` readers; a fourth one is not acceptable.
+ *
+ * It lives in its own module, with nothing imported, so the client-side deep
+ * link code never pulls the entity registry in behind it.
+ */
+
+export type TaskEntityTypeAliasGroup = {
+  /** The generated entity id every spelling in the group means. */
+  entityId: string
+  /** Normalized spellings (`module:entity`, lower case) that authors write. */
+  spellings: readonly string[]
+}
+
+/**
+ * Alternate spellings that unambiguously mean one generated entity id.
+ *
+ * `customers:customer_entity` is deliberately absent — it backs both people and
+ * companies, so no single id is the right answer and leaving a binding on it
+ * unresolvable is the correct outcome.
+ */
+export const TASK_ENTITY_TYPE_ALIAS_GROUPS: readonly TaskEntityTypeAliasGroup[] = [
+  {
+    entityId: 'customers:customer_person_profile',
+    spellings: ['customers:person', 'customers:people', 'customers:customer_person_profile'],
+  },
+  {
+    entityId: 'customers:customer_company_profile',
+    spellings: ['customers:company', 'customers:companies', 'customers:customer_company_profile'],
+  },
+  {
+    entityId: 'customers:customer_deal',
+    spellings: ['customers:deal', 'customers:deals', 'customers:customer_deal'],
+  },
+  {
+    entityId: 'sales:sales_order',
+    spellings: ['sales:order', 'sales:orders', 'sales:sales_order', 'sales:document'],
+  },
+]
+
+const ALIAS_LOOKUP: ReadonlyMap<string, string> = new Map(
+  TASK_ENTITY_TYPE_ALIAS_GROUPS.flatMap((group) =>
+    group.spellings.map((spelling) => [spelling, group.entityId] as const),
+  ),
+)
+
+/**
+ * `Customers.Person` / `customers.person` / ` customers:person ` →
+ * `customers:person`.
+ *
+ * Entity ids are written `module:entity` while record-detail injection contexts
+ * use `module.entity` (`resourceKind`), and authors type both.
+ */
+export function normalizeTaskEntityTypeSpelling(entityType: string): string {
+  return entityType.trim().toLowerCase().replace(/\./g, ':')
+}
+
+/** The generated entity id an enumerated spelling means, or `null`. */
+export function resolveAliasedTaskEntityId(entityType: string): string | null {
+  return ALIAS_LOOKUP.get(normalizeTaskEntityTypeSpelling(entityType)) ?? null
+}
+
+/** Every enumerated spelling, mapped to its generated entity id. */
+export function listTaskEntityTypeAliases(): ReadonlyMap<string, string> {
+  return ALIAS_LOOKUP
+}