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

package/src/definitions.ts

@@ -0,0 +1,93 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { planningReplyHelper, PlanningUnsupported, SchemaWriteMode, scopedSchemaHelper } from '@owlmeans/planning'
+import type {
+  PlanningProtocols, SchemaDefineReply, SchemaDefineRequest, ScopedSchemaBundle, ScopedSchemaRegistry,
+} from '@owlmeans/planning'
+import type { RemoteDefinitions, RemoteDefinitionsOptions } from './types.js'
+import { makePlanningClientLifecycle } from './lifecycle.js'
+
+const clean = <T extends object>(record: T): T =>
+  Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)) as T
+
+/**
+ * Data-defined types and flows over a tree declared with `definitions: true`: a layer's registry is
+ * read through `schema.list` (with its `project`) and cached per project; every write goes through
+ * `schema.define` and drops the whole cache — an organization-wide write reaches every project's
+ * layer. The records of a layer are the server's alone (`records` refuses).
+ *
+ * @throws {PlanningUnsupported} for a tree declared without `definitions`
+ */
+export const makeRemoteDefinitions = <C extends BasicConfig, T extends BasicContext<C>>(
+  context: T, protocols: PlanningProtocols, opts: RemoteDefinitionsOptions = {}
+): RemoteDefinitions => {
+  const lifecycle = opts.lifecycle ?? makePlanningClientLifecycle({ scopeKey: opts.scopeKey })
+  const define = protocols.schema.define
+  if (define == null) {
+    throw new PlanningUnsupported('client:definitions')
+  }
+  const cache = new Map<string, Promise<ScopedSchemaRegistry>>()
+
+  const invalidate = (): void => {
+    cache.clear()
+    opts.onWrite?.()
+  }
+
+  const registry = (project?: string): Promise<ScopedSchemaRegistry> => {
+    const identity = lifecycle.key()
+    const key = `${identity}\u0000${project ?? ''}`
+    let entry = cache.get(key)
+    if (entry == null) {
+      const loading = lifecycle.run(async operation => {
+        const bundle = planningReplyHelper.hydrate<ScopedSchemaBundle>(await operation.wait(context.entrypoint(protocols.schema.list).call({ query: project != null ? { project } : {}, timeout: opts.timeout, signal: operation.signal })))
+        return scopedSchemaHelper.scopedRegistryOf(bundle)
+      })
+      entry = loading
+      cache.set(key, loading)
+      // A failed read is forgotten, so the next caller asks again instead of inheriting the error.
+      loading.catch(() => {
+        if (cache.get(key) === loading) {
+          cache.delete(key)
+        }
+      })
+    }
+    return entry
+  }
+
+  const write = async (request: SchemaDefineRequest): Promise<SchemaDefineReply> => lifecycle.run(async operation => {
+    try {
+      return planningReplyHelper.hydrate<SchemaDefineReply>(await operation.wait(context.entrypoint(define).call({ body: clean(request), timeout: opts.timeout, signal: operation.signal })))
+    } finally {
+      if (operation.active()) invalidate()
+    }
+  })
+
+  return {
+    bundle: async project => (await registry(project)).bundle(),
+
+    registry,
+
+    records: async () => {
+      throw new PlanningUnsupported('client:definitions:records')
+    },
+
+    putAssigneeType: async schema => (await write({ assigneeTypes: [schema], mode: SchemaWriteMode.Put })).records[0],
+    putType: async (type, layer) =>
+      (await write({ project: layer?.project, mode: SchemaWriteMode.Put, types: [type] })).records[0],
+
+    putFlow: async (flow, layer) =>
+      (await write({ project: layer?.project, mode: SchemaWriteMode.Put, flows: [flow] })).records[0],
+
+    define: async (declarations, layer) =>
+      (await write({ project: layer?.project, mode: SchemaWriteMode.Define, ...declarations })).records,
+
+    seed: async (declarations, layer) =>
+      (await write({ project: layer?.project, mode: SchemaWriteMode.Seed, ...declarations })).records,
+
+    retire: async (kind, key, layer) => {
+      const { records } = await write({ project: layer?.project, retire: [{ kind, key }] })
+      return records[records.length - 1]
+    },
+
+    invalidate,
+  }
+}

package/src/events/types.ts

