@owlmeans/server-planning 0.1.18-rc.3 → 0.1.18-rc.31

package/README.md

@@ -2,7 +2,7 @@
 
 The server half of `@owlmeans/planning`: the planning service and its plugin registry, the
 transition executor every write goes through, the in-memory reference store, the commit hub and the
-protocol handlers. A backend appends the service once, binds the handlers to the shared protocol
+protocol handlers, versioned auxiliary resource commands and schema-governed hierarchy. A backend appends the service once, binds the handlers to the shared protocol
 tree, and reads and writes through a scoped facade. A browser or Node client uses
 `@owlmeans/client-planning` against the same tree; a durable store implements the ports and reuses
 the `@owlmeans/server-planning/store` subpath.
@@ -10,13 +10,16 @@ the `@owlmeans/server-planning/store` subpath.
 ## Installation
 
 ```sh
-bun add @owlmeans/server-planning@^0.1.18-rc.3 @owlmeans/planning@^0.1.18-rc.3 ajv
+bun add @owlmeans/server-planning@^0.1.18-rc.31 @owlmeans/planning@^0.1.18-rc.26 ajv
 ```
 
 ## Concepts
 
-- **Facade** — `context.planning().for(scope)`: every read and write of one organization entity,
-  with no scope argument on any method.
+- **Facade** — `ctx.service<PlanningHostService>(PLANNING_SERVICE).for(scope)`: every read and
+  write of one organization entity, with no scope argument on any method. `context.planning()` is
+  the same service, but only on a context that went through `appendPlanningService`; a service
+  registered as a plain one (`makePlanningService()`, a generated target's `services/planning.ts`)
+  has no `context.planning`.
 - **Executor** — the only write path: normalize → idempotency → resolve → plugins' `before` →
   validate → id → code → changes → seq CAS → append → project → receipt. Nothing is appended by a
   refusal.
@@ -26,6 +29,8 @@ bun add @owlmeans/server-planning@^0.1.18-rc.3 @owlmeans/planning@^0.1.18-rc.3 a
   `after` chain exactly once and publishes a commit event.
 - **Store** — `makeMemoryPlanningStore()` for tests and single-process tools; a durable store in
   anything with more than one process.
+- **Resource facade** — `assignees`, `teams`, `comments` and `mentions` use native versioned ports.
+  Organization units serialize dependent writes, schema changes and derived relationships.
 
 ## Usage
 
@@ -37,6 +42,8 @@ import { makePlanningProtocols } from '@owlmeans/planning'
 export const planningProtocols = makePlanningProtocols({
   base: { alias: 'app:planning', path: '/planning' },
   guards: DEFAULT_GUARD,
+  resources: true,
+  definitions: true,
 })
 ```
 
@@ -90,47 +97,113 @@ ensurePlanningService(context).use({
 Hand-written handler and the memory store in a test:
 
 ```ts
-import { appendPlanningService, planningFor } from '@owlmeans/server-planning'
+import { appendPlanningService, planningHandlerOf } from '@owlmeans/server-planning'
 import { makeMemoryPlanningStore } from '@owlmeans/server-planning/store'
 
 appendPlanningService(testContext, { store: makeMemoryPlanningStore({ sync: false }), plugins: [fixtures] })
-const cards = await planningFor(ctx, req, { channel: 'web' }).cards.list({ parent: projectId })
+const cards = await planningHandlerOf(ctx).planningFor(req, { channel: 'web' }).cards.list({ parent: projectId })
 ```
 
+## Native planning resources
+
+Register assignee type schemas through `schemas.assigneeTypes` or the facade's definitions.
+The scoped facade exposes versioned `assignees.create/update/retire`, `teams.create/update/remove`,
+`comments.create/update/remove` and derived `mentions` reads/rebuilds. Resource updates and
+removals require `{ version: record.version }`; they do not allocate card transitions.
+
+Supply a verified `assigneeId` in the trusted scope for comment authors. Hosts may also supply
+`defaultAssigneeId`; `@owlmeans/planning-auth` resolves verified authentication subjects and groups
+to planning ids and can attribute missing card reporters. Never accept author or organization
+claims from an untrusted resource request. Human authentication requirements come from assignee
+type schemas, while nicknames identify participants only within an organization entity.
+
+Use `teams.addMember/removeMember`, `teams.attach/detach`, `teams.members`, `teams.projects` and
+`teams.assignees`. They reuse the relationship store and preserve reusable organization teams.
+Schema reference fields maintain their canonical edges and named inverse views in the same
+organization unit. Explicit relationship writes cannot contradict a field-authoritative edge.
+
+`parent`, `parents` and derived `parentType` are the hierarchy. Schema parent/child rules validate
+creates and reparenting; recursive project scope is checked before paging, including comments,
+history, specifications and relationships. Project `mode` is access-policy metadata, separate
+from status. Deleting a card removes its comments and mention cache. Project purge follows
+current ancestry and retains unrelated organization assignees, reusable teams and reparented
+survivors, even when an older log or edge caches the deleted project id.
+
+Mount `resources: true` and `definitions: true` in the shared protocol tree, then bind stock
+`servePlanningEntrypoints`. Its access resolver authorizes resource commands and conceals records
+outside scope. Stock replies remove native `entityId` metadata from known record/envelope
+positions, while application fields, schema definitions and transition changes remain opaque.
+
 ## API
 
 - Service: `appendPlanningService`, `ensurePlanningService`, `makePlanningService`,
   `planningServiceApi`, `makePluginRegistry`, `makeStoreFacade`, `executeTransition`,
-  `PlanningServiceOptions`, `PlanningHostService`, `PlanningRuntime`, `PluginRegistry`
-- Handlers: `servePlanningEntrypoints`, `planningFor`, `listSchemas`, `listCards`,
+  `creatorHelper` (`creatorOf`, `withCreator`, `assertCreatorFixed`), `PlanningServiceOptions`, `PlanningHostService`,
+  `PlanningRuntime`, `PluginRegistry`
+- Handlers (one per file under `actions/`): `servePlanningEntrypoints`, `listSchemas`, `listCards`,
   `summarizeCards`, `getCard`, `listCardTransitions`, `listCardSpecifications`, `getSpecification`,
-  `listSpecificationRevisions`, `listLinks`, `getTransition`, `executePlanning`, `wireExecution`,
-  `executeOptionsOf`, `getCommit`, `watchCommits`, `PlanningHandlerOptions`, `PlanningScopeExtractor`
-- Scope: `scopeOf`, `actorOf`, `handlerFacade`, `planningServiceOf`, `concealed`, `assertScope`,
-  `notFoundOf`, `clampSeconds`
-- Projection: `makeProjectionProcessor`, `planningQueueHooks`, `ProjectionOptions`
-- Constants: `DEFAULT_ALIAS`, `MEMORY_STORE_ALIAS`, `DEFAULT_COMMIT_MEMORY`, `COMMIT_POLL_LADDER`
-- `@owlmeans/server-planning/store`: `makeMemoryPlanningStore`, `foldPending`, `failPending`,
-  `revisionsFromLog`, `commitEventOf`, `makeCommitHub`, `makeCompositeStore`, and the types
-  `BindablePlanningStore`, `CommitListener`, `CommitHub`, `CommitHubOptions`, `FoldOptions`,
-  `FoldResult`, `MemoryPlanningStore`, `MemoryPlanningStoreOptions`, `StoreRoute`
+  `listSpecificationRevisions`, `listLinks`, `getTransition`, `executePlanning`, `getCommit`,
+  `watchCommits`, `defineSchemas`, `applySchemaRequest`; `executionHelper` (`wireExecution`,
+  `executeOptionsOf`, `assertExecutionWrites`, `assertExecutionGranted`); `PlanningHandlerOptions`,
+  `PlanningScopeExtractor`, `PlanningAccessResolver`, `PlanningAccess`, `PlanningAccessGrants`,
+  `PlanningGrant`
+- Scope: `planningHandlerOf(ctx)` (`planningServiceOf`, `handlerScopeOf`, `handlerFacade`,
+  `planningFor`), `makeRequestScope(req)` (`scopeOf`, `accessScopeOf`, `actorOf`),
+  `makePlanningAccessModel(access)` (`assertGranted`, `writableIn`, `assertWrites`), `guardHelper`
+  (`concealed`, `assertScope`, `notFoundOf`, `clampSeconds`), `projectCriteriaOf`
+- Data-defined schemas: `makeDefinitions`, `makeSchemaViews`, `SchemaViews`, `SchemaViewsOptions`
+- Projection: `makeProjectionProcessor`, `makePlanningQueueHooks`, `ProjectionOptions`
+- Constants: `DEFAULT_ALIAS`, `MEMORY_STORE_ALIAS`, `DEFAULT_COMMIT_MEMORY`, `COMMIT_POLL_LADDER`,
+  `DEFAULT_SCHEMA_VIEWS`
+- `@owlmeans/server-planning/store`: `makeMemoryPlanningStore`, `foldHelper` (`foldPending`,
+  `failPending`, `revisionsFromLog`, `commitEventOf`), `makeCommitHub`, `makeCompositeStore`,
+  `wantsSpecifications`,
+  and the types `BindablePlanningStore`, `CommitListener`, `CommitHub`, `CommitHubOptions`,
+  `FoldOptions`, `FoldResult`, `MemoryPlanningStore`, `MemoryPlanningStoreOptions`, `StoreRoute`
+- `@owlmeans/server-planning/conformance`: `planningConformance`, `conformanceCasesFor`,
+  `planningConformancePlugin`, `conformanceClock`, `ConformanceFailure`, `assertHelper` (`check`,
+  `same`, `sameSet`, `rejects`), the library fixtures (`LIBRARY`, `conformanceFixturesOf(facade)` —
+  `createBranch`, `createBook`, `transit`)
+  and the types `ConformanceCase`, `ConformanceSubject`, `ConformanceCapability`
+- The former plain functions (`planningFor`, `foldPending`, `creatorOf`, `scopeOf`, `concealed`,
+  `planningQueueHooks`, `check`, `createBranch`, …) remain as deprecated delegates.
 
 ## Common pitfalls
 
+- A create's draft goes under `card` — `draft` is refused as `planning:malformed:create-without-draft`.
+- `{ wait: true }` is the SECOND argument of `execute`; inside the execution it is ignored and the
+  receipt returns before the commit.
+- A type or flow declaration has no `name` or `key`: the display name is `label`, the key is `type`
+  (a type) or `id` (a flow). `definitions.define` refuses anything else with `SchemaInvalid`; a code
+  plugin's registry does not check, so keep the literals typed.
+
 - `after` hooks run where the transition is FOLDED, once per commit — register the same plugins in
   every folding process, and never run hooks from a commit-bus subscription.
+- Organization locks are released before `after` hooks, so a hook may write into the same scope.
 - The memory store is per-process heap: wrong for multiple processes or restarts.
 - `actor` comes from the scope; a wire `actor` or `createdBy` is ignored.
+- A create's `createdBy` defaults to the scope's subject (`profileId`, else `userId`, else the
+  scope actor's) on every path — in-process facade and HTTP alike; an in-process draft that names
+  one keeps it, a scope naming nobody leaves it unset.
+- After the create `createdBy` never moves: an execution naming it in `changes` or `unset` is
+  refused with `planning:immutable:createdBy` — over HTTP, in process and from a `before` plugin.
 - Another entity's record is `WorkcardNotFound`, never a permission error.
 - Give retried writes a `key` — it is checked before validation, so a retry answers the first receipt.
 - `expectSeq` compares against `head`; a stale one is `WorkcardConflict`, re-read and retry.
 - Call `appendPlanningService` before any `ensurePlanningService`, or the appended host replaces
   what was registered on the default one.
+- `opts.access` makes the resolver the only source of the organization; a `grants` object refuses
+  every flag it leaves out.
+- A durable store is not done until it passes `@owlmeans/server-planning/conformance`.
+- Resource writes require their current `version`; assignee/team `fields` replace the previous
+  object, while card `changes.fields` merge. A field-backed relationship is changed through its
+  field, not by writing an independent link.
 
 ## Related packages
 
 - `@owlmeans/planning` — records, flows, fold, query language, protocol tree, models
 - `@owlmeans/client-planning` — the remote facade and state mirror
+- `@owlmeans/planning-postgres` — the durable Postgres store
 - `@owlmeans/server-job`, `@owlmeans/queue` — job feeds and the projection queue
 
 <!-- owlmeans:agent-guidance:start -->
@@ -141,7 +214,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.31
+npx @owlmeans/agent-skills@^0.1.18-rc.53
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/server-planning",
-  "version": "0.1.18-rc.3",
-  "generatedAt": "2026-09-21T21:54:22.941Z",
+  "version": "0.1.18-rc.31",
+  "generatedAt": "2026-10-10T22:28:00.509Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/server-planning/SKILL.md

@@ -8,12 +8,12 @@ user-invocable: false
 # @owlmeans/server-planning
 
 **Layer:** Server
-**Install:** `"@owlmeans/server-planning": "^0.1.18-rc.3"` in `dependencies` (`ajv` is a peer)
+**Install:** `"@owlmeans/server-planning": "^0.1.18-rc.31"` in `dependencies` (`ajv` is a peer)
 
 The general implementation of `@owlmeans/planning`: the planning service (a plugin host), the
 scoped facade, the executor every write goes through, the in-memory reference store, the commit
 hub and the protocol handlers. It holds no database code — a durable store implements the ports and
-reuses the `./store` subpath (`foldPending`, `makeCommitHub`) without pulling fastify in.
+reuses the `./store` subpath (`foldHelper.foldPending`, `makeCommitHub`) without pulling fastify in.
 
 ## Key exports
 
@@ -24,13 +24,18 @@ reuses the `./store` subpath (`foldPending`, `makeCommitHub`) without pulling fa
 | `makePlanningService(opts?, alias?)`, `planningServiceApi(opts, self)` | The service, and its body for a specialised service |
 | `PlanningServiceOptions` | `{ store?, plugins?, schemas?, hooks?, ids?, now? }` |
 | `makePluginRegistry`, `makeStoreFacade`, `executeTransition` | The pieces the service is made of |
-| `servePlanningEntrypoints(protocols, opts?)` | One binding per protocol of a `makePlanningProtocols` tree |
-| `planningFor(ctx, req, extra?)` | The request-scoped facade for a hand-written handler |
-| `PlanningHandlerOptions` | `{ service?, event?, maxPoll?, scope?(req, ctx) }` |
-| `listCards` … `executePlanning`, `getCommit`, `watchCommits` | The handlers, to bind one by hand |
-| `scopeOf(req, extra?)`, `actorOf(req)`, `concealed(run)`, `clampSeconds` | Scope and security helpers |
-| `makeProjectionProcessor(ctx, opts?)`, `planningQueueHooks(ctx, opts?)` | A generic projection job body and its `onJobDead` |
-| `./store`: `makeMemoryPlanningStore`, `foldPending`, `failPending`, `revisionsFromLog`, `commitEventOf`, `makeCommitHub`, `makeCompositeStore` | What stores are built from |
+| `creatorHelper` — `.creatorOf(scope)`, `.withCreator(exec, scope)`, `.assertCreatorFixed(exec)` | The subject a create is stamped with as `createdBy`, the defaulting the executor applies, and its refusal of any later move |
+| `servePlanningEntrypoints(protocols, opts?)` | One binding per protocol of a `makePlanningProtocols` tree (`schema.define` too when declared) |
+| `planningHandlerOf(ctx).planningFor(req, extra?)` | The request-scoped facade for a hand-written handler |
+| `PlanningHandlerOptions` | `{ service?, event?, maxPoll?, scope?(req, ctx), access?(req, ctx) }` |
+| `PlanningAccessResolver`, `PlanningAccess`, `PlanningAccessGrants`, `PlanningGrant` | The optional access decision a hosting app supplies |
+| `listCards` … `executePlanning`, `getCommit`, `watchCommits`, `listSchemas`, `defineSchemas`, `applySchemaRequest` | The handlers, to bind one by hand |
+| `makeRequestScope(req)` — `.scopeOf(extra?)`, `.accessScopeOf(access, extra?)`, `.actorOf()`; `planningHandlerOf(ctx).handlerScopeOf`; `makePlanningAccessModel(access)` — `.assertGranted`, `.assertWrites`, `.writableIn`; `executionHelper` — `.assertExecutionGranted`, `.assertExecutionWrites`; `guardHelper` — `.concealed(run)`, `.clampSeconds` | Scope and security helpers |
+| `makeDefinitions(runtime, facade)`, `makeSchemaViews(opts)`, `projectCriteriaOf(projects, through?)` | Data-defined schemas and the project narrowing |
+| `makeProjectionProcessor(ctx, opts?)`, `makePlanningQueueHooks(ctx, opts?)` | A generic projection job body and its `onJobDead` |
+| `./queue`: `declarePlanningQueue(cfg, opts?)`, `PLANNING_PROJECTION_QUEUE` (`planning-projection`), `PLANNING_PROJECT_JOB` (`planning:project`), `ProjectionRequest` | The projection queue's shared address; each process chooses separately whether to listen |
+| `./store`: `makeMemoryPlanningStore`, `foldHelper` (`.foldPending`, `.failPending`, `.revisionsFromLog`, `.commitEventOf`), `makeCommitHub`, `makeCompositeStore`, `wantsSpecifications` | What stores are built from |
+| `./conformance`: `planningConformance`, `conformanceCasesFor`, `planningConformancePlugin`, `conformanceClock`, `ConformanceFailure` | The store conformance suite, runner-agnostic |
 
 ## Wiring
 
@@ -58,30 +63,96 @@ context.registerEntrypoints(servePlanningEntrypoints(planningProtocols, {
   `ensurePlanningService(ctx).use(plugin)` works from `makeContext`, before `init()`.
 - Call `appendPlanningService` BEFORE any `ensurePlanningService`: `ensure` registers a default
   host when none exists, and a later `append` replaces it together with whatever was `use`d on it.
-- In code: `ctx.planning().for({ entityId, profileId?, channel?, actor? })` → a `PlanningFacade`
-  with no scope argument on any method.
+- **The facade:** `ctx.service<PlanningHostService>(PLANNING_SERVICE).for({ entityId, profileId?,
+  channel?, actor? })` → a `PlanningFacade` with no scope argument on any method. That form works
+  however the service was registered. `ctx.planning()` is only a shortcut that `appendPlanningService`
+  / `appendPostgresPlanning` install (typed `WithPlanningService`); a context that registered
+  `makePlanningService()` / `makePostgresPlanningService()` as a plain service — a generated target's
+  `services/planning.ts` — has no `ctx.planning` at all. In a request handler use
+  `planningHandlerOf(ctx).planningFor(req)`: the entity comes from `makeEntityScope(req).requireEntityKey()`, never the token.
+
+## Creating and reading a card
+
+```ts
+import { IntrinsicStatus, PLANNING_SERVICE, TransitionAction, WorkcardKind } from '@owlmeans/planning'
+import type { PlanningHostService } from '@owlmeans/server-planning'
+
+const planning = ctx.service<PlanningHostService>(PLANNING_SERVICE).for({ entityId, profileId })
+
+const shed = await planning.execute({
+  action: TransitionAction.Create,
+  card: { kind: WorkcardKind.Project, type: 'shed:shed', title: 'Maple Street shed' },
+}, { wait: true })
+const drill = await planning.execute({
+  action: TransitionAction.Create,
+  card: { kind: WorkcardKind.Card, type: 'shed:tool', parent: shed.card!.id!, title: 'Cordless drill',
+    fields: { brand: 'Acme' } },
+}, { wait: true })                      // drill.card — the committed record, status 'available'
+
+await planning.cards.get(drill.card!.id!)
+await planning.cards.list({ parent: shed.card!.id!, type: 'shed:tool' })
+await planning.execute({ action: TransitionAction.Transit, card: drill.card!.id!, transition: 'lend' }, { wait: true })
+
+// A card type and a flow as DATA, scoped to this shed — `definitions` exists only where the store
+// keeps schemas (planning-postgres; the memory store with `schemas: true`), and the shed's cards may
+// use them when its project type says `scopedCardTypes: true` (or lists the type in `cardTypes`).
+await planning.definitions!.define({
+  flows: [{
+    id: 'shed:repair', version: 1, label: 'Repair',
+    statuses: [
+      { key: 'reported', intrinsic: IntrinsicStatus.Planned, initial: true, label: 'Reported' },
+      { key: 'fixed', intrinsic: IntrinsicStatus.Closed, terminal: true, label: 'Fixed' },
+    ],
+    transitions: [{ name: 'fix', from: ['reported'], to: 'fixed', label: 'Mark fixed', explicit: true }],
+  }],
+  types: [{
+    type: 'shed:repair', kind: WorkcardKind.Card, version: 1, label: 'Repair ticket',
+    fields: { type: 'object', properties: { tool: { type: 'string' } }, additionalProperties: false },
+    flows: ['shed:repair'], specifications: [],
+  }],
+}, { project: shed.card!.id! })
+```
+
+| Wrong | What happens | Right |
+|---|---|---|
+| `execute({ action, draft: { … } })` | refused: `planning:malformed:create-without-draft` | the draft goes under `card` |
+| `execute({ …, wait: true })` | in process the key is ignored: the receipt returns before the commit, with no `card` — hidden while an inline-folding store (`planning-postgres`) lands at once, exposed the first time another process holds the card's fold | `execute({ … }, { wait: true })` — only the wire body (`ExecuteRequest`) carries `wait` inside |
+| `ctx.planning().for(…)` in a target | `ctx.planning is not a function` | `ctx.service<PlanningHostService>(PLANNING_SERVICE).for(…)` |
+| `{ id, name: 'Repair', … }` on a flow, `{ key, name, … }` on a type | `define` refuses with `SchemaInvalid` (closed schemas); a code plugin's registry does not validate, so the key is silently dropped | a flow's key is `id`, a type's is `type`, the display name is `label` on both |
+| `action: 'create'` | a type error — `TransitionAction` is an enum | `action: TransitionAction.Create` |
+
+Every wrong form is a compile error against the typed facade (`PlanningFacade`,
+`TransitionExecution`, `WorkcardTypeSchema`); it reaches run time only through a helper or a context
+typed `any`, so never type one that way. `tests/create-example.spec.ts` runs this example and each
+wrong form as written.
 
 ## The executor, step by step
 
 Nothing is appended before step 11 — every refusal leaves the log untouched.
 
-1. **Normalize** — deep copy, trimmed text, `parents ∋ parent` (first).
+1. **Normalize** — deep copy, trimmed text, `parents ∋ parent` (first); a create's draft without
+   `createdBy` gets `creatorHelper.creatorOf(scope)` (below).
 2. **Scope** — `entityId` must be present.
 3. **Idempotency** — a `key` already in the entity's log answers ITS receipt, before any
    validation or middleware.
-4. **Resolve** — the card (`WorkcardNotFound`; another entity's card is `PlanningScopeMismatch`),
-   its type and flow, every draft parent (`ParentNotFound`) and the parent project's
-   `cardTypes`/`projectTypes` (`CardTypeNotAllowed`), the specification slot.
+4. **Resolve** — the card (`WorkcardNotFound`; another entity's card is `PlanningScopeMismatch`;
+   one outside the scope's `projects` is `WorkcardNotFound`), its type and flow, every draft parent
+   (`ParentNotFound` — loaded through the facade, so an invisible parent is absent) and the parent
+   project's `cardTypes`/`projectTypes` (`CardTypeNotAllowed`), the specification slot. Where the
+   default store holds data-defined schemas, the card's project is found first and everything
+   after reads that project's resolved layer (`Resolved.schemas`): a data-defined type of a
+   project with `scopedCardTypes` is admitted, a retired type creates nothing
+   (`UnknownWorkcardType('retired:…')`). Without the port `Resolved.schemas` IS the code registry.
 5. **`before` chain** — in plugin order; re-resolved once when it changed the card, type or parent.
 6. **Validate** — shape (`planning:malformed:*`), the flow rule (`IllegalTransition`), immutables
-   (`planning:immutable:*`), merged `fields` (`FieldsInvalid`), labels (`LabelNotAllowed`), a moved
+   (`planning:immutable:*`, `createdBy` among them — `creatorHelper.assertCreatorFixed`), merged `fields` (`FieldsInvalid`), labels (`LabelNotAllowed`), a moved
    parent, the slot (`SpecificationSlotUnknown`, `SpecificationRevisionConflict`, JSON body schema
    → `FieldsInvalid`), relationships (`RelationshipRefused`: undeclared type, `from` not the card,
    missing target, type constraints, `single`, unlinking an absent edge).
-7. **Card id** — `store.newId?.() ?? options.ids?.() ?? uuid()`. Ids are the store's.
+7. **Card id** — `store.newId?.() ?? options.ids?.() ?? idHelper.uuid()`. Ids are the store's.
 8. **Code** — a supplied code is checked; else the plugins' `mintCode` (first answer wins, checked);
    else the type's `CodePolicy` (a slug policy derives from the title) → `CodeTaken`.
-9. **Changes** — `computeChanges`. An `update` that changes nothing answers the card's latest
+9. **Changes** — `changesHelper.computeChanges`. An `update` that changes nothing answers the card's latest
    receipt and appends nothing.
 10. **Seq** — `transitions.nextSeq(card, expectSeq)`, a CAS against `head` (`WorkcardConflict`).
 11. **Append** — `commit: pending`. A lost race on the key answers the winner's receipt.
@@ -92,6 +163,17 @@ Nothing is appended before step 11 — every refusal leaves the log untouched.
 `actor` is the SCOPE's: `profileId`/`userId`/`service`/`channel` come from the scope only; an
 in-process caller may add `agent`/`runId` on the execution. A handler never passes a wire `actor`.
 
+A create's `createdBy` is the scope's subject too — `creatorHelper.creatorOf(scope)`: `profileId`, else `userId`,
+else the same two of `scope.actor`. The executor stamps it on every path, so an in-process facade
+create and the HTTP `execute` produce the same owner. An in-process draft that names `createdBy`
+keeps it (explicit wins — a manager creating on someone's behalf); a scope naming nobody (a service
+or system scope) leaves it unset; the wire drops a draft's `createdBy` before the stamp.
+
+`createdBy` never moves after the create (the rule is `planning` → The record model). The executor
+enforces it itself with `creatorHelper.assertCreatorFixed` at step 6, after the `before` chain, so a wire body, an
+in-process caller and a plugin are refused alike, whatever `@owlmeans/planning` build the host
+resolves. The conformance suite checks a store folds a stored row naming it as the pure fold does.
+
 ## Idempotency and `expectSeq`
 
 - Give every retried or replayed write a `key` (`import:<source>:<n>`). The key is unique per entity
@@ -125,11 +207,15 @@ the store; `bind` replaces the listener, so a store has exactly one.
 
 ## The memory store
 
-`makeMemoryPlanningStore({ sync?, ids?, now?, seed?, onCommitted?, alias? })`
+`makeMemoryPlanningStore({ sync?, ids?, now?, seed?, onCommitted?, alias?, schemas? })`
 
 - Cards and projects in one map, specifications in their own, relationships in a third; every read
   goes through the `@owlmeans/resource` query engine. A card list includes specifications only when
-  the criteria asks for `kind: specification` or a `category`.
+  the criteria asks for `kind: specification` or a `category` (`wantsSpecifications`, the rule every
+  store routes by).
+- `schemas: true` adds the data-defined schema port (records per layer, a revision per
+  organization, synchronous `watch`); off by default — without it every type and flow resolves
+  from code.
 - `sync` (default) folds, publishes and runs `committed` inside `project()`, serialized per card.
   `sync: false` folds nothing until `flush(card?)` — a queued store's shape, for tests that need a
   commit to stay pending.
@@ -144,8 +230,8 @@ the store; `bind` replaces the listener, so a store has exactly one.
   answers the id format the host's references need (ObjectId hex for Mongo).
 - `transitions.list` treats `sinceSeq` as `seq > sinceSeq`; `nextSeq` is the CAS against `head` and
   answers 1 for a card that has no log.
-- The projection body is `foldPending(store, cardId, entityId, { onCommitted, publish, touch, limit })`:
-  it applies pending transitions with `applyTransition` only, marks each committed or failed,
+- The projection body is `foldHelper.foldPending(store, cardId, entityId, { onCommitted, publish, touch, limit })`:
+  it applies pending transitions with `applyHelper.applyTransition` only, marks each committed or failed,
   publishes, then runs `onCommitted`. The caller owns single flight per card. Strip `record` from
   the event before a cross-process bus.
 - **A failed transition never blocks the card.** The fold marks it `failed`, publishes a failed
@@ -153,13 +239,26 @@ the store; `bind` replaces the listener, so a store has exactly one.
   it was, and the next transition folds normally. Without that, every later transition fails as
   out of order and the card is stuck for good. Only two cases stop short: a failed `create` leaves
   no card to advance, and a store that refuses the advancing write stops the fold with `followUp`,
-  leaving the rest pending for a retry. `revisionsFromLog` replays past failed transitions the same
+  leaving the rest pending for a retry. `foldHelper.revisionsFromLog` replays past failed transitions the same
   way.
-- `failPending` is what a dead projection job must do, or waiters hang to their timeout.
+- A transactional store passes `FoldOptions.unit` — it wraps each transition's writes (a
+  savepoint), so a write the database refuses is undone whole and the fold marks that transition
+  failed and goes past it. `foldHelper.foldPending` folds PAST a failure it produces; a row that is ALREADY
+  failed at the cursor, or a gap in the seqs, is the store's to step over before calling it
+  (`planning-postgres` does it in a prelude).
+- `foldHelper.failPending` is what a dead projection job must do, or waiters hang to their timeout.
+- The data-defined schema port (`schemas`) is optional; `makeCompositeStore` passes the default
+  store's through. A store that has it must purge a project's layer with the project.
+- **Run the conformance suite.** `@owlmeans/server-planning/conformance` exports
+  `planningConformance` — named cases with no test runner inside (each throws
+  `ConformanceFailure`) — and `conformanceCasesFor(store)`, which drops the data-defined cases for a
+  store without the port. Boot a service with `planningConformancePlugin` and `conformanceClock()`
+  and hand each case `{ service, store, facade }`; every case works in its own organization, so one
+  boot serves them all.
 - `makeCommitHub({ status, remember?, ladder? })` is the `CommitSource`: feed `publish` from the bus,
   answer `status` from transition rows. `wait` subscribes first, polls once, then climbs the ladder.
-- `revisionsFromLog(transitions, limit?)` answers `specs.revisions`.
-- `makeProjectionProcessor(ctx)` + `planningQueueHooks(ctx)` are the store-agnostic job body and
+- `foldHelper.revisionsFromLog(transitions, limit?)` answers `specs.revisions`.
+- `makeProjectionProcessor(ctx)` + `makePlanningQueueHooks(ctx)` are the store-agnostic job body and
   `onJobDead`; a store with an admission CAS wraps its own around them.
 
 ## A foreign provider
@@ -180,24 +279,142 @@ mapping external records (`mappers`) belongs to that plugin's own store adapter.
 
 ## Scope and security
 
-- `entityId` is `requireEntityKey(req)`; `opts.scope(req, ctx)` adds a `channel` or `service` and
-  can never replace the entity. `actor` and a create's `createdBy` come from the request, never the
-  body.
+- Without `opts.access`: `entityId` is `makeEntityScope(req).requireEntityKey()`; `opts.scope(req, ctx)` adds a
+  `channel` or `service` and can never replace the entity. `actor` and a create's `createdBy` come
+  from the request, never the body (`executionHelper.wireExecution` drops a draft's claim, `creatorHelper.withCreator` stamps the
+  subject, `creatorHelper.assertCreatorFixed` refuses a body naming `createdBy` — an update never re-owns a card).
+- The organization of a scope is the one the request ACTS IN. `makeEntityScope(req).requireEntityKey()` answers
+  `req.entity.id`, the stable record id (the token's `entitySlug` only where no entity resolver is
+  registered). Behind an OIDC relying party (`@owlmeans/server-oidc-rp`) the acting organization is
+  session state: the guard attaches `req.entity` with `id` = the organization claim's frozen
+  `entityKey`, so the tenant key survives a rename and follows a switch. Take it in the handler and
+  pass it down; never read it from the context or from a body.
 - Another entity's card, specification or transition answers `WorkcardNotFound` — the same as an
-  absent id — on reads and writes alike (`concealed`).
-- Queries arrive in their wire form and are decoded with `decode*Query` before `criteriaOf`, which
+  absent id — on reads and writes alike (`guardHelper.concealed`).
+- Queries arrive in their wire form and are decoded with `wireHelper.decode*Query` before `queryHelper.criteriaOf`, which
   always adds the scope's `entityId`.
 
+### The access resolver
+
+`opts.access: (req, ctx) => Promise<{ entityId, projects?, writes?, grants? }>` is the hosting app's
+decision per request; a throw is the request's answer (an `AuthForbidden` answers 403).
+
+- `entityId` is the resolver's — never the token's, never `opts.scope`'s.
+- `projects` becomes `PlanningScope.projects`, which the server facade enforces on reads and
+  writes. A card is visible when at least one project reached through its recursive parent paths
+  is allowed; specifications follow their containing cards. Anything else reads as absent
+  (`WorkcardNotFound`, `null`, an empty list); a create under an invisible parent is
+  `ParentNotFound`. Links, transitions and commits use current endpoint/card ancestry, with a
+  cached project fallback only for purged records. Subscriptions and commit waits enforce the
+  same visibility.
+- **Narrowed lists, counts and summaries use the allowed recursive descendant IDs before paging.**
+  A specification is admitted through the same containing-card hierarchy as a single read.
+  Do not replace this with a direct-parent query or a filter applied after pagination.
+  `tests/narrowing.spec.ts` and shared hierarchy conformance pin this behavior.
+- A person who may see only SOME projects of their organization (a tool-shed volunteer given one
+  shed) is expressed here: the resolver answers the project ids the person's grants list as
+  `projects`, and omits the key when a grant covers every project — never a hand-written filter in
+  each handler.
+- `writes` is the subset of projects the person may WRITE in (`projects` are the ones they VIEW).
+  `execute` on a card, specification or link needs it to be writable — the recursive ancestor
+  rule over `writes`: a card admitted directly or through a writable parent path. A create needs
+  every named parent writable; reparenting checks every supplied destination parent. A create at the root
+  (no parent, not a project) is refused. `schema.define` of a project layer needs the project in
+  `writes`. A refusal is `PlanningForbidden` (403, `forbidden:writes:<id>`), checked before the grants
+  and before the executor. NOT governed by it: a project create (`grants.createProjects` alone) and
+  the organization layer (`grants.defineSchemas`). A card the scope cannot see is still answered
+  as absent by the executor. Omitted — every visible project is writable.
+  `tests/writes.spec.ts` pins viewer, writer and omitted.
+- `grants` gates the stock handlers' writes: `createProjects` (a project create — `true` for the
+  root, a list names the parent projects), `deleteProjects` (the delete of a project card — a list
+  names the projects), `defineSchemas` (`schema.define` — `true` for the organization's layer, a
+  list names project layers). A `grants` object refuses every flag it leaves out with
+  `PlanningForbidden` (403); no `grants` gates nothing. In-process facade writes are not gated.
+
+## Mounting in a target
+
+The api half of the target mount (the common tree and the kit literals: `planning` → Mounting in a
+target).
+
+- Bind `servePlanningEntrypoints(tree, { access })` WITHOUT the commit socket —
+  `.filter(entrypoint => entrypoint.protocol !== tree.commit.events)`: nothing authenticates a
+  target's socket after it opens, so the client long-polls (`commit.get` with `wait`, `execute`
+  with `wait: true`). Never write card, transition or schema routes beside it.
+- The resolver maps container permissions onto the access: `projects` = the containers the person
+  may view, `writes` = those they may modify, `grants` = `createProjects` / `deleteProjects` /
+  `defineSchemas` from their create and admin rights. A creator sees what they created — stamp
+  ownership in a `before` hook and add the card to both lists.
+
+## Data-defined types and flows
+
+Where the default store has the schema port, `runtime.schemasFor(entityId, project?)` answers the
+resolved layer (`scopedSchemaHelper.resolveScopedBundle` over the code bundle and the organization's and project's
+records), cached per (organization, project) and keyed by the store's `revision()` and the plugin
+registry's version — a write anywhere moves the revision the next lookup reads, so a cached layer is
+never stale; a store's `watch` evicts early. Without the port it answers the code registry itself.
+`makeDefinitions` gives the facade `definitions`: every write checks the project (a project card the
+scope can see), the seal, the closed-form checks (a type's flows resolve in its layer, counting flows
+written beside it), then the store's compare-and-set. `retire` of a flow refuses with `SchemaInUse`
+while a live type of the layer — or of any project layer, for an organization record — still runs
+it. `facade.model(card)` builds over the layer of the card's own project, and `schema.list` answers
+the scoped bundle (`?project=`) where `definitions` exists, the code bundle otherwise.
+
 ## Testing
 
 Category A. Build one real context with `makeBasicContext` + `appendPlanningService({ store:
 makeMemoryPlanningStore({ now }), plugins: [fixtures] })`, and run a handler through
 `handler.bind({ ref: { ctx } })(req, res)` with a request carrying `auth` and `entity`. A monotonic
 `now` keeps log order deterministic; `sync: false` + `flush()` pins pending and hook-count cases.
+`tests/conformance.spec.ts` runs the conformance suite against the memory store with and without
+`schemas: true`; a durable store's own tests run the same cases against a real database.
+
+## Auxiliary resources and hierarchy admission
+
+`facade.assignees`, `.teams`, `.comments`, `.mentions` use native versioned ports of
+`PlanningStore`. The stock memory, PostgreSQL and Mongo stores implement them. Mutations run
+inside the store's organization `unit`; CAS, nickname/authentication uniqueness, schema layers,
+canonical links and mentions are validated there. Missing ports raise `PlanningUnsupported`. Assignee type changes recheck incoming typed card
+references against the proposed type; a change cannot invalidate a persisted assignment.
+Do not add a second host-specific planning resource CRUD layer.
+
+`assignees.list({ retired: false })` means every identity not explicitly retired, including
+records with an absent or null retirement flag. The facade translates it to `{ retired: { $ne: true } }`
+before the native port reads; `retired: true` selects historical identities and an omitted filter
+retains both. Keep this predicate consistent with client mirrors and run its shared conformance
+case against memory, PostgreSQL and Mongo; a bare equality to false hides newly created identities.
+
+The request scope supplies trusted `assigneeId` for comment authors and optional
+`defaultAssigneeId` for newly created cards. HTTP handlers stamp actor/organization context;
+`makePlanningAuth(...).scopeFor` resolves OwlMeans identities when that integration is enabled.
+Access resolvers can grant `manageAssignees` and `manageTeams` separately from card writes.
+Comments and project/team attachment require writable containing cards/projects. Auxiliary
+organization lists require authenticated organization scope; do not infer ACLs from project mode.
+
+All stock HTTP replies use `guardHelper.reply`, which conceals scope failures and applies the
+typed planning reply projection. Socket commits use the same projection. Organization `entityId`
+stays in native records and verified scopes, and never leaves through records, schema scopes or
+nested receipts. Keep business fields and schema definitions unchanged when projecting replies.
+
+Admission and native projection recheck hierarchy, schema fields and endpoint types. Recursive
+visibility follows every project ancestor and filters before paging. Definition record reads
+use the same recursive visibility as cards. Reparenting validates all
+descendants under the prospective schema layer. Ordinary parent deletion refuses existing
+children; project purge removes its descendants, comments, mentions, scoped schemas and links,
+while retaining organization assignees and reusable teams. Field-backed edges are reconciled in
+the persistence unit; named inverse edges are derived read views, never duplicate persisted rows.
+
+Run shared conformance with `resources` and `schemas` capabilities against each native provider;
+cover version races, stable mentions, reusable teams, field references, hierarchy and narrowed ACLs.
+
 
 ## Related
 
 - `planning` — records, flows, the fold, the query language, the protocol tree, the models
 - `client-planning` — the remote facade and the state mirror that talk to these handlers
+- `planning-postgres` — the durable Postgres store built from these pieces
 - `server-job`, `queue` — the declare/serve/feed pattern and the projection queue
 - `resource` — the criteria engine every memory read goes through
+
+Project purge uses current card ancestry as ownership. A surviving reparented card retains its
+complete transition history, documents and edges even when their cached project id names its former
+project. Cached project values may select orphaned records, but must never delete surviving records.

package/build/actions/apply-schema-request.d.ts

@@ -0,0 +1,8 @@
+import { type PlanningDefinitions, type SchemaDefineReply, type SchemaDefineRequest } from '@owlmeans/planning';
+/**
+ * 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 declare const applySchemaRequest: (definitions: PlanningDefinitions, request: SchemaDefineRequest) => Promise<SchemaDefineReply>;
+//# sourceMappingURL=apply-schema-request.d.ts.map

package/build/actions/apply-schema-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-schema-request.d.ts","sourceRoot":"","sources":["../../src/actions/apply-schema-request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,KAAK,mBAAmB,EAA2B,MAAM,oBAAoB,CAAA;AAEzJ;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,gBAChB,mBAAmB,WAAW,mBAAmB,KAC7D,OAAO,CAAC,iBAAiB,CA0B3B,CAAA"}

package/build/actions/apply-schema-request.js

@@ -0,0 +1,33 @@
+import { SchemaWriteMode } from '@owlmeans/planning';
+/**
+ * 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, request) => {
+    const layer = request.project != null ? { project: request.project } : {};
+    const declarations = { types: request.types ?? [], flows: request.flows ?? [], assigneeTypes: request.assigneeTypes ?? [] };
+    const records = [];
+    switch (request.mode ?? SchemaWriteMode.Define) {
+        case SchemaWriteMode.Put:
+            for (const schema of declarations.assigneeTypes)
+                records.push(await definitions.putAssigneeType(schema));
+            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) };
+};
+//# sourceMappingURL=apply-schema-request.js.map

package/build/actions/apply-schema-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-schema-request.js","sourceRoot":"","sources":["../../src/actions/apply-schema-request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAuG,MAAM,oBAAoB,CAAA;AAEzJ;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,EACrC,WAAgC,EAAE,OAA4B,EAClC,EAAE;IAC9B,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IACzE,MAAM,YAAY,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,EAAE,EAAE,CAAA;IAC3H,MAAM,OAAO,GAAyB,EAAE,CAAA;IAExC,QAAQ,OAAO,CAAC,IAAI,IAAI,eAAe,CAAC,MAAM,EAAE,CAAC;QAC/C,KAAK,eAAe,CAAC,GAAG;YACtB,KAAK,MAAM,MAAM,IAAI,YAAY,CAAC,aAAa;gBAAE,OAAO,CAAC,IAAI,CAAC,MAAM,WAAW,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAA;YACxG,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,KAAK,EAAE,CAAC;gBACtC,OAAO,CAAC,IAAI,CAAC,MAAM,WAAW,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAA;YACtD,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,KAAK,EAAE,CAAC;gBACtC,OAAO,CAAC,IAAI,CAAC,MAAM,WAAW,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAA;YACtD,CAAC;YACD,MAAK;QACP,KAAK,eAAe,CAAC,IAAI;YACvB,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC,CAAA;YAC5D,MAAK;QACP;YACE,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC,CAAA;IAClE,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QACvC,OAAO,CAAC,IAAI,CAAC,MAAM,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAA;IAClE,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAA;AACvE,CAAC,CAAA"}