@owlmeans/planning 0.1.18-rc.9 → 0.1.18

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.9"` in `dependencies` (`ajv` and `ajv-formats` are peers)
+**Install:** `"@owlmeans/planning": "^0.1.18"` 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
@@ -17,32 +17,54 @@ mirror are `@owlmeans/client-planning`; a durable store implements the ports dec
 
 ## The one idea
 
-Every change is a **transition** — an append-only event — and a card IS the fold of its
+Every workcard 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 |
 |---|---|
 | `Workcard`, `Card`, `Project`, `Specification`, `Relationship`, `Transition` | The records |
 | `StatusFlowSchema`, `WorkcardTypeSchema`, `ProjectTypeSchema`, `SpecificationSlot`, `CodePolicy`, `RelationshipType`, `PlanningSchemaBundle` | Type declarations — data, not code |
+| `PlanningAppDeclarations`, `PlanningAppSchema`, `PlanningAppBagKind` | The application's own type/flow properties (`app` bags) and base card fields, declared in 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 |
-| `makeSchemaRegistry(bundle?)` | Types, flows, cached field validators; `bundle()` / `load()` |
+| `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, the app declarations (`registerApp`, `app`), `fieldsSchema(type)` and its cached validator; `bundle()` / `load()` |
+| `appSchemaHelper` — `merge`, `assertDeclarations`, `bagSchemaOf`, `assertBag`, `fieldsSchemaOf` | The application's declarations: merge order, closed forms, a definition's `app` bag, a type's effective fields schema |
+| `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 |
@@ -51,18 +73,31 @@ 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.
-- **Membership is `parent` + `parents`, never a relationship.** `parents` always contains `parent`
-  (first), so many-to-many membership needs no junction row. `within` queries `parents`.
+  `fields` and is validated by the type's `fields` JSON schema — beside the application's base card
+  fields (`schemas.app.card`, the `types` part). Generic code reads only the top.
+  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.
+- **Card containment is `parent` + `parents`.** `parents` always contains `parent` (first), so
+  multiple direct parents need no junction row. `within` queries those direct parents. Team
+  membership and project-team assignment use canonical typed relationships instead.
 - **Specification is a workcard** (`kind: specification`) with `category`, `format`, `body`, `ref`,
   `revision`, `version`, `bodyChars`. The SLOT — category, format, `multiple`, `revisioned`,
   `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.
+  same record, and earlier bodies come back from the transition log. A document belongs to its
+  primary parent: the parent's `delete` removes it (and the documents under it) with their edges,
+  comments, mentions and log, and never waits for it to be deleted first.
+- **`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. Responsibility uses the optional top-level
+  `assignee` planning ID; additional participant fields belong in the type's `fields` schema.
+  The optional `reporter` also references an assignee ID. 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,112 +108,17 @@ 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
   planned.
 
-## Declaring a type
-
-A `WorkcardTypeSchema` / `ProjectTypeSchema` is plain data registered through a plugin's `schemas`
-or `makeSchemaRegistry({ types, flows })`:
-
-- `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
-  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.
-
-## The fold
-
-`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
-  `PlanningError('fold:out-of-order')`;
-- `create` builds the whole record from `changes` + `id`/`kind`/`type`/`entityId`/`createdAt`/`seq`;
-- `update`/`transit` write `changes` — **`fields` and `flows` merge shallowly, every other key
-  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`.
-
-`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:
-
-- 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
-  closed; a specification gets its format, `bodyChars` and revision 1 when the slot is revisioned.
-  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;
-- 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.
-
-## Querying
-
-`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.
-
-**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>')`.
-
-## The protocol tree and mounting
-
-`makePlanningProtocols({ base: { alias, path?, parent?, service? }, guards, gate?, socketBase? })`:
-
-| Leaf | Route | Request → reply |
-|---|---|---|
-| `schema.list` | GET `/schemas` | → `PlanningSchemaBundle` |
-| `card.list` | GET `/cards` | query `WorkcardQueryWire` → `ListResult<Workcard>` |
-| `card.summary` | GET `/cards/summary` | query `SummaryQueryWire` → `SummaryView` |
-| `card.get` | GET `/cards/:id` | → `Workcard` |
-| `card.transitions` | GET `/cards/:id/transitions` | query `TransitionQueryWire` |
-| `card.specifications` | GET `/cards/:id/specifications` | query `SpecificationQueryWire` |
-| `spec.get` / `spec.revisions` | GET `/specifications/:id` / `…/revisions` | query `RevisionsQuery` |
-| `link.list` | GET `/links` | query `RelationshipQueryWire` |
-| `transition.get` | GET `/transitions/:transition` | → `Transition` |
-| `execute` | POST `/execute` | body `ExecuteRequest` → `TransitionReceiptView` |
-| `commit.get` | GET `/commits/:transition` | query `CommitQuery { wait? }` → `CommitStatus` |
-| `commit.events` | SOCKET `/commits` | query `CommitFeedQuery` → `CommitEvent` frames |
-
-- Aliases derive from the base alias (`planningAliases(base)` → `<base>:card:list`, …); two mounts
-  are two base aliases.
-- 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`.
-- The commit socket hangs under `socketBase` when given and then inherits THAT base's guards —
-  pass an update/socket base that authenticates; otherwise it hangs under the planning base.
-- `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`.
-
 ## Models
 
 `makeWorkcardModel(record, facade)` (and `makeProjectModel`, `makeSpecificationModel`, `modelOf`
@@ -196,51 +136,6 @@ by kind) is the same object on a server and in a browser. `schema`, `flow`, `sta
   `purge` (a delete of the project — the store removes everything under it).
 - `SpecificationModel` adds `body`, `revise`, `history` (from the log).
 
