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

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, executionHelper } from '../src/actions/index.js'
+import { createProject, createTask, ENTITY, invoke, makeTestPlanning, PROFILE, PROJECT, session, TASK } from './context.js'
+import { creatorHelper } from '../src/executor.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(executionHelper.wireExecution(body, { entityId: ENTITY, profileId: PROFILE, userId: 'user-1' })).createdBy).toBe(PROFILE)
+    expect(draftOf(executionHelper.wireExecution(body, { entityId: ENTITY, userId: 'user-1' })).createdBy).toBe('user-1')
+    expect(draftOf(executionHelper.wireExecution(body, { entityId: ENTITY })).createdBy).toBeUndefined()
+  })
+
+  test('creatorOf and withCreator', () => {
+    expect(creatorHelper.creatorOf({ entityId: ENTITY, profileId: 'p', userId: 'u', actor: { profileId: 'a' } })).toBe('p')
+    expect(creatorHelper.creatorOf({ entityId: ENTITY, profileId: '', userId: 'u' })).toBe('u')
+    expect(creatorHelper.creatorOf({ entityId: ENTITY, actor: { userId: 'au', service: 's' } })).toBe('au')
+    expect(creatorHelper.creatorOf({ entityId: ENTITY, service: 's' })).toBeUndefined()
+
+    const update: TransitionExecution = { card: 'card-1', action: TransitionAction.Update, changes: { title: 'T' } }
+    expect(creatorHelper.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(creatorHelper.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(() => creatorHelper.assertCreatorFixed({ card: draft, action: TransitionAction.Create })).not.toThrow()
+    expect(() => creatorHelper.assertCreatorFixed({ card: 'c', action: TransitionAction.Update, changes: { title: 'T', createdBy: undefined } })).not.toThrow()
+    expect(() => creatorHelper.assertCreatorFixed({ card: 'c', action: TransitionAction.Update, unset: ['fields.createdBy'] })).not.toThrow()
+    expect(() => creatorHelper.assertCreatorFixed({ card: 'c', action: TransitionAction.Update, changes: { fields: { createdBy: 'x' } } })).not.toThrow()
+    expect(() => creatorHelper.assertCreatorFixed({ card: 'c', action: TransitionAction.Update, changes: { createdBy: 'x' } })).toThrow('planning:immutable:createdBy')
+    expect(() => creatorHelper.assertCreatorFixed({ card: 'c', action: TransitionAction.Delete, unset: ['createdBy'] })).toThrow('planning:immutable:createdBy')
+    expect(() => creatorHelper.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/memory-store.spec.ts

@@ -52,6 +52,58 @@ describe('@owlmeans/server-planning — the memory store', () => {
     expect(await store.cards.purge(kept.id!, ENTITY)).toBe(4)
   })
 
+  test('deleting a card takes its own documents with their log, edges and comments, and keeps its own delete', async () => {
+    const { facade, store } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning)
+    const task = (await createTask(planning, project.id!, 'Documented')).card!
+    const other = (await createTask(planning, project.id!, 'Other')).card!
+    const design = (await planning.execute({
+      card: { kind: WorkcardKind.Specification, type: SPEC, parent: task.id!, title: 'design', category: 'design', format: SpecificationFormat.Json, body: '{}' },
+      action: TransitionAction.Create,
+    }, { wait: true })).card!
+    // A document of the document, an edge into it and a comment with its mention — no fixture
+    // type declares them, so they are written to the store directly.
+    const at = new Date().toISOString()
+    await store.cards.put({ ...design, id: 'nested-document', parent: design.id!, parents: [design.id!], title: 'nested' })
+    await store.links.put({ entityId: ENTITY, type: 'blocks', from: other.id!, to: design.id!, createdAt: at })
+    const comment = await store.comments!.put({ entityId: ENTITY, card: design.id!, author: 'author-1', body: 'Looks right', version: 1, createdAt: at })
+    const mention = await store.mentions!.put({ entityId: ENTITY, comment: comment.id!, card: design.id!, assignee: 'author-1', revision: 1, version: 1, createdAt: at })
+
+    const deleted = await planning.execute({ card: task.id!, action: TransitionAction.Delete }, { wait: true })
+
+    expect((await planning.commits.status(deleted.transition.id!)).state).toBe(CommitState.Committed)
+    for (const id of [task.id!, design.id!, 'nested-document']) {
+      expect(await planning.cards.load(id)).toBeNull()
+    }
+    expect((await planning.cards.list({ kind: WorkcardKind.Specification })).total).toBe(0)
+    expect((await store.transitions.list({ entityId: ENTITY, card: design.id! })).total).toBe(0)
+    expect((await store.transitions.list({ entityId: ENTITY, card: task.id! })).items.map(row => row.action))
+      .toEqual([TransitionAction.Create, TransitionAction.Delete])
+    expect((await store.links.list({ entityId: ENTITY, to: design.id! })).total).toBe(0)
+    expect(await store.comments!.get(comment.id!, ENTITY)).toBeNull()
+    expect(await store.mentions!.get(mention.id!, ENTITY)).toBeNull()
+    expect(await planning.cards.load(other.id!)).not.toBeNull()
+  })
+
+  test('a card with a child card is refused its delete, documents or not', async () => {
+    const { facade, store } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning)
+    const task = (await createTask(planning, project.id!, 'Parent')).card!
+    await planning.execute({
+      card: { kind: WorkcardKind.Specification, type: SPEC, parent: task.id!, title: 'design', category: 'design', format: SpecificationFormat.Json, body: '{}' },
+      action: TransitionAction.Create,
+    }, { wait: true })
+    // No fixture type admits a child card under a task, so the child is written to the store directly.
+    await store.cards.put({ ...task, id: 'child-card', code: undefined, parent: task.id!, parents: [task.id!], title: 'Child' })
+
+    await expect(planning.execute({ card: task.id!, action: TransitionAction.Delete }, { wait: true }))
+      .rejects.toThrow(`hierarchy:parent-in-use:${task.id}`)
+    expect(await planning.cards.load(task.id!)).not.toBeNull()
+    expect((await planning.specifications.current(task.id!, 'design'))?.body).toBe('{}')
+  })
+
   test('byKey answers the first transition under that key, within its entity only', async () => {
     const { facade, store } = await makeTestPlanning()
     const planning = facade()

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

package/tests/writes.spec.ts

@@ -0,0 +1,140 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  makePlanningProtocols, PlanningForbidden, SchemaOrigin, SpecificationFormat, TransitionAction, WorkcardKind,
+} from '@owlmeans/planning'
+import type { SchemaDefineReply, ScopedSchemaBundle, Specification } from '@owlmeans/planning'
+import { defineSchemas, executePlanning, getCard, listCards, listSchemas } from '../src/actions/index.js'
+import type { PlanningAccess, PlanningHandlerOptions } from '../src/types.js'
+import { createProject, createTask, ENTITY, invoke, makeTestPlanning, PROJECT, session, TASK } from './context.js'
+
+const tree = makePlanningProtocols({ base: { alias: 'test:planning' }, guards: 'test-guard', definitions: true })
+
+const withAccess = (access: PlanningAccess): PlanningHandlerOptions => ({ access: async () => access })
+
+const flow = { id: 'test:rota', version: 1, statuses: [{ key: 'due', intrinsic: 'planned' }], transitions: [] }
+
+/** Two projects: the caller views both and writes only in `written`. */
+const setup = async () => {
+  const planning = await makeTestPlanning({}, { schemas: true })
+  const { facade } = planning
+  const viewed = await createProject(facade(), 'Viewed')
+  const written = await createProject(facade(), 'Written')
+  const viewedTask = (await createTask(facade(), viewed.id!, 'Viewed task')).card!
+  const writtenTask = (await createTask(facade(), written.id!, 'Written task')).card!
+  const access: PlanningAccess = { entityId: ENTITY, projects: [viewed.id!, written.id!], writes: [written.id!] }
+
+  return { ...planning, viewed, written, viewedTask, writtenTask, access, opts: withAccess(access) }
+}
+
+describe('@owlmeans/server-planning — per-project writes', () => {
+  test('a viewer reads a project it may not write in', async () => {
+    const { context, viewed, viewedTask, opts } = await setup()
+
+    expect((await invoke(getCard(tree.card.get, opts), context, { ...session(), params: { id: viewedTask.id } })).id).toBe(viewedTask.id)
+    const listed = await invoke(listCards(tree.card.list, opts), context, { ...session(), query: { parent: viewed.id } })
+    expect(listed.items.map((card: { id: string }) => card.id)).toEqual([viewedTask.id])
+    const bundle: ScopedSchemaBundle = await invoke(listSchemas(tree.schema.list), context, { ...session(), query: { project: viewed.id } })
+    expect(bundle.types.some(type => type.type === TASK)).toBe(true)
+  })
+
+  test('a viewer\'s execute answers 403 on a card, a project, a create and a link; nothing is appended', async () => {
+    const { context, facade, viewed, viewedTask, writtenTask, opts } = await setup()
+    const execute = executePlanning(tree.execute, opts)
+    const refused = async (body: Record<string, unknown>) =>
+      await expect(invoke(execute, context, { ...session(), body })).rejects.toBeInstanceOf(PlanningForbidden)
+
+    expect(PlanningForbidden.httpStatus).toBe(403)
+    await refused({ card: viewedTask.id, action: TransitionAction.Update, changes: { title: 'Renamed' } })
+    await refused({ card: viewedTask.id, action: TransitionAction.Transit, transition: 'start' })
+    await refused({ card: viewed.id, action: TransitionAction.Update, changes: { title: 'Renamed' } })
+    await refused({ card: viewed.id, action: TransitionAction.Delete })
+    await refused({ card: { kind: WorkcardKind.Card, type: TASK, parent: viewed.id, title: 'Sneaky' }, action: TransitionAction.Create })
+    await refused({ card: { kind: WorkcardKind.Card, type: TASK, parent: writtenTask.id, parents: [viewed.id], title: 'Sneaky' }, action: TransitionAction.Create })
+    await refused({ card: viewedTask.id, action: TransitionAction.Link, link: { type: 'blocks', to: writtenTask.id } })
+
+    expect((await facade().cards.get(viewedTask.id!)).title).toBe('Viewed task')
+    expect((await facade().cards.get(viewed.id!)).title).toBe('Viewed')
+    expect((await facade().cards.list({ parent: viewed.id })).items.map(card => card.id)).toEqual([viewedTask.id])
+  })
+
+  test('a specification is written through its parent card', async () => {
+    const { context, facade, viewedTask, writtenTask, opts } = await setup()
+    const execute = executePlanning(tree.execute, opts)
+    const design = async (task: string) => ((await (await facade().model(await facade().cards.get(task)))
+      .write('design', '{"v":1}', { wait: true })).card as Specification)
+    const viewedDesign = await design(viewedTask.id!)
+    const writtenDesign = await design(writtenTask.id!)
+
+    await expect(invoke(execute, context, {
+      ...session(), body: { card: viewedDesign.id, action: TransitionAction.Update, changes: { body: '{"v":2}' } },
+    })).rejects.toBeInstanceOf(PlanningForbidden)
+    await expect(invoke(execute, context, {
+      ...session(), body: {
+        card: { kind: WorkcardKind.Specification, type: viewedDesign.type, parent: viewedTask.id, category: 'design', format: SpecificationFormat.Json, title: 'd', body: '{}' },
+        action: TransitionAction.Create,
+      },
+    })).rejects.toBeInstanceOf(PlanningForbidden)
+    const updated = await invoke(execute, context, {
+      ...session(), body: { card: writtenDesign.id, action: TransitionAction.Update, changes: { body: '{"v":2}' }, wait: true },
+    })
+    expect(updated.card.body).toBe('{"v":2}')
+  })
+
+  test('a writer writes in its project: create, transit, link, and its project layer', async () => {
+    const { context, facade, written, writtenTask, viewedTask, opts } = await setup()
+    const execute = executePlanning(tree.execute, opts)
+
+    const made = await invoke(execute, context, {
+      ...session(), body: { card: { kind: WorkcardKind.Card, type: TASK, parent: written.id, title: 'Allowed' }, action: TransitionAction.Create, wait: true },
+    })
+    expect(made.card.parent).toBe(written.id)
+    await invoke(execute, context, { ...session(), body: { card: writtenTask.id, action: TransitionAction.Transit, transition: 'start', wait: true } })
+    expect((await facade().cards.get(writtenTask.id!)).status).toBe('doing')
+    // A link FROM a writable card may point at a card the caller only views.
+    await invoke(execute, context, {
+      ...session(), body: { card: writtenTask.id, action: TransitionAction.Link, link: { type: 'blocks', to: viewedTask.id }, wait: true },
+    })
+    await invoke(execute, context, { ...session(), body: { card: written.id, action: TransitionAction.Update, changes: { title: 'Renamed' }, wait: true } })
+    expect((await facade().cards.get(written.id!)).title).toBe('Renamed')
+
+    const layer: SchemaDefineReply = await invoke(defineSchemas(tree.schema.define!, opts), context, {
+      ...session(), body: { project: written.id, flows: [flow] },
+    })
+    expect(layer.bundle.origins?.flows['test:rota']).toBe(SchemaOrigin.Project)
+  })
+
+  test('a viewer\'s project-layer schema define answers 403; writes never reach the root', async () => {
+    const { context, viewed, access, opts } = await setup()
+
+    await expect(invoke(defineSchemas(tree.schema.define!, opts), context, {
+      ...session(), body: { project: viewed.id, flows: [flow] },
+    })).rejects.toBeInstanceOf(PlanningForbidden)
+    // `writes` does not gate the organization layer (that is `grants.defineSchemas`), nor a project create.
+    const project = await invoke(executePlanning(tree.execute, opts), context, {
+      ...session(), body: { card: { kind: WorkcardKind.Project, type: PROJECT, title: 'New' }, action: TransitionAction.Create, wait: true },
+    })
+    expect(project.card.kind).toBe(WorkcardKind.Project)
+    await expect(invoke(defineSchemas(tree.schema.define!, withAccess({ ...access, grants: { defineSchemas: [viewed.id!] } })), context, {
+      ...session(), body: { project: viewed.id, flows: [flow] },
+    })).rejects.toBeInstanceOf(PlanningForbidden)
+    // A project create stays `createProjects`' decision when grants are present.
+    await expect(invoke(executePlanning(tree.execute, withAccess({ ...access, grants: {} })), context, {
+      ...session(), body: { card: { kind: WorkcardKind.Project, type: PROJECT, title: 'Refused' }, action: TransitionAction.Create },
+    })).rejects.toBeInstanceOf(PlanningForbidden)
+  })
+
+  test('absent writes keep the old behaviour: every visible project is writable', async () => {
+    const { context, facade, viewed, viewedTask, access } = await setup()
+    const { writes: _writes, ...open } = access
+    const opts = withAccess(open)
+
+    await invoke(executePlanning(tree.execute, opts), context, {
+      ...session(), body: { card: viewedTask.id, action: TransitionAction.Update, changes: { title: 'Renamed' }, wait: true },
+    })
+    expect((await facade().cards.get(viewedTask.id!)).title).toBe('Renamed')
+    const layer: SchemaDefineReply = await invoke(defineSchemas(tree.schema.define!, opts), context, {
+      ...session(), body: { project: viewed.id, flows: [flow] },
+    })
+    expect(layer.records.map(record => record.key)).toEqual(['test:rota'])
+  })
+})

package/build/actions/cards.d.ts

@@ -1,16 +0,0 @@
-import { handlers } from '@owlmeans/server-api';
-import type { PlanningProtocols } from '@owlmeans/planning';
-import type { Context, PlanningHandlerOptions } from '../types.js';
-type RequestHandler = ReturnType<ReturnType<typeof handlers<Context>>['request']>;
-/** Cards of the caller's entity; the query arrives in its wire shape and is decoded here. */
-export declare const listCards: (protocol: PlanningProtocols['card']['list'], opts?: PlanningHandlerOptions) => RequestHandler;
-/** Intrinsic counts of DIRECT children per parent. */
-export declare const summarizeCards: (protocol: PlanningProtocols['card']['summary'], opts?: PlanningHandlerOptions) => RequestHandler;
-/** @throws {WorkcardNotFound} for an absent card and for another entity's alike */
-export declare const getCard: (protocol: PlanningProtocols['card']['get'], opts?: PlanningHandlerOptions) => RequestHandler;
-/** One card's log. */
-export declare const listCardTransitions: (protocol: PlanningProtocols['card']['transitions'], opts?: PlanningHandlerOptions) => RequestHandler;
-/** One card's specifications — the current document per category unless `all`. */
-export declare const listCardSpecifications: (protocol: PlanningProtocols['card']['specifications'], opts?: PlanningHandlerOptions) => RequestHandler;
-export {};
-//# sourceMappingURL=cards.d.ts.map

package/build/actions/cards.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cards.d.ts","sourceRoot":"","sources":["../../src/actions/cards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAI/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAGlE,KAAK,cAAc,GAAG,UAAU,CAAC,UAAU,CAAC,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAA;AAEjF,6FAA6F;AAC7F,eAAO,MAAM,SAAS,aAAc,iBAAiB,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,SAAS,sBAAsB,KAAG,cAKlG,CAAA;AAEL,sDAAsD;AACtD,eAAO,MAAM,cAAc,aAAc,iBAAiB,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,SAAS,sBAAsB,KAAG,cAM1G,CAAA;AAEL,mFAAmF;AACnF,eAAO,MAAM,OAAO,aAAc,iBAAiB,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,SAAS,sBAAsB,KAAG,cAK/F,CAAA;AAEL,sBAAsB;AACtB,eAAO,MAAM,mBAAmB,aAAc,iBAAiB,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,SAAS,sBAAsB,KAAG,cAMnH,CAAA;AAEL,kFAAkF;AAClF,eAAO,MAAM,sBAAsB,aAAc,iBAAiB,CAAC,MAAM,CAAC,CAAC,gBAAgB,CAAC,SAAS,sBAAsB,KAAG,cAMzH,CAAA"}

package/build/actions/cards.js

@@ -1,32 +0,0 @@
-import { handlers } from '@owlmeans/server-api';
-import { decodeSpecificationQuery, decodeSummaryQuery, decodeTransitionQuery, decodeWorkcardQuery, } from '@owlmeans/planning';
-import { concealed, handlerFacade } from '../utils/index.js';
-/** Cards of the caller's entity; the query arrives in its wire shape and is decoded here. */
-export const listCards = (protocol, opts) => handlers().request(protocol, async (req, ctx) => concealed(async () => {
-    const facade = await handlerFacade(ctx, req, opts);
-    return await facade.cards.list(decodeWorkcardQuery(req.query));
-}));
-/** Intrinsic counts of DIRECT children per parent. */
-export const summarizeCards = (protocol, opts) => handlers().request(protocol, async (req, ctx) => concealed(async () => {
-    const facade = await handlerFacade(ctx, req, opts);
-    const { parents, ...query } = decodeSummaryQuery(req.query);
-    return await facade.cards.summary(parents, query);
-}));
-/** @throws {WorkcardNotFound} for an absent card and for another entity's alike */
-export const getCard = (protocol, opts) => handlers().request(protocol, async (req, ctx) => concealed(async () => {
-    const facade = await handlerFacade(ctx, req, opts);
-    return await facade.cards.get(`${req.params.id}`);
-}));
-/** One card's log. */
-export const listCardTransitions = (protocol, opts) => handlers().request(protocol, async (req, ctx) => concealed(async () => {
-    const facade = await handlerFacade(ctx, req, opts);
-    const card = await facade.cards.get(`${req.params.id}`);
-    return await facade.transitions.list({ ...decodeTransitionQuery(req.query), card: card.id });
-}));
-/** One card's specifications — the current document per category unless `all`. */
-export const listCardSpecifications = (protocol, opts) => handlers().request(protocol, async (req, ctx) => concealed(async () => {
-    const facade = await handlerFacade(ctx, req, opts);
-    const card = await facade.cards.get(`${req.params.id}`);
-    return await facade.specifications.list(card.id, decodeSpecificationQuery(req.query));
-}));
-//# sourceMappingURL=cards.js.map