@owlmeans/planning 0.1.18-rc.2 → 0.1.18-rc.20

package/README.md

@@ -9,20 +9,21 @@ the executor with `@owlmeans/server-planning` and reads remotely with `@owlmeans
 ## Installation
 
 ```sh
-bun add @owlmeans/planning@^0.1.18-rc.2 ajv ajv-formats
+bun add @owlmeans/planning@^0.1.18-rc.20 ajv ajv-formats
 ```
 
 ## Concepts
 
 - **Transition** — the only way a record changes: an append-only event; a card is the fold of its
-  transitions in `seq` order (`applyTransition`).
+  transitions in `seq` order (`applyHelper.applyTransition`).
 - **Workcard** — base fields at the top level (`title`, `status`, `parent`, `parents`, `labels`,
   `order`); a type's own fields under `fields`, validated by the type's schema.
 - **Status flow** — shareable data declaring statuses (each mapped to `planned`, `in-progress` or
   `closed`) and named transitions; a type may run several flows.
 - **Specification** — a document workcard held in a slot the parent type declares; a revisioned
   slot revises one record in place.
-- **Wire query** — the scalar form a query travels in over HTTP (`encode*Query` / `decode*Query`).
+- **Wire query** — the scalar form a query travels in over HTTP (`wireHelper.encode*Query` /
+  `wireHelper.decode*Query`).
 
 ## Usage
 
@@ -69,13 +70,27 @@ export const planningProtocols = makePlanningProtocols({
 Encode a query on the client, decode it in a handler:
 
 ```ts
-import { criteriaOf, decodeWorkcardQuery, encodeWorkcardQuery } from '@owlmeans/planning'
+import { queryHelper, wireHelper } from '@owlmeans/planning'
 
-const query = encodeWorkcardQuery({ parent: projectId, status: ['todo', 'doing'], sort: ['order'] })
+const query = wireHelper.encodeWorkcardQuery({ parent: projectId, status: ['todo', 'doing'], sort: ['order'] })
 const page = await context.entrypoint(planningProtocols.card.list).call({ query })
 
 // server side
-const where = criteriaOf(decodeWorkcardQuery(req.query), { entityId })
+const where = queryHelper.criteriaOf(wireHelper.decodeWorkcardQuery(req.query), { entityId })
+```
+
+Create a card and read it back through a facade — in process the one of `@owlmeans/server-planning`
+(`ctx.service<PlanningHostService>(PLANNING_SERVICE).for({ entityId, profileId })`), remotely the one
+of `@owlmeans/client-planning`:
+
+```ts
+import { TransitionAction, WorkcardKind } from '@owlmeans/planning'
+
+const drill = await planning.execute({
+  action: TransitionAction.Create,
+  card: { kind: WorkcardKind.Card, type: 'shed:tool', parent: shedId, title: 'Cordless drill' },
+}, { wait: true })                     // the options are the SECOND argument
+const again = await planning.cards.get(drill.card!.id!)
 ```
 
 Work through a model — the same code on either side of the wire:
@@ -93,10 +108,10 @@ await task.update({ title: 'Renamed' }) // expectSeq defaults to the record's he
 Fold transitions yourself (a mirror, a test, a store):
 
 ```ts
-import { applyRelationship, applyTransition } from '@owlmeans/planning'
+import { applyHelper } from '@owlmeans/planning'
 
