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

package/src/utils/guard.ts

@@ -1,40 +1,51 @@
 import { PlanningScopeMismatch, WorkcardNotFound } from '@owlmeans/planning'
 import type { Workcard } from '@owlmeans/planning'
+import type { GuardHelper } from './guard/types.js'
 
-export const notFoundOf = (id: string): WorkcardNotFound => new WorkcardNotFound(id)
+export const createGuardHelper = (): GuardHelper => {
+  const notFoundOf = (id: string): WorkcardNotFound => new WorkcardNotFound(id)
 
-/**
- * A record of another entity is absent, not forbidden.
- *
- * @throws {WorkcardNotFound}
- */
-export const assertScope = <T extends Pick<Workcard, 'entityId'>>(
-  record: T | null | undefined, scope: { entityId: string }, id: string
-): T => {
-  if (record == null || record.entityId !== scope.entityId) {
-    throw notFoundOf(id)
+  const assertScope = <T extends Pick<Workcard, 'entityId'>>(
+    record: T | null | undefined, scope: { entityId: string }, id: string
+  ): T => {
+    if (record == null || record.entityId !== scope.entityId) {
+      throw notFoundOf(id)
+    }
+    return record
   }
-  return record
-}
 
-/**
- * Run a handler body so that a scope mismatch leaves as `WorkcardNotFound` — telling "not yours"
- * apart from "does not exist" is what turns an id space into an enumeration oracle.
- */
-export const concealed = async <T>(run: () => Promise<T>): Promise<T> => {
-  try {
-    return await run()
-  } catch (error) {
-    if (error instanceof PlanningScopeMismatch
-      || (error as { type?: string } | null)?.type === PlanningScopeMismatch.typeName) {
-      throw new WorkcardNotFound()
+  const concealed = async <T>(run: () => Promise<T>): Promise<T> => {
+    try {
+      return await run()
+    } catch (error) {
+      if (error instanceof PlanningScopeMismatch
+        || (error as { type?: string } | null)?.type === PlanningScopeMismatch.typeName) {
+        throw new WorkcardNotFound()
+      }
+      throw error
     }
-    throw error
   }
-}
 
-/** Seconds as the wire sends them, clamped to `[0, max]`. */
-export const clampSeconds = (value: unknown, max: number): number => {
-  const number = typeof value === 'number' ? value : Number(value ?? 0)
-  return Number.isFinite(number) ? Math.min(Math.max(number, 0), max) : 0
+  const clampSeconds = (value: unknown, max: number): number => {
+    const number = typeof value === 'number' ? value : Number(value ?? 0)
+    return Number.isFinite(number) ? Math.min(Math.max(number, 0), max) : 0
+  }
+
+  return { notFoundOf, assertScope, concealed, clampSeconds }
 }
+
+export const guardHelper = createGuardHelper()
+
+/** @deprecated compat:factory-refactor — use `guardHelper.notFoundOf(…)` */
+export const notFoundOf = (id: string): WorkcardNotFound => guardHelper.notFoundOf(id)
+
+/** @deprecated compat:factory-refactor — use `guardHelper.assertScope(…)` */
+export const assertScope = <T extends Pick<Workcard, 'entityId'>>(
+  record: T | null | undefined, scope: { entityId: string }, id: string
+): T => guardHelper.assertScope<T>(record, scope, id)
+
+/** @deprecated compat:factory-refactor — use `guardHelper.concealed(…)` */
+export const concealed = async <T>(run: () => Promise<T>): Promise<T> => await guardHelper.concealed<T>(run)
+
+/** @deprecated compat:factory-refactor — use `guardHelper.clampSeconds(…)` */
+export const clampSeconds = (value: unknown, max: number): number => guardHelper.clampSeconds(value, max)

package/src/utils/handler/types.ts

@@ -0,0 +1,28 @@
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+import type { PlanningFacade, PlanningScope, PlanningService } from '@owlmeans/planning'
+import type { PlanningHandlerOptions } from '../../types.js'
+import type { HandlerScope } from '../types.js'
+
+/** The planning service of one context, as a request handler reaches it. */
+export interface PlanningHandlerHelper {
+  planningServiceOf: (opts?: Pick<PlanningHandlerOptions, 'service'>) => PlanningService
+  /**
+   * The facade a handler works through, and the access it was resolved under.
+   *
+   * Without `opts.access` it is exactly the request's scope plus what `opts.scope` derives. With it,
+   * the resolver names the organization and the visible projects; a throw from the resolver is the
+   * request's error.
+   */
+  handlerScopeOf: (req: AbstractRequest, opts?: PlanningHandlerOptions) => Promise<HandlerScope>
+  /** The facade a handler works through: the request's scope plus what `opts.scope` derives. */
+  handlerFacade: (req: AbstractRequest, opts?: PlanningHandlerOptions) => Promise<PlanningFacade>
+  /**
+   * 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
+   */
+  planningFor: (
+    req: AbstractRequest, extra?: Partial<PlanningScope>, opts?: Pick<PlanningHandlerOptions, 'service'>
+  ) => PlanningFacade
+}

package/src/utils/handler.ts

@@ -0,0 +1,35 @@
+import { memoHelper, type BasicConfig, type BasicContext } from '@owlmeans/context'
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+import { PLANNING_SERVICE, type PlanningFacade, type PlanningScope, type PlanningService } from '@owlmeans/planning'
+import type { PlanningHandlerOptions, PlanningHostService } from '../types.js'
+import type { PlanningHandlerHelper } from './handler/types.js'
+import { makeRequestScope } from './request.js'
+import type { HandlerScope } from './types.js'
+
+export const makePlanningHandlerHelper = (ctx: BasicContext<BasicConfig>): PlanningHandlerHelper => {
+  const planningServiceOf = (opts?: Pick<PlanningHandlerOptions, 'service'>): PlanningService =>
+    ctx.service<PlanningHostService>(opts?.service ?? PLANNING_SERVICE)
+
+  const handlerScopeOf = async (req: AbstractRequest, opts?: PlanningHandlerOptions): Promise<HandlerScope> => {
+    const planningService = planningServiceOf(opts)
+    const extra = await opts?.scope?.(req, ctx)
+    if (opts?.access == null) {
+      return { facade: planningService.for(makeRequestScope(req).scopeOf(extra ?? undefined)) }
+    }
+    const access = await opts.access(req, ctx)
+
+    return { facade: planningService.for(makeRequestScope(req).accessScopeOf(access, extra ?? undefined)), access }
+  }
+
+  const handlerFacade = async (req: AbstractRequest, opts?: PlanningHandlerOptions): Promise<PlanningFacade> =>
+    (await handlerScopeOf(req, opts)).facade
+
+  const planningFor = (
+    req: AbstractRequest, extra?: Partial<PlanningScope>, opts?: Pick<PlanningHandlerOptions, 'service'>
+  ): PlanningFacade => planningServiceOf(opts).for(makeRequestScope(req).scopeOf(extra))
+
+  return { planningServiceOf, handlerScopeOf, handlerFacade, planningFor }
+}
+
+/** The handler helper of a context — one per context. */
+export const planningHandlerOf = memoHelper.oncePer(makePlanningHandlerHelper)

package/src/utils/index.ts

@@ -1,3 +1,11 @@
+export type * from './types.js'
+export type * from './access/types.js'
+export type * from './guard/types.js'
+export type * from './handler/types.js'
+export type * from './request/types.js'
+
+export * from './access.js'
 export * from './guard.js'
+export * from './handler.js'
+export * from './request.js'
 export * from './scope.js'
-export type * from './types.js'

package/src/utils/request/types.ts

@@ -0,0 +1,23 @@
+import type { PlanningScope, TransitionActor } from '@owlmeans/planning'
+import type { PlanningAccess } from '../../types.js'
+
+/** One request's identity as planning reads it — built at the top of a handler, never stored. */
+export interface RequestScope {
+  /** The authenticated subject of a request, as a transition names it. */
+  actorOf: () => TransitionActor
+  /**
+   * The scope a request reads and writes as.
+   *
+   * `entityId` is `requireEntityKey(req)` — the resolved organization id, never a value from the
+   * body or the query — and `extra` cannot replace it; `extra` adds what the deployment derives
+   * (a `channel`, a `service`). The actor is the authenticated subject plus that channel.
+   *
+   * @throws {AuthorizationError} when the request carries no organization
+   */
+  scopeOf: (extra?: Partial<PlanningScope>) => PlanningScope
+  /**
+   * The scope of a request under a resolved {@link PlanningAccess}: the organization is the
+   * resolver's — never the token's, never `extra`'s — and `projects` narrows it.
+   */
+  accessScopeOf: (access: PlanningAccess, extra?: Partial<PlanningScope>) => PlanningScope
+}

package/src/utils/request.ts

@@ -0,0 +1,40 @@
+
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+import type { PlanningScope, TransitionActor } from '@owlmeans/planning'
+import type { PlanningAccess } from '../types.js'
+import type { RequestScope } from './request/types.js'
+import { makeEntityScope } from '@owlmeans/auth-common'
+
+const clean = <T extends object>(record: T): T =>
+  Object.fromEntries(Object.entries(record).filter(([, value]) => value != null && value !== '')) as T
+
+export const makeRequestScope = (req: AbstractRequest): RequestScope => {
+  const actorOf = (): TransitionActor => clean({
+    profileId: req.auth?.profileId,
+    userId: req.auth?.userId,
+  })
+
+  const scopeWith = (entityId: string, extra?: Partial<PlanningScope>): PlanningScope => {
+    const subject = actorOf()
+    const channel = extra?.channel ?? extra?.actor?.channel
+
+    return clean({
+      ...extra,
+      ...subject,
+      entityId,
+      channel,
+      actor: clean({ ...extra?.actor, ...subject, channel }),
+    }) as PlanningScope
+  }
+
+  const scopeOf = (extra?: Partial<PlanningScope>): PlanningScope => scopeWith(makeEntityScope(req).requireEntityKey(), extra)
+
+  const accessScopeOf = (access: PlanningAccess, extra?: Partial<PlanningScope>): PlanningScope => {
+    const { projects: _projects, entityId: _entityId, ...rest } = extra ?? {}
+    const scope = scopeWith(access.entityId, rest)
+
+    return access.projects != null ? { ...scope, projects: [...access.projects] } : scope
+  }
+
+  return { actorOf, scopeOf, accessScopeOf }
+}

package/src/utils/scope.ts

@@ -1,131 +1,48 @@
-import { requireEntityKey } from '@owlmeans/auth-common'
 import type { BasicConfig, BasicContext } from '@owlmeans/context'
 import type { AbstractRequest } from '@owlmeans/entrypoint'
-import { PLANNING_SERVICE, PlanningForbidden, type PlanningFacade, type PlanningScope, type PlanningService, type TransitionActor, type Workcard } from '@owlmeans/planning'
-import type {
-  PlanningAccess, PlanningAccessGrants, PlanningHandlerOptions, PlanningHostService,
-} from '../types.js'
+import type { PlanningFacade, PlanningScope, PlanningService, TransitionActor, Workcard } from '@owlmeans/planning'
+import type { PlanningAccess, PlanningAccessGrants, PlanningHandlerOptions } from '../types.js'
+import { makePlanningAccessModel } from './access.js'
+import { planningHandlerOf } from './handler.js'
+import { makeRequestScope } from './request.js'
 import type { HandlerScope } from './types.js'
 
-const clean = <T extends object>(record: T): T =>
-  Object.fromEntries(Object.entries(record).filter(([, value]) => value != null && value !== '')) as T
+/** @deprecated compat:factory-refactor — use `makeRequestScope(req).actorOf()` */
+export const actorOf = (req: AbstractRequest): TransitionActor => makeRequestScope(req).actorOf()
 
-/** The authenticated subject of a request, as a transition names it. */
-export const actorOf = (req: AbstractRequest): TransitionActor => clean({
-  profileId: req.auth?.profileId,
-  userId: req.auth?.userId,
-})
-
-const scopeWith = (req: AbstractRequest, entityId: string, extra?: Partial<PlanningScope>): PlanningScope => {
-  const subject = actorOf(req)
-  const channel = extra?.channel ?? extra?.actor?.channel
-
-  return clean({
-    ...extra,
-    ...subject,
-    entityId,
-    channel,
-    actor: clean({ ...extra?.actor, ...subject, channel }),
-  }) as PlanningScope
-}
-
-/**
- * The scope a request reads and writes as.
- *
- * `entityId` is `requireEntityKey(req)` — the resolved organization id, never a value from the
- * body or the query — and `extra` cannot replace it; `extra` adds what the deployment derives
- * (a `channel`, a `service`). The actor is the authenticated subject plus that channel.
- *
- * @throws {AuthorizationError} when the request carries no organization
- */
+/** @deprecated compat:factory-refactor — use `makeRequestScope(req).scopeOf(…)` */
 export const scopeOf = (req: AbstractRequest, extra?: Partial<PlanningScope>): PlanningScope =>
-  scopeWith(req, requireEntityKey(req), extra)
+  makeRequestScope(req).scopeOf(extra)
 
-/**
- * The scope of a request under a resolved {@link PlanningAccess}: the organization is the
- * resolver's — never the token's, never `extra`'s — and `projects` narrows it.
- */
+/** @deprecated compat:factory-refactor — use `makeRequestScope(req).accessScopeOf(…)` */
 export const accessScopeOf = (
   req: AbstractRequest, access: PlanningAccess, extra?: Partial<PlanningScope>
-): PlanningScope => {
-  const { projects: _projects, entityId: _entityId, ...rest } = extra ?? {}
-  const scope = scopeWith(req, access.entityId, rest)
-
-  return access.projects != null ? { ...scope, projects: [...access.projects] } : scope
-}
+): PlanningScope => makeRequestScope(req).accessScopeOf(access, extra)
 
+/** @deprecated compat:factory-refactor — use `planningHandlerOf(ctx).planningServiceOf(…)` */
 export const planningServiceOf = (
   ctx: BasicContext<BasicConfig>, opts?: Pick<PlanningHandlerOptions, 'service'>
-): PlanningService => ctx.service<PlanningHostService>(opts?.service ?? PLANNING_SERVICE)
+): PlanningService => planningHandlerOf(ctx).planningServiceOf(opts)
 
-/**
- * The facade a handler works through, and the access it was resolved under.
- *
- * Without `opts.access` it is exactly the request's scope plus what `opts.scope` derives. With it,
- * the resolver names the organization and the visible projects; a throw from the resolver is the
- * request's error.
- */
+/** @deprecated compat:factory-refactor — use `planningHandlerOf(ctx).handlerScopeOf(…)` */
 export const handlerScopeOf = async (
   ctx: BasicContext<BasicConfig>, req: AbstractRequest, opts?: PlanningHandlerOptions
-): Promise<HandlerScope> => {
-  const extra = await opts?.scope?.(req, ctx)
-  if (opts?.access == null) {
-    return { facade: planningServiceOf(ctx, opts).for(scopeOf(req, extra ?? undefined)) }
-  }
-  const access = await opts.access(req, ctx)
-
-  return { facade: planningServiceOf(ctx, opts).for(accessScopeOf(req, access, extra ?? undefined)), access }
-}
+): Promise<HandlerScope> => await planningHandlerOf(ctx).handlerScopeOf(req, opts)
 
-/** The facade a handler works through: the request's scope plus what `opts.scope` derives. */
+/** @deprecated compat:factory-refactor — use `planningHandlerOf(ctx).handlerFacade(…)` */
 export const handlerFacade = async (
   ctx: BasicContext<BasicConfig>, req: AbstractRequest, opts?: PlanningHandlerOptions
-): Promise<PlanningFacade> => (await handlerScopeOf(ctx, req, opts)).facade
+): Promise<PlanningFacade> => await planningHandlerOf(ctx).handlerFacade(req, opts)
 
