@owlmeans/planning 0.1.18-rc.0

package/tests/apply.spec.ts

@@ -0,0 +1,176 @@
+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 {
+  AT, ENTITY, LATER, PROJECT_TYPE, SPEC_TYPE, STORY_TYPE, TASK_TYPE, makeRegistry, transitionOf,
+} from './fixtures.js'
+
+const registry = makeRegistry()
+
+const created = (): Workcard => {
+  const { changes } = computeChanges(undefined, {
+    action: TransitionAction.Create,
+    card: {
+      kind: WorkcardKind.Card, type: STORY_TYPE.type, parent: 'p1', title: 'As a user I sign in',
+      fields: { area: 'user', primary: false }, code: 'US-ABCDE',
+    },
+  }, STORY_TYPE, registry, AT)
+
+  return applyTransition(undefined, transitionOf({ card: 'c1', seq: 1, action: TransitionAction.Create, changes }))!
+}
+
+describe('applyTransition — the fold', () => {
+  test('create builds the whole record from the changes and the transition identity', () => {
+    const card = created()
+
+    expect(card).toEqual({
+      id: 'c1', kind: WorkcardKind.Card, type: STORY_TYPE.type, entityId: ENTITY,
+      title: 'As a user I sign in', code: 'US-ABCDE', parent: 'p1', parents: ['p1'], labels: [],
+      fields: { area: 'user', primary: false }, flows: { 'test:story': 'planned' },
+      status: 'planned', intrinsic: IntrinsicStatus.Planned,
+      seq: 1, head: 1, createdAt: AT, updatedAt: AT,
+    })
+  })
+
+  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({
+      card: 'c1', seq: 2, action: TransitionAction.Update, at: LATER,
+      changes: { title: 'Renamed', fields: { warning: 'x' }, labels: ['ui'] },
+      unset: ['code', 'fields.primary'],
+    }))!
+
+    expect(card).toEqual(before)
+    expect(next.title).toBe('Renamed')
+    expect(next.fields).toEqual({ area: 'user', warning: 'x' })
+    expect(next.labels).toEqual(['ui'])
+    expect(next.code).toBeUndefined()
+    expect([next.seq, next.head, next.updatedAt, next.createdAt]).toEqual([2, 2, LATER, AT])
+  })
+
+  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 })))
+      .toThrow(PlanningError)
+    expect(() => 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 })))
+      .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()
+
+    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}' } },
+      SPEC_TYPE, registry, LATER, { slot: STORY_TYPE.specifications[0] })
+    const revised = 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])
+  })
+})
+
+describe('applyRelationship', () => {
+  test('a create folds its links, from the card unless a draft names another end', () => {
+    const links = applyRelationship([], transitionOf({
+      id: 't1', card: 'c2', seq: 1, action: TransitionAction.Create, project: 'p1',
+      links: [{ type: 'follows', to: 'c1' }, { type: 'follows', from: 'c0', to: 'c2' }],
+    }))
+
+    expect(links).toEqual([
+      { entityId: ENTITY, type: 'follows', from: 'c2', to: 'c1', project: 'p1', createdAt: AT, transition: 't1' },
+      { entityId: ENTITY, type: 'follows', from: 'c0', to: 'c2', project: 'p1', createdAt: AT, transition: 't1' },
+    ])
+  })
+
+  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' } })
+
+    expect(twice).toHaveLength(1)
+    expect(applyRelationship(other, { ...link, action: TransitionAction.Unlink }).map(edge => edge.type))
+      .toEqual(['blocks'])
+  })
+
+  test('a delete removes every edge touching the card and keeps the rest', () => {
+    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 })))
+      .toEqual([edge('c3', 'c4')])
+  })
+})
+
+describe('computeChanges', () => {
+  test('an update records only what differs, and one that changes nothing is empty', () => {
+    const card = created()
+    const set = 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, {
+      card: 'c1', action: TransitionAction.Update, changes: { title: card.title, code: null as never },
+    }, STORY_TYPE, registry, LATER))).toBe(false)
+    expect(isEmptyChange(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)
+
+    expect(completed).toEqual({
+      changes: { flows: { 'test:story': 'completed' }, status: 'completed', intrinsic: IntrinsicStatus.Closed, closedAt: LATER },
+      unset: [], flow: 'test:story', from: 'in-progress', to: 'completed',
+    })
+
+    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)
+      .toEqual(['closedAt'])
+    expect(() => 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' },
+      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, {
+      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] })
+
+    expect(changes).toMatchObject({ category: 'scaffold', format: 'json', body: '{}', bodyChars: 2, revision: 1, parents: ['p1'] })
+  })
+})
+
+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))
+      .toThrow('immutable:status')
+    expect(() => 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))
+      .toThrow('immutable:title')
+    expect(() => assertMutable({ card: 'c1', action: TransitionAction.Update, changes: { code: 'free' } }, TASK_TYPE))
+      .not.toThrow()
+  })
+})

