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

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.9 @owlmeans/planning@^0.1.18-rc.8 ajv
+bun add @owlmeans/server-planning@^0.1.18 @owlmeans/planning@^0.1.18 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.9 @owlmeans/planning@^0.1.18-rc.8 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.36
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 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,
+  "schemaVersion": 3,
   "package": "@owlmeans/server-planning",
-  "version": "0.1.18-rc.9",
-  "generatedAt": "2026-09-22T22:22:19.434Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.706Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {
@@ -10,7 +10,108 @@
       "name": "server-planning",
       "category": "package-specific",
       "file": "skills/server-planning/SKILL.md",
-      "canonicalPath": ".agents/skills/server-planning/SKILL.md"
+      "canonicalPath": ".agents/skills/server-planning/SKILL.md",
+      "parts": [
+        {
+          "name": "auxiliary",
+          "file": "skills/server-planning/parts/auxiliary.md",
+          "description": "Assignees, teams, comments and mentions on native store ports, the reply projection, hierarchy admission and project purge.",
+          "purposes": [
+            "planning",
+            "data"
+          ],
+          "mentions": [
+            "facade.assignees",
+            "facade.teams",
+            "facade.comments",
+            "facade.mentions",
+            "manageAssignees",
+            "manageTeams",
+            "defaultAssigneeId",
+            "makePlanningAuth",
+            "guardHelper.reply"
+          ]
+        },
+        {
+          "name": "executor",
+          "file": "skills/server-planning/parts/executor.md",
+          "description": "The transition executor step by step (refusal order, actor and createdBy stamping) and the plugin seam (registration, order, store routing, before/after hooks).",
+          "purposes": [
+            "planning",
+            "server-api"
+          ],
+          "mentions": [
+            "executeTransition",
+            "creatorHelper",
+            "makePluginRegistry",
+            "ensurePlanningService",
+            "PlanningRefused",
+            "mintCode",
+            "WorkcardConflict"
+          ]
+        },
+        {
+          "name": "schemas",
+          "file": "skills/server-planning/parts/schemas.md",
+          "description": "Data-defined card types and flows — the resolved layer per organization and project, the facade's definitions, retiring a flow.",
+          "purposes": [
+            "data",
+            "planning",
+            "config"
+          ],
+          "mentions": [
+            "makeDefinitions",
+            "makeSchemaViews",
+            "schemasFor",
+            "scopedSchemaHelper",
+            "definitions",
+            "SchemaInUse"
+          ]
+        },
+        {
+          "name": "serving",
+          "file": "skills/server-planning/parts/serving.md",
+          "description": "The commit feed, request scope and security, the access resolver (projects, writes, grants), and mounting the handlers in a target.",
+          "purposes": [
+            "server-api",
+            "auth",
+            "planning"
+          ],
+          "mentions": [
+            "servePlanningEntrypoints",
+            "planningHandlerOf",
+            "PlanningAccessResolver",
+            "makeRequestScope",
+            "makePlanningAccessModel",
+            "guardHelper",
+            "executionHelper",
+            "PlanningForbidden"
+          ]
+        },
+        {
+          "name": "stores",
+          "file": "skills/server-planning/parts/stores.md",
+          "description": "The in-memory store, writing a durable or foreign store (ports, foldHelper.foldPending, the commit hub, the conformance suite), and testing against the memory store.",
+          "purposes": [
+            "data",
+            "planning",
+            "test"
+          ],
+          "mentions": [
+            "makeMemoryPlanningStore",
+            "PlanningStore",
+            "foldHelper",
+            "makeCommitHub",
+            "makeCompositeStore",
+            "planningConformance",
+            "conformanceCasesFor",
+            "planningConformancePlugin",
+            "makeProjectionProcessor",
+            "@owlmeans/server-planning/store",
+            "@owlmeans/server-planning/conformance"
+          ]
+        }
+      ]
     }
   ]
 }

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.9"` in `dependencies` (`ajv` is a peer)
+**Install:** `"@owlmeans/server-planning": "^0.1.18"` 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
 
@@ -22,15 +22,20 @@ reuses the `./store` subpath (`foldPending`, `makeCommitHub`) without pulling fa
 | `appendPlanningService(ctx, opts?, alias?)` | Registers the lazy host service and `ctx.planning()` |
 | `ensurePlanningService(ctx, alias?)` | Idempotent — what a plugin package calls before `use` |
 | `makePlanningService(opts?, alias?)`, `planningServiceApi(opts, self)` | The service, and its body for a specialised service |
-| `PlanningServiceOptions` | `{ store?, plugins?, schemas?, hooks?, ids?, now? }` |
+| `PlanningServiceOptions` | `{ store?, plugins?, schemas?, hooks?, ids?, now? }` — `schemas.app` is the first source the plugins' `schemas.app` merge over |
 | `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,39 +63,69 @@ 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 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).
-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.
-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
-   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.
-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
-   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.
-12. **Project** — `store.cards.project(card)`: a sync store folds now, a queued one enqueues.
-13. **Receipt** — `{ transition, card? (once committed), committed(opts) }`.
-14. **`wait: true`** — `committed()` before returning (`CommitTimeout`, `CommitFailed`).
-
-`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`.
+- **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 |
+| `{ …, description: '…' }` on a type or a flow | `SchemaInvalid` (closed schemas) | `app: { description }`, with `schemas.app.type` / `.flow` declaring `description` (`planning` → types part) |
+| `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.
 
 ## Idempotency and `expectSeq`
 