-/**
- * Refuse a write the access does not grant. No access, or access without `grants`, gates nothing;
- * a `grants` object refuses every flag it leaves out. `true` grants everything; a list grants the
- * project ids it names — `target` is the project the write is about (`undefined` for the
- * organization's root, which only `true` reaches).
- *
- * @throws {PlanningForbidden}
- */
+/** @deprecated compat:factory-refactor — use `makePlanningAccessModel(access).assertGranted(…)` */
 export const assertGranted = (
   access: PlanningAccess | undefined, grant: keyof PlanningAccessGrants, target?: string
-): void => {
-  if (access?.grants == null) {
-    return
-  }
-  const granted = access.grants[grant]
-  if (granted === true || (Array.isArray(granted) && target != null && granted.includes(target))) {
-    return
-  }
-  throw new PlanningForbidden(`${grant}:${target ?? 'root'}`)
-}
+): void => makePlanningAccessModel(access).assertGranted(grant, target)
 
-/**
- * A card the access's `writes` admits — the rule a narrowed read admits, over `writes`: a project
- * it names, or a card whose `parents` name one. A specification is admitted through its parent card
- * by the caller. No `writes` admits everything.
- */
-export const writableIn = (access: PlanningAccess | undefined, card: Pick<Workcard, 'id' | 'parents'>): boolean => {
-  const writes = access?.writes
-  if (writes == null) {
-    return true
-  }
-  return (card.id != null && writes.includes(card.id)) || card.parents.some(parent => writes.includes(parent))
-}
+/** @deprecated compat:factory-refactor — use `makePlanningAccessModel(access).writableIn(…)` */
+export const writableIn = (access: PlanningAccess | undefined, card: Pick<Workcard, 'id' | 'parents'>): boolean =>
+  makePlanningAccessModel(access).writableIn(card)
 
