@owlmeans/server-planning 0.1.18-rc.2 → 0.1.18-rc.21

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

package/tests/creator.spec.ts

@@ -0,0 +1,257 @@
+import { describe, expect, test } from 'bun:test'
+import { CommitState, makePlanningProtocols, PlanningError, TransitionAction, WorkcardKind } from '@owlmeans/planning'
+import type { PlanningFacade, Transition, TransitionExecution, WorkcardChanges, WorkcardDraft } from '@owlmeans/planning'
+import { executePlanning, wireExecution } from '../src/actions/index.js'
+import { assertCreatorFixed, creatorOf, withCreator } from '../src/executor.js'
+import { createProject, createTask, ENTITY, invoke, makeTestPlanning, PROFILE, PROJECT, session, TASK } from './context.js'
+
+const tree = makePlanningProtocols({ base: { alias: 'test:planning' }, guards: 'test-guard' })
+
+const draftOf = (exec: TransitionExecution): WorkcardDraft => exec.card as WorkcardDraft
+
+describe('@owlmeans/server-planning — a create\'s createdBy', () => {
+  test('an in-process create is stamped with the scope\'s profile, on the card and in the log', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning)
+    const receipt = await createTask(planning, project.id!)
+
+    expect(project.createdBy).toBe(PROFILE)
+    expect(receipt.card!.createdBy).toBe(PROFILE)
+    expect(receipt.transition.changes?.createdBy).toBe(PROFILE)
+    expect((await planning.cards.get(receipt.card!.id!)).createdBy).toBe(PROFILE)
+  })
+
+  test('an explicit createdBy wins over the scope', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning, 'Delegated', { createdBy: 'owner-7' })
+
+    expect(project.createdBy).toBe('owner-7')
+    expect((await createTask(planning, project.id!, 'Theirs', { createdBy: 'owner-8' })).card!.createdBy).toBe('owner-8')
+  })
+
+  test('the subject falls back to the userId, then to the scope\'s actor', async () => {
+    const { service } = await makeTestPlanning()
+
+    const byUser = await createProject(service.for({ entityId: ENTITY, userId: 'user-9' }))
+    const byActor = await createProject(service.for({ entityId: ENTITY, actor: { profileId: 'agent-profile' } }))
+
+    expect(byUser.createdBy).toBe('user-9')
+    expect(byActor.createdBy).toBe('agent-profile')
+  })
+
+  test('a scope that names nobody leaves createdBy unset', async () => {
+    const { service } = await makeTestPlanning()
+
+    const system = await createProject(service.for({ entityId: ENTITY, service: 'importer', channel: 'job' }))
+
+    expect(system.createdBy).toBeUndefined()
+    expect(Object.keys(system)).not.toContain('createdBy')
+  })
+
+  test('later writes by another profile never move it, and the caller\'s execution is not touched', async () => {
+    const { service, facade } = await makeTestPlanning()
+    const exec: TransitionExecution = {
+      card: { kind: WorkcardKind.Project, type: PROJECT, title: 'Kept' }, action: TransitionAction.Create,
+    }
+    const project = (await facade().execute(exec, { wait: true })).card!
+    const other = service.for({ entityId: ENTITY, profileId: 'profile-2' })
+
+    await other.execute({ card: project.id!, action: TransitionAction.Update, changes: { title: 'Renamed' } }, { wait: true })
+    await other.execute({ card: project.id!, action: TransitionAction.Transit, transition: 'activate' }, { wait: true })
+
+    expect((await other.cards.get(project.id!)).createdBy).toBe(PROFILE)
+    expect(draftOf(exec).createdBy).toBeUndefined()
+  })
+
+  test('a before plugin already sees the stamped createdBy', async () => {
+    const seen: (string | undefined)[] = []
+    const { facade } = await makeTestPlanning({
+      plugins: [{
+        name: 'owner-check', order: 10,
+        before: async exec => { seen.push(typeof exec.card === 'object' ? exec.card.createdBy : 'update') },
+      }],
+    })
+
+    await createProject(facade())
+
+    expect(seen).toEqual([PROFILE])
+  })
+
+  test('the wire action is unchanged: the body\'s claim is replaced by the request\'s subject', async () => {
+    const { context } = await makeTestPlanning()
+    const execute = executePlanning(tree.execute)
+    const body = { card: { kind: WorkcardKind.Project, type: PROJECT, title: 'Wire', createdBy: 'intruder' }, action: TransitionAction.Create, wait: true }
+
+    const signed = await invoke(execute, context, { ...session(), body })
+    expect(signed.card.createdBy).toBe(PROFILE)
+
+    const byUser = await invoke(execute, context, {
+      ...session(ENTITY, { auth: { type: 'test', userId: 'user-1', entitySlug: ENTITY, scopes: ['*'] } }), body,
+    })
+    expect(byUser.card.createdBy).toBe('user-1')
+
+    const anonymous = await invoke(execute, context, {
+      ...session(ENTITY, { auth: { type: 'test', entitySlug: ENTITY, scopes: ['*'] } }), body,
+    })
+    expect(anonymous.card.createdBy).toBeUndefined()
+  })
+
+  test('wireExecution still answers the execution the executor will run', () => {
+    const body = { card: { kind: WorkcardKind.Project, type: PROJECT, title: 'W', createdBy: 'intruder' }, action: TransitionAction.Create }
+
+    expect(draftOf(wireExecution(body, { entityId: ENTITY, profileId: PROFILE, userId: 'user-1' })).createdBy).toBe(PROFILE)
+    expect(draftOf(wireExecution(body, { entityId: ENTITY, userId: 'user-1' })).createdBy).toBe('user-1')
+    expect(draftOf(wireExecution(body, { entityId: ENTITY })).createdBy).toBeUndefined()
+  })
+
+  test('creatorOf and withCreator', () => {
+    expect(creatorOf({ entityId: ENTITY, profileId: 'p', userId: 'u', actor: { profileId: 'a' } })).toBe('p')
+    expect(creatorOf({ entityId: ENTITY, profileId: '', userId: 'u' })).toBe('u')
+    expect(creatorOf({ entityId: ENTITY, actor: { userId: 'au', service: 's' } })).toBe('au')
+    expect(creatorOf({ entityId: ENTITY, service: 's' })).toBeUndefined()
+
+    const update: TransitionExecution = { card: 'card-1', action: TransitionAction.Update, changes: { title: 'T' } }
+    expect(withCreator(update, { entityId: ENTITY, profileId: 'p' })).toBe(update)
+    const blank: TransitionExecution = { card: { kind: WorkcardKind.Project, type: PROJECT, title: 'T', createdBy: '' }, action: TransitionAction.Create }
+    expect(draftOf(withCreator(blank, { entityId: ENTITY, profileId: 'p' })).createdBy).toBe('p')
+  })
+})
+
+/** The refusal of a write that names a provenance field, and the log it left untouched. */
+const refusedOf = async (run: Promise<unknown>): Promise<string> => {
+  const error = await run.then(() => null, (error: Error) => error)
+  expect(error).toBeInstanceOf(PlanningError)
+  return error!.message
+}
+
+const logOf = async (planning: PlanningFacade, card: string): Promise<number> =>
+  (await planning.transitions.list({ card })).total
+
+describe('@owlmeans/server-planning — createdBy never moves after the create', () => {
+  test('an in-process update, transit, unset or create overlay naming it is refused, and nothing is appended', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning)
+    const task = (await createTask(planning, project.id!)).card!
+    const attempts: TransitionExecution[] = [
+      { card: task.id!, action: TransitionAction.Update, changes: { createdBy: 'intruder' } },
+      { card: task.id!, action: TransitionAction.Update, changes: { title: 'Mine now', createdBy: 'intruder' } },
+      { card: task.id!, action: TransitionAction.Update, changes: { createdBy: null } as unknown as WorkcardChanges },
+      { card: task.id!, action: TransitionAction.Update, unset: ['createdBy'] },
+      { card: task.id!, action: TransitionAction.Transit, transition: 'start', changes: { createdBy: 'intruder' } },
+      { card: { kind: WorkcardKind.Card, type: TASK, parent: project.id!, title: 'Overlay' }, action: TransitionAction.Create, changes: { createdBy: 'intruder' } },
+    ]
+
+    for (const exec of attempts) {
+      expect(await refusedOf(planning.execute(exec, { wait: true }))).toBe('planning:immutable:createdBy')
+    }
+    expect(await refusedOf(planning.execute({ card: task.id!, action: TransitionAction.Update, changes: { createdAt: '2001-01-01T00:00:00.000Z' } as WorkcardChanges })))
+      .toBe('planning:immutable:createdAt')
+    expect(await refusedOf(planning.execute({ card: task.id!, action: TransitionAction.Update, unset: ['createdAt'] })))
+      .toBe('planning:immutable:createdAt')
+
+    const card = await planning.cards.get(task.id!)
+    expect([card.createdBy, card.title, card.status, card.seq]).toEqual([PROFILE, 'A task', 'todo', 1])
+    expect(await logOf(planning, task.id!)).toBe(1)
+    expect((await planning.cards.list({ parent: project.id })).total).toBe(1)
+  })
+
+  test('a before plugin cannot move it either', async () => {
+    const { facade } = await makeTestPlanning({
+      plugins: [{
+        name: 'reassign', order: 10,
+        before: async exec => exec.action === TransitionAction.Update
+          ? { ...exec, changes: { ...exec.changes, createdBy: 'plugin-owner' } }
+          : undefined,
+      }],
+    })
+    const planning = facade()
+    const project = await createProject(planning)
+
+    expect(await refusedOf(planning.execute({ card: project.id!, action: TransitionAction.Update, changes: { title: 'Renamed' } })))
+      .toBe('planning:immutable:createdBy')
+    expect((await planning.cards.get(project.id!)).createdBy).toBe(PROFILE)
+  })
+
+  test('a trusted in-process create names it; the owner then moves it no more than anyone else', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning, 'On behalf', { createdBy: 'owner-7' })
+    await planning.execute({ card: project.id!, action: TransitionAction.Update, changes: { title: 'Still theirs' } }, { wait: true })
+
+    expect(await refusedOf(planning.execute({ card: project.id!, action: TransitionAction.Update, changes: { createdBy: PROFILE } })))
+      .toBe('planning:immutable:createdBy')
+    expect((await planning.cards.get(project.id!))).toMatchObject({ title: 'Still theirs', createdBy: 'owner-7', seq: 2 })
+  })
+
+  test('the wire refuses it on an update, an unset and a create\'s changes; the draft claim is still dropped', async () => {
+    const { context, facade } = await makeTestPlanning()
+    const execute = executePlanning(tree.execute)
+    const created = await invoke(execute, context, {
+      ...session(), body: { card: { kind: WorkcardKind.Project, type: PROJECT, title: 'Wire', createdBy: 'intruder' }, action: TransitionAction.Create, wait: true },
+    })
+    const id = created.card.id as string
+    const bodies = [
+      { card: id, action: TransitionAction.Update, changes: { createdBy: 'intruder' }, wait: true },
+      { card: id, action: TransitionAction.Update, changes: { title: 'Hijacked', createdBy: 'intruder' }, wait: true },
+      { card: id, action: TransitionAction.Update, unset: ['createdBy'], wait: true },
+      { card: id, action: TransitionAction.Transit, transition: 'activate', changes: { createdBy: 'intruder' }, wait: true },
+      { card: { kind: WorkcardKind.Project, type: PROJECT, title: 'Overlay' }, action: TransitionAction.Create, changes: { createdBy: 'intruder' }, wait: true },
+    ]
+
+    for (const body of bodies) {
+      expect(await refusedOf(invoke(execute, context, { ...session(), body }))).toBe('planning:immutable:createdBy')
+    }
+    expect(await refusedOf(invoke(execute, context, { ...session(), body: { card: id, action: TransitionAction.Update, unset: ['createdAt'] } })))
+      .toBe('planning:immutable:createdAt')
+
+    expect(created.card.createdBy).toBe(PROFILE)
+    const card = await facade().cards.get(id)
+    expect([card.createdBy, card.title, card.status, card.seq]).toEqual([PROFILE, 'Wire', 'open', 1])
+    expect(await logOf(facade(), id)).toBe(1)
+    expect((await facade().cards.list({ kind: WorkcardKind.Project })).total).toBe(1)
+  })
+
+  test('a legacy transition that named it still folds, and the card keeps committing past it', async () => {
+    const { facade, store } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning)
+    const task = (await createTask(planning, project.id!)).card!
+    const legacy = async (patch: Partial<Transition>) => {
+      const seq = await store.transitions!.nextSeq(task.id!, null)
+      return await store.transitions!.append({
+        entityId: task.entityId, card: task.id!, kind: task.kind, type: task.type, project: project.id!, seq,
+        action: TransitionAction.Update, changes: {}, actor: { profileId: 'intruder' },
+        at: '2001-01-01T00:00:00.000Z', commit: { state: CommitState.Pending }, ...patch,
+      })
+    }
+
+    const renamed = await legacy({ changes: { title: 'Legacy', createdBy: 'intruder' } })
+    const cleared = await legacy({ unset: ['createdBy'] })
+    await store.cards.project(task.id!)
+
+    expect((await planning.commits.status(renamed.id!)).state).toBe(CommitState.Committed)
+    expect((await planning.commits.status(cleared.id!)).state).toBe(CommitState.Committed)
+    const folded = await planning.cards.get(task.id!)
+    expect([folded.title, folded.seq, folded.createdBy]).toEqual(['Legacy', 3, undefined])
+
+    await planning.execute({ card: task.id!, action: TransitionAction.Update, changes: { title: 'After' } }, { wait: true })
+    expect(await refusedOf(planning.execute({ card: task.id!, action: TransitionAction.Update, changes: { createdBy: PROFILE } })))
+      .toBe('planning:immutable:createdBy')
+    expect((await planning.cards.get(task.id!))).toMatchObject({ title: 'After', seq: 4 })
+  })
+
+  test('assertCreatorFixed', () => {
+    const draft = { kind: WorkcardKind.Project, type: PROJECT, title: 'T', createdBy: 'owner' }
+
+    expect(() => assertCreatorFixed({ card: draft, action: TransitionAction.Create })).not.toThrow()
+    expect(() => assertCreatorFixed({ card: 'c', action: TransitionAction.Update, changes: { title: 'T', createdBy: undefined } })).not.toThrow()
+    expect(() => assertCreatorFixed({ card: 'c', action: TransitionAction.Update, unset: ['fields.createdBy'] })).not.toThrow()
+    expect(() => assertCreatorFixed({ card: 'c', action: TransitionAction.Update, changes: { fields: { createdBy: 'x' } } })).not.toThrow()
+    expect(() => assertCreatorFixed({ card: 'c', action: TransitionAction.Update, changes: { createdBy: 'x' } })).toThrow('planning:immutable:createdBy')
+    expect(() => assertCreatorFixed({ card: 'c', action: TransitionAction.Delete, unset: ['createdBy'] })).toThrow('planning:immutable:createdBy')
+    expect(() => assertCreatorFixed({ card: draft, action: TransitionAction.Create, changes: { createdBy: 'x' } })).toThrow('planning:immutable:createdBy')
+  })
+})

