@owlmeans/planning 0.1.18-rc.0

package/README.md

@@ -0,0 +1,169 @@
+# @owlmeans/planning
+
+Runtime-free contracts for project planning: workcards (cards, projects, specifications), typed
+relationships, shareable status flows over three intrinsic states, the transition event and its
+pure fold, the schema registry, the protocol tree and the models that behave identically on a
+server and in a browser. An application depends on it from its shared contract package; it wires
+the executor with `@owlmeans/server-planning` and reads remotely with `@owlmeans/client-planning`.
+
+## Installation
+
+```sh
+bun add @owlmeans/planning@^0.1.18-rc.0 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`).
+- **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`).
+
+## Usage
+
+Declare a flow and a type, and register them:
+
+```ts
+import { CodeScope, CodeStyle, IntrinsicStatus, WorkcardKind, makeSchemaRegistry } from '@owlmeans/planning'
+
+const taskFlow = {
+  id: 'app:task', version: 1,
+  statuses: [
+    { key: 'todo', intrinsic: IntrinsicStatus.Planned, initial: true },
+    { key: 'doing', intrinsic: IntrinsicStatus.InProgress },
+    { key: 'done', intrinsic: IntrinsicStatus.Closed, terminal: true },
+  ],
+  transitions: [
+    { name: 'start', from: ['todo'], to: 'doing', explicit: true },
+    { name: 'finish', from: ['doing'], to: 'done', explicit: true },
+    { name: 'reset', from: '*' as const, to: 'todo' },
+  ],
+}
+
+const registry = makeSchemaRegistry({
+  flows: [taskFlow],
+  types: [{
+    type: 'app:task', kind: WorkcardKind.Card, version: 1, flows: ['app:task'], specifications: [],
+    fields: { type: 'object', properties: { estimate: { type: 'number' } }, additionalProperties: false },
+    code: { prefix: 'T-', style: CodeStyle.Random, length: 5, uppercase: true, uniqueWithin: CodeScope.Parent },
+  }],
+})
+```
+
+Declare the protocol tree once in the shared package:
+
+```ts
+import { makePlanningProtocols } from '@owlmeans/planning'
+
+export const planningProtocols = makePlanningProtocols({
+  base: { alias: 'app:api:planning', path: '/planning' },
+  guards: 'guard:default',
+})
+```
+
+Encode a query on the client, decode it in a handler:
+
+```ts
+import { criteriaOf, decodeWorkcardQuery, encodeWorkcardQuery } from '@owlmeans/planning'
+
+const query = 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 })
+```
+
+Work through a model — the same code on either side of the wire:
+
+```ts
+import { makeWorkcardModel } from '@owlmeans/planning'
+
+const task = makeWorkcardModel(card, facade)
+if (task.can('start')) {
+  const receipt = await task.transit('start', undefined, { wait: true })
+}
+await task.update({ title: 'Renamed' }) // expectSeq defaults to the record's head
+```
+
+Fold transitions yourself (a mirror, a test, a store):
+
+```ts
+import { applyRelationship, applyTransition } from '@owlmeans/planning'
+
+const card = transitions.reduce((current, transition) => applyTransition(current, transition), undefined)
+const links = transitions.reduce(applyRelationship, [])
+```
+
+## API
+
+- Records and declarations: `Workcard`, `Card`, `Project`, `Specification`, `Relationship`,
+  `Transition`, `StatusFlowSchema`, `WorkcardTypeSchema`, `ProjectTypeSchema`, `SpecificationSlot`,
+  `CodePolicy`, `RelationshipType`, `PlanningSchemaBundle`.
+- Write path and feed: `TransitionExecution`, `WorkcardDraft`, `ExecuteRequest`,
+  `TransitionReceipt`, `TransitionReceiptView`, `CommitEvent`, `CommitStatus`, `CommitSource`.
+- Ports and seam: `TransitionStore`, `ProjectionStore`, `SpecificationStore`, `RelationshipStore`,
+  `PlanningStore`, `PlanningPlugin`, `PlanningScope`, `PlanningFacade`, `PlanningService`.
+- 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`.
+- 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`.
+- Schemas: `WorkcardSchema`, `SpecificationSchema`, `TransitionSchema`, `ExecuteRequestSchema`,
+  `WorkcardQuerySchema`, … (every record, declaration, request and view).
+- Subpath `@owlmeans/planning/queue`: `PLANNING_PROJECTION_QUEUE`, `PLANNING_PROJECT_JOB`,
+  `declarePlanningQueue`, `ProjectionRequest`.
+
+## Common pitfalls
+
+- 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.
+- `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.
+
+## 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/queue` — the projection queue declared by the `./queue` subpath
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded agent skills under `agent-meta/`. After installing your
+`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
+your project's skill store (`.agents/skills/`):
+
+```sh
+npx @owlmeans/agent-skills@^0.1.18-rc.27
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 2,
+  "package": "@owlmeans/planning",
+  "version": "0.1.18-rc.0",
+  "generatedAt": "2026-09-16T15:11:05.003Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "planning",
+      "category": "package-specific",
+      "file": "skills/planning/SKILL.md",
+      "canonicalPath": ".agents/skills/planning/SKILL.md"
+    }
+  ]
+}

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

