@owlmeans/client-planning 0.1.18-rc.0

package/tests/commits.spec.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from 'bun:test'
+import { CommitState, CommitTimeout, TransitionAction, WorkcardKind } from '@owlmeans/planning'
+import { STORY, makeSuite, protocols, tick } from './context.js'
+import type { Suite } from './context.js'
+
+const draft = (suite: Suite, parent: string) => suite.planning.execute({
+  card: { kind: WorkcardKind.Card, type: STORY, parent, title: 'Waited for' },
+  action: TransitionAction.Create,
+})
+
+describe('@owlmeans/client-planning — waiting for a commit', () => {
+  test('wait subscribes before its first read, so a commit landing right after that read is caught', async () => {
+    let transition: string | undefined
+    let landed = false
+    const suite: Suite = await makeSuite({
+      sync: false,
+      socket: true,
+      poll: 20,
+      // The server folds the moment it has answered the first status read — after the read, before
+      // anything else the client does. Only a subscription made BEFORE the read can hear it.
+      after: async call => {
+        if (!landed && call.alias === protocols.commit.get.alias && transition != null) {
+          landed = true
+          await suite.store.flush()
+          await tick(10)
+        }
+      },
+    })
+    const project = await suite.project()
+    const receipt = await draft(suite, project.id!)
+    transition = receipt.transition.id
+    const before = suite.calls.length
+
+    const card = await suite.planning.commits.wait(transition!, { timeout: 5_000 })
+
+    expect(card?.title).toBe('Waited for')
+    expect(suite.sockets()).toBe(1)
+    // One status read and nothing else: the frame answered, not a long poll.
+    expect(suite.calls.slice(before).filter(call => call.alias === protocols.commit.get.alias)).toHaveLength(1)
+  })
+
+  test('without a socket the long poll alone brings the commit', async () => {
+    const suite = await makeSuite({ sync: false, poll: 2 })
+    const project = await suite.project()
+    const receipt = await draft(suite, project.id!)
+
+    setTimeout(() => { void suite.store.flush() }, 300)
+    const card = await suite.planning.commits.wait(receipt.transition.id!, { timeout: 5_000 })
+
+    expect(card?.title).toBe('Waited for')
+    expect(suite.client.planning().commits.connected()).toBe(false)
+    expect(suite.calls.some(call => call.alias === protocols.commit.get.alias && Number(call.query.wait) > 0)).toBe(true)
+  })
+
+  test('the deadline throws CommitTimeout and leaves the transition pending', async () => {
+    const suite = await makeSuite({ sync: false, poll: 1 })
+    const project = await suite.project()
+    const receipt = await draft(suite, project.id!)
+
+    const started = Date.now()
+    await expect(suite.planning.commits.wait(receipt.transition.id!, { timeout: 1_200 }))
+      .rejects.toBeInstanceOf(CommitTimeout)
+    expect(Date.now() - started).toBeLessThan(3_000)
+
+    expect((await suite.planning.commits.status(receipt.transition.id!)).state).toBe(CommitState.Pending)
+  })
+})

package/tests/context.ts

