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

package/src/types.local.ts

@@ -0,0 +1,7 @@
+import { PlanningSchemaKind, type AssigneeTypeSchema, type StatusFlowSchema, type WorkcardTypeSchema } from '@owlmeans/planning'
+
+export interface Planned {
+  kind: PlanningSchemaKind
+  key: string
+  definition: WorkcardTypeSchema | StatusFlowSchema | AssigneeTypeSchema
+}

package/src/types.ts

@@ -1,11 +1,10 @@
 import type { BasicConfig, BasicContext, LazyService } from '@owlmeans/context'
 import type { AbstractRequest } from '@owlmeans/entrypoint'
-import type {
-  AnyTypeSchema, PlanningPlugin, PlanningScope, PlanningService, PlanningStore, StatusFlowSchema,
-  WithPlanningService,
-} from '@owlmeans/planning'
+import type { AssigneeTypeSchema, AnyTypeSchema, PlanningAppDeclarations, PlanningPlugin, PlanningScope, PlanningService, PlanningStore, StatusFlowSchema, WithPlanningService, PlanningSchemaRegistry, SchemaStore, ScopedSchemaRegistry, CommitEvent, PlanningExecContext, PlanningHookContext, TransitionExecution, WorkcardDraft } from '@owlmeans/planning'
 import type { ApiServerAppend } from '@owlmeans/server-api'
 import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import type { StoreRoute } from './store/types.js'
+
 
 export interface Config extends ServerConfig { }
 
@@ -15,8 +14,11 @@ export interface PlanningServiceOptions {
   /** The default store — every type no plugin owns. An in-memory store when omitted. */
   store?: PlanningStore
   plugins?: PlanningPlugin[]
-  /** Schemas registered before any plugin's. */
-  schemas?: { types?: AnyTypeSchema[], flows?: StatusFlowSchema[] }
+  /**
+   * Schemas registered before any plugin's; `app` is the first source every plugin's `schemas.app`
+   * is merged over.
+   */
+  schemas?: { types?: AnyTypeSchema[], flows?: StatusFlowSchema[], assigneeTypes?: AssigneeTypeSchema[], app?: PlanningAppDeclarations }
   /** Run the `after` chain in this process. Default `true`. */
   hooks?: boolean
   /** Card ids when the store mints none. */
@@ -37,6 +39,53 @@ export interface PlanningScopeExtractor {
   (req: AbstractRequest, ctx: BasicContext<BasicConfig>): Partial<PlanningScope> | Promise<Partial<PlanningScope>>
 }
 
+/**
+ * A grant: `true` for everything the request can see, a list for those project cards only (the
+ * parent of a created project, the deleted project, the schema layer).
+ */
+export type PlanningGrant = boolean | string[]
+
+export interface PlanningAccessGrants {
+  /** Create a project — at the root only with `true`; a list names the parent projects. */
+  manageAssignees?: boolean
+  manageTeams?: boolean
+  createProjects?: PlanningGrant
+  /** Delete a project — a list names the projects. */
+  deleteProjects?: PlanningGrant
+  /** Write data-defined types and flows — the organization-wide layer only with `true`. */
+  defineSchemas?: PlanningGrant
+}
+
+/** What a hosting application decides about one request. */
+export interface PlanningAccess {
+  /** The organization the request acts in — the only source of it once a resolver is given. */
+  entityId: string
+  /** Narrows every read and write to these project cards. Every project when omitted. */
+  projects?: string[]
+  /**
+   * The project cards the request may WRITE in: `execute` on a card, specification or link inside
+   * one of them (the same rule a narrowed read admits — the project, the cards whose `parents` name
+   * it, a specification through its parent card), and `schema.define` of a project layer. A project
+   * outside `projects` is still unreachable. Omitted — writes reach every project `projects` admits;
+   * present — anything else is refused with `PlanningForbidden` (403). Creating a project is
+   * `grants.createProjects`' alone; the organization-wide schema layer is `grants.defineSchemas`'.
+   */
+  writes?: string[]
+  /**
+   * Gates the writes above. Omitted — nothing is gated; present — a flag it leaves out is refused
+   * with `PlanningForbidden`.
+   */
+  grants?: PlanningAccessGrants
+}
+
+/**
+ * Resolves a request's access. A throw is the request's answer (an `AuthForbidden` answers 403
+ * like any other guard refusal).
+ */
+export interface PlanningAccessResolver {
+  (req: AbstractRequest, ctx: BasicContext<BasicConfig>): Promise<PlanningAccess>
+}
+
 export interface PlanningHandlerOptions {
   /** The planning service alias. `PLANNING_SERVICE` when omitted. */
   service?: string
@@ -45,4 +94,88 @@ export interface PlanningHandlerOptions {
   /** The longest single long poll, in seconds — clamps `commit.get`'s `wait` and `execute`'s `timeout`. */
   maxPoll?: number
   scope?: PlanningScopeExtractor
+  /**
+   * The hosting application's access decision per request. Without it the organization is the
+   * request's own (`requireEntityKey`) and nothing is narrowed or gated.
+   */
+  access?: PlanningAccessResolver
+}
+
+export interface SchemaViewsOptions {
+  /** The code registry every layer starts from. */
+  code: () => PlanningSchemaRegistry
+  /** Bumps whenever the code registry changes (a plugin's `use`). */
+  version: () => number
+  /** The schema port, when the store has one. */
+  port: () => SchemaStore | undefined
+  /** How many resolved layers are kept. */
+  limit?: number
+}
+
+export interface SchemaViews {
+  /** The code registry itself without a port; the resolved layer with one. */
+  of: (entityId: string, project?: string) => Promise<PlanningSchemaRegistry>
+  /** @throws {PlanningUnsupported} without a port */
+  scoped: (entityId: string, project?: string) => Promise<ScopedSchemaRegistry>
+}
+
+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>
+}
+
+export interface PluginRegistry {
+  /**
+   * Register, or replace the plugin of the same `name`. Its schemas are contributed now; the
+   * application's declarations are re-merged from the service's own and every plugin's, in plugin
+   * order (`appSchemaHelper.merge`), so a replaced plugin's declarations leave with it.
+   *
+   * @throws {SchemaInvalid} a malformed `schemas.app` — the plugin is not registered
+   */
+  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
+}
+
+export interface PlanningServiceApi extends 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[]
+  /** The default store's data-defined schema port, when it has one. */
+  schemaStore: () => SchemaStore | undefined
+  /**
+   * The registry a card of this organization (and project) resolves through. Without a schema
+   * port it is the service's code registry itself — the very same object.
+   */
+  schemasFor: (entityId: string, project?: string) => Promise<PlanningSchemaRegistry>
+  /** The resolved layer. @throws {PlanningUnsupported} without a schema port */
+  scopedSchemas: (entityId: string, project?: string) => Promise<ScopedSchemaRegistry>
 }