-## Errors
-
-Every refusal is a registered `ResilientError` whose message is `planning:<marker>:<detail>` —
-the marker survives a hop where the class is unknown, so match on it there:
-
-| Class | Marker | HTTP |
-|---|---|---|
-| `PlanningError` | `planning:` (`fold:out-of-order`, `immutable:<field>`, `malformed:<what>`) | 500 |
-| `WorkcardNotFound` | `workcard-not-found:` — also the answer for another entity's card | 404 |
-| `UnknownWorkcardType` / `UnknownStatusFlow` | `unknown-type:` / `unknown-flow:` | 422 |
-| `ParentNotFound` / `CardTypeNotAllowed` | `parent-not-found:` / `card-type-not-allowed:` | 422 |
-| `PlanningRefused` | `refused:` — a plugin middleware said no | 422 |
-| `IllegalTransition` | `illegal-transition:<flow>:<transition>:<from>` | 409 |
-| `FieldsInvalid` / `LabelNotAllowed` | `fields-invalid:` / `label-not-allowed:` | 422 |
-| `SpecificationSlotUnknown` / `SpecificationRevisionConflict` | `specification-slot-unknown:` / `specification-revision-conflict:` | 422 / 409 |
-| `RelationshipRefused` / `CodeTaken` | `relationship-refused:` / `code-taken:` | 422 / 409 |
-| `WorkcardConflict` | `workcard-conflict:` — stale `expectSeq` | 409 |
-| `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
-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
-`tests/error-status.spec.ts` refuses an exported refusal whose status was not decided. A plugin's
-plain `throw` inside `before` becomes `PlanningRefused` and answers 422, so a plugin FAULT must
-throw a `ResilientError` that declares nothing.
-
-## i18n
-
-Importing the package registers, in all seven languages, `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.
-
-## Schema rules
-
-A record schema may become a Mongo `$jsonSchema`, so every exported schema keeps two rules: **no
-`integer`** (`number` only) and **every optional property `nullable: true`** (an enum then admits
-`null` too). No `oneOf`/`anyOf` inside a record schema. Build type arrays per schema, never share
-one object between schemas — ajv may extend a `type` array while compiling. The walk that pins this
-is part of the package's own tests.
-
 ## Depends On
 
 - `@owlmeans/resource` — `Criteria`, `ListOptions`, `ListResult`, `createListSchema`
@@ -251,5 +146,17 @@ 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
+
+## Parts
+
+Load a part on top of this core when its job is in play.
+
+| Part | Load it when |
+|---|---|
+| [types](parts/types.md) | Declaring a type or a status flow, the application's own properties and base card fields (`app`, `appSchemaHelper`), data-defined types and flows (`scopedSchemaHelper`), or a new record schema |
+| [fold](parts/fold.md) | Folding transitions (`applyHelper`, `changesHelper`) or translating a `WorkcardQuery` (`queryHelper`, `wireHelper`) |
+| [mounting](parts/mounting.md) | Declaring or mounting the protocol tree (`makePlanningProtocols`), or serving it in a generated target |
+| [errors](parts/errors.md) | Throwing, matching or phrasing a planning refusal (marker, HTTP status, i18n text) |
+| [collaboration](parts/collaboration.md) | Assignees, reporters, comments and mentions, teams, card hierarchy, the `resources` branches or `PlanningReply` |

package/agent-meta/skills/planning/parts/collaboration.md

