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

package/src/modules/workflows/lib/task-permission-settings.ts

@@ -0,0 +1,117 @@
+/**
+ * The tenant opt-out from the §6.4 task-permission model.
+ *
+ * ## What it is
+ *
+ * One tenant-scoped boolean, `workflows` / `task_permissions_business_context`,
+ * default `true`. `true` is the new model. `false` restores the pre-change READ
+ * filter — `SCOPE ∧ workflows.tasks.view` — on the task list, the task detail
+ * and the work inbox, and nothing else.
+ *
+ * ## What it is NOT
+ *
+ * **It is a `SELECT` filter, not an authorization mode.** `actable` and
+ * `claimable` are computed by the new rule whether it is on or off: completing
+ * still requires being the assignee or claimant, claiming still requires role
+ * overlap on an unclaimed `PENDING` row, tenant and organization scoping are
+ * never reachable by a setting, and the portal routes never consult it at all.
+ * If `businessContextEnabled` is read anywhere outside a read filter, that is a
+ * review failure. The predicate enforces this structurally — the flag reaches
+ * `decideTaskVisibility` as `policy` and only ever widens `visible`.
+ *
+ * ## Why the read fails to `true`
+ *
+ * The exemplar this route is copied from (`entities/api/entity-settings.ts`)
+ * swallows read errors and returns its permissive default. Inverted here on
+ * purpose: a config read that fails — no container, no service, a broken row —
+ * must NOT silently reopen every task in the tenant to everyone holding
+ * `workflows.tasks.view`. Only an explicitly stored, explicitly false value
+ * opts a tenant out.
+ *
+ * ## Lifecycle
+ *
+ * A migration aid with a removal date. It exists for one minor release so a
+ * tenant with an unusual role topology can keep the lights on while they grant
+ * `workflows.tasks.view_all`, and it is removed in the release after. A
+ * permanent opt-out is a permanent second security model to test.
+ */
+
+import { parseBooleanFromUnknown } from '@open-mercato/shared/lib/boolean'
+import type { TaskVisibilityPolicy } from './task-visibility'
+
+/** `module_configs.module_id` for the workflows module's own settings. */
+export const WORKFLOWS_CONFIG_MODULE = 'workflows'
+
+/** `module_configs.name`. Well within `moduleConfigKeySchema`'s 128 chars. */
+export const TASK_PERMISSIONS_BUSINESS_CONTEXT_KEY = 'task_permissions_business_context'
+
+/** Default-ON at release, per the spec's flagged BC paragraph. */
+export const TASK_PERMISSIONS_BUSINESS_CONTEXT_DEFAULT = true
+
+/** The `ModuleConfigService` slice this needs, so tests need no container. */
+export type TaskPermissionsConfigService = {
+  getValue: (
+    moduleId: string,
+    name: string,
+    options?: { defaultValue?: unknown; scope?: { tenantId?: string | null } },
+  ) => Promise<unknown>
+  setValue: (
+    moduleId: string,
+    name: string,
+    value: unknown,
+    scope?: { tenantId?: string | null },
+  ) => Promise<unknown>
+}
+
+/**
+ * Read the tenant's setting.
+ *
+ * Tenant-scoped only — never organization-scoped. One organization inside a
+ * tenant running wide open next to a narrow one is unreviewable, so the scope
+ * carries `tenantId` and nothing else. Callers MUST pass the tenant id from the
+ * authenticated context, never from request input.
+ */
+export async function readTaskPermissionsBusinessContext(
+  moduleConfigService: TaskPermissionsConfigService | null | undefined,
+  tenantId: string | null,
+): Promise<boolean> {
+  if (!moduleConfigService) return TASK_PERMISSIONS_BUSINESS_CONTEXT_DEFAULT
+  try {
+    const value = await moduleConfigService.getValue(
+      WORKFLOWS_CONFIG_MODULE,
+      TASK_PERMISSIONS_BUSINESS_CONTEXT_KEY,
+      {
+        defaultValue: TASK_PERMISSIONS_BUSINESS_CONTEXT_DEFAULT,
+        scope: { tenantId },
+      },
+    )
+    const parsed = parseBooleanFromUnknown(value)
+    // An unparseable stored value is a resolution failure, not an opt-out.
+    return parsed === null ? TASK_PERMISSIONS_BUSINESS_CONTEXT_DEFAULT : parsed
+  } catch {
+    return TASK_PERMISSIONS_BUSINESS_CONTEXT_DEFAULT
+  }
+}
+
+/** The `policy` argument `decideTaskVisibility` and the filter builders take. */
+export async function resolveTaskVisibilityPolicy(
+  moduleConfigService: TaskPermissionsConfigService | null | undefined,
+  tenantId: string | null,
+): Promise<TaskVisibilityPolicy> {
+  return {
+    businessContextEnabled: await readTaskPermissionsBusinessContext(moduleConfigService, tenantId),
+  }
+}
+
+export async function writeTaskPermissionsBusinessContext(
+  moduleConfigService: TaskPermissionsConfigService,
+  tenantId: string,
+  enabled: boolean,
+): Promise<void> {
+  await moduleConfigService.setValue(
+    WORKFLOWS_CONFIG_MODULE,
+    TASK_PERMISSIONS_BUSINESS_CONTEXT_KEY,
+    enabled,
+    { tenantId },
+  )
+}

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

