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

package/src/executor/resolve.ts

@@ -1,33 +1,22 @@
-import {
-  CardTypeNotAllowed, isProject, normalizeParents, ParentNotFound, PlanningError, PlanningScopeMismatch,
-  primaryFlowOf, projectOf, slotOf, TransitionAction, UnknownStatusFlow, WorkcardKind, WorkcardNotFound,
-} from '@owlmeans/planning'
-import type {
-  AnyTypeSchema, PlanningFacade, PlanningStore, ProjectTypeSchema, Specification, SpecificationSlot,
-  StatusFlowSchema, TransitionExecution, Workcard, WorkcardDraft,
-} from '@owlmeans/planning'
-import type { PlanningRuntime } from '../service.js'
-
-/** Everything the steps after resolution read about an execution. */
-export interface Resolved {
-  create: boolean
-  /** The existing card (not a create). */
-  card?: Workcard
-  type: AnyTypeSchema
-  flowId: string
-  flow: StatusFlowSchema
-  /** The primary parent, when it resolves. */
-  parent?: Workcard
-  /** The slot a specification belongs to. */
-  slot?: SpecificationSlot
-  /** The store the type is written to. */
-  store: PlanningStore
+import { CardTypeNotAllowed, isProject, normalizeParents, ParentNotFound, PlanningError, PlanningSchemaKind, PlanningScopeMismatch, primaryFlowOf, projectOf, SchemaOrigin, slotOf, TransitionAction, UnknownStatusFlow, UnknownWorkcardType, WorkcardKind, WorkcardNotFound, type AnyTypeSchema, type PlanningFacade, type PlanningSchemaRegistry, type ProjectTypeSchema, type ScopedSchemaRegistry, type Specification, type TransitionExecution, type Workcard, type WorkcardDraft } from '@owlmeans/planning'
+import type { PlanningRuntime } from '../types.js'
+import { TRIMMED } from './consts.local.js'
+import type { Resolved } from './types.js'
+
+const isScoped = (schemas: PlanningSchemaRegistry): schemas is ScopedSchemaRegistry =>
+  typeof (schemas as Partial<ScopedSchemaRegistry>).originOf === 'function'
+
+/** A type the layer resolves from a data-defined record rather than from code. */
+const dataDefined = (schemas: PlanningSchemaRegistry | undefined, type: string): boolean => {
+  if (schemas == null || !isScoped(schemas) || !schemas.has(type)) {
+    return false
+  }
+  const origin = schemas.originOf(PlanningSchemaKind.Type, type)
+  return origin === SchemaOrigin.Entity || origin === SchemaOrigin.Project
 }
 
 const trimmed = (value: unknown): unknown => typeof value === 'string' ? value.trim() : value
 
-const TRIMMED = ['title', 'description', 'code'] as const
-
 const trim = <T extends object>(record: T | undefined): T | undefined => {
   if (record == null) {
     return record
@@ -45,7 +34,7 @@ const trim = <T extends object>(record: T | undefined): T | undefined => {
  * 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.
  */
-export const normalizeExecution = (input: TransitionExecution): TransitionExecution => {
+const normalizeExecution = (input: TransitionExecution): TransitionExecution => {
   const exec = structuredClone(input) as TransitionExecution
   if (exec.card != null && typeof exec.card === 'object') {
     const draft = trim(exec.card) as WorkcardDraft
@@ -61,9 +50,15 @@ export const normalizeExecution = (input: TransitionExecution): TransitionExecut
   return exec
 }
 
-/** The parent type's rule for a child of `kind`/`type`. @throws {CardTypeNotAllowed} */
-export const assertChildAllowed = (
-  runtime: PlanningRuntime, parent: Workcard, kind: WorkcardKind, type: string
+/**
+ * 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}
+ */
+const assertChildAllowed = (
+  runtime: PlanningRuntime, parent: Workcard, kind: WorkcardKind, type: string, view?: PlanningSchemaRegistry
 ): void => {
   if (kind === WorkcardKind.Specification) {
     return
@@ -73,24 +68,37 @@ export const assertChildAllowed = (
   }
   const parentType = runtime.service().schemas.type(parent.type) as ProjectTypeSchema
   const allowed = kind === WorkcardKind.Project ? parentType.projectTypes ?? [] : parentType.cardTypes ?? []
-  if (!allowed.includes(type)) {
-    throw new CardTypeNotAllowed(`${parent.type}:${type}`)
+  if (allowed.includes(type)) {
+    return
+  }
+  if (kind === WorkcardKind.Card && parentType.scopedCardTypes === true && dataDefined(view, type)) {
+    return
   }
+  throw new CardTypeNotAllowed(`${parent.type}:${type}`)
 }
 
+/** The layer a parent project admits data-defined children through — `undefined` without a schema port. */
+const childViewOf = async (
+  runtime: PlanningRuntime, entityId: string, parent: Workcard
+): Promise<PlanningSchemaRegistry | undefined> =>
+  runtime.schemaStore() == null || !isProject(parent) ? undefined : await runtime.schemasFor(entityId, parent.id)
+
 /**
  * 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}
  */
-export const resolveExecution = async (
+const resolveExecution = async (
   runtime: PlanningRuntime, facade: PlanningFacade, exec: TransitionExecution
 ): Promise<Resolved> => {
   const service = runtime.service()
-  const schemas = service.schemas
   const entityId = facade.scope.entityId
   const create = exec.action === TransitionAction.Create
+  // Without a schema port every step reads the code registry itself, in today's order; with one,
+  // the card's project is found first and the step reads that project's resolved layer.
+  const layered = runtime.schemaStore() != null
+  let schemas: PlanningSchemaRegistry = service.schemas
 
   let card: Workcard | undefined
   let type: AnyTypeSchema
@@ -101,14 +109,34 @@ export const resolveExecution = async (
       throw new PlanningError('malformed:create-without-draft')
     }
     const draft = exec.card
+    const parents = normalizeParents(draft.parent, draft.parents)
+    const loaded = new Map<string, Workcard>()
+    if (layered) {
+      // Loaded through the facade, so a parent this scope cannot see is absent here too.
+      const primary = parents[0] != null ? await facade.cards.load(parents[0]) : null
+      if (parents[0] != null && primary == null) {
+        throw new ParentNotFound(parents[0])
+      }
+      if (primary != null) {
+        loaded.set(parents[0], primary)
+      }
+      const project = draft.kind === WorkcardKind.Project || primary == null
+        ? undefined
+        : projectOf({ kind: draft.kind, parent: parents[0], parents } as unknown as Workcard, primary)
+      schemas = await runtime.schemasFor(entityId, project)
+    }
     type = schemas.type(draft.type)
     if (type.kind !== draft.kind) {
       throw new PlanningError(`malformed:kind:${draft.type}:${draft.kind}`)
     }
+    if (layered && isScoped(schemas) && schemas.isRetired(PlanningSchemaKind.Type, draft.type)) {
+      // Existing cards keep resolving a retired type; nothing new is made of it.
+      throw new UnknownWorkcardType(`retired:${draft.type}`)
+    }
     // Normalized: the primary parent is first. It must accept the child; so must every project
     // among the secondary parents.
-    for (const [index, id] of normalizeParents(draft.parent, draft.parents).entries()) {
-      const found = await facade.cards.load(id)
+    for (const [index, id] of parents.entries()) {
+      const found = loaded.get(id) ?? await facade.cards.load(id)
       if (found == null) {
         throw new ParentNotFound(id)
       }
@@ -116,7 +144,8 @@ export const resolveExecution = async (
         parent = found
       }
       if (index === 0 || isProject(found)) {
-        assertChildAllowed(runtime, found, draft.kind, draft.type)
+        const view = !layered ? undefined : index === 0 && isProject(found) ? schemas : await childViewOf(runtime, entityId, found)
+        assertChildAllowed(runtime, found, draft.kind, draft.type, view)
       }
     }
     if (draft.kind === WorkcardKind.Specification && parent == null) {
@@ -133,9 +162,19 @@ export const resolveExecution = async (
     if (found.entityId !== entityId) {
       throw new PlanningScopeMismatch(exec.card)
     }
+    if (facade.scope.projects != null && await facade.cards.load(exec.card) == null) {
+      // Outside the scope's projects: absent, exactly like another entity's card.
+      throw new WorkcardNotFound(exec.card)
+    }
     card = found
-    type = schemas.type(card.type)
-    parent = card.parent != null ? await facade.cards.load(card.parent) ?? undefined : undefined
+    if (layered) {
+      parent = card.parent != null ? await facade.cards.load(card.parent) ?? undefined : undefined
+      schemas = await runtime.schemasFor(entityId, projectOf(card, parent))
+      type = schemas.type(card.type)
+    } else {
+      type = schemas.type(card.type)
+      parent = card.parent != null ? await facade.cards.load(card.parent) ?? undefined : undefined
+    }
   }
 
   const flowId = exec.flow ?? primaryFlowOf(type)
@@ -158,11 +197,12 @@ export const resolveExecution = async (
     ...(parent != null ? { parent } : {}),
     ...(slot != null ? { slot } : {}),
     store: service.store(type.type),
+    schemas,
   }
 }
 
 /** The project a transition is filed under: a project's own id, else its parent's project. */
-export const projectFor = (resolved: Resolved, exec: TransitionExecution, cardId: string): string | undefined => {
+const projectFor = (resolved: Resolved, exec: TransitionExecution, cardId: string): string | undefined => {
   if (resolved.card != null) {
     return isProject(resolved.card) ? resolved.card.id : projectOf(resolved.card, resolved.parent)
   }
@@ -172,3 +212,7 @@ export const projectFor = (resolved: Resolved, exec: TransitionExecution, cardId
   }
   return projectOf({ kind: draft.kind, parent: draft.parent, parents: draft.parents ?? [] } as unknown as Workcard, resolved.parent)
 }
+
+export const createResolveHelper = () => ({ normalizeExecution, assertChildAllowed, childViewOf, resolveExecution, projectFor })
+
+export const resolveHelper = createResolveHelper()

package/src/executor/types.ts

@@ -0,0 +1,25 @@
+import type { AnyTypeSchema, PlanningSchemaRegistry, PlanningStore, SpecificationSlot, StatusFlowSchema, Workcard } from '@owlmeans/planning'
+import type { createResolveHelper } from './resolve.js'
+
+/** Everything the steps after resolution read about an execution. */
+export interface Resolved {
+  create: boolean
+  /** The existing card (not a create). */
+  card?: Workcard
+  type: AnyTypeSchema
+  flowId: string
+  flow: StatusFlowSchema
+  /** The primary parent, when it resolves. */
+  parent?: Workcard
+  /** The slot a specification belongs to. */
+  slot?: SpecificationSlot
+  /** The store the type is written to. */
+  store: PlanningStore
+  /**
+   * The registry every later step reads: the service's code registry itself, or — where the store
+   * holds data-defined schemas — the resolved layer of the card's project.
+   */
+  schemas: PlanningSchemaRegistry
+}
+
+export type ResolveHelper = ReturnType<typeof createResolveHelper>

package/src/executor/validate.ts

@@ -1,17 +1,9 @@
-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))
+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, type PlanningFacade, type RelationshipDraft, type Specification, type TransitionExecution, type WorkcardDraft } from '@owlmeans/planning'
+import type { PlanningRuntime } from '../types.js'
+import { assertCreatorFixed } from './creator.js'
+import type { Resolved } from './types.js'
+import { ACTIONS } from './consts.local.js'
+import { resolveHelper } from './resolve.js'
 
 const malformed = (what: string): PlanningError => new PlanningError(`malformed:${what}`)
 
@@ -58,10 +50,10 @@ const assertShape = (exec: TransitionExecution, resolved: Resolved): void => {
   assertText('code', changes.code ?? undefined, CODE_MAX, false)
 }
 
-const assertFlow = (exec: TransitionExecution, resolved: Resolved, runtime: PlanningRuntime): void => {
+const assertFlow = (exec: TransitionExecution, resolved: Resolved): void => {
   if (resolved.create) {
     const status = (exec.card as WorkcardDraft).status
-    const primary = runtime.service().schemas.primaryFlow(resolved.type.type)
+    const primary = resolved.schemas.primaryFlow(resolved.type.type)
     if (status != null && !primary.statuses.some(definition => definition.key === status)) {
       throw new IllegalTransition(`${primary.id}:create:${status}`)
     }
@@ -77,8 +69,8 @@ const assertFlow = (exec: TransitionExecution, resolved: Resolved, runtime: Plan
   }
 }
 
-const assertFields = (exec: TransitionExecution, resolved: Resolved, runtime: PlanningRuntime): void => {
-  const schemas = runtime.service().schemas
+const assertFields = (exec: TransitionExecution, resolved: Resolved): void => {
+  const schemas = resolved.schemas
   if (resolved.create) {
     const draft = exec.card as WorkcardDraft
     validateFields(schemas, resolved.type.type, mergeFields(draft.fields, exec.changes?.fields))
@@ -127,18 +119,20 @@ const assertParentMove = async (
     if (found == null) {
       throw new ParentNotFound(id)
     }
-    assertChildAllowed(runtime, found, resolved.card!.kind, resolved.card!.type)
+    resolveHelper.assertChildAllowed(
+      runtime, found, resolved.card!.kind, resolved.card!.type, await resolveHelper.childViewOf(runtime, facade.scope.entityId, found)
+    )
   }
 }
 
 const assertSpecification = async (
-  exec: TransitionExecution, resolved: Resolved, runtime: PlanningRuntime, facade: PlanningFacade
+  exec: TransitionExecution, resolved: Resolved, 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
+  const schemas = resolved.schemas
 
   if (resolved.create) {
     const draft = exec.card as WorkcardDraft
@@ -232,8 +226,9 @@ const assertRelationships = async (
 }
 
 /**
- * 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.
+ * Step 6: shape, flow rule, immutables (`createdBy` among them, {@link assertCreatorFixed}),
+ * `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}
@@ -243,11 +238,12 @@ export const validateExecution = async (
   runtime: PlanningRuntime, facade: PlanningFacade, exec: TransitionExecution, resolved: Resolved
 ): Promise<void> => {
   assertShape(exec, resolved)
-  assertFlow(exec, resolved, runtime)
+  assertFlow(exec, resolved)
   assertMutable(exec, resolved.type)
-  assertFields(exec, resolved, runtime)
+  assertCreatorFixed(exec)
+  assertFields(exec, resolved)
   assertLabels(exec, resolved)
   await assertParentMove(exec, resolved, runtime, facade)
-  await assertSpecification(exec, resolved, runtime, facade)
+  await assertSpecification(exec, resolved, facade)
   await assertRelationships(exec, resolved, facade)
 }

package/src/executor.ts

@@ -1,17 +1,16 @@
 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 { PlanningError, PlanningUnsupported, WorkcardConflict, type ExecuteOptions, type PlanningExecContext, type PlanningFacade, type PlanningPlugin, type PlanningStore, type Transition, type TransitionExecution, type TransitionReceipt } from '@owlmeans/planning'
 import { changeSetOf, transitionOf } from './executor/changes.js'
 import { assignCode } from './executor/code.js'
+import { withCreator } from './executor/creator.js'
 import { makeReceipt } from './executor/receipt.js'
-import { normalizeExecution, projectFor, resolveExecution } from './executor/resolve.js'
-import type { Resolved } from './executor/resolve.js'
+import type { Resolved } from './executor/types.js'
 import { validateExecution } from './executor/validate.js'
-import type { PlanningRuntime } from './service.js'
+import type { PlanningRuntime } from './types.js'
+import { resolveHelper } from './executor/resolve.js'
+
+export { assertCreatorFixed, creatorOf, withCreator } from './executor/creator.js'
 
 const isoNow = (): string => new Date().toISOString()
 
@@ -25,7 +24,7 @@ const execContextOf = (
 ) => (plugin: PlanningPlugin): PlanningExecContext => ({
   context: runtime.context() as BasicContext<BasicConfig>,
   scope: facade.scope,
-  schemas: runtime.service().schemas,
+  schemas: resolved.schemas,
   store: resolved.store,
   facade,
   plugin,
@@ -64,11 +63,13 @@ const currentReceipt = async (
 /**
  * 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`.
+ * 1 normalize (a create's `createdBy` defaults to the scope's subject — {@link withCreator}) →
+ * 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 (a `createdBy` in `changes`/`unset` is refused — {@link assertCreatorFixed}) →
+ * 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.
  */
@@ -76,10 +77,9 @@ 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)
+  let exec = withCreator(resolveHelper.normalizeExecution(input), scope)
 
   if (scope.entityId == null || scope.entityId === '') {
     throw new PlanningError('malformed:scope-without-entity')
@@ -92,12 +92,12 @@ export const executeTransition = async (
     }
   }
 
-  let resolved = await resolveExecution(runtime, facade, exec)
+  let resolved = await resolveHelper.resolveExecution(runtime, facade, exec)
 
   const before = identityOf(exec)
-  exec = normalizeExecution(await runtime.registry.before(exec, execContextOf(runtime, facade, resolved)))
+  exec = resolveHelper.normalizeExecution(await runtime.registry.before(exec, execContextOf(runtime, facade, resolved)))
   if (identityOf(exec) !== before) {
-    resolved = await resolveExecution(runtime, facade, exec)
+    resolved = await resolveHelper.resolveExecution(runtime, facade, exec)
   }
 
   await validateExecution(runtime, facade, exec, resolved)
@@ -114,7 +114,7 @@ export const executeTransition = async (
 
   exec = await assignCode(exec, resolved, scope, runtime.registry, execContextOf(runtime, facade, resolved))
 
-  const { set, empty } = changeSetOf(exec, resolved, service.schemas, at)
+  const { set, empty } = changeSetOf(exec, resolved, resolved.schemas, at)
   if (empty) {
     return await currentReceipt(store, resolved, scope.entityId, opts)
   }
@@ -126,7 +126,7 @@ export const executeTransition = async (
 
   const transition = transitionOf({
     exec, resolved, scope, set, cardId, seq, at,
-    project: projectFor(resolved, exec, cardId),
+    project: resolveHelper.projectFor(resolved, exec, cardId),
   })
 
   let appended: Transition