@owlmeans/planning 0.1.18-rc.0

package/src/i18n/de.json

@@ -0,0 +1,51 @@
+{
+  "kind": {
+    "card": "Karte",
+    "project": "Projekt",
+    "specification": "Spezifikation"
+  },
+  "intrinsic": {
+    "planned": "Geplant",
+    "in-progress": "In Arbeit",
+    "closed": "Abgeschlossen"
+  },
+  "action": {
+    "create": "Erstellt",
+    "update": "Aktualisiert",
+    "transit": "Status geändert",
+    "link": "Verknüpft",
+    "unlink": "Verknüpfung entfernt",
+    "delete": "Gelöscht"
+  },
+  "commit": {
+    "pending": "Wird gespeichert…",
+    "committed": "Gespeichert",
+    "failed": "Nicht gespeichert"
+  },
+  "format": {
+    "markdown": "Markdown",
+    "json": "JSON",
+    "text": "Reiner Text"
+  },
+  "errors": {
+    "PlanningError": "Die Planungsanfrage konnte nicht ausgeführt werden",
+    "PlanningErrorWorkcardNotFound": "Dieses Element existiert nicht oder ist für dich nicht verfügbar",
+    "PlanningErrorUnknownWorkcardType": "Dieser Elementtyp ist unbekannt",
+    "PlanningErrorUnknownStatusFlow": "Dieser Statusablauf ist unbekannt",
+    "PlanningErrorParentNotFound": "Das übergeordnete Element existiert nicht",
+    "PlanningErrorCardTypeNotAllowed": "Ein Element dieses Typs kann hier nicht hinzugefügt werden",
+    "PlanningErrorRefused": "Die Änderung wurde abgelehnt",
+    "PlanningErrorIllegalTransition": "Dieser Statuswechsel ist vom aktuellen Status aus nicht erlaubt",
+    "PlanningErrorFieldsInvalid": "Einige Felder haben ungültige Werte",
+    "PlanningErrorLabelNotAllowed": "Dieses Label ist hier nicht erlaubt",
+    "PlanningErrorSpecificationSlotUnknown": "Diese Art von Dokument ist hier nicht erlaubt",
+    "PlanningErrorSpecificationRevisionConflict": "Dieses Dokument existiert bereits — bearbeite es stattdessen",
+    "PlanningErrorRelationshipRefused": "Diese Verknüpfung ist nicht erlaubt",
+    "PlanningErrorCodeTaken": "Dieser Code ist bereits vergeben",
+    "PlanningErrorWorkcardConflict": "Jemand hat dieses Element inzwischen geändert — neu laden und erneut versuchen",
+    "PlanningErrorCommitTimeout": "Die Änderung wird noch gespeichert — prüfe es gleich noch einmal",
+    "PlanningErrorCommitFailed": "Die Änderung konnte nicht gespeichert werden",
+    "PlanningErrorScopeMismatch": "Dieses Element existiert nicht oder ist für dich nicht verfügbar",
+    "PlanningErrorUnsupported": "Dieser Vorgang wird für dieses Element nicht unterstützt"
+  }
+}

package/src/i18n/en.json