@@ -0,0 +1,301 @@
+import type { Auth } from '@owlmeans/auth'
+import { makeClientContext } from '@owlmeans/client-context'
+import type { ClientConfig, ClientContext } from '@owlmeans/client-context'
+import { AppType, createService, makeBasicContext } from '@owlmeans/context'
+import type { BasicConfig, BasicContext, BasicEntrypoint } from '@owlmeans/context'
+import { EntrypointOutcome, provideResponse, transportAlias } from '@owlmeans/entrypoint'
+import type {
+  AbstractRequest, AbstractResponse, EntrypointHandler, EntrypointTransport, ResolvedEntity,
+} from '@owlmeans/entrypoint'
+import { ResilientError } from '@owlmeans/error'
+import {
+  CodeScope, CodeStyle, IntrinsicStatus, makePlanningProtocols, SpecificationFormat, TransitionAction,
+  WorkcardKind,
+} from '@owlmeans/planning'
+import type {
+  AnyTypeSchema, PlanningFacade, PlanningSchemaBundle, PlanningService, Project, StatusFlowSchema,
+  TransitionReceipt, Workcard,
+} from '@owlmeans/planning'
+import { RouteProtocols } from '@owlmeans/route'
+import { appendPlanningService, servePlanningEntrypoints } from '@owlmeans/server-planning'
+import { makeMemoryPlanningStore } from '@owlmeans/server-planning/store'
+import type { MemoryPlanningStore } from '@owlmeans/server-planning/store'
+import { createBasicConnection } from '@owlmeans/socket'
+import type { Connection } from '@owlmeans/socket'
+import { appendPlanningClient, appendPlanningStores } from '../src/index.js'
+import type { PlanningClientOptions, WithPlanningClient, WithPlanningStores } from '../src/index.js'
+
+/**
+ * The whole suite runs a REAL `@owlmeans/server-planning` behind the client, with no network.
+ *
+ * Two contexts are built, as two processes would build them: a server context with
+ * `appendPlanningService` over the memory store and the handlers `servePlanningEntrypoints` binds,
+ * and a client context with `appendPlanningClient`. What connects them is the framework's own
+ * transport seam — a service under `transportAlias('http')` takes every client call — and it does
+ * what the HTTP hop does to a call, no more: the request crosses as JSON, a query value that is not a
+ * scalar is refused (axios would write `key[]=` and fastify would read that key literally), the
+ * request reaches the SERVER handler with the authenticated entity and profile the HTTP boundary
+ * would attach, and a refusal crosses as the marshalled text the API client unmarshals. The commit
+ * socket is the server's own `commit.events` handler over an in-memory socket pair: the server side
+ * is `@owlmeans/server-socket`'s connection over a WebSocket-shaped pipe, the client side a
+ * `@owlmeans/socket` connection reading the same frames.
+ */
+
+export const ENTITY_ID = 'entity-acme'
+export const OTHER_ENTITY_ID = 'entity-other'
+export const PROFILE_ID = 'profile-1'
+
+export const STORY_FLOW = 'test:story-flow'
+export const PROJECT_FLOW = 'test:project-flow'
+export const PROJECT = 'test:project'
+export const STORY = 'test:story'
+export const SPEC = 'test:spec'
+
+const flows: StatusFlowSchema[] = [
+  {
+    id: STORY_FLOW,
+    version: 1,
+    statuses: [
+      { key: 'todo', intrinsic: IntrinsicStatus.Planned, initial: true },
+      { key: 'doing', intrinsic: IntrinsicStatus.InProgress },
+      { key: 'done', intrinsic: IntrinsicStatus.Closed, terminal: true },
+    ],
+    transitions: [
+      { name: 'start', from: ['todo'], to: 'doing', explicit: true },
+      { name: 'finish', from: ['doing'], to: 'done', explicit: true },
+      { name: 'reset', from: '*', to: 'todo' },
+    ],
+  },
+  {
+    id: PROJECT_FLOW,
+    version: 1,
+    statuses: [
+      { key: 'open', intrinsic: IntrinsicStatus.InProgress, initial: true },
+      { key: 'archived', intrinsic: IntrinsicStatus.Closed, terminal: true },
+    ],
+    transitions: [{ name: 'archive', from: ['open'], to: 'archived' }],
+  },
+]
+
+const types: AnyTypeSchema[] = [
+  {
+    type: PROJECT,
+    kind: WorkcardKind.Project,
+    version: 1,
+    fields: { type: 'object', additionalProperties: true },
+    flows: [PROJECT_FLOW],
+    specifications: [{ category: 'brief', format: SpecificationFormat.Markdown, revisioned: true, type: SPEC }],
+    cardTypes: [STORY],
+  },
+  {
+    type: STORY,
+    kind: WorkcardKind.Card,
+    version: 1,
+    fields: {
+      type: 'object',
+      properties: { area: { type: 'string' } },
+      additionalProperties: false,
+    },
+    flows: [STORY_FLOW],
+    specifications: [],
+    relationships: [{ name: 'follows' }],
+    code: { prefix: 'ST-', style: CodeStyle.Random, length: 5, uppercase: true, uniqueWithin: CodeScope.Parent },
+  },
+  {
+    type: SPEC,
+    kind: WorkcardKind.Specification,
+    version: 1,
+    fields: { type: 'object', additionalProperties: true },
+    flows: [STORY_FLOW],
+    specifications: [],
+  },
+]
+
+export const SCHEMAS: PlanningSchemaBundle = { version: 1, types, flows }
+
+export const protocols = makePlanningProtocols({
+  base: { alias: 'test:planning', path: '/planning' },
+  guards: [],
+})
+
+const AUTH = { profileId: PROFILE_ID, userId: 'user-1', entityId: 'acme' } as unknown as Auth
+const entityOf = (id: string): ResolvedEntity => ({ id, slug: id, iamKey: id })
+
+/** What crossed the transport, per call — the specs read it to prove which route answered. */
+export interface Call {
+  alias: string
+  query: Record<string, unknown>
+}
+
+export interface SuiteOptions extends Partial<Pick<PlanningClientOptions, 'poll' | 'schemas'>> {
+  /** The server folds inside `execute` (default) or only on `store.flush()`. */
+  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
+  /** Runs after the server answered a call and before the client sees the answer. */
+  after?: (call: Call) => Promise<void>
+}
+
+export type ClientCtx = ClientContext<ClientConfig> & WithPlanningClient & Partial<WithPlanningStores>
+
+export interface Suite {
+  server: BasicContext<BasicConfig>
+  store: MemoryPlanningStore
+  /** The server's own facade for the transport's entity — the ground truth a spec compares with. */
+  local: PlanningFacade
+  client: ClientCtx
+  /** The client's facade. */
+  planning: PlanningFacade
+  calls: Call[]
+  sockets: () => number
+  project: (title?: string) => Promise<Project>
+  story: (project: string, title?: string, fields?: Record<string, unknown>) => Promise<Workcard>
+}
+
+const wire = <T>(value: T): T => value === undefined ? value : JSON.parse(JSON.stringify(value)) as T
+
+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 handlers = new Map<string, Set<(...args: unknown[]) => unknown>>()
+  const emit = async (event: string, ...args: unknown[]): Promise<void> => {
+    for (const handler of [...(handlers.get(event) ?? [])]) {
+      await handler(...args)
+    }
+  }
+  const client = createBasicConnection()
+  const server = {
+    send: async (data: string) => { 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))
+    },
+    off: (event: string, handler: (...args: unknown[]) => unknown) => { handlers.get(event)?.delete(handler) },
+    ping: () => { },
+    pong: () => { },
+  }
+  client.send = async message => {
+    await emit('message', Buffer.from(typeof message === 'string' ? message : JSON.stringify(message)))
+  }
+  client.close = async () => { await emit('close', 1000) }
+
+  return { server, client }
+}
+
+export const makeSuite = async (opts: SuiteOptions = {}): Promise<Suite> => {
+  const entityId = opts.entityId ?? ENTITY_ID
+
+  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))
+  await server.configure().init()
+
+  const calls: Call[] = []
+  let opened = 0
+
+  const requestOf = (req: Partial<AbstractRequest>, body?: unknown): AbstractRequest => ({
+    alias: req.alias ?? '',
+    params: wire(req.params ?? {}),
+    query: wire(req.query ?? {}),
+    body: body as AbstractRequest['body'],
+    headers: {},
+    path: req.path ?? '',
+    auth: AUTH,
+    entity: entityOf(entityId),
+  })
+
+  const client = makeClientContext({
+    ready: false, service: 'client-planning-tests', type: AppType.Frontend, layer: undefined, services: {},
+  } as unknown as ClientConfig) as ClientCtx
+
+  client.registerService(createService<EntrypointTransport>(transportAlias(RouteProtocols.WEB), {
+    protocol: RouteProtocols.WEB,
+    handle: (async (req: AbstractRequest, res: AbstractResponse<unknown>) => {
+      for (const [key, value] of Object.entries(req.query ?? {})) {
+        if (value != null && typeof value === 'object') {
+          throw new SyntaxError(`Query value ${key} does not survive a URL`)
+        }
+      }
+      const request = requestOf(req, wire(req.body))
+      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> }
+      calls.push(call)
+      await opts.after?.(call)
+      if (reply.error != null) {
+        // What the server writes as the error body, and what the API client makes of it.
+        const text = ResilientError.marshal(ResilientError.ensure(reply.error)).message
+        res.reject(ResilientError.ensure(text, true))
+        return
+      }
+      res.resolve(wire(reply.value), reply.outcome ?? EntrypointOutcome.Ok)
+    }) as EntrypointHandler,
+  }))
+
+  appendPlanningClient(client, {
+    protocols,
+    poll: opts.poll ?? 2,
+    schemas: opts.schemas,
+    ...(opts.socket === true
+      ? {
+        socket: async (protocol, request) => {
+          const pair = socketPair()
+          await server.entrypoint<BasicEntrypoint & Handled>(protocol.alias).handle!(
+            requestOf({ alias: protocol.alias, query: request?.query ?? {} }, pair.server), provideResponse()
+          )
+          opened += 1
+          return pair.client
+        },
+      }
+      : {}),
+  })
+  if (opts.stores !== false) {
+    appendPlanningStores(client)
+  }
+  await client.configure().init()
+
+  /** A write the server itself makes, folded whichever way the store folds. */
+  const committed = async (pending: Promise<TransitionReceipt>): Promise<Workcard> => {
+    const receipt = await pending
+    if (opts.sync === false) {
+      await store.flush()
+    }
+    return await receipt.committed() as Workcard
+  }
+
+  const service = (server as unknown as { planning: () => PlanningService }).planning()
+  const local = service.for({ entityId, profileId: PROFILE_ID })
+  const planning = client.planning().for()
+
+  return {
+    server,
+    store,
+    local,
+    client,
+    planning,
+    calls,
+    sockets: () => opened,
+    project: async (title = 'Board') => await committed(local.execute({
+      card: { kind: WorkcardKind.Project, type: PROJECT, title },
+      action: TransitionAction.Create,
+    })) as Project,
+    story: async (project, title = 'A story', fields) => await committed(local.execute({
+      card: { kind: WorkcardKind.Card, type: STORY, parent: project, title, ...(fields != null ? { fields } : {}) },
+      action: TransitionAction.Create,
+    })),
+  }
+}
+
+export const tick = async (ms = 0): Promise<void> => await new Promise(resolve => setTimeout(resolve, ms))