@@ -0,0 +1,67 @@
+---
+name: collaboration
+description: Assignees, comments with stable mentions, teams across projects, card hierarchy rules, the resources protocol branches, and PlanningReply's organization-free records.
+metadata:
+  purposes: detail, view
+  mentions: Assignee, Team, Comment, CommentMention, mentionHelper, PlanningResourceKind, PLANNING_PROJECT_TEAM, planningResourceAliases, planningReplyHelper, PlanningReply, teams.addMember, reporter, assignee
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/planning — Assignees, comments, teams and hierarchy
+
+## Assignees, comments, teams and hierarchy
+
+Cards retain the transition log; auxiliary records use separate versioned resources. `Assignee`,
+`Team`, `Comment` and `CommentMention` have organization scope and `version` compare-and-set.
+`PlanningResourceKind` qualifies relationship endpoints so ids from different resources cannot
+collide. Omitted endpoint kinds mean `workcard` for stored legacy edges.
+
+Assignees have stable ids, normalized organization-unique nicknames (`mentionHelper.nicknameKey`),
+`kind: human | non-human`, `type`, flexible `fields`, optional `authentication: { provider,
+externalId }` and retirement. Human types require authentication by default; declare
+`authentication: 'optional'` to allow a human without it. Non-human types default to optional.
+Authentication is provider-neutral; `@owlmeans/planning-auth` adds the optional OwlMeans adapter.
+Code plugins declare `schemas.assigneeTypes`; data definitions use `putAssigneeType` or
+`define({ assigneeTypes })`. Assignee schemas are organization-wide, never project-local.
+
+`reporter` and `assignee` are optional top-level single assignee ids. Additional schema fields use
+`relationships: [{ name, field, toKind: PlanningResourceKind.Assignee, multiple?, to?, inverse? }]`.
+`to` restricts target assignee types. The field is authoritative; the store maintains its canonical
+edge and the facade exposes named inverse views. Do not mirror base fields in `fields`, invent
+join collections or manually write these derived edges. Retired assignees retain existing links
+and comments but cannot receive new assignments or team memberships.
+
+Comments belong to a card and a trusted author assignee. Encode stable mentions with
+`mentionHelper.encode(id, nickname)`, producing `[@nickname](assignee:<encoded-id>)`; renaming a
+nickname never retargets a mention. `CommentMention` is a separate derived cache with the source
+comment `revision`; reads repair interrupted cache updates. Never accept author ids from an
+untrusted request or parse ordinary prose as identity.
+
+Teams are organization resources, reusable across projects. `teams.addMember/removeMember` and
+`teams.attach/detach` use the existing relationship store, with canonical team-member and
+project-team edges. `teams.members(team)` and `teams.projects(team)` read membership and
+attachment; `teams.assignees(project)` reads effective assignees. Read project teams through
+`relationships.list({ from: project, type: PLANNING_PROJECT_TEAM, toKind: PlanningResourceKind.Team })`;
+project assignees are the deduplicated union of attached teams. Team `externalId` may name an
+external permission group; links do not mutate authentication group membership.
+
+Hierarchy uses existing `parent` and direct `parents`, with optional derived `parentType`.
+Declare compatible `parents: { types?, required? }` and `children: { types }` on card schemas.
+Required primary parents cannot be cleared; safe reparenting is supported. Cycles, cross-organization
+links, incompatible descendants and deleting an ordinary card with child cards
+(`hierarchy:parent-in-use`) are refused. A card's own documents — the specifications whose primary
+parent is it, and theirs in turn — never block its delete: they go with it. The
+nearest primary project selects schemas; all project ancestors participate in access checks.
+Project `mode` is `opened` (default) or `closed`, separate from flow status; host policy may use it
+for access decisions.
+
+Declare `resources: true` on `makePlanningProtocols` to add assignee/team/comment/mention
+`get`, `list`, `write` branches and use `planningResourceAliases`. Enable `definitions: true`
+for assignee type schema writes. Use stock facade methods, handlers, stores and feeds on both
+sides; resource commands and versions are validated by the shared wire contract.
+
+Protocol responses use `PlanningReply<T>`: storage organization metadata (`entityId`) is absent
+from records, schema scopes, receipts and commit frames. `planningReplyHelper.project` handles
+only known record/envelope positions; custom fields, transition changes and schema definitions
+remain opaque. Native facades retain their trusted storage scope. Remote facades hydrate the
+shared record shape with empty advisory metadata; never derive organization identity from it.

package/agent-meta/skills/planning/parts/errors.md

