@owlmeans/planning 0.1.18-rc.11 → 0.1.18-rc.12

package/README.md

@@ -9,7 +9,7 @@ the executor with `@owlmeans/server-planning` and reads remotely with `@owlmeans
 ## Installation
 
 ```sh
-bun add @owlmeans/planning@^0.1.18-rc.11 ajv ajv-formats
+bun add @owlmeans/planning@^0.1.18-rc.12 ajv ajv-formats
 ```
 
 ## Concepts
@@ -78,6 +78,20 @@ const page = await context.entrypoint(planningProtocols.card.list).call({ query
 const where = criteriaOf(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:
 
 ```ts
@@ -141,6 +155,11 @@ const links = transitions.reduce(applyRelationship, [])
 
 ## 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.
@@ -157,7 +176,7 @@ const links = transitions.reduce(applyRelationship, [])
 - `@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
@@ -167,7 +186,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.41
+npx @owlmeans/agent-skills@^0.1.18-rc.42
 ```
 
 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.11",
-  "generatedAt": "2026-09-28T02:06:37.879Z",
+  "version": "0.1.18-rc.12",
+  "generatedAt": "2026-09-29T08:01:58.127Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/planning
 
 **Layer:** Cross-cutting domain
-**Install:** `"@owlmeans/planning": "^0.1.18-rc.11"` in `dependencies` (`ajv` and `ajv-formats` are peers)
+**Install:** `"@owlmeans/planning": "^0.1.18-rc.12"` 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
@@ -22,6 +22,42 @@ transitions in `seq` order. There is one write path (`facade.execute(exec)`), on
 (`applyTransition`) and one query translation (`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.
+
+```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', fields: { brand: 'Acme' } },
+}, { wait: true })                      // drill.card — the committed record
+await planning.cards.get(drill.card!.id!)
+await planning.execute({ action: TransitionAction.Transit, card: drill.card!.id!, transition: 'lend' }, { wait: true })
+```
+
+| Wrong | What happens | Right |
+|---|---|---|
+| `{ action, draft: { … } }` | `planning:malformed:create-without-draft` | the draft goes under `card` |
+| `{ …, wait: true }` in the execution | ignored in process: the receipt returns before the commit, with no `card` | `execute(exec, { wait: true })` |
+| `action: 'create'` | a type error — `TransitionAction` is an enum | `TransitionAction.Create` |
+
+Each is a compile error against the typed `TransitionExecution`; it reaches run time only through a
+value typed `any`. `server-planning` carries the full example (facade, read back, data-defined
+type and flow).
+
 ## Key exports
 
 | Export | What it is |
@@ -89,7 +125,21 @@ 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
@@ -133,7 +183,20 @@ optional `PlanningStore.schemas` port — layered **code → entity → project*
 - `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? })`.
+  `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:
+
+```ts
+await planning.definitions!.define({
+  flows: [{ id: 'shed:repair', version: 1, label: 'Repair',
+    statuses: [{ key: 'reported', intrinsic: IntrinsicStatus.Planned, initial: true },
+      { key: 'fixed', intrinsic: IntrinsicStatus.Closed, terminal: true }],
+    transitions: [{ name: 'fix', from: ['reported'], to: 'fixed', explicit: true }] }],
+  types: [{ type: 'shed:repair', kind: WorkcardKind.Card, version: 1, label: 'Repair ticket',
+    fields: { type: 'object' }, flows: ['shed:repair'], specifications: [] }],
+}, { project: shedId })   // admitted under the shed when its type says `scopedCardTypes: true` (or lists it in `cardTypes`)
+```
 
 ## The fold
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/planning",
-  "version": "0.1.18-rc.11",
+  "version": "0.1.18-rc.12",
   "license": "MIT",
   "description": "Runtime-free project-planning contracts — the workcard super type, projects, specifications, typed relationships, status flows with three intrinsic states, the transition event and its pure fold, the schema registry, the models and the protocol tree.",
   "type": "module",
@@ -29,7 +29,7 @@
     "@owlmeans/entrypoint": "^0.1.18-rc.37",
     "@owlmeans/error": "^0.1.18-rc.36",
     "@owlmeans/i18n": "^0.1.18-rc.37",
-    "@owlmeans/resource": "^0.1.18-rc.36",
+    "@owlmeans/resource": "^0.1.18-rc.37",
     "@owlmeans/route": "^0.1.18-rc.33"
   },
   "peerDependencies": {