@owlmeans/server-planning 0.1.18-rc.0

package/src/executor/validate.ts

@@ -0,0 +1,253 @@
+import {
+  applyUnset, assertMutable, BODY_MAX, CODE_MAX, DESCRIPTION_MAX, IllegalTransition,
+  LabelNotAllowed, MAX_LABELS, MAX_PARENTS, mergeFields, normalizeParents, ParentNotFound, PlanningError,
+  RelationshipRefused, ruleOf, SpecificationRevisionConflict, SpecificationSlotUnknown, slotOf, TITLE_MAX,
+  TransitionAction, validateFields, validateSpecificationBody, WorkcardKind,
+} from '@owlmeans/planning'
+import type {
+  PlanningFacade, RelationshipDraft, Specification, TransitionExecution, WorkcardDraft,
+} from '@owlmeans/planning'
+import type { PlanningRuntime } from '../service.js'
+import { assertChildAllowed } from './resolve.js'
+import type { Resolved } from './resolve.js'
+
+const ACTIONS = new Set<string>(Object.values(TransitionAction))
+
+const malformed = (what: string): PlanningError => new PlanningError(`malformed:${what}`)
+
+const assertText = (name: string, value: unknown, max: number, required: boolean): void => {
+  if (value === undefined || value === null) {
+    if (required) {
+      throw malformed(name)
+    }
+    return
+  }
+  if (typeof value !== 'string' || (required && value === '') || value.length > max) {
+    throw malformed(name)
+  }
+}
+
+const assertShape = (exec: TransitionExecution, resolved: Resolved): void => {
+  if (!ACTIONS.has(exec.action)) {
+    throw malformed(`action:${exec.action}`)
+  }
+  if (exec.links != null && exec.action !== TransitionAction.Create) {
+    throw malformed('links-outside-create')
+  }
+  if (exec.action === TransitionAction.Transit && (exec.transition == null || exec.transition === '')) {
+    throw malformed('transit-without-transition')
+  }
+  if ((exec.action === TransitionAction.Link || exec.action === TransitionAction.Unlink)
+    && (exec.link?.to == null || exec.link.to === '' || exec.link.type == null || exec.link.type === '')) {
+    throw malformed(`${exec.action}-without-link`)
+  }
+  if (resolved.create) {
+    const draft = exec.card as WorkcardDraft
+    assertText('title', draft.title, TITLE_MAX, true)
+    assertText('description', draft.description, DESCRIPTION_MAX, false)
+    assertText('code', draft.code, CODE_MAX, false)
+    if ((draft.parents?.length ?? 0) > MAX_PARENTS) {
+      throw malformed('parents')
+    }
+  }
+  const changes = exec.changes ?? {}
+  if (changes.title !== undefined) {
+    assertText('title', changes.title, TITLE_MAX, true)
+  }
+  assertText('description', changes.description ?? undefined, DESCRIPTION_MAX, false)
+  assertText('code', changes.code ?? undefined, CODE_MAX, false)
+}
+
+const assertFlow = (exec: TransitionExecution, resolved: Resolved, runtime: PlanningRuntime): void => {
+  if (resolved.create) {
+    const status = (exec.card as WorkcardDraft).status
+    const primary = runtime.service().schemas.primaryFlow(resolved.type.type)
+    if (status != null && !primary.statuses.some(definition => definition.key === status)) {
+      throw new IllegalTransition(`${primary.id}:create:${status}`)
+    }
+    return
+  }
+  if (exec.action !== TransitionAction.Transit) {
+    return
+  }
+  const card = resolved.card!
+  const from = card.flows[resolved.flowId] ?? card.status
+  if (ruleOf(resolved.flow, exec.transition!, from) == null) {
+    throw new IllegalTransition(`${resolved.flowId}:${exec.transition}:${from}`)
+  }
+}
+
+const assertFields = (exec: TransitionExecution, resolved: Resolved, runtime: PlanningRuntime): void => {
+  const schemas = runtime.service().schemas
+  if (resolved.create) {
+    const draft = exec.card as WorkcardDraft
+    validateFields(schemas, resolved.type.type, mergeFields(draft.fields, exec.changes?.fields))
+    return
+  }
+  const clears = (exec.unset ?? []).filter(path => path.startsWith('fields.'))
+  if (exec.changes?.fields == null && clears.length === 0) {
+    return
+  }
+  const merged = applyUnset({ fields: mergeFields(resolved.card!.fields, exec.changes?.fields) }, clears)
+  validateFields(schemas, resolved.type.type, merged.fields)
+}
+
+const assertLabels = (exec: TransitionExecution, resolved: Resolved): void => {
+  const labels = [
+    ...(resolved.create ? (exec.card as WorkcardDraft).labels ?? [] : []),
+    ...(exec.changes?.labels ?? []),
+  ]
+  if (labels.length === 0) {
+    return
+  }
+  if (new Set(labels).size > MAX_LABELS) {
+    throw new LabelNotAllowed(`too-many:${labels.length}`)
+  }
+  const allowed = resolved.type.labels
+  const refused = allowed == null ? undefined : labels.find(label => !allowed.includes(label))
+  if (refused != null) {
+    throw new LabelNotAllowed(refused)
+  }
+}
+
+const assertParentMove = async (
+  exec: TransitionExecution, resolved: Resolved, runtime: PlanningRuntime, facade: PlanningFacade
+): Promise<void> => {
+  if (resolved.create) {
+    return
+  }
+  const changes = exec.changes ?? {}
+  const moved = [...new Set(normalizeParents(changes.parent, changes.parents))]
+    .filter(id => id !== resolved.card!.parent && !resolved.card!.parents.includes(id))
+  for (const id of moved) {
+    if (id === resolved.card!.id) {
+      throw malformed('parent-self')
+    }
+    const found = await facade.cards.load(id)
+    if (found == null) {
+      throw new ParentNotFound(id)
+    }
+    assertChildAllowed(runtime, found, resolved.card!.kind, resolved.card!.type)
+  }
+}
+
+const assertSpecification = async (
+  exec: TransitionExecution, resolved: Resolved, runtime: PlanningRuntime, facade: PlanningFacade
+): Promise<void> => {
+  const kind = resolved.create ? (exec.card as WorkcardDraft).kind : resolved.card!.kind
+  if (kind !== WorkcardKind.Specification) {
+    return
+  }
+  const schemas = runtime.service().schemas
+
+  if (resolved.create) {
+    const draft = exec.card as WorkcardDraft
+    const parent = resolved.parent!
+    if (draft.category == null || draft.category === '') {
+      throw malformed('specification-without-category')
+    }
+    const slot = slotOf(schemas.type(parent.type), draft.category)
+    if (slot == null) {
+      throw new SpecificationSlotUnknown(`${parent.type}:${draft.category}`)
+    }
+    if (draft.format != null && draft.format !== slot.format) {
+      throw malformed(`format:${draft.category}:${draft.format}`)
+    }
+    assertText('body', draft.body, BODY_MAX, false)
+    validateSpecificationBody(slot, draft.body)
+    if (slot.multiple !== true && await facade.specifications.current(parent.id!, draft.category) != null) {
+      throw new SpecificationRevisionConflict(`${parent.id}:${draft.category}`)
+    }
+    return
+  }
+
+  const spec = resolved.card as Specification
+  const changes = exec.changes ?? {}
+  if (changes.category !== undefined && changes.category !== spec.category) {
+    throw new PlanningError('immutable:category')
+  }
+  const slot = resolved.slot
+  if (slot == null) {
+    return
+  }
+  if (changes.format != null && changes.format !== slot.format) {
+    throw malformed(`format:${spec.category}:${changes.format}`)
+  }
+  if (changes.body != null) {
+    assertText('body', changes.body, BODY_MAX, false)
+    validateSpecificationBody(slot, changes.body)
+  }
+}
+
+const assertRelationships = async (
+  exec: TransitionExecution, resolved: Resolved, facade: PlanningFacade
+): Promise<void> => {
+  const drafts: RelationshipDraft[] = exec.action === TransitionAction.Create
+    ? exec.links ?? []
+    : exec.action === TransitionAction.Link || exec.action === TransitionAction.Unlink ? [exec.link!] : []
+  if (drafts.length === 0) {
+    return
+  }
+  const cardId = resolved.card?.id
+  const declared = resolved.type.relationships ?? []
+  const counted = new Map<string, number>()
+
+  for (const draft of drafts) {
+    const rule = declared.find(entry => entry.name === draft.type)
+    if (rule == null) {
+      throw new RelationshipRefused(`unknown:${draft.type}`)
+    }
+    if (draft.from != null && draft.from !== cardId) {
+      throw new RelationshipRefused(`from:${draft.from}`)
+    }
+    if (exec.action === TransitionAction.Unlink) {
+      const existing = await facade.relationships.list({ from: cardId, to: draft.to, type: draft.type })
+      if (existing.total === 0) {
+        throw new RelationshipRefused(`absent:${draft.type}:${draft.to}`)
+      }
+      continue
+    }
+    const target = await facade.cards.load(draft.to)
+    if (target == null) {
+      throw new RelationshipRefused(`to:${draft.to}`)
+    }
+    if (rule.from != null && !rule.from.includes(resolved.type.type)) {
+      throw new RelationshipRefused(`from-type:${draft.type}:${resolved.type.type}`)
+    }
+    if (rule.to != null && !rule.to.includes(target.type)) {
+      throw new RelationshipRefused(`to-type:${draft.type}:${target.type}`)
+    }
+    if (rule.single === true) {
+      const count = (counted.get(draft.type) ?? 0) + 1
+      counted.set(draft.type, count)
+      const existing = cardId == null
+        ? 0
+        : (await facade.relationships.list({ from: cardId, type: draft.type })).items
+          .filter(link => link.to !== draft.to).length
+      if (count + existing > 1) {
+        throw new RelationshipRefused(`single:${draft.type}`)
+      }
+    }
+  }
+}
+
+/**
+ * Step 6: shape, flow rule, immutables, `fields`, labels, parent moves, the specification slot and
+ * relationships — in that order. Nothing is written by a refusal here.
+ *
+ * @throws {PlanningError} `malformed:*` / `immutable:*`
+ * @throws {IllegalTransition | FieldsInvalid | LabelNotAllowed | ParentNotFound | CardTypeNotAllowed}
+ * @throws {SpecificationSlotUnknown | SpecificationRevisionConflict | RelationshipRefused}
+ */
+export const validateExecution = async (
+  runtime: PlanningRuntime, facade: PlanningFacade, exec: TransitionExecution, resolved: Resolved
+): Promise<void> => {
+  assertShape(exec, resolved)
+  assertFlow(exec, resolved, runtime)
+  assertMutable(exec, resolved.type)
+  assertFields(exec, resolved, runtime)
+  assertLabels(exec, resolved)
+  await assertParentMove(exec, resolved, runtime, facade)
+  await assertSpecification(exec, resolved, runtime, facade)
+  await assertRelationships(exec, resolved, facade)
+}

