@owlmeans/client-planning 0.1.18-rc.0

package/src/facade.ts

@@ -0,0 +1,169 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import {
+  CommitFailed, CommitState, DEFAULT_COMMIT_TIMEOUT, PlanningError, PlanningUnsupported, WorkcardNotFound,
+  encodeRelationshipQuery, encodeSpecificationQuery, encodeSummaryQuery, encodeTransitionQuery,
+  encodeWorkcardQuery, modelOf,
+} from '@owlmeans/planning'
+import type {
+  PlanningFacade, PlanningProtocols, PlanningScope, TransitionReceipt,
+  TransitionReceiptView, Workcard, WorkcardModel,
+} from '@owlmeans/planning'
+import { applyReceipt } from './events.js'
+import type { RemoteFacadeOptions } from './types.js'
+
+/**
+ * A {@link PlanningFacade} over the remote protocol tree — every method is one entrypoint call.
+ *
+ * It is the same interface a server facade implements, so a model (`modelOf`) and everything
+ * built on the facade run unchanged in a browser or a Node client. Three things differ, and all
+ * three are the server's to decide:
+ *
+ * - the scope is advisory — the server takes the entity and the actor from the credential, and the
+ *   execution's own `actor` is never sent;
+ * - `execute({ wait: true })` never holds the POST: the receipt comes back at once and the commit is
+ *   awaited through `commits.wait` (subscribe, then long-poll), so a lost response cannot leave a
+ *   caller unsure whether the transition was appended;
+ * - `cards.count` is a one-row list read for its `total` — the tree declares no count route.
+ */
+export const makeRemoteFacade = <C extends BasicConfig, T extends BasicContext<C>>(
+  context: T, protocols: PlanningProtocols, scope: Partial<PlanningScope>, opts: RemoteFacadeOptions
+): PlanningFacade => {
+  const timeout = opts.timeout
+  const { commits } = opts
+
+  const receiptOf = (view: TransitionReceiptView): TransitionReceipt => {
+    const id = view.transition.id
+    if (id == null) {
+      throw new PlanningError('malformed:receipt-without-transition')
+    }
+
+    return {
+      transition: view.transition,
+      ...(view.card !== undefined ? { card: view.card } : {}),
+      committed: async waitOpts => {
+        const { state, error } = view.transition.commit
+        if (state === CommitState.Failed) {
+          throw new CommitFailed(error ?? id)
+        }
+        if (state === CommitState.Committed && view.card !== undefined) {
+          return view.card
+        }
+
+        return await commits.wait(id, { timeout: waitOpts?.timeout ?? DEFAULT_COMMIT_TIMEOUT })
+      },
+    }
+  }
+
+  const facade: PlanningFacade = {
+    scope: { ...scope, entityId: scope.entityId ?? '' },
+
+    schemas: opts.schemas,
+
+    cards: {
+      get: async id => await context.entrypoint(protocols.card.get).call({ params: { id }, timeout }),
+
+      load: async id => {
+        try {
+          return await facade.cards.get(id)
+        } catch (e) {
+          if (e instanceof WorkcardNotFound) {
+            return null
+          }
+          throw e
+        }
+      },
+
+      list: async query => await context.entrypoint(protocols.card.list).call({
+        query: encodeWorkcardQuery(query), timeout,
+      }),
+
+      count: async query => {
+        const { page: _page, size: _size, sort: _sort, ...where } = query ?? {}
+        const answer = await context.entrypoint(protocols.card.list).call({
+          query: encodeWorkcardQuery({ ...where, page: 0, size: 1 }), timeout,
+        })
+
+        return answer.total
+      },
+
+      summary: async (parents, query) => await context.entrypoint(protocols.card.summary).call({
+        query: encodeSummaryQuery({ ...query, parents }), timeout,
+      }),
+    },
+
+    specifications: {
+      current: async (parent, category) => {
+        const answer = await context.entrypoint(protocols.card.specifications).call({
+          params: { id: parent }, query: encodeSpecificationQuery({ category }), timeout,
+        })
+
+        return answer.items[0] ?? null
+      },
+
+      list: async (parent, query) => await context.entrypoint(protocols.card.specifications).call({
+        params: { id: parent }, query: encodeSpecificationQuery(query), timeout,
+      }),
+
+      get: async id => await context.entrypoint(protocols.spec.get).call({ params: { id }, timeout }),
+
+      revisions: async (id, limit) => {
+        const answer = await context.entrypoint(protocols.spec.revisions).call({
+          params: { id }, query: limit != null ? { limit } : {}, timeout,
+        })
+
+        return answer.items
+      },
+    },
+
+    relationships: {
+      list: async query => await context.entrypoint(protocols.link.list).call({
+        query: encodeRelationshipQuery(query), timeout,
+      }),
+    },
+
+    transitions: {
+      get: async id => await context.entrypoint(protocols.transition.get).call({
+        params: { transition: id }, timeout,
+      }),
+
+      list: async query => {
+        // The tree reads the log through ONE card; a project-wide read has no route to travel.
+        if (query.card == null) {
+          throw new PlanningUnsupported('client:transitions-without-card')
+        }
+
+        return await context.entrypoint(protocols.card.transitions).call({
+          params: { id: query.card }, query: encodeTransitionQuery(query), timeout,
+        })
+      },
+    },
+
+    commits,
+
+    execute: async (exec, executeOpts) => {
+      // Neither the actor nor a hold travels: the server decides who wrote, and the wait is ours.
+      const { actor: _actor, ...body } = exec
+      const view = await context.entrypoint(protocols.execute).call({ body, timeout })
+      const stores = opts.stores?.()
+      if (stores != null) {
+        await applyReceipt(stores, view)
+      }
+      const receipt = receiptOf(view)
+      if (executeOpts?.wait === true) {
+        receipt.card = await receipt.committed({ timeout: executeOpts.timeout })
+      }
+
+      return receipt
+    },
+
+    model: async <R extends Workcard = Workcard>(card: R | string): Promise<WorkcardModel<R>> => {
+      await opts.loadSchemas?.()
+      const record = typeof card === 'string' ? await facade.cards.get(card) as R : card
+
+      return modelOf<R>(record, facade)
+    },
+  }
+
+  return facade
+}
+