-const card = transitions.reduce((current, transition) => applyTransition(current, transition), undefined)
-const links = transitions.reduce(applyRelationship, [])
+const card = transitions.reduce((current, transition) => applyHelper.applyTransition(current, transition), undefined)
+const links = transitions.reduce(applyHelper.applyRelationship, [])
 ```
 
 ## API
@@ -107,48 +122,76 @@ const links = transitions.reduce(applyRelationship, [])
 - Write path and feed: `TransitionExecution`, `WorkcardDraft`, `ExecuteRequest`,
   `TransitionReceipt`, `TransitionReceiptView`, `CommitEvent`, `CommitStatus`, `CommitSource`.
 - Ports and seam: `TransitionStore`, `ProjectionStore`, `SpecificationStore`, `RelationshipStore`,
-  `PlanningStore`, `PlanningPlugin`, `PlanningScope`, `PlanningFacade`, `PlanningService`.
+  `SchemaStore`, `PlanningStore`, `PlanningPlugin`, `PlanningScope`, `PlanningFacade`,
+  `PlanningService`, `PlanningDefinitions`.
+- Data-defined types and flows: `ScopedSchemaRecord`, `ScopedSchemaWhere`, `ScopedSchemaBundle`,
+  `ScopedSchemaRegistry`, `SchemaDeclarations`, `SchemaWriteOptions`, `SchemaDefineRequest`,
+  `SchemaDefineReply`, and `scopedSchemaHelper` (`resolveScopedBundle`, `scopedRegistryOf`,
+  `assertTypeSchema`, `assertFlowSchema`, `assertOverridable`, `flowInUse`, `schemaRecordKey`,
+  `schemaKeyOf`).
 - Enums and constants: `WorkcardKind`, `IntrinsicStatus`, `IntrinsicPolicy`, `TransitionAction`,
-  `CommitState`, `SpecificationFormat`, `CodeStyle`, `CodeScope`, `PLANNING_SERVICE`,
-  `PLANNING_PATH`, `PLANNING_COMMIT_EVENT`, `planningAliases`, limits (`TITLE_MAX`, …).
-- Fold and changes: `applyTransition`, `applyRelationship`, `computeChanges`, `isEmptyChange`,
-  `assertMutable`, `mergeFields`, `applyUnset`.
-- Status: `intrinsicOf`, `initialStatusOf`, `ruleOf`, `canTransit`, `transitionsFrom`,
-  `initialFlowsOf`, `resolveIntrinsic`, `primaryFlowOf`, `isTerminal`.
-- Query: `criteriaOf`, `listOptionsOf`, `specCriteriaOf`, `linkWhereOf`, `transitionWhereOf`,
-  `summaryOf`, `encode/decodeWorkcardQuery`, `encode/decodeSummaryQuery`,
-  `encode/decodeTransitionQuery`, `encode/decodeSpecificationQuery`,
-  `encode/decodeRelationshipQuery`.
-- Codes, specifications, validation: `mintCode`, `codeScopeOf`, `slotOf`, `currentSpecification`,
-  `nextRevision`, `specificationTypeOf`, `makeAjv`, `validateFields`, `validateCard`,
-  `validateSpecificationBody`.
+  `CommitState`, `SpecificationFormat`, `CodeStyle`, `CodeScope`, `PlanningSchemaKind`,
+  `SchemaOrigin`, `SchemaWriteMode`, `PLANNING_SERVICE`, `PLANNING_PATH`, `PLANNING_COMMIT_EVENT`,
+  limits (`TITLE_MAX`, …); `planningAliasHelper` (`planningAliases`, `planningDefinitionAliases`).
+- Helpers — each a ready object (`xxxHelper`) built by its `createXxxHelper()`, its interface
+  exported beside it:
+  - `applyHelper` — the fold: `applyTransition`, `applyRelationship`.
+  - `changesHelper` — `computeChanges`, `isEmptyChange`, `assertMutable`, `mergeFields`,
+    `applyUnset`, `sameValue`.
+  - `cardHelper` — `isProject`, `isCard`, `isSpecification`, `normalizeParents`, `cardDefaults`,
+    `isPending`, `parentOf`, `projectOf`.
+  - `statusHelper` — `intrinsicOf`, `initialStatusOf`, `ruleOf`, `canTransit`, `transitionsFrom`,
+    `initialFlowsOf`, `resolveIntrinsic`, `primaryFlowOf`, `flowIdsOf`, `statusDefinitionOf`,
+    `isTerminal`.
+  - `queryHelper` — `criteriaOf`, `listOptionsOf`, `specCriteriaOf`, `linkWhereOf`,
+    `transitionWhereOf`, `summaryOf`.
+  - `wireHelper` — `encode/decodeWorkcardQuery`, `encode/decodeSummaryQuery`,
+    `encode/decodeTransitionQuery`, `encode/decodeSpecificationQuery`,
+    `encode/decodeRelationshipQuery`, `encode/decodeList`, `encode/decodeSort`.
+  - `codeHelper` — `mintCode`, `codeScopeOf`, `slugOf`.
+  - `specificationHelper` — `slotOf`, `currentSpecification`, `nextRevision`, `isRevisioned`,
+    `bodyCharsOf`, `specificationTypeOf`.
+  - `validateHelper` — `validateFields`, `validateCard`, `validateSpecificationBody`,
+    `invalidFieldKeys`, `ajvErrorText`; and `makeAjv`.
+- The former plain functions (`applyTransition`, `criteriaOf`, `encodeWorkcardQuery`, …) remain as
+  deprecated delegates to these helpers.
 - Registry, protocols, models: `makeSchemaRegistry`, `makePlanningProtocols`, `makeWorkcardModel`,
   `makeProjectModel`, `makeSpecificationModel`, `modelOf`.
 - Errors: `PlanningError`, `WorkcardNotFound`, `UnknownWorkcardType`, `UnknownStatusFlow`,
   `ParentNotFound`, `CardTypeNotAllowed`, `PlanningRefused`, `IllegalTransition`, `FieldsInvalid`,
   `LabelNotAllowed`, `SpecificationSlotUnknown`, `SpecificationRevisionConflict`,
   `RelationshipRefused`, `CodeTaken`, `WorkcardConflict`, `CommitTimeout`, `CommitFailed`,
-  `PlanningScopeMismatch`, `PlanningUnsupported`.
+  `PlanningScopeMismatch`, `SchemaConflict`, `SchemaInUse`, `SchemaSealed`, `SchemaInvalid`,
+  `PlanningForbidden`, `PlanningUnsupported`.
 - Schemas: `WorkcardSchema`, `SpecificationSchema`, `TransitionSchema`, `ExecuteRequestSchema`,
   `WorkcardQuerySchema`, … (every record, declaration, request and view).
 
 ## Common pitfalls
 
+- A create's draft goes under `card` (never `draft`), and `{ wait, timeout }` is the second argument
+  of `execute` — inside the execution an in-process facade ignores it.
+- 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); a status has `key`, a transition rule `name`. The declaration schemas
+  are closed — `definitions.define` refuses an extra key with `SchemaInvalid`.
 - Pass a query through `encode*Query` before an HTTP call — arrays and objects do not survive a
   query string as they are.
 - `status`, `intrinsic` and `flows` move only through `transit`; an `update` naming them is refused.
+- `createdBy` is written once, by a create's draft: `changes` or `unset` naming it is refused on
+  every action (`planning:immutable:createdBy`), so an ownership check can trust it.
 - `fields` and `flows` in `changes` merge; every other key replaces. Clear with `null` or `unset`.
 - A model's `expectSeq` is its record's head: a stale model refuses with `WorkcardConflict`.
 - `WorkcardNotFound` is also the answer for another entity's card — never read it as "deleted".
 - `CommitTimeout` leaves the transition pending; it will still commit.
 - Keep schemas `$jsonSchema`-safe: no `integer`, every optional property nullable.
+- Only card types and flows are data-defined, and a code key needs `overridable: true` to be
+  overridden; a data-defined declaration's `version` is its compare-and-set token.
 
 ## Related packages
 
 - `@owlmeans/server-planning` — executor, plugin registry, memory store, handlers
 - `@owlmeans/client-planning` — remote facade, state mirror, commit waiting
 - `@owlmeans/resource` — the criteria language
-- `@owlmeans/server-planning` — server execution and projection implementations
+- `@owlmeans/planning-postgres` — the durable Postgres store
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -158,7 +201,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.30
+npx @owlmeans/agent-skills@^0.1.18-rc.51
 ```
 
 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/planning",