@@ -0,0 +1,248 @@
+---
+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.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/planning
+
+**Layer:** Cross-cutting domain
+**Install:** `"@owlmeans/planning": "^0.1.18-rc.0"` 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
+memory store and the handlers are `@owlmeans/server-planning`; the remote facade and the state
+mirror are `@owlmeans/client-planning`; a durable store implements the ports declared here.
+
+## The one idea
+
+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
+of the wire, so one log always means one 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 |
+| `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 |
+| `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()` |
+| `makePlanningProtocols(opts)` | The protocol tree |
+| `makeWorkcardModel`, `makeProjectModel`, `makeSpecificationModel`, `modelOf`, `executeFor` | Models |
+| `*Schema` | AJV schemas of every record, declaration, request and view |
+| `@owlmeans/planning/queue` | `PLANNING_PROJECTION_QUEUE`, `PLANNING_PROJECT_JOB`, `declarePlanningQueue(cfg, opts?)`, `ProjectionRequest` |
+
+## The record model
+
+- **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`.
+- **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.
+- **`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.
+- `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.
+
+## Status flows
+
+- Every status maps onto one of three intrinsic states: `planned`, `in-progress`, `closed`.
+  Summaries, gates and boards read the intrinsic state; the status key is the provider's vocabulary.
+- 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
+  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;
+  `{ 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`
+by kind) is the same object on a server and in a browser. `schema`, `flow`, `statusOf`,
+`intrinsicOf`, `can`, `available`, `pending` answer from the registry with no I/O; `transit`,
+`update`, `remove`, `link`, `unlink`, `write` build a `TransitionExecution` and call
+`facade.execute`.
+
+- `expectSeq` defaults to `record.head ?? record.seq`; pass `null` to opt out, a number to pin.
+  A stale model therefore refuses with `WorkcardConflict` — `reload()` and retry.
+- `write(category, body)` creates the slot's document when the slot is empty and updates it when
+  filled (expecting the DOCUMENT's head, not the parent's). The model never computes a revision;
+  the executor does.
+- `ProjectModel` adds `cards`, `projects` (by `within`), `summary` (zero counts when empty) and
+  `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 |
+|---|---|
+| `PlanningError` | `planning:` (`fold:out-of-order`, `immutable:<field>`, `malformed:<what>`) |
+| `WorkcardNotFound` | `workcard-not-found:` — also the answer for another entity's card |
+| `UnknownWorkcardType` / `UnknownStatusFlow` | `unknown-type:` / `unknown-flow:` |
+| `ParentNotFound` / `CardTypeNotAllowed` | `parent-not-found:` / `card-type-not-allowed:` |
+| `PlanningRefused` | `refused:` — a plugin middleware said no |
+| `IllegalTransition` | `illegal-transition:<flow>:<transition>:<from>` |
+| `FieldsInvalid` / `LabelNotAllowed` | `fields-invalid:` / `label-not-allowed:` |
+| `SpecificationSlotUnknown` / `SpecificationRevisionConflict` | `specification-slot-unknown:` / `specification-revision-conflict:` |
+| `RelationshipRefused` / `CodeTaken` | `relationship-refused:` / `code-taken:` |
+| `WorkcardConflict` | `workcard-conflict:` — stale `expectSeq` |
+| `CommitTimeout` / `CommitFailed` | `commit-timeout:` (still pending, nothing undone) / `commit-failed:` |
+| `PlanningScopeMismatch` / `PlanningUnsupported` | `scope-mismatch:` / `unsupported:` |
+
+Type names are `PlanningError<Suffix>` (`PlanningErrorWorkcardNotFound`).
+
+## 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`
+- `@owlmeans/entrypoint`, `@owlmeans/route` — the protocol tree
+- `@owlmeans/error`, `@owlmeans/i18n`, `@owlmeans/auth` (`IdValueSchema`), `@owlmeans/basic-ids`, `@owlmeans/context`
+- `@owlmeans/queue` — only through the `./queue` subpath
+
+## Related
+
+- [[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
+- [[queue]] — the projection queue the `./queue` subpath declares

package/build/consts.d.ts

@@ -0,0 +1,126 @@
+/** What a workcard IS. Cards, projects and specifications share one id space and one fold. */
+export declare enum WorkcardKind {
+    Card = "card",
+    Project = "project",
+    Specification = "specification"
+}
+/**
+ * The three states every status of every flow maps onto.
+ *
+ * A provider's statuses are its own vocabulary; these three are the only ones generic code — a
+ * summary, a board header, a gate — ever reads.
+ */
+export declare enum IntrinsicStatus {
+    Planned = "planned",
+    InProgress = "in-progress",
+    Closed = "closed"
+}
+/** Advancement order — `resolveIntrinsic` under {@link IntrinsicPolicy.All} takes the minimum. */
+export declare const INTRINSIC_ORDER: Readonly<Record<IntrinsicStatus, number>>;
+/** How a type running several flows answers its one intrinsic status. */
+export declare enum IntrinsicPolicy {
+    /** The primary flow's status decides. */
+    Primary = "primary",
+    /** The least advanced flow decides — closed only when every flow is closed. */
+    All = "all"
+}
+export declare enum TransitionAction {
+    Create = "create",
+    Update = "update",
+    Transit = "transit",
+    Link = "link",
+    Unlink = "unlink",
+    Delete = "delete"
+}
+export declare enum CommitState {
+    Pending = "pending",
+    Committed = "committed",
+    Failed = "failed"
+}
+export declare enum SpecificationFormat {
+    Markdown = "markdown",
+    Json = "json",
+    Text = "text"
+}
+export declare enum CodeStyle {
+    Random = "random",
+    Sequential = "sequential",
+    Slug = "slug"
+}
+/** Where a minted code must be unique. */
+export declare enum CodeScope {
+    Parent = "parent",
+    Entity = "entity"
+}
+/** Service alias of the planning facade host. Identical on the server and in a client. */
+export declare const PLANNING_SERVICE = "planning";
+/** The path segment the protocol tree answers under when the mount names none. */
+export declare const PLANNING_PATH = "/planning";
+/** The socket frame name the commit feed pushes under. */
+export declare const PLANNING_COMMIT_EVENT = "planning-commit";
+/** The i18n resource the package's labels are registered under (`lib:planning.*`). */
+export declare const PLANNING_I18N = "planning";
+/** A `from` that matches every status of the flow. */
+export declare const ANY_STATUS = "*";
+/** How long `committed()` waits by default, in milliseconds. */
+export declare const DEFAULT_COMMIT_TIMEOUT = 30000;
+/** Seconds a single long poll of `commit.get` holds by default. */
+export declare const DEFAULT_COMMIT_POLL = 20;
+/** The longest single long poll a server grants, in seconds. */
+export declare const MAX_COMMIT_POLL = 55;
+/** Re-rolls a code policy gets before it refuses with `CodeTaken`. */
+export declare const CODE_MINT_ATTEMPTS = 8;
+/** Random part length of a code policy that names none. */
+export declare const DEFAULT_CODE_LENGTH = 6;
+export declare const DEFAULT_PLUGIN_ORDER = 50;
+export declare const DEFAULT_PAGE_SIZE = 100;
+export declare const PLANNING_SCHEMA_VERSION = 1;
+export declare const TITLE_MAX = 2048;
+export declare const DESCRIPTION_MAX = 16384;
+export declare const CODE_MAX = 64;
+export declare const TYPE_MAX = 128;
+export declare const LABEL_MAX = 64;
+export declare const MAX_LABELS = 32;
+export declare const MAX_PARENTS = 32;
+export declare const BODY_MAX = 1048576;
+export declare const CAUSE_MAX = 256;
+export declare const KEY_MAX = 256;
+export declare const REF_MAX = 1024;
+export declare const QUERY_TEXT_MAX = 256;
+/** The longest list a wire query carries in one value (ids, parents). */
+export declare const MAX_QUERY_LIST = 500;
+/**
+ * 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.
+ */
+export declare const planningAliases: (base: string) => Readonly<{
+    base: string;
+    schema: Readonly<{
+        list: `${string}:schema:list`;
+    }>;
+    card: Readonly<{
+        list: `${string}:card:list`;
+        summary: `${string}:card:summary`;
+        get: `${string}:card:get`;
+        transitions: `${string}:card:transitions`;
+        specifications: `${string}:card:specifications`;
+    }>;
+    spec: Readonly<{
+        get: `${string}:specification:get`;
+        revisions: `${string}:specification:revisions`;
+    }>;
+    link: Readonly<{
+        list: `${string}:link:list`;
+    }>;
+    transition: Readonly<{
+        get: `${string}:transition:get`;
+    }>;
+    execute: `${string}:execute`;
+    commit: Readonly<{
+        get: `${string}:commit:get`;
+        events: `${string}:commit:events`;
+    }>;
+}>;
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,oBAAY,YAAY;IACtB,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,aAAa,kBAAkB;CAChC;AAED;;;;;GAKG;AACH,oBAAY,eAAe;IACzB,OAAO,YAAY;IACnB,UAAU,gBAAgB;IAC1B,MAAM,WAAW;CAClB;AAED,kGAAkG;AAClG,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAIpE,CAAA;AAEF,yEAAyE;AACzE,oBAAY,eAAe;IACzB,yCAAyC;IACzC,OAAO,YAAY;IACnB,+EAA+E;IAC/E,GAAG,QAAQ;CACZ;AAED,oBAAY,gBAAgB;IAC1B,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,MAAM,WAAW;CAClB;AAED,oBAAY,WAAW;IACrB,OAAO,YAAY;IACnB,SAAS,cAAc;IACvB,MAAM,WAAW;CAClB;AAED,oBAAY,mBAAmB;IAC7B,QAAQ,aAAa;IACrB,IAAI,SAAS;IACb,IAAI,SAAS;CACd;AAED,oBAAY,SAAS;IACnB,MAAM,WAAW;IACjB,UAAU,eAAe;IACzB,IAAI,SAAS;CACd;AAED,0CAA0C;AAC1C,oBAAY,SAAS;IACnB,MAAM,WAAW;IACjB,MAAM,WAAW;CAClB;AAED,0FAA0F;AAC1F,eAAO,MAAM,gBAAgB,aAAa,CAAA;AAE1C,kFAAkF;AAClF,eAAO,MAAM,aAAa,cAAc,CAAA;AAExC,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,oBAAoB,CAAA;AAEtD,sFAAsF;AACtF,eAAO,MAAM,aAAa,aAAa,CAAA;AAEvC,sDAAsD;AACtD,eAAO,MAAM,UAAU,MAAM,CAAA;AAE7B,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,QAAS,CAAA;AAC5C,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,KAAK,CAAA;AACrC,gEAAgE;AAChE,eAAO,MAAM,eAAe,KAAK,CAAA;AACjC,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,IAAI,CAAA;AACnC,2DAA2D;AAC3D,eAAO,MAAM,mBAAmB,IAAI,CAAA;AACpC,eAAO,MAAM,oBAAoB,KAAK,CAAA;AACtC,eAAO,MAAM,iBAAiB,MAAM,CAAA;AACpC,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC,eAAO,MAAM,SAAS,OAAO,CAAA;AAC7B,eAAO,MAAM,eAAe,QAAQ,CAAA;AACpC,eAAO,MAAM,QAAQ,KAAK,CAAA;AAC1B,eAAO,MAAM,QAAQ,MAAM,CAAA;AAC3B,eAAO,MAAM,SAAS,KAAK,CAAA;AAC3B,eAAO,MAAM,UAAU,KAAK,CAAA;AAC5B,eAAO,MAAM,WAAW,KAAK,CAAA;AAC7B,eAAO,MAAM,QAAQ,UAAY,CAAA;AACjC,eAAO,MAAM,SAAS,MAAM,CAAA;AAC5B,eAAO,MAAM,OAAO,MAAM,CAAA;AAC1B,eAAO,MAAM,OAAO,OAAO,CAAA;AAC3B,eAAO,MAAM,cAAc,MAAM,CAAA;AACjC,yEAAyE;AACzE,eAAO,MAAM,cAAc,MAAM,CAAA;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,eAAe,SAAU,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkB1C,CAAA"}