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

package/src/invariants.ts

@@ -0,0 +1,106 @@
+import {
+  FieldsInvalid, PlanningResourceKind, PLANNING_ASSIGNEE, PLANNING_REPORTER, ProjectMode,
+  RelationshipRefused, TransitionAction, validateHelper, WorkcardKind, type RelationshipDraft, type Workcard,
+} from '@owlmeans/planning'
+import { makePlanningHierarchy } from './hierarchy.js'
+import type { PlanningRuntime } from './types.js'
+import type { PlanningInvariants } from './invariants/types.js'
+
+/** Checks projected state again at persistence time, including queued writes whose parents moved. */
+export const makePlanningInvariants = (runtime: PlanningRuntime): PlanningInvariants => {
+  const registryFor = async (card: Workcard) => await runtime.schemasFor(card.entityId, await makePlanningHierarchy(runtime).project(card))
+  const referencesOf = async (card: Workcard): Promise<RelationshipDraft[]> => {
+    const schemas = await registryFor(card)
+    const refs: RelationshipDraft[] = []
+    if (card.reporter != null) refs.push({ type: PLANNING_REPORTER, to: card.reporter, toKind: PlanningResourceKind.Assignee })
+    if (card.assignee != null) refs.push({ type: PLANNING_ASSIGNEE, to: card.assignee, toKind: PlanningResourceKind.Assignee })
+    for (const rule of schemas.type(card.type).relationships ?? []) {
+      if (rule.field == null) continue
+      const value = card.fields[rule.field]
+      if (value == null) continue
+      if (rule.multiple !== true && typeof value !== 'string') throw new FieldsInvalid(`relationship:field:${rule.field}:single`)
+      if (rule.multiple === true && (!Array.isArray(value) || value.some(id => typeof id !== 'string'))) throw new FieldsInvalid(`relationship:field:${rule.field}:multiple`)
+      for (const id of Array.isArray(value) ? value : [value]) refs.push({ type: rule.name, to: id as string, toKind: rule.toKind ?? PlanningResourceKind.Workcard })
+    }
+    return refs
+  }
+  const assertReference = async (card: Workcard, ref: RelationshipDraft, existing: boolean): Promise<void> => {
+    const reader = runtime.reader()
+    const kind = ref.toKind ?? PlanningResourceKind.Workcard
+    const target = kind === PlanningResourceKind.Assignee ? await reader.assignees?.get(ref.to, card.entityId)
+      : kind === PlanningResourceKind.Team ? await reader.teams?.get(ref.to, card.entityId)
+        : kind === PlanningResourceKind.Workcard ? await reader.cards.get(ref.to, card.entityId) : null
+    if (target == null || target.entityId !== card.entityId) throw new RelationshipRefused(`reference:${kind}:${ref.to}`)
+    const rule = (await registryFor(card)).type(card.type).relationships?.find(rule => rule.name === ref.type)
+    if (rule?.from != null && !rule.from.includes(card.type)) throw new RelationshipRefused(`from-type:${ref.type}:${card.type}`)
+    if (rule?.to != null && !rule.to.includes('type' in target ? String(target.type) : '')) throw new RelationshipRefused(`to-type:${ref.type}`)
+    if (kind === PlanningResourceKind.Assignee && !existing && 'retired' in target && target.retired) throw new RelationshipRefused(`assignee:retired:${ref.to}`)
+  }
+  const invariants: PlanningInvariants = {
+    validate: async (before, after, transition) => {
+      const hierarchy = makePlanningHierarchy(runtime)
+      if (after == null) {
+        if (before != null) {
+          await hierarchy.validate(before, true)
+          // What the delete's fold removes: a project's whole subtree, any other card's own documents.
+          const removed = before.kind === WorkcardKind.Project ? await hierarchy.descendants(before.id!, before.entityId) : await hierarchy.documents(before.id!, before.entityId)
+          const doomed = new Set([before.id!, ...removed.map(card => card.id!)])
+          const incoming = await runtime.reader().links?.list({ entityId: before.entityId, to: [...doomed], toKind: PlanningResourceKind.Workcard }, { size: 0 })
+          for (const edge of incoming?.items ?? []) {
+            if (doomed.has(edge.from) || (edge.fromKind ?? PlanningResourceKind.Workcard) !== PlanningResourceKind.Workcard) continue
+            const owner = await runtime.reader().cards.get(edge.from, before.entityId)
+            if (owner != null && (await registryFor(owner)).type(owner.type).relationships?.some(rule => rule.name === edge.type && rule.field != null)) {
+              throw new RelationshipRefused(`reference-in-use:${edge.to}:${edge.from}`)
+            }
+          }
+        }
+        return
+      }
+      await hierarchy.validate(after)
+      const schemas = await registryFor(after)
+      validateHelper.validateCard(after, schemas)
+      if (after.kind !== WorkcardKind.Project && after.mode != null) throw new FieldsInvalid('mode:project-only')
+      if (after.kind === WorkcardKind.Project && after.mode == null) after.mode = ProjectMode.Opened
+      const previous = before == null ? [] : await referencesOf(before)
+      for (const ref of await referencesOf(after)) await assertReference(after, ref, previous.some(entry => entry.type === ref.type && entry.to === ref.to && entry.toKind === ref.toKind))
+      const counted = new Map<string, Set<string>>()
+      for (const link of transition.links ?? (transition.link != null ? [transition.link] : [])) {
+        const rule = schemas.type(after.type).relationships?.find(rule => rule.name === link.type)
+        if (rule == null) throw new RelationshipRefused(`unknown:${link.type}`)
+        if ((link.toKind ?? PlanningResourceKind.Workcard) !== (rule.toKind ?? PlanningResourceKind.Workcard) || (link.fromKind ?? PlanningResourceKind.Workcard) !== PlanningResourceKind.Workcard) throw new RelationshipRefused(`kind:${link.type}`)
+        if (link.from != null && link.from !== after.id) throw new RelationshipRefused(`from:${link.from}`)
+        if (rule?.field != null) throw new RelationshipRefused(`field-authoritative:${rule.field}`)
+        if (transition.action !== TransitionAction.Unlink) {
+          await assertReference(after, link, false)
+          if (rule.single) {
+            const destinations = counted.get(rule.name) ?? new Set<string>()
+            destinations.add(link.to)
+            for (const edge of (await runtime.reader().links?.list({ entityId: after.entityId, from: after.id, type: rule.name }, { size: 0 }))?.items ?? []) destinations.add(edge.to)
+            counted.set(rule.name, destinations)
+            if (destinations.size > 1) throw new RelationshipRefused(`single:${rule.name}`)
+          }
+        }
+      }
+      if (before != null && (before.parent !== after.parent || JSON.stringify(before.parents) !== JSON.stringify(after.parents))) {
+        const reader = runtime.reader()
+        const alternate: PlanningRuntime = { ...runtime, reader: () => ({ ...reader, cards: { ...reader.cards, get: async (id, entityId) => id === after.id && entityId === after.entityId ? after : await reader.cards.get(id, entityId) } }) }
+        const hypothetical = makePlanningHierarchy(alternate)
+        for (const child of await hierarchy.descendants(after.id!, after.entityId)) {
+          await hypothetical.validate(child)
+          await makePlanningInvariants(alternate).validate(child, child, { ...transition, links: undefined, link: undefined, action: TransitionAction.Update })
+        }
+      }
+    },
+    references: async (after, transition) => {
+      const links = runtime.service().store(after.type).links
+      if (links == null) return
+      const schemas = await registryFor(after)
+      const types = [PLANNING_REPORTER, PLANNING_ASSIGNEE, ...(schemas.type(after.type).relationships ?? []).filter(rule => rule.field != null).map(rule => rule.name)]
+      const wanted = await referencesOf(after)
+      const stored = await links.list({ entityId: after.entityId, from: after.id, type: types }, { size: 0 })
+      for (const link of stored.items) if (!wanted.some(ref => ref.type === link.type && ref.to === link.to && (ref.toKind ?? PlanningResourceKind.Workcard) === (link.toKind ?? PlanningResourceKind.Workcard))) await links.drop({ entityId: after.entityId, id: link.id })
+      for (const ref of wanted) await links.put({ ...ref, from: after.id!, fromKind: PlanningResourceKind.Workcard, entityId: after.entityId, createdAt: transition.at, transition: transition.id, project: transition.project })
+    },
+  }
+  return invariants
+}