@@ -0,0 +1,35 @@
+import type { CommitEvent, PlanningFacade, TransitionReceiptView, Workcard } from '@owlmeans/planning'
+import type { PlanningClientLifecycle, PlanningOperation } from '../lifecycle/types.js'
+
+export interface PlanningMirrorOptions {
+  lifecycle: PlanningClientLifecycle
+  operation: PlanningOperation
+}
+
+/** What one set of mirror stores learns from the server: commit frames, receipts and cards read. */
+export interface PlanningMirror {
+  /**
+   * 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.
+   */
+  applyCommitEvent: (event: CommitEvent, facade?: PlanningFacade, options?: PlanningMirrorOptions) => Promise<void>
+  /**
+   * 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.
+   */
+  applyReceipt: (receipt: TransitionReceiptView, options?: PlanningMirrorOptions) => Promise<void>
+  /** Write cards the caller read on its own, under the same newer-fold-wins rule as a commit. */
+  applyCards: (cards: Workcard[], options?: PlanningMirrorOptions) => Promise<void>
+}

package/src/events.ts

@@ -1,121 +1,131 @@
-import { CommitState, TransitionAction, WorkcardKind } from '@owlmeans/planning'
-import type { CommitEvent, PlanningFacade, TransitionReceiptView, Workcard } from '@owlmeans/planning'
-import { syncLinks } from './stores.js'
+import { memoHelper } from '@owlmeans/context'
+import { CommitState, TransitionAction, WorkcardKind, type CommitEvent, type PlanningFacade, type TransitionReceiptView, type Workcard } from '@owlmeans/planning'
+import type { PlanningMirror, PlanningMirrorOptions } from './events/types.js'
+import { syncHelper } from './sync.js'
 import type { PlanningStores } from './types.js'
-import { dropCard, putCard, putCommit } 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 local = async (options: PlanningMirrorOptions | undefined, work: () => Promise<void>): Promise<void> =>
+    options == null ? await work() : await options.lifecycle.mutate(options.operation, work)
+  const read = async <T>(options: PlanningMirrorOptions | undefined, pending: Promise<T>): Promise<T> =>
+    options == null ? await pending : await options.operation.wait(pending)
+  const applyCommitEvent = async (event: CommitEvent, facade?: PlanningFacade, options?: PlanningMirrorOptions): Promise<void> => {
+    options?.operation.check()
+    // Resolve network references before entering the local mutation queue. Close must never
+    // wait for a lost card/link read, and sequence comparisons happen against the latest mirror.
+    const settled = event.state === CommitState.Committed && event.action !== TransitionAction.Delete
+    const record = event.record !== undefined ? event.record
+      : settled && facade != null ? await read(options, facade.cards.load(event.card)) : undefined
+    const links = settled && facade != null && (event.action === TransitionAction.Link || event.action === TransitionAction.Unlink)
+      ? await read(options, facade.relationships.list({ from: event.card, size: 0 })) : undefined
+    await local(options, async () => {
+      const known = await stores.cards.load(event.card)
 
-  await 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 })
-    }
-    return
-  }
-  if (known != null && known.seq > event.seq) {
-    return
-  }
+      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
+      }
 