package/src/feed.ts

@@ -0,0 +1,131 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { criteriaOf, PLANNING_SERVICE } from '@owlmeans/planning'
+import type { Relationship, RelationshipQuery, Unsubscribe } from '@owlmeans/planning'
+import type { Criteria } from '@owlmeans/resource'
+import { applyCards, applyCommitEvent } from './events.js'
+import { planningStoresOf, syncCards, syncLinks } from './stores.js'
+import type { PlanningClientService, PlanningFeed, PlanningFeedOptions, PlanningFeedState } from './types.js'
+import { clean } from './utils/record.js'
+
+const linkCriteriaOf = (query: RelationshipQuery): Criteria<Relationship> =>
+  clean({ from: query.from, to: query.to, type: query.type }) as Criteria<Relationship>
+
+/**
+ * Keep the state mirror current: subscribe to commits FIRST, then seed from the list, then fold
+ * every frame — and, with `refresh`, re-seed on an interval as the authoritative backstop to a
+ * socket that can drop frames. React-free: a hook wraps it, a Node process uses it as it is.
+ *
+ * The seed is `syncCards` over `where` (default `criteriaOf(query)`), never `replace()`: the store
+ * holds every kind, and a board's list must not drop the projects beside it. A card a frame wrote
+ * while the list was in flight is kept even when the list does not name it yet. A PAGED seed only
+ * writes — a page cannot say what does not exist.
+ *
+ * Without a socket opener the feed is a seed plus its refresh; `commits.wait` still long-polls.
+ *
+ * @throws {SyntaxError} when the context has no planning client or no planning stores
+ */
+export const makePlanningFeed = <C extends BasicConfig, T extends BasicContext<C>>(
+  context: T, opts: PlanningFeedOptions = {}
+): PlanningFeed => {
+  const stores = planningStoresOf(context)
+  if (stores == null) {
+    throw new SyntaxError('Planning feed needs appendPlanningStores(context)')
+  }
+  const service = context.service<PlanningClientService>(PLANNING_SERVICE)
+  const facade = service.for(opts.scope)
+
+  const state: PlanningFeedState = { connected: false, seeded: false, error: null }
+  const report = (patch: Partial<PlanningFeedState>): void => {
+    const next = { ...state, ...patch }
+    if (next.connected === state.connected && next.seeded === state.seeded && next.error === state.error) {
+      return
+    }
+    Object.assign(state, next)
+    opts.onChange?.({ ...state })
+  }
+
+  const paged = opts.query?.size != null && opts.query.size > 0
+  const where = opts.where ?? criteriaOf(opts.query)
+  const touched = new Set<string>()
+  let seeding = 0
+  let stopped = false
+  let unsubscribe: Unsubscribe | null = null
+  let timer: ReturnType<typeof setInterval> | undefined
+
+  const seed = async (): Promise<void> => {
+    if (stopped) {
+      return
+    }
+    seeding += 1
+    try {
+      const answer = await facade.cards.list(paged ? opts.query : { ...opts.query, size: 0 })
+      if (stopped) {
+        return
+      }
+      if (paged) {
+        await applyCards(stores, answer.items)
+      } else {
+        await syncCards(stores.cards, answer.items, where, { keep: touched })
+      }
+      if (opts.links != null) {
+        const links = await facade.relationships.list({ ...opts.links, size: opts.links.size ?? 0 })
+        if (!stopped) {
+          await syncLinks(stores.links, links.items, linkCriteriaOf(opts.links))
+        }
+      }
+      report({ seeded: true, error: null })
+    } catch (e) {
+      if (!stopped) {
+        report({ error: e as Error })
+      }
+    } finally {
+      seeding -= 1
+      if (seeding === 0) {
+        touched.clear()
+      }
+    }
+  }
+
+  const ready = (async () => {
+    try {
+      const stop = await service.commits.subscribe(async event => {
+        if (seeding > 0) {
+          touched.add(event.card)
+        }
+        try {
+          await applyCommitEvent(stores, event, facade)
+        } catch (e) {
+          console.error('Planning feed apply error:', e)
+        }
+      }, opts.filter)
+      if (stopped) {
+        stop()
+        return
+      }
+      unsubscribe = stop
+      report({ connected: service.commits.connected() })
+    } catch (e) {
+      report({ error: e as Error })
+    }
+    await seed()
+    if (!stopped && opts.refresh != null && opts.refresh > 0) {
+      timer = setInterval(() => { void seed() }, opts.refresh)
+    }
+  })()
+
+  return {
+    get connected() { return state.connected },
+    get seeded() { return state.seeded },
+    get error() { return state.error },
+    ready,
+    refresh: seed,
+    stop: async () => {
+      stopped = true
+      if (timer != null) {
+        clearInterval(timer)
+      }
+      unsubscribe?.()
+      unsubscribe = null
+    },
+  }
+}