package/src/executor.ts

@@ -0,0 +1,149 @@
+import { uuid } from '@owlmeans/basic-ids'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { PlanningError, PlanningUnsupported, WorkcardConflict } from '@owlmeans/planning'
+import type {
+  ExecuteOptions, PlanningExecContext, PlanningFacade, PlanningPlugin, PlanningStore, Transition,
+  TransitionExecution, TransitionReceipt,
+} from '@owlmeans/planning'
+import { changeSetOf, transitionOf } from './executor/changes.js'
+import { assignCode } from './executor/code.js'
+import { makeReceipt } from './executor/receipt.js'
+import { normalizeExecution, projectFor, resolveExecution } from './executor/resolve.js'
+import type { Resolved } from './executor/resolve.js'
+import { validateExecution } from './executor/validate.js'
+import type { PlanningRuntime } from './service.js'
+
+const isoNow = (): string => new Date().toISOString()
+
+/** What a type/parent change by a middleware is judged by. */
+const identityOf = (exec: TransitionExecution): string => typeof exec.card === 'string'
+  ? `${exec.action}|${exec.card}|${exec.flow ?? ''}|${exec.changes?.parent ?? ''}`
+  : `${exec.action}|${exec.card.kind}|${exec.card.type}|${exec.card.parent ?? ''}|${(exec.card.parents ?? []).join(',')}|${exec.flow ?? ''}`
+
+const execContextOf = (
+  runtime: PlanningRuntime, facade: PlanningFacade, resolved: Resolved
+) => (plugin: PlanningPlugin): PlanningExecContext => ({
+  context: runtime.context() as BasicContext<BasicConfig>,
+  scope: facade.scope,
+  schemas: runtime.service().schemas,
+  store: resolved.store,
+  facade,
+  plugin,
+  type: resolved.type,
+  flow: resolved.flow,
+  ...(resolved.card != null ? { card: resolved.card } : {}),
+  ...(resolved.parent != null ? { parent: resolved.parent } : {}),
+})
+
+const findByKey = async (
+  runtime: PlanningRuntime, entityId: string, key: string
+): Promise<{ store: PlanningStore, transition: Transition } | null> => {
+  for (const store of runtime.stores()) {
+    const transition = await store.transitions?.byKey(entityId, key)
+    if (transition != null) {
+      return { store, transition }
+    }
+  }
+  return null
+}
+
+/** The receipt an update that changes nothing answers with: the card's latest transition. */
+const currentReceipt = async (
+  store: PlanningStore, resolved: Resolved, entityId: string, opts?: ExecuteOptions
+): Promise<TransitionReceipt> => {
+  const latest = await store.transitions!.list(
+    { entityId, card: resolved.card!.id! }, { sort: [{ field: 'seq', order: 'desc' }], size: 1 }
+  )
+  const transition = latest.items[0]
+  if (transition == null) {
+    throw new PlanningUnsupported(`empty-update-without-log:${resolved.card!.id}`)
+  }
+  return await makeReceipt(store, transition, opts)
+}
+
+/**
+ * THE write path. Nothing is appended before step 11, so every refusal leaves the log untouched.
+ *
+ * 1 normalize → 2 scope → 3 idempotency (a known `key` answers its first receipt, before any
+ * validation) → 4 resolve → 5 the plugins' `before` chain (re-resolved once when it moved the type
+ * or the parent) → 6 validate → 7 allocate the card id → 8 code → 9 changes (an update changing
+ * nothing answers the current receipt and appends nothing) → 10 seq, a CAS against the head →
+ * 11 append → 12 request the projection → 13 receipt → 14 `wait`.
+ *
+ * `after` hooks are NOT run here — the process that folds runs them, once per commit.
+ */
+export const executeTransition = async (
+  runtime: PlanningRuntime, facade: PlanningFacade, input: TransitionExecution, opts?: ExecuteOptions
+): Promise<TransitionReceipt> => {
+  const scope = facade.scope
+  const service = runtime.service()
+  const at = (runtime.options.now ?? isoNow)()
+
+  let exec = normalizeExecution(input)
+
+  if (scope.entityId == null || scope.entityId === '') {
+    throw new PlanningError('malformed:scope-without-entity')
+  }
+
+  if (exec.key != null && exec.key !== '') {
+    const found = await findByKey(runtime, scope.entityId, exec.key)
+    if (found != null) {
+      return await makeReceipt(found.store, found.transition, opts)
+    }
+  }
+
+  let resolved = await resolveExecution(runtime, facade, exec)
+
+  const before = identityOf(exec)
+  exec = normalizeExecution(await runtime.registry.before(exec, execContextOf(runtime, facade, resolved)))
+  if (identityOf(exec) !== before) {
+    resolved = await resolveExecution(runtime, facade, exec)
+  }
+
+  await validateExecution(runtime, facade, exec, resolved)
+
+  const store = resolved.store
+  const transitions = store.transitions
+  if (transitions == null) {
+    throw new PlanningUnsupported(`transitions:${store.alias ?? resolved.type.type}`)
+  }
+
+  const cardId = resolved.create
+    ? store.newId?.() ?? runtime.options.ids?.() ?? uuid()
+    : resolved.card!.id!
+
+  exec = await assignCode(exec, resolved, scope, runtime.registry, execContextOf(runtime, facade, resolved))
+
+  const { set, empty } = changeSetOf(exec, resolved, service.schemas, at)
+  if (empty) {
+    return await currentReceipt(store, resolved, scope.entityId, opts)
+  }
+
+  const seq = await transitions.nextSeq(cardId, resolved.create ? null : exec.expectSeq ?? null)
+  if (resolved.create && seq !== 1) {
+    throw new WorkcardConflict(`${cardId}:create:${seq}`)
+  }
+
+  const transition = transitionOf({
+    exec, resolved, scope, set, cardId, seq, at,
+    project: projectFor(resolved, exec, cardId),
+  })
+
+  let appended: Transition
+  try {
+    appended = await transitions.append(transition)
+  } catch (error) {
+    // A lost race on the idempotency key: the winner's receipt is the answer.
+    if (exec.key != null && exec.key !== '') {
+      const winner = await transitions.byKey(scope.entityId, exec.key)
+      if (winner != null) {
+        return await makeReceipt(store, winner, opts)
+      }
+    }
+    throw error
+  }
+
+  await store.cards.project(cardId, appended.id != null ? { transition: appended.id } : undefined)
+
+  return await makeReceipt(store, appended, opts)
+}