@@ -0,0 +1,95 @@
+/**
+ * Task presets (spec §6.1, item 7).
+ *
+ * PURE: a preset is a data transformation over the inspector's drafts, so the
+ * shape it produces is unit-testable — and provable to parse — without opening
+ * the editor. Every piece of author-facing copy is passed IN by the caller,
+ * which is what keeps the labels translated (`useT` lives in the component)
+ * while the rule about what a preset contains lives here.
+ */
+
+import type { FormField } from '../components/fields/FormFieldArrayEditor'
+import {
+  newDecisionDraft,
+  newEntityBindingDraft,
+  type TaskDecisionDraft,
+  type TaskEntityBindingDraft,
+} from './task-inspector-config'
+
+export const APPROVAL_PRESET_COMMENT_FIELD = 'comment'
+
+export interface ApprovalPresetCopy {
+  approveLabel: string
+  rejectLabel: string
+  commentLabel: string
+}
+
+export interface ApprovalPresetRoutes {
+  /** Durable transition ids of the step's outgoing routes, in evaluation order. */
+  approveTransitionId?: string
+  rejectTransitionId?: string
+}
+
+export interface ApprovalPresetInput extends ApprovalPresetCopy, ApprovalPresetRoutes {
+  decisions?: TaskDecisionDraft[]
+  formFields?: FormField[]
+  entityBindings?: TaskEntityBindingDraft[]
+}
+
+export interface ApprovalPresetResult {
+  decisions: TaskDecisionDraft[]
+  formFields: FormField[]
+  entityBindings: TaskEntityBindingDraft[]
+  /** True when the preset left an empty binding row for the author to complete. */
+  promptsForEntityBinding: boolean
+}
+
+/**
+ * Approve / Reject plus a comment field, bound to the step's first two
+ * outgoing routes.
+ *
+ * Three deliberate choices:
+ *
+ * - It is ADDITIVE. Existing decisions, form fields and bindings are kept, and
+ *   a decision already bound to a route the preset would use is left alone —
+ *   applying the preset twice must not double the buttons or overwrite copy an
+ *   author wrote.
+ * - Routes are bound by their DURABLE ids, taken from the step's real outgoing
+ *   transitions. When a route is missing the button is still created with an
+ *   empty binding rather than an invented id: an unbound button is visible and
+ *   fixable, a fabricated id is a silently broken workflow.
+ * - It PROMPTS for the entity binding rather than guessing one. An approval is
+ *   always an approval OF something, and the ledger path that yields that
+ *   record is the one thing a preset genuinely cannot know, so it seeds an
+ *   empty binding row instead of leaving the section untouched.
+ */
+export function buildApprovalPreset(input: ApprovalPresetInput): ApprovalPresetResult {
+  const decisions = [...(input.decisions ?? [])]
+  const boundRoutes = new Set(decisions.map((decision) => decision.transitionId).filter(Boolean))
+
+  const addDecision = (label: string, transitionId: string, style: TaskDecisionDraft['style']) => {
+    if (transitionId && boundRoutes.has(transitionId)) return
+    const draft = newDecisionDraft(transitionId)
+    decisions.push({ ...draft, label, style })
+    if (transitionId) boundRoutes.add(transitionId)
+  }
+
+  addDecision(input.approveLabel, input.approveTransitionId ?? '', 'primary')
+  addDecision(input.rejectLabel, input.rejectTransitionId ?? '', 'destructive')
+
+  const formFields = [...(input.formFields ?? [])]
+  if (!formFields.some((field) => field.name === APPROVAL_PRESET_COMMENT_FIELD)) {
+    formFields.push({
+      name: APPROVAL_PRESET_COMMENT_FIELD,
+      type: 'textarea',
+      label: input.commentLabel,
+      required: false,
+    })
+  }
+
+  const entityBindings = [...(input.entityBindings ?? [])]
+  const promptsForEntityBinding = entityBindings.length === 0
+  if (promptsForEntityBinding) entityBindings.push(newEntityBindingDraft())
+
+  return { decisions, formFields, entityBindings, promptsForEntityBinding }
+}