@@ -0,0 +1,51 @@
+{
+  "kind": {
+    "card": "Card",
+    "project": "Project",
+    "specification": "Specification"
+  },
+  "intrinsic": {
+    "planned": "Planned",
+    "in-progress": "In progress",
+    "closed": "Closed"
+  },
+  "action": {
+    "create": "Created",
+    "update": "Updated",
+    "transit": "Status changed",
+    "link": "Linked",
+    "unlink": "Unlinked",
+    "delete": "Deleted"
+  },
+  "commit": {
+    "pending": "Saving…",
+    "committed": "Saved",
+    "failed": "Not saved"
+  },
+  "format": {
+    "markdown": "Markdown",
+    "json": "JSON",
+    "text": "Plain text"
+  },
+  "errors": {
+    "PlanningError": "The planning request could not be completed",
+    "PlanningErrorWorkcardNotFound": "This item does not exist or is not available to you",
+    "PlanningErrorUnknownWorkcardType": "This item type is not known",
+    "PlanningErrorUnknownStatusFlow": "This status flow is not known",
+    "PlanningErrorParentNotFound": "The parent item does not exist",
+    "PlanningErrorCardTypeNotAllowed": "This item type cannot be added here",
+    "PlanningErrorRefused": "The change was refused",
+    "PlanningErrorIllegalTransition": "This status change is not allowed from the current status",
+    "PlanningErrorFieldsInvalid": "Some fields have invalid values",
+    "PlanningErrorLabelNotAllowed": "This label is not allowed here",
+    "PlanningErrorSpecificationSlotUnknown": "This kind of document is not allowed here",
+    "PlanningErrorSpecificationRevisionConflict": "This document already exists — edit it instead",
+    "PlanningErrorRelationshipRefused": "This link is not allowed",
+    "PlanningErrorCodeTaken": "This code is already taken",
+    "PlanningErrorWorkcardConflict": "Someone changed this item in the meantime — reload and try again",
+    "PlanningErrorCommitTimeout": "The change is still being saved — check again shortly",
+    "PlanningErrorCommitFailed": "The change could not be saved",
+    "PlanningErrorScopeMismatch": "This item does not exist or is not available to you",
+    "PlanningErrorUnsupported": "This operation is not supported for this item"
+  }
+}

package/src/i18n/es.json

@@ -0,0 +1,51 @@
+{
+  "kind": {
+    "card": "Tarjeta",
+    "project": "Proyecto",
+    "specification": "Especificación"
+  },
+  "intrinsic": {
+    "planned": "Planificado",
+    "in-progress": "En curso",
+    "closed": "Cerrado"
+  },
+  "action": {
+    "create": "Creado",
+    "update": "Actualizado",
+    "transit": "Estado cambiado",
+    "link": "Vinculado",
+    "unlink": "Vínculo eliminado",
+    "delete": "Eliminado"
+  },
+  "commit": {
+    "pending": "Guardando…",
+    "committed": "Guardado",
+    "failed": "No guardado"
+  },
+  "format": {
+    "markdown": "Markdown",
+    "json": "JSON",
+    "text": "Texto sin formato"
+  },
+  "errors": {
+    "PlanningError": "No se pudo completar la solicitud de planificación",
+    "PlanningErrorWorkcardNotFound": "Este elemento no existe o no está disponible para ti",
+    "PlanningErrorUnknownWorkcardType": "Este tipo de elemento no se conoce",
+    "PlanningErrorUnknownStatusFlow": "Este flujo de estados no se conoce",
+    "PlanningErrorParentNotFound": "El elemento superior no existe",
+    "PlanningErrorCardTypeNotAllowed": "No se puede añadir aquí un elemento de este tipo",
+    "PlanningErrorRefused": "El cambio fue rechazado",
+    "PlanningErrorIllegalTransition": "Este cambio de estado no está permitido desde el estado actual",
+    "PlanningErrorFieldsInvalid": "Algunos campos tienen valores no válidos",
+    "PlanningErrorLabelNotAllowed": "Esta etiqueta no está permitida aquí",
+    "PlanningErrorSpecificationSlotUnknown": "Este tipo de documento no está permitido aquí",
+    "PlanningErrorSpecificationRevisionConflict": "Este documento ya existe — edítalo en su lugar",
+    "PlanningErrorRelationshipRefused": "Este vínculo no está permitido",
+    "PlanningErrorCodeTaken": "Este código ya está en uso",
+    "PlanningErrorWorkcardConflict": "Alguien cambió este elemento mientras tanto — recarga e inténtalo de nuevo",
+    "PlanningErrorCommitTimeout": "El cambio aún se está guardando — vuelve a comprobarlo en breve",
+    "PlanningErrorCommitFailed": "No se pudo guardar el cambio",
+    "PlanningErrorScopeMismatch": "Este elemento no existe o no está disponible para ti",
+    "PlanningErrorUnsupported": "Esta operación no es compatible con este elemento"
+  }
+}