package/src/facade.ts

@@ -0,0 +1,162 @@
+import {
+  criteriaOf, currentSpecification, isSpecification, linkWhereOf, listOptionsOf, modelOf,
+  PlanningUnsupported, specCriteriaOf, transitionWhereOf, WorkcardKind, WorkcardNotFound,
+} from '@owlmeans/planning'
+import type {
+  CommitSource, PlanningFacade, PlanningScope, Specification, Workcard, WorkcardModel,
+} from '@owlmeans/planning'
+import { executeTransition } from './executor.js'
+import type { PlanningRuntime } from './service.js'
+import type { CommitHub } from './store/types.js'
+
+/**
+ * The scoped facade over the service's stores.
+ *
+ * Every read carries the scope's `entityId` into the store and re-checks it on what comes back, so
+ * a card of another entity is simply absent — `load` answers `null`, `get` throws
+ * `WorkcardNotFound`, exactly as for an id that never existed. Reads go through the composite
+ * store (the default store plus the stores plugins own); writes go through the executor.
+ */
+export const makeStoreFacade = (runtime: PlanningRuntime, scope: PlanningScope): PlanningFacade => {
+  const entityId = scope.entityId
+  const reader = () => runtime.reader()
+  const mine = <T extends { entityId: string }>(record: T | null | undefined): T | null =>
+    record != null && record.entityId === entityId ? record : null
+
+  const commitSource = (): CommitSource => {
+    const commits = reader().commits
+    if (commits == null) {
+      throw new PlanningUnsupported('commits')
+    }
+    return commits
+  }
+
+  /** The transition is this entity's — its row, or the remembered commit of a purged one. */
+  const assertTransition = async (transition: string): Promise<void> => {
+    const row = await reader().transitions?.get(transition)
+    if (row != null) {
+      if (row.entityId !== entityId) {
+        throw new WorkcardNotFound(`transition:${transition}`)
+      }
+      return
+    }
+    const recalled = (reader().commits as Partial<CommitHub> | undefined)?.recall?.(transition)
+    if (recalled == null || recalled.entityId !== entityId) {
+      throw new WorkcardNotFound(`transition:${transition}`)
+    }
+  }
+
+  const facade: PlanningFacade = {
+    scope: Object.freeze({ ...scope }),
+
+    schemas: runtime.service().schemas,
+
+    cards: {
+      load: async id => mine(await reader().cards.get(id, entityId)),
+
+      get: async id => {
+        const card = await facade.cards.load(id)
+        if (card == null) {
+          throw new WorkcardNotFound(id)
+        }
+        return card
+      },
+
+      list: async query => await reader().cards.list(criteriaOf(query, scope), listOptionsOf(query)),
+
+      count: async query => await reader().cards.count(criteriaOf(query, scope)),
+
+      summary: async (parents, query) => parents.length === 0
+        ? {}
+        : await reader().cards.summary(parents, criteriaOf({ kind: query?.kind, type: query?.type }, scope)),
+    },
+
+    specifications: {
+      current: async (parent, category) => {
+        const specs = reader().specs
+        if (specs != null) {
+          return mine(await specs.current(parent, category, entityId))
+        }
+        const listed = await reader().cards.list(specCriteriaOf(parent, { category }, scope) as never, { size: 0 })
+        return currentSpecification(listed.items, category)
+      },
+
+      list: async (parent, query) => {
+        const specs = reader().specs
+        if (specs != null) {
+          return await specs.list(parent, entityId, query)
+        }
+        return await reader().cards.list(specCriteriaOf(parent, query, scope) as never, listOptionsOf(query) as never) as never
+      },
+
+      get: async id => {
+        const card = await facade.cards.load(id)
+        if (card == null || !isSpecification(card)) {
+          throw new WorkcardNotFound(id)
+        }
+        return card as Specification
+      },
+
+      revisions: async (id, limit) => {
+        await facade.specifications.get(id)
+        const specs = reader().specs
+        if (specs == null) {
+          throw new PlanningUnsupported('revisions')
+        }
+        return await specs.revisions(id, entityId, limit)
+      },
+    },
+
+    relationships: {
+      list: async query => {
+        const links = reader().links
+        return links == null
+          ? { items: [], total: 0 }
+          : await links.list(linkWhereOf(query, scope), listOptionsOf(query))
+      },
+    },
+
+    transitions: {
+      get: async id => {
+        const transition = mine(await reader().transitions?.get(id))
+        if (transition == null) {
+          throw new WorkcardNotFound(`transition:${id}`)
+        }
+        return transition
+      },
+
+      list: async query => {
+        const transitions = reader().transitions
+        return transitions == null
+          ? { items: [], total: 0 }
+          : await transitions.list(transitionWhereOf(query, scope), listOptionsOf(query))
+      },
+    },
+
+    commits: {
+      status: async transition => {
+        await assertTransition(transition)
+        return await commitSource().status(transition)
+      },
+
+      subscribe: (listener, filter) => commitSource().subscribe(listener, { ...filter, entityId }),
+
+      wait: async (transition, opts) => {
+        await assertTransition(transition)
+        return await commitSource().wait(transition, opts)
+      },
+    },
+
+    execute: async (exec, opts) => await executeTransition(runtime, facade, exec, opts),
+
+    model: async <T extends Workcard = Workcard>(card: T | string): Promise<WorkcardModel<T>> => {
+      const record = typeof card === 'string' ? await facade.cards.get(card) as T : card
+      if (record.entityId !== entityId) {
+        throw new WorkcardNotFound(record.id ?? WorkcardKind.Card)
+      }
+      return modelOf<T>(record, facade)
+    },
+  }
+
+  return facade
+}