package/tests/code.spec.ts

@@ -0,0 +1,40 @@
+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'
+
+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)
+
+    expect(code).toMatch(/^US-[1-9A-Z]{5}$/)
+  })
+
+  test('slug: derived from the seed, then suffixed while taken', async () => {
+    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]+$/)
+  })
+
+  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')
+  })
+
+  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)
+    expect(asked).toBe(3)
+    expect(codeScopeOf(STORY_TYPE.code!, { parent: 'p1' })).toEqual({ parent: 'p1' })
+  })
+})

package/tests/entrypoints.spec.ts

@@ -0,0 +1,57 @@
+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'
+
+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 declared = protocols(tree as never).map(protocol => protocol.alias)
+
+    expect(new Set(declared).size).toBe(declared.length)
+    expect(declared.sort()).toEqual([
+      aliases.base, aliases.schema.list, aliases.card.list, aliases.card.summary, aliases.card.get,
+      aliases.card.transitions, aliases.card.specifications, aliases.spec.get, aliases.spec.revisions,
+      aliases.link.list, aliases.transition.get, aliases.execute, aliases.commit.get, aliases.commit.events,
+    ].sort())
+    expect(declared.every(alias => alias.startsWith(`${BASE}`))).toBe(true)
+  })
+
+  test('the guard, gate, parent and service sit on the base alone; leaves hang under it', () => {
+    const gate = { alias: 'gate:owner', params: ['vib-project-{entity}'] }
+    const tree = makePlanningProtocols({
+      base: { alias: BASE, parent: 'app:api', service: 'api' }, guards: ['guard:default'], gate,
+    })
+
+    expect(tree.base.guards).toEqual(['guard:default'])
+    expect(tree.base.gate).toEqual(gate)
+    expect(tree.base.route.route).toMatchObject({ path: PLANNING_PATH, parent: 'app:api', service: 'api' })
+    expect(tree.card.get.guards).toEqual([])
+    expect(tree.card.get.route.route.parent).toBe(BASE)
+    expect(tree.execute.route.route.method).toBe(RouteMethod.POST)
+    expect(tree.card.list.route.route.method).toBe(RouteMethod.GET)
+  })
+
+  test('static /cards/summary is declared before parametric /cards/:id', () => {
+    const tree = makePlanningProtocols({ base: { alias: BASE }, guards: 'guard:default' })
+    const order = Object.keys(tree.card)
+
+    expect(tree.card.summary.route.route.path).toBe('/cards/summary')
+    expect(tree.card.get.route.route.path).toBe('/cards/:id')
+    expect(order.indexOf('summary')).toBeLessThan(order.indexOf('get'))
+    expect(tree.card.list.contract?.requestSchemas.query).toBeDefined()
+  })
+
+  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' })
+
+    expect(own.commit.events.route.route).toMatchObject({ protocol: RouteProtocols.SOCKET, parent: BASE, path: '/commits' })
+    expect(shared.commit.events.route.route.parent).toBe('app:update')
+    expect(Object.isFrozen(shared) && Object.isFrozen(shared.commit.events)).toBe(true)
+  })
+})

