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

package/src/conformance/fixtures.ts

@@ -0,0 +1,121 @@
+// owlmeans-structure: allow-file the conformance fixtures are one declarative data set together with the plugin that serves it
+import { CodeScope, CodeStyle, IntrinsicStatus, SpecificationFormat, TransitionAction, WorkcardKind, type AnyTypeSchema, type PlanningFacade, type PlanningPlugin, type StatusFlowSchema, type TransitionReceipt, type Workcard } from '@owlmeans/planning'
+import { BOOK_TYPE, LIBRARY, PERIODICAL_TYPE } from './consts.js'
+
+const flows: StatusFlowSchema[] = [
+  {
+    id: LIBRARY.circulation,
+    version: 1,
+    statuses: [
+      { key: 'shelved', intrinsic: IntrinsicStatus.Planned, initial: true },
+      { key: 'lent', intrinsic: IntrinsicStatus.InProgress },
+      { key: 'retired', intrinsic: IntrinsicStatus.Closed, terminal: true },
+    ],
+    transitions: [
+      { name: 'lend', from: ['shelved'], to: 'lent', explicit: true },
+      { name: 'return', from: ['lent'], to: 'shelved', explicit: true },
+      { name: 'retire', from: '*', to: 'retired' },
+      { name: 'restore', from: ['retired'], to: 'shelved' },
+    ],
+  },
+  {
+    id: LIBRARY.review,
+    version: 1,
+    statuses: [
+      { key: 'unreviewed', intrinsic: IntrinsicStatus.Planned, initial: true },
+      { key: 'reviewed', intrinsic: IntrinsicStatus.Closed },
+    ],
+    transitions: [{ name: 'review', from: ['unreviewed'], to: 'reviewed' }],
+  },
+  {
+    id: LIBRARY.branchLife,
+    version: 1,
+    statuses: [
+      { key: 'open', intrinsic: IntrinsicStatus.Planned, initial: true },
+      { key: 'active', intrinsic: IntrinsicStatus.InProgress },
+    ],
+    transitions: [{ name: 'activate', from: ['open'], to: 'active' }],
+  },
+  {
+    id: LIBRARY.pageLife,
+    version: 1,
+    statuses: [{ key: 'draft', intrinsic: IntrinsicStatus.Planned, initial: true }],
+    transitions: [],
+  },
+]
+
+const types: AnyTypeSchema[] = [
+  {
+    type: LIBRARY.branch,
+    kind: WorkcardKind.Project,
+    version: 1,
+    fields: { type: 'object', additionalProperties: true },
+    flows: [LIBRARY.branchLife],
+    cardTypes: [LIBRARY.book, LIBRARY.periodical],
+    projectTypes: [LIBRARY.branch],
+    scopedCardTypes: true,
+    specifications: [
+      { category: 'charter', format: SpecificationFormat.Markdown },
+      { category: 'notes', format: SpecificationFormat.Markdown, multiple: true },
+    ],
+    code: { style: CodeStyle.Slug, uniqueWithin: CodeScope.Entity, mutable: true },
+  },
+  {
+    type: LIBRARY.room,
+    kind: WorkcardKind.Project,
+    version: 1,
+    fields: { type: 'object', additionalProperties: true },
+    flows: [LIBRARY.branchLife],
+    cardTypes: [LIBRARY.book],
+    specifications: [],
+  },
+  BOOK_TYPE,
+  PERIODICAL_TYPE,
+  {
+    type: LIBRARY.page,
+    kind: WorkcardKind.Specification,
+    version: 1,
+    fields: { type: 'object', additionalProperties: true },
+    flows: [LIBRARY.pageLife],
+    specifications: [],
+  },
+]
+
+/** The types and flows every conformance case runs against — register it on the service under test. */
+export const planningConformancePlugin: PlanningPlugin = Object.freeze({
+  name: 'planning-conformance',
+  order: 0,
+  schemas: { types, flows },
+})
+
+/**
+ * A clock that never repeats an instant — what a conformance service is booted with, so an
+ * `updatedSince` or an ordering by `at` is deterministic on a fast store.
+ */
+export const conformanceClock = (): (() => string) => {
+  let last = 0
+  return () => {
+    last = Math.max(Date.now(), last + 1)
+    return new Date(last).toISOString()
+  }
+}
+
+export const createBranch = async (
+  planning: PlanningFacade, title: string = 'Riverside branch', extra: Record<string, unknown> = {}
+): Promise<Workcard> => (await planning.execute({
+  card: { kind: WorkcardKind.Project, type: LIBRARY.branch, title, ...extra },
+  action: TransitionAction.Create,
+}, { wait: true })).card!
+
+export const createBook = async (
+  planning: PlanningFacade, branch: string, title: string = 'A book', extra: Record<string, unknown> = {}
+): Promise<Workcard> => (await planning.execute({
+  card: { kind: WorkcardKind.Card, type: LIBRARY.book, parent: branch, title, ...extra },
+  action: TransitionAction.Create,
+}, { wait: true })).card!
+
+export const transit = async (
+  planning: PlanningFacade, card: string, transition: string, extra: { flow?: string } = {}
+): Promise<TransitionReceipt> => await planning.execute({
+  card, action: TransitionAction.Transit, transition, ...extra,
+}, { wait: true })

