@owlmeans/planning 0.1.18-rc.2 → 0.1.18-rc.21

package/tests/apply.spec.ts

@@ -1,17 +1,17 @@
 import { describe, expect, test } from 'bun:test'
 import { IntrinsicStatus, TransitionAction, WorkcardKind } from '../src/consts.js'
 import { IllegalTransition, PlanningError } from '../src/errors.js'
-import { applyRelationship, applyTransition } from '../src/helpers/apply.js'
-import { assertMutable, computeChanges, isEmptyChange } from '../src/helpers/changes.js'
-import type { Relationship, Specification, Workcard } from '../src/types.js'
+import type { Relationship, Specification, Workcard, WorkcardChanges } from '../src/types.js'
 import {
   AT, ENTITY, LATER, PROJECT_TYPE, SPEC_TYPE, STORY_TYPE, TASK_TYPE, makeRegistry, transitionOf,
 } from './fixtures.js'
+import { applyHelper } from '../src/helpers/apply.js'
+import { changesHelper } from '../src/helpers/changes.js'
 
 const registry = makeRegistry()
 
 const created = (): Workcard => {
-  const { changes } = computeChanges(undefined, {
+  const { changes } = changesHelper.computeChanges(undefined, {
     action: TransitionAction.Create,
     card: {
       kind: WorkcardKind.Card, type: STORY_TYPE.type, parent: 'p1', title: 'As a user I sign in',
@@ -19,7 +19,7 @@ const created = (): Workcard => {
     },
   }, STORY_TYPE, registry, AT)
 
-  return applyTransition(undefined, transitionOf({ card: 'c1', seq: 1, action: TransitionAction.Create, changes }))!
+  return applyHelper.applyTransition(undefined, transitionOf({ card: 'c1', seq: 1, action: TransitionAction.Create, changes }))!
 }
 
 describe('applyTransition — the fold', () => {
@@ -38,7 +38,7 @@ describe('applyTransition — the fold', () => {
   test('update merges fields, replaces the rest, clears unset — and never mutates its input', () => {
     const card = created()
     const before = structuredClone(card)
-    const next = applyTransition(card, transitionOf({
+    const next = applyHelper.applyTransition(card, transitionOf({
       card: 'c1', seq: 2, action: TransitionAction.Update, at: LATER,
       changes: { title: 'Renamed', fields: { warning: 'x' }, labels: ['ui'] },
       unset: ['code', 'fields.primary'],
@@ -55,23 +55,23 @@ describe('applyTransition — the fold', () => {
   test('an applied seq returns the card unchanged; a gap or a missing card is refused', () => {
     const card = { ...created(), head: 3 }
 
-    expect(applyTransition(card, transitionOf({ card: 'c1', seq: 1, action: TransitionAction.Update }))).toBe(card)
-    expect(() => applyTransition(card, transitionOf({ card: 'c1', seq: 3, action: TransitionAction.Update })))
+    expect(applyHelper.applyTransition(card, transitionOf({ card: 'c1', seq: 1, action: TransitionAction.Update }))).toBe(card)
+    expect(() => applyHelper.applyTransition(card, transitionOf({ card: 'c1', seq: 3, action: TransitionAction.Update })))
       .toThrow(PlanningError)
-    expect(() => applyTransition(undefined, transitionOf({ card: 'c1', seq: 2, action: TransitionAction.Update })))
+    expect(() => applyHelper.applyTransition(undefined, transitionOf({ card: 'c1', seq: 2, action: TransitionAction.Update })))
       .toThrow('fold:out-of-order')
-    expect(applyTransition({ ...card, seq: 1 }, transitionOf({ card: 'c1', seq: 2, action: TransitionAction.Link, at: LATER })))
+    expect(applyHelper.applyTransition({ ...card, seq: 1 }, transitionOf({ card: 'c1', seq: 2, action: TransitionAction.Link, at: LATER })))
       .toMatchObject({ seq: 2, head: 3, updatedAt: LATER, title: card.title })
   })
 
   test('delete answers null, and a revised document carries its new revision', () => {
     const card = created()
-    expect(applyTransition(card, transitionOf({ card: 'c1', seq: 2, action: TransitionAction.Delete }))).toBeNull()
+    expect(applyHelper.applyTransition(card, transitionOf({ card: 'c1', seq: 2, action: TransitionAction.Delete }))).toBeNull()
 
     const spec = { ...card, kind: WorkcardKind.Specification, category: 'design', format: 'json', body: '{}', revision: 1 } as Specification
-    const { changes } = computeChanges(spec, { card: 'c1', action: TransitionAction.Update, changes: { body: '{"a":1}' } },
+    const { changes } = changesHelper.computeChanges(spec, { card: 'c1', action: TransitionAction.Update, changes: { body: '{"a":1}' } },
       SPEC_TYPE, registry, LATER, { slot: STORY_TYPE.specifications[0] })
-    const revised = applyTransition(spec, transitionOf({ card: 'c1', seq: 2, action: TransitionAction.Update, changes })) as Specification
+    const revised = applyHelper.applyTransition(spec, transitionOf({ card: 'c1', seq: 2, action: TransitionAction.Update, changes })) as Specification
 
     expect([revised.revision, revised.body, revised.bodyChars]).toEqual([2, '{"a":1}', 7])
   })
@@ -79,7 +79,7 @@ describe('applyTransition — the fold', () => {
 
 describe('applyRelationship', () => {
   test('a create folds its links, from the card unless a draft names another end', () => {
-    const links = applyRelationship([], transitionOf({
+    const links = applyHelper.applyRelationship([], transitionOf({
       id: 't1', card: 'c2', seq: 1, action: TransitionAction.Create, project: 'p1',
       links: [{ type: 'follows', to: 'c1' }, { type: 'follows', from: 'c0', to: 'c2' }],
     }))
@@ -92,12 +92,12 @@ describe('applyRelationship', () => {
 
   test('link is idempotent and unlink removes only the matching edge', () => {
     const link = transitionOf({ card: 'c2', seq: 2, action: TransitionAction.Link, link: { type: 'follows', to: 'c1' } })
-    const once = applyRelationship([], link)
-    const twice = applyRelationship(once, link)
-    const other = applyRelationship(twice, { ...link, link: { type: 'blocks', to: 'c1' } })
+    const once = applyHelper.applyRelationship([], link)
+    const twice = applyHelper.applyRelationship(once, link)
+    const other = applyHelper.applyRelationship(twice, { ...link, link: { type: 'blocks', to: 'c1' } })
 
     expect(twice).toHaveLength(1)
-    expect(applyRelationship(other, { ...link, action: TransitionAction.Unlink }).map(edge => edge.type))
+    expect(applyHelper.applyRelationship(other, { ...link, action: TransitionAction.Unlink }).map(edge => edge.type))
       .toEqual(['blocks'])
   })
 
@@ -105,7 +105,7 @@ describe('applyRelationship', () => {
     const edge = (from: string, to: string): Relationship => ({ entityId: ENTITY, type: 'follows', from, to, createdAt: AT })
     const links = [edge('c1', 'c2'), edge('c3', 'c1'), edge('c3', 'c4')]
 
-    expect(applyRelationship(links, transitionOf({ card: 'c1', seq: 5, action: TransitionAction.Delete })))
+    expect(applyHelper.applyRelationship(links, transitionOf({ card: 'c1', seq: 5, action: TransitionAction.Delete })))
       .toEqual([edge('c3', 'c4')])
   })
 })
@@ -113,23 +113,23 @@ describe('applyRelationship', () => {
 describe('computeChanges', () => {
   test('an update records only what differs, and one that changes nothing is empty', () => {
     const card = created()
-    const set = computeChanges(card, {
+    const set = changesHelper.computeChanges(card, {
       card: 'c1', action: TransitionAction.Update,
       changes: { title: card.title, description: 'New', fields: { area: 'user', primary: true } },
     }, STORY_TYPE, registry, LATER)
 
     expect(set).toEqual({ changes: { description: 'New', fields: { primary: true } }, unset: [] })
-    expect(isEmptyChange(computeChanges(card, {
+    expect(changesHelper.isEmptyChange(changesHelper.computeChanges(card, {
       card: 'c1', action: TransitionAction.Update, changes: { title: card.title, code: null as never },
     }, STORY_TYPE, registry, LATER))).toBe(false)
-    expect(isEmptyChange(computeChanges(card, {
+    expect(changesHelper.isEmptyChange(changesHelper.computeChanges(card, {
       card: 'c1', action: TransitionAction.Update, changes: { title: card.title, description: null as never },
     }, STORY_TYPE, registry, LATER))).toBe(true)
   })
 
   test('a transit moves the flow, mirrors status and intrinsic, and sets or clears closedAt', () => {
     const card = { ...created(), status: 'in-progress', flows: { 'test:story': 'in-progress' }, intrinsic: IntrinsicStatus.InProgress }
-    const completed = computeChanges(card, { card: 'c1', action: TransitionAction.Transit, transition: 'complete' }, STORY_TYPE, registry, LATER)
+    const completed = changesHelper.computeChanges(card, { card: 'c1', action: TransitionAction.Transit, transition: 'complete' }, STORY_TYPE, registry, LATER)
 
     expect(completed).toEqual({
       changes: { flows: { 'test:story': 'completed' }, status: 'completed', intrinsic: IntrinsicStatus.Closed, closedAt: LATER },
@@ -137,23 +137,23 @@ describe('computeChanges', () => {
     })
 
     const closed = { ...card, status: 'completed', flows: { 'test:story': 'completed' }, intrinsic: IntrinsicStatus.Closed, closedAt: LATER }
-    expect(computeChanges(closed, { card: 'c1', action: TransitionAction.Transit, transition: 'reset' }, STORY_TYPE, registry, LATER).unset)
+    expect(changesHelper.computeChanges(closed, { card: 'c1', action: TransitionAction.Transit, transition: 'reset' }, STORY_TYPE, registry, LATER).unset)
       .toEqual(['closedAt'])
-    expect(() => computeChanges(closed, { card: 'c1', action: TransitionAction.Transit, transition: 'start' }, STORY_TYPE, registry, LATER))
+    expect(() => changesHelper.computeChanges(closed, { card: 'c1', action: TransitionAction.Transit, transition: 'start' }, STORY_TYPE, registry, LATER))
       .toThrow(IllegalTransition)
   })
 
   test('a non-primary transit under IntrinsicPolicy.All keeps the card open until every flow closes', () => {
     const task = { ...created(), type: TASK_TYPE.type, status: 'completed', intrinsic: IntrinsicStatus.Planned,
       flows: { 'test:story': 'completed', 'test:review': 'reviewing' } }
-    const set = computeChanges(task, { card: 'c1', action: TransitionAction.Transit, transition: 'approve', flow: 'test:review' },
+    const set = changesHelper.computeChanges(task, { card: 'c1', action: TransitionAction.Transit, transition: 'approve', flow: 'test:review' },
       TASK_TYPE, registry, LATER)
 
     expect(set.changes).toEqual({ flows: { 'test:review': 'approved' }, intrinsic: IntrinsicStatus.Closed, closedAt: LATER })
   })
 
   test('a create of a revisioned document starts at revision 1 with its body length', () => {
-    const { changes } = computeChanges(undefined, {
+    const { changes } = changesHelper.computeChanges(undefined, {
       action: TransitionAction.Create,
       card: { kind: WorkcardKind.Specification, type: SPEC_TYPE.type, parent: 'p1', title: 'scaffold', category: 'scaffold', body: '{}' },
     }, SPEC_TYPE, registry, AT, { slot: PROJECT_TYPE.specifications[1] })
@@ -164,13 +164,77 @@ describe('computeChanges', () => {
 
 describe('assertMutable', () => {
   test('status moves only through transit, a fixed code stays fixed, derived fields are never supplied', () => {
-    expect(() => assertMutable({ card: 'c1', action: TransitionAction.Update, changes: { status: 'completed' } }, STORY_TYPE))
+    expect(() => changesHelper.assertMutable({ card: 'c1', action: TransitionAction.Update, changes: { status: 'completed' } }, STORY_TYPE))
       .toThrow('immutable:status')
-    expect(() => assertMutable({ card: 'c1', action: TransitionAction.Update, changes: { code: 'US-X' } }, STORY_TYPE))
+    expect(() => changesHelper.assertMutable({ card: 'c1', action: TransitionAction.Update, changes: { code: 'US-X' } }, STORY_TYPE))
       .toThrow('immutable:code')
-    expect(() => assertMutable({ card: 'c1', action: TransitionAction.Update, unset: ['title'] }, STORY_TYPE))
+    expect(() => changesHelper.assertMutable({ card: 'c1', action: TransitionAction.Update, unset: ['title'] }, STORY_TYPE))
       .toThrow('immutable:title')
-    expect(() => assertMutable({ card: 'c1', action: TransitionAction.Update, changes: { code: 'free' } }, TASK_TYPE))
+    expect(() => changesHelper.assertMutable({ card: 'c1', action: TransitionAction.Update, changes: { code: 'free' } }, TASK_TYPE))
       .not.toThrow()
   })
+
+  test('provenance is never written after the create: createdBy and createdAt in changes or unset, on any action', () => {
+    const draft = { kind: WorkcardKind.Card, type: STORY_TYPE.type, parent: 'p1', title: 'Owned', createdBy: 'owner-1' }
+    const refused = [
+      { card: 'c1', action: TransitionAction.Update, changes: { createdBy: 'intruder' } },
+      { card: 'c1', action: TransitionAction.Update, changes: { createdBy: null } },
+      { card: 'c1', action: TransitionAction.Update, unset: ['createdBy'] },
+      { card: 'c1', action: TransitionAction.Transit, transition: 'start', changes: { createdBy: 'intruder' } },
+      { card: 'c1', action: TransitionAction.Link, link: { type: 'follows', to: 'c2' }, unset: ['createdBy'] },
+      { card: draft, action: TransitionAction.Create, changes: { createdBy: 'intruder' } },
+    ] as Parameters<typeof changesHelper.assertMutable>[0][]
+
+    for (const exec of refused) {
+      expect(() => changesHelper.assertMutable(exec, STORY_TYPE)).toThrow('planning:immutable:createdBy')
+    }
+    expect(() => changesHelper.assertMutable({ card: 'c1', action: TransitionAction.Update, changes: { createdAt: LATER } as WorkcardChanges }, STORY_TYPE))
+      .toThrow('planning:immutable:createdAt')
+    expect(() => changesHelper.assertMutable({ card: 'c1', action: TransitionAction.Update, unset: ['createdAt'] }, STORY_TYPE))
+      .toThrow('planning:immutable:createdAt')
+    expect(() => changesHelper.assertMutable({ card: draft, action: TransitionAction.Create }, STORY_TYPE)).not.toThrow()
+    expect(() => changesHelper.assertMutable({ card: 'c1', action: TransitionAction.Update, changes: { createdBy: undefined, title: 'T' } }, STORY_TYPE))
+      .not.toThrow()
+  })
+})
+
+describe('createdBy — written by the create alone', () => {
+  const owned = (): Workcard => ({ ...created(), createdBy: 'owner-1' })
+
+  test('computeChanges takes it from the draft and never from changes or unset', () => {
+    const create = changesHelper.computeChanges(undefined, {
+      action: TransitionAction.Create,
+      card: { kind: WorkcardKind.Card, type: STORY_TYPE.type, parent: 'p1', title: 'Owned', createdBy: 'owner-1' },
+      changes: { createdBy: 'intruder' },
+    }, STORY_TYPE, registry, AT)
+    expect(create.changes.createdBy).toBe('owner-1')
+
+    const update = changesHelper.computeChanges(owned(), {
+      card: 'c1', action: TransitionAction.Update, changes: { createdBy: 'intruder', title: 'Renamed' }, unset: ['createdBy'],
+    }, STORY_TYPE, registry, LATER)
+    expect(update).toEqual({ changes: { title: 'Renamed' }, unset: [] })
+
+    const cleared = changesHelper.computeChanges(owned(), { card: 'c1', action: TransitionAction.Update, changes: { createdBy: null } as unknown as WorkcardChanges },
+      STORY_TYPE, registry, LATER)
+    expect(changesHelper.isEmptyChange(cleared)).toBe(true)
+
+    const transit = changesHelper.computeChanges(owned(), {
+      card: 'c1', action: TransitionAction.Transit, transition: 'start', changes: { createdBy: 'intruder' }, unset: ['createdBy'],
+    }, STORY_TYPE, registry, LATER)
+    expect(transit.changes.createdBy).toBeUndefined()
+    expect(transit.unset).not.toContain('createdBy')
+  })
+
+  test('the fold replays a legacy transition that named it, as written — the refusal is at admission', () => {
+    const card = owned()
+    const renamed = applyHelper.applyTransition(card, transitionOf({
+      card: 'c1', seq: 2, action: TransitionAction.Update, at: LATER, changes: { title: 'Legacy', createdBy: 'intruder' },
+    }))!
+    const cleared = applyHelper.applyTransition(renamed, transitionOf({ card: 'c1', seq: 3, action: TransitionAction.Update, unset: ['createdBy'] }))!
+
+    expect([renamed.seq, renamed.title, renamed.createdBy, renamed.createdAt]).toEqual([2, 'Legacy', 'intruder', AT])
+    expect([cleared.seq, cleared.title, cleared.createdBy]).toEqual([3, 'Legacy', undefined])
+    expect(applyHelper.applyTransition(cleared, transitionOf({ card: 'c1', seq: 4, action: TransitionAction.Update, changes: { title: 'After' } }))!
+      .title).toBe('After')
+  })
 })

package/tests/code.spec.ts

@@ -1,14 +1,14 @@
 import { describe, expect, test } from 'bun:test'
 import { CodeScope, CodeStyle } from '../src/consts.js'
 import { CodeTaken } from '../src/errors.js'
-import { codeScopeOf, mintCode } from '../src/helpers/code.js'
 import { STORY_TYPE } from './fixtures.js'
+import { codeHelper } from '../src/helpers/code.js'
 
 const free = () => false
 
 describe('mintCode', () => {
   test('random: prefix plus an upper-cased Base58 part of the policy length', async () => {
-    const code = await mintCode(STORY_TYPE.code!, free)
+    const code = await codeHelper.mintCode(STORY_TYPE.code!, free)
 
     expect(code).toMatch(/^US-[1-9A-Z]{5}$/)
   })
@@ -17,24 +17,24 @@ describe('mintCode', () => {
     const policy = { style: CodeStyle.Slug, uniqueWithin: CodeScope.Entity }
     const taken = new Set(['shop-dashboard', 'shop-dashboard-2'])
 
-    expect(await mintCode(policy, free, 8, { seed: 'Shop Dashboard!' })).toBe('shop-dashboard')
-    expect(await mintCode(policy, code => taken.has(code), 8, { seed: 'Shop Dashboard!' })).toBe('shop-dashboard-3')
-    expect(await mintCode(policy, free)).toMatch(/^[a-z]+-[a-z]+$/)
+    expect(await codeHelper.mintCode(policy, free, 8, { seed: 'Shop Dashboard!' })).toBe('shop-dashboard')
+    expect(await codeHelper.mintCode(policy, code => taken.has(code), 8, { seed: 'Shop Dashboard!' })).toBe('shop-dashboard-3')
+    expect(await codeHelper.mintCode(policy, free)).toMatch(/^[a-z]+-[a-z]+$/)
   })
 
   test('sequential: counts on from the scope, zero-padded to the length', async () => {
     const policy = { prefix: 'REQ-', style: CodeStyle.Sequential, length: 3, uniqueWithin: CodeScope.Parent }
 
-    expect(await mintCode(policy, free, 8, { count: 41 })).toBe('REQ-042')
-    expect(await mintCode(policy, async code => code === 'REQ-042', 8, { count: 41 })).toBe('REQ-043')
+    expect(await codeHelper.mintCode(policy, free, 8, { count: 41 })).toBe('REQ-042')
+    expect(await codeHelper.mintCode(policy, async code => code === 'REQ-042', 8, { count: 41 })).toBe('REQ-043')
   })
 
   test('refuses with CodeTaken after the attempt cap, asking exactly that many times', async () => {
     let asked = 0
     const always = async () => { asked++; return true }
 
-    await expect(mintCode(STORY_TYPE.code!, always, 3)).rejects.toThrow(CodeTaken)
+    await expect(codeHelper.mintCode(STORY_TYPE.code!, always, 3)).rejects.toThrow(CodeTaken)
     expect(asked).toBe(3)
-    expect(codeScopeOf(STORY_TYPE.code!, { parent: 'p1' })).toEqual({ parent: 'p1' })
+    expect(codeHelper.codeScopeOf(STORY_TYPE.code!, { parent: 'p1' })).toEqual({ parent: 'p1' })
   })
 })

package/tests/entrypoints.spec.ts

@@ -2,14 +2,15 @@ import { describe, expect, test } from 'bun:test'
 import { protocols } from '@owlmeans/entrypoint'
 import { RouteMethod, RouteProtocols } from '@owlmeans/route'
 import { makePlanningProtocols } from '../src/entrypoints.js'
-import { PLANNING_PATH, planningAliases } from '../src/consts.js'
+import { PLANNING_PATH } from '../src/consts.js'
+import { planningAliasHelper } from '../src/aliases.js'
 
 const BASE = 'app:api:planning'
 
 describe('makePlanningProtocols', () => {
   test('declares every leaf once, each alias derived from the base alias', () => {
     const tree = makePlanningProtocols({ base: { alias: BASE }, guards: 'guard:default' })
-    const aliases = planningAliases(BASE)
+    const aliases = planningAliasHelper.planningAliases(BASE)
     const declared = protocols(tree as never).map(protocol => protocol.alias)
 
     expect(new Set(declared).size).toBe(declared.length)
@@ -46,6 +47,21 @@ describe('makePlanningProtocols', () => {
     expect(tree.card.list.contract?.requestSchemas.query).toBeDefined()
   })
 
+  test('definitions add the scoped schema list and the schema write; without them neither exists', () => {
+    const plain = makePlanningProtocols({ base: { alias: BASE }, guards: 'guard:default' })
+    const scoped = makePlanningProtocols({ base: { alias: BASE }, guards: 'guard:default', definitions: true })
+    const define = planningAliasHelper.planningDefinitionAliases(BASE).define
+
+    expect(plain.schema.define).toBeUndefined()
+    expect(plain.schema.list.contract?.requestSchemas.query).toBeUndefined()
+    expect(protocols(plain as never).some(protocol => protocol.alias === define)).toBe(false)
+
+    expect(scoped.schema.define?.alias).toBe(define)
+    expect(scoped.schema.define?.route.route).toMatchObject({ path: '/schemas', method: RouteMethod.POST, parent: BASE })
+    expect(scoped.schema.list.contract?.requestSchemas.query).toBeDefined()
+    expect(protocols(scoped as never).filter(protocol => protocol.alias === define)).toHaveLength(1)
+  })
+
   test('the commit feed is a socket under socketBase when given, under the planning base otherwise', () => {
     const own = makePlanningProtocols({ base: { alias: BASE }, guards: 'guard:default' })
     const shared = makePlanningProtocols({ base: { alias: BASE }, guards: 'guard:default', socketBase: 'app:update' })

package/tests/error-status.spec.ts

@@ -26,6 +26,11 @@ const DECLARED: Record<string, number | undefined> = {
   LabelNotAllowed: 422,
   SpecificationSlotUnknown: 422,
   RelationshipRefused: 422,
+  SchemaConflict: 409,
+  SchemaInUse: 409,
+  SchemaSealed: 422,
+  SchemaInvalid: 422,
+  PlanningForbidden: 403,
   CommitTimeout: undefined,
   CommitFailed: undefined,
   PlanningUnsupported: undefined,
@@ -40,7 +45,7 @@ describe('planning refusals — declared HTTP statuses', () => {
     expect(classes.map(([name]) => name).sort()).toEqual(Object.keys(DECLARED).sort())
   })
 
-  test('an absent card is 404, a card in another state 409, refused content 422; faults declare nothing', () => {
+  test('an absent card is 404, a missing grant 403, a card in another state 409, refused content 422; faults declare nothing', () => {
     for (const [name, Class] of classes) {
       expect([name, statusOf(new Class('x'))]).toEqual([name, DECLARED[name]])
     }

package/tests/models.spec.ts

@@ -1,16 +1,17 @@
 import { describe, expect, test } from 'bun:test'
-import { applyQuery } from '@owlmeans/resource'
 import { CommitState, TransitionAction, WorkcardKind } from '../src/consts.js'
 import { WorkcardNotFound } from '../src/errors.js'
-import { applyTransition } from '../src/helpers/apply.js'
-import { computeChanges, isEmptyChange } from '../src/helpers/changes.js'
-import { criteriaOf, summaryOf } from '../src/helpers/query.js'
-import { currentSpecification, slotOf } from '../src/helpers/specification.js'
 import { makeProjectModel, makeWorkcardModel, modelOf } from '../src/models/index.js'
+import type { ProjectModel } from '../src/models/types.js'
 import type {
   PlanningFacade, Project, Specification, TransitionExecution, Workcard, WorkcardDraft,
 } from '../src/types.js'
 import { AT, ENTITY, PROJECT_TYPE, STORY_TYPE, makeRegistry } from './fixtures.js'
+import { applyHelper } from '../src/helpers/apply.js'
+import { changesHelper } from '../src/helpers/changes.js'
+import { queryHelper } from '../src/helpers/query.js'
+import { specificationHelper } from '../src/helpers/specification.js'
+import { recordQueryHelper } from '@owlmeans/resource'
 
 /**
  * The smallest facade the models can run against: maps, folded synchronously with the package's
@@ -28,14 +29,14 @@ const makeFacade = () => {
     cards: {
       get: async id => cards.get(id) ?? Promise.reject(new WorkcardNotFound(id)),
       load: async id => cards.get(id) ?? null,
-      list: async query => applyQuery([...cards.values()], criteriaOf(query, facade.scope)),
-      count: async query => applyQuery([...cards.values()], criteriaOf(query, facade.scope)).total,
+      list: async query => recordQueryHelper.applyQuery([...cards.values()], queryHelper.criteriaOf(query, facade.scope)),
+      count: async query => recordQueryHelper.applyQuery([...cards.values()], queryHelper.criteriaOf(query, facade.scope)).total,
       summary: async (parents, query) =>
-        summaryOf(applyQuery([...cards.values()], criteriaOf(query, facade.scope)).items, parents),
+        queryHelper.summaryOf(recordQueryHelper.applyQuery([...cards.values()], queryHelper.criteriaOf(query, facade.scope)).items, parents),
     },
     specifications: {
-      current: async (parent, category) => currentSpecification([...cards.values()].filter(card => card.parent === parent), category),
-      list: async parent => applyQuery([...cards.values()], { parent, kind: WorkcardKind.Specification }) as never,
+      current: async (parent, category) => specificationHelper.currentSpecification([...cards.values()].filter(card => card.parent === parent), category),
+      list: async parent => recordQueryHelper.applyQuery([...cards.values()], { parent, kind: WorkcardKind.Specification }) as never,
       get: async id => cards.get(id) as Specification,
       revisions: async () => [],
     },
@@ -53,18 +54,18 @@ const makeFacade = () => {
       const type = schemas.type(card?.type ?? draft!.type)
       const parent = cards.get(card?.parent ?? draft?.parent ?? '')
       const category = (card as Specification | undefined)?.category ?? draft?.category
-      const slot = parent != null && category != null ? slotOf(schemas.type(parent.type), category) : undefined
-      const set = computeChanges(card, exec, type, schemas, AT, { slot })
+      const slot = parent != null && category != null ? specificationHelper.slotOf(schemas.type(parent.type), category) : undefined
+      const set = changesHelper.computeChanges(card, exec, type, schemas, AT, { slot })
       const id = card?.id ?? `card-${++next}`
       const transition = {
         id: `t-${++next}`, entityId: ENTITY, card: id, kind: card?.kind ?? draft!.kind, type: type.type,
         seq: (card?.head ?? card?.seq ?? 0) + 1, action: exec.action, changes: set.changes, unset: set.unset,
         actor: {}, at: AT, commit: { state: CommitState.Committed },
       }
-      if (exec.action === TransitionAction.Update && isEmptyChange(set)) {
+      if (exec.action === TransitionAction.Update && changesHelper.isEmptyChange(set)) {
         return { transition, card, committed: async () => card ?? null }
       }
-      const folded = applyTransition(card, transition)
+      const folded = applyHelper.applyTransition(card, transition)
       folded == null ? cards.delete(id) : cards.set(id, folded)
       return { transition, card: folded, committed: async () => folded }
     },
@@ -125,7 +126,7 @@ describe('write', () => {
     const project = await seed({ kind: WorkcardKind.Project, type: PROJECT_TYPE.type, title: 'Shop' })
     await seed({ kind: WorkcardKind.Card, type: STORY_TYPE.type, parent: project.id, title: 'Story', fields: { area: 'user', primary: false } })
 
-    const model = await facade.model(project) as unknown as ReturnType<typeof makeProjectModel>
+    const model = await facade.model(project) as unknown as ProjectModel
 
     expect(await model.summary()).toEqual({ total: 1, planned: 1, 'in-progress': 0, closed: 0 })
     expect((await model.cards()).total).toBe(1)

package/tests/query.spec.ts

@@ -1,13 +1,11 @@
 import { describe, expect, test } from 'bun:test'
-import { applyQuery } from '@owlmeans/resource'
 import { IntrinsicStatus, WorkcardKind } from '../src/consts.js'
 import { PlanningError } from '../src/errors.js'
-import {
-  criteriaOf, decodeSummaryQuery, decodeWorkcardQuery, encodeSummaryQuery, encodeWorkcardQuery, listOptionsOf,
-  summaryOf,
-} from '../src/helpers/query.js'
 import type { Workcard, WorkcardQuery } from '../src/types.js'
 import { AT, ENTITY } from './fixtures.js'
+import { queryHelper } from '../src/helpers/query.js'
+import { wireHelper } from '../src/helpers/wire.js'
+import { recordQueryHelper } from '@owlmeans/resource'
 
 const card = (id: string, extra: Partial<Workcard>): Workcard => ({
   id, kind: WorkcardKind.Card, type: 'test:story', entityId: ENTITY, title: `Card ${id}`, parent: 'p1',
@@ -23,11 +21,11 @@ const CARDS = [
 ]
 
 const ids = (query: WorkcardQuery): string[] =>
-  applyQuery(CARDS, criteriaOf(query, { entityId: ENTITY }), listOptionsOf(query)).items.map(item => item.id!)
+  recordQueryHelper.applyQuery(CARDS, queryHelper.criteriaOf(query, { entityId: ENTITY }), queryHelper.listOptionsOf(query)).items.map(item => item.id!)
 
 describe('criteriaOf', () => {
   test('translates the table, always scoped to the entity and omitting what is undefined', () => {
-    expect(criteriaOf({
+    expect(queryHelper.criteriaOf({
       kind: WorkcardKind.Card, type: ['test:story', 'test:task'], parent: 'p1', within: 'p2', status: undefined,
       labels: ['ui'], ids: ['a'], flow: { id: 'test:story', status: ['planned'] }, fields: { area: 'user' },
       code: 'US-AAA', updatedSince: AT,
@@ -60,30 +58,30 @@ describe('wire queries', () => {
       flow: { id: 'test:story', status: ['planned', 'failed'] }, fields: { area: 'user', primary: true },
       q: 'sign in', page: 1, size: 20, sort: ['order', { field: 'updatedAt', order: 'desc' }],
     }
-    const wire = encodeWorkcardQuery(query)
+    const wire = wireHelper.encodeWorkcardQuery(query)
 
     expect(Object.values(wire).every(value => typeof value === 'string' || typeof value === 'number')).toBe(true)
     expect(wire.sort).toBe('order,-updatedAt')
-    expect(criteriaOf(decodeWorkcardQuery(wire), { entityId: ENTITY })).toEqual(criteriaOf(query, { entityId: ENTITY }))
-    expect(listOptionsOf(decodeWorkcardQuery(wire))).toEqual({ page: 1, size: 20, sort: ['order', { field: 'updatedAt', order: 'desc' }] })
+    expect(queryHelper.criteriaOf(wireHelper.decodeWorkcardQuery(wire), { entityId: ENTITY })).toEqual(queryHelper.criteriaOf(query, { entityId: ENTITY }))
+    expect(queryHelper.listOptionsOf(wireHelper.decodeWorkcardQuery(wire))).toEqual({ page: 1, size: 20, sort: ['order', { field: 'updatedAt', order: 'desc' }] })
   })
 
   test('decode accepts what a transport may have split already, and coerces numbers', () => {
-    expect(decodeWorkcardQuery({ status: ['planned', 'failed'], size: '10', labels: 'ui' } as never))
+    expect(wireHelper.decodeWorkcardQuery({ status: ['planned', 'failed'], size: '10', labels: 'ui' } as never))
       .toEqual({ status: ['planned', 'failed'], size: 10, labels: ['ui'] })
-    expect(decodeSummaryQuery(encodeSummaryQuery({ parents: ['p1', 'p2'], type: 'test:story' })))
+    expect(wireHelper.decodeSummaryQuery(wireHelper.encodeSummaryQuery({ parents: ['p1', 'p2'], type: 'test:story' })))
       .toEqual({ parents: ['p1', 'p2'], type: 'test:story' })
   })
 
   test('a value that does not decode is a malformed query', () => {
-    expect(() => decodeWorkcardQuery({ fields: '{broken' })).toThrow(PlanningError)
-    expect(() => decodeWorkcardQuery({ size: 'many' } as never)).toThrow('malformed:query:size')
+    expect(() => wireHelper.decodeWorkcardQuery({ fields: '{broken' })).toThrow(PlanningError)
+    expect(() => wireHelper.decodeWorkcardQuery({ size: 'many' } as never)).toThrow('malformed:query:size')
   })
 })
 
 describe('summaryOf', () => {
   test('counts direct children per parent by intrinsic state, with no key for a parent without any', () => {
-    expect(summaryOf(CARDS.filter(item => item.entityId === ENTITY), ['p1', 'p3'])).toEqual({
+    expect(queryHelper.summaryOf(CARDS.filter(item => item.entityId === ENTITY), ['p1', 'p3'])).toEqual({
       p1: { total: 2, planned: 1, 'in-progress': 0, closed: 1 },
     })
   })

package/tests/schemas.spec.ts

@@ -1,11 +1,11 @@
 import { describe, expect, test } from 'bun:test'
 import * as schemas from '../src/schemas.js'
 import { TransitionAction, WorkcardKind } from '../src/consts.js'
-import { makeAjv, validateCard } from '../src/helpers/validate.js'
-import { applyTransition } from '../src/helpers/apply.js'
-import { computeChanges } from '../src/helpers/changes.js'
+import { makeAjv, validateHelper } from '../src/helpers/validate.js'
 import { FieldsInvalid } from '../src/errors.js'
 import { AT, STORY_TYPE, makeRegistry, transitionOf } from './fixtures.js'
+import { applyHelper } from '../src/helpers/apply.js'
+import { changesHelper } from '../src/helpers/changes.js'
 
 type Node = Record<string, unknown>
 
@@ -53,15 +53,15 @@ describe('schemas', () => {
     exported.forEach(([, schema]) => ajv.compile(schema as object))
 
     const registry = makeRegistry()
-    const { changes } = computeChanges(undefined, {
+    const { changes } = changesHelper.computeChanges(undefined, {
       action: TransitionAction.Create,
       card: { kind: WorkcardKind.Card, type: STORY_TYPE.type, title: 'Story', fields: { area: 'user', primary: true } },
     }, STORY_TYPE, registry, AT)
-    const card = applyTransition(undefined, transitionOf({ card: 'c1', seq: 1, action: TransitionAction.Create, changes }))!
+    const card = applyHelper.applyTransition(undefined, transitionOf({ card: 'c1', seq: 1, action: TransitionAction.Create, changes }))!
 
-    expect(() => validateCard(card, registry)).not.toThrow()
-    expect(() => validateCard({ ...card, fields: { area: 'moon', primary: true } }, registry)).toThrow(FieldsInvalid)
-    expect(() => validateCard({ ...card, fields: { 'a.b': 1 } }, registry)).toThrow('keys:a.b')
+    expect(() => validateHelper.validateCard(card, registry)).not.toThrow()
+    expect(() => validateHelper.validateCard({ ...card, fields: { area: 'moon', primary: true } }, registry)).toThrow(FieldsInvalid)
+    expect(() => validateHelper.validateCard({ ...card, fields: { 'a.b': 1 } }, registry)).toThrow('keys:a.b')
   })
 
   test('an execute request accepts a card id or a create draft, and refuses an unknown action', () => {