-/**
- * Refuse a write into a project the access's `writes` leaves out. No `writes` refuses nothing;
- * `target` is the project the write is in (`undefined` for the organization's root, which a set
- * `writes` never admits).
- *
- * @throws {PlanningForbidden}
- */
-export const assertWrites = (access: PlanningAccess | undefined, target?: string): void => {
-  if (access?.writes == null || (target != null && access.writes.includes(target))) {
-    return
-  }
-  throw new PlanningForbidden(`writes:${target ?? 'root'}`)
-}
+/** @deprecated compat:factory-refactor — use `makePlanningAccessModel(access).assertWrites(…)` */
+export const assertWrites = (access: PlanningAccess | undefined, target?: string): void =>
+  makePlanningAccessModel(access).assertWrites(target)

package/tests/creator.spec.ts

@@ -1,9 +1,9 @@
 import { describe, expect, test } from 'bun:test'
 import { CommitState, makePlanningProtocols, PlanningError, TransitionAction, WorkcardKind } from '@owlmeans/planning'
 import type { PlanningFacade, Transition, TransitionExecution, WorkcardChanges, WorkcardDraft } from '@owlmeans/planning'
-import { executePlanning, wireExecution } from '../src/actions/index.js'
-import { assertCreatorFixed, creatorOf, withCreator } from '../src/executor.js'
+import { executePlanning, executionHelper } from '../src/actions/index.js'
 import { createProject, createTask, ENTITY, invoke, makeTestPlanning, PROFILE, PROJECT, session, TASK } from './context.js'
