@owlmeans/server-planning 0.1.18-rc.9 → 0.1.18

package/src/definitions.ts

@@ -0,0 +1,264 @@
+import { cardHelper, PlanningSchemaKind, PlanningUnsupported, SchemaConflict, SchemaInUse, scopedSchemaHelper, UnknownStatusFlow, UnknownWorkcardType, WorkcardNotFound, type AssigneeTypeSchema, 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 { changesUtils } from './executor/changes.js'
+import type { PlanningRuntime, SchemaViews, SchemaViewsOptions } from './types.js'
+import type { Planned } from './types.local.js'
+
+const isoNow = (): string => new Date().toISOString()
+
+/**
+ * The resolved layers of one planning service, cached per (organization, project) and keyed by the
+ * organization's schema revision and the code registry's version — a write anywhere, in any
+ * process, moves the revision the next lookup reads, so a cached layer is never served stale. A
+ * store that can `watch` evicts an organization's layers as soon as it hears of a write.
+ */
+export const makeSchemaViews = (opts: SchemaViewsOptions): SchemaViews => {
+  const limit = opts.limit ?? DEFAULT_SCHEMA_VIEWS
+  const cache = new Map<string, { revision: number, version: number, view: ScopedSchemaRegistry }>()
+  let watching: { store: SchemaStore, release: Unsubscribe } | undefined
+
+  const keyOf = (entityId: string, project?: string): string => `${entityId}\u0000${project ?? ''}`
+
+  const evict = (entityId: string): void => {
+    const prefix = `${entityId}\u0000`
+    for (const key of [...cache.keys()]) {
+      if (key.startsWith(prefix)) {
+        cache.delete(key)
+      }
+    }
+  }
+
+  const scoped: SchemaViews['scoped'] = async (entityId, project) => {
+    const store = opts.port()
+    if (store == null) {
+      throw new PlanningUnsupported('schemas')
+    }
+    if (store.watch != null && watching?.store !== store) {
+      watching?.release()
+      watching = { store, release: store.watch(evict) }
+    }
+
+    const revision = await store.revision(entityId)
+    const version = opts.version()
+    const key = keyOf(entityId, project)
+    const hit = cache.get(key)
+    if (hit != null && hit.revision === revision && hit.version === version) {
+      cache.delete(key)
+      cache.set(key, hit)
+      return hit.view
+    }
+
+    const records = [
+      ...await store.list({ entityId, project: null }),
+      ...(project != null ? await store.list({ entityId, project }) : []),
+    ]
+    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) {
+      const oldest = cache.keys().next().value
+      if (oldest == null) {
+        break
+      }
+      cache.delete(oldest)
+    }
+
+    return view
+  }
+
+  return {
+    of: async (entityId, project) => opts.port() == null ? opts.code() : await scoped(entityId, project),
+    scoped,
+  }
+}
+
+const planOf = (declarations: SchemaDeclarations): Planned[] => [
+  ...(declarations.assigneeTypes ?? []).map(schema => ({ kind: PlanningSchemaKind.AssigneeType, key: schema.type, definition: schema })),
+  ...(declarations.flows ?? []).map(flow => ({ kind: PlanningSchemaKind.Flow, key: flow.id, definition: flow })),
+  ...(declarations.types ?? []).map(type => ({ kind: PlanningSchemaKind.Type, key: type.type, definition: type })),
+]
+
+const layerKey = (kind: PlanningSchemaKind, key: string): string => `${kind}:${key}`
+
+/**
+ * The data-defined schema surface of one scoped facade. Every write checks, before anything is
+ * stored: the project (a project card this scope can see), the seal of the code registry, the
+ * declaration's closed-form checks (a type's flows must resolve in its layer, counting the flows
+ * written beside it; a type's and a flow's `app` bag against the application's declarations) — and
+ * then writes through the port's compare-and-set.
+ */
+export const makeDefinitions = (runtime: PlanningRuntime, facade: PlanningFacade): PlanningDefinitions => {
+  const scope = facade.scope
+  const entityId = scope.entityId
+  const now = runtime.options.now ?? isoNow
+
+  const port = (): SchemaStore => {
+    const store = runtime.schemaStore()
+    if (store == null) {
+      throw new PlanningUnsupported('schemas')
+    }
+    return store
+  }
+
+  const visible = async (project: string): Promise<boolean> => scope.projects == null || await facade.cards.load(project) != null
+
+  /** @throws {WorkcardNotFound} for anything but a project card this scope can see */
+  const assertProject = async (project?: string): Promise<void> => {
+    if (project == null) {
+      return
+    }
+    const card = await facade.cards.load(project)
+    if (card == null || !cardHelper.isProject(card)) {
+      throw new WorkcardNotFound(project)
+    }
+  }
+
+  const layerOf = async (project?: string): Promise<Map<string, ScopedSchemaRecord>> =>
+    new Map((await port().list({ entityId, project: project ?? null }))
+      .map(record => [layerKey(record.kind, record.key), record]))
+
+  /** Seal and closed-form checks for everything in the plan — nothing is written when one fails. */
+  const validate = async (plan: Planned[], project?: string): Promise<void> => {
+    const code = runtime.service().schemas
+    const app = code.app()
+    const layer = await runtime.scopedSchemas(entityId, project)
+    const pending = new Map(plan.filter(entry => entry.kind === PlanningSchemaKind.Flow)
+      .map(entry => [entry.key, entry.definition as StatusFlowSchema]))
+    const flows: Pick<PlanningSchemaRegistry, 'flow'> = { flow: id => pending.get(id) ?? layer.flow(id) }
+
+    for (const entry of plan) {
+      scopedSchemaHelper.assertOverridable(code, entry.kind, entry.key)
+      if (entry.kind === PlanningSchemaKind.AssigneeType) {
+        if (project != null) throw new PlanningUnsupported('assignee-schema:project-layer')
+        scopedSchemaHelper.assertAssigneeTypeSchema(entry.definition as AssigneeTypeSchema)
+      } else if (entry.kind === PlanningSchemaKind.Flow) {
+        scopedSchemaHelper.assertFlowSchema(entry.definition as StatusFlowSchema, app)
+      } else {
+        scopedSchemaHelper.assertTypeSchema(entry.definition as WorkcardTypeSchema, flows, app)
+      }
+    }
+  }
+
+  const recordOf = (
+    entry: Planned, version: number, project: string | undefined, current?: ScopedSchemaRecord, retired?: boolean
+  ): ScopedSchemaRecord => {
+    const at = now()
+    const by = changesUtils.actorOf(scope, {} as TransitionExecution)
+    return Object.fromEntries(Object.entries({
+      entityId,
+      project,
+      kind: entry.kind,
+      key: entry.key,
+      version,
+      definition: { ...structuredClone(entry.definition), version },
+      retired: retired === true ? true : undefined,
+      createdAt: current?.createdAt ?? at,
+      updatedAt: current != null ? at : undefined,
+      by: Object.keys(by).length > 0 ? by : undefined,
+    }).filter(([, value]) => value !== undefined)) as unknown as ScopedSchemaRecord
+  }
+
+  const unit = async <R>(run: () => Promise<R>): Promise<R> => {
+    const store = runtime.service().store()
+    return store.unit != null ? await store.unit(entityId, run) : await run()
+  }
+
+  const write = async (
+    plan: Planned[], opts: SchemaWriteOptions | undefined, versionOf: (entry: Planned, current?: ScopedSchemaRecord) => number | null
+  ): Promise<ScopedSchemaRecord[]> => await unit(async () => {
+    await assertProject(opts?.project)
+    const layer = await layerOf(opts?.project)
+    const todo = plan
+      .map(entry => ({ entry, current: layer.get(layerKey(entry.kind, entry.key)) }))
+      .map(item => ({ ...item, version: versionOf(item.entry, item.current) }))
+      .filter((item): item is typeof item & { version: number } => item.version != null)
+    await validate(todo.map(item => item.entry), opts?.project)
+
+    const written: ScopedSchemaRecord[] = []
+    for (const item of todo) {
+      written.push(await port().put(recordOf(item.entry, item.version, opts?.project, item.current)))
+    }
+    return written
+  })
+
+  const put = async (entry: Planned, opts?: SchemaWriteOptions): Promise<ScopedSchemaRecord> =>
+    (await write([entry], opts, () => entry.definition.version))[0]
+
+  const definitions: PlanningDefinitions = {
+    bundle: async project => {
+      await assertProject(project)
+      return (await runtime.scopedSchemas(entityId, project)).bundle()
+    },
+
+    registry: async project => {
+      await assertProject(project)
+      return await runtime.scopedSchemas(entityId, project)
+    },
+
+    records: async opts => {
+      if (typeof opts?.project === 'string' && !await visible(opts.project)) {
+        return []
+      }
+      const records = await port().list(Object.fromEntries(Object.entries({
+        entityId, project: opts?.project, kind: opts?.kind, retired: opts?.retired,
+      }).filter(([, value]) => value !== undefined)) as { entityId: string })
+      const allowed = await Promise.all(records.map(async record => record.project == null || await visible(record.project)))
+      return records.filter((_record, index) => allowed[index])
+    },
+
+    putAssigneeType: async schema => await put({ kind: PlanningSchemaKind.AssigneeType, key: schema.type, definition: schema }),
+
+    putType: async (type, opts) => await put({ kind: PlanningSchemaKind.Type, key: type.type, definition: type }, opts),
+
+    putFlow: async (flow, opts) => await put({ kind: PlanningSchemaKind.Flow, key: flow.id, definition: flow }, opts),
+
+    define: async (declarations, opts) =>
+      await write(planOf(declarations), opts, (_, current) => (current?.version ?? 0) + 1),
+
+    seed: async (declarations, opts) => {
+      const written: ScopedSchemaRecord[] = []
+      try {
+        written.push(...await write(planOf(declarations), opts, (_, current) => current == null ? 1 : null))
+      } catch (error) {
+        if (!(error instanceof SchemaConflict)) {
+          throw error
+        }
+        // A concurrent seed wrote a key first; what is left is still only what the layer lacks.
+        written.push(...await write(planOf(declarations), opts, (_, current) => current == null ? 1 : null))
+      }
+      return written
+    },
+
+    retire: async (kind, key, opts) => await unit(async () => {
+      await assertProject(opts?.project)
+      const current = (await layerOf(opts?.project)).get(layerKey(kind, key))
+      if (current == null) {
+        throw kind === PlanningSchemaKind.Type ? new UnknownWorkcardType(key) : new UnknownStatusFlow(key)
+      }
+      if (current.retired === true) {
+        return current
+      }
+      const retiring = recordOf({ kind, key, definition: current.definition }, current.version + 1, opts?.project, current, true)
+
+      if (kind === PlanningSchemaKind.Flow) {
+        const code = runtime.service().schemas.bundle()
+        const all = (await port().list({ entityId }))
+          .map(record => record.kind === kind && record.key === key && record.project === current.project ? retiring : record)
+        // The organization's layer reaches every project; a project's reaches itself alone.
+        const projects = opts?.project != null
+          ? [opts.project]
+          : [undefined, ...new Set(all.map(record => record.project).filter((id): id is string => id != null))]
+        for (const project of projects) {
+          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}` : ''}`)
+          }
+        }
+      }
+
+      return await port().put(retiring)
+    }),
+  }
+
+  return definitions
+}

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,78 +1,59 @@
-import { CommitState, computeChanges, isEmptyChange, TransitionAction } from '@owlmeans/planning'
-import type {
-  ChangeSet, PlanningSchemaRegistry, PlanningScope, RelationshipDraft, Transition, TransitionActor,
-  TransitionExecution, WorkcardDraft,
-} from '@owlmeans/planning'
-import type { Resolved } from './resolve.js'
+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,83 +1,76 @@
-import {
-  CODE_MINT_ATTEMPTS, CodeScope, CodeStyle, CodeTaken, mintCode, TransitionAction,
-} from '@owlmeans/planning'
-import type {
-  CodePolicy, PlanningExecContext, PlanningPlugin, PlanningScope, TransitionExecution, WorkcardDraft,
-} 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 { Workcard } from '@owlmeans/planning'
-import type { PluginRegistry } from '../registry.js'
-import type { Resolved } from './resolve.js'
+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/consts.local.ts

@@ -0,0 +1,8 @@
+import { TransitionAction } from '@owlmeans/planning'
+
+/** The field a create's draft writes once and nothing moves afterwards. */
+export const CREATOR = 'createdBy'
+
+export const TRIMMED = ['title', 'description', 'code'] as const
+
+export const ACTIONS = new Set<string>(Object.values(TransitionAction))

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
+}