package/src/projection.ts

@@ -1,22 +1,12 @@
 import type { BasicConfig, BasicContext } from '@owlmeans/context'
-import { PLANNING_SERVICE } from '@owlmeans/planning'
-import type { CommitEvent, PlanningService, PlanningStore } from '@owlmeans/planning'
-import { PLANNING_PROJECT_JOB, PLANNING_PROJECTION_QUEUE } from './queue/index.js'
-import type { ProjectionRequest } from './queue/index.js'
+import { PLANNING_SERVICE, type PlanningService, type PlanningStore } from '@owlmeans/planning'
+import { PLANNING_PROJECT_JOB, PLANNING_PROJECTION_QUEUE } from './queue/consts.js'
+import type { ProjectionRequest } from './queue/types.js'
 import type { JobProcessor, QueueHooks } from '@owlmeans/queue'
-import { failPending, foldPending } from './store/fold.js'
-import type { PlanningHostService } from './types.js'
+import { foldHelper } from './store/fold.js'
+import type { PlanningHostService, ProjectionOptions } from './types.js'
 import type { CommitHub, FoldResult } from './store/types.js'
 
-export interface ProjectionOptions {
-  /** The planning service alias. */
-  service?: string
-  /** The store the queue folds — the service's default store when omitted. */
-  store?: (service: PlanningService) => PlanningStore
-  /** Where events go — the store's commit hub `publish` when it has one. */
-  publish?: (event: CommitEvent) => Promise<void>
-}
-
 const serviceOf = (ctx: BasicContext<BasicConfig>, opts?: ProjectionOptions): PlanningService =>
   ctx.service<PlanningHostService>(opts?.service ?? PLANNING_SERVICE)
 
