@owlmeans/server-planning 0.1.18-rc.9 → 0.1.18

package/tests/access.spec.ts

@@ -0,0 +1,160 @@
+import { describe, expect, test } from 'bun:test'
+import { AuthForbidden } from '@owlmeans/auth'
+import {
+  CommitState, makePlanningProtocols, ParentNotFound, PlanningForbidden, PlanningSchemaKind, SchemaOrigin,
+  TransitionAction, WorkcardKind, WorkcardNotFound,
+} from '@owlmeans/planning'
+import type { CommitEvent, SchemaDefineReply, ScopedSchemaBundle } from '@owlmeans/planning'
+import {
+  defineSchemas, executePlanning, getCard, getCommit, listCards, listLinks, listSchemas, summarizeCards,
+} from '../src/actions/index.js'
+import type { PlanningAccess, PlanningHandlerOptions } from '../src/types.js'
+import {
+  createProject, createTask, ENTITY, invoke, makeTestPlanning, OTHER_ENTITY, PROJECT, session, TASK,
+} from './context.js'
+
+const tree = makePlanningProtocols({ base: { alias: 'test:planning' }, guards: 'test-guard', definitions: true })
+
+const withAccess = (access: PlanningAccess | (() => PlanningAccess)): PlanningHandlerOptions => ({
+  access: async () => typeof access === 'function' ? access() : access,
+})
+
+describe('@owlmeans/server-planning — access resolver', () => {
+  test('the organization is the resolver\'s, never the token\'s, and a resolver throw is the answer', async () => {
+    const { context, facade } = await makeTestPlanning()
+    const theirs = await createProject(facade(OTHER_ENTITY), 'Theirs')
+    await createProject(facade(), 'Mine')
+
+    const listed = await invoke(listCards(tree.card.list, withAccess({ entityId: OTHER_ENTITY })), context, { ...session(ENTITY), query: {} })
+    expect(listed.items.map((card: { id: string }) => card.id)).toEqual([theirs.id])
+
+    const refusing: PlanningHandlerOptions = { access: async () => { throw new AuthForbidden('no-seat') } }
+    await expect(invoke(listCards(tree.card.list, refusing), context, { ...session(), query: {} })).rejects.toBeInstanceOf(AuthForbidden)
+  })
+
+  test('projects narrow reads: an invisible project and its cards are absent, lists and summaries shrink', async () => {
+    const { context, facade } = await makeTestPlanning()
+    const visible = await createProject(facade(), 'Visible')
+    const hidden = await createProject(facade(), 'Hidden')
+    const seen = (await createTask(facade(), visible.id!, 'Seen')).card!
+    const unseen = (await createTask(facade(), hidden.id!, 'Unseen')).card!
+    await facade().execute({ card: unseen.id!, action: TransitionAction.Link, link: { type: 'blocks', to: seen.id! } }, { wait: true })
+    const opts = withAccess({ entityId: ENTITY, projects: [visible.id!] })
+
+    await expect(invoke(getCard(tree.card.get, opts), context, { ...session(), params: { id: unseen.id } })).rejects.toBeInstanceOf(WorkcardNotFound)
+    await expect(invoke(getCard(tree.card.get, opts), context, { ...session(), params: { id: hidden.id } })).rejects.toBeInstanceOf(WorkcardNotFound)
+    expect((await invoke(getCard(tree.card.get, opts), context, { ...session(), params: { id: seen.id } })).id).toBe(seen.id)
+
+    const listed = await invoke(listCards(tree.card.list, opts), context, { ...session(), query: { type: TASK } })
+    expect(listed.items.map((card: { id: string }) => card.id)).toEqual([seen.id])
+    const summary = await invoke(summarizeCards(tree.card.summary, opts), context, { ...session(), query: { parents: `${visible.id},${hidden.id}` } })
+    expect(Object.keys(summary)).toEqual([visible.id!])
+    expect((await invoke(listLinks(tree.link.list, opts), context, { ...session(), query: { to: seen.id } })).total).toBe(0)
+  })
+
+  test('projects narrow writes: an invisible parent is ParentNotFound, an invisible card absent', async () => {
+    const { context, facade } = await makeTestPlanning()
+    const visible = await createProject(facade(), 'Visible')
+    const hidden = await createProject(facade(), 'Hidden')
+    const unseen = (await createTask(facade(), hidden.id!, 'Unseen')).card!
+    const execute = executePlanning(tree.execute, withAccess({ entityId: ENTITY, projects: [visible.id!] }))
+
+    await expect(invoke(execute, context, {
+      ...session(), body: { card: { kind: WorkcardKind.Card, type: TASK, parent: hidden.id, title: 'Sneaky' }, action: TransitionAction.Create },
+    })).rejects.toBeInstanceOf(ParentNotFound)
+    await expect(invoke(execute, context, {
+      ...session(), body: { card: unseen.id, action: TransitionAction.Update, changes: { title: 'Renamed' } },
+    })).rejects.toBeInstanceOf(WorkcardNotFound)
+
+    const made = await invoke(execute, context, {
+      ...session(), body: { card: { kind: WorkcardKind.Card, type: TASK, parent: visible.id, title: 'Allowed' }, action: TransitionAction.Create, wait: true },
+    })
+    expect(made.card.title).toBe('Allowed')
+    expect((await facade().cards.get(unseen.id!)).title).toBe('Unseen')
+  })
+
+  test('commit status and subscriptions stay inside the visible projects', async () => {
+    const { context, facade, service } = await makeTestPlanning()
+    const visible = await createProject(facade(), 'Visible')
+    const hidden = await createProject(facade(), 'Hidden')
+    const narrowed = service.for({ entityId: ENTITY, projects: [visible.id!] })
+    const heard: CommitEvent[] = []
+    const unsubscribe = await narrowed.commits.subscribe(event => { heard.push(event) })
+
+    const seen = await createTask(facade(), visible.id!, 'Seen')
+    const unseen = await createTask(facade(), hidden.id!, 'Unseen')
+    unsubscribe()
+
+    expect(heard.map(event => event.card)).toEqual([seen.card!.id!])
+    await expect(invoke(getCommit(tree.commit.get, withAccess({ entityId: ENTITY, projects: [visible.id!] })), context, {
+      ...session(), params: { transition: unseen.transition.id }, query: {},
+    })).rejects.toBeInstanceOf(WorkcardNotFound)
+    expect((await narrowed.commits.status(seen.transition.id!)).state).toBe(CommitState.Committed)
+  })
+
+  test('grants gate project creation, project deletion and schema definitions with a 403 refusal', async () => {
+    const { context, facade } = await makeTestPlanning({}, { schemas: true })
+    const parent = await createProject(facade(), 'Parent')
+    const other = await createProject(facade(), 'Other')
+    const nested = { kind: WorkcardKind.Project, type: PROJECT, parent: parent.id, title: 'Nested' }
+    const scoped = (grants: PlanningAccess['grants']) => withAccess({ entityId: ENTITY, grants })
+
+    await expect(invoke(executePlanning(tree.execute, scoped({})), context, {
+      ...session(), body: { card: { kind: WorkcardKind.Project, type: PROJECT, title: 'Root' }, action: TransitionAction.Create },
+    })).rejects.toBeInstanceOf(PlanningForbidden)
+    expect(PlanningForbidden.httpStatus).toBe(403)
+    await expect(invoke(executePlanning(tree.execute, scoped({ createProjects: [parent.id!] })), context, {
+      ...session(), body: { card: { kind: WorkcardKind.Project, type: PROJECT, title: 'Root' }, action: TransitionAction.Create },
+    })).rejects.toBeInstanceOf(PlanningForbidden)
+    const made = await invoke(executePlanning(tree.execute, scoped({ createProjects: [parent.id!] })), context, {
+      ...session(), body: { card: nested, action: TransitionAction.Create, wait: true },
+    })
+    expect(made.card.parent).toBe(parent.id)
+    // A card is not a project: creating one needs no grant.
+    await invoke(executePlanning(tree.execute, scoped({})), context, {
+      ...session(), body: { card: { kind: WorkcardKind.Card, type: TASK, parent: parent.id, title: 'Task' }, action: TransitionAction.Create },
+    })
+
+    await expect(invoke(executePlanning(tree.execute, scoped({ deleteProjects: [other.id!] })), context, {
+      ...session(), body: { card: parent.id, action: TransitionAction.Delete },
+    })).rejects.toBeInstanceOf(PlanningForbidden)
+    await invoke(executePlanning(tree.execute, scoped({ deleteProjects: [other.id!] })), context, {
+      ...session(), body: { card: other.id, action: TransitionAction.Delete, wait: true },
+    })
+    expect(await facade().cards.load(other.id!)).toBeNull()
+
+    const flow = { id: 'test:rota', version: 1, statuses: [{ key: 'due', intrinsic: 'planned' }], transitions: [] }
+    await expect(invoke(defineSchemas(tree.schema.define!, scoped({ defineSchemas: [parent.id!] })), context, {
+      ...session(), body: { flows: [flow] },
+    })).rejects.toBeInstanceOf(PlanningForbidden)
+    const layer: SchemaDefineReply = await invoke(defineSchemas(tree.schema.define!, scoped({ defineSchemas: [parent.id!] })), context, {
+      ...session(), body: { project: parent.id, flows: [flow] },
+    })
+    expect([layer.bundle.origins?.flows['test:rota'], layer.records.map(record => record.key)]).toEqual([SchemaOrigin.Project, ['test:rota']])
+  })
+})
+
+describe('@owlmeans/server-planning — schema handlers', () => {
+  test('schema.list answers the code bundle without a schema port, and the scoped layer with one', async () => {
+    const plain = await makeTestPlanning()
+    const bundle = await invoke(listSchemas(tree.schema.list), plain.context, { ...session(), query: {} })
+    expect(bundle).toEqual(plain.service.schemas.bundle())
+
+    const scoped = await makeTestPlanning({}, { schemas: true })
+    const project = await createProject(scoped.facade(), 'Layered')
+    const note = { type: 'test:memo', kind: WorkcardKind.Card, version: 1, fields: { type: 'object' }, flows: ['test:task'], specifications: [] }
+    await invoke(defineSchemas(tree.schema.define!), scoped.context, { ...session(), body: { project: project.id, types: [note] } })
+
+    const entityLayer: ScopedSchemaBundle = await invoke(listSchemas(tree.schema.list), scoped.context, { ...session(), query: {} })
+    const projectLayer: ScopedSchemaBundle = await invoke(listSchemas(tree.schema.list), scoped.context, { ...session(), query: { project: project.id } })
+    expect(entityLayer.types.some(type => type.type === 'test:memo')).toBe(false)
+    expect(projectLayer.origins?.types['test:memo']).toBe(SchemaOrigin.Project)
+    await expect(invoke(listSchemas(tree.schema.list), scoped.context, { ...session(OTHER_ENTITY), query: { project: project.id } }))
+      .rejects.toBeInstanceOf(WorkcardNotFound)
+
+    const retired: SchemaDefineReply = await invoke(defineSchemas(tree.schema.define!), scoped.context, {
+      ...session(), body: { project: project.id, retire: [{ kind: PlanningSchemaKind.Type, key: 'test:memo' }] },
+    })
+    expect([retired.bundle.retired?.types, retired.records[0]?.retired]).toEqual([['test:memo'], true])
+  })
+})

