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

package/src/executor.ts

@@ -1,17 +1,18 @@
-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 { applyHelper, PlanningError, PlanningUnsupported, WorkcardConflict, type ExecuteOptions, type PlanningExecContext, type PlanningFacade, type PlanningPlugin, type PlanningStore, type Transition, type TransitionExecution, type TransitionReceipt } from '@owlmeans/planning'
+import { changesUtils } from './executor/changes.js'
+import { codeUtils } from './executor/code.js'
+import { creatorHelper } 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 { resolveUtilsOf } from './executor/resolve.js'
+import { idHelper } from '@owlmeans/basic-ids'
+
+export { assertCreatorFixed, createCreatorHelper, creatorHelper, creatorOf, withCreator } from './executor/creator.js'
+export type * from './executor/creator/types.js'
 
 const isoNow = (): string => new Date().toISOString()
 
@@ -25,7 +26,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 +65,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 — `creatorHelper.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 — `creatorHelper.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 +79,10 @@ 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)()
+  const resolve = resolveUtilsOf(runtime)
 
-  let exec = normalizeExecution(input)
+  let exec = creatorHelper.withCreator(resolve.normalizeExecution(input), scope)
 
   if (scope.entityId == null || scope.entityId === '') {
     throw new PlanningError('malformed:scope-without-entity')
@@ -92,12 +95,12 @@ export const executeTransition = async (
     }
   }
 
-  let resolved = await resolveExecution(runtime, facade, exec)
+  let resolved = await resolve.resolveExecution(facade, exec)
 
   const before = identityOf(exec)
-  exec = normalizeExecution(await runtime.registry.before(exec, execContextOf(runtime, facade, resolved)))
+  exec = resolve.normalizeExecution(await runtime.registry.before(exec, execContextOf(runtime, facade, resolved)))
   if (identityOf(exec) !== before) {
-    resolved = await resolveExecution(runtime, facade, exec)
+    resolved = await resolve.resolveExecution(facade, exec)
   }
 
   await validateExecution(runtime, facade, exec, resolved)
@@ -109,24 +112,27 @@ export const executeTransition = async (
   }
 
   const cardId = resolved.create
-    ? store.newId?.() ?? runtime.options.ids?.() ?? uuid()
+    ? store.newId?.() ?? runtime.options.ids?.() ?? idHelper.uuid()
     : resolved.card!.id!
 
-  exec = await assignCode(exec, resolved, scope, runtime.registry, execContextOf(runtime, facade, resolved))
+  exec = await codeUtils.assignCode(exec, resolved, scope, runtime.registry, execContextOf(runtime, facade, resolved))
 
-  const { set, empty } = changeSetOf(exec, resolved, service.schemas, at)
+  const { set, empty } = changesUtils.changeSetOf(exec, resolved, resolved.schemas, at)
   if (empty) {
     return await currentReceipt(store, resolved, scope.entityId, opts)
   }
 