package/src/i18n/pl.json

@@ -0,0 +1,51 @@
+{
+  "kind": {
+    "card": "Karta",
+    "project": "Projekt",
+    "specification": "Specyfikacja"
+  },
+  "intrinsic": {
+    "planned": "Zaplanowane",
+    "in-progress": "W toku",
+    "closed": "Zamknięte"
+  },
+  "action": {
+    "create": "Utworzono",
+    "update": "Zaktualizowano",
+    "transit": "Zmieniono status",
+    "link": "Powiązano",
+    "unlink": "Usunięto powiązanie",
+    "delete": "Usunięto"
+  },
+  "commit": {
+    "pending": "Zapisywanie…",
+    "committed": "Zapisano",
+    "failed": "Nie zapisano"
+  },
+  "format": {
+    "markdown": "Markdown",
+    "json": "JSON",
+    "text": "Zwykły tekst"
+  },
+  "errors": {
+    "PlanningError": "Nie udało się wykonać żądania planowania",
+    "PlanningErrorWorkcardNotFound": "Ten element nie istnieje lub nie jest dla Ciebie dostępny",
+    "PlanningErrorUnknownWorkcardType": "Ten typ elementu jest nieznany",
+    "PlanningErrorUnknownStatusFlow": "Ten przepływ statusów jest nieznany",
+    "PlanningErrorParentNotFound": "Element nadrzędny nie istnieje",
+    "PlanningErrorCardTypeNotAllowed": "Nie można tutaj dodać elementu tego typu",
+    "PlanningErrorRefused": "Zmiana została odrzucona",
+    "PlanningErrorIllegalTransition": "Ta zmiana statusu jest niedozwolona z bieżącego statusu",
+    "PlanningErrorFieldsInvalid": "Niektóre pola mają nieprawidłowe wartości",
+    "PlanningErrorLabelNotAllowed": "Ta etykieta jest tutaj niedozwolona",
+    "PlanningErrorSpecificationSlotUnknown": "Ten rodzaj dokumentu jest tutaj niedozwolony",
+    "PlanningErrorSpecificationRevisionConflict": "Ten dokument już istnieje — edytuj go",
+    "PlanningErrorRelationshipRefused": "To powiązanie jest niedozwolone",
+    "PlanningErrorCodeTaken": "Ten kod jest już zajęty",
+    "PlanningErrorWorkcardConflict": "Ktoś w międzyczasie zmienił ten element — odśwież i spróbuj ponownie",
+    "PlanningErrorCommitTimeout": "Zmiana jest nadal zapisywana — sprawdź ponownie za chwilę",
+    "PlanningErrorCommitFailed": "Nie udało się zapisać zmiany",
+    "PlanningErrorScopeMismatch": "Ten element nie istnieje lub nie jest dla Ciebie dostępny",
+    "PlanningErrorUnsupported": "Ta operacja nie jest obsługiwana dla tego elementu"
+  }
+}

package/src/i18n/ru.json