package/src/helper.ts

@@ -0,0 +1,44 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+import type { PlanningFacade, PlanningProtocols, PlanningScope } from '@owlmeans/planning'
+import { bind } from '@owlmeans/server-entrypoint'
+import {
+  executePlanning, getCard, getCommit, getSpecification, getTransition, listCardSpecifications,
+  listCardTransitions, listCards, listLinks, listSchemas, listSpecificationRevisions, summarizeCards,
+  watchCommits,
+} from './actions/index.js'
+import type { PlanningHandlerOptions } from './types.js'
+import { planningServiceOf, scopeOf } from './utils/index.js'
+
+/**
+ * Bind this package's handlers to a tree declared by `makePlanningProtocols` — one binding per
+ * protocol, the base included. Pass the tree itself, never a flattened list; an application that
+ * wants its own handler for one leaf binds that protocol afterwards.
+ */
+export const servePlanningEntrypoints = (protocols: PlanningProtocols, opts?: PlanningHandlerOptions) => [
+  bind(protocols.base),
+  bind(protocols.schema.list, listSchemas(protocols.schema.list, opts)),
+  bind(protocols.card.list, listCards(protocols.card.list, opts)),
+  bind(protocols.card.summary, summarizeCards(protocols.card.summary, opts)),
+  bind(protocols.card.get, getCard(protocols.card.get, opts)),
+  bind(protocols.card.transitions, listCardTransitions(protocols.card.transitions, opts)),
+  bind(protocols.card.specifications, listCardSpecifications(protocols.card.specifications, opts)),
+  bind(protocols.spec.get, getSpecification(protocols.spec.get, opts)),
+  bind(protocols.spec.revisions, listSpecificationRevisions(protocols.spec.revisions, opts)),
+  bind(protocols.link.list, listLinks(protocols.link.list, opts)),
+  bind(protocols.transition.get, getTransition(protocols.transition.get, opts)),
+  bind(protocols.execute, executePlanning(protocols.execute, opts)),
+  bind(protocols.commit.get, getCommit(protocols.commit.get, opts)),
+  bind(protocols.commit.events, watchCommits(protocols.commit.events, opts)),
+]
+
+/**
+ * The facade a hand-written handler works through: the request's entity and subject, plus `extra`
+ * (a `channel`) — never an entity from the request body.
+ *
+ * @throws {AuthorizationError} when the request carries no organization
+ */
+export const planningFor = (
+  ctx: BasicContext<BasicConfig>, req: AbstractRequest, extra?: Partial<PlanningScope>,
+  opts?: Pick<PlanningHandlerOptions, 'service'>
+): PlanningFacade => planningServiceOf(ctx, opts).for(scopeOf(req, extra))