package/src/utils/access/types.ts

@@ -0,0 +1,30 @@
+import type { Workcard } from '@owlmeans/planning'
+import type { PlanningAccess, PlanningAccessGrants } from '../../types.js'
+
+/** The write rules of one resolved {@link PlanningAccess} — no access at all gates nothing. */
+export interface PlanningAccessModel {
+  readonly record: PlanningAccess | undefined
+  /**
+   * 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}
+   */
+  assertGranted: (grant: keyof PlanningAccessGrants, target?: string) => void
+  /**
+   * 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.
+   */
+  writableIn: (card: Pick<Workcard, 'id' | 'parents'>) => boolean
+  /**
+   * 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}
+   */
+  assertWrites: (target?: string) => void
+}

package/src/utils/access.ts

@@ -0,0 +1,33 @@
+import { PlanningForbidden, type Workcard } from '@owlmeans/planning'
+import type { PlanningAccess, PlanningAccessGrants } from '../types.js'
+import type { PlanningAccessModel } from './access/types.js'
+
+export const makePlanningAccessModel = (access: PlanningAccess | undefined): PlanningAccessModel => {
+  const assertGranted = (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'}`)
+  }
+
+  const writableIn = (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))
+  }
+
+  const assertWrites = (target?: string): void => {
+    if (access?.writes == null || (target != null && access.writes.includes(target))) {
+      return
+    }
+    throw new PlanningForbidden(`writes:${target ?? 'root'}`)
+  }
+
+  return { record: access, assertGranted, writableIn, assertWrites }
+}

package/src/utils/guard/types.ts

@@ -0,0 +1,21 @@
+import type { WorkcardNotFound, Workcard, PlanningReply } from '@owlmeans/planning'
+
+/** What every handler answers with when a record is not the caller's: absence, never a refusal. */
+export interface GuardHelper {
+  notFoundOf: (id: string) => WorkcardNotFound
+  /**
+   * A record of another entity is absent, not forbidden.
+   *
+   * @throws {WorkcardNotFound}
+   */
+  assertScope: <T extends Pick<Workcard, 'entityId'>>(record: T | null | undefined, scope: { entityId: string }, id: string) => T
+  /**
+   * 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.
+   */
+  concealed: <T>(run: () => Promise<T>) => Promise<T>
+  /** Conceal scope failures and project storage metadata out of a public reply. */
+  reply: <T>(run: () => Promise<T>) => Promise<PlanningReply<T>>
+  /** Seconds as the wire sends them, clamped to `[0, max]`. */
+  clampSeconds: (value: unknown, max: number) => number
+}