package/src/conformance/index.ts

@@ -0,0 +1,11 @@
+/**
+ * The planning store conformance suite — a framework-agnostic list of named cases every
+ * `PlanningStore` answers identically. No test runner is imported: a store's own spec file loops
+ * over {@link conformanceCasesFor} and hands each case a {@link ConformanceSubject}; a case throws
+ * `ConformanceFailure` (a plain `Error`) when an expectation does not hold.
+ */
+export * from './assert.js'
+export * from './cases.js'
+export type * from './types.js'
+export * from './fixtures.js'
+export * from './consts.js'

package/src/conformance/types.ts

@@ -0,0 +1,20 @@
+import type { PlanningFacade, PlanningService, PlanningStore } from '@owlmeans/planning'
+
+/** What a case runs against: a planning service over the store under test. */
+export interface ConformanceSubject {
+  /** A service with `planningConformancePlugin` registered and a strictly increasing clock. */
+  service: PlanningService
+  /** The store under test — the service's default store. */
+  store: PlanningStore
+  /** A facade of one organization, acting as a signed-in person. */
+  facade: (entityId: string) => PlanningFacade
+}
+
+/** A capability a store may implement; a case that needs one is skipped for a store without it. */
+export type ConformanceCapability = 'schemas'
+
+export interface ConformanceCase {
+  name: string
+  needs?: ConformanceCapability[]
+  run: (subject: ConformanceSubject) => Promise<void>
+}

package/src/consts.ts

@@ -20,3 +20,9 @@ export const DEFAULT_COMMIT_MEMORY = 1000
  * ladder is what answers when it folded somewhere the hub does not.
  */
 export const COMMIT_POLL_LADDER: readonly number[] = Object.freeze([250, 1000, 2000])
+
+/**
+ * How many resolved schema layers (organization, project) a service keeps. A layer is re-resolved
+ * whenever its organization's schema revision moves, so the cap bounds memory, never staleness.
+ */
+export const DEFAULT_SCHEMA_VIEWS = 500

package/src/definitions.ts

@@ -0,0 +1,250 @@
+import { assertFlowSchema, assertOverridable, assertTypeSchema, flowInUse, isProject, PlanningSchemaKind, PlanningUnsupported, resolveScopedBundle, SchemaConflict, SchemaInUse, scopedRegistryOf, UnknownStatusFlow, UnknownWorkcardType, WorkcardNotFound, type PlanningDefinitions, type PlanningFacade, type PlanningSchemaRegistry, type SchemaDeclarations, type SchemaStore, type SchemaWriteOptions, type ScopedSchemaRecord, type ScopedSchemaRegistry, type StatusFlowSchema, type TransitionExecution, type Unsubscribe, type WorkcardTypeSchema } from '@owlmeans/planning'
+import { DEFAULT_SCHEMA_VIEWS } from './consts.js'
+import { actorOf } 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 = scopedRegistryOf(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.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) — 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 = (project: string): boolean => scope.projects == null || scope.projects.includes(project)
+
+  /** @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 || !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 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) {
+      assertOverridable(code, entry.kind, entry.key)
+      if (entry.kind === PlanningSchemaKind.Flow) {
+        assertFlowSchema(entry.definition as StatusFlowSchema)
+      } else {
+        assertTypeSchema(entry.definition as WorkcardTypeSchema, flows)
+      }
+    }
+  }
+
+  const recordOf = (
+    entry: Planned, version: number, project: string | undefined, current?: ScopedSchemaRecord, retired?: boolean
+  ): ScopedSchemaRecord => {
+    const at = now()
+    const by = 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 write = async (
+    plan: Planned[], opts: SchemaWriteOptions | undefined, versionOf: (entry: Planned, current?: ScopedSchemaRecord) => number | null
+  ): Promise<ScopedSchemaRecord[]> => {
+    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' && !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 })
+      return records.filter(record => record.project == null || visible(record.project))
+    },
+
+    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 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 = flowInUse(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.ts

@@ -1,9 +1,5 @@
-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 { CommitState, computeChanges, isEmptyChange, TransitionAction, type ChangeSet, type PlanningSchemaRegistry, type PlanningScope, type RelationshipDraft, type Transition, type TransitionActor, type TransitionExecution, type WorkcardDraft } from '@owlmeans/planning'
+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

package/src/executor/code.ts

@@ -1,13 +1,7 @@
-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, CodeScope, CodeStyle, CodeTaken, mintCode, TransitionAction, type CodePolicy, type PlanningExecContext, type PlanningPlugin, type PlanningScope, type TransitionExecution, type WorkcardDraft, type Workcard } 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 { Resolved } from './types.js'
 
 /** The criteria a code must be unique within — the policy's scope, `parent` when there is none. */
 const scopeCriteria = (

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.ts

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