package/src/index.ts

@@ -0,0 +1,13 @@
+export type * from './types.js'
+export type * from './store/types.js'
+
+export * from './consts.js'
+export * from './service.js'
+export * from './registry.js'
+export * from './facade.js'
+export * from './executor.js'
+export * from './helper.js'
+export * from './projection.js'
+export * from './actions/index.js'
+export * from './utils/index.js'
+export * from './store/index.js'

package/src/projection.ts

@@ -0,0 +1,65 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { PLANNING_SERVICE } from '@owlmeans/planning'
+import type { CommitEvent, PlanningService, PlanningStore } from '@owlmeans/planning'
+import { PLANNING_PROJECT_JOB, PLANNING_PROJECTION_QUEUE } from '@owlmeans/planning/queue'
+import type { ProjectionRequest } from '@owlmeans/planning/queue'
+import type { JobProcessor, QueueHooks } from '@owlmeans/queue'
+import { failPending, foldPending } from './store/fold.js'
+import type { PlanningHostService } from './types.js'
+import type { CommitHub, FoldResult } from './store/types.js'
+
+export interface ProjectionOptions {
+  /** The planning service alias. */
+  service?: string
+  /** The store the queue folds — the service's default store when omitted. */
+  store?: (service: PlanningService) => PlanningStore
+  /** Where events go — the store's commit hub `publish` when it has one. */
+  publish?: (event: CommitEvent) => Promise<void>
+}
+
+const serviceOf = (ctx: BasicContext<BasicConfig>, opts?: ProjectionOptions): PlanningService =>
+  ctx.service<PlanningHostService>(opts?.service ?? PLANNING_SERVICE)
+
+const storeOf = (service: PlanningService, opts?: ProjectionOptions): PlanningStore =>
+  opts?.store?.(service) ?? service.store()
+
+const publisherOf = (store: PlanningStore, opts?: ProjectionOptions) =>
+  opts?.publish ?? (store.commits as Partial<CommitHub> | undefined)?.publish
+
+/**
+ * The body of a projection job: fold one card with the service's `committed` as the commit
+ * listener, so the `after` chain runs in the process that took the job.
+ *
+ * Register it only where the process listens to `PLANNING_PROJECTION_QUEUE`; a durable store adds
+ * its own admission and release around it.
+ */
+export const makeProjectionProcessor = (
+  ctx: BasicContext<BasicConfig>, opts?: ProjectionOptions
+): JobProcessor<ProjectionRequest, FoldResult> => async job => {
+  const service = serviceOf(ctx, opts)
+  const store = storeOf(service, opts)
+  const publish = publisherOf(store, opts)
+
+  return await foldPending(store, job.data.cardId, job.data.entityId, {
+    touch: job.touch,
+    onCommitted: async event => { await service.committed(event) },
+    ...(publish != null ? { publish } : {}),
+  })
+}
+
+/**
+ * `onJobDead` for the projection queue: every pending transition of the card is marked failed and a
+ * failed event is published — otherwise `execute({ wait: true })` and `commits.wait` hang to their
+ * timeout. Merge it into the queue driver's hooks.
+ */
+export const planningQueueHooks = (ctx: BasicContext<BasicConfig>, opts?: ProjectionOptions): QueueHooks => ({
+  onJobDead: async (job, reason) => {
+    if (job.queue !== PLANNING_PROJECTION_QUEUE || job.name !== PLANNING_PROJECT_JOB) {
+      return
+    }
+    const request = job.data as ProjectionRequest
+    const store = storeOf(serviceOf(ctx, opts), opts)
+    const publish = publisherOf(store, opts)
+    await failPending(store, request.cardId, request.entityId, reason, publish != null ? { publish } : {})
+  },
+})