@owlmeans/planning 0.1.18-rc.8 → 0.1.18

package/tests/app.spec.ts

@@ -0,0 +1,188 @@
+import { describe, expect, test } from 'bun:test'
+import { IntrinsicStatus, PlanningSchemaKind, PlanningUnsupported, SchemaInvalid, WorkcardKind } from '../src/index.js'
+import type { PlanningAppDeclarations, ProjectTypeSchema, ScopedSchemaRecord, StatusFlowSchema, WorkcardTypeSchema } from '../src/index.js'
+import { appSchemaHelper } from '../src/helpers/app.js'
+import { scopedSchemaHelper } from '../src/helpers/scoped.js'
+import { makeAjv, validateHelper } from '../src/helpers/validate.js'
+import { makeSchemaRegistry } from '../src/registry.js'
+import { PlanningSchemaBundleSchema, SchemaDefineRequestSchema } from '../src/schemas.js'
+
+/** A repair shop: the app gives every type and flow a description and every job card a priority. */
+const APP: PlanningAppDeclarations = {
+  type: { properties: { description: { type: 'string', maxLength: 200 } } },
+  flow: { type: 'object', properties: { description: { type: 'string' } }, required: ['description'] },
+  card: { properties: { priority: { type: 'string', enum: ['low', 'high'] } } },
+}
+
+const MEND: StatusFlowSchema = {
+  id: 'shop:mend', version: 1, overridable: true,
+  statuses: [{ key: 'queued', intrinsic: IntrinsicStatus.Planned, initial: true }, { key: 'done', intrinsic: IntrinsicStatus.Closed }],
+  transitions: [{ name: 'finish', from: ['queued'], to: 'done' }],
+}
+
+/** Closed fields, a local `$defs` reference — the shape a base field must not break. */
+const JOB: WorkcardTypeSchema = {
+  type: 'shop:job', kind: WorkcardKind.Card, version: 1, flows: [MEND.id], specifications: [],
+  fields: {
+    type: 'object',
+    properties: { cost: { $ref: '#/$defs/money' } },
+    additionalProperties: false,
+    $defs: { money: { type: 'number', minimum: 0 } },
+  },
+}
+
+const SHOP: ProjectTypeSchema = {
+  type: 'shop:site', kind: WorkcardKind.Project, version: 1, fields: { type: 'object', additionalProperties: false },
+  flows: [MEND.id], specifications: [], cardTypes: [JOB.type], scopedCardTypes: true,
+}
+
+describe('appSchemaHelper — declarations', () => {
+  test('merges in the order given: properties united, a later name replacing whole, required united', () => {
+    const merged = appSchemaHelper.merge([
+      undefined,
+      { card: { properties: { priority: { type: 'string' }, size: { type: 'number' } }, required: ['size'] } },
+      { card: { properties: { priority: { type: 'string', enum: ['low'] } }, required: ['priority'] }, type: { properties: {} } },
+    ])
+    expect(merged).toEqual({
+      card: {
+        type: 'object',
+        properties: { priority: { type: 'string', enum: ['low'] }, size: { type: 'number' } },
+        required: ['size', 'priority'],
+      },
+      type: { type: 'object', properties: {} },
+    })
+    expect(appSchemaHelper.merge([])).toBeUndefined()
+    expect(appSchemaHelper.merge([undefined, {}])).toBeUndefined()
+  })
+
+  test('refuses a declaration a merge by name could not honour', () => {
+    const refused = (app: unknown, marker: string) =>
+      expect(() => appSchemaHelper.assertDeclarations(app as PlanningAppDeclarations)).toThrow(marker)
+    refused({ status: { properties: {} } }, 'app:kind:status')
+    refused({ card: { properties: {}, additionalProperties: false } }, 'app:card:keyword:additionalProperties')
+    refused({ type: { type: 'string', properties: {} } }, 'app:type:type')
+    refused({ flow: { properties: [] } }, 'app:flow:properties')
+    refused({ card: { properties: { 'a.b': {} } } }, 'app:card:name:a.b')
+    refused({ card: { properties: { $x: {} } } }, 'app:card:name:$x')
+    refused({ type: { properties: { a: {} }, required: ['b'] } }, 'app:type:required:b')
+    refused({ type: { properties: { a: { type: 'nope' } } } }, 'app:type:')
+    expect(() => appSchemaHelper.merge([{ card: { properties: {}, allOf: [] } as never }])).toThrow(SchemaInvalid)
+    expect(() => appSchemaHelper.assertDeclarations(APP)).not.toThrow()
+  })
+})
+
+describe('appSchemaHelper — definition bags', () => {
+  test('a bag is closed over the declared kind, and refused when the kind is undeclared', () => {
+    const ok = (kind: PlanningSchemaKind.Type | PlanningSchemaKind.Flow, bag: unknown, app = APP) =>
+      appSchemaHelper.assertBag(kind, 'k', bag, app)
+
+    expect(() => ok(PlanningSchemaKind.Type, { description: 'Jobs at the counter' })).not.toThrow()
+    expect(() => ok(PlanningSchemaKind.Type, undefined)).not.toThrow()
+    expect(() => ok(PlanningSchemaKind.Type, { colour: 'red' })).toThrow('type:k:app:')
+    expect(() => ok(PlanningSchemaKind.Type, { description: 5 })).toThrow(SchemaInvalid)
+    expect(() => ok(PlanningSchemaKind.Type, { description: 'x', nested: { 'a.b': 1 } })).toThrow('type:k:app:keys:nested.a.b')
+    // A required property makes the bag itself mandatory.
+    expect(() => ok(PlanningSchemaKind.Flow, undefined)).toThrow("flow:k:app:/ must have required property 'description'")
+    expect(() => ok(PlanningSchemaKind.Flow, { description: 'Bench work' })).not.toThrow()
+    expect(() => ok(PlanningSchemaKind.Flow, { description: 'x' }, { card: APP.card })).toThrow('flow:k:app:undeclared')
+    expect(() => ok(PlanningSchemaKind.Flow, undefined, {})).not.toThrow()
+    expect(appSchemaHelper.bagSchemaOf(APP, PlanningSchemaKind.Type)).toEqual({
+      type: 'object', properties: { description: { type: 'string', maxLength: 200 } }, additionalProperties: false,
+    })
+    expect(appSchemaHelper.bagSchemaOf({}, PlanningSchemaKind.Flow)).toBeUndefined()
+  })
+
+  test('the declaration schemas admit an app bag on the wire and in a bundle', () => {
+    const define = makeAjv().compile(SchemaDefineRequestSchema)
+    const bundle = makeAjv().compile(PlanningSchemaBundleSchema)
+
+    expect(define({ types: [{ ...JOB, app: { description: 'x' } }], flows: [{ ...MEND, app: { description: 'y' } }] })).toBe(true)
+    expect(define({ types: [{ ...JOB, app: 'x' }] })).toBe(false)
+    expect(bundle({ version: 1, types: [JOB], flows: [MEND], app: APP })).toBe(true)
+    expect(bundle({ version: 1, types: [JOB], flows: [MEND], app: { status: {} } })).toBe(false)
+  })
+})
+
+describe('appSchemaHelper — base card fields', () => {
+  test('a card type validates its own fields and the base ones; closed fields never refuse a base field', () => {
+    const registry = makeSchemaRegistry({ flows: [MEND], types: [JOB, SHOP], app: APP })
+    const valid = (fields: Record<string, unknown>) => registry.validator(JOB.type)(fields)
+
+    expect(valid({ cost: 12, priority: 'high' })).toBe(true)
+    expect(valid({ cost: 12 })).toBe(true)
+    expect(valid({ cost: -1, priority: 'high' })).toBe(false)
+    expect(valid({ cost: 1, priority: 'urgent' })).toBe(false)
+    expect(valid({ cost: 1, colour: 'red' })).toBe(false)
+    expect(() => validateHelper.validateFields(registry, JOB.type, { priority: 'urgent' })).toThrow('shop:job:')
+    // A project type is not a card type: its closed fields stay closed.
+    expect(registry.validator(SHOP.type)({ priority: 'high' })).toBe(false)
+    expect(registry.fieldsSchema(SHOP.type)).toBe(SHOP.fields)
+  })
+
+  test('a type may narrow a base field, and a required base field is required of every card type', () => {
+    const narrow: WorkcardTypeSchema = { ...JOB, type: 'shop:rush', fields: { type: 'object', properties: { priority: { const: 'high' } } } }
+    const registry = makeSchemaRegistry({
+      flows: [MEND], types: [narrow],
+      app: { card: { properties: { priority: { type: 'string', enum: ['low', 'high'] } }, required: ['priority'] } },
+    })
+
+    expect(registry.validator(narrow.type)({ priority: 'high' })).toBe(true)
+    expect(registry.validator(narrow.type)({ priority: 'low' })).toBe(false)
+    expect(registry.validator(narrow.type)({})).toBe(false)
+  })
+
+  test('without base fields the type\'s own fields object is what compiles', () => {
+    expect(appSchemaHelper.fieldsSchemaOf(JOB)).toBe(JOB.fields)
+    expect(appSchemaHelper.fieldsSchemaOf(JOB, { type: APP.type })).toBe(JOB.fields)
+    expect(makeSchemaRegistry({ flows: [MEND], types: [JOB] }).fieldsSchema(JOB.type)).toBe(JOB.fields)
+  })
+})
+
+describe('the schema registry and the scoped layers carry the declarations', () => {
+  test('registerApp replaces them and drops the cached validators; a bundle names them only when present', () => {
+    const registry = makeSchemaRegistry({ flows: [MEND], types: [JOB] })
+    expect('app' in registry.bundle()).toBe(false)
+    expect(registry.validator(JOB.type)({ priority: 'high' })).toBe(false)
+
+    registry.registerApp(APP)
+    expect(registry.app()).toEqual(APP)
+    expect(registry.bundle().app).toEqual(APP)
+    expect(registry.validator(JOB.type)({ priority: 'high' })).toBe(true)
+
+    registry.load({ version: 1, types: [JOB], flows: [MEND] })
+    expect(registry.app()).toBeUndefined()
+    expect(registry.validator(JOB.type)({ priority: 'high' })).toBe(false)
+    registry.load({ version: 1, types: [JOB], flows: [MEND], app: APP })
+    expect(registry.validator(JOB.type)({ priority: 'high' })).toBe(true)
+    expect(() => registry.registerApp({ card: { properties: { 'a.b': {} } } })).toThrow(SchemaInvalid)
+  })
+
+  test('a resolved layer passes the code declarations through; its registry refuses registerApp', () => {
+    const code = makeSchemaRegistry({ flows: [MEND], types: [JOB, SHOP], app: APP })
+    const record: ScopedSchemaRecord = {
+      entityId: 'org-1', kind: PlanningSchemaKind.Type, key: 'shop:quote', version: 1, createdAt: '2026-10-01T00:00:00.000Z',
+      definition: { ...JOB, type: 'shop:quote', fields: { type: 'object', additionalProperties: false }, app: { description: 'Quotes' } },
+    }
+    const layer = scopedSchemaHelper.scopedRegistryOf(scopedSchemaHelper.resolveScopedBundle(code.bundle(), [record], { entityId: 'org-1' }))
+
+    expect(layer.bundle().app).toEqual(APP)
+    expect((layer.type('shop:quote') as WorkcardTypeSchema).app).toEqual({ description: 'Quotes' })
+    expect(layer.validator('shop:quote')({ priority: 'low' })).toBe(true)
+    expect(() => layer.registerApp(undefined)).toThrow(PlanningUnsupported)
+    const plain = scopedSchemaHelper.resolveScopedBundle(makeSchemaRegistry({ flows: [MEND], types: [JOB] }).bundle(), [], { entityId: 'org-1' })
+    expect('app' in plain).toBe(false)
+  })
+
+  test('the closed-form checks of a data-defined type and flow apply the declarations', () => {
+    const flows = makeSchemaRegistry({ flows: [MEND] })
+    const quote: WorkcardTypeSchema = { ...JOB, type: 'shop:quote' }
+
+    expect(() => scopedSchemaHelper.assertTypeSchema({ ...quote, app: { description: 'Quotes' } }, flows, APP)).not.toThrow()
+    expect(() => scopedSchemaHelper.assertTypeSchema({ ...quote, app: { owner: 'me' } }, flows, APP)).toThrow('type:shop:quote:app:')
+    expect(() => scopedSchemaHelper.assertTypeSchema({ ...quote, app: { description: 'Quotes' } }, flows)).toThrow('type:shop:quote:app:undeclared')
+    expect(() => scopedSchemaHelper.assertTypeSchema(quote, flows)).not.toThrow()
+    expect(() => scopedSchemaHelper.assertFlowSchema({ ...MEND, app: { description: 'Bench' } }, APP)).not.toThrow()
+    expect(() => scopedSchemaHelper.assertFlowSchema(MEND, APP)).toThrow('flow:shop:mend:app:')
+    expect(() => scopedSchemaHelper.assertFlowSchema(MEND)).not.toThrow()
+  })
+})

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/csp.spec.ts