package/src/utils/guard.ts

@@ -1,40 +1,53 @@
-import { PlanningScopeMismatch, WorkcardNotFound } from '@owlmeans/planning'
+import { planningReplyHelper, 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,
+    reply: async run => planningReplyHelper.project(await concealed(run)),
+  }
 }
+
+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,2 +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'

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,51 +1,48 @@
-import { requireEntityKey } from '@owlmeans/auth-common'
 import type { BasicConfig, BasicContext } from '@owlmeans/context'
 import type { AbstractRequest } from '@owlmeans/entrypoint'
-import { PLANNING_SERVICE } from '@owlmeans/planning'
-import type { PlanningFacade, PlanningScope, PlanningService, TransitionActor } from '@owlmeans/planning'
-import type { PlanningHandlerOptions, PlanningHostService } from '../types.js'
-
-const clean = <T extends object>(record: T): T =>
-  Object.fromEntries(Object.entries(record).filter(([, value]) => value != null && value !== '')) as T
-
-/** 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,
-})
-
-/**
- * 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
- */
-export const scopeOf = (req: AbstractRequest, extra?: Partial<PlanningScope>): PlanningScope => {
-  const entityId = requireEntityKey(req)
-  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
-}
+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'
 
+/** @deprecated compat:factory-refactor — use `makeRequestScope(req).actorOf()` */
+export const actorOf = (req: AbstractRequest): TransitionActor => makeRequestScope(req).actorOf()
+
+/** @deprecated compat:factory-refactor — use `makeRequestScope(req).scopeOf(…)` */
+export const scopeOf = (req: AbstractRequest, extra?: Partial<PlanningScope>): PlanningScope =>
+  makeRequestScope(req).scopeOf(extra)
+
+/** @deprecated compat:factory-refactor — use `makeRequestScope(req).accessScopeOf(…)` */
+export const accessScopeOf = (
+  req: AbstractRequest, access: PlanningAccess, extra?: Partial<PlanningScope>
+): 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: the request's scope plus what `opts.scope` derives. */
+/** @deprecated compat:factory-refactor — use `planningHandlerOf(ctx).handlerScopeOf(…)` */
+export const handlerScopeOf = async (
+  ctx: BasicContext<BasicConfig>, req: AbstractRequest, opts?: PlanningHandlerOptions
+): Promise<HandlerScope> => await planningHandlerOf(ctx).handlerScopeOf(req, opts)
+
+/** @deprecated compat:factory-refactor — use `planningHandlerOf(ctx).handlerFacade(…)` */
 export const handlerFacade = async (
   ctx: BasicContext<BasicConfig>, req: AbstractRequest, opts?: PlanningHandlerOptions
-): Promise<PlanningFacade> => {
-  const extra = await opts?.scope?.(req, ctx)
+): Promise<PlanningFacade> => await planningHandlerOf(ctx).handlerFacade(req, opts)
+
+/** @deprecated compat:factory-refactor — use `makePlanningAccessModel(access).assertGranted(…)` */
+export const assertGranted = (
+  access: PlanningAccess | undefined, grant: keyof PlanningAccessGrants, target?: string
+): void => makePlanningAccessModel(access).assertGranted(grant, target)
+
+/** @deprecated compat:factory-refactor — use `makePlanningAccessModel(access).writableIn(…)` */
+export const writableIn = (access: PlanningAccess | undefined, card: Pick<Workcard, 'id' | 'parents'>): boolean =>
+  makePlanningAccessModel(access).writableIn(card)
 
-  return planningServiceOf(ctx, opts).for(scopeOf(req, extra ?? undefined))
-}
+/** @deprecated compat:factory-refactor — use `makePlanningAccessModel(access).assertWrites(…)` */
+export const assertWrites = (access: PlanningAccess | undefined, target?: string): void =>
+  makePlanningAccessModel(access).assertWrites(target)

package/src/utils/types.ts

@@ -0,0 +1,8 @@
+import type { PlanningFacade } from '@owlmeans/planning'
+import type { PlanningAccess } from '../types.js'
+
+export interface HandlerScope {
+  facade: PlanningFacade
+  /** The resolver's answer, when the handler options carry one. */
+  access?: PlanningAccess
+}