@owlmeans/planning 0.1.18-rc.9 → 0.1.18

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 { PlanningUnsupported, WorkcardNotFound } from '../src/errors.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
@@ -21,21 +22,28 @@ const makeFacade = () => {
   const cards = new Map<string, Workcard>()
   const executed: TransitionExecution[] = []
   let next = 0
+  const unsupported = async (): Promise<never> => { throw new PlanningUnsupported('model-fixture:resources') }
 
   const facade: PlanningFacade = {
+    assignees: { get: unsupported, load: unsupported, list: unsupported, create: unsupported, update: unsupported, retire: unsupported },
+    teams: { get: unsupported, load: unsupported, list: unsupported, create: unsupported, update: unsupported, remove: unsupported,
+      members: unsupported, addMember: unsupported, removeMember: unsupported, projects: unsupported,
+      attach: unsupported, detach: unsupported, assignees: unsupported },
+    comments: { get: unsupported, load: unsupported, list: unsupported, create: unsupported, update: unsupported, remove: unsupported },
+    mentions: { get: unsupported, load: unsupported, list: unsupported, rebuild: unsupported },
     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,
+      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 +61,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 +133,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', () => {

package/tests/scoped.spec.ts

@@ -0,0 +1,161 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  IntrinsicStatus, PlanningSchemaKind, SchemaOrigin, WorkcardKind,
+} from '../src/consts.js'
+import { PlanningUnsupported, SchemaInvalid, SchemaSealed } from '../src/errors.js'
+import { makeSchemaRegistry } from '../src/registry.js'
+import type {
+  ProjectTypeSchema, ScopedSchemaRecord, StatusFlowSchema, WorkcardTypeSchema,
+} from '../src/types.js'
+import { scopedSchemaHelper } from '../src/helpers/scoped.js'
+
+/** A community garden: plots are tended through a season flow; a shared tool shed is sealed. */
+const SEASON: StatusFlowSchema = {
+  id: 'garden:season',
+  version: 1,
+  overridable: true,
+  statuses: [
+    { key: 'fallow', intrinsic: IntrinsicStatus.Planned, initial: true },
+    { key: 'growing', intrinsic: IntrinsicStatus.InProgress },
+    { key: 'harvested', intrinsic: IntrinsicStatus.Closed },
+  ],
+  transitions: [
+    { name: 'sow', from: ['fallow'], to: 'growing' },
+    { name: 'harvest', from: ['growing'], to: 'harvested' },
+  ],
+}
+
+const ROTA: StatusFlowSchema = {
+  id: 'garden:rota',
+  version: 1,
+  statuses: [{ key: 'open', intrinsic: IntrinsicStatus.Planned, initial: true }],
+  transitions: [],
+}
+
+const PLOT: WorkcardTypeSchema = {
+  type: 'garden:plot', kind: WorkcardKind.Card, version: 1, overridable: true,
+  fields: { type: 'object' }, flows: [SEASON.id], specifications: [],
+}
+
+const SHED: WorkcardTypeSchema = {
+  type: 'garden:shed', kind: WorkcardKind.Card, version: 1,
+  fields: { type: 'object' }, flows: [ROTA.id], specifications: [],
+}
+
+const GARDEN: ProjectTypeSchema = {
+  type: 'garden:site', kind: WorkcardKind.Project, version: 1, fields: { type: 'object' },
+  flows: [ROTA.id], specifications: [], cardTypes: [PLOT.type], scopedCardTypes: true,
+}
+
+const code = makeSchemaRegistry({ flows: [SEASON, ROTA], types: [PLOT, SHED, GARDEN] })
+
+const record = (patch: Partial<ScopedSchemaRecord> & Pick<ScopedSchemaRecord, 'kind' | 'key' | 'definition'>): ScopedSchemaRecord => ({
+  entityId: 'org-1', version: 1, createdAt: '2026-09-01T00:00:00.000Z', ...patch,
+})
+
+const BED: WorkcardTypeSchema = {
+  type: 'garden:bed', kind: WorkcardKind.Card, version: 1, fields: { type: 'object' }, flows: [SEASON.id], specifications: [],
+}
+
+describe('scoped schemas — layering', () => {
+  test('an organization record adds a type, a project record overrides it for that project only', () => {
+    const records = [
+      record({ kind: PlanningSchemaKind.Type, key: BED.type, definition: BED }),
+      record({ kind: PlanningSchemaKind.Type, key: BED.type, project: 'site-1', version: 3, definition: { ...BED, label: 'Raised bed' } }),
+    ]
+
+    const shared = scopedSchemaHelper.scopedRegistryOf(scopedSchemaHelper.resolveScopedBundle(code.bundle(), records, { entityId: 'org-1', revision: 2 }))
+    const site = scopedSchemaHelper.scopedRegistryOf(scopedSchemaHelper.resolveScopedBundle(code.bundle(), records, { entityId: 'org-1', project: 'site-1' }))
+    const other = scopedSchemaHelper.scopedRegistryOf(scopedSchemaHelper.resolveScopedBundle(code.bundle(), records, { entityId: 'org-2' }))
+
+    expect(shared.type(BED.type).label).toBeUndefined()
+    expect(shared.originOf(PlanningSchemaKind.Type, BED.type)).toBe(SchemaOrigin.Entity)
+    expect(shared.revision).toBe(2)
+    expect(site.type(BED.type)).toMatchObject({ label: 'Raised bed', version: 3 })
+    expect(site.originOf(PlanningSchemaKind.Type, BED.type)).toBe(SchemaOrigin.Project)
+    expect(site.originOf(PlanningSchemaKind.Type, PLOT.type)).toBe(SchemaOrigin.Code)
+    expect(other.has(BED.type)).toBe(false)
+  })
+
+  test('a sealed code key ignores a record; an overridable one takes it', () => {
+    const records = [
+      record({ kind: PlanningSchemaKind.Type, key: SHED.type, definition: { ...SHED, label: 'Hijacked' } }),
+      record({ kind: PlanningSchemaKind.Type, key: PLOT.type, definition: { ...PLOT, label: 'Allotment' } }),
+      record({ kind: PlanningSchemaKind.Type, key: GARDEN.type, definition: { ...BED, type: GARDEN.type } }),
+    ]
+    const view = scopedSchemaHelper.scopedRegistryOf(scopedSchemaHelper.resolveScopedBundle(code.bundle(), records, { entityId: 'org-1' }))
+
+    expect(view.type(SHED.type).label).toBeUndefined()
+    expect(view.type(PLOT.type).label).toBe('Allotment')
+    expect(view.type(GARDEN.type).kind).toBe(WorkcardKind.Project)
+    expect(() => scopedSchemaHelper.assertOverridable(code, PlanningSchemaKind.Type, SHED.type)).toThrow(SchemaSealed)
+    expect(() => scopedSchemaHelper.assertOverridable(code, PlanningSchemaKind.Type, GARDEN.type)).toThrow(SchemaSealed)
+    expect(() => scopedSchemaHelper.assertOverridable(code, PlanningSchemaKind.Flow, ROTA.id)).toThrow(SchemaSealed)
+    expect(() => scopedSchemaHelper.assertOverridable(code, PlanningSchemaKind.Flow, SEASON.id)).not.toThrow()
+  })
+
+  test('a retired record gives way to a live one below it, and resolves retired when none is left', () => {
+    const records = [
+      record({ kind: PlanningSchemaKind.Type, key: PLOT.type, retired: true, definition: { ...PLOT, label: 'Old' } }),
+      record({ kind: PlanningSchemaKind.Type, key: BED.type, retired: true, definition: BED }),
+    ]
+    const view = scopedSchemaHelper.scopedRegistryOf(scopedSchemaHelper.resolveScopedBundle(code.bundle(), records, { entityId: 'org-1' }))
+
+    expect(view.type(PLOT.type).label).toBeUndefined()
+    expect(view.isRetired(PlanningSchemaKind.Type, PLOT.type)).toBe(false)
+    expect(view.type(BED.type).type).toBe(BED.type)
+    expect(view.isRetired(PlanningSchemaKind.Type, BED.type)).toBe(true)
+    expect(view.bundle().retired).toEqual({ types: [BED.type], flows: [] })
+  })
+
+  test('the view is read-only', () => {
+    const view = scopedSchemaHelper.scopedRegistryOf(scopedSchemaHelper.resolveScopedBundle(code.bundle(), [], { entityId: 'org-1' }))
+
+    expect(() => view.registerType(BED)).toThrow(PlanningUnsupported)
+    expect(() => view.load(code.bundle())).toThrow(PlanningUnsupported)
+    expect(view.primaryFlow(PLOT.type).id).toBe(SEASON.id)
+  })
+
+  test('a flow retired with no live fallback is in use while a live type runs it', () => {
+    const flow: StatusFlowSchema = { ...ROTA, id: 'garden:watering' }
+    const using: WorkcardTypeSchema = { ...BED, type: 'garden:hose', flows: [flow.id] }
+    const retiredFlow = record({ kind: PlanningSchemaKind.Flow, key: flow.id, retired: true, definition: flow })
+    const live = scopedSchemaHelper.resolveScopedBundle(code.bundle(), [
+      retiredFlow, record({ kind: PlanningSchemaKind.Type, key: using.type, definition: using }),
+    ], { entityId: 'org-1' })
+    const idle = scopedSchemaHelper.resolveScopedBundle(code.bundle(), [
+      retiredFlow, record({ kind: PlanningSchemaKind.Type, key: using.type, retired: true, definition: using }),
+    ], { entityId: 'org-1' })
+
+    expect(scopedSchemaHelper.flowInUse(live, flow.id)).toBe(using.type)
+    expect(scopedSchemaHelper.flowInUse(idle, flow.id)).toBeUndefined()
+  })
+})
+
+describe('scoped schemas — closed-form checks', () => {
+  test('a flow needs unique statuses, declared targets and a from that is * or declared', () => {
+    expect(() => scopedSchemaHelper.assertFlowSchema(SEASON)).not.toThrow()
+    expect(() => scopedSchemaHelper.assertFlowSchema({ ...SEASON, statuses: [...SEASON.statuses, SEASON.statuses[0]] }))
+      .toThrow('status-repeated:fallow')
+    expect(() => scopedSchemaHelper.assertFlowSchema({ ...SEASON, transitions: [{ name: 'compost', from: '*', to: 'compost' }] }))
+      .toThrow('compost:to:compost')
+    expect(() => scopedSchemaHelper.assertFlowSchema({ ...SEASON, transitions: [{ name: 'sow', from: ['frozen'], to: 'growing' }] }))
+      .toThrow('sow:from:frozen')
+    expect(() => scopedSchemaHelper.assertFlowSchema({ ...SEASON, statuses: [] })).toThrow(SchemaInvalid)
+  })
+
+  test('a type must be a card with a compiling fields schema and unique flows that resolve', () => {
+    expect(() => scopedSchemaHelper.assertTypeSchema(BED, code)).not.toThrow()
+    expect(() => scopedSchemaHelper.assertTypeSchema({ ...BED, kind: WorkcardKind.Specification }, code)).toThrow('kind:specification')
+    expect(() => scopedSchemaHelper.assertTypeSchema({ ...BED, fields: { type: 'nonsense' } }, code)).toThrow('fields:')
+    expect(() => scopedSchemaHelper.assertTypeSchema({ ...BED, flows: [SEASON.id, SEASON.id] }, code)).toThrow('flow-repeated')
+    expect(() => scopedSchemaHelper.assertTypeSchema({ ...BED, flows: ['garden:frost'] }, code)).toThrow('flow:garden:frost')
+  })
+
+  test('a type and a flow may carry a tone and an icon as presentation hints; other keys stay refused', () => {
+    expect(() => scopedSchemaHelper.assertTypeSchema({ ...BED, tone: 'green', icon: 'sprout' }, code)).not.toThrow()
+    expect(() => scopedSchemaHelper.assertFlowSchema({ ...SEASON, tone: 'amber', icon: 'sun' })).not.toThrow()
+    expect(() => scopedSchemaHelper.assertTypeSchema({ ...BED, colour: 'green' } as WorkcardTypeSchema, code)).toThrow(SchemaInvalid)
+    expect(() => scopedSchemaHelper.assertFlowSchema({ ...SEASON, tone: 'x'.repeat(65) })).toThrow(SchemaInvalid)
+  })
+})

package/tests/status.spec.ts

@@ -1,55 +1,64 @@
 import { describe, expect, test } from 'bun:test'
 import { IntrinsicStatus } from '../src/consts.js'
 import { UnknownStatusFlow, UnknownWorkcardType } from '../src/errors.js'
-import {
-  canTransit, initialFlowsOf, initialStatusOf, intrinsicOf, resolveIntrinsic, ruleOf, transitionsFrom,
-} from '../src/helpers/status.js'
 import { PROJECT_TYPE, REVIEW_FLOW, STORY_FLOW, STORY_TYPE, TASK_TYPE, makeRegistry } from './fixtures.js'
+import { statusHelper } from '../src/helpers/status.js'
 
 const registry = makeRegistry()
 
 describe('status flows', () => {
   test('every status maps onto its intrinsic state; the initial one is the marked one', () => {
-    expect(intrinsicOf(STORY_FLOW, 'failed')).toBe(IntrinsicStatus.Planned)
-    expect(intrinsicOf(STORY_FLOW, 'completed')).toBe(IntrinsicStatus.Closed)
-    expect(intrinsicOf(STORY_FLOW, 'unknown')).toBeUndefined()
-    expect(initialStatusOf(REVIEW_FLOW)).toBe('pending')
+    expect(statusHelper.intrinsicOf(STORY_FLOW, 'failed')).toBe(IntrinsicStatus.Planned)
+    expect(statusHelper.intrinsicOf(STORY_FLOW, 'completed')).toBe(IntrinsicStatus.Closed)
+    expect(statusHelper.intrinsicOf(STORY_FLOW, 'unknown')).toBeUndefined()
+    expect(statusHelper.initialStatusOf(REVIEW_FLOW)).toBe('pending')
   })
 
   test('a repeated name picks the rule whose from matches, and a wildcard answers last', () => {
-    expect(ruleOf(STORY_FLOW, 'start', 'failed')?.to).toBe('in-progress')
-    expect(ruleOf(STORY_FLOW, 'start', 'completed')).toBeUndefined()
-    expect(ruleOf(REVIEW_FLOW, 'reopen', 'approved')?.to).toBe('reviewing')
-    expect(ruleOf(REVIEW_FLOW, 'reopen', 'reviewing')?.to).toBe('pending')
+    expect(statusHelper.ruleOf(STORY_FLOW, 'start', 'failed')?.to).toBe('in-progress')
+    expect(statusHelper.ruleOf(STORY_FLOW, 'start', 'completed')).toBeUndefined()
+    expect(statusHelper.ruleOf(REVIEW_FLOW, 'reopen', 'approved')?.to).toBe('reviewing')
+    expect(statusHelper.ruleOf(REVIEW_FLOW, 'reopen', 'reviewing')?.to).toBe('pending')
+  })
+
+  test('a status the flow does not declare matches every rule of the name, the first declared answering', () => {
+    // A card whose flow changed under it: `abandoned` is no longer a status of the flow.
+    expect(statusHelper.ruleOf(STORY_FLOW, 'start', 'abandoned')?.to).toBe('in-progress')
+    expect(statusHelper.ruleOf(STORY_FLOW, 'complete', 'abandoned')?.to).toBe('completed')
+    expect(statusHelper.ruleOf(STORY_FLOW, 'reset', 'abandoned')?.to).toBe('planned')
+    expect(statusHelper.ruleOf(STORY_FLOW, 'nope', 'abandoned')).toBeUndefined()
+    // A declared status keeps its own rules only.
+    expect(statusHelper.ruleOf(STORY_FLOW, 'complete', 'planned')).toBeUndefined()
+    expect(statusHelper.transitionsFrom(STORY_FLOW, 'abandoned').map(rule => rule.name)).toEqual(['start', 'complete', 'fail', 'reset'])
   })
 
   test('canTransit and transitionsFrom read the same rules, one per name', () => {
-    expect(canTransit(STORY_FLOW, 'reset', 'planned')).toBe(true)
-    expect(canTransit(STORY_FLOW, 'complete', 'planned')).toBe(false)
-    expect(transitionsFrom(STORY_FLOW, 'in-progress').map(rule => rule.name)).toEqual(['complete', 'fail', 'reset'])
-    expect(transitionsFrom(STORY_FLOW, 'failed', { explicit: true }).map(rule => `${rule.name}→${rule.to}`))
+    expect(statusHelper.canTransit(STORY_FLOW, 'reset', 'planned')).toBe(true)
+    expect(statusHelper.canTransit(STORY_FLOW, 'complete', 'planned')).toBe(false)
+    expect(statusHelper.transitionsFrom(STORY_FLOW, 'in-progress').map(rule => rule.name)).toEqual(['complete', 'fail', 'reset'])
+    expect(statusHelper.transitionsFrom(STORY_FLOW, 'failed', { explicit: true }).map(rule => `${rule.name}→${rule.to}`))
       .toEqual(['start→in-progress', 'reset→planned'])
   })
 })
 
 describe('intrinsic resolution', () => {
   test('primary policy reads the primary flow only', () => {
-    expect(resolveIntrinsic(STORY_TYPE, { 'test:story': 'in-progress' }, registry)).toBe(IntrinsicStatus.InProgress)
-    expect(resolveIntrinsic(PROJECT_TYPE, { 'test:story': 'completed' }, registry)).toBe(IntrinsicStatus.Closed)
+    expect(statusHelper.resolveIntrinsic(STORY_TYPE, { 'test:story': 'in-progress' }, registry)).toBe(IntrinsicStatus.InProgress)
+    expect(statusHelper.resolveIntrinsic(PROJECT_TYPE, { 'test:story': 'completed' }, registry)).toBe(IntrinsicStatus.Closed)
   })
 
   test('IntrinsicPolicy.All takes the least advanced flow', () => {
-    expect(resolveIntrinsic(TASK_TYPE, { 'test:story': 'completed', 'test:review': 'reviewing' }, registry))
+    expect(statusHelper.resolveIntrinsic(TASK_TYPE, { 'test:story': 'completed', 'test:review': 'reviewing' }, registry))
       .toBe(IntrinsicStatus.InProgress)
-    expect(resolveIntrinsic(TASK_TYPE, { 'test:story': 'completed', 'test:review': 'approved' }, registry))
+    expect(statusHelper.resolveIntrinsic(TASK_TYPE, { 'test:story': 'completed', 'test:review': 'approved' }, registry))
       .toBe(IntrinsicStatus.Closed)
-    expect(resolveIntrinsic(TASK_TYPE, { 'test:story': 'failed', 'test:review': 'approved' }, registry))
+    expect(statusHelper.resolveIntrinsic(TASK_TYPE, { 'test:story': 'failed', 'test:review': 'approved' }, registry))
       .toBe(IntrinsicStatus.Planned)
   })
 
   test('initialFlowsOf starts every flow at its initial status, the primary at the draft status', () => {
-    expect(initialFlowsOf(TASK_TYPE, registry)).toEqual({ 'test:story': 'planned', 'test:review': 'pending' })
-    expect(initialFlowsOf(TASK_TYPE, registry, 'failed')).toEqual({ 'test:story': 'failed', 'test:review': 'pending' })
+    expect(statusHelper.initialFlowsOf(TASK_TYPE, registry)).toEqual({ 'test:story': 'planned', 'test:review': 'pending' })
+    expect(statusHelper.initialFlowsOf(TASK_TYPE, registry, 'failed')).toEqual({ 'test:story': 'failed', 'test:review': 'pending' })
   })
 })