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

package/tests/context.ts

@@ -9,7 +9,7 @@ import type {
 } from '@owlmeans/entrypoint'
 import { ResilientError } from '@owlmeans/error'
 import {
-  CodeScope, CodeStyle, IntrinsicStatus, makePlanningProtocols, SpecificationFormat, TransitionAction,
+  AssigneeKind, CodeScope, CodeStyle, IntrinsicStatus, makePlanningProtocols, SpecificationFormat, TransitionAction,
   WorkcardKind,
 } from '@owlmeans/planning'
 import type {
@@ -86,6 +86,7 @@ const types: AnyTypeSchema[] = [
     flows: [PROJECT_FLOW],
     specifications: [{ category: 'brief', format: SpecificationFormat.Markdown, revisioned: true, type: SPEC }],
     cardTypes: [STORY],
+    scopedCardTypes: true,
   },
   {
     type: STORY,
@@ -111,13 +112,23 @@ const types: AnyTypeSchema[] = [
   },
 ]
 
-export const SCHEMAS: PlanningSchemaBundle = { version: 1, types, flows }
+const assigneeTypes = [{ type: 'test:participant', version: 1, kind: AssigneeKind.Human, fields: { type: 'object', additionalProperties: false } }]
+export const SCHEMAS: PlanningSchemaBundle = { version: 1, types, flows, assigneeTypes }
 
 export const protocols = makePlanningProtocols({
   base: { alias: 'test:planning', path: '/planning' },
   guards: [],
 })
 
+/** The same mount with the data-defined schema surface. */
+export const definitionProtocols = makePlanningProtocols({
+  base: { alias: 'test:planning', path: '/planning' },
+  guards: [],
+  definitions: true,
+})
+
+export const resourceProtocols = makePlanningProtocols({ base: { alias: 'test:planning', path: '/planning' }, guards: [], definitions: true, resources: true })
+
 const AUTH = { profileId: PROFILE_ID, userId: 'user-1', entityId: 'acme' } as unknown as Auth
 const entityOf = (id: string): ResolvedEntity => ({ id, slug: id, iamKey: id })
 
@@ -125,19 +136,28 @@ const entityOf = (id: string): ResolvedEntity => ({ id, slug: id, iamKey: id })
 export interface Call {
   alias: string
   query: Record<string, unknown>
+  reply?: unknown
+  signal?: AbortSignal
 }
 
-export interface SuiteOptions extends Partial<Pick<PlanningClientOptions, 'poll' | 'schemas'>> {
+export interface SuiteOptions extends Partial<Pick<PlanningClientOptions, 'poll' | 'schemas' | 'scopeKey'>> {
   /** The server folds inside `execute` (default) or only on `store.flush()`. */
+  resources?: boolean
   sync?: boolean
   /** Give the client a commit socket. */
   socket?: boolean
   /** Register the state mirror on the client. */
   stores?: boolean
   /** The entity the transport authenticates as. */
-  entityId?: string
+  entityId?: string | (() => string)
+  /** Mount the tree with `definitions: true` over a store holding data-defined schemas. */
+  definitions?: boolean
   /** Runs after the server answered a call and before the client sees the answer. */
   after?: (call: Call) => Promise<void>
+  /** A barrier at the actual transport boundary, before the real server handler runs. */
+  before?: (request: AbstractRequest) => Promise<void>
+  /** A barrier after the real socket handler connected but before its opener returns. */
+  opening?: (connection: Connection, attempt: number) => Promise<void>
 }
 
 export type ClientCtx = ClientContext<ClientConfig> & WithPlanningClient & Partial<WithPlanningStores>
@@ -151,6 +171,7 @@ export interface Suite {
   /** The client's facade. */
   planning: PlanningFacade
   calls: Call[]
+  frames: unknown[]
   sockets: () => number
   project: (title?: string) => Promise<Project>
   story: (project: string, title?: string, fields?: Record<string, unknown>) => Promise<Workcard>
@@ -161,7 +182,7 @@ const wire = <T>(value: T): T => value === undefined ? value : JSON.parse(JSON.s
 type Handled = { handle?: EntrypointHandler }
 
 /** A WebSocket-shaped pipe for the server handler, wired to a client connection reading its frames. */
-const socketPair = (): { server: unknown, client: Connection } => {
+const socketPair = (frames: unknown[]): { server: unknown, client: Connection } => {
   const handlers = new Map<string, Set<(...args: unknown[]) => unknown>>()
   const emit = async (event: string, ...args: unknown[]): Promise<void> => {
     for (const handler of [...(handlers.get(event) ?? [])]) {
@@ -170,7 +191,7 @@ const socketPair = (): { server: unknown, client: Connection } => {
   }
   const client = createBasicConnection()
   const server = {
-    send: async (data: string) => { await client.receive(data) },
+    send: async (data: string) => { frames.push(JSON.parse(data)); await client.receive(data) },
     close: async () => { await emit('close', 1000) },
     on: (event: string, handler: (...args: unknown[]) => unknown) => {
       handlers.set(event, (handlers.get(event) ?? new Set()).add(handler))
@@ -188,17 +209,23 @@ const socketPair = (): { server: unknown, client: Connection } => {
 }
 
 export const makeSuite = async (opts: SuiteOptions = {}): Promise<Suite> => {
-  const entityId = opts.entityId ?? ENTITY_ID
+  const entityKey = () => typeof opts.entityId === 'function' ? opts.entityId() : opts.entityId ?? ENTITY_ID
+  const entityId = entityKey()
 
   const server = makeBasicContext<BasicConfig>({
     ready: false, service: 'client-planning-tests-server', type: AppType.Backend,
   } as BasicConfig)
-  const store = makeMemoryPlanningStore({ sync: opts.sync !== false })
-  appendPlanningService(server, { store, schemas: { types, flows } })
-  server.registerEntrypoints(servePlanningEntrypoints(protocols))
+  const tree = opts.resources === true ? resourceProtocols : opts.definitions === true ? definitionProtocols : protocols
+  const store = makeMemoryPlanningStore({ sync: opts.sync !== false, schemas: opts.definitions === true || opts.resources === true })
+  appendPlanningService(server, { store, schemas: { types, flows, assigneeTypes } })
+  let author: string | undefined
+  server.registerEntrypoints(servePlanningEntrypoints(tree, { scope: () => ({ assigneeId: author }) }))
   await server.configure().init()
 
+  if (opts.resources) author = (await (server as unknown as { planning: () => PlanningService }).planning().for({ entityId }).assignees.create({ nickname: 'commenter', type: 'test:participant', kind: AssigneeKind.Human, authentication: { provider: 'tests', externalId: PROFILE_ID } })).id
+
   const calls: Call[] = []
+  const frames: unknown[] = []
   let opened = 0
 
   const requestOf = (req: Partial<AbstractRequest>, body?: unknown): AbstractRequest => ({
@@ -209,7 +236,7 @@ export const makeSuite = async (opts: SuiteOptions = {}): Promise<Suite> => {
     headers: {},
     path: req.path ?? '',
     auth: AUTH,
-    entity: entityOf(entityId),
+    entity: entityOf(entityKey()),
   })
 
   const client = makeClientContext({
@@ -225,13 +252,14 @@ export const makeSuite = async (opts: SuiteOptions = {}): Promise<Suite> => {
         }
       }
       const request = requestOf(req, wire(req.body))
+      await opts.before?.(req)
       const reply = provideResponse<unknown>()
       try {
         await server.entrypoint<BasicEntrypoint & Handled>(req.alias).handle!(request, reply)
       } catch (e) {
         reply.reject(e as Error)
       }
-      const call = { alias: req.alias, query: request.query as Record<string, unknown> }
+      const call = { alias: req.alias, query: request.query as Record<string, unknown>, reply: wire(reply.value), signal: req.signal }
       calls.push(call)
       await opts.after?.(call)
       if (reply.error != null) {
@@ -245,17 +273,19 @@ export const makeSuite = async (opts: SuiteOptions = {}): Promise<Suite> => {
   }))
 
   appendPlanningClient(client, {
-    protocols,
+    protocols: tree,
+    scopeKey: opts.scopeKey,
     poll: opts.poll ?? 2,
     schemas: opts.schemas,
     ...(opts.socket === true
       ? {
         socket: async (protocol, request) => {
-          const pair = socketPair()
+          const pair = socketPair(frames)
           await server.entrypoint<BasicEntrypoint & Handled>(protocol.alias).handle!(
             requestOf({ alias: protocol.alias, query: request?.query ?? {} }, pair.server), provideResponse()
           )
           opened += 1
+          await opts.opening?.(pair.client, opened)
           return pair.client
         },
       }
@@ -276,7 +306,7 @@ export const makeSuite = async (opts: SuiteOptions = {}): Promise<Suite> => {
   }
 
   const service = (server as unknown as { planning: () => PlanningService }).planning()
-  const local = service.for({ entityId, profileId: PROFILE_ID })
+  const local = service.for({ entityId, profileId: PROFILE_ID, assigneeId: author })
   const planning = client.planning().for()
 
   return {
@@ -286,6 +316,7 @@ export const makeSuite = async (opts: SuiteOptions = {}): Promise<Suite> => {
     client,
     planning,
     calls,
+    frames,
     sockets: () => opened,
     project: async (title = 'Board') => await committed(local.execute({
       card: { kind: WorkcardKind.Project, type: PROJECT, title },

package/tests/csp.spec.ts

@@ -0,0 +1,119 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { appSchemaHelper, makeSchemaRegistry } from '@owlmeans/planning'
+import type { PlanningAppDeclarations, PlanningService } from '@owlmeans/planning'
+import { makePlanningFieldValidator } from '../src/index.js'
+import { makeSuite, STORY } from './context.js'
+import type { Suite, SuiteOptions } from './context.js'
+
+/** What a browser says when a page's `script-src` lacks `'unsafe-eval'`. */
+const REFUSAL = "Evaluating a string as JavaScript violates the following Content Security Policy directive because 'unsafe-eval' is not an allowed source of script"
+
+/** The work-management seed's declarations: every type and flow may carry a description. */
+const APP: PlanningAppDeclarations = {
+  type: { properties: { description: { type: 'string', maxLength: 2000 } } },
+  flow: { properties: { description: { type: 'string', maxLength: 2000 } } },
+}
+const SERVED = appSchemaHelper.merge([APP])
+
+/**
+ * The CLIENT runs in a browser page under the publisher's policy — a `document`, and every code
+ * generation refused — while the in-process server it calls does not: the suite's transport leaves
+ * the page before the server handler runs (`before`) and re-enters it once the server answered
+ * (`after`). Armed only by a test, so the suite's own set-up runs outside it.
+ */
+const makeStrictPage = () => {
+  const scope = globalThis as unknown as Record<string, unknown>
+  const saved = { Function: scope.Function as FunctionConstructor, eval: scope.eval as typeof eval, error: console.error }
+  const counts = { generated: 0, logged: 0 }
+  const refuse = (): never => {
+    counts.generated++
+    throw new EvalError(REFUSAL)
+  }
+  const refusing = { Function: new Proxy(saved.Function, { construct: refuse, apply: refuse }), eval: new Proxy(saved.eval, { apply: refuse }) }
+  let armed = false
+
+  const enter = (): void => {
+    scope.document = {}
+    scope.Function = refusing.Function
+    scope.eval = refusing.eval
+    console.error = () => { counts.logged++ }
+  }
+  const leave = (): void => {
+    delete scope.document
+    scope.Function = saved.Function
+    scope.eval = saved.eval
+    console.error = saved.error
+  }
+
+  return {
+    counts,
+    arm: () => { armed = true; counts.generated = 0; counts.logged = 0; enter() },
+    disarm: () => { armed = false; leave() },
+    hooks: {
+      before: async () => { if (armed) leave() },
+      after: async () => { if (armed) enter() },
+    } satisfies Pick<SuiteOptions, 'before' | 'after'>,
+  }
+}
+
+const page = makeStrictPage()
+
+/** A seed-like target: the application's declarations registered on the server, as its plugin does. */
+const declared = async (opts: SuiteOptions = {}): Promise<Suite> => {
+  const suite = await makeSuite({ schemas: false, ...opts, ...page.hooks })
+  ;(suite.server as unknown as { planning: () => PlanningService }).planning().use({ name: 'seed', schemas: { app: APP } })
+
+  return suite
+}
+
+afterEach(() => page.disarm())
+
+describe('@owlmeans/client-planning — a page under a strict script-src', () => {
+  test('the served bundle loads, a model resolves and a form validates without generating code', async () => {
+    const suite = await declared()
+    const project = await suite.project('Spring')
+    const story = await suite.story(project.id!, 'Warm-up', { area: 'stage' })
+    const service = suite.client.planning()
+
+    page.arm()
+    const registry = await service.loadSchemas()
+    expect(registry.app()).toEqual(SERVED!)
+    const model = await suite.planning.model(story.id!)
+    expect(model.available().map(rule => rule.name)).toContain('start')
+    const form = makePlanningFieldValidator(registry.fieldsSchema(STORY))
+    expect(form.validateFields({ area: 'stage' }).valid).toBe(true)
+    expect(form.validateFields({ area: 2 }).valid).toBe(false)
+    page.disarm()
+
+    expect(page.counts).toEqual({ generated: 0, logged: 0 })
+  })
+
+  test('an organization layer and a project layer resolve through definitions without generating code', async () => {
+    const suite = await declared({ definitions: true })
+    const project = await suite.project('Spring')
+    const story = await suite.story(project.id!, 'Warm-up', { area: 'stage' })
+    const definitions = suite.planning.definitions!
+
+    page.arm()
+    const layer = await definitions.registry()
+    expect(layer.app()).toEqual(SERVED!)
+    expect((await definitions.bundle()).app).toEqual(SERVED!)
+    expect((await definitions.registry(project.id!)).app()).toEqual(SERVED!)
+    const model = await suite.planning.model(story.id!)
+    expect(model.schema().type).toBe(STORY)
+    page.disarm()
+
+    expect(page.counts).toEqual({ generated: 0, logged: 0 })
+  })
+
+  test('the page really refuses code generation: a native validator cannot be compiled in it', async () => {
+    const suite = await declared()
+    const bundle = (await suite.client.planning().loadSchemas()).bundle()
+
+    page.arm()
+    expect(() => makeSchemaRegistry(bundle).validator(STORY)).toThrow(EvalError)
+    page.disarm()
+
+    expect(page.counts.generated).toBeGreaterThan(0)
+  })
+})

package/tests/definitions.spec.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  PlanningSchemaKind, PlanningUnsupported, SchemaOrigin, TransitionAction, WorkcardKind,
+} from '@owlmeans/planning'
+import type { WorkcardTypeSchema } from '@owlmeans/planning'
+import { definitionProtocols, makeSuite, STORY_FLOW } from './context.js'
+
+/** A choir's rehearsal card, defined as data for one project. */
+const REHEARSAL: WorkcardTypeSchema = {
+  type: 'test:rehearsal', kind: WorkcardKind.Card, version: 1, fields: { type: 'object' }, flows: [STORY_FLOW], specifications: [],
+}
+
+describe('@owlmeans/client-planning — data-defined schemas', () => {
+  test('a layer is read once per project and read again after any write', async () => {
+    const suite = await makeSuite({ definitions: true })
+    const project = await suite.project('Spring concert')
+    const definitions = suite.planning.definitions!
+    const reads = () => suite.calls.filter(call => call.alias === definitionProtocols.schema.list.alias).length
+
+    const written = await definitions.define({ types: [REHEARSAL] }, { project: project.id })
+    expect(written.map(record => [record.kind, record.key, record.version, record.project]))
+      .toEqual([[PlanningSchemaKind.Type, REHEARSAL.type, 1, project.id]])
+
+    const before = reads()
+    const layer = await definitions.registry(project.id)
+    await definitions.registry(project.id)
+    expect(reads()).toBe(before + 1)
+    expect(layer.originOf(PlanningSchemaKind.Type, REHEARSAL.type)).toBe(SchemaOrigin.Project)
+    expect((await definitions.bundle()).types.some(type => type.type === REHEARSAL.type)).toBe(false)
+
+    await definitions.putType({ ...REHEARSAL, version: 2, label: 'Rehearsal' }, { project: project.id })
+    expect((await definitions.registry(project.id)).type(REHEARSAL.type).label).toBe('Rehearsal')
+    expect(reads()).toBe(before + 3)
+    await expect(definitions.records()).rejects.toBeInstanceOf(PlanningUnsupported)
+  })
+
+  test('a model of a card resolves its type in its own project\'s layer', async () => {
+    const suite = await makeSuite({ definitions: true })
+    const project = await suite.project('Autumn concert')
+    await suite.planning.definitions!.define({ types: [REHEARSAL] }, { project: project.id })
+    const card = (await suite.local.execute({
+      card: { kind: WorkcardKind.Card, type: REHEARSAL.type, parent: project.id!, title: 'Sectionals' },
+      action: TransitionAction.Create,
+    }, { wait: true })).card!
+
+    const model = await suite.planning.model(card.id!)
+    expect(model.schema().type).toBe(REHEARSAL.type)
+    expect(model.available().map(rule => rule.name)).toEqual(['start', 'reset'])
+  })
+
+  test('a nested card model resolves its data-defined schema through the primary ancestor chain', async () => {
+    const suite = await makeSuite({ definitions: true })
+    const project = await suite.project('Nested rehearsals')
+    await suite.planning.definitions!.define({ types: [{ ...REHEARSAL, children: { types: [REHEARSAL.type] } }] }, { project: project.id })
+    const create = async (parent: string) => (await suite.local.execute({ action: TransitionAction.Create,
+      card: { kind: WorkcardKind.Card, type: REHEARSAL.type, title: 'Section', parent },
+    }, { wait: true })).card!
+    const parent = await create(project.id!)
+    const child = await create(parent.id!)
+    const grandchild = await create(child.id!)
+    const model = await suite.planning.model(grandchild.id!)
+    expect(model.schema().type).toBe(REHEARSAL.type)
+    expect(model.available().map(rule => rule.name)).toEqual(['start', 'reset'])
+    const layers = suite.calls.filter(call => call.alias === definitionProtocols.schema.list.alias).map(call => call.query?.project)
+    expect(layers).not.toContain(parent.id)
+    expect(layers).not.toContain(child.id)
+  })
+
+  test('a tree declared without definitions has none', async () => {
+    const suite = await makeSuite()
+    expect(suite.planning.definitions).toBeUndefined()
+    expect(suite.client.planning().definitions).toBeUndefined()
+  })
+})

package/tests/draft7.spec.ts

@@ -0,0 +1,13 @@
+import { describe, expect, test } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { JSON_SCHEMA_DRAFT_07 } from '../src/validation/consts.js'
+
+describe('@owlmeans/client-planning — the draft-07 meta-schema', () => {
+  test('is ajv\'s own refs file, kept as data rather than imported as JSON', () => {
+    const file = createRequire(import.meta.url).resolve('ajv/dist/refs/json-schema-draft-07.json')
+
+    expect(JSON_SCHEMA_DRAFT_07).toEqual(JSON.parse(readFileSync(file, 'utf8')))
+    expect(readFileSync(new URL('../src/validation.ts', import.meta.url), 'utf8')).not.toContain('.json\'')
+  })
+})

package/tests/events.spec.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from 'bun:test'
 import { CommitState, TransitionAction, WorkcardKind } from '@owlmeans/planning'
 import type { CommitEvent, Transition, Workcard } from '@owlmeans/planning'
-import { applyCards, applyCommitEvent, syncLinks } from '../src/index.js'
+import { planningMirrorOf, syncHelper } from '../src/index.js'
 import { STORY, makeSuite } from './context.js'
 
 /** The frame a bus publishes for a transition — ids only unless a record is given. */
@@ -23,21 +23,23 @@ describe('@owlmeans/client-planning — commit folds', () => {
   test('a committed frame without a record writes the card re-read through the facade', async () => {
     const suite = await makeSuite()
     const stores = suite.client.planningStores!()
+    const mirror = planningMirrorOf(stores)
     const project = await suite.project()
     const receipt = await suite.local.execute({
       card: { kind: WorkcardKind.Card, type: STORY, parent: project.id, title: 'Folded' },
       action: TransitionAction.Create,
     }, { wait: true })
 
-    await applyCommitEvent(stores, frameOf(receipt.transition), suite.planning)
+    await mirror.applyCommitEvent(frameOf(receipt.transition), suite.planning)
 
-    expect(await stores.cards.get(receipt.transition.card)).toEqual(receipt.card!)
+    expect(await stores.cards.get(receipt.transition.card)).toEqual({ ...receipt.card!, entityId: '' })
     expect((await stores.commits.get(receipt.transition.id!)).state).toBe(CommitState.Committed)
   })
 
   test('a committed delete removes the row and every link touching it', async () => {
     const suite = await makeSuite()
     const stores = suite.client.planningStores!()
+    const mirror = planningMirrorOf(stores)
     const project = await suite.project()
     const first = await suite.story(project.id!, 'First')
     const second = (await suite.local.execute({
@@ -45,13 +47,13 @@ describe('@owlmeans/client-planning — commit folds', () => {
       action: TransitionAction.Create,
       links: [{ type: 'follows', to: first.id! }],
     }, { wait: true })).card!
-    await applyCards(stores, [first, second])
+    await mirror.applyCards([first, second])
     const links = await suite.planning.relationships.list({ from: second.id })
-    await syncLinks(stores.links, links.items)
+    await syncHelper.syncLinks(stores.links, links.items)
     expect(await stores.links.count()).toBe(1)
 
     const removal = await suite.local.execute({ card: first.id!, action: TransitionAction.Delete }, { wait: true })
-    await applyCommitEvent(stores, frameOf(removal.transition, null), suite.planning)
+    await mirror.applyCommitEvent(frameOf(removal.transition, null), suite.planning)
 
     expect(await stores.cards.load(first.id!)).toBeNull()
     expect(await stores.cards.load(second.id!)).not.toBeNull()
@@ -61,6 +63,7 @@ describe('@owlmeans/client-planning — commit folds', () => {
   test('a frame for an id the store never saw still writes a row', async () => {
     const suite = await makeSuite()
     const stores = suite.client.planningStores!()
+    const mirror = planningMirrorOf(stores)
     const project = await suite.project()
     const receipt = await suite.local.execute({
       card: { kind: WorkcardKind.Card, type: STORY, parent: project.id, title: 'From another tab' },
@@ -68,7 +71,7 @@ describe('@owlmeans/client-planning — commit folds', () => {
     }, { wait: true })
     expect(await stores.cards.count()).toBe(0)
 
-    await applyCommitEvent(stores, frameOf(receipt.transition, receipt.card))
+    await mirror.applyCommitEvent(frameOf(receipt.transition, receipt.card))
 
     expect((await stores.cards.get(receipt.transition.card)).title).toBe('From another tab')
   })
@@ -76,6 +79,7 @@ describe('@owlmeans/client-planning — commit folds', () => {
   test('an older seq never overwrites a newer record', async () => {
     const suite = await makeSuite()
     const stores = suite.client.planningStores!()
+    const mirror = planningMirrorOf(stores)
     const project = await suite.project()
     const created = await suite.local.execute({
       card: { kind: WorkcardKind.Card, type: STORY, parent: project.id, title: 'Racing' },
@@ -84,9 +88,9 @@ describe('@owlmeans/client-planning — commit folds', () => {
     const started = await suite.local.execute({
       card: created.transition.card, action: TransitionAction.Transit, transition: 'start',
     }, { wait: true })
-    await applyCards(stores, [started.card!])
+    await mirror.applyCards([started.card!])
 
-    await applyCommitEvent(stores, frameOf(created.transition, created.card))
+    await mirror.applyCommitEvent(frameOf(created.transition, created.card))
 
     const stored = await stores.cards.get(created.transition.card)
     expect(stored.seq).toBe(2)

package/tests/facade.spec.ts

@@ -19,7 +19,8 @@ describe('@owlmeans/client-planning — remote facade', () => {
     }
     const remote = await suite.planning.cards.list(query)
 
-    expect(remote).toEqual(await suite.local.cards.list(query))
+    const native = await suite.local.cards.list(query)
+    expect(remote).toEqual({ ...native, items: native.items.map(card => ({ ...card, entityId: '' })) })
     expect(remote.items.map(card => card.title)).toEqual(['Alpha login'])
     expect(await suite.planning.cards.count({ parent: project.id })).toBe(3)
     expect(await suite.planning.cards.summary([project.id!])).toEqual(await suite.local.cards.summary([project.id!]))

package/tests/lifecycle/context.ts

@@ -0,0 +1,29 @@
+import type { ResourceRecord } from '@owlmeans/resource'
+import type { StateResource } from '@owlmeans/state'
+
+export interface Barrier {
+  entered: Promise<void>
+  hold: () => Promise<void>
+  release: () => void
+}
+export interface StoreBarrier extends Barrier { restore: () => void }
+
+/** Delay a real operation once; later calls continue through the actual transport/store. */
+export const makeBarrier = (): Barrier => {
+  let entered!: () => void
+  let release!: () => void
+  let used = false
+  const pending = new Promise<void>(resolve => { release = resolve })
+  const arrived = new Promise<void>(resolve => { entered = resolve })
+  return { entered: arrived, release, hold: async () => {
+    if (used) return
+    used = true; entered(); await pending
+  } }
+}
+
+export const pauseStoreRead = <R extends ResourceRecord>(store: StateResource<R>): StoreBarrier => {
+  const barrier = makeBarrier()
+  const load = store.load.bind(store)
+  store.load = async (...args) => { const row: R | null = await Reflect.apply(load, store, args); await barrier.hold(); return row }
+  return { ...barrier, restore: () => { store.load = load } }
+}

package/tests/lifecycle-close.spec.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from 'bun:test'
+import { TransitionAction, WorkcardKind } from '@owlmeans/planning'
+import type { TransitionReceipt } from '@owlmeans/planning'
+import { makeSuite, STORY, tick } from './context.js'
+import { makeBarrier, pauseStoreRead } from './lifecycle/context.js'
+
+describe('@owlmeans/client-planning — draining an authenticated close', () => {
+  test('drains admitted receipt and auxiliary folds, rejects mid-close RPCs and leaves no late rows', async () => {
+    for (const kind of ['card', 'team', 'commit'] as const) {
+      const suite = await makeSuite({ schemas: false, resources: true, sync: kind !== 'commit' })
+      const stores = suite.client.planningStores!()
+      const project = await suite.project()
+      let pending: TransitionReceipt | undefined
+      if (kind === 'commit') {
+        pending = await suite.planning.execute({ action: TransitionAction.Create, card: { kind: WorkcardKind.Card, type: STORY, parent: project.id!, title: 'Old commit' } })
+        await suite.store.flush()
+      }
+      const pause = kind === 'team' ? pauseStoreRead(stores.teams) : pauseStoreRead(stores.cards)
+      const writing = kind === 'commit' ? pending!.committed() : kind === 'card'
+        ? suite.planning.execute({ action: TransitionAction.Create, card: { kind: WorkcardKind.Card, type: STORY, parent: project.id!, title: 'Old card' } })
+        : suite.planning.teams.create({ name: 'Old team', fields: {} })
+      void writing.catch(() => {})
+      await pause.entered
+      let done = false
+      const closing = suite.client.planning().close().then(() => { done = true })
+      const again = suite.client.planning().close()
+      const calls = suite.calls.length
+      await expect(suite.planning.teams.create({ name: 'During close', fields: {} })).rejects.toThrow('scope-changed')
+      expect(suite.calls.length).toBe(calls)
+      await tick()
+      expect(done).toBe(false)
+      pause.release()
+      await Promise.all([closing, again])
+      await expect(writing).rejects.toThrow('scope-changed')
+      pause.restore()
+      for (const store of Object.values(stores)) expect((await store.list({}, { size: 0 })).items).toEqual([])
+      const fresh = await suite.planning.teams.create({ name: 'After close', fields: {} })
+      expect((await stores.teams.get(fresh.id!)).name).toBe('After close')
+      await suite.client.planning().close()
+    }
+  })
+
+  test('a failed clear blocks fresh work until an explicit retry clears the actual stores', async () => {
+    let identity = 'a'
+    const suite = await makeSuite({ resources: true, schemas: false, scopeKey: () => identity })
+    const stores = suite.client.planningStores!()
+    const old = await suite.planning.teams.create({ name: 'Kept on failure', fields: {} })
+    const remove = stores.teams.delete.bind(stores.teams)
+    let fail = true
+    stores.teams.delete = async (...args) => { if (fail) throw new Error('Storage unavailable'); return await remove(...args) }
+    await expect(suite.client.planning().close()).rejects.toThrow('Storage unavailable')
+    const calls = suite.calls.length
+    await expect(suite.planning.teams.get(old.id!)).rejects.toThrow('scope-changed')
+    expect(suite.calls.length).toBe(calls)
+    expect((await stores.teams.get(old.id!)).name).toBe('Kept on failure')
+    identity = 'b'
+    await expect(suite.planning.teams.list()).rejects.toThrow('scope-changed')
+    expect(suite.calls.length).toBe(calls)
+    fail = false
+    await suite.client.planning().close()
+    expect(await stores.teams.load(old.id!)).toBeNull()
+    expect((await suite.planning.teams.create({ name: 'Recovered', fields: {} })).name).toBe('Recovered')
+    stores.teams.delete = remove
+    await suite.client.planning().close()
+  })
+
+  test('a cached committed receipt is invalid after close while the server write remains committed', async () => {
+    let identity = 'a'
+    const suite = await makeSuite({ schemas: false, scopeKey: () => identity })
+    const project = await suite.project()
+    const receipt = await suite.planning.execute({ action: TransitionAction.Create, card: { kind: WorkcardKind.Card, type: STORY, parent: project.id!, title: 'Committed' } })
+    await suite.client.planning().close()
+    identity = 'b'
+    await expect(receipt.committed()).rejects.toThrow('scope-changed')
+    expect((await suite.local.cards.get(receipt.card!.id!)).title).toBe('Committed')
+    await suite.client.planning().close()
+  })
+
+  test('successive identities each clear after prior admitted writes without accepting the middle generation', async () => {
+    let identity = 'organization-a'
+    const suite = await makeSuite({ resources: true, schemas: false, scopeKey: () => identity, entityId: () => identity })
+    const stores = suite.client.planningStores!()
+    await suite.planning.teams.create({ name: 'A', fields: {} })
+    const pause = makeBarrier()
+    const remove = stores.teams.delete.bind(stores.teams)
+    stores.teams.delete = async (...args) => { await pause.hold(); return await remove(...args) }
+    identity = 'organization-b'
+    suite.client.planning().scopeKey()
+    await pause.entered
+    const middle = suite.planning.teams.create({ name: 'B', fields: {} })
+    void middle.catch(() => {})
+    await tick()
+    identity = 'organization-c'
+    const fresh = suite.planning.teams.create({ name: 'C', fields: {} })
+    pause.release()
+    await expect(middle).rejects.toThrow('scope-changed')
+    const team = await fresh
+    expect((await stores.teams.list({}, { size: 0 })).items.map(row => row.id)).toEqual([team.id])
+    expect(team.name).toBe('C')
+    stores.teams.delete = remove
+    await suite.client.planning().close()
+  })
+})