-  if (event.action === TransitionAction.Delete) {
-    await 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
+      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 (record === null) {
-    // Committed, and gone by the time it was read: a later delete won the race.
-    await dropCard(stores, event.card, event.kind === WorkcardKind.Project)
-  } else if (record !== undefined) {
-    await putCard(stores.cards, record)
+      if (links != null) {
+        await syncHelper.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 syncLinks(stores.links, links.items, { from: event.card })
-  }
-}
+  const applyReceipt = async (receipt: TransitionReceiptView, options?: PlanningMirrorOptions): Promise<void> => local(options, async () => {
+    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
+    }
 
-/**
- * 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 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 dropCard(stores, transition.card, transition.kind === WorkcardKind.Project)
-    return
-  }
-  if (receipt.card != null) {
-    await 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 })
-  }
-}
+  const applyCards = async (cards: Workcard[], options?: PlanningMirrorOptions): Promise<void> => local(options, async () => {
+    for (const card of cards) {
+      await recordUtils.putCard(stores.cards, card)
+    }
+  })
 
-/** 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 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,16 @@
+import type { ListResult } from '@owlmeans/resource'
 import type { BasicConfig, BasicContext } from '@owlmeans/context'
 import {
-  CommitFailed, CommitState, DEFAULT_COMMIT_TIMEOUT, PlanningError, PlanningUnsupported, WorkcardNotFound,
-  encodeRelationshipQuery, encodeSpecificationQuery, encodeSummaryQuery, encodeTransitionQuery,
-  encodeWorkcardQuery, modelOf,
+  CommitFailed, CommitState, DEFAULT_COMMIT_TIMEOUT, modelOf, PlanningError, PlanningUnsupported, wireHelper,
+  WorkcardKind, WorkcardNotFound, planningReplyHelper,
 } from '@owlmeans/planning'
 import type {
-  PlanningFacade, PlanningProtocols, PlanningScope, TransitionReceipt,
-  TransitionReceiptView, Workcard, WorkcardModel,
+  PlanningFacade, PlanningProtocols, PlanningScope, PlanningReply, TransitionReceipt,
+  TransitionReceiptView, Workcard, WorkcardModel, Specification, Relationship, Transition, SpecificationRevisionList, SummaryView,
 } from '@owlmeans/planning'
-import { applyReceipt } from './events.js'
+import { makeRemoteResourceFacade } from './resources.js'
+import { planningMirrorOf } from './events.js'
+import { makePlanningClientLifecycle } from './lifecycle.js'
 import type { RemoteFacadeOptions } from './types.js'
 
 /**
@@ -30,8 +32,12 @@ export const makeRemoteFacade = <C extends BasicConfig, T extends BasicContext<C
 ): PlanningFacade => {
   const timeout = opts.timeout
   const { commits } = opts
+  const lifecycle = opts.lifecycle ?? makePlanningClientLifecycle({ scopeKey: opts.scopeKey })
 
-  const receiptOf = (view: TransitionReceiptView): TransitionReceipt => {
+  const scopedCall = async <R>(run: (signal: AbortSignal) => Promise<PlanningReply<R>>): Promise<R> =>
+    lifecycle.run(async operation => planningReplyHelper.hydrate<R>(await operation.wait(run(operation.signal))))
+
+  const receiptOf = (view: TransitionReceiptView, key: string): TransitionReceipt => {
     const id = view.transition.id
     if (id == null) {
       throw new PlanningError('malformed:receipt-without-transition')
@@ -41,26 +47,30 @@ export const makeRemoteFacade = <C extends BasicConfig, T extends BasicContext<C
       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
-        }
+        const operation = lifecycle.capture(key)
+        try {
+          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 })
+          return await operation.wait(commits.wait(id, { timeout: waitOpts?.timeout ?? DEFAULT_COMMIT_TIMEOUT }))
+        } finally { operation.release() }
       },
     }
   }
 
   const facade: PlanningFacade = {
+    ...makeRemoteResourceFacade(context, protocols, { ...opts, lifecycle }),
     scope: { ...scope, entityId: scope.entityId ?? '' },
 
     schemas: opts.schemas,
 
     cards: {
-      get: async id => await context.entrypoint(protocols.card.get).call({ params: { id }, timeout }),
+      get: async id => await scopedCall<Workcard>(signal => context.entrypoint(protocols.card.get).call({ params: { id }, timeout, signal })),
 
       load: async id => {
         try {
@@ -73,58 +83,58 @@ export const makeRemoteFacade = <C extends BasicConfig, T extends BasicContext<C
         }
       },
 
-      list: async query => await context.entrypoint(protocols.card.list).call({
-        query: encodeWorkcardQuery(query), timeout,
-      }),
+      list: async query => await scopedCall<ListResult<Workcard>>(signal => context.entrypoint(protocols.card.list).call({
+        query: wireHelper.encodeWorkcardQuery(query), timeout, signal,
+      })),
 
       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,
-        })
+        const answer = await scopedCall<ListResult<Workcard>>(signal => context.entrypoint(protocols.card.list).call({
+          query: wireHelper.encodeWorkcardQuery({ ...where, page: 0, size: 1 }), timeout, signal,
+        }))
 
         return answer.total
       },
 
-      summary: async (parents, query) => await context.entrypoint(protocols.card.summary).call({
-        query: encodeSummaryQuery({ ...query, parents }), timeout,
-      }),
+      summary: async (parents, query) => await scopedCall<SummaryView>(signal => context.entrypoint(protocols.card.summary).call({
+        query: wireHelper.encodeSummaryQuery({ ...query, parents }), timeout, signal,
+      })),
     },
 
     specifications: {
       current: async (parent, category) => {
-        const answer = await context.entrypoint(protocols.card.specifications).call({
-          params: { id: parent }, query: encodeSpecificationQuery({ category }), timeout,
-        })
+        const answer = await scopedCall<ListResult<Specification>>(signal => context.entrypoint(protocols.card.specifications).call({
+          params: { id: parent }, query: wireHelper.encodeSpecificationQuery({ category }), timeout, signal,
+        }))
 
         return answer.items[0] ?? null
       },
 
-      list: async (parent, query) => await context.entrypoint(protocols.card.specifications).call({
-        params: { id: parent }, query: encodeSpecificationQuery(query), timeout,
-      }),
+      list: async (parent, query) => await scopedCall<ListResult<Specification>>(signal => context.entrypoint(protocols.card.specifications).call({
+        params: { id: parent }, query: wireHelper.encodeSpecificationQuery(query), timeout, signal,
+      })),
 
-      get: async id => await context.entrypoint(protocols.spec.get).call({ params: { id }, timeout }),
+      get: async id => await scopedCall<Specification>(signal => context.entrypoint(protocols.spec.get).call({ params: { id }, timeout, signal })),
 
       revisions: async (id, limit) => {
-        const answer = await context.entrypoint(protocols.spec.revisions).call({
-          params: { id }, query: limit != null ? { limit } : {}, timeout,
-        })
+        const answer = await scopedCall<SpecificationRevisionList>(signal => context.entrypoint(protocols.spec.revisions).call({
+          params: { id }, query: limit != null ? { limit } : {}, timeout, signal,
+        }))
 
         return answer.items
       },
     },
 
     relationships: {
-      list: async query => await context.entrypoint(protocols.link.list).call({
-        query: encodeRelationshipQuery(query), timeout,
-      }),
+      list: async query => await scopedCall<ListResult<Relationship>>(signal => context.entrypoint(protocols.link.list).call({
+        query: wireHelper.encodeRelationshipQuery(query), timeout, signal,
+      })),
     },
 
     transitions: {
-      get: async id => await context.entrypoint(protocols.transition.get).call({
-        params: { transition: id }, timeout,
-      }),
+      get: async id => await scopedCall<Transition>(signal => context.entrypoint(protocols.transition.get).call({
+        params: { transition: id }, timeout, signal,
+      })),
 
       list: async query => {
         // The tree reads the log through ONE card; a project-wide read has no route to travel.
@@ -132,36 +142,58 @@ export const makeRemoteFacade = <C extends BasicConfig, T extends BasicContext<C
           throw new PlanningUnsupported('client:transitions-without-card')
         }
 
-        return await context.entrypoint(protocols.card.transitions).call({
-          params: { id: query.card }, query: encodeTransitionQuery(query), timeout,
-        })
+        return await scopedCall<ListResult<Transition>>(signal => context.entrypoint(protocols.card.transitions).call({
+          params: { id: query.card! }, query: wireHelper.encodeTransitionQuery(query), timeout, signal,
+        }))
       },
     },
 
     commits,
 
-    execute: async (exec, executeOpts) => {
+    execute: async (exec, executeOpts) => lifecycle.run(async operation => {
       // 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 view = planningReplyHelper.hydrate<TransitionReceiptView>(await operation.wait(context.entrypoint(protocols.execute).call({ body, timeout, signal: operation.signal })))
       const stores = opts.stores?.()
       if (stores != null) {
-        await applyReceipt(stores, view)
+        await planningMirrorOf(stores).applyReceipt(view, { lifecycle, operation })
       }
-      const receipt = receiptOf(view)
+      operation.check()
+      const receipt = receiptOf(view, operation.key)
       if (executeOpts?.wait === true) {
-        receipt.card = await receipt.committed({ timeout: executeOpts.timeout })
+        receipt.card = await operation.wait(receipt.committed({ timeout: executeOpts.timeout }))
       }
 
       return receipt
-    },
+    }),
+
+    model: async <R extends Workcard = Workcard>(card: R | string): Promise<WorkcardModel<R>> => lifecycle.run(async operation => {
+      if (opts.loadSchemas != null) await operation.wait(opts.loadSchemas())
+      const record = typeof card === 'string' ? await operation.wait(facade.cards.get(card)) as R : card
+      // A card of a project resolves its types in that project's layer; the organization's layer
+      // is the service's own bundle, and a specification's type is always code's.
+      let project = opts.definitions == null ? undefined : record.kind === WorkcardKind.Project ? record.id : undefined
+      if (opts.definitions != null && record.kind === WorkcardKind.Card) {
+        let parent = record.parent
+        const seen = new Set<string>(record.id != null ? [record.id] : [])
+        while (parent != null) {
+          if (seen.has(parent)) throw new PlanningError('hierarchy:cycle')
+          seen.add(parent)
+          const ancestor = await operation.wait(facade.cards.get(parent))
+          if (ancestor.kind === WorkcardKind.Project) { project = ancestor.id; break }
+          parent = ancestor.parent
+        }
+      }
+      if (project == null) {
+        return modelOf<R>(record, facade)
+      }
 
-    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, schemas: await operation.wait(opts.definitions!.registry(project)) })
+    }),
+  }
 
-      return modelOf<R>(record, facade)
-    },
+  if (opts.definitions != null) {
+    facade.definitions = opts.definitions
   }
 
   return facade