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

package/src/conformance/cases.ts

@@ -1,13 +1,16 @@
-import { uuid } from '@owlmeans/basic-ids'
-import { applyTransition, CardTypeNotAllowed, CommitState, IntrinsicStatus, PlanningError, PlanningSchemaKind, RelationshipRefused, SchemaConflict, SchemaInUse, SchemaInvalid, SchemaOrigin, SchemaSealed, SpecificationFormat, TransitionAction, UnknownWorkcardType, WorkcardConflict, WorkcardKind, WorkcardNotFound, type CommitEvent, type PlanningFacade, type PlanningStore, type StatusFlowSchema, type Transition, type TransitionExecution, type Unsubscribe, type Workcard, type WorkcardQuery, type WorkcardTypeSchema } from '@owlmeans/planning'
-import { creatorOf } from '../executor/creator.js'
-import { check, rejects, same, sameSet } from './assert.js'
-import { createBook, createBranch, transit } from './fixtures.js'
+
+import { applyHelper, CardTypeNotAllowed, CommitState, IntrinsicStatus, PlanningError, PlanningSchemaKind, RelationshipRefused, SchemaConflict, SchemaInUse, SchemaInvalid, SchemaOrigin, SchemaSealed, SpecificationFormat, TransitionAction, UnknownWorkcardType, WorkcardConflict, WorkcardKind, WorkcardNotFound, type CommitEvent, type PlanningFacade, type PlanningStore, type StatusFlowSchema, type Transition, type TransitionExecution, type Unsubscribe, type Workcard, type WorkcardQuery, type WorkcardTypeSchema } from '@owlmeans/planning'
+import { creatorHelper } from '../executor/creator.js'
+import { assertHelper } from './assert.js'
+import { conformanceFixturesOf } from './fixtures.js'
 import { BOOK_TYPE, LIBRARY, PERIODICAL_TYPE } from './consts.js'
 import type { ConformanceCase } from './types.js'
+import { idHelper } from '@owlmeans/basic-ids'
+
+const { check, rejects, same, sameSet } = assertHelper
 
 /** A fresh organization per case, so cases never see each other's cards on a shared database. */
-const organization = (): string => `conformance-${uuid()}`
+const organization = (): string => `conformance-${idHelper.uuid()}`
 
 const ids = async (planning: PlanningFacade, query: WorkcardQuery): Promise<string[]> =>
   (await planning.cards.list({ ...query, size: 0 })).items.map(card => card.id!)