+import { creatorHelper } from '../src/executor.js'
 
 const tree = makePlanningProtocols({ base: { alias: 'test:planning' }, guards: 'test-guard' })
 
@@ -101,21 +101,21 @@ describe('@owlmeans/server-planning — a create\'s createdBy', () => {
   test('wireExecution still answers the execution the executor will run', () => {
     const body = { card: { kind: WorkcardKind.Project, type: PROJECT, title: 'W', createdBy: 'intruder' }, action: TransitionAction.Create }
 
-    expect(draftOf(wireExecution(body, { entityId: ENTITY, profileId: PROFILE, userId: 'user-1' })).createdBy).toBe(PROFILE)
-    expect(draftOf(wireExecution(body, { entityId: ENTITY, userId: 'user-1' })).createdBy).toBe('user-1')
-    expect(draftOf(wireExecution(body, { entityId: ENTITY })).createdBy).toBeUndefined()
+    expect(draftOf(executionHelper.wireExecution(body, { entityId: ENTITY, profileId: PROFILE, userId: 'user-1' })).createdBy).toBe(PROFILE)
+    expect(draftOf(executionHelper.wireExecution(body, { entityId: ENTITY, userId: 'user-1' })).createdBy).toBe('user-1')
+    expect(draftOf(executionHelper.wireExecution(body, { entityId: ENTITY })).createdBy).toBeUndefined()
   })
 
   test('creatorOf and withCreator', () => {
-    expect(creatorOf({ entityId: ENTITY, profileId: 'p', userId: 'u', actor: { profileId: 'a' } })).toBe('p')
-    expect(creatorOf({ entityId: ENTITY, profileId: '', userId: 'u' })).toBe('u')
-    expect(creatorOf({ entityId: ENTITY, actor: { userId: 'au', service: 's' } })).toBe('au')
-    expect(creatorOf({ entityId: ENTITY, service: 's' })).toBeUndefined()
+    expect(creatorHelper.creatorOf({ entityId: ENTITY, profileId: 'p', userId: 'u', actor: { profileId: 'a' } })).toBe('p')
+    expect(creatorHelper.creatorOf({ entityId: ENTITY, profileId: '', userId: 'u' })).toBe('u')
+    expect(creatorHelper.creatorOf({ entityId: ENTITY, actor: { userId: 'au', service: 's' } })).toBe('au')
+    expect(creatorHelper.creatorOf({ entityId: ENTITY, service: 's' })).toBeUndefined()
 
     const update: TransitionExecution = { card: 'card-1', action: TransitionAction.Update, changes: { title: 'T' } }
-    expect(withCreator(update, { entityId: ENTITY, profileId: 'p' })).toBe(update)
+    expect(creatorHelper.withCreator(update, { entityId: ENTITY, profileId: 'p' })).toBe(update)
     const blank: TransitionExecution = { card: { kind: WorkcardKind.Project, type: PROJECT, title: 'T', createdBy: '' }, action: TransitionAction.Create }
-    expect(draftOf(withCreator(blank, { entityId: ENTITY, profileId: 'p' })).createdBy).toBe('p')
+    expect(draftOf(creatorHelper.withCreator(blank, { entityId: ENTITY, profileId: 'p' })).createdBy).toBe('p')
   })
 })
 