package/src/helper.ts

@@ -0,0 +1,18 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { PLANNING_SERVICE } from '@owlmeans/planning'
+import type { PlanningFacade, PlanningScope, Workcard, WorkcardModel } from '@owlmeans/planning'
+import type { PlanningClientService } from './types.js'
+
+/** The facade of the context's planning client — `context.planning().for(scope)` without the mixin type. */
+export const planningOf = <C extends BasicConfig, T extends BasicContext<C>>(
+  context: T, scope?: Partial<PlanningScope>
+): PlanningFacade => context.service<PlanningClientService>(PLANNING_SERVICE).for(scope)
+
+/**
+ * The model of a card (read by id when given one), with the schema bundle loaded first so `can()` and
+ * `available()` answer from real flows. Named apart from `@owlmeans/planning`'s `modelOf(record,
+ * facade)`, which it calls.
+ */
+export const planningModelOf = async <R extends Workcard = Workcard, C extends BasicConfig = BasicConfig, T extends BasicContext<C> = BasicContext<C>>(
+  context: T, card: R | string, scope?: Partial<PlanningScope>
+): Promise<WorkcardModel<R>> => await planningOf<C, T>(context, scope).model<R>(card)

package/src/index.ts

@@ -0,0 +1,10 @@
+export type * from './types.js'
+
+export * from './consts.js'
+export * from './client.js'
+export * from './facade.js'
+export * from './commits.js'
+export * from './stores.js'
+export * from './events.js'
+export * from './feed.js'
+export * from './helper.js'

package/src/stores.ts