@@ -0,0 +1,51 @@
+{
+  "kind": {
+    "card": "Карточка",
+    "project": "Проект",
+    "specification": "Спецификация"
+  },
+  "intrinsic": {
+    "planned": "Запланировано",
+    "in-progress": "В работе",
+    "closed": "Закрыто"
+  },
+  "action": {
+    "create": "Создано",
+    "update": "Обновлено",
+    "transit": "Статус изменён",
+    "link": "Связано",
+    "unlink": "Связь удалена",
+    "delete": "Удалено"
+  },
+  "commit": {
+    "pending": "Сохранение…",
+    "committed": "Сохранено",
+    "failed": "Не сохранено"
+  },
+  "format": {
+    "markdown": "Markdown",
+    "json": "JSON",
+    "text": "Обычный текст"
+  },
+  "errors": {
+    "PlanningError": "Не удалось выполнить запрос планирования",
+    "PlanningErrorWorkcardNotFound": "Этот элемент не существует или недоступен вам",
+    "PlanningErrorUnknownWorkcardType": "Этот тип элемента неизвестен",
+    "PlanningErrorUnknownStatusFlow": "Этот поток статусов неизвестен",
+    "PlanningErrorParentNotFound": "Родительский элемент не существует",
+    "PlanningErrorCardTypeNotAllowed": "Элемент этого типа нельзя добавить сюда",
+    "PlanningErrorRefused": "Изменение отклонено",
+    "PlanningErrorIllegalTransition": "Такая смена статуса недопустима из текущего статуса",
+    "PlanningErrorFieldsInvalid": "Некоторые поля содержат недопустимые значения",
+    "PlanningErrorLabelNotAllowed": "Эта метка здесь недопустима",
+    "PlanningErrorSpecificationSlotUnknown": "Этот вид документа здесь недопустим",
+    "PlanningErrorSpecificationRevisionConflict": "Этот документ уже существует — отредактируйте его",
+    "PlanningErrorRelationshipRefused": "Эта связь недопустима",
+    "PlanningErrorCodeTaken": "Этот код уже занят",
+    "PlanningErrorWorkcardConflict": "Кто-то изменил этот элемент за это время — обновите и попробуйте снова",
+    "PlanningErrorCommitTimeout": "Изменение ещё сохраняется — проверьте чуть позже",
+    "PlanningErrorCommitFailed": "Не удалось сохранить изменение",
+    "PlanningErrorScopeMismatch": "Этот элемент не существует или недоступен вам",
+    "PlanningErrorUnsupported": "Эта операция не поддерживается для этого элемента"
+  }
+}

package/src/i18n/uk.json

@@ -0,0 +1,51 @@
+{
+  "kind": {
+    "card": "Картка",
+    "project": "Проєкт",
+    "specification": "Специфікація"
+  },
+  "intrinsic": {
+    "planned": "Заплановано",
+    "in-progress": "У роботі",
+    "closed": "Закрито"
+  },
+  "action": {
+    "create": "Створено",
+    "update": "Оновлено",
+    "transit": "Статус змінено",
+    "link": "Пов’язано",
+    "unlink": "Зв’язок видалено",
+    "delete": "Видалено"
+  },
+  "commit": {
+    "pending": "Збереження…",
+    "committed": "Збережено",
+    "failed": "Не збережено"
+  },
+  "format": {
+    "markdown": "Markdown",
+    "json": "JSON",
+    "text": "Звичайний текст"
+  },
+  "errors": {
+    "PlanningError": "Не вдалося виконати запит планування",
+    "PlanningErrorWorkcardNotFound": "Цей елемент не існує або недоступний вам",
+    "PlanningErrorUnknownWorkcardType": "Цей тип елемента невідомий",
+    "PlanningErrorUnknownStatusFlow": "Цей потік статусів невідомий",
+    "PlanningErrorParentNotFound": "Батьківський елемент не існує",
+    "PlanningErrorCardTypeNotAllowed": "Елемент цього типу не можна додати сюди",
+    "PlanningErrorRefused": "Зміну відхилено",
+    "PlanningErrorIllegalTransition": "Така зміна статусу неприпустима з поточного статусу",
+    "PlanningErrorFieldsInvalid": "Деякі поля мають неприпустимі значення",
+    "PlanningErrorLabelNotAllowed": "Ця мітка тут неприпустима",
+    "PlanningErrorSpecificationSlotUnknown": "Цей вид документа тут неприпустимий",
+    "PlanningErrorSpecificationRevisionConflict": "Цей документ уже існує — відредагуйте його",
+    "PlanningErrorRelationshipRefused": "Цей зв’язок неприпустимий",
+    "PlanningErrorCodeTaken": "Цей код уже зайнятий",
+    "PlanningErrorWorkcardConflict": "Хтось змінив цей елемент тим часом — оновіть і спробуйте знову",
+    "PlanningErrorCommitTimeout": "Зміна ще зберігається — перевірте трохи пізніше",
+    "PlanningErrorCommitFailed": "Не вдалося зберегти зміну",
+    "PlanningErrorScopeMismatch": "Цей елемент не існує або недоступний вам",
+    "PlanningErrorUnsupported": "Ця операція не підтримується для цього елемента"
+  }
+}