@@ -246,12 +246,12 @@ describe('@owlmeans/server-planning — createdBy never moves after the create',
   test('assertCreatorFixed', () => {
     const draft = { kind: WorkcardKind.Project, type: PROJECT, title: 'T', createdBy: 'owner' }
 
-    expect(() => assertCreatorFixed({ card: draft, action: TransitionAction.Create })).not.toThrow()
-    expect(() => assertCreatorFixed({ card: 'c', action: TransitionAction.Update, changes: { title: 'T', createdBy: undefined } })).not.toThrow()
-    expect(() => assertCreatorFixed({ card: 'c', action: TransitionAction.Update, unset: ['fields.createdBy'] })).not.toThrow()
-    expect(() => assertCreatorFixed({ card: 'c', action: TransitionAction.Update, changes: { fields: { createdBy: 'x' } } })).not.toThrow()
-    expect(() => assertCreatorFixed({ card: 'c', action: TransitionAction.Update, changes: { createdBy: 'x' } })).toThrow('planning:immutable:createdBy')
-    expect(() => assertCreatorFixed({ card: 'c', action: TransitionAction.Delete, unset: ['createdBy'] })).toThrow('planning:immutable:createdBy')
-    expect(() => assertCreatorFixed({ card: draft, action: TransitionAction.Create, changes: { createdBy: 'x' } })).toThrow('planning:immutable:createdBy')
+    expect(() => creatorHelper.assertCreatorFixed({ card: draft, action: TransitionAction.Create })).not.toThrow()
+    expect(() => creatorHelper.assertCreatorFixed({ card: 'c', action: TransitionAction.Update, changes: { title: 'T', createdBy: undefined } })).not.toThrow()
+    expect(() => creatorHelper.assertCreatorFixed({ card: 'c', action: TransitionAction.Update, unset: ['fields.createdBy'] })).not.toThrow()
+    expect(() => creatorHelper.assertCreatorFixed({ card: 'c', action: TransitionAction.Update, changes: { fields: { createdBy: 'x' } } })).not.toThrow()
+    expect(() => creatorHelper.assertCreatorFixed({ card: 'c', action: TransitionAction.Update, changes: { createdBy: 'x' } })).toThrow('planning:immutable:createdBy')
+    expect(() => creatorHelper.assertCreatorFixed({ card: 'c', action: TransitionAction.Delete, unset: ['createdBy'] })).toThrow('planning:immutable:createdBy')
+    expect(() => creatorHelper.assertCreatorFixed({ card: draft, action: TransitionAction.Create, changes: { createdBy: 'x' } })).toThrow('planning:immutable:createdBy')
   })
 })