@@ -0,0 +1,81 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import type { Relationship, Workcard } from '@owlmeans/planning'
+import type { Criteria } from '@owlmeans/resource'
+import { appendStateResource } from '@owlmeans/state'
+import type { StateResourceAppend } from '@owlmeans/state'
+import { DEFAULT_STORE_ALIASES } from './consts.js'
+import type { PlanningStoreAliases, PlanningStores, SyncOptions, WithPlanningStores } from './types.js'
+import { idsOf, putCard, putLink } from './utils/record.js'
+
+/**
+ * Register the planning state mirror: ONE card store for every kind, a link store and a commit
+ * store, and `context.planningStores()`.
+ *
+ * Projects, cards and specifications share one id space, so they share one store — a store per
+ * kind would let a card list that reloads drop the projects beside it, and would give a record two
+ * homes the moment its kind is read wrong. Idempotent, like every `append*`.
+ */
+export const appendPlanningStores = <C extends BasicConfig, T extends BasicContext<C>>(
+  context: T, aliases?: Partial<PlanningStoreAliases>
+): T & WithPlanningStores & StateResourceAppend => {
+  const names: PlanningStoreAliases = { ...DEFAULT_STORE_ALIASES, ...aliases }
+  let ctx = appendStateResource<C, T, Workcard>(context, names.cards)
+  ctx = appendStateResource<C, typeof ctx, Relationship>(ctx, names.links)
+  ctx = appendStateResource<C, typeof ctx>(ctx, names.commits)
+
+  const result = ctx as T & WithPlanningStores & StateResourceAppend
+  if (result.planningStores == null) {
+    result.planningStores = () => ({
+      cards: result.getStateResource(names.cards),
+      links: result.getStateResource(names.links),
+      commits: result.getStateResource(names.commits),
+    })
+  }
+
+  return result
+}
+
+/** The stores `appendPlanningStores` registered, or `null` on a context that has none. */
+export const planningStoresOf = (context: BasicContext<any>): PlanningStores | null => {
+  const ctx = context as Partial<WithPlanningStores>
+
+  return typeof ctx.planningStores === 'function' ? ctx.planningStores() : null
+}
+
+/**
+ * Make the store agree with an authoritative list WITHIN a scope: every card given is written
+ * (unless the store holds a newer fold of it), and every card matching `where` that the list does
+ * not name is dropped. Cards outside `where` are left alone — which is why this, and never
+ * `replace()`, is how a list reaches the one shared card store.
+ *
+ * Unchanged cards are not rewritten, so a periodic re-seed wakes no subscriber.
+ */
+export const syncCards = async (
+  store: PlanningStores['cards'], items: Workcard[], where?: Criteria<Workcard>, opts?: SyncOptions
+): Promise<void> => {
+  await dropUnnamed(store, idsOf(items), where, opts)
+  for (const item of items) {
+    await putCard(store, item)
+  }
+}
+
+/** {@link syncCards} for the link store. */
+export const syncLinks = async (
+  store: PlanningStores['links'], items: Relationship[], where?: Criteria<Relationship>, opts?: SyncOptions
+): Promise<void> => {
+  await dropUnnamed(store, idsOf(items), where, opts)
+  for (const item of items) {
+    await putLink(store, item)
+  }
+}
+
+const dropUnnamed = async <T extends Workcard | Relationship>(
+  store: PlanningStores['cards'] | PlanningStores['links'], named: string[], where?: Criteria<T>, opts?: SyncOptions
+): Promise<void> => {
+  const keep = new Set([...named, ...(opts?.keep ?? [])])
+  const scoped = await (store as PlanningStores['cards']).list(where as Criteria<Workcard>)
+  const stale = idsOf(scoped.items).filter(id => !keep.has(id))
+  if (stale.length > 0) {
+    await store.purge({ id: { $in: stale } })
+  }
+}

package/src/types.ts