+  const preview = changesUtils.transitionOf({ exec, resolved, scope, set, cardId, seq: (resolved.card?.seq ?? 0) + 1, at, project: resolve.projectFor(resolved, exec, cardId) })
+  await store.validateProjection?.(resolved.card ?? null, applyHelper.applyTransition(resolved.card, preview), preview)
+
   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({
+  const transition = changesUtils.transitionOf({
     exec, resolved, scope, set, cardId, seq, at,
-    project: projectFor(resolved, exec, cardId),
+    project: resolve.projectFor(resolved, exec, cardId),
   })
 
   let appended: Transition

package/src/facade.ts

@@ -1,14 +1,27 @@
-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 { cardHelper, modelOf, PlanningResourceKind, PlanningUnsupported, queryHelper, specificationHelper, WorkcardKind, WorkcardNotFound, type CommitEvent, type CommitSource, type PlanningFacade, type PlanningScope, type Relationship, type Specification, type Transition, type Workcard, type WorkcardModel, type WorkcardQuery } from '@owlmeans/planning'
+import { recordQueryHelper } from '@owlmeans/resource'
+import type { Criteria } from '@owlmeans/resource'
+import { makeResourceFacade } from './resources.js'
+import { makeDefinitions } from './definitions.js'
 import { executeTransition } from './executor.js'
-import type { PlanningRuntime } from './service.js'
+import type { PlanningRuntime } from './types.js'
+import { makePlanningHierarchy } from './hierarchy.js'
 import type { CommitHub } from './store/types.js'
 
+/**
+ * The criteria a scope narrowed to `projects` adds to every card list, count and summary: the
+ * projects themselves, every card whose `parents` name one of them, and the specifications whose
+ * parent card is one of `through` — the cards of those projects a specification is seen through,
+ * exactly as a single read sees it (a specification's `parents` hold only its own card).
+ */
+export const projectCriteriaOf = (projects: readonly string[], through: readonly string[] = []): Criteria<Workcard> => ({
+  $or: [
+    { id: { $in: [...projects] } },
+    { parents: { $overlaps: [...projects] } },
+    ...(through.length > 0 ? [{ kind: WorkcardKind.Specification, parent: { $in: [...through] } }] : []),
+  ],
+}) as Criteria<Workcard>
+
 /**
  * The scoped facade over the service's stores.
  *
@@ -16,13 +29,44 @@ import type { CommitHub } from './store/types.js'
  * 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.
+ *
+ * A scope naming `projects` sees those projects, the cards whose `parents` name one of them, and a
+ * specification whose parent card is one of those (a card's specification through its card);
+ * everything else reads as absent. Lists, counts and summaries are narrowed by an AND'd criteria
+ * that admits the same cards a single read does — the parent cards a specification is seen through
+ * are resolved once per call ({@link projectCriteriaOf}) — and commit events and transitions
+ * outside the set are dropped or refused.
+ *
+ * `definitions` is present when the default store holds data-defined schemas; a model is then
+ * built over the registry of the card's own project.
  */
 export const makeStoreFacade = (runtime: PlanningRuntime, scope: PlanningScope): PlanningFacade => {
   const entityId = scope.entityId
+  const projects = scope.projects != null ? [...new Set(scope.projects)] : undefined
   const reader = () => runtime.reader()
   const mine = <T extends { entityId: string }>(record: T | null | undefined): T | null =>
     record != null && record.entityId === entityId ? record : null
 
+  const hierarchy = makePlanningHierarchy(runtime)
+  const visible = async (card: Workcard | null): Promise<Workcard | null> =>
+    card != null && await hierarchy.visible(card, projects) ? card : null
+  const allowedIds = async (): Promise<string[]> => {
+    if (projects == null) return []
+    const result = new Set<string>()
+    for (const project of projects) {
+      const root = mine(await reader().cards.get(project, entityId))
+      if (root == null) continue
+      result.add(project)
+      for (const card of await hierarchy.descendants(project, entityId)) result.add(card.id!)
+    }
+    return [...result]
+  }
+  const narrow = async (where: Criteria<Workcard>): Promise<Criteria<Workcard>> => projects == null ? where
+    : { ...where, $and: [...(where.$and ?? []), { id: { $in: await allowedIds() } }] }
+  const narrowed = async (query?: WorkcardQuery | null): Promise<Criteria<Workcard>> => await narrow(queryHelper.criteriaOf(query, scope))
+  const projectVisible = (project?: string | null): boolean =>
+    projects == null || (project != null && projects.includes(project))
+
   const commitSource = (): CommitSource => {
     const commits = reader().commits
     if (commits == null) {
@@ -31,28 +75,37 @@ export const makeStoreFacade = (runtime: PlanningRuntime, scope: PlanningScope):
     return commits
   }
 
-  /** The transition is this entity's — its row, or the remembered commit of a purged one. */
+  /** The transition is this entity's (and this scope's) — its row, or the remembered commit of a purged one. */
+  const transitionVisible = async (row: Pick<Transition, 'card' | 'project'>): Promise<boolean> => {
+    if (projects == null) return true
+    const card = mine(await reader().cards.get(row.card, entityId))
+    return card != null ? await hierarchy.visible(card, projects) : projectVisible(row.project)
+  }
   const assertTransition = async (transition: string): Promise<void> => {
     const row = await reader().transitions?.get(transition)
     if (row != null) {
-      if (row.entityId !== entityId) {
+      if (row.entityId !== entityId || !await transitionVisible(row)) {
         throw new WorkcardNotFound(`transition:${transition}`)
       }
       return
     }
     const recalled = (reader().commits as Partial<CommitHub> | undefined)?.recall?.(transition)
-    if (recalled == null || recalled.entityId !== entityId) {
+    if (recalled == null || recalled.entityId !== entityId || !projectVisible(recalled.project)) {
       throw new WorkcardNotFound(`transition:${transition}`)
     }
   }
 
+  /** The project a card resolves its data-defined types in. */
+  const projectFor = async (card: Workcard): Promise<string | undefined> => await hierarchy.project(card)
+
   const facade: PlanningFacade = {
-    scope: Object.freeze({ ...scope }),
+    ...makeResourceFacade(runtime, () => facade),
+    scope: Object.freeze({ ...scope, ...(projects != null ? { projects } : {}) }),
 
     schemas: runtime.service().schemas,
 
     cards: {
-      load: async id => mine(await reader().cards.get(id, entityId)),
+      load: async id => await visible(mine(await reader().cards.get(id, entityId))),
 
       get: async id => {
         const card = await facade.cards.load(id)
@@ -62,36 +115,42 @@ export const makeStoreFacade = (runtime: PlanningRuntime, scope: PlanningScope):
         return card
       },
 
-      list: async query => await reader().cards.list(criteriaOf(query, scope), listOptionsOf(query)),
+      list: async query => await reader().cards.list(await narrowed(query), queryHelper.listOptionsOf(query)),
 
-      count: async query => await reader().cards.count(criteriaOf(query, scope)),
+      count: async query => await reader().cards.count(await narrowed(query)),
 
       summary: async (parents, query) => parents.length === 0
         ? {}
-        : await reader().cards.summary(parents, criteriaOf({ kind: query?.kind, type: query?.type }, scope)),
+        : await reader().cards.summary(parents, await narrow(queryHelper.criteriaOf({ kind: query?.kind, type: query?.type }, scope))),
     },
 
     specifications: {
       current: async (parent, category) => {
+        if (projects != null && await facade.cards.load(parent) == null) {
+          return null
+        }
         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)
+        const listed = await reader().cards.list(queryHelper.specCriteriaOf(parent, { category }, scope) as never, { size: 0 })
+        return specificationHelper.currentSpecification(listed.items, category)
       },
 
       list: async (parent, query) => {
+        if (projects != null && await facade.cards.load(parent) == null) {
+          return { items: [], total: 0 }
+        }
         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
+        return await reader().cards.list(queryHelper.specCriteriaOf(parent, query, scope) as never, queryHelper.listOptionsOf(query) as never) as never
       },
 
       get: async id => {
         const card = await facade.cards.load(id)
-        if (card == null || !isSpecification(card)) {
+        if (card == null || !cardHelper.isSpecification(card)) {
           throw new WorkcardNotFound(id)
         }
         return card as Specification
@@ -110,16 +169,44 @@ export const makeStoreFacade = (runtime: PlanningRuntime, scope: PlanningScope):
     relationships: {
       list: async query => {
         const links = reader().links
-        return links == null
-          ? { items: [], total: 0 }
-          : await links.list(linkWhereOf(query, scope), listOptionsOf(query))
+        if (links == null) {
+          return { items: [], total: 0 }
+        }
+        const where = queryHelper.linkWhereOf(query, scope)
+        // Inverse names are views over the canonical edge, never separately stored links.
+        const stored = await links.list(query?.type != null ? { entityId, id: where.id, project: where.project } : where, { size: 0 })
+        const names = query?.type == null ? undefined : Array.isArray(query.type) ? query.type : [query.type]
+        const presented: Relationship[] = []
+        for (const link of stored.items) {
+          if (names == null || names.includes(link.type)) presented.push(link)
+          if (names == null || (link.fromKind ?? PlanningResourceKind.Workcard) !== PlanningResourceKind.Workcard) continue
+          const source = await reader().cards.get(link.from, entityId)
+          if (source == null) continue
+          const rules = (await runtime.schemasFor(entityId, await hierarchy.project(source))).type(source.type).relationships ?? []
+          for (const rule of rules) if (rule.name === link.type && rule.inverse != null && names.includes(rule.inverse)) {
+            presented.push({ ...link, type: rule.inverse, from: link.to, to: link.from,
+              fromKind: link.toKind ?? PlanningResourceKind.Workcard, toKind: link.fromKind ?? PlanningResourceKind.Workcard })
+          }
+        }
+        const items: Relationship[] = []
+        for (const link of presented) {
+          if (projects == null) { items.push(link); continue }
+          const endpoints: string[] = []
+          if ((link.fromKind ?? PlanningResourceKind.Workcard) === PlanningResourceKind.Workcard) endpoints.push(link.from)
+          if ((link.toKind ?? PlanningResourceKind.Workcard) === PlanningResourceKind.Workcard) endpoints.push(link.to)
+          if (endpoints.length === 0) continue
+          let admitted = true
+          for (const id of endpoints) if (await facade.cards.load(id) == null) { admitted = false; break }
+          if (admitted) items.push(link)
+        }
+        return recordQueryHelper.applyQuery(items, where as Criteria<Relationship>, queryHelper.listOptionsOf(query))
       },
     },
 
     transitions: {
       get: async id => {
         const transition = mine(await reader().transitions?.get(id))
-        if (transition == null) {
+        if (transition == null || !await transitionVisible(transition)) {
           throw new WorkcardNotFound(`transition:${id}`)
         }
         return transition
@@ -127,9 +214,13 @@ export const makeStoreFacade = (runtime: PlanningRuntime, scope: PlanningScope):
 
       list: async query => {
         const transitions = reader().transitions
-        return transitions == null
-          ? { items: [], total: 0 }
-          : await transitions.list(transitionWhereOf(query, scope), listOptionsOf(query))
+        if (transitions == null) {
+          return { items: [], total: 0 }
+        }
+        const listed = await transitions.list(queryHelper.transitionWhereOf(query, scope), { size: 0 })
+        const items: Transition[] = []
+        for (const transition of listed.items) if (await transitionVisible(transition)) items.push(transition)
+        return recordQueryHelper.applyQuery(items, undefined, queryHelper.listOptionsOf(query))
       },
     },
 
@@ -139,7 +230,10 @@ export const makeStoreFacade = (runtime: PlanningRuntime, scope: PlanningScope):
         return await commitSource().status(transition)
       },
 
-      subscribe: (listener, filter) => commitSource().subscribe(listener, { ...filter, entityId }),
+      subscribe: (listener, filter) => commitSource().subscribe(projects == null
+        ? listener
+        : async (event: CommitEvent) => await transitionVisible(event) ? await listener(event) : undefined,
+      { ...filter, entityId }),
 
       wait: async (transition, opts) => {
         await assertTransition(transition)
@@ -154,9 +248,18 @@ export const makeStoreFacade = (runtime: PlanningRuntime, scope: PlanningScope):
       if (record.entityId !== entityId) {
         throw new WorkcardNotFound(record.id ?? WorkcardKind.Card)
       }
-      return modelOf<T>(record, facade)
+      if (runtime.schemaStore() == null) {
+        return modelOf<T>(record, facade)
+      }
+      // A data-defined type answers from the registry of the card's own project.
+      const schemas = await runtime.schemasFor(entityId, await projectFor(record))
+      return modelOf<T>(record, { ...facade, schemas })
     },
   }
 
+  if (runtime.schemaStore() != null) {
+    facade.definitions = makeDefinitions(runtime, facade)
+  }
+
   return facade
 }

package/src/helper.ts

@@ -1,23 +1,29 @@
+import { servePlanningResources } from './actions/resources.js'
 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,
+  defineSchemas, 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'
+import { planningHandlerOf } from './utils/handler.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.
+ * protocol, the base included (and `schema.define` when the tree declares it). 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) => [
+  ...servePlanningResources(protocols, opts),
   bind(protocols.base),
   bind(protocols.schema.list, listSchemas(protocols.schema.list, opts)),
+  ...(protocols.schema.define != null
+    ? [bind(protocols.schema.define, defineSchemas(protocols.schema.define, 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)),
@@ -32,13 +38,8 @@ export const servePlanningEntrypoints = (protocols: PlanningProtocols, opts?: Pl
   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
- */
+/** @deprecated compat:factory-refactor — use `planningHandlerOf(ctx).planningFor(…)` */
 export const planningFor = (
   ctx: BasicContext<BasicConfig>, req: AbstractRequest, extra?: Partial<PlanningScope>,
   opts?: Pick<PlanningHandlerOptions, 'service'>
-): PlanningFacade => planningServiceOf(ctx, opts).for(scopeOf(req, extra))
+): PlanningFacade => planningHandlerOf(ctx).planningFor(req, extra, opts)

package/src/hierarchy/types.ts

@@ -0,0 +1,20 @@
+import type { Workcard } from '@owlmeans/planning'
+
+export interface PlanningHierarchy {
+  ancestors: (card: Pick<Workcard, 'entityId' | 'parent' | 'parents'>) => Promise<Workcard[]>
+  project: (card: Pick<Workcard, 'entityId' | 'kind' | 'id' | 'parent'>) => Promise<string | undefined>
+  projects: (card: Workcard) => Promise<string[]>
+  visible: (card: Workcard, projects?: readonly string[]) => Promise<boolean>
+  descendants: (id: string, entityId: string) => Promise<Workcard[]>
+  /**
+   * A card's own documents: the specifications whose primary parent is the card, and theirs in
+   * turn. They never block the card's delete — its fold removes them with it.
+   */
+  documents: (id: string, entityId: string) => Promise<Workcard[]>
+  /**
+   * The card's own shape against its schemas — or, `deleting`, whether it may go: a project always
+   * (its delete purges what is under it); any other card only when everything under it is one of
+   * its own `documents` (`hierarchy:parent-in-use` otherwise).
+   */
+  validate: (card: Workcard, deleting?: boolean) => Promise<void>
+}

package/src/hierarchy.ts

@@ -0,0 +1,113 @@
+import {
+  CardTypeNotAllowed, FieldsInvalid, ParentNotFound, PlanningError, PlanningSchemaKind, SchemaOrigin,
+  WorkcardKind, type Workcard, type PlanningSchemaRegistry, type ProjectTypeSchema, type ScopedSchemaRegistry,
+} from '@owlmeans/planning'
+import type { PlanningRuntime } from './types.js'
+import type { PlanningHierarchy } from './hierarchy/types.js'
+
+/** One recursive resolver for schema inheritance, project authorization and hierarchy constraints. */
+export const makePlanningHierarchy = (runtime: PlanningRuntime): PlanningHierarchy => {
+  const cards = () => runtime.reader().cards
+  const ancestors: PlanningHierarchy['ancestors'] = async card => {
+    const visited = new Set<string>()
+    const result: Workcard[] = []
+    const visit = async (id: string, path: Set<string>): Promise<void> => {
+      if (path.has(id)) throw new PlanningError(`hierarchy:cycle:${id}`)
+      if (visited.has(id)) return
+      const parent = await cards().get(id, card.entityId)
+      if (parent == null || parent.entityId !== card.entityId) throw new ParentNotFound(id)
+      const next = new Set([...path, id])
+      for (const reference of parent.parents) await visit(reference, next)
+      visited.add(id)
+      result.push(parent)
+    }
+    for (const id of card.parents) await visit(id, new Set())
+    return result
+  }
+  const project: PlanningHierarchy['project'] = async card => {
+    if (card.kind === WorkcardKind.Project) return card.id
+    const visited = new Set<string>()
+    let parent = card.parent
+    while (parent != null) {
+      if (visited.has(parent)) throw new PlanningError(`hierarchy:cycle:${parent}`)
+      visited.add(parent)
+      const found = await cards().get(parent, card.entityId)
+      if (found == null) throw new ParentNotFound(parent)
+      if (found.kind === WorkcardKind.Project) return found.id
+      parent = found.parent
+    }
+    return undefined
+  }
+  const descendants: PlanningHierarchy['descendants'] = async (id, entityId) => {
+    const found = new Map<string, Workcard>()
+    let frontier = [id]
+    while (frontier.length > 0) {
+      const result = await cards().list({ entityId, parents: { $overlaps: frontier }, kind: [WorkcardKind.Card, WorkcardKind.Project, WorkcardKind.Specification] } as never, { size: 0 })
+      frontier = []
+      for (const card of result.items) if (card.id !== id && !found.has(card.id!)) { found.set(card.id!, card); frontier.push(card.id!) }
+    }
+    return [...found.values()]
+  }
+  /** The specifications among `below` whose primary parent is `id` or one already owned. */
+  const ownedOf = (id: string, below: Workcard[]): Workcard[] => {
+    const owners = new Set([id])
+    const owned: Workcard[] = []
+    let grown = true
+    while (grown) {
+      grown = false
+      for (const card of below) {
+        if (card.kind === WorkcardKind.Specification && card.parent != null && owners.has(card.parent) && !owners.has(card.id!)) {
+          owners.add(card.id!)
+          owned.push(card)
+          grown = true
+        }
+      }
+    }
+    return owned
+  }
+  const assertPair = (parent: Workcard, card: Workcard, schemas: PlanningSchemaRegistry): void => {
+    if (card.kind === WorkcardKind.Specification) return
+    const childType = schemas.type(card.type)
+    if (childType.parents?.types != null && !childType.parents.types.includes(parent.type)) throw new CardTypeNotAllowed(`${card.type}:parent:${parent.type}`)
+    const parentType = schemas.type(parent.type)
+    if (parentType.children != null) {
+      if (!parentType.children.types.includes(card.type)) throw new CardTypeNotAllowed(`${parent.type}:child:${card.type}`)
+      return
+    }
+    if (parent.kind !== WorkcardKind.Project) throw new CardTypeNotAllowed(`${parent.type}:child:${card.type}`)
+    const container = parentType as ProjectTypeSchema
+    const allowed = card.kind === WorkcardKind.Project ? container.projectTypes ?? [] : container.cardTypes
+    const origin = (schemas as Partial<ScopedSchemaRegistry>).originOf?.(PlanningSchemaKind.Type, card.type)
+    if (!allowed.includes(card.type) && !(card.kind === WorkcardKind.Card && container.scopedCardTypes && (origin === SchemaOrigin.Project || origin === SchemaOrigin.Entity))) throw new CardTypeNotAllowed(`${parent.type}:${card.type}`)
+  }
+  const hierarchy: PlanningHierarchy = {
+    ancestors,
+    project,
+    descendants,
+    documents: async (id, entityId) => ownedOf(id, await descendants(id, entityId)),
+    projects: async card => [...new Set([...(card.kind === WorkcardKind.Project ? [card.id!] : []), ...(await ancestors(card)).filter(parent => parent.kind === WorkcardKind.Project).map(parent => parent.id!)])],
+    visible: async (card, projects) => projects == null || (await hierarchy.projects(card)).some(id => projects.includes(id)),
+    validate: async (card, deleting = false) => {
+      if (deleting) {
+        if (card.kind === WorkcardKind.Project) return
+        // The card's own documents go with it; anything else under it keeps it alive.
+        const below = await descendants(card.id!, card.entityId)
+        if (below.length > ownedOf(card.id!, below).length) throw new PlanningError(`hierarchy:parent-in-use:${card.id}`)
+        return
+      }
+      const schemas = await runtime.schemasFor(card.entityId, await project(card))
+      const type = schemas.type(card.type)
+      if (type.parents?.required && card.parent == null) throw new ParentNotFound(`required:${card.type}`)
+      if (card.parent != null && !card.parents.includes(card.parent)) throw new FieldsInvalid('hierarchy:primary-membership')
+      const parents = await ancestors(card)
+      if (parents.some(parent => parent.id === card.id)) throw new PlanningError(`hierarchy:cycle:${card.id}`)
+      for (const id of card.parents) {
+        const parent = parents.find(parent => parent.id === id)!
+        assertPair(parent, card, await runtime.schemasFor(card.entityId, await project(parent)))
+      }
+      if (card.parent != null) card.parentType = parents.find(parent => parent.id === card.parent)!.type
+      else delete card.parentType
+    },
+  }
+  return hierarchy
+}

package/src/index.ts

@@ -5,6 +5,7 @@ export * from './consts.js'
 export * from './service.js'
 export * from './registry.js'
 export * from './facade.js'
+export * from './definitions.js'
 export * from './executor.js'
 export * from './helper.js'
 export * from './projection.js'

package/src/invariants/types.ts

@@ -0,0 +1,6 @@
+import type { Workcard, Transition } from '@owlmeans/planning'
+
+export interface PlanningInvariants {
+  validate: (before: Workcard | null, after: Workcard | null, transition: Transition) => Promise<void>
+  references: (after: Workcard, transition: Transition) => Promise<void>
+}