package/tests/events.spec.ts

@@ -0,0 +1,95 @@
+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 { STORY, makeSuite } from './context.js'
+
+/** The frame a bus publishes for a transition — ids only unless a record is given. */
+const frameOf = (transition: Transition, record?: Workcard | null): CommitEvent => ({
+  transition: transition.id!,
+  card: transition.card,
+  entityId: transition.entityId,
+  project: transition.project,
+  kind: transition.kind,
+  type: transition.type,
+  seq: transition.seq,
+  action: transition.action,
+  state: CommitState.Committed,
+  at: transition.at,
+  ...(record !== undefined ? { record } : {}),
+})
+
+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 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)
+
+    expect(await stores.cards.get(receipt.transition.card)).toEqual(receipt.card!)
+    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 project = await suite.project()
+    const first = await suite.story(project.id!, 'First')
+    const second = (await suite.local.execute({
+      card: { kind: WorkcardKind.Card, type: STORY, parent: project.id, title: 'Second' },
+      action: TransitionAction.Create,
+      links: [{ type: 'follows', to: first.id! }],
+    }, { wait: true })).card!
+    await applyCards(stores, [first, second])
+    const links = await suite.planning.relationships.list({ from: second.id })
+    await 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)
+
+    expect(await stores.cards.load(first.id!)).toBeNull()
+    expect(await stores.cards.load(second.id!)).not.toBeNull()
+    expect(await stores.links.count()).toBe(0)
+  })
+
+  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 project = await suite.project()
+    const receipt = await suite.local.execute({
+      card: { kind: WorkcardKind.Card, type: STORY, parent: project.id, title: 'From another tab' },
+      action: TransitionAction.Create,
+    }, { wait: true })
+    expect(await stores.cards.count()).toBe(0)
+
+    await applyCommitEvent(stores, frameOf(receipt.transition, receipt.card))
+
+    expect((await stores.cards.get(receipt.transition.card)).title).toBe('From another tab')
+  })
+
+  test('an older seq never overwrites a newer record', async () => {
+    const suite = await makeSuite()
+    const stores = suite.client.planningStores!()
+    const project = await suite.project()
+    const created = await suite.local.execute({
+      card: { kind: WorkcardKind.Card, type: STORY, parent: project.id, title: 'Racing' },
+      action: TransitionAction.Create,
+    }, { wait: true })
+    const started = await suite.local.execute({
+      card: created.transition.card, action: TransitionAction.Transit, transition: 'start',
+    }, { wait: true })
+    await applyCards(stores, [started.card!])
+
+    await applyCommitEvent(stores, frameOf(created.transition, created.card))
+
+    const stored = await stores.cards.get(created.transition.card)
+    expect(stored.seq).toBe(2)
+    expect(stored.status).toBe('doing')
+  })
+})

