@owlmeans/server-planning 0.1.18-rc.13 → 0.1.18-rc.14

package/README.md

@@ -10,13 +10,16 @@ the `@owlmeans/server-planning/store` subpath.
 ## Installation
 
 ```sh
-bun add @owlmeans/server-planning@^0.1.18-rc.13 @owlmeans/planning@^0.1.18-rc.11 ajv
+bun add @owlmeans/server-planning@^0.1.18-rc.14 @owlmeans/planning@^0.1.18-rc.12 ajv
 ```
 
 ## Concepts
 
-- **Facade** — `context.planning().for(scope)`: every read and write of one organization entity,
-  with no scope argument on any method.
+- **Facade** — `ctx.service<PlanningHostService>(PLANNING_SERVICE).for(scope)`: every read and
+  write of one organization entity, with no scope argument on any method. `context.planning()` is
+  the same service, but only on a context that went through `appendPlanningService`; a service
+  registered as a plain one (`makePlanningService()`, a generated target's `services/planning.ts`)
+  has no `context.planning`.
 - **Executor** — the only write path: normalize → idempotency → resolve → plugins' `before` →
   validate → id → code → changes → seq CAS → append → project → receipt. Nothing is appended by a
   refusal.
@@ -125,6 +128,13 @@ const cards = await planningFor(ctx, req, { channel: 'web' }).cards.list({ paren
 
 ## Common pitfalls
 
+- A create's draft goes under `card` — `draft` is refused as `planning:malformed:create-without-draft`.
+- `{ wait: true }` is the SECOND argument of `execute`; inside the execution it is ignored and the
+  receipt returns before the commit.
+- A type or flow declaration has no `name` or `key`: the display name is `label`, the key is `type`
+  (a type) or `id` (a flow). `definitions.define` refuses anything else with `SchemaInvalid`; a code
+  plugin's registry does not check, so keep the literals typed.
+
 - `after` hooks run where the transition is FOLDED, once per commit — register the same plugins in
   every folding process, and never run hooks from a commit-bus subscription.
 - The memory store is per-process heap: wrong for multiple processes or restarts.
@@ -153,7 +163,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/server-planning",
-  "version": "0.1.18-rc.13",
-  "generatedAt": "2026-09-28T02:06:37.869Z",
+  "version": "0.1.18-rc.14",
+  "generatedAt": "2026-09-29T08:01:58.111Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/server-planning
 
 **Layer:** Server
-**Install:** `"@owlmeans/server-planning": "^0.1.18-rc.13"` in `dependencies` (`ajv` is a peer)
+**Install:** `"@owlmeans/server-planning": "^0.1.18-rc.14"` in `dependencies` (`ajv` is a peer)
 
 The general implementation of `@owlmeans/planning`: the planning service (a plugin host), the
 scoped facade, the executor every write goes through, the in-memory reference store, the commit
@@ -61,8 +61,68 @@ context.registerEntrypoints(servePlanningEntrypoints(planningProtocols, {
   `ensurePlanningService(ctx).use(plugin)` works from `makeContext`, before `init()`.
 - Call `appendPlanningService` BEFORE any `ensurePlanningService`: `ensure` registers a default
   host when none exists, and a later `append` replaces it together with whatever was `use`d on it.
-- In code: `ctx.planning().for({ entityId, profileId?, channel?, actor? })` → a `PlanningFacade`
-  with no scope argument on any method.
+- **The facade:** `ctx.service<PlanningHostService>(PLANNING_SERVICE).for({ entityId, profileId?,
+  channel?, actor? })` → a `PlanningFacade` with no scope argument on any method. That form works
+  however the service was registered. `ctx.planning()` is only a shortcut that `appendPlanningService`
+  / `appendPostgresPlanning` install (typed `WithPlanningService`); a context that registered
+  `makePlanningService()` / `makePostgresPlanningService()` as a plain service — a generated target's
+  `services/planning.ts` — has no `ctx.planning` at all. In a request handler use
+  `planningFor(ctx, req)`: the entity comes from `requireEntityKey(req)`, never the token.
+
+## Creating and reading a card
+
+```ts
+import { IntrinsicStatus, PLANNING_SERVICE, TransitionAction, WorkcardKind } from '@owlmeans/planning'
+import type { PlanningHostService } from '@owlmeans/server-planning'
+
+const planning = ctx.service<PlanningHostService>(PLANNING_SERVICE).for({ entityId, profileId })
+
+const shed = await planning.execute({
+  action: TransitionAction.Create,
+  card: { kind: WorkcardKind.Project, type: 'shed:shed', title: 'Maple Street shed' },
+}, { wait: true })
+const drill = await planning.execute({
+  action: TransitionAction.Create,
+  card: { kind: WorkcardKind.Card, type: 'shed:tool', parent: shed.card!.id!, title: 'Cordless drill',
+    fields: { brand: 'Acme' } },
+}, { wait: true })                      // drill.card — the committed record, status 'available'
+
+await planning.cards.get(drill.card!.id!)
+await planning.cards.list({ parent: shed.card!.id!, type: 'shed:tool' })
+await planning.execute({ action: TransitionAction.Transit, card: drill.card!.id!, transition: 'lend' }, { wait: true })
+
+// A card type and a flow as DATA, scoped to this shed — `definitions` exists only where the store
+// keeps schemas (planning-postgres; the memory store with `schemas: true`), and the shed's cards may
+// use them when its project type says `scopedCardTypes: true` (or lists the type in `cardTypes`).
+await planning.definitions!.define({
+  flows: [{
+    id: 'shed:repair', version: 1, label: 'Repair',
+    statuses: [
+      { key: 'reported', intrinsic: IntrinsicStatus.Planned, initial: true, label: 'Reported' },
+      { key: 'fixed', intrinsic: IntrinsicStatus.Closed, terminal: true, label: 'Fixed' },
+    ],
+    transitions: [{ name: 'fix', from: ['reported'], to: 'fixed', label: 'Mark fixed', explicit: true }],
+  }],
+  types: [{
+    type: 'shed:repair', kind: WorkcardKind.Card, version: 1, label: 'Repair ticket',
+    fields: { type: 'object', properties: { tool: { type: 'string' } }, additionalProperties: false },
+    flows: ['shed:repair'], specifications: [],
+  }],
+}, { project: shed.card!.id! })
+```
+
+| Wrong | What happens | Right |
+|---|---|---|
+| `execute({ action, draft: { … } })` | refused: `planning:malformed:create-without-draft` | the draft goes under `card` |
+| `execute({ …, wait: true })` | in process the key is ignored: the receipt returns before the commit, with no `card` | `execute({ … }, { wait: true })` — only the wire body (`ExecuteRequest`) carries `wait` inside |
+| `ctx.planning().for(…)` in a target | `ctx.planning is not a function` | `ctx.service<PlanningHostService>(PLANNING_SERVICE).for(…)` |
+| `{ id, name: 'Repair', … }` on a flow, `{ key, name, … }` on a type | `define` refuses with `SchemaInvalid` (closed schemas); a code plugin's registry does not validate, so the key is silently dropped | a flow's key is `id`, a type's is `type`, the display name is `label` on both |
+| `action: 'create'` | a type error — `TransitionAction` is an enum | `action: TransitionAction.Create` |
+
+Every wrong form is a compile error against the typed facade (`PlanningFacade`,
+`TransitionExecution`, `WorkcardTypeSchema`); it reaches run time only through a helper or a context
+typed `any`, so never type one that way. `tests/create-example.spec.ts` runs this example and each
+wrong form as written.
 
 ## The executor, step by step
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-planning",
-  "version": "0.1.18-rc.13",
+  "version": "0.1.18-rc.14",
   "license": "MIT",
   "description": "The general planning implementation — the planning service and its plugin/middleware registry, the transition executor, the in-memory store, the protocol handlers and the commit feed.",
   "type": "module",
@@ -45,19 +45,19 @@
   },
   "dependencies": {
     "@owlmeans/auth": "^0.1.18-rc.36",
-    "@owlmeans/auth-common": "^0.1.18-rc.40",
+    "@owlmeans/auth-common": "^0.1.18-rc.41",
     "@owlmeans/basic-ids": "^0.1.18-rc.34",
     "@owlmeans/context": "^0.1.18-rc.32",
     "@owlmeans/entrypoint": "^0.1.18-rc.37",
     "@owlmeans/error": "^0.1.18-rc.36",
-    "@owlmeans/planning": "^0.1.18-rc.11",
-    "@owlmeans/queue": "^0.1.18-rc.34",
-    "@owlmeans/resource": "^0.1.18-rc.36",
+    "@owlmeans/planning": "^0.1.18-rc.12",
+    "@owlmeans/queue": "^0.1.18-rc.35",
+    "@owlmeans/resource": "^0.1.18-rc.37",
     "@owlmeans/route": "^0.1.18-rc.33",
-    "@owlmeans/server-api": "^0.1.18-rc.44",
-    "@owlmeans/server-context": "^0.1.18-rc.37",
+    "@owlmeans/server-api": "^0.1.18-rc.45",
+    "@owlmeans/server-context": "^0.1.18-rc.38",
     "@owlmeans/server-entrypoint": "^0.1.18-rc.36",
-    "@owlmeans/server-socket": "^0.1.18-rc.47",
+    "@owlmeans/server-socket": "^0.1.18-rc.48",
     "@owlmeans/socket": "^0.1.18-rc.35"
   },
   "peerDependencies": {
@@ -66,7 +66,7 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test": "^0.1.18-rc.32",
+    "@owlmeans/test": "^0.1.18-rc.33",
     "@types/bun": "^1.4.0",
     "@types/node": "^26.1.0",
     "ajv": "^8.17.1",

package/tests/create-example.spec.ts

@@ -0,0 +1,202 @@
+import { describe, expect, test } from 'bun:test'
+import { AppType, makeBasicContext } from '@owlmeans/context'
+import type { BasicConfig } from '@owlmeans/context'
+import {
+  CommitState, IntrinsicStatus, PLANNING_SERVICE, SchemaInvalid, TransitionAction, WorkcardKind,
+} from '@owlmeans/planning'
+import type {
+  PlanningPlugin, StatusFlowSchema, TransitionExecution, WithPlanningService, WorkcardTypeSchema,
+} from '@owlmeans/planning'
+import { appendPlanningService, makePlanningService } from '../src/service.js'
+import { makeMemoryPlanningStore } from '../src/store/memory.js'
+import type { MemoryPlanningStoreOptions } from '../src/store/types.js'
+import type { PlanningHostService } from '../src/types.js'
+
+/**
+ * The create example the `planning`, `server-planning` and `planning-postgres` skills show, run as
+ * written — and the wrong forms beside it, each answered the way the skills say.
+ */
+
+const SHED: PlanningPlugin = {
+  name: 'shed-planning',
+  schemas: {
+    flows: [
+      {
+        id: 'shed:site', version: 1,
+        statuses: [
+          { key: 'open', intrinsic: IntrinsicStatus.Planned, initial: true },
+          { key: 'closed', intrinsic: IntrinsicStatus.Closed, terminal: true },
+        ],
+        transitions: [{ name: 'close', from: ['open'], to: 'closed' }],
+      },
+      {
+        id: 'shed:loan', version: 1,
+        statuses: [
+          { key: 'available', intrinsic: IntrinsicStatus.Planned, initial: true, label: 'Available' },
+          { key: 'lent', intrinsic: IntrinsicStatus.InProgress, label: 'Lent out' },
+          { key: 'retired', intrinsic: IntrinsicStatus.Closed, terminal: true },
+        ],
+        transitions: [
+          { name: 'lend', from: ['available'], to: 'lent', label: 'Lend', explicit: true },
+          { name: 'return', from: ['lent'], to: 'available', label: 'Return', explicit: true },
+          { name: 'retire', from: '*', to: 'retired' },
+        ],
+        label: 'Loan',
+      },
+    ],
+    types: [
+      {
+        type: 'shed:shed', kind: WorkcardKind.Project, version: 1, label: 'Tool shed',
+        fields: { type: 'object' }, flows: ['shed:site'], specifications: [],
+        cardTypes: ['shed:tool'], scopedCardTypes: true,
+      },
+      {
+        type: 'shed:tool', kind: WorkcardKind.Card, version: 1, label: 'Tool',
+        fields: { type: 'object', properties: { brand: { type: 'string' } }, additionalProperties: false },
+        flows: ['shed:loan'], specifications: [],
+      },
+    ],
+  },
+}
+
+const cfg = (): BasicConfig => ({ ready: false, service: 'shed-tests', type: AppType.Backend, services: {} })
+
+/** A target's shape: the service registered as a plain service, no `ctx.planning()`. */
+const bootTarget = async (store: MemoryPlanningStoreOptions = {}) => {
+  const memory = makeMemoryPlanningStore({ schemas: true, ...store })
+  const context = makeBasicContext(cfg())
+  context.registerService(makePlanningService({ store: memory, plugins: [SHED] }))
+  context.configure()
+  await context.init()
+
+  return { context, memory }
+}
+
+const scope = { entityId: 'org-1', profileId: 'profile-1' }
+
+describe('creating a card — the documented form', () => {
+  test('scoped facade → create a project and a card under it with { wait: true } → read back', async () => {
+    const { context } = await bootTarget()
+    const planning = context.service<PlanningHostService>(PLANNING_SERVICE).for(scope)
+
+    const shed = await planning.execute({
+      action: TransitionAction.Create,
+      card: { kind: WorkcardKind.Project, type: 'shed:shed', title: 'Maple Street shed' },
+    }, { wait: true })
+    const shedId = shed.card!.id!
+
+    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 })
+
+    expect(drill.transition.commit.state).toBe(CommitState.Committed)
+    expect(drill.card).toMatchObject({ title: 'Cordless drill', status: 'available', parent: shedId })
+
+    const again = await planning.cards.get(drill.card!.id!)
+    expect(again.fields).toEqual({ brand: 'Acme' })
+    const tools = await planning.cards.list({ parent: shedId, type: 'shed:tool' })
+    expect(tools.items.map(tool => tool.title)).toEqual(['Cordless drill'])
+
+    const lent = await planning.execute({
+      action: TransitionAction.Transit, card: drill.card!.id!, transition: 'lend',
+    }, { wait: true })
+    expect(lent.card?.status).toBe('lent')
+  })
+
+  test('a data-defined type and flow with the exact keys, then a card of that type', async () => {
+    const { context } = await bootTarget()
+    const planning = context.service<PlanningHostService>(PLANNING_SERVICE).for(scope)
+    const shedId = (await planning.execute({
+      action: TransitionAction.Create,
+      card: { kind: WorkcardKind.Project, type: 'shed:shed', title: 'Maple Street shed' },
+    }, { wait: true })).card!.id!
+
+    const records = await planning.definitions!.define({
+      flows: [{
+        id: 'shed:repair', version: 1, label: 'Repair',
+        statuses: [
+          { key: 'reported', intrinsic: IntrinsicStatus.Planned, initial: true, label: 'Reported' },
+          { key: 'fixed', intrinsic: IntrinsicStatus.Closed, terminal: true, label: 'Fixed' },
+        ],
+        transitions: [{ name: 'fix', from: ['reported'], to: 'fixed', label: 'Mark fixed', explicit: true }],
+      }],
+      types: [{
+        type: 'shed:repair', kind: WorkcardKind.Card, version: 1, label: 'Repair ticket',
+        fields: { type: 'object', properties: { tool: { type: 'string' } }, additionalProperties: false },
+        flows: ['shed:repair'], specifications: [],
+      }],
+    }, { project: shedId })
+    expect(records.map(record => `${record.kind}:${record.key}:${record.version}`))
+      .toEqual(['flow:shed:repair:1', 'type:shed:repair:1'])
+
+    const ticket = await planning.execute({
+      action: TransitionAction.Create,
+      card: { kind: WorkcardKind.Card, type: 'shed:repair', parent: shedId, title: 'Drill chuck slips' },
+    }, { wait: true })
+    expect(ticket.card?.status).toBe('reported')
+  })
+})
+
+describe('creating a card — the wrong forms', () => {
+  test('`draft:` in place of `card:` is refused before anything is written', async () => {
+    const { context } = await bootTarget()
+    const planning = context.service<PlanningHostService>(PLANNING_SERVICE).for(scope)
+    const wrong = { action: TransitionAction.Create, draft: { kind: WorkcardKind.Project, type: 'shed:shed', title: 'x' } }
+
+    await expect(planning.execute(wrong as unknown as TransitionExecution, { wait: true }))
+      .rejects.toThrow('planning:malformed:create-without-draft')
+  })
+
+  test('`wait: true` inside the execution is ignored in process — the receipt is back before the commit', async () => {
+    const { context, memory } = await bootTarget({ sync: false })
+    const planning = context.service<PlanningHostService>(PLANNING_SERVICE).for(scope)
+    const create: TransitionExecution = {
+      action: TransitionAction.Create,
+      card: { kind: WorkcardKind.Project, type: 'shed:shed', title: 'Maple Street shed' },
+    }
+
+    const early = await planning.execute({ ...create, wait: true } as TransitionExecution)
+    expect(early.transition.commit.state).toBe(CommitState.Pending)
+    expect(early.card).toBeUndefined()
+
+    // In the second argument it holds until the commit lands — here, until the store folds.
+    const folding = setInterval(() => void memory.flush(), 5)
+    try {
+      const held = await planning.execute({
+        ...create, card: { ...(create.card as object), title: 'Oak Lane shed' },
+      } as TransitionExecution, { wait: true })
+      expect(held.transition.commit.state).toBe(CommitState.Committed)
+      expect(held.card?.title).toBe('Oak Lane shed')
+    } finally {
+      clearInterval(folding)
+    }
+  })
+
+  test('`ctx.planning()` exists only where appendPlanningService ran; the service alias always works', async () => {
+    const { context } = await bootTarget()
+    expect((context as Partial<WithPlanningService>).planning).toBeUndefined()
+    expect(context.service<PlanningHostService>(PLANNING_SERVICE).for(scope).scope.entityId).toBe('org-1')
+
+    const appended = appendPlanningService(makeBasicContext(cfg()), { plugins: [SHED] })
+    appended.configure()
+    await appended.init()
+    expect(appended.planning()).toBe(appended.service<PlanningHostService>(PLANNING_SERVICE))
+  })
+
+  test('a declaration with `name` / `key` instead of `label` / `type` / `id` is SchemaInvalid', async () => {
+    const { context } = await bootTarget()
+    const planning = context.service<PlanningHostService>(PLANNING_SERVICE).for(scope)
+    const flow = SHED.schemas!.flows![1]
+    const type = SHED.schemas!.types![1] as WorkcardTypeSchema
+
+    const named = { ...flow, id: 'shed:named', name: 'Loan' } as unknown as StatusFlowSchema
+    await expect(planning.definitions!.define({ flows: [named] })).rejects.toBeInstanceOf(SchemaInvalid)
+
+    const keyed = { ...type, type: 'shed:keyed', key: 'shed:keyed', name: 'Tool' } as unknown as WorkcardTypeSchema
+    await expect(planning.definitions!.define({ types: [keyed] })).rejects.toBeInstanceOf(SchemaInvalid)
+  })
+})