package/tests/fixtures.ts

@@ -0,0 +1,124 @@
+import {
+  CodeScope, CodeStyle, CommitState, IntrinsicPolicy, IntrinsicStatus, SpecificationFormat,
+  TransitionAction, WorkcardKind,
+} from '../src/consts.js'
+import { makeSchemaRegistry } from '../src/registry.js'
+import type {
+  PlanningSchemaRegistry, ProjectTypeSchema, StatusFlowSchema, Transition, WorkcardTypeSchema,
+} from '../src/types.js'
+
+export const ENTITY = 'entity-1'
+export const AT = '2026-09-16T10:00:00.000Z'
+export const LATER = '2026-09-16T11:00:00.000Z'
+
+/** The story shape: `start` declared twice (from planned, from failed), `reset` from anywhere. */
+export const STORY_FLOW: StatusFlowSchema = {
+  id: 'test:story',
+  version: 1,
+  statuses: [
+    { key: 'planned', intrinsic: IntrinsicStatus.Planned, initial: true },
+    { key: 'in-progress', intrinsic: IntrinsicStatus.InProgress },
+    { key: 'completed', intrinsic: IntrinsicStatus.Closed, terminal: true },
+    { key: 'failed', intrinsic: IntrinsicStatus.Planned },
+  ],
+  transitions: [
+    { name: 'start', from: ['planned'], to: 'in-progress', explicit: true },
+    { name: 'complete', from: ['in-progress'], to: 'completed' },
+    { name: 'fail', from: ['in-progress'], to: 'failed' },
+    { name: 'reset', from: '*', to: 'planned', explicit: true },
+    { name: 'start', from: ['failed'], to: 'in-progress', explicit: true },
+  ],
+}
+
+/** A second flow: its `reopen` wildcard is declared BEFORE the specific rule it must lose to. */
+export const REVIEW_FLOW: StatusFlowSchema = {
+  id: 'test:review',
+  version: 1,
+  statuses: [
+    { key: 'pending', intrinsic: IntrinsicStatus.Planned, initial: true },
+    { key: 'reviewing', intrinsic: IntrinsicStatus.InProgress },
+    { key: 'approved', intrinsic: IntrinsicStatus.Closed },
+  ],
+  transitions: [
+    { name: 'review', from: ['pending'], to: 'reviewing' },
+    { name: 'approve', from: ['reviewing'], to: 'approved' },
+    { name: 'reopen', from: '*', to: 'pending' },
+    { name: 'reopen', from: ['approved'], to: 'reviewing' },
+  ],
+}
+
+export const STORY_TYPE: WorkcardTypeSchema = {
+  type: 'test:story',
+  kind: WorkcardKind.Card,
+  version: 1,
+  fields: {
+    type: 'object',
+    properties: {
+      area: { type: 'string', enum: ['guest', 'user'] },
+      primary: { type: 'boolean' },
+      warning: { type: 'string', nullable: true },
+    },
+    required: ['area', 'primary'],
+    additionalProperties: false,
+  },
+  flows: [STORY_FLOW.id],
+  specifications: [
+    { category: 'design', format: SpecificationFormat.Json, revisioned: true, keepRevisions: 3 },
+  ],
+  relationships: [{ name: 'follows', single: true }],
+  labels: ['ui', 'api'],
+  code: { prefix: 'US-', style: CodeStyle.Random, length: 5, uppercase: true, uniqueWithin: CodeScope.Parent },
+}
+
+/** Runs both flows; closed only when both are. */
+export const TASK_TYPE: WorkcardTypeSchema = {
+  type: 'test:task',
+  kind: WorkcardKind.Card,
+  version: 1,
+  fields: { type: 'object', additionalProperties: true },
+  flows: [STORY_FLOW.id, REVIEW_FLOW.id],
+  intrinsic: IntrinsicPolicy.All,
+  specifications: [],
+}
+
+export const PROJECT_TYPE: ProjectTypeSchema = {
+  type: 'test:project',
+  kind: WorkcardKind.Project,
+  version: 1,
+  fields: { type: 'object', additionalProperties: true },
+  flows: [STORY_FLOW.id],
+  specifications: [
+    { category: 'specification', format: SpecificationFormat.Markdown, required: true },
+    { category: 'scaffold', format: SpecificationFormat.Json, revisioned: true, keepRevisions: 3 },
+  ],
+  cardTypes: [STORY_TYPE.type, TASK_TYPE.type],
+  code: { style: CodeStyle.Slug, uniqueWithin: CodeScope.Entity },
+}
+
+export const SPEC_TYPE: WorkcardTypeSchema = {
+  type: 'test:spec',
+  kind: WorkcardKind.Specification,
+  version: 1,
+  fields: { type: 'object', additionalProperties: true },
+  flows: [STORY_FLOW.id],
+  specifications: [],
+}
+
+export const makeRegistry = (): PlanningSchemaRegistry => makeSchemaRegistry({
+  flows: [STORY_FLOW, REVIEW_FLOW],
+  types: [STORY_TYPE, TASK_TYPE, PROJECT_TYPE, SPEC_TYPE],
+})
+
+/** A transition with everything a fold does not care about filled in. */
+export const transitionOf = (partial: Partial<Transition> & Pick<Transition, 'card' | 'seq' | 'action'>): Transition => ({
+  entityId: ENTITY,
+  kind: WorkcardKind.Card,
+  type: STORY_TYPE.type,
+  changes: {},
+  actor: {},
+  at: AT,
+  commit: { state: CommitState.Pending },
+  ...partial,
+})
+
+export { TransitionAction }