package/tests/facade.spec.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  IllegalTransition, TransitionAction, WorkcardKind, WorkcardNotFound,
+} from '@owlmeans/planning'
+import type { Specification, WorkcardQuery } from '@owlmeans/planning'
+import { OTHER_ENTITY_ID, PROFILE_ID, PROJECT, STORY, makeSuite } from './context.js'
+
+describe('@owlmeans/client-planning — remote facade', () => {
+  test('a rich query means on the client exactly what it means on the server', async () => {
+    const suite = await makeSuite()
+    const project = await suite.project()
+    await suite.story(project.id!, 'Alpha login', { area: 'auth' })
+    await suite.story(project.id!, 'Beta login', { area: 'billing' })
+    await suite.story(project.id!, 'Gamma search', { area: 'auth' })
+
+    const query: WorkcardQuery = {
+      kind: WorkcardKind.Card, type: [STORY], parent: project.id, status: ['todo', 'doing'],
+      fields: { area: 'auth' }, q: 'login', sort: ['title'], size: 0,
+    }
+    const remote = await suite.planning.cards.list(query)
+
+    expect(remote).toEqual(await suite.local.cards.list(query))
+    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!]))
+  })
+
+  test('a server refusal arrives as its own class', async () => {
+    const suite = await makeSuite()
+    const project = await suite.project()
+    const story = await suite.story(project.id!)
+
+    const illegal = suite.planning.execute({ card: story.id!, action: TransitionAction.Transit, transition: 'finish' })
+    await expect(illegal).rejects.toBeInstanceOf(IllegalTransition)
+
+    await expect(suite.planning.cards.get('missing')).rejects.toBeInstanceOf(WorkcardNotFound)
+    expect(await suite.planning.cards.load('missing')).toBeNull()
+
+    // Another entity's card is answered exactly like a missing one.
+    const foreign = await (suite.server as any).planning().for({ entityId: OTHER_ENTITY_ID }).execute({
+      card: { kind: WorkcardKind.Project, type: PROJECT, title: 'Theirs' }, action: TransitionAction.Create,
+    }, { wait: true })
+    await expect(suite.planning.cards.get(foreign.card.id)).rejects.toBeInstanceOf(WorkcardNotFound)
+  })
+
+  test('execute answers a receipt whose committed() resolves with the folded card', async () => {
+    const suite = await makeSuite({ sync: false })
+    const project = await suite.project()
+
+    const receipt = await suite.planning.execute({
+      card: { kind: WorkcardKind.Card, type: STORY, parent: project.id, title: 'Remote story' },
+      action: TransitionAction.Create,
+      // The server decides who wrote; whatever the wire says is ignored.
+      actor: { profileId: 'forged' },
+    })
+    expect(receipt.transition.actor.profileId).toBe(PROFILE_ID)
+
+    setTimeout(() => { void suite.store.flush() }, 50)
+    const card = await receipt.committed({ timeout: 5_000 })
+    expect(card?.title).toBe('Remote story')
+    expect(card?.code).toMatch(/^ST-/)
+
+    const model = await suite.planning.model(card!)
+    expect(model.can('start')).toBe(true)
+    setTimeout(() => { void suite.store.flush() }, 50)
+    const started = await model.transit('start', undefined, { wait: true, timeout: 5_000 })
+    expect(started.card?.status).toBe('doing')
+  })
+
+  test('a model writes a specification, then revises the same record', async () => {
+    const suite = await makeSuite()
+    const project = await suite.planning.model(await suite.project())
+
+    await project.write('brief', '# First', { wait: true })
+    await project.write('brief', '# Second', { wait: true })
+
+    const current = await suite.planning.specifications.current(project.id, 'brief') as Specification
+    expect(current.body).toBe('# Second')
+    expect(current.revision).toBe(2)
+    const history = await suite.planning.specifications.revisions(current.id!)
+    expect(history.map(revision => revision.body)).toContain('# First')
+  })
+})