package/src/i18n.ts

@@ -0,0 +1,21 @@
+import { addI18nLib } from '@owlmeans/i18n'
+import { PLANNING_I18N } from './consts.js'
+
+import en from './i18n/en.json' with { type: 'json' }
+import pl from './i18n/pl.json' with { type: 'json' }
+import ru from './i18n/ru.json' with { type: 'json' }
+import be from './i18n/be.json' with { type: 'json' }
+import uk from './i18n/uk.json' with { type: 'json' }
+import es from './i18n/es.json' with { type: 'json' }
+import de from './i18n/de.json' with { type: 'json' }
+
+/**
+ * Labels under `lib:planning.*`, and every refusal under the shared `errors` resource keyed by its
+ * type name — which is where a panel's error lookup (`errors.<type>`) finds them.
+ */
+const LANGUAGES = { en, pl, ru, be, uk, es, de }
+
+Object.entries(LANGUAGES).forEach(([lng, data]) => {
+  addI18nLib(lng, PLANNING_I18N, data)
+  addI18nLib(lng, 'errors', data.errors)
+})

package/src/index.ts

@@ -0,0 +1,9 @@
+export type * from './types.js'
+export * from './consts.js'
+export * from './schemas.js'
+export * from './errors.js'
+export * from './entrypoints.js'
+export * from './registry.js'
+export * from './helpers/index.js'
+export * from './models/index.js'
+export * from './i18n.js'

package/src/models/index.ts

@@ -0,0 +1,21 @@
+import { WorkcardKind } from '../consts.js'
+import type { PlanningFacade, Project, Specification, Workcard, WorkcardModel } from '../types.js'
+import { makeProjectModel } from './project.js'
+import { makeSpecificationModel } from './specification.js'
+import { makeWorkcardModel } from './workcard.js'
+
+export { executeFor, makeWorkcardModel } from './workcard.js'
+export { makeProjectModel } from './project.js'
+export { makeSpecificationModel } from './specification.js'
+
+/** The model a record's kind calls for — what a facade's `model()` answers. */
+export const modelOf = <T extends Workcard = Workcard>(record: T, facade: PlanningFacade): WorkcardModel<T> => {
+  switch (record.kind) {
+    case WorkcardKind.Project:
+      return makeProjectModel(record as unknown as Project, facade) as unknown as WorkcardModel<T>
+    case WorkcardKind.Specification:
+      return makeSpecificationModel(record as unknown as Specification, facade) as unknown as WorkcardModel<T>
+    default:
+      return makeWorkcardModel(record, facade)
+  }
+}

package/src/models/project.ts

@@ -0,0 +1,24 @@
+import { IntrinsicStatus, WorkcardKind } from '../consts.js'
+import type { PlanningFacade, Project, ProjectModel } from '../types.js'
+import { makeWorkcardModel } from './workcard.js'
+
+/** A workcard model plus the project's own reads: its cards, its sub-projects, its summary. */
+export const makeProjectModel = (record: Project, facade: PlanningFacade): ProjectModel => {
+  const model = makeWorkcardModel<Project>(record, facade)
+
+  return {
+    ...model,
+
+    cards: query => facade.cards.list({ ...query, within: model.id, kind: WorkcardKind.Card }),
+
+    projects: query => facade.cards.list({ ...query, within: model.id, kind: WorkcardKind.Project }),
+
+    summary: async query => (await facade.cards.summary([model.id], query))[model.id] ?? {
+      total: 0, [IntrinsicStatus.Planned]: 0, [IntrinsicStatus.InProgress]: 0, [IntrinsicStatus.Closed]: 0,
+    },
+
+    purge: opts => model.remove(opts),
+
+    reload: async () => makeProjectModel(await facade.cards.get(model.id) as Project, facade),
+  }
+}

package/src/models/specification.ts