package/tests/app.spec.ts

@@ -0,0 +1,112 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  FieldsInvalid, IntrinsicStatus, makePlanningProtocols, SchemaInvalid, TransitionAction, WorkcardKind,
+} from '@owlmeans/planning'
+import type { PlanningAppDeclarations, SchemaDefineReply, ScopedSchemaBundle, StatusFlowSchema, WorkcardTypeSchema } from '@owlmeans/planning'
+import { defineSchemas, listSchemas } from '../src/actions/index.js'
+import { createProject, createTask, ENTITY, invoke, makeTestPlanning, session, TASK } from './context.js'
+
+const tree = makePlanningProtocols({ base: { alias: 'test:planning' }, guards: 'test-guard', definitions: true })
+
+const DESCRIBED: PlanningAppDeclarations = {
+  type: { properties: { description: { type: 'string' } } },
+  flow: { properties: { description: { type: 'string' } } },
+}
+
+const ESTIMATED: PlanningAppDeclarations = { card: { properties: { estimate: { type: 'number', minimum: 0 } } } }
+
+const ROTA: StatusFlowSchema = {
+  id: 'test:rota', version: 1, statuses: [{ key: 'due', intrinsic: IntrinsicStatus.Planned, initial: true }], transitions: [],
+}
+
+const CHORE: WorkcardTypeSchema = {
+  type: 'test:chore', kind: WorkcardKind.Card, version: 1, flows: [ROTA.id], specifications: [],
+  fields: { type: 'object', additionalProperties: false },
+}
+
+describe('@owlmeans/server-planning — application declarations', () => {
+  test('the service\'s own come first, then every plugin\'s in plugin order; a replaced plugin takes its own away', async () => {
+    const { service } = await makeTestPlanning({
+      schemas: { app: { card: { properties: { estimate: { type: 'string' } } } } },
+      plugins: [
+        { name: 'late', order: 90, schemas: { app: { card: { properties: { estimate: { type: 'number' } }, required: ['estimate'] } } } },
+        { name: 'early', order: 10, schemas: { app: { card: { properties: { estimate: { type: 'integer' }, hours: { type: 'number' } } } } } },
+      ],
+    })
+
+    expect(service.schemas.app()?.card).toEqual({
+      type: 'object', properties: { estimate: { type: 'number' }, hours: { type: 'number' } }, required: ['estimate'],
+    })
+    service.use({ name: 'late' })
+    expect(service.schemas.app()?.card).toEqual({ type: 'object', properties: { estimate: { type: 'integer' }, hours: { type: 'number' } } })
+    expect(service.schemas.bundle().app?.card?.properties.estimate).toEqual({ type: 'integer' })
+  })
+
+  test('a malformed declaration refuses the plugin and leaves the registry as it was', async () => {
+    const { service } = await makeTestPlanning({ plugins: [{ name: 'app', schemas: { app: DESCRIBED } }] })
+    const before = service.plugins().map(plugin => plugin.name)
+
+    expect(() => service.use({ name: 'bad', schemas: { app: { card: { properties: {}, additionalProperties: false } as never } } }))
+      .toThrow(SchemaInvalid)
+    expect(service.plugins().map(plugin => plugin.name)).toEqual(before)
+    expect(service.schemas.app()).toEqual(service.schemas.bundle().app!)
+  })
+
+  test('nothing declared: no `app` in the bundle, and an app bag on a data-defined type is refused', async () => {
+    const { service, facade } = await makeTestPlanning({}, { schemas: true })
+
+    expect('app' in service.schemas.bundle()).toBe(false)
+    expect('app' in await facade().definitions!.bundle()).toBe(false)
+    await expect(facade().definitions!.define({ flows: [ROTA], types: [{ ...CHORE, app: { description: 'x' } }] }))
+      .rejects.toThrow('type:test:chore:app:undeclared')
+    expect(await facade().definitions!.records()).toEqual([])
+  })
+
+  test('base card fields reach a code type with closed fields, on create and on update', async () => {
+    const { facade } = await makeTestPlanning({ plugins: [{ name: 'app', schemas: { app: ESTIMATED } }] })
+    const planning = facade()
+    const project = await createProject(planning)
+
+    const task = (await createTask(planning, project.id!, 'Estimated', { fields: { area: 'user', estimate: 3 } })).card!
+    expect(task.fields).toEqual({ area: 'user', estimate: 3 })
+    await expect(createTask(planning, project.id!, 'Negative', { fields: { estimate: -1 } })).rejects.toBeInstanceOf(FieldsInvalid)
+    await expect(createTask(planning, project.id!, 'Unknown', { fields: { colour: 'red' } })).rejects.toBeInstanceOf(FieldsInvalid)
+    await expect(planning.execute({ card: task.id!, action: TransitionAction.Update, changes: { fields: { estimate: 'soon' } } }, { wait: true }))
+      .rejects.toBeInstanceOf(FieldsInvalid)
+    expect((await planning.execute({ card: task.id!, action: TransitionAction.Update, changes: { fields: { estimate: 5 } } }, { wait: true })).card!.fields.estimate)
+      .toBe(5)
+    // A project is not a card type: its fields are its own type's alone.
+    expect(planning.schemas.fieldsSchema(project.type)).toBe(planning.schemas.type(project.type).fields)
+  })
+
+  test('define, put and seed check the bags; the wire carries them both ways', async () => {
+    const { context, facade } = await makeTestPlanning({ plugins: [{ name: 'app', schemas: { app: { ...DESCRIBED, ...ESTIMATED } } }] }, { schemas: true })
+    const definitions = facade().definitions!
+
+    const reply: SchemaDefineReply = await invoke(defineSchemas(tree.schema.define!), context, {
+      ...session(), body: { flows: [{ ...ROTA, app: { description: 'Weekly' } }], types: [{ ...CHORE, app: { description: 'Small jobs' } }] },
+    })
+    expect(reply.records.map(record => (record.definition as { app?: unknown }).app)).toEqual([{ description: 'Weekly' }, { description: 'Small jobs' }])
+    expect(reply.bundle.app?.type?.properties).toEqual({ description: { type: 'string' } })
+    const listed: ScopedSchemaBundle = await invoke(listSchemas(tree.schema.list), context, { ...session(), query: {} })
+    expect(listed.types.find(type => type.type === CHORE.type)?.app).toEqual({ description: 'Small jobs' })
+
+    await expect(invoke(defineSchemas(tree.schema.define!), context, {
+      ...session(), body: { types: [{ ...CHORE, app: { description: 7 } }] },
+    })).rejects.toBeInstanceOf(SchemaInvalid)
+    await expect(definitions.putType({ ...CHORE, version: 2, app: { owner: 'me' } })).rejects.toThrow('type:test:chore:app:')
+    await expect(definitions.putFlow({ ...ROTA, version: 2, app: { owner: 'me' } })).rejects.toThrow('flow:test:rota:app:')
+    await expect(definitions.seed({ types: [{ ...CHORE, type: 'test:errand', app: { owner: 'me' } }] })).rejects.toBeInstanceOf(SchemaInvalid)
+    expect((await definitions.putType({ ...CHORE, version: 2, app: { description: 'Chores' } })).definition).toMatchObject({ app: { description: 'Chores' } })
+    expect((await definitions.registry()).validator(CHORE.type)({ estimate: 1 })).toBe(true)
+    expect((await definitions.registry()).validator(CHORE.type)({ estimate: -1 })).toBe(false)
+  })
+
+  test('a code task type keeps answering for an organization with no records', async () => {
+    const { facade } = await makeTestPlanning({ plugins: [{ name: 'app', schemas: { app: ESTIMATED } }] }, { schemas: true })
+    const registry = await facade(ENTITY).definitions!.registry()
+
+    expect(registry.validator(TASK)({ area: 'guest', estimate: 2 })).toBe(true)
+    expect(registry.validator(TASK)({ area: 'guest', estimate: -2 })).toBe(false)
+  })
+})