@@ -0,0 +1,51 @@
+---
+name: errors
+description: Every refusal class with its planning marker and HTTP status, the httpStatus rules for a new refusal, and the eight-language i18n the package registers.
+metadata:
+  purposes: feedback
+  mentions: PlanningError, WorkcardNotFound, IllegalTransition, WorkcardConflict, PlanningRefused, FieldsInvalid, SchemaConflict, SchemaSealed, SchemaInvalid, PlanningForbidden, CommitTimeout, CommitFailed, lib:planning
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/planning — Errors and i18n
+
+## Errors
+
+Every refusal is a registered `ResilientError` whose message is `planning:<marker>:<detail>` —
+the marker survives a hop where the class is unknown, so match on it there:
+
+| Class | Marker | HTTP |
+|---|---|---|
+| `PlanningError` | `planning:` (`fold:out-of-order`, `immutable:<field>`, `malformed:<what>`) | 500 |
+| `WorkcardNotFound` | `workcard-not-found:` — also the answer for another entity's card | 404 |
+| `UnknownWorkcardType` / `UnknownStatusFlow` | `unknown-type:` / `unknown-flow:` | 422 |
+| `ParentNotFound` / `CardTypeNotAllowed` | `parent-not-found:` / `card-type-not-allowed:` | 422 |
+| `PlanningRefused` | `refused:` — a plugin middleware said no | 422 |
+| `IllegalTransition` | `illegal-transition:<flow>:<transition>:<from>` | 409 |
+| `FieldsInvalid` / `LabelNotAllowed` | `fields-invalid:` / `label-not-allowed:` | 422 |
+| `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 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
+`tests/error-status.spec.ts` refuses an exported refusal whose status was not decided. A plugin's
+plain `throw` inside `before` becomes `PlanningRefused` and answers 422, so a plugin FAULT must
+throw a `ResilientError` that declares nothing.
+
+## i18n
+
+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.

package/agent-meta/skills/planning/parts/fold.md

@@ -0,0 +1,69 @@
+---
+name: fold
+description: The pure fold (applyTransition, applyRelationship), what computeChanges records and assertMutable refuses, and the one query translation with its wire form.
+metadata:
+  purposes: query, state
+  mentions: applyHelper, applyTransition, applyRelationship, changesHelper, computeChanges, assertMutable, isEmptyChange, queryHelper, criteriaOf, listOptionsOf, summaryOf, wireHelper, encodeWorkcardQuery, decodeWorkcardQuery, WorkcardQuery
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/planning — The fold and querying
+
+## The fold
+
+`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
+  `PlanningError('fold:out-of-order')`;
+- `create` builds the whole record from `changes` + `id`/`kind`/`type`/`entityId`/`createdAt`/`seq`;
+- `update`/`transit` write `changes` — **`fields` and `flows` merge shallowly, every other key
+  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`;
+- 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.
+
+`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.
+
+`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
+  closed; a specification gets its format, `bodyChars` and revision 1 when the slot is revisioned.
+  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 `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.
+
+`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
+
+`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
+`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 `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>')`.

package/agent-meta/skills/planning/parts/mounting.md

@@ -0,0 +1,64 @@
+---
+name: mounting
+description: The protocol tree makePlanningProtocols declares (leaves, routes, aliases, guards, the commit socket) and how a generated target mounts it.
+metadata:
+  purposes: server-api, config
+  mentions: makePlanningProtocols, planningAliasHelper, planningAliases, planningDefinitionAliases, PLANNING_PATH, socketBase, ExecuteRequest, CommitQuery, CommitFeedQuery, schema.define
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/planning — The protocol tree and mounting
+
+## The protocol tree and mounting
+
+`makePlanningProtocols({ base: { alias, path?, parent?, service? }, guards, gate?, socketBase?, definitions? })`:
+
+| Leaf | Route | Request → reply |
+|---|---|---|
+| `schema.list` | GET `/schemas` | → `PlanningSchemaBundle` |
+| `card.list` | GET `/cards` | query `WorkcardQueryWire` → `ListResult<Workcard>` |
+| `card.summary` | GET `/cards/summary` | query `SummaryQueryWire` → `SummaryView` |
+| `card.get` | GET `/cards/:id` | → `Workcard` |
+| `card.transitions` | GET `/cards/:id/transitions` | query `TransitionQueryWire` |
+| `card.specifications` | GET `/cards/:id/specifications` | query `SpecificationQueryWire` |
+| `spec.get` / `spec.revisions` | GET `/specifications/:id` / `…/revisions` | query `RevisionsQuery` |
+| `link.list` | GET `/links` | query `RelationshipQueryWire` |
+| `transition.get` | GET `/transitions/:transition` | → `Transition` |
+| `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 (`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`.
+- The commit socket hangs under `socketBase` when given and then inherits THAT base's guards —
+  pass an update/socket base that authenticates; otherwise it hangs under the planning base.
+- `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, resources: 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`.
+- What the app itself keeps about every type, flow or card (a type's `description`, an origin's
+  attribute planning has no key for) is `PLANNING.schemas.app` — never an extra key on a type or a
+  flow (the `types` part, Application-declared properties).