package/tests/entrypoints.spec.ts

@@ -16,6 +16,11 @@ describe('@owlmeans/server-planning — entrypoints', () => {
 
     expect(bindings.length).toBe(declared.length)
     expect(new Set(bindings.map(binding => binding.alias))).toEqual(new Set(declared.map(protocol => protocol.alias)))
+
+    const scoped = makePlanningProtocols({ base: { alias: 'test:planning' }, guards: 'test-guard', definitions: true })
+    const all = protocols(scoped as never)
+    expect(servePlanningEntrypoints(scoped).map(binding => binding.alias).sort()).toEqual(all.map(protocol => protocol.alias).sort())
+    expect(all.length).toBe(declared.length + 1)
   })
 
   test('execute takes the actor and createdBy from the request, never from the body', async () => {

package/tests/narrowing.spec.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from 'bun:test'
+import { WorkcardKind, WorkcardNotFound } from '@owlmeans/planning'
+import type { PlanningFacade, Workcard } from '@owlmeans/planning'
+import { createProject, createTask, ENTITY, makeTestPlanning, PROFILE } from './context.js'
+
+/**
+ * Two projects with a task each, a design document on each task and a plan on the first project —
+ * a specification's `parents` hold only its own card, so a scope narrowed to one project sees the
+ * task's document through the task.
+ */
+const fixture = async () => {
+  const planning = await makeTestPlanning()
+  const owner = planning.facade()
+  const granted = await createProject(owner, 'Granted')
+  const hidden = await createProject(owner, 'Hidden')
+  const seen = (await createTask(owner, granted.id!, 'Seen')).card!
+  const unseen = (await createTask(owner, hidden.id!, 'Unseen')).card!
+  const write = async (card: Workcard, category: string, body: string): Promise<Workcard> =>
+    (await (await owner.model(card)).write(category, body, { wait: true })).card!
+  const design = await write(seen, 'design', '{"steps":[1]}')
+  const hiddenDesign = await write(unseen, 'design', '{"steps":[2]}')
+  const plan = await write(granted, 'plan', '{"steps":[3]}')
+  const scoped = (projects: string[]): PlanningFacade =>
+    planning.service.for({ entityId: ENTITY, profileId: PROFILE, channel: 'test', projects })
+
+  return { ...planning, owner, granted, hidden, seen, unseen, design, hiddenDesign, plan, scoped }
+}
+
+const ids = (items: Workcard[]): string[] => items.map(card => card.id!).sort()
+
+describe('@owlmeans/server-planning — a narrowed scope lists what it reads', () => {
+  test('a granted card\'s specification is listed and counted as it is read', async () => {
+    const { seen, unseen, design, hiddenDesign, plan, granted, scoped } = await fixture()
+    const member = scoped([granted.id!])
+
+    expect((await member.cards.get(design.id!)).id).toBe(design.id!)
+    await expect(member.cards.get(hiddenDesign.id!)).rejects.toBeInstanceOf(WorkcardNotFound)
+
+    const underCard = await member.cards.list({ parent: seen.id!, kind: WorkcardKind.Specification })
+    expect(ids(underCard.items)).toEqual([design.id!])
+    expect(underCard.total).toBe(1)
+    expect(await member.cards.count({ parent: seen.id!, kind: WorkcardKind.Specification })).toBe(1)
+    expect((await member.cards.list({ parent: unseen.id!, kind: WorkcardKind.Specification })).items).toEqual([])
+    expect(await member.cards.count({ parent: unseen.id! })).toBe(0)
+
+    const everyDocument = await member.cards.list({ kind: WorkcardKind.Specification })
+    expect(ids(everyDocument.items)).toEqual([design.id!, plan.id!].sort())
+    expect(await member.cards.count({ kind: WorkcardKind.Specification })).toBe(2)
+    expect(ids((await member.cards.list({ kind: WorkcardKind.Card })).items)).toEqual([seen.id!])
+
+    expect(ids((await member.cards.list({ parent: seen.id!, category: 'design' })).items)).toEqual([design.id!])
+    expect((await member.specifications.list(seen.id!)).total).toBe(1)
+    // A summary counts a parent's cards, never its documents.
+    expect(Object.keys(await member.cards.summary([granted.id!, seen.id!, unseen.id!]))).toEqual([granted.id!])
+  })
+
+  test('every card the narrowed scope reads is the one it lists, and no other', async () => {
+    const { owner, granted, scoped } = await fixture()
+    const member = scoped([granted.id!])
+    const every = { size: 0, kind: [WorkcardKind.Project, WorkcardKind.Card, WorkcardKind.Specification] }
+    const everything = (await owner.cards.list(every)).items
+    const listed = new Set(ids((await member.cards.list(every)).items))
+
+    expect(everything.length).toBe(7)
+    for (const card of everything) {
+      expect([card.id, (await member.cards.load(card.id!)) != null]).toEqual([card.id, listed.has(card.id!)])
+    }
+    expect(listed.size).toBe(4)
+    expect(await member.cards.count(every)).toBe(listed.size)
+  })
+
+  test('a scope with no project, or another one, sees none of the granted project\'s documents', async () => {
+    const { seen, design, plan, hidden, scoped } = await fixture()
+
+    for (const outsider of [scoped([]), scoped([hidden.id!])]) {
+      await expect(outsider.cards.get(design.id!)).rejects.toBeInstanceOf(WorkcardNotFound)
+      expect((await outsider.cards.list({ parent: seen.id!, kind: WorkcardKind.Specification })).items).toEqual([])
+      expect(await outsider.cards.count({ parent: seen.id! })).toBe(0)
+      const documents = ids((await outsider.cards.list({ kind: WorkcardKind.Specification })).items)
+      expect(documents).not.toContain(design.id!)
+      expect(documents).not.toContain(plan.id!)
+    }
+    expect((await scoped([]).cards.list({ size: 0, kind: [WorkcardKind.Card, WorkcardKind.Specification] })).total).toBe(0)
+  })
+
+  test('an unnarrowed scope sees every document of the organization', async () => {
+    const { owner, unseen, design, hiddenDesign, plan } = await fixture()
+
+    expect(ids((await owner.cards.list({ kind: WorkcardKind.Specification })).items))
+      .toEqual([design.id!, hiddenDesign.id!, plan.id!].sort())
+    expect(await owner.cards.count({ kind: WorkcardKind.Specification })).toBe(3)
+    expect(ids((await owner.cards.list({ parent: unseen.id!, kind: WorkcardKind.Specification })).items)).toEqual([hiddenDesign.id!])
+  })
+})

package/tests/plugins.spec.ts

@@ -1,3 +1,4 @@
+import { configureLog, logConfig } from '@owlmeans/log'
 import { describe, expect, test } from 'bun:test'
 import { CommitState, PlanningRefused, TransitionAction, WorkcardKind } from '@owlmeans/planning'
 import { makeMemoryPlanningStore } from '../src/store/memory.js'
@@ -66,8 +67,8 @@ describe('@owlmeans/server-planning — plugins', () => {
       ],
     }, { sync: false })
     const planning = facade()
-    const errors = console.error
-    console.error = () => undefined
+    const { level } = logConfig()
+    configureLog({ level: 'silent' })
     try {
       const receipt = await planning.execute({ card: { kind: WorkcardKind.Project, type: PROJECT, title: 'Later' }, action: TransitionAction.Create })
       expect(receipt.transition.commit.state).toBe(CommitState.Pending)
@@ -80,7 +81,7 @@ describe('@owlmeans/server-planning — plugins', () => {
       expect(seen).toEqual([`${receipt.transition.card}:committed:test`])
       expect((await receipt.committed({ timeout: 100 }))!.title).toBe('Later')
     } finally {
-      console.error = errors
+      configureLog({ level })
     }
   })
 })