package/src/actions/cards.ts

@@ -1,48 +0,0 @@
-import { handlers } from '@owlmeans/server-api'
-import { decodeSpecificationQuery, decodeSummaryQuery, decodeTransitionQuery, decodeWorkcardQuery, type PlanningProtocols } from '@owlmeans/planning'
-import type { Context, PlanningHandlerOptions } from '../types.js'
-import { concealed, handlerFacade } from '../utils/index.js'
-import type { RequestHandler } from './types.js'
-
-/** Cards of the caller's entity; the query arrives in its wire shape and is decoded here. */
-export const listCards = (protocol: PlanningProtocols['card']['list'], opts?: PlanningHandlerOptions): RequestHandler =>
-  handlers<Context>().request(protocol, async (req, ctx) => concealed(async () => {
-    const facade = await handlerFacade(ctx, req, opts)
-
-    return await facade.cards.list(decodeWorkcardQuery(req.query))
-  }))
-
-/** Intrinsic counts of DIRECT children per parent. */
-export const summarizeCards = (protocol: PlanningProtocols['card']['summary'], opts?: PlanningHandlerOptions): RequestHandler =>
-  handlers<Context>().request(protocol, async (req, ctx) => concealed(async () => {
-    const facade = await handlerFacade(ctx, req, opts)
-    const { parents, ...query } = decodeSummaryQuery(req.query)
-
-    return await facade.cards.summary(parents, query)
-  }))
-
-/** @throws {WorkcardNotFound} for an absent card and for another entity's alike */
-export const getCard = (protocol: PlanningProtocols['card']['get'], opts?: PlanningHandlerOptions): RequestHandler =>
-  handlers<Context>().request(protocol, async (req, ctx) => concealed(async () => {
-    const facade = await handlerFacade(ctx, req, opts)
-
-    return await facade.cards.get(`${req.params.id}`)
-  }))
-
-/** One card's log. */
-export const listCardTransitions = (protocol: PlanningProtocols['card']['transitions'], opts?: PlanningHandlerOptions): RequestHandler =>
-  handlers<Context>().request(protocol, async (req, ctx) => concealed(async () => {
-    const facade = await handlerFacade(ctx, req, opts)
-    const card = await facade.cards.get(`${req.params.id}`)
-
-    return await facade.transitions.list({ ...decodeTransitionQuery(req.query), card: card.id })
-  }))
-
-/** One card's specifications — the current document per category unless `all`. */
-export const listCardSpecifications = (protocol: PlanningProtocols['card']['specifications'], opts?: PlanningHandlerOptions): RequestHandler =>
-  handlers<Context>().request(protocol, async (req, ctx) => concealed(async () => {
-    const facade = await handlerFacade(ctx, req, opts)
-    const card = await facade.cards.get(`${req.params.id}`)
-
-    return await facade.specifications.list(card.id!, decodeSpecificationQuery(req.query))
-  }))