-  "version": "0.1.18-rc.2",
-  "generatedAt": "2026-09-19T13:42:56.252Z",
+  "version": "0.1.18-rc.20",
+  "generatedAt": "2026-10-06T11:45:57.665Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -1,6 +1,6 @@
 ---
 name: planning
-description: How to use @owlmeans/planning — the runtime-free workcard model (cards, projects, specifications), typed relationships, shareable status flows with three intrinsic states, the Transition event and its pure fold, the schema registry, the query language and its wire encoding, the protocol tree, and the models that work identically on a server and in a browser. Auto-invoked when importing a Workcard type, a status flow, applyTransition, computeChanges, criteriaOf, encodeWorkcardQuery, makePlanningProtocols or a planning model.
+description: How to use @owlmeans/planning — the runtime-free workcard model (cards, projects, specifications), typed relationships, shareable status flows with three intrinsic states, the Transition event and its pure fold, the schema registry, the query language and its wire encoding, the protocol tree, and the models that work identically on a server and in a browser. Auto-invoked when importing a Workcard type, a status flow, applyHelper, changesHelper, queryHelper, wireHelper, makePlanningProtocols or a planning model.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/planning
 
 **Layer:** Cross-cutting domain
-**Install:** `"@owlmeans/planning": "^0.1.18-rc.2"` in `dependencies` (`ajv` and `ajv-formats` are peers)
+**Install:** `"@owlmeans/planning": "^0.1.18-rc.20"` in `dependencies` (`ajv` and `ajv-formats` are peers)
 
 The contracts of project planning: record shapes, schemas, refusals, the protocol tree, the pure
 fold and the models. No database, no fastify, no React. The executor, the plugin registry, the
@@ -19,9 +19,27 @@ mirror are `@owlmeans/client-planning`; a durable store implements the ports dec
 
 Every change is a **transition** — an append-only event — and a card IS the fold of its
 transitions in `seq` order. There is one write path (`facade.execute(exec)`), one fold
-(`applyTransition`) and one query translation (`criteriaOf`), shared by every store and both sides
+(`applyHelper.applyTransition`) and one query translation (`queryHelper.criteriaOf`), shared by every store and both sides
 of the wire, so one log always means one card.
 