package/tests/feed.spec.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'bun:test'
+import { makePlanningFeed } from '../src/index.js'
+import { makeSuite, tick } from './context.js'
+
+describe('@owlmeans/client-planning — the feed', () => {
+  test('seeds the mirror from the list, then folds every commit the socket pushes', async () => {
+    const suite = await makeSuite({ socket: true })
+    const stores = suite.client.planningStores!()
+    const project = await suite.project()
+    const first = await suite.story(project.id!, 'Seeded')
+
+    const feed = makePlanningFeed(suite.client, { query: { parent: project.id }, filter: { project: project.id } })
+    await feed.ready
+    expect(feed.seeded).toBe(true)
+    expect(feed.connected).toBe(true)
+    expect((await stores.cards.get(first.id!)).title).toBe('Seeded')
+
+    const second = await suite.story(project.id!, 'Pushed')
+    await tick(20)
+    expect((await stores.cards.get(second.id!)).title).toBe('Pushed')
+
+    await feed.stop()
+  })
+
+  test('stop() ends the folding and leaves the shared socket open', async () => {
+    const suite = await makeSuite({ socket: true })
+    const stores = suite.client.planningStores!()
+    const project = await suite.project()
+
+    const feed = makePlanningFeed(suite.client, { query: { parent: project.id } })
+    await feed.ready
+    await feed.stop()
+
+    const late = await suite.story(project.id!, 'After stop')
+    await tick(20)
+    expect(await stores.cards.load(late.id!)).toBeNull()
+    expect(suite.client.planning().commits.connected()).toBe(true)
+  })
+})