@@ -0,0 +1,122 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { IntrinsicStatus, WorkcardKind } from '../src/index.js'
+import type {
+  PlanningAppDeclarations, PlanningSchemaBundle, ProjectTypeSchema, StatusFlowSchema, WorkcardTypeSchema,
+} from '../src/index.js'
+import { appSchemaHelper } from '../src/helpers/app.js'
+import { scopedSchemaHelper } from '../src/helpers/scoped.js'
+import { makeSchemaRegistry } from '../src/registry.js'
+
+/** What a browser says when a page's `script-src` lacks `'unsafe-eval'`. */
+const REFUSAL = "Evaluating a string as JavaScript violates the following Content Security Policy directive because 'unsafe-eval' is not an allowed source of script"
+
+/** The work-management seed's declarations: every type and flow may carry a description. */
+const APP: PlanningAppDeclarations = {
+  type: { properties: { description: { type: 'string', maxLength: 2000 } } },
+  flow: { properties: { description: { type: 'string', maxLength: 2000 } } },
+}
+
+const WORK: StatusFlowSchema = {
+  id: 'wm:work-flow', version: 1, overridable: true, app: { description: 'Day-to-day work' },
+  statuses: [{ key: 'open', intrinsic: IntrinsicStatus.Planned, initial: true }, { key: 'done', intrinsic: IntrinsicStatus.Closed }],
+  transitions: [{ name: 'finish', from: ['open'], to: 'done' }],
+}
+
+const TASK: WorkcardTypeSchema = {
+  type: 'wm:task', kind: WorkcardKind.Card, version: 1, flows: [WORK.id], specifications: [], overridable: true,
+  app: { description: 'Work items' },
+  fields: { type: 'object', properties: { priority: { type: 'string', enum: ['low', 'high'] } }, required: ['priority'] },
+}
+
+const WORKSPACE: ProjectTypeSchema = {
+  type: 'wm:workspace', kind: WorkcardKind.Project, version: 1, fields: { type: 'object' },
+  flows: [WORK.id], specifications: [], cardTypes: [TASK.type],
+}
+
+/**
+ * A browser page under the publisher's policy: a `document` exists and every code generation is
+ * refused, the way a `script-src` without `'unsafe-eval'` refuses `new Function` and `eval`.
+ */
+const makeStrictPage = () => {
+  const scope = globalThis as unknown as Record<string, unknown>
+  const saved = { Function: scope.Function as FunctionConstructor, eval: scope.eval as typeof eval, error: console.error }
+  const counts = { generated: 0, logged: 0 }
+  const refuse = (): never => {
+    counts.generated++
+    throw new EvalError(REFUSAL)
+  }
+  const refusing = { Function: new Proxy(saved.Function, { construct: refuse, apply: refuse }), eval: new Proxy(saved.eval, { apply: refuse }) }
+
+  return {
+    counts,
+    enter: () => {
+      scope.document = {}
+      scope.Function = refusing.Function
+      scope.eval = refusing.eval
+      console.error = () => { counts.logged++ }
+    },
+    leave: () => {
+      delete scope.document
+      scope.Function = saved.Function
+      scope.eval = saved.eval
+      console.error = saved.error
+    },
+  }
+}
+
+const page = makeStrictPage()
+
+/** What a server serves: compiled there, then a JSON body — no object a page could share with it. */
+const served = (): PlanningSchemaBundle => JSON.parse(JSON.stringify(makeSchemaRegistry({
+  version: 1, types: [WORKSPACE, TASK], flows: [WORK], app: appSchemaHelper.merge([APP]),
+}).bundle())) as PlanningSchemaBundle
+
+afterEach(() => page.leave())
+
+describe('planning schemas — a page under a strict script-src', () => {
+  test('a registry builds, loads and merges served declarations without generating code', () => {
+    const bundle = served()
+    const scoped = JSON.parse(JSON.stringify(scopedSchemaHelper.resolveScopedBundle(bundle, [], { entityId: 'org-1' })))
+    page.counts.generated = 0
+    page.counts.logged = 0
+
+    page.enter()
+    const registry = makeSchemaRegistry(bundle)
+    expect(registry.app()).toEqual(bundle.app!)
+    registry.load(bundle)
+    expect(registry.bundle()).toEqual(bundle)
+    expect(appSchemaHelper.merge([bundle.app])).toEqual(bundle.app!)
+    appSchemaHelper.assertDeclarations(bundle.app!)
+    const layer = scopedSchemaHelper.scopedRegistryOf(scoped)
+    expect(layer.app()).toEqual(bundle.app!)
+    expect((layer.type(TASK.type) as WorkcardTypeSchema).app).toEqual({ description: 'Work items' })
+    expect(layer.fieldsSchema(TASK.type)).toEqual(TASK.fields)
+    page.leave()
+
+    expect(page.counts).toEqual({ generated: 0, logged: 0 })
+  })
+
+  test('the closed form is still refused in a page; only the compile is the server\'s', () => {
+    const bundle = served()
+    const uncompilable = { type: { properties: { a: { type: 'nope' } } } } as unknown as PlanningAppDeclarations
+    expect(() => appSchemaHelper.assertDeclarations(uncompilable)).toThrow('app:type:')
+
+    page.enter()
+    expect(() => appSchemaHelper.assertDeclarations({ card: { properties: { 'a.b': {} } } })).toThrow('app:card:name:a.b')
+    expect(() => makeSchemaRegistry({ ...bundle, app: { type: { properties: { a: {} }, required: ['b'] } } }))
+      .toThrow('app:type:required:b')
+    expect(() => appSchemaHelper.assertDeclarations(uncompilable)).not.toThrow()
+    page.leave()
+  })
+
+  test('the page really refuses code generation: a native validator cannot be compiled in it', () => {
+    const bundle = served()
+    page.counts.generated = 0
+
+    page.enter()
+    expect(() => makeSchemaRegistry(bundle).validator(TASK.type)).toThrow(EvalError)
+    page.leave()
+
+    expect(page.counts.generated).toBeGreaterThan(0)
+  })
+})

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' })