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

package/src/feed.ts

@@ -1,24 +1,27 @@
 import type { BasicConfig, BasicContext } from '@owlmeans/context'
-import { criteriaOf, PLANNING_SERVICE } from '@owlmeans/planning'
-import type { Relationship, RelationshipQuery, Unsubscribe } from '@owlmeans/planning'
+import { logger } from '@owlmeans/log'
+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 { clean } from './utils/record.js'
+import { recordUtils } from './utils/record.js'
+
+const log = logger('client-planning')
 
 const linkCriteriaOf = (query: RelationshipQuery): Criteria<Relationship> =>
-  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.
  *
@@ -27,15 +30,19 @@ 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 { lifecycle } = service
+  const operation = lifecycle.capture()
   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 => {
+    if (!active()) return
     const next = { ...state, ...patch }
     if (next.connected === state.connected && next.seeded === state.seeded && next.error === state.error) {
       return
@@ -45,37 +52,39 @@ 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
+  const active = () => !stopped && operation.active()
   let unsubscribe: Unsubscribe | null = null
   let timer: ReturnType<typeof setInterval> | undefined
 
   const seed = async (): Promise<void> => {
-    if (stopped) {
+    if (!active()) {
       return
     }
     seeding += 1
     try {
-      const answer = await facade.cards.list(paged ? opts.query : { ...opts.query, size: 0 })
-      if (stopped) {
+      const answer = await operation.wait(facade.cards.list(paged ? opts.query : { ...opts.query, size: 0 }))
+      if (!active()) {
         return
       }
       if (paged) {
-        await applyCards(stores, answer.items)
+        await mirror.applyCards(answer.items, { lifecycle, operation })
       } else {
-        await syncCards(stores.cards, answer.items, where, { keep: touched })
+        await lifecycle.mutate(operation, async () => 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))
+        const links = await operation.wait(facade.relationships.list({ ...opts.links, size: opts.links.size ?? 0 }))
+        if (active()) {
+          const criteria = linkCriteriaOf(opts.links)
+          await lifecycle.mutate(operation, async () => await syncHelper.syncLinks(stores.links, links.items, criteria))
         }
       }
       report({ seeded: true, error: null })
     } catch (e) {
-      if (!stopped) {
+      if (active()) {
         report({ error: e as Error })
       }
     } finally {
@@ -88,17 +97,20 @@ export const makePlanningFeed = <C extends BasicConfig, T extends BasicContext<C
 
   const ready = (async () => {
     try {
-      const stop = await service.commits.subscribe(async event => {
+      const subscribing = Promise.resolve(service.commits.subscribe(async event => {
+        if (!active()) return
         if (seeding > 0) {
           touched.add(event.card)
         }
         try {
-          await applyCommitEvent(stores, event, facade)
+          await mirror.applyCommitEvent(event, facade, { lifecycle, operation })
         } catch (e) {
-          console.error('Planning feed apply error:', e)
+          if (active()) log.warn('Planning feed apply failed', { card: event.card, error: e })
         }
-      }, opts.filter)
-      if (stopped) {
+      }, opts.filter))
+      void subscribing.then(stop => { if (!active()) stop() }, () => {})
+      const stop = await operation.wait(subscribing)
+      if (!active()) {
         stop()
         return
       }
@@ -108,12 +120,13 @@ export const makePlanningFeed = <C extends BasicConfig, T extends BasicContext<C
       report({ error: e as Error })
     }
     await seed()
-    if (!stopped && opts.refresh != null && opts.refresh > 0) {
+    if (active() && opts.refresh != null && opts.refresh > 0) {
       timer = setInterval(() => { void seed() }, opts.refresh)
     }
   })()
 
-  return {
+  let unregister: (() => void) | undefined
+  const feed: PlanningFeed = {
     get connected() { return state.connected },
     get seeded() { return state.seeded },
     get error() { return state.error },
@@ -121,11 +134,17 @@ export const makePlanningFeed = <C extends BasicConfig, T extends BasicContext<C
     refresh: seed,
     stop: async () => {
       stopped = true
+      operation.cancel()
+      unregister?.()
       if (timer != null) {
         clearInterval(timer)
       }
       unsubscribe?.()
       unsubscribe = null
+      await lifecycle.drain()
+      operation.release()
     },
   }
+  unregister = service.registerFeed(feed)
+  return feed
 }

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,10 +1,22 @@
 export type * from './types.js'
+export type * from './events/types.js'
+export type * from './helper/types.js'
+export type * from './sync/types.js'
+export type * from './lifecycle/types.js'
+export type * from './validation/types.js'
 
 export * from './consts.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'
+
+export * from './resources.js'
+export * from './resource-feed.js'
+export * from './lifecycle.js'
+export * from './validation.js'

package/src/lifecycle/types.ts

@@ -0,0 +1,28 @@
+/** One captured authenticated generation; cancellation does not undo a server write. */
+export interface PlanningOperation {
+  key: string
+  signal: AbortSignal
+  active: () => boolean
+  check: () => void
+  wait: <T>(pending: Promise<T>) => Promise<T>
+  cancel: (reason?: Error) => void
+  release: () => void
+}
+
+/** Shared cancellation and the boundary between local mirror mutations and clearing. */
+export interface PlanningClientLifecycle {
+  key: () => string
+  capture: (expected?: string) => PlanningOperation
+  run: <T>(work: (operation: PlanningOperation) => Promise<T>) => Promise<T>
+  /** Local store operations only: never hold this queue over an RPC or a socket opener. */
+  mutate: <T>(operation: PlanningOperation, work: () => Promise<T>) => Promise<T>
+  drain: () => Promise<void>
+  onInvalidate: (listener: () => void | Promise<void>) => () => void
+  close: () => Promise<void>
+}
+
+export interface PlanningClientLifecycleOptions {
+  scopeKey?: () => string | undefined
+  /** Runs in the mutation queue after admitted old writes have drained. */
+  clear?: () => Promise<void>
+}

package/src/lifecycle.ts

@@ -0,0 +1,123 @@
+import { logger } from '@owlmeans/log'
+import { PlanningError } from '@owlmeans/planning'
+import type { PlanningClientLifecycle, PlanningClientLifecycleOptions, PlanningOperation } from './lifecycle/types.js'
+
+const log = logger('client-planning')
+
+export const makePlanningClientLifecycle = (opts: PlanningClientLifecycleOptions = {}): PlanningClientLifecycle => {
+  let identity = opts.scopeKey?.() ?? ''
+  let epoch = 0
+  let tail: Promise<void> = Promise.resolve()
+  let closing: Promise<void> | null = null
+  let blocked = false
+  let failed = false
+  let empty = false
+  let admissions = 0
+  const operations = new Set<AbortController>()
+  const listeners = new Set<() => void | Promise<void>>()
+  const changed = (): PlanningError => new PlanningError('client:scope-changed')
+
+  const cancel = (): void => {
+    for (const controller of operations) controller.abort(changed())
+    operations.clear()
+  }
+  const invalidate = (explicit = true): Promise<void> => {
+    // Changing a credential cannot recover a failed clear. Only an awaited explicit retry can.
+    if (!explicit && failed) { epoch++; cancel(); return Promise.resolve() }
+    if (explicit && closing != null && blocked) return closing
+    // An explicit close rejects admission. A newly observed identity already names the new
+    // credential: its RPCs may start, but its local writes queue behind this generation's clear.
+    blocked = explicit || blocked
+    epoch++
+    cancel()
+    const admitted = admissions
+    const previous = closing
+    let resolve!: () => void
+    let reject!: (error: unknown) => void
+    const attempt = new Promise<void>((yes, no) => { resolve = yes; reject = no })
+    closing = attempt
+    // Reserve clearing before invalidation listeners can start work. Each observed identity
+    // change reserves its own clear, including changes while an earlier close is still draining.
+    const clearing = tail.then(async () => { await opts.clear?.() }).catch(error => {
+      blocked = true; failed = true; cancel(); throw error
+    })
+    tail = clearing.catch(() => {})
+    const stopping = [...listeners].map(async listener => { await listener() })
+    void Promise.all([clearing, ...stopping, ...(previous != null ? [previous] : [])]).then(() => {
+      if (closing === attempt) { blocked = false; failed = false; closing = null; empty = admissions === admitted }
+      resolve()
+    }, error => {
+      if (closing === attempt) { blocked = true; failed = true; closing = null; cancel() }
+      reject(error)
+    })
+    // key() can invalidate without an awaiting caller; still observe and report cleanup failures.
+    void attempt.catch(error => log.error('Planning scope cleanup failed', error))
+    return attempt
+  }
+
+  const key = (): string => {
+    const current = opts.scopeKey?.() ?? ''
+    if (current !== identity) {
+      identity = current
+      // An awaited close already drained and emptied this generation. Adopt the next credential
+      // synchronously when no request/feed was admitted since, without a redundant invalidation.
+      if (empty && closing == null && !blocked && !failed) epoch++
+      else void invalidate(false)
+    }
+    return `${epoch}:${identity}`
+  }
+
+  const capture = (expected?: string): PlanningOperation => {
+    const captured = key()
+    if (blocked) throw changed()
+    if (expected != null && expected !== captured) throw changed()
+    empty = false
+    admissions++
+    const controller = new AbortController()
+    operations.add(controller)
+    const active = (): boolean => key() === captured && !blocked && !controller.signal.aborted
+    const check = (): void => {
+      if (key() !== captured || blocked) throw changed()
+      if (controller.signal.aborted) throw controller.signal.reason
+    }
+    const wait = async <T>(pending: Promise<T>): Promise<T> => {
+      let abort: (() => void) | undefined
+      try {
+        // Observe even an already-cancelled operation's pending promise; a late RPC rejection
+        // must never become unhandled after its caller has left this generation.
+        const cancelled = new Promise<never>((_, reject) => {
+          abort = () => reject(controller.signal.reason ?? changed())
+          controller.signal.addEventListener('abort', abort, { once: true })
+          if (!active()) abort()
+        })
+        const result = await Promise.race([pending, cancelled])
+        check()
+        return result
+      } catch (error) { check(); throw error }
+      finally { if (abort != null) controller.signal.removeEventListener('abort', abort) }
+    }
+    return { key: captured, signal: controller.signal, active, check, wait,
+      cancel: reason => { controller.abort(reason ?? changed()) }, release: () => { operations.delete(controller) } }
+  }
+
+  return {
+    key, capture,
+    run: async work => {
+      const operation = capture()
+      try { const result = await work(operation); operation.check(); return result } finally { operation.release() }
+    },
+    mutate: async (operation, work) => {
+      const writing = tail.then(async () => {
+        operation.check()
+        const result = await work()
+        operation.check()
+        return result
+      })
+      tail = writing.then(() => {}, () => {})
+      return await writing
+    },
+    drain: async () => { await tail },
+    onInvalidate: listener => { listeners.add(listener); return () => { listeners.delete(listener) } },
+    close: async () => { identity = opts.scopeKey?.() ?? ''; await invalidate() },
+  }
+}

package/src/resource-feed.ts

@@ -0,0 +1,79 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { mentionHelper, PLANNING_SERVICE, type PlanningRecord } from '@owlmeans/planning'
+import type { ListResult } from '@owlmeans/resource'
+import { planningContextOf } from './helper.js'
+import type { PlanningClientService, PlanningFeed, PlanningFeedState, PlanningResourceFeedOptions } from './types.js'
+
+/** Refresh separate resources into the stock stores; a stopped/changed-tenant feed cannot publish. */
+export const makePlanningResourceFeed = <C extends BasicConfig, T extends BasicContext<C>>(
+  context: T, opts: PlanningResourceFeedOptions = {}
+): PlanningFeed => {
+  const stores = planningContextOf(context).stores()
+  if (stores == null) throw new SyntaxError('Planning feed needs appendPlanningStores(context)')
+  const service = context.service<PlanningClientService>(PLANNING_SERVICE)
+  const { lifecycle } = service
+  const operation = lifecycle.capture()
+  const active = () => !stopped && operation.active()
+  const facade = service.for(opts.scope)
+  const state: PlanningFeedState = { connected: false, seeded: false, error: null }
+  let stopped = false
+  let pending: Promise<void> | undefined
+  let timer: ReturnType<typeof setInterval> | undefined
+  const refresh = async (): Promise<void> => {
+    if (!active()) return
+    if (pending != null) return await pending
+    pending = (async () => {
+      try {
+        for (const name of ['assignees', 'teams', 'comments', 'mentions'] as const) {
+          const query = opts[name]
+          if (query == null) continue
+          const store = stores[name]
+          const { page: _page, size: _size, sort: _sort, ids, nickname, authentication, ...where } = query as Record<string, any>
+          const matches = { ...where, ...(ids != null ? { id: { $in: ids } } : {}),
+            ...(name === 'assignees' && where.retired === false ? { retired: { $ne: true } } : {}),
+            ...(nickname != null ? { nicknameKey: mentionHelper.nicknameKey(nickname) } : {}),
+            ...(authentication != null ? { 'authentication.provider': authentication.provider, 'authentication.externalId': authentication.externalId } : {}),
+            ...(opts.scope?.entityId != null ? { entityId: opts.scope.entityId } : {}) }
+          // Capture prior versions before the request: a local mutation/new row arriving while
+          // the seed is in flight must survive an older snapshot's absence.
+          const snapshot = (await operation.wait<ListResult<PlanningRecord>>(store.list(matches as never, { size: 0 }))).items
+          operation.check()
+          const rows = await operation.wait<ListResult<PlanningRecord>>(facade[name].list(query as never))
+          if (!active()) return
+          const named = new Set(rows.items.map(row => row.id))
+          await lifecycle.mutate(operation, async () => {
+            if (!(query.size != null && query.size > 0)) {
+              for (const row of snapshot) if (!named.has(row.id)) {
+                const current = await store.load(row.id!)
+                if (current?.version === row.version) await store.delete(row.id!)
+              }
+            }
+            for (const row of rows.items as PlanningRecord[]) {
+              const previous = await store.load(row.id!)
+              if (previous == null || previous.version <= row.version) await store.save(row as never)
+            }
+          })
+        }
+        if (active()) Object.assign(state, { seeded: true, error: null })
+      } catch (error) { if (active()) state.error = error as Error }
+      if (active()) opts.onChange?.({ ...state })
+    })()
+    try { await pending } finally { pending = undefined }
+  }
+  const ready = refresh().then(() => {
+    if (active() && (opts.refresh ?? 5000) > 0) timer = setInterval(() => { void refresh() }, opts.refresh ?? 5000)
+  })
+  let unregister: (() => void) | undefined
+  const feed: PlanningFeed = {
+    get connected() { return state.connected }, get seeded() { return state.seeded }, get error() { return state.error },
+    ready, refresh,
+    stop: async () => {
+      stopped = true; operation.cancel(); unregister?.()
+      if (timer != null) clearInterval(timer)
+      await lifecycle.drain()
+      operation.release()
+    },
+  }
+  unregister = service.registerFeed(feed)
+  return feed
+}

package/src/resources.ts

@@ -0,0 +1,84 @@
+import type { BasicContext, BasicConfig } from '@owlmeans/context'
+import { planningReplyHelper, PlanningUnsupported, WorkcardNotFound } from '@owlmeans/planning'
+import type { Assignee, Team, Comment, CommentMention, PlanningResourceProtocols, PlanningProtocols, PlanningResourceCommand, PlanningResourceFacade, PlanningRecord, PlanningResourceReply } from '@owlmeans/planning'
+import type { RemoteFacadeOptions } from './types.js'
+import type { ListResult } from '@owlmeans/resource'
+import { makePlanningClientLifecycle } from './lifecycle.js'
+
+/** The same auxiliary facade in browsers and Node clients, with versioned stock state mirrors. */
+export const makeRemoteResourceFacade = <C extends BasicConfig, T extends BasicContext<C>>(
+  context: T, protocols: PlanningProtocols, opts: RemoteFacadeOptions
+): PlanningResourceFacade => {
+  const lifecycle = opts.lifecycle ?? makePlanningClientLifecycle({ scopeKey: opts.scopeKey })
+  const tree = (name: 'assignees' | 'teams' | 'comments' | 'mentions') => {
+    const value = protocols[name]
+    if (value == null) throw new PlanningUnsupported(`client:${name}`)
+    return value as unknown as PlanningResourceProtocols
+  }
+  const mirror = async (name: 'assignees' | 'teams' | 'comments' | 'mentions', row: PlanningRecord): Promise<void> => {
+    const store = opts.stores?.()?.[name]
+    if (store == null || row.id == null) return
+    const known = await store.load(row.id)
+    if (known == null || known.version <= row.version) await store.save(row as never)
+  }
+  const get = async (name: 'assignees' | 'teams' | 'comments' | 'mentions', id: string) => lifecycle.run(async operation => {
+    const row = planningReplyHelper.hydrate<PlanningRecord>(await operation.wait(context.entrypoint(tree(name).get).call({ params: { id }, timeout: opts.timeout, signal: operation.signal })))
+    await lifecycle.mutate(operation, async () => await mirror(name, row))
+    return row
+  })
+  const load = async (name: 'assignees' | 'teams' | 'comments' | 'mentions', id: string) => {
+    try { return await get(name, id) } catch (error) { if (error instanceof WorkcardNotFound) return null; throw error }
+  }
+  const list = async (name: 'assignees' | 'teams' | 'comments' | 'mentions', query?: object) => lifecycle.run(async operation => {
+    const rows = planningReplyHelper.hydrate<ListResult<PlanningRecord>>(await operation.wait(context.entrypoint(tree(name).list).call({ query: { query: JSON.stringify(query ?? {}) }, timeout: opts.timeout, signal: operation.signal })))
+    return rows
+  })
+  const write = async (name: 'assignees' | 'teams' | 'comments' | 'mentions', body: PlanningResourceCommand) => lifecycle.run(async operation => {
+    const answer = planningReplyHelper.hydrate<PlanningResourceReply>(await operation.wait(context.entrypoint(tree(name).write).call({ body, timeout: opts.timeout, signal: operation.signal })))
+    await lifecycle.mutate(operation, async () => {
+      if (answer != null && !Array.isArray(answer)) await mirror(name, answer)
+      if (name === 'mentions' && Array.isArray(answer)) for (const row of answer) if (typeof row !== 'string') await mirror(name, row)
+      if (body.action === 'remove' && body.id != null) await opts.stores?.()?.[name].delete(body.id)
+    })
+    return answer
+  })
+  return {
+    assignees: {
+      get: async id => await get('assignees', id) as Assignee,
+      load: async id => await load('assignees', id) as Assignee | null,
+      list: async query => await list('assignees', query) as ListResult<Assignee>,
+      create: async draft => await write('assignees', { action: 'create', draft }) as Assignee,
+      update: async (id, draft, options) => await write('assignees', { action: 'update', id, draft, ...options }) as Assignee,
+      retire: async (id, options) => await write('assignees', { action: 'retire', id, ...options }) as Assignee,
+    },
+    teams: {
+      get: async id => await get('teams', id) as Team,
+      load: async id => await load('teams', id) as Team | null,
+      list: async query => await list('teams', query) as ListResult<Team>,
+      create: async draft => await write('teams', { action: 'create', draft }) as Team,
+      update: async (id, draft, options) => await write('teams', { action: 'update', id, draft, ...options }) as Team,
+      remove: async (id, options) => { await write('teams', { action: 'remove', id, ...options }) },
+      members: async id => await write('teams', { action: 'members', id }) as Assignee[],
+      projects: async id => await write('teams', { action: 'projects', id }) as string[],
+      assignees: async id => await write('teams', { action: 'assignees', id }) as Assignee[],
+      addMember: async (id, assignee) => { await write('teams', { action: 'addMember', id, assignee }) },
+      removeMember: async (id, assignee) => { await write('teams', { action: 'removeMember', id, assignee }) },
+      attach: async (id, project) => { await write('teams', { action: 'attach', id, project }) },
+      detach: async (id, project) => { await write('teams', { action: 'detach', id, project }) },
+    },
+    comments: {
+      get: async id => await get('comments', id) as Comment,
+      load: async id => await load('comments', id) as Comment | null,
+      list: async query => await list('comments', query) as ListResult<Comment>,
+      create: async draft => await write('comments', { action: 'create', draft }) as Comment,
+      update: async (id, draft, options) => await write('comments', { action: 'update', id, draft, ...options }) as Comment,
+      remove: async (id, options) => { await write('comments', { action: 'remove', id, ...options }) },
+    },
+    mentions: {
+      get: async id => await get('mentions', id) as CommentMention,
+      load: async id => await load('mentions', id) as CommentMention | null,
+      list: async query => await list('mentions', query) as ListResult<CommentMention>,
+      rebuild: async id => await write('mentions', { action: 'rebuild', id }) as CommentMention[],
+    },
+  }
+}

package/src/stores.ts

@@ -1,11 +1,11 @@
 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 { appendStateResource, type StateResourceAppend } from '@owlmeans/state'
 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 { idsOf, putCard, putLink } from './utils/record.js'
 
 /**
  * Register the planning state mirror: ONE card store for every kind, a link store and a commit
@@ -23,10 +23,12 @@ export const appendPlanningStores = <C extends BasicConfig, T extends BasicConte
   ctx = appendStateResource<C, typeof ctx, Relationship>(ctx, names.links)
   ctx = appendStateResource<C, typeof ctx>(ctx, names.commits)
 
+  for (const name of [names.assignees, names.teams, names.comments, names.mentions]) ctx = appendStateResource(ctx, name as any)
   const result = ctx as T & WithPlanningStores & StateResourceAppend
   if (result.planningStores == null) {
     result.planningStores = () => ({
       cards: result.getStateResource(names.cards),
+      assignees: result.getStateResource(names.assignees), teams: result.getStateResource(names.teams), comments: result.getStateResource(names.comments), mentions: result.getStateResource(names.mentions),
       links: result.getStateResource(names.links),
       commits: result.getStateResource(names.commits),
     })
@@ -35,47 +37,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, idsOf(items), where, opts)
-  for (const item of items) {
-    await 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, 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 } })
-  }
-}
+): Promise<void> => await syncHelper.syncLinks(store, items, where, opts)