@@ -0,0 +1,163 @@
+import type { ClientConfig, ClientContext } from '@owlmeans/client-context'
+import type { LazyService } from '@owlmeans/context'
+import type { AbstractRequest, EntrypointProtocolDeclaration } from '@owlmeans/entrypoint'
+import type {
+  CommitFilter, CommitSource, CommitState, PlanningFacade, PlanningProtocols, PlanningSchemaRegistry,
+  PlanningScope, PlanningService, Relationship, RelationshipQuery, TransitionAction, Workcard,
+  WorkcardKind, WorkcardQuery,
+} from '@owlmeans/planning'
+import type { Criteria, ResourceRecord } from '@owlmeans/resource'
+import type { Connection } from '@owlmeans/socket'
+import type { StateAlias, StateResource } from '@owlmeans/state'
+
+export interface Config extends ClientConfig { }
+
+export interface Context<C extends Config = Config> extends ClientContext<C> { }
+
+/**
+ * Opens the commit socket. Injected, because the way a socket is opened is the host's: a browser
+ * wraps `@owlmeans/client-socket` (which puts the session token on the connection), a Node client
+ * usually has no socket at all. Answering `null` means "no socket" — the client then long-polls.
+ */
+export interface PlanningSocketOpener {
+  (protocol: EntrypointProtocolDeclaration, request?: Partial<AbstractRequest>): Promise<Connection | null>
+}
+
+export interface PlanningClientOptions {
+  /** The tree the server mounted — the same `makePlanningProtocols` call, alias for alias. */
+  protocols: PlanningProtocols
+  /**
+   * The default facade's scope. Advisory on a client: the server derives the entity and the actor
+   * from the credential, never from anything this sends.
+   */
+  scope?: Partial<PlanningScope>
+  /** How the commit socket is opened. Without it `commits.wait` long-polls only. */
+  socket?: PlanningSocketOpener
+  /**
+   * Load the schema bundle in the background once the context is ready (default `true`). The load
+   * never fails or blocks the context; whatever needs the schemas (`model()`, `loadSchemas()`)
+   * loads them on first use either way.
+   */
+  schemas?: boolean
+  /** The longest single long poll, in seconds (default `DEFAULT_COMMIT_POLL`). */
+  poll?: number
+  /** Bind the protocol tree as client entrypoints (default `true`). */
+  bind?: boolean
+  /** The HTTP deadline of every call that is not a long poll, in milliseconds. */
+  timeout?: number
+}
+
+/** What `appendPlanningClient` registers under `PLANNING_SERVICE`. */
+export interface PlanningClientService extends PlanningService, LazyService {
+  /** A facade over the remote tree. The scope is advisory (see {@link PlanningClientOptions.scope}). */
+  for: (scope?: Partial<PlanningScope>) => PlanningFacade
+  commits: RemoteCommitSource
+  /** The registry, loaded from the server's bundle — once, unless `force`d. */
+  loadSchemas: (opts?: { force?: boolean }) => Promise<PlanningSchemaRegistry>
+  /** Release the shared commit socket. */
+  close: () => Promise<void>
+}
+
+export interface WithPlanningClient {
+  planning: () => PlanningClientService
+}
+
+export interface RemoteCommitSource extends CommitSource {
+  /** A socket is open under this source. */
+  connected: () => boolean
+  /** Release the shared socket. Subscriptions stop receiving until the next `subscribe`. */
+  close: () => Promise<void>
+}
+
+export interface RemoteCommitSourceOptions {
+  socket?: PlanningSocketOpener
+  /** Seconds. */
+  poll?: number
+  /** Milliseconds, for the non-holding status read. */
+  timeout?: number
+  /** The state mirror a settled commit is folded into, when one is registered. */
+  stores?: () => PlanningStores | null
+}
+
+export interface RemoteFacadeOptions {
+  commits: RemoteCommitSource
+  schemas: PlanningSchemaRegistry
+  /** Resolves the registry before a model is built. */
+  loadSchemas?: () => Promise<PlanningSchemaRegistry>
+  timeout?: number
+  stores?: () => PlanningStores | null
+}
+
+/** One row per transition the client wrote or saw settle. */
+export interface PlanningCommitRecord extends ResourceRecord {
+  /** The transition id. */
+  id: string
+  card?: string
+  entityId?: string
+  project?: string
+  kind?: WorkcardKind
+  type?: string
+  seq?: number
+  action?: TransitionAction
+  state: CommitState
+  at?: string
+  error?: string
+}
+
+export interface PlanningStoreAliases {
+  cards: StateAlias<Workcard>
+  links: StateAlias<Relationship>
+  commits: StateAlias<PlanningCommitRecord>
+}
+
+export interface PlanningStores {
+  cards: StateResource<Workcard>
+  links: StateResource<Relationship>
+  commits: StateResource<PlanningCommitRecord>
+}
+
+export interface WithPlanningStores {
+  planningStores: () => PlanningStores
+}
+
+export interface SyncOptions {
+  /** Ids never dropped by this sync — records written by a commit while the list was in flight. */
+  keep?: Iterable<string>
+}
+
+export interface PlanningFeedOptions {
+  /** What the seeding list asks for. Unpaged unless the query pages. */
+  query?: WorkcardQuery
+  /**
+   * The part of the store the seed is authoritative for: rows matching it that the answer does not
+   * name are dropped. `criteriaOf(query)` when omitted; a PAGED seed never drops anything.
+   */
+  where?: Criteria<Workcard>
+  /** Also seed the link store from this query. */
+  links?: RelationshipQuery
+  /** Which commit frames fold into the store. Every frame the server sends when omitted. */
+  filter?: CommitFilter
+  /** Re-seed on this interval, in milliseconds — the authoritative poll beside the socket. */
+  refresh?: number
+  scope?: Partial<PlanningScope>
+  /** Called on every change of {@link PlanningFeedState}. */
+  onChange?: (state: PlanningFeedState) => void
+}
+
+export interface PlanningFeedState {
+  /** The commit socket is open. */
+  connected: boolean
+  /** The authoritative list has been written into the store at least once. */
+  seeded: boolean
+  /** What the last seeding call threw, if it threw. */
+  error: Error | null
+}
+
+export interface PlanningFeed extends Readonly<PlanningFeedState> {
+  /** Settles after the first seed attempt (it never rejects — read `error`). */
+  ready: Promise<void>
+  /** Seed again now. */
+  refresh: () => Promise<void>
+  /** Stop folding frames and refreshing. The shared socket stays open. */
+  stop: () => Promise<void>
+}