@@ -40,7 +30,7 @@ export const makeProjectionProcessor = (
   const store = storeOf(service, opts)
   const publish = publisherOf(store, opts)
 
-  return await foldPending(store, job.data.cardId, job.data.entityId, {
+  return await foldHelper.foldPending(store, job.data.cardId, job.data.entityId, {
     touch: job.touch,
     onCommitted: async event => { await service.committed(event) },
     ...(publish != null ? { publish } : {}),
@@ -52,7 +42,7 @@ export const makeProjectionProcessor = (
  * failed event is published — otherwise `execute({ wait: true })` and `commits.wait` hang to their
  * timeout. Merge it into the queue driver's hooks.
  */
-export const planningQueueHooks = (ctx: BasicContext<BasicConfig>, opts?: ProjectionOptions): QueueHooks => ({
+export const makePlanningQueueHooks = (ctx: BasicContext<BasicConfig>, opts?: ProjectionOptions): QueueHooks => ({
   onJobDead: async (job, reason) => {
     if (job.queue !== PLANNING_PROJECTION_QUEUE || job.name !== PLANNING_PROJECT_JOB) {
       return
@@ -60,6 +50,10 @@ export const planningQueueHooks = (ctx: BasicContext<BasicConfig>, opts?: Projec
     const request = job.data as ProjectionRequest
     const store = storeOf(serviceOf(ctx, opts), opts)
     const publish = publisherOf(store, opts)
-    await failPending(store, request.cardId, request.entityId, reason, publish != null ? { publish } : {})
+    await foldHelper.failPending(store, request.cardId, request.entityId, reason, publish != null ? { publish } : {})
   },
 })
+
+/** @deprecated compat:factory-refactor — use `makePlanningQueueHooks(…)` */
+export const planningQueueHooks = (ctx: BasicContext<BasicConfig>, opts?: ProjectionOptions): QueueHooks =>
+  makePlanningQueueHooks(ctx, opts)

package/src/queue/consts.ts

@@ -0,0 +1,5 @@
+/** The server-side queue used to project planning transitions. */
+export const PLANNING_PROJECTION_QUEUE = 'planning-projection'
+
+/** The processor name accepted by the planning projection queue. */
+export const PLANNING_PROJECT_JOB = 'planning:project'

package/src/queue/declare.ts

@@ -0,0 +1,7 @@
+import { declareQueue, type Config } from '@owlmeans/queue'
+import { PLANNING_PROJECT_JOB, PLANNING_PROJECTION_QUEUE } from './consts.js'
+import type { PlanningQueueOptions } from './types.js'
+
+/** Declare the shared projection address; each process separately chooses whether to listen. */
+export const declarePlanningQueue = <C extends Config>(cfg: C, opts?: PlanningQueueOptions): C =>
+  declareQueue(cfg, PLANNING_PROJECTION_QUEUE, [PLANNING_PROJECT_JOB], opts)

package/src/queue/index.ts

@@ -1,25 +1,3 @@
-import { declareQueue } from '@owlmeans/queue'
-import type { Config, JobOptions, QueueWorkerOptions } from '@owlmeans/queue'
-
-/** The server-side queue used to project planning transitions. */
-export const PLANNING_PROJECTION_QUEUE = 'planning-projection'
-
-/** The processor name accepted by the planning projection queue. */
-export const PLANNING_PROJECT_JOB = 'planning:project'
-
-/** What one projection job folds. */
-export interface ProjectionRequest {
-  cardId: string
-  entityId: string
-  /** The transition that requested projection; it is a hint rather than a fold bound. */
-  transition?: string
-}
-
-export interface PlanningQueueOptions {
-  worker?: QueueWorkerOptions
-  defaults?: JobOptions
-}
-
-/** Declare the shared projection address; each process separately chooses whether to listen. */
-export const declarePlanningQueue = <C extends Config>(cfg: C, opts?: PlanningQueueOptions): C =>
-  declareQueue(cfg, PLANNING_PROJECTION_QUEUE, [PLANNING_PROJECT_JOB], opts)
+export { declarePlanningQueue } from './declare.js'
+export { PLANNING_PROJECTION_QUEUE, PLANNING_PROJECT_JOB } from './consts.js'
+export type { PlanningQueueOptions, ProjectionRequest } from './types.js'

package/src/queue/types.ts

@@ -0,0 +1,14 @@
+import type { JobOptions, QueueWorkerOptions } from '@owlmeans/queue'
+
+/** What one projection job folds. */
+export interface ProjectionRequest {
+  cardId: string
+  entityId: string
+  /** The transition that requested projection; it is a hint rather than a fold bound. */
+  transition?: string
+}
+
+export interface PlanningQueueOptions {
+  worker?: QueueWorkerOptions
+  defaults?: JobOptions
+}

package/src/registry.ts

@@ -1,34 +1,10 @@
 import type { BasicConfig, BasicContext } from '@owlmeans/context'
 import { ResilientError } from '@owlmeans/error'
-import { DEFAULT_PLUGIN_ORDER, PlanningRefused } from '@owlmeans/planning'
-import type {
-  CommitEvent, PlanningExecContext, PlanningHookContext, PlanningPlugin, PlanningSchemaRegistry,
-  PlanningStore, TransitionExecution, WorkcardDraft,
-} from '@owlmeans/planning'
-import type { StoreRoute } from './store/types.js'
+import { logger } from '@owlmeans/log'
+import { appSchemaHelper, DEFAULT_PLUGIN_ORDER, PlanningRefused, type PlanningPlugin, type PlanningSchemaRegistry, type PlanningStore } from '@owlmeans/planning'
+import type { PluginRegistry } from './types.js'
 
-export interface PluginRegistry {
-  /** Register, or replace the plugin of the same `name`. Its schemas are contributed now. */
-  use: (plugin: PlanningPlugin) => void
-  /** Every plugin, `order` ascending (registration order among equals). */
-  plugins: () => PlanningPlugin[]
-  /** The owning plugins that supply a store, in plugin order, each store resolved once. */
-  routes: (ctx?: BasicContext<BasicConfig>) => StoreRoute[]
-  /** The first owning plugin's store for a type, else `fallback`. */
-  storeFor: (type: string | undefined, fallback: PlanningStore, ctx?: BasicContext<BasicConfig>) => PlanningStore
-  /** The first plugin answering a code wins. */
-  mintCode: (
-    draft: WorkcardDraft, taken: (code: string) => Promise<boolean>, contextOf: (plugin: PlanningPlugin) => PlanningExecContext
-  ) => Promise<string | undefined>
-  /** The `before` chain; answers the execution the chain left. */
-  before: (
-    exec: TransitionExecution, contextOf: (plugin: PlanningPlugin) => PlanningExecContext
-  ) => Promise<TransitionExecution>
-  /** The `after` chain; a failing hook is logged and the chain goes on. */
-  after: (event: CommitEvent, contextOf: (plugin: PlanningPlugin) => PlanningHookContext) => Promise<void>
-  /** Bumps on every `use` — what a cached composite store is keyed by. */
-  version: () => number
-}
+const log = logger('planning')
 
 const messageOf = (error: unknown): string => error instanceof Error ? error.message : `${error}`
 
@@ -37,21 +13,26 @@ const messageOf = (error: unknown): string => error instanceof Error ? error.mes
  *
  * Ordering is `order ?? DEFAULT_PLUGIN_ORDER` ascending, lower first; a plugin registered under a
  * name already present replaces it in place. A store factory is resolved once per plugin object and
- * handed to `onStore` (the service binds its `committed` there).
+ * handed to `onStore` (the service binds its `committed` there). The application's declarations the
+ * registry started with (the service's `schemas.app`) are the first source every `use` merges the
+ * plugins' `schemas.app` over, in plugin order.
  */
 export const makePluginRegistry = (
   schemas: PlanningSchemaRegistry, onStore?: (store: PlanningStore) => void
 ): PluginRegistry => {
   const registered: PlanningPlugin[] = []
   const stores = new WeakMap<PlanningPlugin, PlanningStore>()
+  const base = schemas.app()
   let version = 0
 
-  const ordered = (): PlanningPlugin[] => registered
+  const sorted = (plugins: PlanningPlugin[]): PlanningPlugin[] => plugins
     .map((plugin, index) => ({ plugin, index }))
     .sort((left, right) => (left.plugin.order ?? DEFAULT_PLUGIN_ORDER) - (right.plugin.order ?? DEFAULT_PLUGIN_ORDER)
       || left.index - right.index)
     .map(entry => entry.plugin)
 
+  const ordered = (): PlanningPlugin[] => sorted(registered)
+
   const storeOf = (plugin: PlanningPlugin, ctx?: BasicContext<BasicConfig>): PlanningStore | undefined => {
     if (plugin.store == null) {
       return undefined
@@ -68,11 +49,12 @@ export const makePluginRegistry = (
   const registry: PluginRegistry = {
     use: plugin => {
       const at = registered.findIndex(entry => entry.name === plugin.name)
-      if (at < 0) {
-        registered.push(plugin)
-      } else {
-        registered[at] = plugin
-      }
+      const next = at < 0 ? [...registered, plugin] : registered.map((entry, index) => index === at ? plugin : entry)
+      // Merged before anything changes: a malformed declaration leaves the registry as it was.
+      const app = appSchemaHelper.merge([base, ...sorted(next).map(entry => entry.schemas?.app)])
+      registered.splice(0, registered.length, ...next)
+      schemas.registerApp(app)
+      plugin.schemas?.assigneeTypes?.forEach(schemas.registerAssigneeType)
       plugin.schemas?.flows?.forEach(schemas.registerFlow)
       plugin.schemas?.types?.forEach(schemas.registerType)
       version++
@@ -131,7 +113,7 @@ export const makePluginRegistry = (
         try {
           await plugin.after(event, contextOf(plugin))
         } catch (error) {
-          console.error(`planning: after hook of ${plugin.name} failed on ${event.transition}:`, error)
+          log.error('Planning after hook failed', { plugin: plugin.name, transition: event.transition, error })
         }
       }
     },

package/src/resources.ts

@@ -0,0 +1,256 @@
+import {
+  AssigneeKind, AssigneeSchema, CommentSchema, CommentMentionSchema, FieldsInvalid, mentionHelper,
+  PlanningForbidden, PlanningResourceKind, PlanningSchemaKind, PlanningUnsupported, PLANNING_PROJECT_TEAM,
+  PLANNING_TEAM_MEMBER, TeamSchema, WorkcardConflict, WorkcardKind, WorkcardNotFound, validateHelper,
+} from '@owlmeans/planning'
+import type {
+  Assignee, Comment, CommentMention, PlanningFacade, PlanningRecord, PlanningRecordStore,
+  PlanningResourceFacade, RelationshipStore, Team,
+} from '@owlmeans/planning'
+import { recordQueryHelper, type Criteria } from '@owlmeans/resource'
+import type { PlanningRuntime } from './types.js'
+import { makePlanningHierarchy } from './hierarchy.js'
+
+/** Versioned auxiliary resources, using the same scoped schema and relationship ports as cards. */
+export const makeResourceFacade = (runtime: PlanningRuntime, facade: () => PlanningFacade): PlanningResourceFacade => {
+  const scope = () => facade().scope
+  const entityId = () => scope().entityId
+  const now = runtime.options.now ?? (() => new Date().toISOString())
+  const store = () => runtime.service().store()
+  const unit = async <R>(run: () => Promise<R>): Promise<R> => store().unit == null ? await run() : await store().unit!(entityId(), run)
+  const port = <R extends PlanningRecord>(name: 'assignees' | 'teams' | 'comments' | 'mentions'): PlanningRecordStore<R> => {
+    const value = store()[name]
+    if (value == null) throw new PlanningUnsupported(name)
+    return value as unknown as PlanningRecordStore<R>
+  }
+  const links = (): RelationshipStore => {
+    if (store().links == null) throw new PlanningUnsupported('links')
+    return store().links!
+  }
+  const base = (): PlanningRecord => ({ entityId: entityId(), id: store().newId?.() ?? runtime.options.ids?.(), version: 1, createdAt: now() })
+  const get = async <R extends PlanningRecord>(name: 'assignees' | 'teams' | 'comments' | 'mentions', id: string): Promise<R> => {
+    const found = await port<R>(name).get(id, entityId())
+    if (found == null || found.entityId !== entityId()) throw new WorkcardNotFound(`${name}:${id}`)
+    return found
+  }
+  const check = (record: object, schema: object): void => {
+    // The same record validator is used for both built-in durable providers.
+    validateHelper.assertSchema(schema, record)
+    if ('fields' in record) {
+      const invalid = validateHelper.invalidFieldKeys(record.fields)
+      if (invalid.length > 0) throw new FieldsInvalid(`keys:${invalid.join(',')}`)
+    }
+  }
+  const assertVersion = (record: PlanningRecord, version: number): void => {
+    if (record.version !== version) throw new WorkcardConflict(`${record.id}:version:${version}:stored:${record.version}`)
+  }
+  const list = async <R extends PlanningRecord>(name: 'assignees' | 'teams' | 'comments' | 'mentions', query?: object) => {
+    const { page, size, sort, ids, authentication, nickname, ...where } = (query ?? {}) as Record<string, any>
+    return await port<R>(name).list({ ...where, entityId: entityId(),
+      ...(name === 'assignees' && where.retired === false ? { retired: { $ne: true } } : {}),
+      ...(ids != null ? { id: { $in: ids } } : {}),
+      ...(nickname != null ? { nicknameKey: mentionHelper.nicknameKey(nickname) } : {}),
+      ...(authentication != null ? { 'authentication.provider': authentication.provider, 'authentication.externalId': authentication.externalId } : {}),
+    } as Criteria<R>, { page, size, sort })
+  }
+  const validateAssignee = async (record: Assignee, creating: boolean): Promise<void> => {
+    check(record, AssigneeSchema)
+    const schemas = await runtime.schemasFor(entityId())
+    const schema = schemas.assigneeType(record.type)
+    if (creating && 'isRetired' in schemas && (schemas as any).isRetired(PlanningSchemaKind.AssigneeType, record.type)) {
+      throw new FieldsInvalid(`assignee:retired-type:${record.type}`)
+    }
+    if (schema.kind !== record.kind) throw new FieldsInvalid(`assignee:kind:${record.kind}`)
+    if ((schema.authentication === 'required' || (schema.authentication == null && record.kind === AssigneeKind.Human)) && record.authentication == null) {
+      throw new FieldsInvalid('assignee:authentication-required')
+    }
+    const validate = schemas.assigneeValidator(record.type)
+    if (!validate(record.fields)) throw new FieldsInvalid(validateHelper.ajvErrorText(validate.errors))
+    const duplicate = await list<Assignee>('assignees', { nickname: record.nickname, size: 0 })
+    if (duplicate.items.some(row => row.id !== record.id)) throw new WorkcardConflict(`assignee:nickname:${record.nickname}`)
+    if (record.authentication != null) {
+      const identity = await list<Assignee>('assignees', { authentication: record.authentication, size: 0 })
+      if (identity.items.some(row => row.id !== record.id)) throw new WorkcardConflict('assignee:authentication-taken')
+    }
+  }
+  const assertComment = async (record: Comment): Promise<void> => {
+    await facade().cards.get(record.card)
+    await get<Assignee>('assignees', record.author)
+    check(record, CommentSchema)
+    for (const id of mentionHelper.parse(record.body)) await get<Assignee>('assignees', id)
+  }
+  const assertCommentAuthor = (record: Comment): void => {
+    if (scope().assigneeId == null || scope().assigneeId !== record.author) throw new PlanningForbidden('comment:author')
+  }
+  const teamLink = async (team: string, target: string, member: boolean, add: boolean): Promise<void> => {
+    await get<Team>('teams', team)
+    if (member) {
+      const assignee = await get<Assignee>('assignees', target)
+      if (add && assignee.retired) throw new FieldsInvalid(`assignee:retired:${target}`)
+    } else {
+      const project = await facade().cards.get(target)
+      if (project.kind !== WorkcardKind.Project) throw new FieldsInvalid(`team:project:${target}`)
+    }
+    const edge = member
+      ? { from: team, to: target, fromKind: PlanningResourceKind.Team, toKind: PlanningResourceKind.Assignee, type: PLANNING_TEAM_MEMBER }
+      : { from: target, to: team, fromKind: PlanningResourceKind.Workcard, toKind: PlanningResourceKind.Team, type: PLANNING_PROJECT_TEAM, project: target }
+    if (add) await links().put({ ...edge, entityId: entityId(), createdAt: now() })
+    else await links().drop({ ...edge, entityId: entityId() })
+  }
+  const rebuild = async (id: string): Promise<CommentMention[]> => {
+    const comment = await get<Comment>('comments', id)
+    await facade().cards.get(comment.card)
+    const existing = await list<CommentMention>('mentions', { comment: id, size: 0 })
+    const wanted = mentionHelper.parse(comment.body)
+    const rows: CommentMention[] = []
+    for (const assignee of wanted) {
+      await get<Assignee>('assignees', assignee)
+      const previous = existing.items.find(row => row.assignee === assignee)
+      if (previous?.revision === comment.version) { rows.push(previous); continue }
+      const row: CommentMention = { ...(previous ?? base()), comment: id, card: comment.card, assignee,
+        version: (previous?.version ?? 0) + 1, revision: comment.version }
+      check(row, CommentMentionSchema)
+      rows.push(await port<CommentMention>('mentions').put(row))
+    }
+    for (const row of existing.items) if (!wanted.includes(row.assignee)) await port<CommentMention>('mentions').drop(row.id!, entityId(), row.version)
+    return rows
+  }
+  const resources: PlanningResourceFacade = {
+    assignees: {
+      get: async id => await get<Assignee>('assignees', id),
+      load: async id => await port<Assignee>('assignees').get(id, entityId()),
+      list: async query => await list<Assignee>('assignees', query),
+      create: async draft => await unit(async () => {
+        const record: Assignee = { ...base(), ...draft, nickname: draft.nickname.trim(), nicknameKey: mentionHelper.nicknameKey(draft.nickname), fields: draft.fields ?? {} }
+        await validateAssignee(record, true)
+        return await port<Assignee>('assignees').put(record)
+      }),
+      update: async (id, changes, opts) => await unit(async () => {
+        const previous = await get<Assignee>('assignees', id)
+        assertVersion(previous, opts.version)
+        const record = { ...previous, ...changes, nicknameKey: mentionHelper.nicknameKey(changes.nickname ?? previous.nickname), version: previous.version + 1, updatedAt: now() }
+        await validateAssignee(record, record.type !== previous.type)
+        if (record.type !== previous.type) {
+          const incoming = await links().list({ entityId: entityId(), to: id, toKind: PlanningResourceKind.Assignee }, { size: 0 })
+          for (const edge of incoming.items) {
+            if ((edge.fromKind ?? PlanningResourceKind.Workcard) !== PlanningResourceKind.Workcard) continue
+            const card = await runtime.reader().cards.get(edge.from, entityId())
+            if (card == null) continue
+            const schemas = await runtime.schemasFor(entityId(), await makePlanningHierarchy(runtime).project(card))
+            const rule = schemas.type(card.type).relationships?.find(rule => rule.name === edge.type)
+            if (rule?.to != null && !rule.to.includes(record.type)) throw new FieldsInvalid(`assignee:type-in-use:${record.type}`)
+          }
+        }
+        return await port<Assignee>('assignees').put(record)
+      }),
+      retire: async (id, opts) => await unit(async () => {
+        const previous = await get<Assignee>('assignees', id)
+        assertVersion(previous, opts.version)
+        return await port<Assignee>('assignees').put({ ...previous, retired: true, version: previous.version + 1, updatedAt: now() })
+      }),
+    },
+    teams: {
+      get: async id => await get<Team>('teams', id),
+      load: async id => await port<Team>('teams').get(id, entityId()),
+      list: async query => await list<Team>('teams', query),
+      create: async draft => await unit(async () => {
+        const record: Team = { ...base(), ...draft, fields: draft.fields ?? {} }
+        check(record, TeamSchema)
+        return await port<Team>('teams').put(record)
+      }),
+      update: async (id, changes, opts) => await unit(async () => {
+        const previous = await get<Team>('teams', id)
+        assertVersion(previous, opts.version)
+        const record = { ...previous, ...changes, version: previous.version + 1, updatedAt: now() }
+        check(record, TeamSchema)
+        return await port<Team>('teams').put(record)
+      }),
+      remove: async (id, opts) => await unit(async () => {
+        const previous = await get<Team>('teams', id)
+        assertVersion(previous, opts.version)
+        if ((await links().list({ entityId: entityId(), to: id, toKind: PlanningResourceKind.Team }, { size: 1 })).total > 0) throw new WorkcardConflict(`team:in-use:${id}`)
+        await links().drop({ entityId: entityId(), from: id, fromKind: PlanningResourceKind.Team })
+        await port<Team>('teams').drop(id, entityId(), opts.version)
+      }),
+      members: async team => {
+        await get<Team>('teams', team)
+        const edges = await links().list({ entityId: entityId(), from: team, type: PLANNING_TEAM_MEMBER, fromKind: PlanningResourceKind.Team }, { size: 0 })
+        return await Promise.all(edges.items.map(edge => get<Assignee>('assignees', edge.to)))
+      },
+      addMember: async (team, assignee) => await unit(async () => await teamLink(team, assignee, true, true)),
+      removeMember: async (team, assignee) => await unit(async () => await teamLink(team, assignee, true, false)),
+      attach: async (team, project) => await unit(async () => await teamLink(team, project, false, true)),
+      detach: async (team, project) => await unit(async () => await teamLink(team, project, false, false)),
+      projects: async team => {
+        await get<Team>('teams', team)
+        const edges = await links().list({ entityId: entityId(), to: team, type: PLANNING_PROJECT_TEAM, toKind: PlanningResourceKind.Team }, { size: 0 })
+        const visible = await Promise.all(edges.items.map(async edge => await facade().cards.load(edge.from) != null ? edge.from : undefined))
+        return visible.filter((id): id is string => id != null)
+      },
+      assignees: async project => {
+        await facade().cards.get(project)
+        const edges = await links().list({ entityId: entityId(), from: project, type: PLANNING_PROJECT_TEAM, toKind: PlanningResourceKind.Team }, { size: 0 })
+        const members = (await Promise.all(edges.items.map(edge => resources.teams.members(edge.to)))).flat()
+        return [...new Map(members.map(member => [member.id, member])).values()]
+      },
+    },
+    comments: {
+      get: async id => { const row = await get<Comment>('comments', id); await facade().cards.get(row.card); return row },
+      load: async id => { const row = await port<Comment>('comments').get(id, entityId()); return row != null && await facade().cards.load(row.card) != null ? row : null },
+      list: async query => {
+        if (query?.card != null) await facade().cards.get(query.card)
+        const result = await list<Comment>('comments', { ...query, size: 0 })
+        const visible: Comment[] = []
+        for (const row of result.items) if (await facade().cards.load(row.card) != null) visible.push(row)
+        return recordQueryHelper.applyQuery(visible, undefined, query)
+      },
+      create: async draft => await unit(async () => {
+        if (scope().assigneeId == null) throw new PlanningForbidden('comment:author-required')
+        const record: Comment = { ...base(), card: draft.card, body: draft.body, author: scope().assigneeId! }
+        await assertComment(record)
+        const written = await port<Comment>('comments').put(record)
+        await rebuild(written.id!)
+        return written
+      }),
+      update: async (id, changes, opts) => await unit(async () => {
+        const previous = await get<Comment>('comments', id)
+        assertCommentAuthor(previous)
+        assertVersion(previous, opts.version)
+        const record = { ...previous, body: changes.body, version: previous.version + 1, updatedAt: now() }
+        await assertComment(record)
+        const written = await port<Comment>('comments').put(record)
+        await rebuild(id)
+        return written
+      }),
+      remove: async (id, opts) => await unit(async () => {
+        const previous = await get<Comment>('comments', id)
+        await facade().cards.get(previous.card)
+        assertCommentAuthor(previous)
+        assertVersion(previous, opts.version)
+        const mentioned = await list<CommentMention>('mentions', { comment: id, size: 0 })
+        for (const row of mentioned.items) await port<CommentMention>('mentions').drop(row.id!, entityId(), row.version)
+        await port<Comment>('comments').drop(id, entityId(), opts.version)
+      }),
+    },
+    mentions: {
+      get: async id => {
+        const row = await get<CommentMention>('mentions', id)
+        const refreshed = await unit(async () => await rebuild(row.comment))
+        const found = refreshed.find(mention => mention.id === id)
+        if (found == null) throw new WorkcardNotFound(`mentions:${id}`)
+        return found
+      },
+      load: async id => {
+        try { return await resources.mentions.get(id) } catch (error) { if (error instanceof WorkcardNotFound) return null; throw error }
+      },
+      rebuild: async id => await unit(async () => await rebuild(id)),
+      list: async query => {
+        const comments = await resources.comments.list({ ...(query?.card != null ? { card: query.card } : {}), size: 0 })
+        const rows: CommentMention[] = []
+        for (const comment of comments.items) if (query?.comment == null || comment.id === query.comment) rows.push(...await unit(async () => await rebuild(comment.id!)))
+        return recordQueryHelper.applyQuery(rows, { ...(query?.assignee != null ? { assignee: query.assignee } : {}) }, query)
+      },
+    },
+  }
+  return resources
+}

package/src/service.ts

@@ -1,29 +1,14 @@
-import { createLazyService } from '@owlmeans/context'
-import type { BasicConfig, BasicContext } from '@owlmeans/context'
-import { makeSchemaRegistry, PlanningError } from '@owlmeans/planning'
-import type { PlanningService, PlanningStore, Transition, WithPlanningService } from '@owlmeans/planning'
+import { makePlanningInvariants } from './invariants.js'
+import { createLazyService, type BasicConfig, type BasicContext } from '@owlmeans/context'
+import { makeSchemaRegistry, PlanningError, type PlanningService, type PlanningStore, type Transition, type WithPlanningService } from '@owlmeans/planning'
 import { DEFAULT_ALIAS } from './consts.js'
+import { makeSchemaViews } from './definitions.js'
 import { makeStoreFacade } from './facade.js'
 import { makePluginRegistry } from './registry.js'
-import type { PluginRegistry } from './registry.js'
 import { makeCompositeStore } from './store/composite.js'
 import { makeMemoryPlanningStore } from './store/memory.js'
 import type { BindablePlanningStore } from './store/types.js'
-import type { PlanningHostService, PlanningServiceOptions } from './types.js'
-
-export type PlanningServiceApi = Pick<PlanningService, 'use' | 'plugins' | 'schemas' | 'store' | 'for' | 'committed'>
-
-/** What the facade and the executor reach the service through. */
-export interface PlanningRuntime {
-  service: () => PlanningService
-  registry: PluginRegistry
-  options: PlanningServiceOptions
-  context: () => BasicContext<BasicConfig> | undefined
-  /** The composite store reads and commits go through. */
-  reader: () => PlanningStore
-  /** Every distinct store: the default one first, then each plugin's. */
-  stores: () => PlanningStore[]
-}
+import type { PlanningHostService, PlanningServiceOptions, PlanningRuntime, PlanningServiceApi } from './types.js'
 
 const contextOf = (service: PlanningService): BasicContext<BasicConfig> | undefined =>
   (service as Partial<PlanningHostService>).ctx as BasicContext<BasicConfig> | undefined
@@ -45,6 +30,8 @@ export const planningServiceApi = (
       return
     }
     bound.add(store)
+    store.validateProjection = async (before, after, transition) => await makePlanningInvariants(runtime).validate(before, after, transition)
+    store.projectReferences = async (after, transition) => await makePlanningInvariants(runtime).references(after, transition)
     ;(store as BindablePlanningStore).bind?.(async event => { await self().committed(event) })
   }
 
@@ -54,6 +41,12 @@ export const planningServiceApi = (
 
   let reader: { version: number, store: PlanningStore } | undefined
 
+  const views = makeSchemaViews({
+    code: () => schemas,
+    version: () => registry.version(),
+    port: () => fallback.schemas,
+  })
+
   const runtime: PlanningRuntime = {
     service: self,
     registry,
@@ -66,6 +59,9 @@ export const planningServiceApi = (
       return reader.store
     },
     stores: () => [...new Set([fallback, ...registry.routes(runtime.context()).map(route => route.store)])],
+    schemaStore: () => fallback.schemas,
+    schemasFor: views.of,
+    scopedSchemas: views.scoped,
   }
 
   options.plugins?.forEach(registry.use)