+## The write call
+
+`facade.execute(execution, options?)` — the same signature on the server facade
+(`@owlmeans/server-planning`, reached as `ctx.service<PlanningHostService>(PLANNING_SERVICE).for({
+entityId, profileId })`) and the remote one (`@owlmeans/client-planning`).
+
+- The **execution** has exactly these keys — `TransitionExecutionSchema` is closed, but only the
+  wire validates against it; in process an unknown key is silently ignored: `card` — the `WorkcardDraft` of a
+  create (`kind`, `type`, `title` required; `parent`/`parents`, `description`, `code`, `labels`,
+  `order`, `fields`, `status`, and a specification's `category`/`format`/`body`), the card id
+  otherwise — and `action` (`TransitionAction`), then per action `transition`, `flow`, `changes`,
+  `unset`, `link` / `links`, and `cause`, `key`, `expectSeq`.
+- The **options** are `{ wait?, timeout? }`, always the second argument. Only the wire body
+  (`ExecuteRequest`) carries them beside the execution.
+
+The worked example (facade, create, read back, transit, a data-defined type and flow) and the wrong
+forms generated code keeps writing are `server-planning` → Creating and reading a card.
+
 ## Key exports
 
 | Export | What it is |
@@ -29,20 +47,22 @@ of the wire, so one log always means one card.
 | `Workcard`, `Card`, `Project`, `Specification`, `Relationship`, `Transition` | The records |
 | `StatusFlowSchema`, `WorkcardTypeSchema`, `ProjectTypeSchema`, `SpecificationSlot`, `CodePolicy`, `RelationshipType`, `PlanningSchemaBundle` | Type declarations — data, not code |
 | `TransitionExecution`, `WorkcardDraft`, `TransitionReceipt`, `CommitEvent`, `CommitSource` | The write path and its commit feed |
-| `TransitionStore`, `ProjectionStore`, `SpecificationStore`, `RelationshipStore`, `PlanningStore` | Ports a store implements (only `cards` is required) |
-| `PlanningPlugin`, `PlanningScope`, `PlanningFacade`, `PlanningService` | The plugin seam and the facade, typed here so a plugin and a client can name them |
-| `WorkcardKind`, `IntrinsicStatus`, `IntrinsicPolicy`, `TransitionAction`, `CommitState`, `SpecificationFormat`, `CodeStyle`, `CodeScope` | Enums |
-| `PLANNING_SERVICE` (`'planning'`), `PLANNING_PATH`, `PLANNING_COMMIT_EVENT` (`'planning-commit'`), `planningAliases(base)` | Names both sides share |
+| `TransitionStore`, `ProjectionStore`, `SpecificationStore`, `RelationshipStore`, `SchemaStore`, `PlanningStore` | Ports a store implements (only `cards` is required) |
+| `PlanningPlugin`, `PlanningScope`, `PlanningFacade`, `PlanningService`, `PlanningDefinitions` | The plugin seam and the facade, typed here so a plugin and a client can name them |
+| `ScopedSchemaRecord`, `ScopedSchemaWhere`, `ScopedSchemaBundle`, `ScopedSchemaRegistry`, `SchemaDeclarations`, `SchemaWriteOptions`, `SchemaScope`, `SchemaKey`, `SchemaListQuery`, `SchemaDefineRequest`, `SchemaDefineReply` | Data-defined types and flows |
+| `WorkcardKind`, `IntrinsicStatus`, `IntrinsicPolicy`, `TransitionAction`, `CommitState`, `SpecificationFormat`, `CodeStyle`, `CodeScope`, `PlanningSchemaKind`, `SchemaOrigin`, `SchemaWriteMode` | Enums |
+| `PLANNING_SERVICE` (`'planning'`), `PLANNING_PATH`, `PLANNING_COMMIT_EVENT` (`'planning-commit'`), `planningAliasHelper.planningAliases(base)`, `planningAliasHelper.planningDefinitionAliases(base)` | Names both sides share |
 | `TITLE_MAX` 2048, `DESCRIPTION_MAX` 16384, `CODE_MAX` 64, `BODY_MAX` 1048576, `MAX_LABELS` 32, `MAX_PARENTS` 32, `DEFAULT_COMMIT_TIMEOUT` 30 s, `DEFAULT_COMMIT_POLL` 20 s, `MAX_COMMIT_POLL` 55 s, `CODE_MINT_ATTEMPTS` 8 | Limits |
-| `applyTransition`, `applyRelationship` | The fold |
-| `computeChanges`, `isEmptyChange`, `assertMutable`, `mergeFields`, `applyUnset`, `sameValue` | What a transition records |
-| `intrinsicOf`, `initialStatusOf`, `ruleOf`, `canTransit`, `transitionsFrom`, `initialFlowsOf`, `resolveIntrinsic`, `primaryFlowOf`, `isTerminal` | Status helpers |
-| `criteriaOf`, `listOptionsOf`, `specCriteriaOf`, `linkWhereOf`, `transitionWhereOf`, `summaryOf` | Querying |
-| `encode*Query` / `decode*Query` (Workcard, Summary, Transition, Specification, Relationship), `encodeSort`, `decodeSort`, `encodeList`, `decodeList` | The wire form of a query |
-| `mintCode`, `codeScopeOf`, `slugOf` | Codes |
-| `slotOf`, `currentSpecification`, `nextRevision`, `specificationTypeOf`, `bodyCharsOf` | Specifications |
-| `makeAjv`, `validateFields`, `validateCard`, `validateSpecificationBody`, `invalidFieldKeys`, `ajvErrorText` | Validation |
+| `applyHelper` — `applyTransition`, `applyRelationship` | The fold |
+| `changesHelper` — `computeChanges`, `isEmptyChange`, `assertMutable`, `mergeFields`, `applyUnset`, `sameValue` | What a transition records |
+| `statusHelper` — `intrinsicOf`, `initialStatusOf`, `ruleOf`, `canTransit`, `transitionsFrom`, `initialFlowsOf`, `resolveIntrinsic`, `primaryFlowOf`, `isTerminal` | Status helpers |
+| `queryHelper` — `criteriaOf`, `listOptionsOf`, `specCriteriaOf`, `linkWhereOf`, `transitionWhereOf`, `summaryOf` | Querying |
+| `wireHelper` — `encode*Query` / `decode*Query` (Workcard, Summary, Transition, Specification, Relationship), `encodeSort`, `decodeSort`, `encodeList`, `decodeList` | The wire form of a query |
+| `codeHelper` — `mintCode`, `codeScopeOf`, `slugOf` | Codes |
+| `specificationHelper` — `slotOf`, `currentSpecification`, `nextRevision`, `specificationTypeOf`, `bodyCharsOf` | Specifications |
+| `makeAjv`, `validateHelper` — `validateFields`, `validateCard`, `validateSpecificationBody`, `invalidFieldKeys`, `ajvErrorText` | Validation |
 | `makeSchemaRegistry(bundle?)` | Types, flows, cached field validators; `bundle()` / `load()` |
+| `scopedSchemaHelper` — `resolveScopedBundle`, `scopedRegistryOf`, `assertTypeSchema`, `assertFlowSchema`, `assertOverridable`, `flowInUse`, `schemaRecordKey`, `schemaKeyOf` | Data-defined layers: resolution, the read-only view, the closed-form checks |
 | `makePlanningProtocols(opts)` | The protocol tree |
 | `makeWorkcardModel`, `makeProjectModel`, `makeSpecificationModel`, `modelOf`, `executeFor` | Models |
 | `*Schema` | AJV schemas of every record, declaration, request and view |
@@ -52,8 +72,10 @@ of the wire, so one log always means one card.
 - **Base fields at the top level, provider fields under `fields`.** `title`, `description`, `code`,
   `status`, `labels`, `order`, `parent` are generic and indexable; everything a type adds lives in
   `fields` and is validated by the type's `fields` JSON schema. Generic code reads only the top.
-  A `fields` key never holds `.` or `$` at any depth (`invalidFieldKeys`).
-- **`entityId` is the organization's stable id**, never a slug. Every read is scoped by it.
+  A `fields` key never holds `.` or `$` at any depth (`validateHelper.invalidFieldKeys`).
+- **`entityId` is the organization's stable record id** — never the wire `entitySlug`, never a body
+  value. Every read is scoped by it; where a request's comes from is `server-planning` → Scope and
+  security.
 - **Membership is `parent` + `parents`, never a relationship.** `parents` always contains `parent`
   (first), so many-to-many membership needs no junction row. `within` queries `parents`.
 - **Specification is a workcard** (`kind: specification`) with `category`, `format`, `body`, `ref`,
@@ -61,8 +83,13 @@ of the wire, so one log always means one card.
   `keepRevisions`, a JSON body `schema` — is declared on the PARENT's type. One record per
   `(parent, category)` unless the slot is `multiple`; a revisioned slot increments `revision` on the
   same record, and earlier bodies come back from the transition log.
+- **`createdBy` is written once, from a create's draft, and never moves.** Named in `changes` or
+  `unset` it is refused on every action (`planning:immutable:createdBy`), so an ownership check
+  (`card.createdBy === profileId`) can trust it. A card that changes hands keeps that in a field of
+  its own type (`fields.assignee`); who made each later write is the transition's `actor`.
 - **`seq` is the last folded transition, `head` the highest allocated.** `head > seq` means a write
-  is in flight (`isPending`); optimistic concurrency (`expectSeq`) compares against the head.
+  is in flight (`cardHelper.isPending`); optimistic concurrency (`expectSeq`) compares against the
+  head.
 - `order` is a double: a card may sit between two others (`3.5`).
 - Timestamps are ISO-8601 UTC strings (`toISOString()`), so lexicographic order is chronological.
 
@@ -73,10 +100,12 @@ of the wire, so one log always means one card.
 - A flow is shareable across types, and a type may run several (`flows[0]` is primary).
   `flows` on the record is authoritative for every flow; `status`/`intrinsic` mirror the primary.
 - A rule name may repeat with different `from` sets (`start` from `planned`, `start` from
-  `failed`). `ruleOf` picks the rule naming the current status; a `'*'` rule of that name answers
+  `failed`). `statusHelper.ruleOf` picks the rule naming the current status; a `'*'` rule of that name answers
   only when none does, wherever it is declared. `'*'` includes the target status itself, so