package/src/actions/schemas.ts

@@ -1,87 +0,0 @@
-import { handlers } from '@owlmeans/server-api'
-import { PlanningUnsupported, SchemaWriteMode, type PlanningDefinitions, type PlanningProtocols, type SchemaDefineReply, type SchemaDefineRequest, type ScopedSchemaBundle, type ScopedSchemaRecord } from '@owlmeans/planning'
-import type { Context, PlanningHandlerOptions } from '../types.js'
-import { assertGranted, assertWrites, concealed, handlerScopeOf } from '../utils/index.js'
-import type { RequestHandler } from './types.js'
-
-const text = (value: unknown): string | undefined =>
-  value == null || value === '' ? undefined : `${Array.isArray(value) ? value[0] : value}`
-
-/**
- * The schema bundle — what a client loads to answer `can()` with no round trip. Scoped like every
- * other leaf (no organization, no bundle). Where the store holds data-defined schemas it is the
- * resolved layer of the organization, or of the project the `project` query names (a project this
- * scope can see); otherwise the service's code bundle.
- *
- * @throws {WorkcardNotFound} for a project this scope cannot see
- */
-export const listSchemas = (
-  protocol: PlanningProtocols['schema']['list'], opts?: PlanningHandlerOptions
-): RequestHandler =>
-  handlers<Context>().request(protocol, async (req, ctx) => concealed(async (): Promise<ScopedSchemaBundle> => {
-    const { facade } = await handlerScopeOf(ctx, req, opts)
-    if (facade.definitions == null) {
-      return facade.schemas.bundle()
-    }
-
-    return await facade.definitions.bundle(text((req.query as { project?: unknown } | undefined)?.project))
-  }))
-
-/**
- * Apply one `schema.define` request to a facade's definitions: the declarations in the request's
- * mode (flows before types), then the retirements — answering what was written and the layer as it
- * resolves afterwards.
- */
-export const applySchemaRequest = async (
-  definitions: PlanningDefinitions, request: SchemaDefineRequest
-): Promise<SchemaDefineReply> => {
-  const layer = request.project != null ? { project: request.project } : {}
-  const declarations = { types: request.types ?? [], flows: request.flows ?? [] }
-  const records: ScopedSchemaRecord[] = []
-
-  switch (request.mode ?? SchemaWriteMode.Define) {
-    case SchemaWriteMode.Put:
-      for (const flow of declarations.flows) {
-        records.push(await definitions.putFlow(flow, layer))
-      }
-      for (const type of declarations.types) {
-        records.push(await definitions.putType(type, layer))
-      }
-      break
-    case SchemaWriteMode.Seed:
-      records.push(...await definitions.seed(declarations, layer))
-      break
-    default:
-      records.push(...await definitions.define(declarations, layer))
-  }
-  for (const key of request.retire ?? []) {
-    records.push(await definitions.retire(key.kind, key.key, layer))
-  }
-
-  return { records, bundle: await definitions.bundle(request.project) }
-}
-
-/**
- * The write of data-defined types and flows. A project layer needs the project in the access's
- * `writes` when the resolver answers it; then `grants.defineSchemas` gates when the resolver answers
- * grants (the organization-wide layer needs `true`, a project layer its id).
- *
- * @throws {PlanningUnsupported} where the store holds no data-defined schemas
- * @throws {PlanningForbidden | SchemaConflict | SchemaSealed | SchemaInvalid | SchemaInUse | WorkcardNotFound}
- */
-export const defineSchemas = (
-  protocol: NonNullable<PlanningProtocols['schema']['define']>, opts?: PlanningHandlerOptions
-): RequestHandler =>
-  handlers<Context>().request(protocol, async (req, ctx) => concealed(async (): Promise<SchemaDefineReply> => {
-    const { facade, access } = await handlerScopeOf(ctx, req, opts)
-    const request = (req.body ?? {}) as SchemaDefineRequest
-    if (facade.definitions == null) {
-      throw new PlanningUnsupported('definitions')
-    }
-    if (request.project != null) {
-      assertWrites(access, request.project)
-    }
-    assertGranted(access, 'defineSchemas', request.project)
-
-    return await applySchemaRequest(facade.definitions, request)
-  }))