package/src/utils/record.ts

@@ -0,0 +1,91 @@
+import type { PlanningCommitRecord, PlanningStores } from '../types.js'
+import type { CommitState, Relationship, Workcard } from '@owlmeans/planning'
+import type { ResourceRecord } from '@owlmeans/resource'
+import type { StateResource } from '@owlmeans/state'
+
+const stable = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(stable)
+  }
+  if (value != null && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value as Record<string, unknown>)
+      .filter(([, entry]) => entry !== undefined)
+      .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+      .map(([key, entry]) => [key, stable(entry)]))
+  }
+
+  return value
+}
+
+/** Same content, whatever order the keys arrived in. */
+export const sameRecord = (left: unknown, right: unknown): boolean =>
+  JSON.stringify(stable(left)) === JSON.stringify(stable(right))
+
+/**
+ * Write one card unless the store already holds a NEWER fold of it.
+ *
+ * `seq` is the last folded transition, so a lower one is an older picture — a list fetched before a
+ * commit landed must not undo that commit. The head only ever grows: a head this client allocated
+ * (`applyReceipt`) stays until a fold catches up with it.
+ */
+export const putCard = async (store: StateResource<Workcard>, card: Workcard): Promise<Workcard> => {
+  if (card.id == null) {
+    return card
+  }
+  const known = await store.load(card.id)
+  if (known != null && (known.seq ?? 0) > (card.seq ?? 0)) {
+    return known
+  }
+  const head = Math.max(card.head ?? card.seq ?? 0, known?.head ?? 0)
+  const next = head > (card.head ?? card.seq ?? 0) ? { ...card, head } : card
+  if (known != null && sameRecord(known, next)) {
+    return known
+  }
+  await store.save(next)
+
+  return next
+}
+
+export const putLink = async (store: StateResource<Relationship>, link: Relationship): Promise<void> => {
+  if (link.id == null) {
+    return
+  }
+  const known = await store.load(link.id)
+  if (known != null && sameRecord(known, link)) {
+    return
+  }
+  await store.save(link)
+}
+
+/** Drop a card, whatever lives under it when it is a project, and every link touching any of them. */
+export const dropCard = async (stores: PlanningStores, id: string, project: boolean): Promise<void> => {
+  const ids = [id]
+  if (project) {
+    const children = await stores.cards.list({ parents: { $contains: [id] } })
+    ids.push(...children.items.map(child => child.id).filter((child): child is string => child != null))
+  }
+  await stores.cards.purge({ id: { $in: ids } })
+  if (await stores.links.count({ $or: [{ from: { $in: ids } }, { to: { $in: ids } }] }) > 0) {
+    await stores.links.purge({ $or: [{ from: { $in: ids } }, { to: { $in: ids } }] })
+  }
+}
+
+/** Record what is known about a transition, merged over what was known before. */
+export const putCommit = async (
+  store: StateResource<PlanningCommitRecord>, record: Partial<PlanningCommitRecord> & { id: string, state: CommitState }
+): Promise<PlanningCommitRecord> => {
+  const known = await store.load(record.id)
+  const next = { ...known, ...clean(record) } as PlanningCommitRecord
+  if (known != null && sameRecord(known, next)) {
+    return known
+  }
+  await store.save(next)
+
+  return next
+}
+
+export const clean = <T extends object>(record: T): T =>
+  Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)) as T
+
+export const idsOf = <T extends ResourceRecord>(records: T[]): string[] =>
+  records.map(record => record.id).filter((id): id is string => id != null)