@owlmeans/client-planning 0.1.18-rc.21 → 0.1.18-rc.22

package/src/events.ts

@@ -1,120 +1,122 @@
+import { memoHelper } from '@owlmeans/context'
 import { CommitState, TransitionAction, WorkcardKind, type CommitEvent, type PlanningFacade, type TransitionReceiptView, type Workcard } from '@owlmeans/planning'
-import { syncLinks } from './stores.js'
+import type { PlanningMirror } from './events/types.js'
+import { syncHelper } from './sync.js'
 import type { PlanningStores } from './types.js'
-import { recordHelper } from './utils/record.js'
+import { recordUtils } from './utils/record.js'
 
-/**
- * Fold one commit frame into the mirror.
- *
- * - An OLDER `seq` never overwrites a newer record — frames and list answers race.
- * - A committed `delete` REMOVES the row and every link touching it (and, for a project, the rows
- *   under it — the server purged them in the same fold).
- * - A frame for an id the store never saw still writes a row: a card created in another tab
- *   appears here without waiting for the next list.
- * - A `failed` commit leaves the card alone; the reason is recorded in the commit store.
- *
- * A frame from a cross-process bus carries ids only. When `record` is absent the card is re-read
- * through `facade`; without one there is nothing to write but the commit itself.
- */
-export const applyCommitEvent = async (
-  stores: PlanningStores, event: CommitEvent, facade?: PlanningFacade
-): Promise<void> => {
-  const known = await stores.cards.load(event.card)
+export const makePlanningMirror = (stores: PlanningStores): PlanningMirror => {
+  const applyCommitEvent = async (event: CommitEvent, facade?: PlanningFacade): Promise<void> => {
+    const known = await stores.cards.load(event.card)
 
-  await recordHelper.putCommit(stores.commits, {
-    id: event.transition,
-    card: event.card,
-    entityId: event.entityId,
-    project: event.project,
-    kind: event.kind,
-    type: event.type,
-    seq: event.seq,
-    action: event.action,
-    state: event.state,
-    at: event.at,
-    error: event.error,
-  })
+    await recordUtils.putCommit(stores.commits, {
+      id: event.transition,
+      card: event.card,
+      entityId: event.entityId,
+      project: event.project,
+      kind: event.kind,
+      type: event.type,
+      seq: event.seq,
+      action: event.action,
+      state: event.state,
+      at: event.at,
+      error: event.error,
+    })
 
-  if (event.state === CommitState.Failed) {
-    return
-  }
-  if (event.state === CommitState.Pending) {
-    if (known != null && (known.head ?? known.seq) < event.seq) {
-      await stores.cards.save({ ...known, head: event.seq })
+    if (event.state === CommitState.Failed) {
+      return
+    }
+    if (event.state === CommitState.Pending) {
+      if (known != null && (known.head ?? known.seq) < event.seq) {
+        await stores.cards.save({ ...known, head: event.seq })
+      }
+      return
+    }
+    if (known != null && known.seq > event.seq) {
+      return
     }
-    return
-  }
-  if (known != null && known.seq > event.seq) {
-    return
-  }
 
-  if (event.action === TransitionAction.Delete) {
-    await recordHelper.dropCard(stores, event.card, event.kind === WorkcardKind.Project)
-    return
-  }
+    if (event.action === TransitionAction.Delete) {
+      await recordUtils.dropCard(stores, event.card, event.kind === WorkcardKind.Project)
+      return
+    }
 
-  const record: Workcard | null | undefined = event.record !== undefined
-    ? event.record
-    : facade != null ? await facade.cards.load(event.card) : undefined
+    const record: Workcard | null | undefined = event.record !== undefined
+      ? event.record
+      : facade != null ? await facade.cards.load(event.card) : undefined
 
-  if (record === null) {
-    // Committed, and gone by the time it was read: a later delete won the race.
-    await recordHelper.dropCard(stores, event.card, event.kind === WorkcardKind.Project)
-  } else if (record !== undefined) {
-    await recordHelper.putCard(stores.cards, record)
-  }
+    if (record === null) {
+      // Committed, and gone by the time it was read: a later delete won the race.
+      await recordUtils.dropCard(stores, event.card, event.kind === WorkcardKind.Project)
+    } else if (record !== undefined) {
+      await recordUtils.putCard(stores.cards, record)
+    }
 
-  if (facade != null && (event.action === TransitionAction.Link || event.action === TransitionAction.Unlink)) {
-    const links = await facade.relationships.list({ from: event.card, size: 0 })
-    await syncLinks(stores.links, links.items, { from: event.card })
+    if (facade != null && (event.action === TransitionAction.Link || event.action === TransitionAction.Unlink)) {
+      const links = await facade.relationships.list({ from: event.card, size: 0 })
+      await syncHelper.syncLinks(stores.links, links.items, { from: event.card })
+    }
   }
-}
 
-/**
- * Mark a receipt in the mirror the moment the server answers it.
- *
- * A pending transition raises the card's `head` to its `seq`, so `head > seq` — the model's
- * `pending()` — is true before any frame arrives. A receipt that already carries the committed
- * card writes it; a committed delete drops the row.
- */
-export const applyReceipt = async (stores: PlanningStores, receipt: TransitionReceiptView): Promise<void> => {
-  const { transition } = receipt
-  if (transition.id != null) {
-    await recordHelper.putCommit(stores.commits, {
-      id: transition.id,
-      card: transition.card,
-      entityId: transition.entityId,
-      project: transition.project,
-      kind: transition.kind,
-      type: transition.type,
-      seq: transition.seq,
-      action: transition.action,
-      state: transition.commit.state,
-      at: transition.commit.at,
-      error: transition.commit.error,
-    })
-  }
-  if (transition.commit.state === CommitState.Failed) {
-    return
-  }
-  if (transition.commit.state === CommitState.Committed && transition.action === TransitionAction.Delete) {
-    await recordHelper.dropCard(stores, transition.card, transition.kind === WorkcardKind.Project)
-    return
-  }
-  if (receipt.card != null) {
-    await recordHelper.putCard(stores.cards, receipt.card)
-    return
-  }
+  const applyReceipt = async (receipt: TransitionReceiptView): Promise<void> => {
+    const { transition } = receipt
+    if (transition.id != null) {
+      await recordUtils.putCommit(stores.commits, {
+        id: transition.id,
+        card: transition.card,
+        entityId: transition.entityId,
+        project: transition.project,
+        kind: transition.kind,
+        type: transition.type,
+        seq: transition.seq,
+        action: transition.action,
+        state: transition.commit.state,
+        at: transition.commit.at,
+        error: transition.commit.error,
+      })
+    }
+    if (transition.commit.state === CommitState.Failed) {
+      return
+    }
+    if (transition.commit.state === CommitState.Committed && transition.action === TransitionAction.Delete) {
+      await recordUtils.dropCard(stores, transition.card, transition.kind === WorkcardKind.Project)
+      return
+    }
+    if (receipt.card != null) {
+      await recordUtils.putCard(stores.cards, receipt.card)
+      return
+    }
 
-  const known = await stores.cards.load(transition.card)
-  if (known != null && (known.head ?? known.seq) < transition.seq) {
-    await stores.cards.save({ ...known, head: transition.seq })
+    const known = await stores.cards.load(transition.card)
+    if (known != null && (known.head ?? known.seq) < transition.seq) {
+      await stores.cards.save({ ...known, head: transition.seq })
+    }
   }
-}
 
-/** Write cards the caller read on its own, under the same newer-fold-wins rule as a commit. */
-export const applyCards = async (stores: Pick<PlanningStores, 'cards'>, cards: Workcard[]): Promise<void> => {
-  for (const card of cards) {
-    await recordHelper.putCard(stores.cards, card)
+  const applyCards = async (cards: Workcard[]): Promise<void> => {
+    for (const card of cards) {
+      await recordUtils.putCard(stores.cards, card)
+    }
   }
+
+  return { applyCommitEvent, applyReceipt, applyCards }
 }
+
+/** The mirror of one set of stores — one per stores object. */
+export const planningMirrorOf = memoHelper.oncePer(makePlanningMirror)
+
+/** @deprecated compat:factory-refactor — use `planningMirrorOf(stores).applyCommitEvent(…)` */
+export const applyCommitEvent = async (
+  stores: PlanningStores, event: CommitEvent, facade?: PlanningFacade
+): Promise<void> => await planningMirrorOf(stores).applyCommitEvent(event, facade)
+
+/** @deprecated compat:factory-refactor — use `planningMirrorOf(stores).applyReceipt(…)` */
+export const applyReceipt = async (stores: PlanningStores, receipt: TransitionReceiptView): Promise<void> =>
+  await planningMirrorOf(stores).applyReceipt(receipt)
+
+/**
+ * @deprecated compat:factory-refactor — use `planningMirrorOf(stores).applyCards(…)`. Only `cards` is
+ * read, so a narrower stores object still works here.
+ */
+export const applyCards = async (stores: Pick<PlanningStores, 'cards'>, cards: Workcard[]): Promise<void> =>
+  await planningMirrorOf(stores as PlanningStores).applyCards(cards)

package/src/facade.ts

@@ -1,14 +1,13 @@
 import type { BasicConfig, BasicContext } from '@owlmeans/context'
 import {
-  CommitFailed, CommitState, DEFAULT_COMMIT_TIMEOUT, PlanningError, PlanningUnsupported, WorkcardKind, WorkcardNotFound,
-  encodeRelationshipQuery, encodeSpecificationQuery, encodeSummaryQuery, encodeTransitionQuery,
-  encodeWorkcardQuery, modelOf,
+  CommitFailed, CommitState, DEFAULT_COMMIT_TIMEOUT, modelOf, PlanningError, PlanningUnsupported, wireHelper,
+  WorkcardKind, WorkcardNotFound,
 } from '@owlmeans/planning'
 import type {
   PlanningFacade, PlanningProtocols, PlanningScope, TransitionReceipt,
   TransitionReceiptView, Workcard, WorkcardModel,
 } from '@owlmeans/planning'
-import { applyReceipt } from './events.js'
+import { planningMirrorOf } from './events.js'
 import type { RemoteFacadeOptions } from './types.js'
 
 /**
@@ -74,34 +73,34 @@ export const makeRemoteFacade = <C extends BasicConfig, T extends BasicContext<C
       },
 
       list: async query => await context.entrypoint(protocols.card.list).call({
-        query: encodeWorkcardQuery(query), timeout,
+        query: wireHelper.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,
+          query: wireHelper.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,
+        query: wireHelper.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,
+          params: { id: parent }, query: wireHelper.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,
+        params: { id: parent }, query: wireHelper.encodeSpecificationQuery(query), timeout,
       }),
 
       get: async id => await context.entrypoint(protocols.spec.get).call({ params: { id }, timeout }),
@@ -117,7 +116,7 @@ export const makeRemoteFacade = <C extends BasicConfig, T extends BasicContext<C
 
     relationships: {
       list: async query => await context.entrypoint(protocols.link.list).call({
-        query: encodeRelationshipQuery(query), timeout,
+        query: wireHelper.encodeRelationshipQuery(query), timeout,
       }),
     },
 
@@ -133,7 +132,7 @@ export const makeRemoteFacade = <C extends BasicConfig, T extends BasicContext<C
         }
 
         return await context.entrypoint(protocols.card.transitions).call({
-          params: { id: query.card }, query: encodeTransitionQuery(query), timeout,
+          params: { id: query.card }, query: wireHelper.encodeTransitionQuery(query), timeout,
         })
       },
     },
@@ -146,7 +145,7 @@ export const makeRemoteFacade = <C extends BasicConfig, T extends BasicContext<C
       const view = await context.entrypoint(protocols.execute).call({ body, timeout })
       const stores = opts.stores?.()
       if (stores != null) {
-        await applyReceipt(stores, view)
+        await planningMirrorOf(stores).applyReceipt(view)
       }
       const receipt = receiptOf(view)
       if (executeOpts?.wait === true) {

package/src/feed.ts

@@ -1,26 +1,27 @@
 import type { BasicConfig, BasicContext } from '@owlmeans/context'
 import { logger } from '@owlmeans/log'
-import { criteriaOf, PLANNING_SERVICE, type Relationship, type RelationshipQuery, type Unsubscribe } from '@owlmeans/planning'
+import { PLANNING_SERVICE, queryHelper, type Relationship, type RelationshipQuery, type Unsubscribe } from '@owlmeans/planning'
 import type { Criteria } from '@owlmeans/resource'
-import { applyCards, applyCommitEvent } from './events.js'
-import { planningStoresOf, syncCards, syncLinks } from './stores.js'
+import { planningMirrorOf } from './events.js'
+import { planningContextOf } from './helper.js'
+import { syncHelper } from './sync.js'
 import type { PlanningClientService, PlanningFeed, PlanningFeedOptions, PlanningFeedState } from './types.js'
-import { recordHelper } from './utils/record.js'
+import { recordUtils } from './utils/record.js'
 
 const log = logger('client-planning')
 
 const linkCriteriaOf = (query: RelationshipQuery): Criteria<Relationship> =>
-  recordHelper.clean({ from: query.from, to: query.to, type: query.type }) as Criteria<Relationship>
+  recordUtils.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.
+ * The seed is `syncHelper.syncCards` over `where` (default `queryHelper.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.
  *
@@ -29,12 +30,13 @@ const linkCriteriaOf = (query: RelationshipQuery): Criteria<Relationship> =>
 export const makePlanningFeed = <C extends BasicConfig, T extends BasicContext<C>>(
   context: T, opts: PlanningFeedOptions = {}
 ): PlanningFeed => {
-  const stores = planningStoresOf(context)
+  const stores = planningContextOf(context).stores()
   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 mirror = planningMirrorOf(stores)
 
   const state: PlanningFeedState = { connected: false, seeded: false, error: null }
   const report = (patch: Partial<PlanningFeedState>): void => {
@@ -47,7 +49,7 @@ export const makePlanningFeed = <C extends BasicConfig, T extends BasicContext<C
   }
 
   const paged = opts.query?.size != null && opts.query.size > 0
-  const where = opts.where ?? criteriaOf(opts.query)
+  const where = opts.where ?? queryHelper.criteriaOf(opts.query)
   const touched = new Set<string>()
   let seeding = 0
   let stopped = false
@@ -65,14 +67,14 @@ export const makePlanningFeed = <C extends BasicConfig, T extends BasicContext<C
         return
       }
       if (paged) {
-        await applyCards(stores, answer.items)
+        await mirror.applyCards(answer.items)
       } else {
-        await syncCards(stores.cards, answer.items, where, { keep: touched })
+        await syncHelper.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))
+          await syncHelper.syncLinks(stores.links, links.items, linkCriteriaOf(opts.links))
         }
       }
       report({ seeded: true, error: null })
@@ -95,7 +97,7 @@ export const makePlanningFeed = <C extends BasicConfig, T extends BasicContext<C
           touched.add(event.card)
         }
         try {
-          await applyCommitEvent(stores, event, facade)
+          await mirror.applyCommitEvent(event, facade)
         } catch (e) {
           log.warn('Planning feed apply failed', { card: event.card, error: e })
         }

package/src/helper/types.ts

@@ -0,0 +1,15 @@
+import type { PlanningFacade, PlanningScope, Workcard, WorkcardModel } from '@owlmeans/planning'
+import type { PlanningStores } from '../types.js'
+
+/** The planning client of one context, without the `WithPlanningClient` mixin type. */
+export interface PlanningContextHelper {
+  /** The facade of the context's planning client — `context.planning().for(scope)`. */
+  facade: (scope?: Partial<PlanningScope>) => PlanningFacade
+  /**
+   * 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. Built by `@owlmeans/planning`'s `modelOf(record, facade)`.
+   */
+  model: <R extends Workcard = Workcard>(card: R | string, scope?: Partial<PlanningScope>) => Promise<WorkcardModel<R>>
+  /** The stores `appendPlanningStores` registered, or `null` on a context that has none. */
+  stores: () => PlanningStores | null
+}

package/src/helper.ts

@@ -1,18 +1,35 @@
-import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { memoHelper, type BasicConfig, type 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'
+import type { PlanningContextHelper } from './helper/types.js'
+import type { PlanningClientService, PlanningStores, WithPlanningStores } from './types.js'
 
-/** The facade of the context's planning client — `context.planning().for(scope)` without the mixin type. */
+export const makePlanningContextHelper = (context: BasicContext<BasicConfig>): PlanningContextHelper => {
+  const facade = (scope?: Partial<PlanningScope>): PlanningFacade =>
+    context.service<PlanningClientService>(PLANNING_SERVICE).for(scope)
+
+  const model = async <R extends Workcard = Workcard>(
+    card: R | string, scope?: Partial<PlanningScope>
+  ): Promise<WorkcardModel<R>> => await facade(scope).model<R>(card)
+
+  const stores = (): PlanningStores | null => {
+    const ctx = context as Partial<WithPlanningStores>
+
+    return typeof ctx.planningStores === 'function' ? ctx.planningStores() : null
+  }
+
+  return { facade, model, stores }
+}
+
+/** The planning helper of a context — one per context. */
+export const planningContextOf = memoHelper.oncePer(makePlanningContextHelper)
+
+/** @deprecated compat:factory-refactor — use `planningContextOf(context).facade(…)` */
 export const planningOf = <C extends BasicConfig, T extends BasicContext<C>>(
   context: T, scope?: Partial<PlanningScope>
-): PlanningFacade => context.service<PlanningClientService>(PLANNING_SERVICE).for(scope)
+): PlanningFacade => planningContextOf(context).facade(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.
- */
+/** @deprecated compat:factory-refactor — use `planningContextOf(context).model(…)` */
 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)
+): Promise<WorkcardModel<R>> => await planningContextOf(context).model<R>(card, scope)

package/src/index.ts

@@ -1,12 +1,15 @@
 export type * from './types.js'
+export type * from './events/types.js'
+export type * from './helper/types.js'
+export type * from './sync/types.js'
 
 export * from './consts.js'
-export * from './utils.js'
 export * from './client.js'
 export * from './facade.js'
 export * from './definitions.js'
 export * from './commits.js'
 export * from './stores.js'
+export * from './sync.js'
 export * from './events.js'
 export * from './feed.js'
 export * from './helper.js'

package/src/stores.ts

@@ -2,9 +2,10 @@ import type { BasicConfig, BasicContext } from '@owlmeans/context'
 import type { Relationship, Workcard } from '@owlmeans/planning'
 import type { Criteria } from '@owlmeans/resource'
 import { appendStateResource, type StateResourceAppend } from '@owlmeans/state'
-import { DEFAULT_STORE_ALIASES } from './utils.js'
+import { DEFAULT_STORE_ALIASES } from './consts.js'
+import { planningContextOf } from './helper.js'
+import { syncHelper } from './sync.js'
 import type { PlanningStoreAliases, PlanningStores, SyncOptions, WithPlanningStores } from './types.js'
-import { recordHelper } from './utils/record.js'
 
 /**
  * Register the planning state mirror: ONE card store for every kind, a link store and a commit
@@ -34,47 +35,16 @@ export const appendPlanningStores = <C extends BasicConfig, T extends BasicConte
   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
-}
+/** @deprecated compat:factory-refactor — use `planningContextOf(context).stores()` */
+export const planningStoresOf = (context: BasicContext<any>): PlanningStores | null => planningContextOf(context).stores()
 
-/**
- * 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.
- */
+/** @deprecated compat:factory-refactor — use `syncHelper.syncCards(…)` */
 export const syncCards = async (
   store: PlanningStores['cards'], items: Workcard[], where?: Criteria<Workcard>, opts?: SyncOptions
-): Promise<void> => {
-  await dropUnnamed(store, recordHelper.idsOf(items), where, opts)
-  for (const item of items) {
-    await recordHelper.putCard(store, item)
-  }
-}
+): Promise<void> => await syncHelper.syncCards(store, items, where, opts)
 
-/** {@link syncCards} for the link store. */
+/** @deprecated compat:factory-refactor — use `syncHelper.syncLinks(…)` */
 export const syncLinks = async (
   store: PlanningStores['links'], items: Relationship[], where?: Criteria<Relationship>, opts?: SyncOptions
-): Promise<void> => {
-  await dropUnnamed(store, recordHelper.idsOf(items), where, opts)
-  for (const item of items) {
-    await recordHelper.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 = recordHelper.idsOf(scoped.items).filter(id => !keep.has(id))
-  if (stale.length > 0) {
-    await store.purge({ id: { $in: stale } })
-  }
-}
+): Promise<void> => await syncHelper.syncLinks(store, items, where, opts)

package/src/sync/types.ts

@@ -0,0 +1,18 @@
+import type { Relationship, Workcard } from '@owlmeans/planning'
+import type { Criteria } from '@owlmeans/resource'
+import type { PlanningStores, SyncOptions } from '../types.js'
+
+/** An authoritative list made true in one mirror store — within a scope, never beyond it. */
+export interface SyncHelper {
+  /**
+   * 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.
+   */
+  syncCards: (store: PlanningStores['cards'], items: Workcard[], where?: Criteria<Workcard>, opts?: SyncOptions) => Promise<void>
+  /** {@link SyncHelper.syncCards} for the link store. */
+  syncLinks: (store: PlanningStores['links'], items: Relationship[], where?: Criteria<Relationship>, opts?: SyncOptions) => Promise<void>
+}

package/src/sync.ts

@@ -0,0 +1,40 @@
+import type { Relationship, Workcard } from '@owlmeans/planning'
+import type { Criteria } from '@owlmeans/resource'
+import type { SyncHelper } from './sync/types.js'
+import type { PlanningStores, SyncOptions } from './types.js'
+import { recordUtils } from './utils/record.js'
+
+export const createSyncHelper = (): SyncHelper => {
+  const syncCards = async (
+    store: PlanningStores['cards'], items: Workcard[], where?: Criteria<Workcard>, opts?: SyncOptions
+  ): Promise<void> => {
+    await dropUnnamed(store, recordUtils.idsOf(items), where, opts)
+    for (const item of items) {
+      await recordUtils.putCard(store, item)
+    }
+  }
+
+  const syncLinks = async (
+    store: PlanningStores['links'], items: Relationship[], where?: Criteria<Relationship>, opts?: SyncOptions
+  ): Promise<void> => {
+    await dropUnnamed(store, recordUtils.idsOf(items), where, opts)
+    for (const item of items) {
+      await recordUtils.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 = recordUtils.idsOf(scoped.items).filter(id => !keep.has(id))
+    if (stale.length > 0) {
+      await store.purge({ id: { $in: stale } })
+    }
+  }
+
+  return { syncCards, syncLinks }
+}
+
+export const syncHelper = createSyncHelper()

package/src/utils/record/types.ts

@@ -0,0 +1,27 @@
+import type { CommitState, Relationship, Workcard } from '@owlmeans/planning'
+import type { ResourceRecord } from '@owlmeans/resource'
+import type { StateResource } from '@owlmeans/state'
+import type { PlanningCommitRecord, PlanningStores } from '../../types.js'
+
+/** How a record is written into the state mirror: only when it is newer, and only when it changed. */
+export interface RecordUtils {
+  /** Same content, whatever order the keys arrived in. */
+  sameRecord: (left: unknown, right: unknown) => boolean
+  /**
+   * 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.
+   */
+  putCard: (store: StateResource<Workcard>, card: Workcard) => Promise<Workcard>
+  putLink: (store: StateResource<Relationship>, link: Relationship) => Promise<void>
+  /** Drop a card, whatever lives under it when it is a project, and every link touching any of them. */
+  dropCard: (stores: PlanningStores, id: string, project: boolean) => Promise<void>
+  /** Record what is known about a transition, merged over what was known before. */
+  putCommit: (
+    store: StateResource<PlanningCommitRecord>, record: Partial<PlanningCommitRecord> & { id: string, state: CommitState }
+  ) => Promise<PlanningCommitRecord>
+  clean: <T extends object>(record: T) => T
+  idsOf: <T extends ResourceRecord>(records: T[]) => string[]
+}