package/src/modules/workflows/lib/task-quick-action.ts

@@ -0,0 +1,111 @@
+/**
+ * Workflows Module - Notification quick-action rule (pure)
+ *
+ * Spec §6.2: *"Notification quick-actions complete a decision inline **only
+ * when** the task has exactly one-click semantics: no editable-prefilled fields
+ * and no required comment — otherwise the quick action deep-links to the full
+ * task."*
+ *
+ * What "one click" means here, and why each clause is load-bearing:
+ *
+ *  - **Exactly one decision, or none.** A notification action carries an
+ *    `actionId`; the notifications module builds the command input from the
+ *    notification's `sourceEntityId` alone (`notificationService.executeAction`),
+ *    so WHICH of several buttons was pressed cannot reach the command. Two
+ *    decisions therefore cannot be distinguished from a notification, and the
+ *    honest answer is the deep link. (The platform's other command-backed
+ *    notification — `staff.leave_request.pending` — sidesteps this by giving
+ *    each button its OWN command id; workflow decisions are per-task data, so
+ *    that is not available here.)
+ *  - **No form fields.** Anything the assignee may type is input the quick
+ *    action cannot collect, and completing with an empty payload would either
+ *    fail `validateFormData` or silently discard what the author asked for.
+ *  - **No editable-prefilled fields**, verbatim from the spec — a reviewer who
+ *    is meant to correct data inline is not a one-click reviewer.
+ *  - **No required comment.** There is no authoring surface for this today (the
+ *    task detail's comment box is always optional), so the input defaults to
+ *    false; it is modelled explicitly so the rule does not have to be rewritten
+ *    when one appears.
+ *
+ * PURE: no ORM, DI, React or registry imports.
+ */
+
+import type { NotificationTypeAction } from '@open-mercato/shared/modules/notifications/types'
+import { countTaskFormFields } from './task-form-schema'
+
+export const TASK_COMPLETE_COMMAND_ID = 'workflows.tasks.complete'
+
+/** Action id of the one-click completion button. */
+export const TASK_QUICK_ACTION_COMPLETE_ID = 'complete'
+
+/** Action id of the deep link to the full task. */
+export const TASK_QUICK_ACTION_VIEW_ID = 'view'
+
+export const TASK_DEEP_LINK_HREF = '/backend/tasks/{sourceEntityId}'
+
+export interface TaskQuickActionInput {
+  /** Decision buttons resolved for this task. */
+  decisions?: { id: string }[] | null
+  /** The authored form schema, in either accepted shape. */
+  formSchema?: unknown
+  /** Form fields the assignee may correct before deciding. */
+  editablePrefilled?: string[] | null
+  /** Reserved: no authoring surface exists yet, so callers leave it unset. */
+  requiresComment?: boolean
+}
+
+/**
+ * Whether this task can be finished from a notification with one click.
+ *
+ * Fail-closed by construction: every clause has to hold, and an unrecognised
+ * form schema shape counts as "has fields" only when it actually declares any,
+ * so a malformed schema degrades to the deep link rather than to a completion
+ * that drops data.
+ */
+export function isOneClickTask(input: TaskQuickActionInput): boolean {
+  if (input.requiresComment) return false
+  if (input.editablePrefilled?.length) return false
+  if (countTaskFormFields(input.formSchema) > 0) return false
+
+  const decisions = input.decisions ?? []
+  return decisions.length <= 1
+}
+
+/**
+ * The actions a task notification offers.
+ *
+ * A one-click task gets the command-backed completion button; anything else
+ * gets the deep link, which is what the spec's "otherwise" clause asks for. The
+ * deep link is present in BOTH cases — a quick action is a shortcut, never the
+ * only way to reach the task.
+ */
+export function buildTaskQuickActions(input: TaskQuickActionInput): NotificationTypeAction[] {
+  const viewAction: NotificationTypeAction = {
+    id: TASK_QUICK_ACTION_VIEW_ID,
+    labelKey: 'common.view',
+    variant: 'outline',
+    href: TASK_DEEP_LINK_HREF,
+    icon: 'external-link',
+  }
+
+  if (!isOneClickTask(input)) return [viewAction]
+
+  return [
+    viewAction,
+    {
+      id: TASK_QUICK_ACTION_COMPLETE_ID,
+      labelKey: 'workflows.notifications.task.actions.complete',
+      variant: 'default',
+      icon: 'check',
+      commandId: TASK_COMPLETE_COMMAND_ID,
+    },
+  ]
+}
+
+/**
+ * The primary action id for a task notification: the completion button when
+ * there is one, otherwise the deep link.
+ */
+export function resolveTaskPrimaryActionId(input: TaskQuickActionInput): string {
+  return isOneClickTask(input) ? TASK_QUICK_ACTION_COMPLETE_ID : TASK_QUICK_ACTION_VIEW_ID
+}

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

