@owlmeans/server-planning 0.1.18-rc.21 → 0.1.18-rc.22

package/src/definitions.ts

@@ -1,6 +1,6 @@
-import { assertFlowSchema, assertOverridable, assertTypeSchema, flowInUse, isProject, PlanningSchemaKind, PlanningUnsupported, resolveScopedBundle, SchemaConflict, SchemaInUse, scopedRegistryOf, UnknownStatusFlow, UnknownWorkcardType, WorkcardNotFound, type PlanningDefinitions, type PlanningFacade, type PlanningSchemaRegistry, type SchemaDeclarations, type SchemaStore, type SchemaWriteOptions, type ScopedSchemaRecord, type ScopedSchemaRegistry, type StatusFlowSchema, type TransitionExecution, type Unsubscribe, type WorkcardTypeSchema } from '@owlmeans/planning'
+import { cardHelper, PlanningSchemaKind, PlanningUnsupported, SchemaConflict, SchemaInUse, scopedSchemaHelper, UnknownStatusFlow, UnknownWorkcardType, WorkcardNotFound, type PlanningDefinitions, type PlanningFacade, type PlanningSchemaRegistry, type SchemaDeclarations, type SchemaStore, type SchemaWriteOptions, type ScopedSchemaRecord, type ScopedSchemaRegistry, type StatusFlowSchema, type TransitionExecution, type Unsubscribe, type WorkcardTypeSchema } from '@owlmeans/planning'
 import { DEFAULT_SCHEMA_VIEWS } from './consts.js'
-import { actorOf } from './executor/changes.js'
+import { changesUtils } from './executor/changes.js'
 import type { PlanningRuntime, SchemaViews, SchemaViewsOptions } from './types.js'
 import type { Planned } from './types.local.js'
 
@@ -52,7 +52,7 @@ export const makeSchemaViews = (opts: SchemaViewsOptions): SchemaViews => {
       ...await store.list({ entityId, project: null }),
       ...(project != null ? await store.list({ entityId, project }) : []),
     ]