@@ -0,0 +1,21 @@
+import type { PlanningFacade, Specification, SpecificationModel } from '../types.js'
+import { makeWorkcardModel } from './workcard.js'
+
+/** A workcard model over one document: its body, a revision of it, and its history from the log. */
+export const makeSpecificationModel = (record: Specification, facade: PlanningFacade): SpecificationModel => {
+  const model = makeWorkcardModel<Specification>(record, facade)
+
+  return {
+    ...model,
+
+    body: () => record.body,
+
+    revise: (body, opts) => model.update(Object.fromEntries(Object.entries({
+      body, version: opts?.version, ref: opts?.ref,
+    }).filter(([, value]) => value !== undefined)), opts),
+
+    history: limit => facade.specifications.revisions(model.id, limit),
+
+    reload: async () => makeSpecificationModel(await facade.specifications.get(model.id), facade),
+  }
+}

package/src/models/workcard.ts

@@ -0,0 +1,138 @@
+import { IntrinsicStatus, TransitionAction, WorkcardKind } from '../consts.js'
+import { PlanningError } from '../errors.js'
+import { isPending } from '../helpers/card.js'
+import { slotOf, specificationTypeOf } from '../helpers/specification.js'
+import {
+  canTransit, initialStatusOf, intrinsicOf, primaryFlowOf, transitionsFrom,
+} from '../helpers/status.js'
+import type {
+  ExecuteOptions, ModelExecuteOptions, PlanningFacade, TransitionExecution, TransitionReceipt,
+  Workcard, WorkcardModel,
+} from '../types.js'
+
+/**
+ * Run an execution with a model's defaults: `expectSeq` is the record's head (its seq when nothing
+ * is in flight) unless the caller names one — `null` opts out.
+ */
+export const executeFor = (
+  facade: PlanningFacade, record: Pick<Workcard, 'seq' | 'head'> | null, exec: TransitionExecution,
+  opts?: ModelExecuteOptions
+): Promise<TransitionReceipt> => {
+  const { wait, timeout, actor, cause, key, expectSeq } = opts ?? {}
+  const options: ExecuteOptions = Object.fromEntries(Object.entries({ wait, timeout })
+    .filter(([, value]) => value !== undefined))
+
+  return facade.execute(Object.fromEntries(Object.entries({
+    ...exec,
+    actor,
+    cause,
+    key,
+    expectSeq: expectSeq !== undefined ? expectSeq : record == null ? undefined : record.head ?? record.seq,
+  }).filter(([, value]) => value !== undefined)) as unknown as TransitionExecution, options)
+}
+
+/**
+ * The same object on a server and in a browser: reads answer from the schema registry with no I/O,
+ * writes build a {@link TransitionExecution} and hand it to the facade.
+ *
+ * @throws {PlanningError} `malformed:model-without-id` for a record that was never stored
+ */
+export const makeWorkcardModel = <T extends Workcard = Workcard>(record: T, facade: PlanningFacade): WorkcardModel<T> => {
+  if (record.id == null) {
+    throw new PlanningError('malformed:model-without-id')
+  }
+  const id = record.id
+  const run = (exec: Omit<TransitionExecution, 'card'>, opts?: ModelExecuteOptions) =>
+    executeFor(facade, record, { ...exec, card: id }, opts)
+
+  const model: WorkcardModel<T> = {
+    record,
+    id,
+    kind: record.kind,
+    type: record.type,
+
+    schema: () => facade.schemas.type(record.type),
+
+    flow: flowId => facade.schemas.flow(flowId ?? primaryFlowOf(model.schema())),
+
+    statusOf: flowId => {
+      const primary = primaryFlowOf(model.schema())
+      if (flowId == null || flowId === primary) {
+        return record.status
+      }
+      return record.flows[flowId] ?? initialStatusOf(model.flow(flowId))
+    },
+
+    intrinsicOf: flowId => flowId == null
+      ? record.intrinsic
+      : intrinsicOf(model.flow(flowId), model.statusOf(flowId)) ?? IntrinsicStatus.Planned,
+
+    can: (transition, flowId) => canTransit(model.flow(flowId), transition, model.statusOf(flowId)),
+
+    available: flowId => transitionsFrom(model.flow(flowId), model.statusOf(flowId)),
+
+    pending: () => isPending(record),
+
+    transit: (transition, changes, opts) => run({
+      action: TransitionAction.Transit, transition, flow: opts?.flow, changes,
+    }, opts),
+
+    update: (changes, opts) => run({ action: TransitionAction.Update, changes, unset: opts?.unset }, opts),
+
+    remove: opts => run({ action: TransitionAction.Delete }, opts),
+
+    link: (type, to, fields, opts) => run({
+      action: TransitionAction.Link, link: { type, from: id, to, ...(fields != null ? { fields } : {}) },
+    }, opts),
+
+    unlink: (type, to, opts) => run({ action: TransitionAction.Unlink, link: { type, from: id, to } }, opts),
+
+    children: query => facade.cards.list({ ...query, parent: id }),
+
+    relationships: query => facade.relationships.list({ ...query, from: query?.from ?? id }),
+
+    transitions: query => facade.transitions.list({ ...query, card: id }),
+
+    specification: category => facade.specifications.current(id, category),
+
+    specifications: query => facade.specifications.list(id, query),
+
+    revisions: async (category, limit) => {
+      const current = await facade.specifications.current(id, category)
+      return current?.id == null ? [] : facade.specifications.revisions(current.id, limit)
+    },
+
+    write: async (category, body, opts) => {
+      const current = await facade.specifications.current(id, category)
+      if (current?.id != null) {
+        return executeFor(facade, current, {
+          card: current.id,
+          action: TransitionAction.Update,
+          changes: Object.fromEntries(Object.entries({
+            body, format: opts?.format, version: opts?.version, ref: opts?.ref,
+          }).filter(([, value]) => value !== undefined)),
+        }, opts)
+      }
+
+      const slot = slotOf(model.schema(), category)
+      return executeFor(facade, null, {
+        card: Object.fromEntries(Object.entries({
+          kind: WorkcardKind.Specification,
+          type: opts?.type ?? specificationTypeOf(facade.schemas, record.type, slot),
+          parent: id,
+          title: opts?.title ?? category,
+          category,
+          format: opts?.format ?? slot?.format,
+          body,
+          ref: opts?.ref,
+          version: opts?.version ?? slot?.version,
+        }).filter(([, value]) => value !== undefined)) as unknown as TransitionExecution['card'],
+        action: TransitionAction.Create,
+      }, opts)
+    },
+
+    reload: async () => makeWorkcardModel(await facade.cards.get(id) as T, facade),
+  }
+
+  return model
+}