@@ -0,0 +1,270 @@
+import type {
+  TaskDecision,
+  TaskEntityBinding,
+  TaskLocalizedString,
+  UserTaskAssigneeKind,
+  UserTaskConfig,
+} from '../data/validators'
+
+/**
+ * Resolving what a task author wrote into what a task actually says.
+ *
+ * PURE by construction (no ORM, DI, React or registry imports): the caller
+ * supplies an `interpolate` function, which in the engine is the Phase-2b
+ * `interpolateVariables` bound to the instance context. That keeps every rule
+ * here unit-testable without a workflow, and lets the task surfaces re-resolve
+ * copy with the same code the engine used at creation time.
+ *
+ * Interpolation is deliberately LENIENT here, never strict. A dynamic assignee
+ * that resolves to nothing is not an error — it is exactly the case the spec's
+ * mandatory fallback role exists for, and failing the step instead would strand
+ * the run over a piece of copy.
+ */
+
+export type TaskInterpolate = (value: unknown) => unknown
+
+export interface ResolvedTaskEntityBinding {
+  entityType: string
+  entityId: string
+  label?: TaskLocalizedString
+}
+
+export interface ResolvedTaskAssignment {
+  assignedTo: string | null
+  assignedToRoles: string[] | null
+  /** True when a dynamic assignee was authored and resolved to nothing. */
+  fellBackToRoles: boolean
+  /**
+   * Which principal namespace `assignedTo` names — the `user_tasks.assignee_kind`
+   * discriminator, decided here so every creation site gets the same answer.
+   *
+   * `'customer'` requires BOTH that the author asked for it AND that an
+   * individual assignee actually resolved. A customer-addressed task with no
+   * assignee is unaddressable: portal principals cannot claim from a queue, and
+   * the portal branch of the visibility predicate has no arm that would ever
+   * admit it.
+   */
+  assigneeKind: UserTaskAssigneeKind
+  /**
+   * True when the author asked for a portal assignee and the dynamic id resolved
+   * to nothing, so the task fell back to the authored backoffice role queue.
+   * Worth a log line: the work is still reachable, but by a different audience
+   * than the author intended.
+   */
+  fellBackFromCustomer: boolean
+}
+
+export interface ResolvedTaskDecision {
+  id: string
+  label: TaskLocalizedString
+  transitionId: string
+  style?: TaskDecision['style']
+}
+
+const TOKEN_PATTERN = /\{\{[^}]+\}\}/
+
+function isUnresolved(value: unknown): boolean {
+  return typeof value === 'string' && TOKEN_PATTERN.test(value)
+}
+
+function toResolvedString(value: unknown): string | null {
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    if (!trimmed.length || isUnresolved(trimmed)) return null
+    return trimmed
+  }
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value)
+  return null
+}
+
+/**
+ * Resolve author copy that may be a plain string or a per-locale map. Every
+ * leaf goes through the interpolator, so a pill works in either shape.
+ */
+export function resolveTaskText(
+  value: TaskLocalizedString | undefined | null,
+  interpolate: TaskInterpolate
+): TaskLocalizedString | null {
+  if (value == null) return null
+  if (typeof value === 'string') {
+    const resolved = interpolate(value)
+    return typeof resolved === 'string' ? resolved : String(resolved ?? '')
+  }
+  const resolved: Record<string, string> = {}
+  for (const [locale, text] of Object.entries(value)) {
+    const localeValue = interpolate(text)
+    resolved[locale] = typeof localeValue === 'string' ? localeValue : String(localeValue ?? '')
+  }
+  return resolved
+}
+
+/**
+ * Flatten localized copy onto the single text column a `UserTask` has. Prefers
+ * the requested locale, then the first declared one — a task must never render
+ * blank because its author wrote only one locale.
+ */
+export function flattenTaskText(
+  value: TaskLocalizedString | null | undefined,
+  locale?: string
+): string | null {
+  if (value == null) return null
+  if (typeof value === 'string') return value.length ? value : null
+  if (locale && typeof value[locale] === 'string' && value[locale].length) return value[locale]
+  for (const text of Object.values(value)) {
+    if (typeof text === 'string' && text.length) return text
+  }
+  return null
+}
+
+/**
+ * Resolve the assignment the author configured.
+ *
+ * A `Dynamic` assignment is a pill in `assignedTo` (`{{context.deal.ownerId}}`).
+ * When it resolves to nothing — the path is missing, the value is empty, or the
+ * token survived interpolation unchanged — the task falls to the authored role
+ * queue rather than being created with nobody able to see it. That queue IS the
+ * spec's mandatory fallback role; the inspector is what makes it mandatory.
+ *
+ * The legacy array form of `assignedTo` keeps meaning "these are roles".
+ *
+ * ## `assigneeKind`
+ *
+ * `userTaskConfig.assigneeKind: 'customer'` is what addresses a task to a PORTAL
+ * principal — the id in `assignedTo` is then a `CustomerUser.id`, not a
+ * backoffice user id, and only the portal routes can see or complete it. It is
+ * honoured only when an individual assignee actually resolves, and it forces
+ * `assignedToRoles` to null: portal roles are a different namespace
+ * (`CustomerRole`), a backoffice role queue on a customer-addressed row would
+ * offer the work to an audience that can never reach it, and design §7.1 makes
+ * that combination an invariant rather than a preference.
+ *
+ * Absent (every definition authored before this existed), the answer is `'user'`
+ * — which is exactly what those rows have always meant.
+ */
+export function resolveTaskAssignment(
+  config: Pick<UserTaskConfig, 'assignedTo' | 'assignedToRoles' | 'assigneeKind'>,
+  interpolate: TaskInterpolate
+): ResolvedTaskAssignment {
+  const authoredRoles = config.assignedToRoles?.length ? config.assignedToRoles : null
+  const wantsCustomer = config.assigneeKind === 'customer'
+
+  if (Array.isArray(config.assignedTo)) {
+    return {
+      assignedTo: null,
+      assignedToRoles: config.assignedTo.length ? config.assignedTo : authoredRoles,
+      fellBackToRoles: false,
+      assigneeKind: 'user',
+      fellBackFromCustomer: wantsCustomer,
+    }
+  }
+
+  if (typeof config.assignedTo !== 'string' || !config.assignedTo.length) {
+    return {
+      assignedTo: null,
+      assignedToRoles: authoredRoles,
+      fellBackToRoles: false,
+      assigneeKind: 'user',
+      fellBackFromCustomer: wantsCustomer,
+    }
+  }
+
+  const resolved = toResolvedString(interpolate(config.assignedTo))
+  if (resolved) {
+    return {
+      assignedTo: resolved,
+      assignedToRoles: wantsCustomer ? null : authoredRoles,
+      fellBackToRoles: false,
+      assigneeKind: wantsCustomer ? 'customer' : 'user',
+      fellBackFromCustomer: false,
+    }
+  }
+
+  return {
+    assignedTo: null,
+    assignedToRoles: authoredRoles,
+    fellBackToRoles: true,
+    assigneeKind: 'user',
+    fellBackFromCustomer: wantsCustomer,
+  }
+}
+
+/**
+ * Resolve each binding's `idPath` against the run context.
+ *
+ * A binding whose id does not resolve is DROPPED, not carried as a dangling
+ * reference: the ledger marks plenty of paths `maybe`-presence, so an absent
+ * record is an ordinary outcome and a task about "order #undefined" is worse
+ * than a task about nothing. `unresolved` names what was dropped so the caller
+ * can log it.
+ */
+export function resolveTaskEntityBindings(
+  bindings: TaskEntityBinding[] | undefined | null,
+  interpolate: TaskInterpolate
+): { bindings: ResolvedTaskEntityBinding[]; unresolved: string[] } {
+  if (!bindings?.length) return { bindings: [], unresolved: [] }
+
+  const resolvedBindings: ResolvedTaskEntityBinding[] = []
+  const unresolved: string[] = []
+
+  for (const binding of bindings) {
+    const expression = TOKEN_PATTERN.test(binding.idPath) ? binding.idPath : `{{${binding.idPath}}}`
+    const entityId = toResolvedString(interpolate(expression))
+    if (!entityId) {
+      unresolved.push(binding.idPath)
+      continue
+    }
+    const label = resolveTaskText(binding.label, interpolate)
+    resolvedBindings.push({
+      entityType: binding.entityType,
+      entityId,
+      ...(label != null ? { label } : {}),
+    })
+  }
+
+  return { bindings: resolvedBindings, unresolved }
+}
+
+/**
+ * The distinct AUTHORED entity types across a task's resolved bindings, for the
+ * denormalized `user_tasks.entity_types` column the §6.4 entity gate filters on.
+ *
+ * Verbatim, deduped, order-preserving. Verbatim because the visibility
+ * predicate's per-request access map is keyed on exactly the string the binding
+ * carries — normalizing here would give the SQL filter and the JS predicate two
+ * different notions of "the same type".
+ *
+ * Empty in, empty out: the caller stores NULL for a task about nothing, which is
+ * what the vacuous-pass rule reads. Same expression the work-inbox projection
+ * already computes per row, so a row's stored column and its projected
+ * `entityTypes` cannot disagree.
+ */
+export function collectResolvedEntityTypes(
+  bindings: readonly ResolvedTaskEntityBinding[],
+): string[] {
+  return [...new Set(bindings.map((binding) => binding.entityType))]
+}
+
+/** Resolve decision-button copy; the route binding itself is already durable. */
+export function resolveTaskDecisions(
+  decisions: TaskDecision[] | undefined | null,
+  interpolate: TaskInterpolate
+): ResolvedTaskDecision[] {
+  if (!decisions?.length) return []
+  return decisions.map((decision) => ({
+    id: decision.id,
+    label: resolveTaskText(decision.label, interpolate) ?? decision.id,
+    transitionId: decision.transitionId,
+    ...(decision.style ? { style: decision.style } : {}),
+  }))
+}
+
+/**
+ * The authored deadline duration. `deadline` is the business-word superset;
+ * `slaDuration` is the original bare-duration form and keeps working forever.
+ */
+export function resolveTaskDeadlineDuration(
+  config: Pick<UserTaskConfig, 'deadline' | 'slaDuration'>
+): string | null {
+  const duration = config.deadline?.duration ?? config.slaDuration
+  return typeof duration === 'string' && duration.length ? duration : null
+}