@@ -21,13 +24,14 @@ const cases: ConformanceCase[] = [
     name: 'folds transitions in seq order and settles each one once',
     run: async ({ facade }) => {
       const planning = facade(organization())
+      const fixtures = conformanceFixturesOf(planning)
       const events: CommitEvent[] = []
       const unsubscribe: Unsubscribe = await planning.commits.subscribe(event => { events.push(event) })
       try {
-        const branch = await createBranch(planning)
-        const book = await createBook(planning, branch.id!, 'Winter poems')
+        const branch = await fixtures.createBranch()
+        const book = await fixtures.createBook(branch.id!, 'Winter poems')
         await execute(planning, { card: book.id!, action: TransitionAction.Update, changes: { title: 'Winter verses' } })
-        await transit(planning, book.id!, 'lend')
+        await fixtures.transit(book.id!, 'lend')
 
         const card = await planning.cards.get(book.id!)
         same([card.seq, card.head, card.title, card.status, card.intrinsic], [3, 3, 'Winter verses', 'lent', IntrinsicStatus.InProgress], 'the folded card')
@@ -43,13 +47,14 @@ const cases: ConformanceCase[] = [
     name: 'allocates seq against the head and refuses a stale expectSeq',
     run: async ({ facade, store }) => {
       const planning = facade(organization())
-      const book = await createBook(planning, (await createBranch(planning)).id!)
+      const fixtures = conformanceFixturesOf(planning)
+      const book = await fixtures.createBook((await fixtures.createBranch()).id!)
 
       await execute(planning, { card: book.id!, action: TransitionAction.Update, changes: { title: 'First' }, expectSeq: 1 })
       await rejects(planning.execute({ card: book.id!, action: TransitionAction.Update, changes: { title: 'Stale' }, expectSeq: 1 }),
         WorkcardConflict, 'a stale expectSeq')
       same(await store.transitions!.head(book.id!), 2, 'the head after two transitions')
-      same(await store.transitions!.nextSeq(`conformance-${uuid()}`, null), 1, 'a card with no log allocates 1')
+      same(await store.transitions!.nextSeq(`conformance-${idHelper.uuid()}`, null), 1, 'a card with no log allocates 1')
       same((await planning.cards.get(book.id!)).title, 'First', 'the refused write left the card alone')
     },
   },
@@ -58,7 +63,8 @@ const cases: ConformanceCase[] = [
     name: 'an idempotency key answers its first receipt',
     run: async ({ facade }) => {
       const planning = facade(organization())
-      const book = await createBook(planning, (await createBranch(planning)).id!)
+      const fixtures = conformanceFixturesOf(planning)
+      const book = await fixtures.createBook((await fixtures.createBranch()).id!)
 
       const first = await planning.execute({ card: book.id!, action: TransitionAction.Update, changes: { title: 'Kept' }, key: 'import:1' }, { wait: true })
       const again = await planning.execute({ card: book.id!, action: TransitionAction.Update, changes: { title: 'Lost' }, key: 'import:1' }, { wait: true })
@@ -73,14 +79,15 @@ const cases: ConformanceCase[] = [
     name: 'keeps a create\'s createdBy — the scope\'s subject, or the one the caller named — through later writes',
     run: async ({ facade }) => {
       const planning = facade(organization())
-      const subject = creatorOf(planning.scope)
+      const fixtures = conformanceFixturesOf(planning)
+      const subject = creatorHelper.creatorOf(planning.scope)
       check(subject != null, 'the conformance facade acts as a signed-in person')
 
-      const branch = await createBranch(planning)
-      const stamped = await createBook(planning, branch.id!, 'Stamped')
-      const named = await createBook(planning, branch.id!, 'Named', { createdBy: 'conformance-donor' })
+      const branch = await fixtures.createBranch()
+      const stamped = await fixtures.createBook(branch.id!, 'Stamped')
+      const named = await fixtures.createBook(branch.id!, 'Named', { createdBy: 'conformance-donor' })
       await execute(planning, { card: stamped.id!, action: TransitionAction.Update, changes: { title: 'Stamped, revised' } })
-      await transit(planning, stamped.id!, 'lend')
+      await fixtures.transit(stamped.id!, 'lend')
 
       same([branch.createdBy, (await planning.cards.get(stamped.id!)).createdBy, (await planning.cards.get(named.id!)).createdBy],
         [subject, subject, 'conformance-donor'], 'createdBy read back after later writes')
@@ -94,8 +101,9 @@ const cases: ConformanceCase[] = [
     run: async ({ facade, store }) => {
       const org = organization()
       const planning = facade(org)
-      const branch = await createBranch(planning)
-      const book = await createBook(planning, branch.id!, 'Owned')
+      const fixtures = conformanceFixturesOf(planning)
+      const branch = await fixtures.createBranch()
+      const book = await fixtures.createBook(branch.id!, 'Owned')
       const moves: TransitionExecution[] = [
         { card: book.id!, action: TransitionAction.Update, changes: { title: 'Taken', createdBy: 'conformance-intruder' } },
         { card: book.id!, action: TransitionAction.Update, unset: ['createdBy'] },
@@ -107,7 +115,7 @@ const cases: ConformanceCase[] = [
       }
       const kept = await planning.cards.get(book.id!)
       same([kept.createdBy, kept.title, kept.seq, (await planning.transitions.list({ card: book.id! })).total],
-        [creatorOf(planning.scope), 'Owned', 1, 1], 'the refused writes left the card and its log alone')
+        [creatorHelper.creatorOf(planning.scope), 'Owned', 1, 1], 'the refused writes left the card and its log alone')
 
       // Rows appended before the refusal existed: the store folds them exactly as the pure fold does.
       const legacy: Transition[] = []
@@ -124,7 +132,7 @@ const cases: ConformanceCase[] = [
       for (const row of legacy) {
         same((await planning.commits.status(row.id!)).state, CommitState.Committed, `legacy row ${row.seq} settles committed`)
       }
-      const expected = legacy.reduce<Workcard | null>((card, row) => applyTransition(card, row), kept)!
+      const expected = legacy.reduce<Workcard | null>((card, row) => applyHelper.applyTransition(card, row), kept)!
       const folded = await planning.cards.get(book.id!)
       same([folded.title, folded.seq, folded.createdBy], [expected.title, expected.seq, expected.createdBy], 'the legacy rows folded')
       await execute(planning, { card: book.id!, action: TransitionAction.Update, changes: { title: 'After' } })
@@ -136,18 +144,19 @@ const cases: ConformanceCase[] = [
     name: 'transit moves the intrinsic state and closedAt, and a second flow leaves the primary alone',
     run: async ({ facade }) => {
       const planning = facade(organization())
-      const book = await createBook(planning, (await createBranch(planning)).id!)
+      const fixtures = conformanceFixturesOf(planning)
+      const book = await fixtures.createBook((await fixtures.createBranch()).id!)
 
-      await transit(planning, book.id!, 'retire')
+      await fixtures.transit(book.id!, 'retire')
       const retired = await planning.cards.get(book.id!)
       same([retired.status, retired.intrinsic], ['retired', IntrinsicStatus.Closed], 'retired')
       check(typeof retired.closedAt === 'string', 'closedAt is set on entering closed')
 
-      await transit(planning, book.id!, 'restore')
+      await fixtures.transit(book.id!, 'restore')
       const restored = await planning.cards.get(book.id!)
       same([restored.status, restored.intrinsic, restored.closedAt], ['shelved', IntrinsicStatus.Planned, undefined], 'closedAt cleared on leaving closed')
 
-      await transit(planning, book.id!, 'review', { flow: LIBRARY.review })
+      await fixtures.transit(book.id!, 'review', { flow: LIBRARY.review })
       const reviewed = await planning.cards.get(book.id!)
       same([reviewed.status, reviewed.flows[LIBRARY.review], reviewed.intrinsic], ['shelved', 'reviewed', IntrinsicStatus.Planned], 'the second flow moved alone')
     },
@@ -158,12 +167,13 @@ const cases: ConformanceCase[] = [
     run: async ({ facade }) => {
       const org = organization()
       const planning = facade(org)
-      const east = await createBranch(planning, 'East branch')
-      const west = await createBranch(planning, 'West branch')
-      const poems = await createBook(planning, east.id!, 'Winter poems', { labels: ['rare'], fields: { genre: 'poetry', signed: true } })
-      const atlas = await createBook(planning, east.id!, 'River atlas', { labels: ['new'], parents: [west.id!], fields: { genre: 'history' } })
-      const harbour = await createBook(planning, east.id!, 'Quiet harbour', { fields: { genre: 'fiction', signed: false } })
-      await transit(planning, atlas.id!, 'lend')
+      const fixtures = conformanceFixturesOf(planning)
+      const east = await fixtures.createBranch('East branch')
+      const west = await fixtures.createBranch('West branch')
+      const poems = await fixtures.createBook(east.id!, 'Winter poems', { labels: ['rare'], fields: { genre: 'poetry', signed: true } })
+      const atlas = await fixtures.createBook(east.id!, 'River atlas', { labels: ['new'], parents: [west.id!], fields: { genre: 'history' } })
+      const harbour = await fixtures.createBook(east.id!, 'Quiet harbour', { fields: { genre: 'fiction', signed: false } })
+      await fixtures.transit(atlas.id!, 'lend')
       const since = (await planning.cards.get(atlas.id!)).updatedAt!
 
       sameSet(await ids(planning, { within: west.id }), [atlas.id], 'within')
@@ -189,8 +199,9 @@ const cases: ConformanceCase[] = [
     name: 'lists specifications only when the query asks for them',
     run: async ({ facade }) => {
       const planning = facade(organization())
-      const branch = await createBranch(planning)
-      const book = await createBook(planning, branch.id!)
+      const fixtures = conformanceFixturesOf(planning)
+      const branch = await fixtures.createBranch()
+      const book = await fixtures.createBook(branch.id!)
       const model = await planning.model(book)
       const summary = (await model.write('summary', '{"lines":["a"]}', { wait: true })).card!
       const charter = (await (await planning.model(branch)).write('charter', '# Charter', { wait: true })).card!
@@ -208,9 +219,10 @@ const cases: ConformanceCase[] = [
     name: 'pages and sorts a list, counting the whole match',
     run: async ({ facade }) => {
       const planning = facade(organization())
-      const branch = await createBranch(planning)
+      const fixtures = conformanceFixturesOf(planning)
+      const branch = await fixtures.createBranch()
       for (const order of [5, 3, 1, 4, 2]) {
-        await createBook(planning, branch.id!, `Volume ${order}`, { order })
+        await fixtures.createBook(branch.id!, `Volume ${order}`, { order })
       }
 
       const page = await planning.cards.list({ parent: branch.id, sort: ['order'], size: 2, page: 1 })
@@ -225,15 +237,16 @@ const cases: ConformanceCase[] = [
     name: 'summarizes direct children by intrinsic state',
     run: async ({ facade }) => {
       const planning = facade(organization())
-      const branch = await createBranch(planning)
-      const empty = await createBranch(planning, 'Empty branch')
-      const lent = await createBook(planning, branch.id!, 'Lent')
-      const retired = await createBook(planning, branch.id!, 'Retired')
-      await createBook(planning, branch.id!, 'Shelved')
-      await transit(planning, lent.id!, 'lend')
-      await transit(planning, retired.id!, 'retire')
-      const annex = await createBranch(planning, 'Annex', { parent: branch.id })
-      await createBook(planning, annex.id!, 'Deeper')
+      const fixtures = conformanceFixturesOf(planning)
+      const branch = await fixtures.createBranch()
+      const empty = await fixtures.createBranch('Empty branch')
+      const lent = await fixtures.createBook(branch.id!, 'Lent')
+      const retired = await fixtures.createBook(branch.id!, 'Retired')
+      await fixtures.createBook(branch.id!, 'Shelved')
+      await fixtures.transit(lent.id!, 'lend')
+      await fixtures.transit(retired.id!, 'retire')
+      const annex = await fixtures.createBranch('Annex', { parent: branch.id })
+      await fixtures.createBook(annex.id!, 'Deeper')
       await (await planning.model(branch)).write('charter', '# Charter', { wait: true })
 
       const summary = await planning.cards.summary([branch.id!, empty.id!])
@@ -248,8 +261,9 @@ const cases: ConformanceCase[] = [
     name: 'answers a specification current, listed, every document and its revisions',
     run: async ({ facade }) => {
       const planning = facade(organization())
-      const branch = await createBranch(planning)
-      const book = await createBook(planning, branch.id!)
+      const fixtures = conformanceFixturesOf(planning)
+      const branch = await fixtures.createBranch()
+      const book = await fixtures.createBook(branch.id!)
       const model = await planning.model(book)
       await model.write('summary', '{"lines":["first"]}', { wait: true })
       await (await planning.model(book.id!)).write('summary', '{"lines":["second"]}', { wait: true })
@@ -275,10 +289,11 @@ const cases: ConformanceCase[] = [
     name: 'keeps links: both ends, the single constraint, unlink and a delete dropping edges',
     run: async ({ facade }) => {
       const planning = facade(organization())
-      const branch = await createBranch(planning)
-      const first = await createBook(planning, branch.id!, 'First')
-      const second = await createBook(planning, branch.id!, 'Second')
-      const third = await createBook(planning, branch.id!, 'Third')
+      const fixtures = conformanceFixturesOf(planning)
+      const branch = await fixtures.createBranch()
+      const first = await fixtures.createBook(branch.id!, 'First')
+      const second = await fixtures.createBook(branch.id!, 'Second')
+      const third = await fixtures.createBook(branch.id!, 'Third')
 
       await execute(planning, { card: second.id!, action: TransitionAction.Link, link: { type: 'sequel-of', to: first.id! } })
       same((await planning.relationships.list({ from: second.id })).total, 1, 'from')
@@ -301,9 +316,10 @@ const cases: ConformanceCase[] = [
     name: 'isolates organizations on every read and write',
     run: async ({ facade }) => {
       const mine = facade(organization())
+      const fixtures = conformanceFixturesOf(mine)
       const theirs = facade(organization())
-      const branch = await createBranch(mine)
-      const book = await createBook(mine, branch.id!)
+      const branch = await fixtures.createBranch()
+      const book = await fixtures.createBook(branch.id!)
       const receipt = await mine.execute({ card: book.id!, action: TransitionAction.Update, changes: { title: 'Mine' } }, { wait: true })
 
       same(await theirs.cards.load(book.id!), null, 'load')
@@ -322,15 +338,16 @@ const cases: ConformanceCase[] = [
     name: 'purges everything under a deleted project, keeping at most its own delete as a tombstone',
     run: async ({ facade }) => {
       const planning = facade(organization())
-      const doomed = await createBranch(planning, 'Doomed branch')
-      const kept = await createBranch(planning, 'Kept branch')
-      const first = await createBook(planning, doomed.id!, 'First')
-      const second = await createBook(planning, doomed.id!, 'Second')
+      const fixtures = conformanceFixturesOf(planning)
+      const doomed = await fixtures.createBranch('Doomed branch')
+      const kept = await fixtures.createBranch('Kept branch')
+      const first = await fixtures.createBook(doomed.id!, 'First')
+      const second = await fixtures.createBook(doomed.id!, 'Second')
       await execute(planning, { card: second.id!, action: TransitionAction.Link, link: { type: 'sequel-of', to: first.id! } })
       const summary = (await (await planning.model(first)).write('summary', '{}', { wait: true })).card!
-      const annex = await createBranch(planning, 'Annex', { parent: doomed.id })
-      const deeper = await createBook(planning, annex.id!, 'Deeper')
-      const survivor = await createBook(planning, kept.id!, 'Survivor')
+      const annex = await fixtures.createBranch('Annex', { parent: doomed.id })
+      const deeper = await fixtures.createBook(annex.id!, 'Deeper')
+      const survivor = await fixtures.createBook(kept.id!, 'Survivor')
 
       const deleted = await planning.execute({ card: doomed.id!, action: TransitionAction.Delete }, { wait: true })
 
@@ -352,7 +369,8 @@ const cases: ConformanceCase[] = [
     run: async ({ facade, store }) => {
       const org = organization()
       const planning = facade(org)
-      const book = await createBook(planning, (await createBranch(planning)).id!)
+      const fixtures = conformanceFixturesOf(planning)
+      const book = await fixtures.createBook((await fixtures.createBranch()).id!)
       // A row two past the card with nothing between — its allocation lost long ago.
       const rogue = await store.transitions!.append({
         entityId: org, card: book.id!, kind: WorkcardKind.Card, type: LIBRARY.book, seq: 3,
@@ -375,6 +393,7 @@ const cases: ConformanceCase[] = [
     needs: ['schemas'],
     run: async ({ facade }) => {
       const planning = facade(organization())
+      const fixtures = conformanceFixturesOf(planning)
       const pamphlets: StatusFlowSchema = {
         id: 'library:pamphlet-life', version: 1,
         statuses: [{ key: 'stacked', intrinsic: IntrinsicStatus.Planned, initial: true }, { key: 'taken', intrinsic: IntrinsicStatus.Closed }],
@@ -387,11 +406,11 @@ const cases: ConformanceCase[] = [
       same(written.map(record => [record.kind, record.key, record.version]),
         [[PlanningSchemaKind.Flow, pamphlets.id, 1], [PlanningSchemaKind.Type, pamphlet.type, 1]], 'flows first, then types')
 
-      const branch = await createBranch(planning)
+      const branch = await fixtures.createBranch()
       const card = await execute(planning, { card: { kind: WorkcardKind.Card, type: pamphlet.type, parent: branch.id!, title: 'Opening hours' }, action: TransitionAction.Create })
       same([card?.status, card?.intrinsic], ['stacked', IntrinsicStatus.Planned], 'the data-defined flow started it')
       same((await planning.model(card!)).available().map(rule => rule.name), ['take'], 'the model reads the layer')
-      await transit(planning, card!.id!, 'take')
+      await fixtures.transit(card!.id!, 'take')
 
       const room = await execute(planning, { card: { kind: WorkcardKind.Project, type: LIBRARY.room, title: 'Reading room' }, action: TransitionAction.Create })
       await rejects(planning.execute({ card: { kind: WorkcardKind.Card, type: pamphlet.type, parent: room!.id!, title: 'Refused' }, action: TransitionAction.Create }),
@@ -408,8 +427,9 @@ const cases: ConformanceCase[] = [
     needs: ['schemas'],
     run: async ({ facade }) => {
       const planning = facade(organization())
-      const branch = await createBranch(planning)
-      const other = await createBranch(planning, 'Other branch')
+      const fixtures = conformanceFixturesOf(planning)
+      const branch = await fixtures.createBranch()
+      const other = await fixtures.createBranch('Other branch')
       await planning.definitions!.define({ types: [{ ...PERIODICAL_TYPE, label: 'Magazine' }] })
       await planning.definitions!.define({ types: [{ ...PERIODICAL_TYPE, label: 'Zine' }] }, { project: branch.id })
 
@@ -450,6 +470,7 @@ const cases: ConformanceCase[] = [
     needs: ['schemas'],
     run: async ({ facade }) => {
       const planning = facade(organization())
+      const fixtures = conformanceFixturesOf(planning)
       const definitions = planning.definitions!
       const repair: StatusFlowSchema = {
         id: 'library:repair', version: 1,
@@ -464,15 +485,15 @@ const cases: ConformanceCase[] = [
         type: 'library:folio', kind: WorkcardKind.Card, version: 1, fields: { type: 'object' }, flows: [repair.id], specifications: [],
       }
       await definitions.define({ flows: [repair], types: [folio] })
-      const branch = await createBranch(planning)
+      const branch = await fixtures.createBranch()
       const card = await execute(planning, { card: { kind: WorkcardKind.Card, type: folio.type, parent: branch.id!, title: 'Old map' }, action: TransitionAction.Create })
-      await transit(planning, card!.id!, 'mend')
+      await fixtures.transit(card!.id!, 'mend')
 
       await rejects(definitions.retire(PlanningSchemaKind.Flow, repair.id), SchemaInUse, 'a flow a live type runs')
 
       // The flow changes under the card: `mending` is no longer declared, and the card still moves.
       await definitions.define({ flows: [{ ...repair, statuses: [repair.statuses[0], repair.statuses[2]], transitions: [{ name: 'finish', from: ['queued'], to: 'done' }] }] })
-      await transit(planning, card!.id!, 'finish')
+      await fixtures.transit(card!.id!, 'finish')
       same((await planning.cards.get(card!.id!)).status, 'done', 'an undeclared status follows the rule of the name')
 
       await definitions.retire(PlanningSchemaKind.Type, folio.type)

package/src/conformance/clock.ts

@@ -0,0 +1,11 @@
+/**
+ * A clock that never repeats an instant — what a conformance service is booted with, so an
+ * `updatedSince` or an ordering by `at` is deterministic on a fast store.
+ */
+export const conformanceClock = (): (() => string) => {
+  let last = 0
+  return () => {
+    last = Math.max(Date.now(), last + 1)
+    return new Date(last).toISOString()
+  }
+}

package/src/conformance/consts.ts

@@ -1,4 +1,4 @@
-import { type WorkcardTypeSchema, CodeScope, CodeStyle, SpecificationFormat, WorkcardKind } from '@owlmeans/planning'
+import { type AnyTypeSchema, type PlanningPlugin, type StatusFlowSchema, type WorkcardTypeSchema, CodeScope, CodeStyle, IntrinsicStatus, SpecificationFormat, WorkcardKind } from '@owlmeans/planning'
 
 /**
  * The conformance vocabulary: a lending library. Branches (projects) hold books and periodicals
@@ -42,3 +42,89 @@ export const PERIODICAL_TYPE: WorkcardTypeSchema = {
   flows: [LIBRARY.circulation],
   specifications: [],
 }
+
+const flows: StatusFlowSchema[] = [
+  {
+    id: LIBRARY.circulation,
+    version: 1,
+    statuses: [
+      { key: 'shelved', intrinsic: IntrinsicStatus.Planned, initial: true },
+      { key: 'lent', intrinsic: IntrinsicStatus.InProgress },
+      { key: 'retired', intrinsic: IntrinsicStatus.Closed, terminal: true },
+    ],
+    transitions: [
+      { name: 'lend', from: ['shelved'], to: 'lent', explicit: true },
+      { name: 'return', from: ['lent'], to: 'shelved', explicit: true },
+      { name: 'retire', from: '*', to: 'retired' },
+      { name: 'restore', from: ['retired'], to: 'shelved' },
+    ],
+  },
+  {
+    id: LIBRARY.review,
+    version: 1,
+    statuses: [
+      { key: 'unreviewed', intrinsic: IntrinsicStatus.Planned, initial: true },
+      { key: 'reviewed', intrinsic: IntrinsicStatus.Closed },
+    ],
+    transitions: [{ name: 'review', from: ['unreviewed'], to: 'reviewed' }],
+  },
+  {
+    id: LIBRARY.branchLife,
+    version: 1,
+    statuses: [
+      { key: 'open', intrinsic: IntrinsicStatus.Planned, initial: true },
+      { key: 'active', intrinsic: IntrinsicStatus.InProgress },
+    ],
+    transitions: [{ name: 'activate', from: ['open'], to: 'active' }],
+  },
+  {
+    id: LIBRARY.pageLife,
+    version: 1,
+    statuses: [{ key: 'draft', intrinsic: IntrinsicStatus.Planned, initial: true }],
+    transitions: [],
+  },
+]
+
+const types: AnyTypeSchema[] = [
+  {
+    type: LIBRARY.branch,
+    kind: WorkcardKind.Project,
+    version: 1,
+    fields: { type: 'object', additionalProperties: true },
+    flows: [LIBRARY.branchLife],
+    cardTypes: [LIBRARY.book, LIBRARY.periodical],
+    projectTypes: [LIBRARY.branch],
+    scopedCardTypes: true,
+    specifications: [
+      { category: 'charter', format: SpecificationFormat.Markdown },
+      { category: 'notes', format: SpecificationFormat.Markdown, multiple: true },
+    ],
+    code: { style: CodeStyle.Slug, uniqueWithin: CodeScope.Entity, mutable: true },
+  },
+  {
+    type: LIBRARY.room,
+    kind: WorkcardKind.Project,
+    version: 1,
+    fields: { type: 'object', additionalProperties: true },
+    flows: [LIBRARY.branchLife],
+    cardTypes: [LIBRARY.book],
+    specifications: [],
+  },
+  BOOK_TYPE,
+  PERIODICAL_TYPE,
+  {
+    type: LIBRARY.page,
+    kind: WorkcardKind.Specification,
+    version: 1,
+    fields: { type: 'object', additionalProperties: true },
+    flows: [LIBRARY.pageLife],
+    specifications: [],
+  },
+]
+
+/** The types and flows every conformance case runs against — register it on the service under test. */
+export const planningConformancePlugin: PlanningPlugin = Object.freeze({
+  name: 'planning-conformance',
+  order: 0,
+  schemas: { types, flows },
+})

package/src/conformance/errors.ts

@@ -0,0 +1,7 @@
+/** A conformance expectation that did not hold. Plain `Error`, so any test runner reports it. */
+export class ConformanceFailure extends Error {
+  constructor(message: string) {
+    super(`planning conformance: ${message}`)
+    this.name = 'ConformanceFailure'
+  }
+}

package/src/conformance/fixtures/types.ts

@@ -0,0 +1,11 @@
+import type { TransitionReceipt, Workcard } from '@owlmeans/planning'
+
+/** The records a conformance case creates and moves, through one organization's facade. */
+export interface ConformanceFixtures {
+  /** A branch (project) at the root, written and committed. */
+  createBranch: (title?: string, extra?: Record<string, unknown>) => Promise<Workcard>
+  /** A book (card) under a branch, written and committed. */
+  createBook: (branch: string, title?: string, extra?: Record<string, unknown>) => Promise<Workcard>
+  /** A transit of a card, waited until it commits. */
+  transit: (card: string, transition: string, extra?: { flow?: string }) => Promise<TransitionReceipt>
+}

package/src/conformance/fixtures.ts

@@ -1,121 +1,46 @@
-// owlmeans-structure: allow-file the conformance fixtures are one declarative data set together with the plugin that serves it
-import { CodeScope, CodeStyle, IntrinsicStatus, SpecificationFormat, TransitionAction, WorkcardKind, type AnyTypeSchema, type PlanningFacade, type PlanningPlugin, type StatusFlowSchema, type TransitionReceipt, type Workcard } from '@owlmeans/planning'
-import { BOOK_TYPE, LIBRARY, PERIODICAL_TYPE } from './consts.js'
+import { memoHelper } from '@owlmeans/context'
+import { TransitionAction, WorkcardKind, type PlanningFacade, type TransitionReceipt, type Workcard } from '@owlmeans/planning'
+import { LIBRARY } from './consts.js'
+import type { ConformanceFixtures } from './fixtures/types.js'
 
-const flows: StatusFlowSchema[] = [
-  {
-    id: LIBRARY.circulation,
-    version: 1,
-    statuses: [
-      { key: 'shelved', intrinsic: IntrinsicStatus.Planned, initial: true },
-      { key: 'lent', intrinsic: IntrinsicStatus.InProgress },
-      { key: 'retired', intrinsic: IntrinsicStatus.Closed, terminal: true },
-    ],
-    transitions: [
-      { name: 'lend', from: ['shelved'], to: 'lent', explicit: true },
-      { name: 'return', from: ['lent'], to: 'shelved', explicit: true },
-      { name: 'retire', from: '*', to: 'retired' },
-      { name: 'restore', from: ['retired'], to: 'shelved' },
-    ],
-  },
-  {
-    id: LIBRARY.review,
-    version: 1,
-    statuses: [
-      { key: 'unreviewed', intrinsic: IntrinsicStatus.Planned, initial: true },
-      { key: 'reviewed', intrinsic: IntrinsicStatus.Closed },
-    ],
-    transitions: [{ name: 'review', from: ['unreviewed'], to: 'reviewed' }],
-  },
-  {
-    id: LIBRARY.branchLife,
-    version: 1,
-    statuses: [
-      { key: 'open', intrinsic: IntrinsicStatus.Planned, initial: true },
-      { key: 'active', intrinsic: IntrinsicStatus.InProgress },
-    ],
-    transitions: [{ name: 'activate', from: ['open'], to: 'active' }],
-  },
-  {
-    id: LIBRARY.pageLife,
-    version: 1,
-    statuses: [{ key: 'draft', intrinsic: IntrinsicStatus.Planned, initial: true }],
-    transitions: [],
-  },
-]
+export const makeConformanceFixtures = (planning: PlanningFacade): ConformanceFixtures => {
+  const createBranch = async (
+    title: string = 'Riverside branch', extra: Record<string, unknown> = {}
+  ): Promise<Workcard> => (await planning.execute({
+    card: { kind: WorkcardKind.Project, type: LIBRARY.branch, title, ...extra },
+    action: TransitionAction.Create,
+  }, { wait: true })).card!
 
-const types: AnyTypeSchema[] = [
-  {
-    type: LIBRARY.branch,
-    kind: WorkcardKind.Project,
-    version: 1,
-    fields: { type: 'object', additionalProperties: true },
-    flows: [LIBRARY.branchLife],
-    cardTypes: [LIBRARY.book, LIBRARY.periodical],
-    projectTypes: [LIBRARY.branch],
-    scopedCardTypes: true,
-    specifications: [
-      { category: 'charter', format: SpecificationFormat.Markdown },
-      { category: 'notes', format: SpecificationFormat.Markdown, multiple: true },
-    ],
-    code: { style: CodeStyle.Slug, uniqueWithin: CodeScope.Entity, mutable: true },
-  },
-  {
-    type: LIBRARY.room,
-    kind: WorkcardKind.Project,
-    version: 1,
-    fields: { type: 'object', additionalProperties: true },
-    flows: [LIBRARY.branchLife],
-    cardTypes: [LIBRARY.book],
-    specifications: [],
-  },
-  BOOK_TYPE,
-  PERIODICAL_TYPE,
-  {
-    type: LIBRARY.page,
-    kind: WorkcardKind.Specification,
-    version: 1,
-    fields: { type: 'object', additionalProperties: true },
-    flows: [LIBRARY.pageLife],
-    specifications: [],
-  },
-]
+  const createBook = async (
+    branch: string, title: string = 'A book', extra: Record<string, unknown> = {}
+  ): Promise<Workcard> => (await planning.execute({
+    card: { kind: WorkcardKind.Card, type: LIBRARY.book, parent: branch, title, ...extra },
+    action: TransitionAction.Create,
+  }, { wait: true })).card!
 
-/** The types and flows every conformance case runs against — register it on the service under test. */
-export const planningConformancePlugin: PlanningPlugin = Object.freeze({
-  name: 'planning-conformance',
-  order: 0,
-  schemas: { types, flows },
-})
+  const transit = async (
+    card: string, transition: string, extra: { flow?: string } = {}
+  ): Promise<TransitionReceipt> => await planning.execute({
+    card, action: TransitionAction.Transit, transition, ...extra,
+  }, { wait: true })
 
-/**
- * A clock that never repeats an instant — what a conformance service is booted with, so an
- * `updatedSince` or an ordering by `at` is deterministic on a fast store.
- */
-export const conformanceClock = (): (() => string) => {
-  let last = 0
-  return () => {
-    last = Math.max(Date.now(), last + 1)
-    return new Date(last).toISOString()
-  }
+  return { createBranch, createBook, transit }
 }
 
+/** The fixtures of one facade — one per facade. */
+export const conformanceFixturesOf = memoHelper.oncePer(makeConformanceFixtures)
+
+/** @deprecated compat:factory-refactor — use `conformanceFixturesOf(planning).createBranch(…)` */
 export const createBranch = async (
   planning: PlanningFacade, title: string = 'Riverside branch', extra: Record<string, unknown> = {}
-): Promise<Workcard> => (await planning.execute({
-  card: { kind: WorkcardKind.Project, type: LIBRARY.branch, title, ...extra },
-  action: TransitionAction.Create,
-}, { wait: true })).card!
+): Promise<Workcard> => await conformanceFixturesOf(planning).createBranch(title, extra)
 
+/** @deprecated compat:factory-refactor — use `conformanceFixturesOf(planning).createBook(…)` */
 export const createBook = async (
   planning: PlanningFacade, branch: string, title: string = 'A book', extra: Record<string, unknown> = {}
-): Promise<Workcard> => (await planning.execute({
-  card: { kind: WorkcardKind.Card, type: LIBRARY.book, parent: branch, title, ...extra },
-  action: TransitionAction.Create,
-}, { wait: true })).card!
+): Promise<Workcard> => await conformanceFixturesOf(planning).createBook(branch, title, extra)
 
+/** @deprecated compat:factory-refactor — use `conformanceFixturesOf(planning).transit(…)` */
 export const transit = async (
   planning: PlanningFacade, card: string, transition: string, extra: { flow?: string } = {}
-): Promise<TransitionReceipt> => await planning.execute({
-  card, action: TransitionAction.Transit, transition, ...extra,
-}, { wait: true })
+): Promise<TransitionReceipt> => await conformanceFixturesOf(planning).transit(card, transition, extra)

package/src/conformance/index.ts

@@ -7,5 +7,8 @@
 export * from './assert.js'
 export * from './cases.js'
 export type * from './types.js'
+export type * from './assert/types.js'
+export type * from './fixtures/types.js'
+export * from './clock.js'
 export * from './fixtures.js'
 export * from './consts.js'