-    const view = scopedRegistryOf(resolveScopedBundle(opts.code().bundle(), records, { entityId, project, revision }))
+    const view = scopedSchemaHelper.scopedRegistryOf(scopedSchemaHelper.resolveScopedBundle(opts.code().bundle(), records, { entityId, project, revision }))
     cache.delete(key)
     cache.set(key, { revision, version, view })
     while (cache.size > limit) {
@@ -106,7 +106,7 @@ export const makeDefinitions = (runtime: PlanningRuntime, facade: PlanningFacade
       return
     }
     const card = await facade.cards.load(project)
-    if (card == null || !isProject(card)) {
+    if (card == null || !cardHelper.isProject(card)) {
       throw new WorkcardNotFound(project)
     }
   }
@@ -124,11 +124,11 @@ export const makeDefinitions = (runtime: PlanningRuntime, facade: PlanningFacade
     const flows: Pick<PlanningSchemaRegistry, 'flow'> = { flow: id => pending.get(id) ?? layer.flow(id) }
 
     for (const entry of plan) {
-      assertOverridable(code, entry.kind, entry.key)
+      scopedSchemaHelper.assertOverridable(code, entry.kind, entry.key)
       if (entry.kind === PlanningSchemaKind.Flow) {
-        assertFlowSchema(entry.definition as StatusFlowSchema)
+        scopedSchemaHelper.assertFlowSchema(entry.definition as StatusFlowSchema)
       } else {
-        assertTypeSchema(entry.definition as WorkcardTypeSchema, flows)
+        scopedSchemaHelper.assertTypeSchema(entry.definition as WorkcardTypeSchema, flows)
       }
     }
   }
@@ -137,7 +137,7 @@ export const makeDefinitions = (runtime: PlanningRuntime, facade: PlanningFacade
     entry: Planned, version: number, project: string | undefined, current?: ScopedSchemaRecord, retired?: boolean
   ): ScopedSchemaRecord => {
     const at = now()
-    const by = actorOf(scope, {} as TransitionExecution)
+    const by = changesUtils.actorOf(scope, {} as TransitionExecution)
     return Object.fromEntries(Object.entries({
       entityId,
       project,
@@ -235,7 +235,7 @@ export const makeDefinitions = (runtime: PlanningRuntime, facade: PlanningFacade
           ? [opts.project]
           : [undefined, ...new Set(all.map(record => record.project).filter((id): id is string => id != null))]
         for (const project of projects) {
-          const user = flowInUse(resolveScopedBundle(code, all, { entityId, project }), key)
+          const user = scopedSchemaHelper.flowInUse(scopedSchemaHelper.resolveScopedBundle(code, all, { entityId, project }), key)
           if (user != null) {
             throw new SchemaInUse(`flow:${key}:type:${user}${project != null ? `:project:${project}` : ''}`)
           }

package/src/executor/changes/types.ts

@@ -0,0 +1,38 @@
+import type {
+  ChangeSet, PlanningSchemaRegistry, PlanningScope, Transition, TransitionActor, TransitionExecution,
+} from '@owlmeans/planning'
+import type { Resolved } from '../types.js'
+
+/** What step 11 builds the appended transition from. */
+export interface AppendParams {
+  exec: TransitionExecution
+  resolved: Resolved
+  scope: PlanningScope
+  set: ChangeSet
+  cardId: string
+  seq: number
+  project?: string
+  at: string
+}
+
+/** The record an execution appends: its changes, its actor and the transition itself. */
+export interface ChangesUtils {
+  /**
+   * Step 9: the recorded `changes`/`unset`, and whether an update wrote nothing.
+   *
+   * @throws {IllegalTransition | PlanningError}
+   */
+  changeSetOf: (
+    exec: TransitionExecution, resolved: Resolved, schemas: PlanningSchemaRegistry, at: string
+  ) => { set: ChangeSet, empty: boolean }
+  /**
+   * Who wrote it — the SCOPE's identity, never the execution's.
+   *
+   * `profileId`, `userId`, `service` and `channel` come only from the scope (the server builds it
+   * from the authenticated request); the descriptive `agent`/`runId` an in-process caller passes on
+   * the execution are kept unless the scope's own actor names them.
+   */
+  actorOf: (scope: PlanningScope, exec: TransitionExecution) => TransitionActor
+  /** Step 11's record: the event as it is appended, `pending`. */
+  transitionOf: (params: AppendParams) => Transition
+}

package/src/executor/changes.ts

@@ -1,74 +1,59 @@
-import { CommitState, computeChanges, isEmptyChange, TransitionAction, type ChangeSet, type PlanningSchemaRegistry, type PlanningScope, type RelationshipDraft, type Transition, type TransitionActor, type TransitionExecution, type WorkcardDraft } from '@owlmeans/planning'
+import { changesHelper, CommitState, TransitionAction, type ChangeSet, type PlanningSchemaRegistry, type PlanningScope, type RelationshipDraft, type Transition, type TransitionActor, type TransitionExecution, type WorkcardDraft } from '@owlmeans/planning'
+import type { ChangesUtils, AppendParams } from './changes/types.js'
 import type { Resolved } from './types.js'
 
 const clean = <T extends object>(record: T): T =>
   Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)) as T
 
-/**
- * Step 9: the recorded `changes`/`unset`, and whether an update wrote nothing.
- *
- * @throws {IllegalTransition | PlanningError}
- */
-export const changeSetOf = (
-  exec: TransitionExecution, resolved: Resolved, schemas: PlanningSchemaRegistry, at: string
-): { set: ChangeSet, empty: boolean } => {
-  const set = computeChanges(resolved.card, exec, resolved.type, schemas, at, { slot: resolved.slot })
-  const empty = exec.action === TransitionAction.Update && isEmptyChange(set)
+export const createChangesUtils = (): ChangesUtils => {
+  const changeSetOf = (
+    exec: TransitionExecution, resolved: Resolved, schemas: PlanningSchemaRegistry, at: string
+  ): { set: ChangeSet, empty: boolean } => {
+    const set = changesHelper.computeChanges(resolved.card, exec, resolved.type, schemas, at, { slot: resolved.slot })
+    const empty = exec.action === TransitionAction.Update && changesHelper.isEmptyChange(set)
 
-  return { set, empty }
-}
+    return { set, empty }
+  }
 
-/**
- * Who wrote it — the SCOPE's identity, never the execution's.
- *
- * `profileId`, `userId`, `service` and `channel` come only from the scope (the server builds it
- * from the authenticated request); the descriptive `agent`/`runId` an in-process caller passes on
- * the execution are kept unless the scope's own actor names them.
- */
-export const actorOf = (scope: PlanningScope, exec: TransitionExecution): TransitionActor => clean({
-  agent: exec.actor?.agent,
-  runId: exec.actor?.runId,
-  ...clean({ profileId: scope.profileId, userId: scope.userId, service: scope.service }),
-  ...clean(scope.actor ?? {}),
-  channel: scope.channel ?? scope.actor?.channel,
-})
+  const actorOf = (scope: PlanningScope, exec: TransitionExecution): TransitionActor => clean({
+    agent: exec.actor?.agent,
+    runId: exec.actor?.runId,
+    ...clean({ profileId: scope.profileId, userId: scope.userId, service: scope.service }),
+    ...clean(scope.actor ?? {}),
+    channel: scope.channel ?? scope.actor?.channel,
+  })
 
-const withFrom = (link: RelationshipDraft, card: string): RelationshipDraft => ({ ...link, from: link.from ?? card })
+  const withFrom = (link: RelationshipDraft, card: string): RelationshipDraft => ({ ...link, from: link.from ?? card })
 
-/** Step 11's record: the event as it is appended, `pending`. */
-export const transitionOf = (params: {
-  exec: TransitionExecution
-  resolved: Resolved
-  scope: PlanningScope
-  set: ChangeSet
-  cardId: string
-  seq: number
-  project?: string
-  at: string
-}): Transition => {
-  const { exec, resolved, scope, set, cardId, seq, project, at } = params
-  const kind = resolved.create ? (exec.card as WorkcardDraft).kind : resolved.card!.kind
+  const transitionOf = (params: AppendParams): Transition => {
+    const { exec, resolved, scope, set, cardId, seq, project, at } = params
+    const kind = resolved.create ? (exec.card as WorkcardDraft).kind : resolved.card!.kind
 
-  return clean({
-    entityId: scope.entityId,
-    card: cardId,
-    kind,
-    type: resolved.type.type,
-    project,
-    seq,
-    action: exec.action,
-    flow: set.flow,
-    transition: exec.action === TransitionAction.Transit ? exec.transition : undefined,
-    from: set.from,
-    to: set.to,
-    changes: set.changes,
-    unset: set.unset.length > 0 ? set.unset : undefined,
-    link: exec.link != null && exec.action !== TransitionAction.Create ? withFrom(exec.link, cardId) : undefined,
-    links: resolved.create && (exec.links?.length ?? 0) > 0 ? exec.links!.map(link => withFrom(link, cardId)) : undefined,
-    actor: actorOf(scope, exec),
-    cause: exec.cause,
-    key: exec.key,
-    at,
-    commit: { state: CommitState.Pending },
-  })
+    return clean({
+      entityId: scope.entityId,
+      card: cardId,
+      kind,
+      type: resolved.type.type,
+      project,
+      seq,
+      action: exec.action,
+      flow: set.flow,
+      transition: exec.action === TransitionAction.Transit ? exec.transition : undefined,
+      from: set.from,
+      to: set.to,
+      changes: set.changes,
+      unset: set.unset.length > 0 ? set.unset : undefined,
+      link: exec.link != null && exec.action !== TransitionAction.Create ? withFrom(exec.link, cardId) : undefined,
+      links: resolved.create && (exec.links?.length ?? 0) > 0 ? exec.links!.map(link => withFrom(link, cardId)) : undefined,
+      actor: actorOf(scope, exec),
+      cause: exec.cause,
+      key: exec.key,
+      at,
+      commit: { state: CommitState.Pending },
+    })
+  }
+
+  return { changeSetOf, actorOf, transitionOf }
 }
+
+export const changesUtils = createChangesUtils()

package/src/executor/code/types.ts

@@ -0,0 +1,23 @@
+import type { PlanningExecContext, PlanningPlugin, PlanningScope, TransitionExecution } from '@owlmeans/planning'
+import type { PluginRegistry } from '../../types.js'
+import type { Resolved } from '../types.js'
+
+/** Step 8 of the write path: the code a card gets, unique within its policy's scope. */
+export interface CodeUtils {
+  /**
+   * Step 8: the code a new card gets, or the check a changed code passes.
+   *
+   * A caller-supplied code is checked for uniqueness; otherwise the plugins' `mintCode` chain answers
+   * (first answer wins, and is checked too); otherwise the type's policy mints one — a slug policy
+   * derives it from the title. A type with no policy and no supplied code gets none.
+   *
+   * @throws {CodeTaken}
+   */
+  assignCode: (
+    exec: TransitionExecution,
+    resolved: Resolved,
+    scope: PlanningScope,
+    registry: PluginRegistry,
+    contextOf: (plugin: PlanningPlugin) => PlanningExecContext
+  ) => Promise<TransitionExecution>
+}

package/src/executor/code.ts

@@ -1,77 +1,76 @@
-import { CODE_MINT_ATTEMPTS, CodeScope, CodeStyle, CodeTaken, mintCode, TransitionAction, type CodePolicy, type PlanningExecContext, type PlanningPlugin, type PlanningScope, type TransitionExecution, type WorkcardDraft, type Workcard } from '@owlmeans/planning'
+import { CODE_MINT_ATTEMPTS, codeHelper, CodeScope, CodeStyle, CodeTaken, TransitionAction, type CodePolicy, type PlanningExecContext, type PlanningPlugin, type PlanningScope, type TransitionExecution, type Workcard, type WorkcardDraft } from '@owlmeans/planning'
 import type { Criteria } from '@owlmeans/resource'
 import type { PluginRegistry } from '../types.js'
+import type { CodeUtils } from './code/types.js'
 import type { Resolved } from './types.js'
 
-/** The criteria a code must be unique within — the policy's scope, `parent` when there is none. */
-const scopeCriteria = (
-  scope: PlanningScope, type: string, parent: string | undefined, policy?: CodePolicy
-): Criteria<Workcard> => ({
-  entityId: scope.entityId,
-  type,
-  ...((policy?.uniqueWithin ?? CodeScope.Parent) === CodeScope.Parent ? { parent: parent ?? null } : {}),
-}) as Criteria<Workcard>
+export const createCodeUtils = (): CodeUtils => {
+  /** The criteria a code must be unique within — the policy's scope, `parent` when there is none. */
+  const scopeCriteria = (
+    scope: PlanningScope, type: string, parent: string | undefined, policy?: CodePolicy
+  ): Criteria<Workcard> => ({
+    entityId: scope.entityId,
+    type,
+    ...((policy?.uniqueWithin ?? CodeScope.Parent) === CodeScope.Parent ? { parent: parent ?? null } : {}),
+  }) as Criteria<Workcard>
 
-export const takenProbe = (resolved: Resolved, scope: PlanningScope, parent: string | undefined) => {
-  const base = scopeCriteria(scope, resolved.type.type, parent, resolved.type.code)
+  /** Is a code taken within the scope the type's policy names (its parent when it names none)? */
+  const takenProbe = (resolved: Resolved, scope: PlanningScope, parent: string | undefined): (code: string) => Promise<boolean> => {
+    const base = scopeCriteria(scope, resolved.type.type, parent, resolved.type.code)
 
-  return async (code: string): Promise<boolean> =>
-    await resolved.store.cards.count({ ...base, code } as Criteria<Workcard>) > 0
-}
+    return async (code: string): Promise<boolean> =>
+      await resolved.store.cards.count({ ...base, code } as Criteria<Workcard>) > 0
+  }
 
-/**
- * Step 8: the code a new card gets, or the check a changed code passes.
- *
- * A caller-supplied code is checked for uniqueness; otherwise the plugins' `mintCode` chain answers
- * (first answer wins, and is checked too); otherwise the type's policy mints one — a slug policy
- * derives it from the title. A type with no policy and no supplied code gets none.
- *
- * @throws {CodeTaken}
- */
-export const assignCode = async (
-  exec: TransitionExecution,
-  resolved: Resolved,
-  scope: PlanningScope,
-  registry: PluginRegistry,
-  contextOf: (plugin: PlanningPlugin) => PlanningExecContext
-): Promise<TransitionExecution> => {
-  const policy = resolved.type.code
+  const assignCode = async (
+    exec: TransitionExecution,
+    resolved: Resolved,
+    scope: PlanningScope,
+    registry: PluginRegistry,
+    contextOf: (plugin: PlanningPlugin) => PlanningExecContext
+  ): Promise<TransitionExecution> => {
+    const policy = resolved.type.code
 
-  if (exec.action !== TransitionAction.Create) {
-    const code = exec.changes?.code
-    if (code != null && code !== resolved.card?.code
-      && await takenProbe(resolved, scope, exec.changes?.parent ?? resolved.card?.parent)(code)) {
-      throw new CodeTaken(code)
+    if (exec.action !== TransitionAction.Create) {
+      const code = exec.changes?.code
+      if (code != null && code !== resolved.card?.code
+        && await takenProbe(resolved, scope, exec.changes?.parent ?? resolved.card?.parent)(code)) {
+        throw new CodeTaken(code)
+      }
+      return exec
     }
-    return exec
-  }
 
-  const draft = exec.card as WorkcardDraft
-  const taken = takenProbe(resolved, scope, draft.parent)
-  if (draft.code != null && draft.code !== '') {
-    if (await taken(draft.code)) {
-      throw new CodeTaken(draft.code)
+    const draft = exec.card as WorkcardDraft
+    const taken = takenProbe(resolved, scope, draft.parent)
+    if (draft.code != null && draft.code !== '') {
+      if (await taken(draft.code)) {
+        throw new CodeTaken(draft.code)
+      }
+      return exec
+    }
+    if (policy == null) {
+      return exec
     }
-    return exec
-  }
-  if (policy == null) {
-    return exec
-  }
 
-  let code = await registry.mintCode(draft, taken, contextOf)
-  if (code != null) {
-    if (await taken(code)) {
-      throw new CodeTaken(code)
+    let code = await registry.mintCode(draft, taken, contextOf)
+    if (code != null) {
+      if (await taken(code)) {
+        throw new CodeTaken(code)
+      }
+    } else {
+      const count = policy.style === CodeStyle.Sequential
+        ? await resolved.store.cards.count(scopeCriteria(scope, draft.type, draft.parent, policy))
+        : undefined
+      code = await codeHelper.mintCode(policy, taken, CODE_MINT_ATTEMPTS, {
+        ...(policy.style === CodeStyle.Slug ? { seed: draft.title } : {}),
+        ...(count != null ? { count } : {}),
+      })
     }
-  } else {
-    const count = policy.style === CodeStyle.Sequential
-      ? await resolved.store.cards.count(scopeCriteria(scope, draft.type, draft.parent, policy))
-      : undefined
-    code = await mintCode(policy, taken, CODE_MINT_ATTEMPTS, {
-      ...(policy.style === CodeStyle.Slug ? { seed: draft.title } : {}),
-      ...(count != null ? { count } : {}),
-    })
+
+    return { ...exec, card: { ...draft, code } }
   }
 
-  return { ...exec, card: { ...draft, code } }
+  return { assignCode }
 }
+
+export const codeUtils = createCodeUtils()

package/src/executor/creator/types.ts

@@ -0,0 +1,33 @@
+import type { PlanningScope, TransitionExecution } from '@owlmeans/planning'
+
+/** Who owns a card: `createdBy`, stamped from the scope on a create and fixed after it. */
+export interface CreatorHelper {
+  /**
+   * The subject a create made under `scope` is stamped with as its `createdBy`: the scope's
+   * `profileId`, else its `userId`, else the same two of its `actor` — the authenticated subject an
+   * HTTP scope carries, in the same format. `undefined` for a scope that names nobody (a service or a
+   * system scope).
+   */
+  creatorOf: (scope: PlanningScope) => string | undefined
+  /**
+   * A create's draft with `createdBy` defaulted to {@link CreatorHelper.creatorOf} the scope. A
+   * `createdBy` the caller supplied wins; a scope that names nobody leaves the draft as it is;
+   * anything but a create is returned untouched. Never mutates `exec`.
+   *
+   * The executor applies it to every execution, so an in-process facade create and a wire create
+   * stamp the same value.
+   */
+  withCreator: (exec: TransitionExecution, scope: PlanningScope) => TransitionExecution
+  /**
+   * Refuse an execution that names `createdBy` in `changes` or `unset`, whatever the action — a
+   * create included, whose owner is its draft's. After the create it never moves, so an ownership
+   * check (`card.createdBy === profileId`) cannot be bypassed by anyone allowed to update the card.
+   *
+   * The executor runs it with the immutables of step 6, after the `before` chain, so a wire body, an
+   * in-process caller and a plugin are refused alike. It is the executor's own check, whatever
+   * `@owlmeans/planning` build `changesHelper.assertMutable` comes from.
+   *
+   * @throws {PlanningError} `planning:immutable:createdBy`
+   */
+  assertCreatorFixed: (exec: TransitionExecution) => void
+}

package/src/executor/creator.ts

@@ -1,51 +1,43 @@
 import { PlanningError, TransitionAction, type PlanningScope, type TransitionExecution } from '@owlmeans/planning'
 import { CREATOR } from './consts.local.js'
+import type { CreatorHelper } from './creator/types.js'
 
 const named = (value?: string | null): value is string => value != null && value !== ''
 
-/**
- * The subject a create made under `scope` is stamped with as its `createdBy`: the scope's
- * `profileId`, else its `userId`, else the same two of its `actor` — the authenticated subject an
- * HTTP scope carries, in the same format. `undefined` for a scope that names nobody (a service or a
- * system scope).
- */
-export const creatorOf = (scope: PlanningScope): string | undefined =>
-  [scope.profileId, scope.userId, scope.actor?.profileId, scope.actor?.userId].find(named)
-
-/**
- * A create's draft with `createdBy` defaulted to {@link creatorOf} the scope. A `createdBy` the
- * caller supplied wins; a scope that names nobody leaves the draft as it is; anything but a create
- * is returned untouched. Never mutates `exec`.
- *
- * The executor applies it to every execution, so an in-process facade create and a wire create
- * stamp the same value.
- */
-export const withCreator = (exec: TransitionExecution, scope: PlanningScope): TransitionExecution => {
-  if (exec.action !== TransitionAction.Create || exec.card == null || typeof exec.card !== 'object') {
-    return exec
+export const createCreatorHelper = (): CreatorHelper => {
+  const creatorOf = (scope: PlanningScope): string | undefined =>
+    [scope.profileId, scope.userId, scope.actor?.profileId, scope.actor?.userId].find(named)
+
+  const withCreator = (exec: TransitionExecution, scope: PlanningScope): TransitionExecution => {
+    if (exec.action !== TransitionAction.Create || exec.card == null || typeof exec.card !== 'object') {
+      return exec
+    }
+    if (named(exec.card.createdBy)) {
+      return exec
+    }
+    const creator = creatorOf(scope)
+
+    return creator == null ? exec : { ...exec, card: { ...exec.card, createdBy: creator } }
   }
-  if (named(exec.card.createdBy)) {
-    return exec
+
+  const assertCreatorFixed = (exec: TransitionExecution): void => {
+    if ((exec.changes as Record<string, unknown> | undefined)?.[CREATOR] !== undefined
+      || (exec.unset ?? []).some(path => path.split('.')[0] === CREATOR)) {
+      throw new PlanningError(`immutable:${CREATOR}`)
+    }
   }
-  const creator = creatorOf(scope)
 
-  return creator == null ? exec : { ...exec, card: { ...exec.card, createdBy: creator } }
+  return { creatorOf, withCreator, assertCreatorFixed }
 }
 
-/**
- * Refuse an execution that names `createdBy` in `changes` or `unset`, whatever the action — a
- * create included, whose owner is its draft's. After the create it never moves, so an ownership
- * check (`card.createdBy === profileId`) cannot be bypassed by anyone allowed to update the card.
- *
- * The executor runs it with the immutables of step 6, after the `before` chain, so a wire body, an
- * in-process caller and a plugin are refused alike. It is the executor's own check, whatever
- * `@owlmeans/planning` build `assertMutable` comes from.
- *
- * @throws {PlanningError} `planning:immutable:createdBy`
- */
-export const assertCreatorFixed = (exec: TransitionExecution): void => {
-  if ((exec.changes as Record<string, unknown> | undefined)?.[CREATOR] !== undefined
-    || (exec.unset ?? []).some(path => path.split('.')[0] === CREATOR)) {
-    throw new PlanningError(`immutable:${CREATOR}`)
-  }
-}
+export const creatorHelper = createCreatorHelper()
+
+/** @deprecated compat:factory-refactor — use `creatorHelper.creatorOf(…)` */
+export const creatorOf = (scope: PlanningScope): string | undefined => creatorHelper.creatorOf(scope)
+
+/** @deprecated compat:factory-refactor — use `creatorHelper.withCreator(…)` */
+export const withCreator = (exec: TransitionExecution, scope: PlanningScope): TransitionExecution =>
+  creatorHelper.withCreator(exec, scope)
+
+/** @deprecated compat:factory-refactor — use `creatorHelper.assertCreatorFixed(…)` */
+export const assertCreatorFixed = (exec: TransitionExecution): void => creatorHelper.assertCreatorFixed(exec)

package/src/executor/resolve/types.ts

@@ -0,0 +1,30 @@
+import type { PlanningFacade, PlanningSchemaRegistry, TransitionExecution, Workcard, WorkcardKind } from '@owlmeans/planning'
+import type { Resolved } from '../types.js'
+
+/** Steps 1 and 4 of the write path, over one service runtime. */
+export interface ResolveUtils {
+  /**
+   * Step 1: a deep copy with trimmed text, `parents ∋ parent` on a draft, and no duplicate `unset`
+   * paths. The caller's object is never touched.
+   */
+  normalizeExecution: (input: TransitionExecution) => TransitionExecution
+  /**
+   * The parent type's rule for a child of `kind`/`type`: a project lists the `cardTypes` (and
+   * `projectTypes`) it admits, and one declaring `scopedCardTypes` also admits a card type its layer
+   * (`view`, the parent project's resolved schemas) defines as data. Project types are code's alone.
+   *
+   * @throws {CardTypeNotAllowed}
+   */
+  assertChildAllowed: (parent: Workcard, kind: WorkcardKind, type: string, view?: PlanningSchemaRegistry) => void
+  /** The layer a parent project admits data-defined children through — `undefined` without a schema port. */
+  childViewOf: (entityId: string, parent: Workcard) => Promise<PlanningSchemaRegistry | undefined>
+  /**
+   * Step 4: the card, its type and flow, its parent and — for a specification — its slot.
+   *
+   * @throws {WorkcardNotFound | PlanningScopeMismatch | UnknownWorkcardType | UnknownStatusFlow}
+   * @throws {ParentNotFound | CardTypeNotAllowed | PlanningError}
+   */
+  resolveExecution: (facade: PlanningFacade, exec: TransitionExecution) => Promise<Resolved>
+  /** The project a transition is filed under: a project's own id, else its parent's project. */
+  projectFor: (resolved: Resolved, exec: TransitionExecution, cardId: string) => string | undefined
+}