package/tests/i18n.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from 'bun:test'
+import { SUPPORTED_LNGS } from '@owlmeans/i18n'
+import * as errors from '../src/errors.js'
+
+const keysOf = (node: unknown, prefix: string = ''): string[] => node != null && typeof node === 'object'
+  ? Object.entries(node).flatMap(([key, value]) => keysOf(value, `${prefix}${key}.`))
+  : [prefix.slice(0, -1)]
+
+const load = async (lng: string): Promise<unknown> =>
+  (await import(`../src/i18n/${lng}.json`, { with: { type: 'json' } })).default
+
+describe('i18n', () => {
+  test('all seven languages carry exactly the same keys, none empty', async () => {
+    const english = keysOf(await load('en')).sort()
+
+    expect(SUPPORTED_LNGS).toHaveLength(7)
+    for (const lng of SUPPORTED_LNGS) {
+      const data = await load(lng)
+      expect(keysOf(data).sort()).toEqual(english)
+      expect(JSON.stringify(data)).not.toContain('""')
+    }
+  })
+
+  test('every registered refusal class has an error text', async () => {
+    const texts = (await load('en') as { errors: Record<string, string> }).errors
+    const types = Object.values(errors).map(errorClass => (errorClass as { typeName: string }).typeName)
+
+    expect(types.filter(type => texts[type] == null)).toEqual([])
+  })
+})

package/tests/models.spec.ts