@@ -100,104 +135,20 @@ in-process caller may add `agent`/`runId` on the execution. A handler never pass
   see the same `seq` but only one wins the head. `null` or omitted opts out; a model fills it from
   its record.
 
-## The plugin seam
-
-| Concern | Rule |
-|---|---|
-| Registration | `use(plugin)` replaces by `name`; schemas are contributed at `use` time (later type/flow id wins) |
-| Order | `order ?? 50` ascending, registration order among equals |
-| Store routing | `store(type)` = the first plugin whose `owns(type)` is true AND that supplies a `store`; else the default store. A store factory is resolved once |
-| Reads | By id: the default store, then each owned store. A list naming one owned type (or several owned by one store) goes there; any other list — a cross-type query — is the default store's alone |
-| `mintCode` | First non-`undefined` answer wins |
-| `before` | Every plugin in order; may return a replaced execution; a `ResilientError` passes through, anything else becomes `PlanningRefused('<plugin>:<message>')` |
-| `after` | Every plugin in order, once per COMMITTED transition; errors logged, never rethrown |
-
-**Where `after` runs.** The service's `committed(event)` runs the chain, and it is called by the
-process that FOLDS the transition — the memory store inside `project()`, a queued store's projection
-job after marking the commit. Never subscribe a process to the commit bus to run hooks: that fires
-once per subscribed process. Every process that folds registers the same plugins; each commit is
-folded by one of them, so each hook fires once. `hooks: false` makes a process fold without running
-them. A hook sees `ctx.transition` (read back, so `actor.channel` is available) and a facade scoped
-to the event's entity acting as this process's `cfg.service`.
-
-The service hands `committed` to a store through `store.bind?.(listener)` the first time it resolves
-the store; `bind` replaces the listener, so a store has exactly one.
-
-## The memory store
-
-`makeMemoryPlanningStore({ sync?, ids?, now?, seed?, onCommitted?, alias? })`
-
-- 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`.
-- `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.
-- A project `delete` purges the project, everything whose `parents` reach it, their specifications,
-  links and log; the commit hub remembers the settled event so the waiter still gets its answer.
-- **It is wrong for more than one process or a restart** — the log, the cards and the commit feed
-  are this process's heap. Use it for tests, tools and single-process demos.
-
-## Writing a durable store
-
-- Implement `PlanningStore` (`transitions`, `cards`, `specs`, `links`, `commits`, `newId`). `newId`
-  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,
-  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
-  event, and goes PAST it: the card's `seq` advances to that transition with every other value as
-  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
-  way.
-- `failPending` is what a dead projection job must do, or waiters hang to their timeout.
-- `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
-  `onJobDead`; a store with an admission CAS wraps its own around them.
-
-## A foreign provider
-
-Only `cards` is required. A plugin that `owns` its types and supplies a store without
-`transitions` can be read through the facade; writes to it refuse with `PlanningUnsupported` —
-mapping external records (`mappers`) belongs to that plugin's own store adapter.
-
-## The commit feed
-
-- **Poll** — `commit.get` answers the status; with `?wait=<s>` (clamped to `maxPoll`, default 55)
-  it subscribes, re-polls, and holds until the commit settles or the time is up, answering `pending`
-  then — never an error.
-- **Notify** — `commit.events` pushes `planning-commit` frames (or `opts.event`) filtered by the
-  authenticated entity and optional `project`/`card` query values; a frame without `record` gets the
-  card as it reads now. The subscription is released on the socket's `close` frame.
-- `execute` with `wait: true` holds at most `maxPoll` seconds whatever `timeout` the body asked for.
-
-## 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.
-- 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
-  always adds the scope's `entityId`.
-
-## 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.
-
 ## 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
+
+## Parts
+
+| Part | Load it when |
+|---|---|
+| [executor](parts/executor.md) | writing a planning plugin, or diagnosing why a transition was refused or never committed |
+| [stores](parts/stores.md) | choosing or writing a store, or testing planning code |
+| [serving](parts/serving.md) | binding the planning handlers, writing an access resolver, or narrowing what a person sees or writes |
+| [schemas](parts/schemas.md) | defining or retiring types and flows as data |
+| [auxiliary](parts/auxiliary.md) | working with assignees, teams, comments or mentions, or with reparenting and purge |

package/agent-meta/skills/server-planning/parts/auxiliary.md

@@ -0,0 +1,54 @@
+---
+name: auxiliary
+description: Assignees, teams, comments and mentions on native store ports, the reply projection, hierarchy admission and project purge.
+metadata:
+  purposes: planning, data
+  mentions: facade.assignees, facade.teams, facade.comments, facade.mentions, manageAssignees, manageTeams, defaultAssigneeId, makePlanningAuth, guardHelper.reply
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/server-planning — Auxiliary resources and hierarchy admission
+
+## 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 deletion refuses a card with child cards
+(`hierarchy:parent-in-use`, from `makePlanningHierarchy().validate(card, true)`); the card's own
+documents (`hierarchy.documents`) never refuse it — the delete's fold drops them with it, and the
+incoming field-reference check counts them among what goes. 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.
+
+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.