-  `reset` from `planned` is legal.
-- `transitionsFrom(flow, status)` answers one rule per name in declaration order;
+  `reset` from `planned` is legal. A status the flow does NOT declare (a card whose flow changed
+  under it) matches every rule of the name, the first declared answering — such a card can always
+  move back onto the flow it now runs.
+- `statusHelper.transitionsFrom(flow, status)` answers one rule per name in declaration order;
   `{ explicit: true }` keeps the ones offered to a person.
 - `IntrinsicPolicy.Primary` (default) reads the primary flow; `IntrinsicPolicy.All` takes the least
   advanced flow — closed only when every flow is closed. A status a flow does not declare reads as
@@ -85,21 +114,72 @@ of the wire, so one log always means one card.
 ## Declaring a type
 
 A `WorkcardTypeSchema` / `ProjectTypeSchema` is plain data registered through a plugin's `schemas`
-or `makeSchemaRegistry({ types, flows })`:
+or `makeSchemaRegistry({ types, flows })`. **Every declaration schema is closed** — these are ALL
+the keys:
+
+| Declaration | Required | Optional |
+|---|---|---|
+| card / specification type | `type` (its key), `kind`, `version`, `fields`, `flows` (at least one), `specifications` | `intrinsic`, `relationships`, `labels`, `code`, `label`, `overridable` |
+| project type | the same, plus `cardTypes` | `projectTypes`, `scopedCardTypes` |
+| flow | `id` (its key), `version`, `statuses` (at least one), `transitions` | `label`, `overridable` |
+| status | `key`, `intrinsic` | `initial`, `terminal`, `label`, `tone` |
+| transition rule | `name`, `from` (status keys or `'*'`), `to` | `label`, `explicit` |
+
+The display name is `label` everywhere; a type or a flow has no `name`, `key` or `description`
+(`key` belongs to a status, `name` to a rule). As data, `definitions` refuses an extra key with
+`SchemaInvalid`; in code the registry does not validate a declaration, so only TypeScript's
+excess-property check catches it — keep the literal typed.
 
 - `fields` — the AJV schema of `fields`; the registry compiles and caches it (`validator(type)`).
 - `specifications` — the slots this type's cards carry as children. A slot may name its
-  specification `type`; otherwise `specificationTypeOf` takes the only registered specification
+  specification `type`; otherwise `specificationHelper.specificationTypeOf` takes the only registered specification
   type, then the one sharing the parent type's prefix (`viable:project` → `viable:spec`).
 - `code` — `CodePolicy { prefix?, style: random|sequential|slug, length?, uppercase?, uniqueWithin:
   parent|entity, mutable? }`. A code is fixed once minted unless `mutable`.
 - `relationships` — the edge types a card may start (`single` = at most one per card).
 - `labels` — the allowed labels (any when omitted).