package/src/queue/index.ts

@@ -0,0 +1,31 @@
+import { declareQueue } from '@owlmeans/queue'
+import type { Config, JobOptions, QueueWorkerOptions } from '@owlmeans/queue'
+
+/**
+ * The projection queue — a separate subpath so a browser bundle importing `@owlmeans/planning`
+ * never pulls `@owlmeans/queue`.
+ *
+ * The projection is a BARE processor, not a queued entrypoint: a queued entrypoint names one
+ * service, and the same queue is served by every process that folds.
+ */
+export const PLANNING_PROJECTION_QUEUE = 'planning-projection'
+
+/** The one job the projection queue accepts. */
+export const PLANNING_PROJECT_JOB = 'planning:project'
+
+/** What one projection job folds. */
+export interface ProjectionRequest {
+  cardId: string
+  entityId: string
+  /** The transition that asked for it — a hint, never the fold's bound. */
+  transition?: string
+}
+
+export interface PlanningQueueOptions {
+  worker?: QueueWorkerOptions
+  defaults?: JobOptions
+}
+
+/** Declare the projection queue in the SHARED config; `listenQueues` stays each process's own. */
+export const declarePlanningQueue = <C extends Config>(cfg: C, opts?: PlanningQueueOptions): C =>
+  declareQueue(cfg, PLANNING_PROJECTION_QUEUE, [PLANNING_PROJECT_JOB], opts)