package/tests/conformance.spec.ts

@@ -0,0 +1,47 @@
+import { describe, test } from 'bun:test'
+import { AppType, makeBasicContext } from '@owlmeans/context'
+import type { BasicConfig } from '@owlmeans/context'
+import { appendPlanningService } from '../src/service.js'
+import { makeMemoryPlanningStore } from '../src/store/memory.js'
+import {
+  conformanceCasesFor, conformanceClock, planningConformance, planningConformancePlugin,
+} from '../src/conformance/index.js'
+import type { ConformanceSubject } from '../src/conformance/index.js'
+
+/** The memory store, booted the way a backend boots it, answering every conformance case. */
+const boot = async (schemas: boolean): Promise<ConformanceSubject> => {
+  const now = conformanceClock()
+  const store = makeMemoryPlanningStore({ now, schemas })
+  const cfg: BasicConfig = { ready: false, service: 'planning-conformance', type: AppType.Backend, services: {} }
+  const context = appendPlanningService(makeBasicContext(cfg), { store, now, plugins: [planningConformancePlugin] })
+  context.configure()
+  await context.init()
+  const service = context.planning()
+
+  return {
+    service,
+    store,
+    facade: entityId => service.for({ entityId, profileId: 'conformance-librarian', channel: 'conformance' }),
+  }
+}
+
+describe('@owlmeans/server-planning — store conformance (memory, with data-defined schemas)', () => {
+  const probe = makeMemoryPlanningStore({ schemas: true })
+  for (const entry of conformanceCasesFor(probe)) {
+    test(entry.name, async () => { await entry.run(await boot(true)) })
+  }
+})
+
+describe('@owlmeans/server-planning — store conformance (memory, code schemas only)', () => {
+  const probe = makeMemoryPlanningStore()
+  const cases = conformanceCasesFor(probe)
+  test('a store without the schema port qualifies for every case but the data-defined ones', () => {
+    const skipped = planningConformance.filter(entry => !cases.includes(entry))
+    if (skipped.some(entry => !(entry.needs ?? []).includes('schemas')) || skipped.length === 0) {
+      throw new Error('only the data-defined cases are skipped')
+    }
+  })
+  for (const entry of cases) {
+    test(entry.name, async () => { await entry.run(await boot(false)) })
+  }
+})

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)
+  })
+})