-- A project type lists `cardTypes` (and `projectTypes` for nesting) its children may have.
+- A project type lists `cardTypes` (and `projectTypes` for nesting) its children may have;
+  `scopedCardTypes: true` also admits card types defined as data (below).
+- `overridable: true` on a code type or flow opens it to a data-defined override.
+
+## Data-defined types and flows
+
+Card types and status flows may also be DATA — `ScopedSchemaRecord`s a store keeps behind the
+optional `PlanningStore.schemas` port — layered **code → entity → project**:
+
+- `code` is the plugin registry (the default), `entity` an organization-wide record
+  (`project` absent), `project` a record of one project card. A project record overrides an
+  organization one of the same key.
+- **Only card types and flows are data.** A code key is sealed unless its declaration says
+  `overridable: true`; project and specification types are always code's (`scopedSchemaHelper.assertOverridable` →
+  `SchemaSealed`).
+- A record's `version` is its compare-and-set token and is written into the declaration's own
+  `version`: a write lands only at its layer's next version, 1 for a new key (`SchemaConflict`).
+- The closed-form checks are shared by every store: `scopedSchemaHelper.assertFlowSchema` (the declaration's schema,
+  unique status keys, every `to` declared, `from` `'*'` or declared statuses) and
+  `scopedSchemaHelper.assertTypeSchema` (the `card` kind, a compiling `fields` schema, unique flows that resolve) —
+  `SchemaInvalid`.
+- **Retired** means offered for nothing new, still resolved for what uses it: a retired record
+  gives way to a live declaration below it, and a key retired in every layer resolves retired —
+  present in the bundle's `types`/`flows`, listed in `retired`. A flow cannot be retired while a
+  live type of an affected layer still runs it (`scopedSchemaHelper.flowInUse` → `SchemaInUse`).
+- `scopedSchemaHelper.resolveScopedBundle(code, records, scope)` is the ONE resolution (pure);
+  `scopedRegistryOf` is its read-only registry (`originOf`, `isRetired`; `register*`/`load` refuse). A
+  `ScopedSchemaBundle` extends the plain bundle with `scope`, `revision`, `origins`, `retired`, so a
+  reader of the plain bundle is unaffected.
+- `SchemaStore`: `list(where)`, `put(record)` (the CAS), `purge({ entityId, project })`,
+  `revision(entityId)` (monotonic per organization), optional `watch(listener)`.
+- `PlanningFacade.definitions` (present only where the store has the port): `bundle(project?)`,
+  `registry(project?)`, `records`, `putType`/`putFlow` (CAS on the declaration's version),
+  `define` (each at its layer's next version, flows first), `seed` (only the keys the layer lacks),
+  `retire(kind, key, { project? })`. The declaration still carries its own `version` (any number
+  ≥ 1 for `define`/`seed`, which assign the layer's next one; the exact next one for `put*`), and
+  a project layer is `{ project: <project card id> }` in the second argument (a `define` call:
+  `server-planning` → Creating and reading a card).
 
 ## The fold
 
-`applyTransition(card | undefined, transition)` is pure and total:
+`applyHelper.applyTransition(card | undefined, transition)` is pure and total:
 
 - an already-applied seq (`seq <= card.seq`) returns the same card — re-folding is safe;
 - anything but `card.seq + 1` (or seq 1 for a create with no card) throws
@@ -109,12 +189,15 @@ or `makeSchemaRegistry({ types, flows })`:
   replaces** — and clear `unset` (`key`, `fields.key`, `flows.id`); identity and required keys are
   never written or cleared;
 - `link`/`unlink` move only `seq`/`head`/`updatedAt`; `delete` answers `null`;
-- every result carries `seq = transition.seq`, `head = max(head, seq)`, `updatedAt = transition.at`.
+- every result carries `seq = transition.seq`, `head = max(head, seq)`, `updatedAt = transition.at`;
+- the log is replayed AS WRITTEN: a stored row admission would refuse (an update naming
+  `createdBy`) still folds. Guards live at admission (`changesHelper.assertMutable`, the executor), never in the
+  fold, so a stored log never stops projecting.
 
-`applyRelationship(links, transition)` folds the edges: a create's `links`, `link`, `unlink`, and a
+`applyHelper.applyRelationship(links, transition)` folds the edges: a create's `links`, `link`, `unlink`, and a
 `delete` dropping every edge touching the card. An existing edge is kept, so re-folding adds nothing.
 
-`computeChanges(card, exec, type, registry, at, { slot? })` is what the executor records:
+`changesHelper.computeChanges(card, exec, type, registry, at, { slot? })` is what the executor records:
 
 - create — the whole initial record: normalized `parents`, every flow at its initial status (the
   draft's `status` for the primary), mirrored `status`/`intrinsic`, `closedAt` when it starts
@@ -122,37 +205,40 @@ or `makeSchemaRegistry({ types, flows })`:
   The code must already be on the draft (the executor mints first);
 - update — only differing values; `null` or `exec.unset` clears a field that has one; a moved
   `parent` replaces the old one in `parents`; changed content of a revisioned document sets
-  `revision + 1`. An update that changes nothing is `isEmptyChange` and must append nothing;
+  `revision + 1`. An update that changes nothing is `changesHelper.isEmptyChange` and must append nothing;
 - transit — `flows[flow] = rule.to`, `status` on the primary flow, `intrinsic` when it moves,
   `closedAt` set on entering closed and cleared on leaving; throws `IllegalTransition`;
 - link/unlink/delete — nothing.
 
-`assertMutable(exec, type)` refuses (`planning:immutable:<field>`) identity keys, `revision` /
-`bodyChars`, `status`/`intrinsic`/`flows`/`closedAt` outside a create (they move only through
-`transit`), `category`, a fixed `code`, and clearing a required field.
+`changesHelper.assertMutable(exec, type)` refuses (`planning:immutable:<field>`) identity keys (`createdAt`
+among them), `createdBy` in `changes` or `unset` on any action (a create included),
+`revision` / `bodyChars`, `status`/`intrinsic`/`flows`/`closedAt` outside a create (they move only
+through `transit`), `category`, a fixed `code`, and clearing a required field.
 
 ## Querying
 
-`criteriaOf(query, scope)` is the ONE translation from `WorkcardQuery` to `Criteria<Workcard>`:
+`queryHelper.criteriaOf(query, scope)` is the ONE translation from `WorkcardQuery` to `Criteria<Workcard>`:
 bare values and arrays pass through (`kind`, `type`, `status`, `intrinsic`, `code`, `category`),
 `parent` is direct children, `within` → `parents: { $contains }`, `labels` → `$overlaps`, `ids` →
 `id: { $in }`, `flow` → `flows.<id>`, `fields` → `fields.<key>` equality, `q` → `$or` of title /
 description `$ilike` (wildcards escaped) and code `$startsWith`, `updatedSince` → `updatedAt: {
 $gte }`. `entityId` always comes from the scope; `undefined` is omitted. Paging and sort are
-`listOptionsOf` (`size: 0` = no limit). `summaryOf(cards, parents)` counts DIRECT children by
-intrinsic state and gives no key to a parent with none.
+`queryHelper.listOptionsOf` (`size: 0` = no limit). `queryHelper.summaryOf(cards, parents)` counts DIRECT children by
+intrinsic state and gives no key to a parent with none. A scope naming `projects` is narrowed by
+the SERVER facade on top of this translation (`server-planning` → The access resolver);
+`TransitionWhere.project` and `RelationshipWhere.project` take one id or a list.
 
 **A query crosses HTTP in its wire form.** The OwlMeans transport cannot carry arrays or nested
 objects in a query string (the client writes `key[]=`, the server reads that key literally), so
 the list, summary, transitions, specifications and links protocols take `*QueryWire` shapes: lists
 comma-joined (a JSON array when an entry holds a comma), objects as JSON, sort as `field,-field`.
-A client calls `encodeWorkcardQuery(query)` before `call({ query })`; a handler calls
-`decodeWorkcardQuery(req.query)` — tolerant of arrays and of the rich form — and then
-`criteriaOf`. A value that does not decode throws `PlanningError('malformed:query:<key>')`.
+A client calls `wireHelper.encodeWorkcardQuery(query)` before `call({ query })`; a handler calls
+`wireHelper.decodeWorkcardQuery(req.query)` — tolerant of arrays and of the rich form — and then
+`queryHelper.criteriaOf`. A value that does not decode throws `PlanningError('malformed:query:<key>')`.
 
 ## The protocol tree and mounting
 
-`makePlanningProtocols({ base: { alias, path?, parent?, service? }, guards, gate?, socketBase? })`:
+`makePlanningProtocols({ base: { alias, path?, parent?, service? }, guards, gate?, socketBase?, definitions? })`:
 
 | Leaf | Route | Request → reply |
 |---|---|---|
@@ -168,9 +254,13 @@ A client calls `encodeWorkcardQuery(query)` before `call({ query })`; a handler
 | `execute` | POST `/execute` | body `ExecuteRequest` → `TransitionReceiptView` |
 | `commit.get` | GET `/commits/:transition` | query `CommitQuery { wait? }` → `CommitStatus` |
 | `commit.events` | SOCKET `/commits` | query `CommitFeedQuery` → `CommitEvent` frames |
+| `schema.define` (with `definitions: true`) | POST `/schemas` | body `SchemaDefineRequest { project?, mode?, types?, flows?, retire? }` → `SchemaDefineReply { records, bundle }` |
 
-- Aliases derive from the base alias (`planningAliases(base)` → `<base>:card:list`, …); two mounts
-  are two base aliases.
+- Aliases derive from the base alias (`planningAliasHelper.planningAliases(base)` → `<base>:card:list`, …); two mounts
+  are two base aliases. `definitions: true` adds `schema.define` (its alias from
+  `planningAliasHelper.planningDefinitionAliases(base)`, kept apart so a tree without it names no undeclared alias)
+  and gives `schema.list` a `SchemaListQuery { project? }` answered with that layer's scoped bundle.
+  Without it the tree declares exactly the other leaves.
 - The guards and the gate sit on the base alone; every HTTP leaf inherits them. `path` defaults to
   `/planning`.
 - Static `/cards/summary` is declared before parametric `/cards/:id`.
@@ -179,6 +269,24 @@ A client calls `encodeWorkcardQuery(query)` before `call({ query })`; a handler
 - `actor` in an execute body is ignored on the wire: the server fills it from the request.
 - Responses carry no runtime schema (typed only), so a serializer never strips `fields`.
 
+## Mounting in a target
+
+A generated target serves this tree as it is — no hand-written card, transition, schema or document
+routes; domain rules are `before` plugins. This section is the hub; each package skill has its half.
+
+- **common** declares the one tree the api and the web share: `makePlanningProtocols({ base: {
+  alias: 'api:planning' }, guards: DEFAULT_GUARD, definitions: true })`, in its own module beside
+  the `PLANNING` plugin (`sources/common/src/planning.ts`).
+- **api** — `server-planning` → Mounting in a target (stock handlers, no commit socket, the
+  resolver answering `writes`). **web** — `client-planning` → Mounting in a target. **store** —
+  `planning-postgres`.
+- **Kit literals**: card types and flows are LITERAL objects in `PLANNING.schemas.flows` / `.types`,
+  above the `// owlmeans: add planning flows|types above this line` sentinels — a spread or an
+  imported constant hides them from the library's registration checks. Card types and flows carry
+  `overridable: true` with open `fields` (`additionalProperties: true`); the container project type
+  (always sealed) carries `scopedCardTypes: true`, so the app's people override and extend them as
+  data through `schema.define`.
+
 ## Models
 
 `makeWorkcardModel(record, facade)` (and `makeProjectModel`, `makeSpecificationModel`, `modelOf`
@@ -213,13 +321,17 @@ the marker survives a hop where the class is unknown, so match on it there:
 | `SpecificationSlotUnknown` / `SpecificationRevisionConflict` | `specification-slot-unknown:` / `specification-revision-conflict:` | 422 / 409 |
 | `RelationshipRefused` / `CodeTaken` | `relationship-refused:` / `code-taken:` | 422 / 409 |
 | `WorkcardConflict` | `workcard-conflict:` — stale `expectSeq` | 409 |
+| `SchemaConflict` / `SchemaInUse` | `schema-conflict:` (lost version CAS) / `schema-in-use:` (retiring a flow a live type runs) | 409 |
+| `SchemaSealed` / `SchemaInvalid` | `schema-sealed:` / `schema-invalid:` | 422 |
+| `PlanningForbidden` | `forbidden:<grant>:<target>` — the request's access lacks a grant; `forbidden:writes:<id>` — the card or project is outside its `writes` | 403 |
 | `CommitTimeout` / `CommitFailed` | `commit-timeout:` (still pending, nothing undone) / `commit-failed:` | 500 |
 | `PlanningScopeMismatch` / `PlanningUnsupported` | `scope-mismatch:` / `unsupported:` | 404 / 500 |
 
 Type names are `PlanningError<Suffix>` (`PlanningErrorWorkcardNotFound`).
 
 **The HTTP column is each class's `static httpStatus`** (the `error` skill's principle; 500 = none
-declared): an addressed card that is absent or another entity's is 404, a card whose state or head
+declared): an addressed card that is absent or another entity's is 404, a write the request's
+access does not grant is 403, a card whose state or head (or a schema record whose version)
 refuses the write is 409, a body naming what the registry, the parent or a schema refuses is 422.
 Faults declare nothing, and so does `PlanningError` itself — its three causes share one class, and
 a base's static would reach every subclass. A new refusal declares on its own leaf class, and
@@ -229,7 +341,7 @@ throw a `ResilientError` that declares nothing.
 
 ## i18n
 
-Importing the package registers, in all seven languages, `lib:planning.*` labels (`kind.*`,
+Importing the package registers, in eight languages (en, pl, ru, be, uk, es, de, fr), `lib:planning.*` labels (`kind.*`,
 `intrinsic.*`, `action.*`, `commit.*`, `format.*`) and one text per refusal type under the shared
 `errors` resource (`errors.<TypeName>`), where a panel's error lookup finds it.
 
@@ -251,5 +363,5 @@ is part of the package's own tests.
 
 - [[server-planning]] — the executor, the plugin registry, the memory store, the handlers
 - [[client-planning]] — the remote facade, the state mirror, waiting for a commit
-- [[resource]] — the criteria language `criteriaOf` targets
-- [[server-planning]] — executor, projection implementations, plugin registry and memory store
+- [[resource]] — the criteria language `queryHelper.criteriaOf` targets
+- [[planning-postgres]] — a durable store implementing every port, the schema port included

package/build/aliases/types.d.ts

@@ -0,0 +1,49 @@
+/** The aliases one planning tree answers under — every one derived from the mount's base alias. */
+export interface PlanningAliases {
+    readonly base: string;
+    readonly schema: {
+        readonly list: string;
+    };
+    readonly card: {
+        readonly list: string;
+        readonly summary: string;
+        readonly get: string;
+        readonly transitions: string;
+        readonly specifications: string;
+    };
+    readonly spec: {
+        readonly get: string;
+        readonly revisions: string;
+    };
+    readonly link: {
+        readonly list: string;
+    };
+    readonly transition: {
+        readonly get: string;
+    };
+    readonly execute: string;
+    readonly commit: {
+        readonly get: string;
+        readonly events: string;
+    };
+}
+/** The aliases of the leaves a tree gains with `definitions: true`. */
+export interface PlanningDefinitionAliases {
+    readonly define: string;
+}
+export interface PlanningAliasHelper {
+    /**
+     * The aliases one planning tree answers under, derived from the mount's base alias.
+     *
+     * Two mounts of the tree in one deployment are two base aliases, never two copies of this table —
+     * which is why nothing here is a global constant.
+     */
+    planningAliases: (base: string) => PlanningAliases;
+    /**
+     * The aliases of the leaves a tree gains with `definitions: true` — kept apart from
+     * {@link PlanningAliasHelper.planningAliases} so a tree declared without them names no alias it
+     * does not declare.
+     */
+    planningDefinitionAliases: (base: string) => PlanningDefinitionAliases;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/aliases/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/aliases/types.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1C,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;QACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;QACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;QAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;KAChC,CAAA;IACD,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IACnE,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACxC,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CACnE;AAED,uEAAuE;AACvE,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,eAAe,CAAA;IAClD;;;;OAIG;IACH,yBAAyB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,yBAAyB,CAAA;CACvE"}

package/build/aliases/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/aliases/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/aliases/types.ts"],"names":[],"mappings":""}

package/build/aliases.d.ts

@@ -0,0 +1,4 @@
+import type { PlanningAliasHelper } from './aliases/types.js';
+export declare const createPlanningAliasHelper: () => PlanningAliasHelper;
+export declare const planningAliasHelper: PlanningAliasHelper;
+//# sourceMappingURL=aliases.d.ts.map

package/build/aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aliases.d.ts","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,mBAAmB,EAA6B,MAAM,oBAAoB,CAAA;AAEzG,eAAO,MAAM,yBAAyB,QAAO,mBA0B5C,CAAA;AAED,eAAO,MAAM,mBAAmB,qBAA8B,CAAA"}