@@ -0,0 +1,133 @@
+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 {
+  PlanningFacade, Project, Specification, TransitionExecution, Workcard, WorkcardDraft,
+} from '../src/types.js'
+import { AT, ENTITY, PROJECT_TYPE, STORY_TYPE, makeRegistry } from './fixtures.js'
+
+/**
+ * The smallest facade the models can run against: maps, folded synchronously with the package's
+ * own helpers. It records every execution so a spec can read what a model sent.
+ */
+const makeFacade = () => {
+  const schemas = makeRegistry()
+  const cards = new Map<string, Workcard>()
+  const executed: TransitionExecution[] = []
+  let next = 0
+
+  const facade: PlanningFacade = {
+    scope: { entityId: ENTITY },
+    schemas,
+    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,
+      summary: async (parents, query) =>
+        summaryOf(applyQuery([...cards.values()], 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,
+      get: async id => cards.get(id) as Specification,
+      revisions: async () => [],
+    },
+    relationships: { list: async () => ({ items: [], total: 0 }) },
+    transitions: { get: async id => Promise.reject(new WorkcardNotFound(id)), list: async () => ({ items: [], total: 0 }) },
+    commits: {
+      status: async transition => ({ transition, state: CommitState.Committed }),
+      subscribe: () => () => undefined,
+      wait: async () => null,
+    },
+    execute: async exec => {
+      executed.push(exec)
+      const card = typeof exec.card === 'string' ? cards.get(exec.card) : undefined
+      const draft = typeof exec.card === 'string' ? undefined : exec.card as WorkcardDraft
+      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 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)) {
+        return { transition, card, committed: async () => card ?? null }
+      }
+      const folded = applyTransition(card, transition)
+      folded == null ? cards.delete(id) : cards.set(id, folded)
+      return { transition, card: folded, committed: async () => folded }
+    },
+    model: async card => modelOf(typeof card === 'string' ? await facade.cards.get(card) as never : card, facade),
+  }
+
+  const seed = async (draft: WorkcardDraft): Promise<Workcard> =>
+    (await facade.execute({ action: TransitionAction.Create, card: draft })).card!
+
+  return { facade, executed, cards, seed }
+}
+
+describe('workcard model', () => {
+  test('expectSeq defaults to the head, then the seq; null opts out and a given value wins', async () => {
+    const { facade, executed, seed } = makeFacade()
+    const card = await seed({ kind: WorkcardKind.Card, type: STORY_TYPE.type, title: 'Story', fields: { area: 'user', primary: false } })
+
+    await makeWorkcardModel({ ...card, head: 4 }, facade).update({ title: 'A' })
+    await makeWorkcardModel(card, facade).transit('start')
+    await makeWorkcardModel(card, facade).link('follows', 'x', undefined, { expectSeq: 9 })
+    await makeWorkcardModel(card, facade).remove({ expectSeq: null })
+
+    expect(executed.slice(1).map(exec => exec.expectSeq)).toEqual([4, 1, 9, null])
+    expect(executed[2]).toMatchObject({ card: card.id, action: TransitionAction.Transit, transition: 'start' })
+  })
+
+  test('can and available answer from the registry with no I/O', async () => {
+    const { facade, seed } = makeFacade()
+    const model = makeWorkcardModel(await seed({ kind: WorkcardKind.Card, type: STORY_TYPE.type, title: 'Story', fields: { area: 'user', primary: false } }), facade)
+
+    expect(model.can('start')).toBe(true)
+    expect(model.can('complete')).toBe(false)
+    expect(model.available().map(rule => rule.name)).toEqual(['start', 'reset'])
+    expect(model.pending()).toBe(false)
+  })
+})
+
+describe('write', () => {
+  test('creates the slot\'s document when empty and revises the same record when filled', async () => {
+    const { facade, executed, cards, seed } = makeFacade()
+    const project = await seed({ kind: WorkcardKind.Project, type: PROJECT_TYPE.type, title: 'Shop' })
+    const model = makeProjectModel(project as Project, facade)
+
+    // The spec type is resolved from the registry: the only specification type registered.
+    const first = await model.write('scaffold', '{"a":1}')
+    const second = await model.write('scaffold', '{"a":2}')
+    const specs = [...cards.values()].filter(card => card.kind === WorkcardKind.Specification) as Specification[]
+
+    expect(executed.slice(1).map(exec => exec.action)).toEqual([TransitionAction.Create, TransitionAction.Update])
+    expect(executed[1].card).toMatchObject({ kind: WorkcardKind.Specification, type: 'test:spec', parent: project.id, category: 'scaffold', format: 'json' })
+    expect(executed[2]).toMatchObject({ card: first.card!.id, expectSeq: 1, changes: { body: '{"a":2}' } })
+    expect(specs.map(spec => [spec.revision, spec.body])).toEqual([[2, '{"a":2}']])
+    expect(second.card!.id).toBe(first.card!.id)
+  })
+
+  test('a project model summarises its direct cards', async () => {
+    const { facade, seed } = makeFacade()
+    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>
+
+    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

@@ -0,0 +1,90 @@
+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'
+
+const card = (id: string, extra: Partial<Workcard>): Workcard => ({
+  id, kind: WorkcardKind.Card, type: 'test:story', entityId: ENTITY, title: `Card ${id}`, parent: 'p1',
+  parents: ['p1'], status: 'planned', intrinsic: IntrinsicStatus.Planned, flows: { 'test:story': 'planned' },
+  labels: [], fields: {}, seq: 1, createdAt: AT, ...extra,
+})
+
+const CARDS = [
+  card('a', { code: 'US-AAA', labels: ['ui'], fields: { area: 'user' }, order: 2 }),
+  card('b', { code: 'US-BBB', status: 'completed', intrinsic: IntrinsicStatus.Closed, parents: ['p1', 'p2'], order: 1 }),
+  card('c', { entityId: 'other', code: 'US-CCC' }),
+  card('d', { title: '50% off_sale', parent: 'p2', parents: ['p2'], fields: { area: 'guest' } }),
+]
+
+const ids = (query: WorkcardQuery): string[] =>
+  applyQuery(CARDS, criteriaOf(query, { entityId: ENTITY }), 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({
+      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,
+    }, { entityId: ENTITY }) as Record<string, unknown>).toEqual({
+      entityId: ENTITY, kind: WorkcardKind.Card, type: ['test:story', 'test:task'], parent: 'p1',
+      parents: { $contains: 'p2' }, labels: { $overlaps: ['ui'] }, id: { $in: ['a'] },
+      'flows.test:story': ['planned'], 'fields.area': 'user', code: 'US-AAA', updatedAt: { $gte: AT },
+    })
+  })
+
+  test('means the same thing to the in-memory engine: membership, labels, fields, code and sort', () => {
+    expect(ids({})).toEqual(['a', 'b', 'd'])
+    expect(ids({ within: 'p2', sort: ['order'] })).toEqual(['b', 'd'])
+    expect(ids({ labels: ['ui', 'api'] })).toEqual(['a'])
+    expect(ids({ fields: { area: 'guest' } })).toEqual(['d'])
+    expect(ids({ code: ['US-BBB', 'US-CCC'], intrinsic: IntrinsicStatus.Closed })).toEqual(['b'])
+  })
+
+  test('a search matches title text literally and a code prefix', () => {
+    expect(ids({ q: '50%' })).toEqual(['d'])
+    expect(ids({ q: '%' })).toEqual(['d'])
+    expect(ids({ q: 'US-A' })).toEqual(['a'])
+  })
+})
+
+describe('wire queries', () => {
+  test('a rich query survives encode → decode into the same criteria', () => {
+    const query: WorkcardQuery = {
+      kind: WorkcardKind.Card, type: ['test:story', 'test:task'], parent: 'p1', labels: ['a,b', 'c'], ids: ['x'],
+      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)
+
+    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' }] })
+  })
+
+  test('decode accepts what a transport may have split already, and coerces numbers', () => {
+    expect(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' })))
+      .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')
+  })
+})
+
+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({
+      p1: { total: 2, planned: 1, 'in-progress': 0, closed: 1 },
+    })
+  })
+})