package/tests/stores.spec.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from 'bun:test'
+import { isPending, modelOf, TransitionAction, WorkcardKind } from '@owlmeans/planning'
+import { applyCards, syncCards } from '../src/index.js'
+import { makeSuite } from './context.js'
+
+describe('@owlmeans/client-planning — the state mirror', () => {
+  test('syncCards drops only what matches `where` and the list does not name', async () => {
+    const suite = await makeSuite()
+    const stores = suite.client.planningStores!()
+    const one = await suite.project('One')
+    const two = await suite.project('Two')
+    const kept = await suite.story(one.id!, 'Kept')
+    const deleted = await suite.story(one.id!, 'Deleted elsewhere')
+    const elsewhere = await suite.story(two.id!, 'Another project')
+    await applyCards(stores, [one, two, kept, deleted, elsewhere])
+
+    await syncCards(stores.cards, [kept], { parent: one.id })
+
+    const ids = (await stores.cards.list()).items.map(card => card.id).sort()
+    expect(ids).toEqual([one.id, two.id, kept.id, elsewhere.id].sort())
+  })
+
+  test('projects, cards and specifications share one store and one id space', async () => {
+    const suite = await makeSuite()
+    const stores = suite.client.planningStores!()
+    const project = await suite.project()
+    await (await suite.planning.model(project)).write('brief', '# Brief', { wait: true })
+    await suite.story(project.id!)
+
+    const [projects, specs, cards] = await Promise.all([
+      suite.planning.cards.list({ kind: WorkcardKind.Project }),
+      suite.planning.specifications.list(project.id!),
+      suite.planning.cards.list({ kind: WorkcardKind.Card, parent: project.id }),
+    ])
+    await syncCards(stores.cards, projects.items, { kind: WorkcardKind.Project })
+    await syncCards(stores.cards, specs.items, { kind: WorkcardKind.Specification, parent: project.id })
+    // A card list reloading with nothing in it must not take the project or its brief with it.
+    await syncCards(stores.cards, [], { kind: WorkcardKind.Card, parent: project.id })
+    await syncCards(stores.cards, cards.items, { kind: WorkcardKind.Card, parent: project.id })
+
+    const kinds = (await stores.cards.list()).items.map(card => card.kind).sort()
+    expect(kinds).toEqual([WorkcardKind.Card, WorkcardKind.Project, WorkcardKind.Specification])
+  })
+
+  test('a receipt marks the card pending (head > seq) and its commit clears the mark', async () => {
+    const suite = await makeSuite({ sync: false })
+    const stores = suite.client.planningStores!()
+    const project = await suite.project()
+    const story = await suite.story(project.id!)
+    await applyCards(stores, [story])
+
+    const receipt = await suite.planning.execute({
+      card: story.id!, action: TransitionAction.Transit, transition: 'start', expectSeq: story.seq,
+    })
+
+    const marked = await stores.cards.get(story.id!)
+    expect(isPending(marked)).toBe(true)
+    expect(modelOf(marked, suite.planning).pending()).toBe(true)
+
+    await suite.store.flush()
+    await receipt.committed({ timeout: 5_000 })
+
+    const folded = await stores.cards.get(story.id!)
+    expect(isPending(folded)).toBe(false)
+    expect(folded.status).toBe('doing')
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "types": [
+      "bun"
+    ],
+    "rootDir": "../",
+    "noEmit": true
+  },
+  "include": [
+    "./**/*",
+    "../src/**/*"
+  ]
+}