@owlmeans/viable-common 0.0.43 → 0.0.45

package/tests/connect-errors.spec.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from 'bun:test'
 import { ResilientError } from '@owlmeans/error'
-import { ConnectConsentRequired, ConnectOutOfCredits } from '../src/connect/errors.js'
+import { ConnectConfirmationRequired, ConnectConsentRequired, ConnectOutOfCredits } from '../src/connect/errors.js'
+import type { ConnectConfirmation } from '../src/connect/errors/types.js'
 
 describe('@owlmeans/viable-common — ConnectOutOfCredits', () => {
   test('carries its fields fresh, and survives a marshal/unmarshal round trip', () => {
@@ -50,3 +51,35 @@ describe('@owlmeans/viable-common — ConnectConsentRequired', () => {
     expect((ResilientError.ensure(fresh.marshal()) as ConnectConsentRequired).deadline).toBeUndefined()
   })
 })
+
+describe('@owlmeans/viable-common — ConnectConfirmationRequired', () => {
+  const fields: ConnectConfirmation = {
+    action: 'convert-proceed', cap: 1_000_000, spent: 420_000, estimate: 850_000, fromAllowance: 580_000,
+    fromCreditLimits: 150_000, moneyUsd: 2.4,
+  }
+
+  test('packs the action, the conversion limit and the stage split, and answers 428', () => {
+    const fresh = new ConnectConfirmationRequired(ConnectConfirmationRequired.encode(fields))
+
+    expect(fresh.message).toBe('viable-connect:confirmation-required:convert-proceed:1000000:420000:850000:580000:150000:2.4')
+    expect(fresh).toEqual(expect.objectContaining(fields))
+    expect((fresh.constructor as { httpStatus?: number }).httpStatus).toBe(428)
+  })
+
+  test('survives a marshal/unmarshal round trip — only type and message cross a hop', () => {
+    const restored = ResilientError.ensure(
+      new ConnectConfirmationRequired(ConnectConfirmationRequired.encode({ ...fields, action: 'convert-start' })).marshal()
+    )
+
+    expect(restored).toBeInstanceOf(ConnectConfirmationRequired)
+    expect(restored).toEqual(expect.objectContaining({ ...fields, action: 'convert-start' }))
+  })
+
+  test('decode is encode\'s inverse; an unreadable number reads back as 0, never NaN', () => {
+    expect(ConnectConfirmationRequired.decode(ConnectConfirmationRequired.encode(fields))).toEqual(fields)
+    expect(ConnectConfirmationRequired.encode({ ...fields, moneyUsd: Number.NaN })).toEndWith(':0')
+    expect(ConnectConfirmationRequired.decode('convert-start:x')).toEqual({
+      action: 'convert-start', cap: 0, spent: 0, estimate: 0, fromAllowance: 0, fromCreditLimits: 0, moneyUsd: 0,
+    })
+  })
+})

package/tests/convert.spec.ts

@@ -7,14 +7,13 @@ import {
   CONVERSION_ARTIFACTS, CONVERSION_DIR, CONVERSION_DOCS, CONVERSION_MEMORY, ConversionStage,
   EntropyClass, FileClass, SizeClass, STACK_FAMILY, StackId, TAXONOMY_ORDER, TaxonomyKind
 } from '../src/convert/index.js'
-import {
-  binaryByExtension, canEnter, decisionFor, entropyClassOf, fileClassOf, isOriginPath, originPath,
-  sizeClassOf, stageAfter, storyComplexity
-} from '../src/convert/helpers.js'
+import { censusHelper } from '../src/convert/census.js'
+import { conversionStageHelper } from '../src/convert/stage.js'
+import { storyComplexity } from '../src/convert/estimate.js'
+import { conversionOriginHelper } from '../src/convert/origin.js'
 import { HISTORY_FILE } from '../src/metadata/consts.js'
-import {
-  conversionStoryDoc, CONVERTED_ORIGIN_DIR, ConversionDecision
-} from '../src/convert/consts.js'
+import { CONVERTED_ORIGIN_DIR, ConversionDecision } from '../src/convert/consts.js'
+import { conversionDocHelper } from '../src/convert/docs.js'
 
 /**
  * Every `*Schema` a module exports.
@@ -177,26 +176,26 @@ describe('viable-common - the conversion contracts', () => {
   })
 
   test('canEnter allows a retry and the next stage, and refuses a skip', () => {
-    expect(canEnter(ConversionStage.Intake, ConversionStage.Intake)).toBe(true)
-    expect(canEnter(ConversionStage.Intake, ConversionStage.Analysis)).toBe(true)
+    expect(conversionStageHelper.canEnter(ConversionStage.Intake, ConversionStage.Intake)).toBe(true)
+    expect(conversionStageHelper.canEnter(ConversionStage.Intake, ConversionStage.Analysis)).toBe(true)
     // Extraction reads the documents analysis wrote; entering it from intake runs it against
     // documents that were never produced.
-    expect(canEnter(ConversionStage.Intake, ConversionStage.Extraction)).toBe(false)
-    expect(canEnter(ConversionStage.Extraction, ConversionStage.Analysis)).toBe(false)
+    expect(conversionStageHelper.canEnter(ConversionStage.Intake, ConversionStage.Extraction)).toBe(false)
+    expect(conversionStageHelper.canEnter(ConversionStage.Extraction, ConversionStage.Analysis)).toBe(false)
   })
 
   test('the stage ladder ends at implementation rather than falling off it', () => {
-    expect(stageAfter(ConversionStage.Intake)).toBe(ConversionStage.Analysis)
-    expect(stageAfter(ConversionStage.Implementation)).toBe(ConversionStage.Implementation)
-    expect(decisionFor(ConversionStage.Extraction)).toBe(ConversionDecision.Implement)
-    expect(decisionFor(ConversionStage.Implementation)).toBe(ConversionDecision.Leave)
+    expect(conversionStageHelper.stageAfter(ConversionStage.Intake)).toBe(ConversionStage.Analysis)
+    expect(conversionStageHelper.stageAfter(ConversionStage.Implementation)).toBe(ConversionStage.Implementation)
+    expect(conversionStageHelper.decisionFor(ConversionStage.Extraction)).toBe(ConversionDecision.Implement)
+    expect(conversionStageHelper.decisionFor(ConversionStage.Implementation)).toBe(ConversionDecision.Leave)
   })
 
   test('every conversion document lives under the conversion directory', () => {
     for (const doc of CONVERSION_DOCS) {
       expect(doc.startsWith(`${CONVERSION_DIR}/`), doc).toBe(true)
     }
-    expect(conversionStoryDoc('US-ABC12').startsWith(`${CONVERSION_DIR}/`)).toBe(true)
+    expect(conversionDocHelper.conversionStoryDoc('US-ABC12').startsWith(`${CONVERSION_DIR}/`)).toBe(true)
     for (const node of CONVERSION_MEMORY) {
       expect(node.startsWith('.agents/memory/'), node).toBe(true)
     }
@@ -210,54 +209,54 @@ describe('viable-common - the conversion contracts', () => {
   })
 
   test('origin paths round-trip and never nest', () => {
-    expect(originPath('src/index.ts')).toBe(`${CONVERTED_ORIGIN_DIR}/src/index.ts`)
-    expect(isOriginPath(originPath('src/index.ts'))).toBe(true)
-    expect(isOriginPath(CONVERTED_ORIGIN_DIR)).toBe(true)
-    expect(isOriginPath('sources/web/src/index.ts')).toBe(false)
+    expect(conversionOriginHelper.originPath('src/index.ts')).toBe(`${CONVERTED_ORIGIN_DIR}/src/index.ts`)
+    expect(conversionOriginHelper.isOriginPath(conversionOriginHelper.originPath('src/index.ts'))).toBe(true)
+    expect(conversionOriginHelper.isOriginPath(CONVERTED_ORIGIN_DIR)).toBe(true)
+    expect(conversionOriginHelper.isOriginPath('sources/web/src/index.ts')).toBe(false)
     // A caller that has lost track of which side of the move it holds must not be able to produce
     // `__viable_converted/__viable_converted/`.
-    expect(originPath(originPath('src/index.ts'))).toBe(`${CONVERTED_ORIGIN_DIR}/src/index.ts`)
+    expect(conversionOriginHelper.originPath(conversionOriginHelper.originPath('src/index.ts'))).toBe(`${CONVERTED_ORIGIN_DIR}/src/index.ts`)
   })
 
   test('sizeClassOf splits on the declared bounds', () => {
-    expect(sizeClassOf(0)).toBe(SizeClass.Tiny)
-    expect(sizeClassOf(2_047)).toBe(SizeClass.Tiny)
-    expect(sizeClassOf(2_048)).toBe(SizeClass.Small)
-    expect(sizeClassOf(32_767)).toBe(SizeClass.Small)
-    expect(sizeClassOf(32_768)).toBe(SizeClass.Medium)
-    expect(sizeClassOf(262_144)).toBe(SizeClass.Large)
-    expect(sizeClassOf(2_097_152)).toBe(SizeClass.Huge)
+    expect(censusHelper.sizeClassOf(0)).toBe(SizeClass.Tiny)
+    expect(censusHelper.sizeClassOf(2_047)).toBe(SizeClass.Tiny)
+    expect(censusHelper.sizeClassOf(2_048)).toBe(SizeClass.Small)
+    expect(censusHelper.sizeClassOf(32_767)).toBe(SizeClass.Small)
+    expect(censusHelper.sizeClassOf(32_768)).toBe(SizeClass.Medium)
+    expect(censusHelper.sizeClassOf(262_144)).toBe(SizeClass.Large)
+    expect(censusHelper.sizeClassOf(2_097_152)).toBe(SizeClass.Huge)
   })
 
   test('entropyClassOf tells prose from a minified bundle from binary', () => {
-    expect(entropyClassOf('export const answer = 42\nconsole.log(answer)\n'))
+    expect(censusHelper.entropyClassOf('export const answer = 42\nconsole.log(answer)\n'))
       .toBe(EntropyClass.Text)
     // Printable throughout, and not something a model can reason over: no line breaks, no indent.
-    expect(entropyClassOf(`const a=1,b=2,c=3;${'x'.repeat(400)}`)).toBe(EntropyClass.Dense)
-    expect(entropyClassOf(`‰PNG${'ÿ
'.repeat(40)}`))
+    expect(censusHelper.entropyClassOf(`const a=1,b=2,c=3;${'x'.repeat(400)}`)).toBe(EntropyClass.Dense)
+    expect(censusHelper.entropyClassOf(`‰PNG${'ÿ
'.repeat(40)}`))
       .toBe(EntropyClass.Opaque)
   })
 
   test('fileClassOf reads the path before the extension', () => {
-    expect(fileClassOf('sources/api/src/index.ts', 'ts')).toBe(FileClass.Source)
-    expect(fileClassOf('node_modules/left-pad/index.js', 'js')).toBe(FileClass.Generated)
-    expect(fileClassOf('tests/api.spec.ts', 'ts')).toBe(FileClass.Test)
-    expect(fileClassOf('seed/users.json', 'json')).toBe(FileClass.Data)
-    expect(fileClassOf('package.json', 'json')).toBe(FileClass.Manifest)
-    expect(fileClassOf('bun.lock', 'lock')).toBe(FileClass.Lock)
+    expect(censusHelper.fileClassOf('sources/api/src/index.ts', 'ts')).toBe(FileClass.Source)
+    expect(censusHelper.fileClassOf('node_modules/left-pad/index.js', 'js')).toBe(FileClass.Generated)
+    expect(censusHelper.fileClassOf('tests/api.spec.ts', 'ts')).toBe(FileClass.Test)
+    expect(censusHelper.fileClassOf('seed/users.json', 'json')).toBe(FileClass.Data)
+    expect(censusHelper.fileClassOf('package.json', 'json')).toBe(FileClass.Manifest)
+    expect(censusHelper.fileClassOf('bun.lock', 'lock')).toBe(FileClass.Lock)
   })
 
   test('a seed or dump location reclassifies a payload and never a program', () => {
     // Asked before the test check and the extension table, the seed/dump rule answered `Data` for
     // all four of these — real source, out of the census's source budget on a word in its path.
-    expect(fileClassOf('tests/fixtures/user.ts', 'ts')).toBe(FileClass.Test)
-    expect(fileClassOf('src/seedUsers.ts', 'ts')).toBe(FileClass.Source)
-    expect(fileClassOf('src/exportReport.ts', 'ts')).toBe(FileClass.Source)
-    expect(fileClassOf('bin/cli.ts', 'ts')).toBe(FileClass.Source)
+    expect(censusHelper.fileClassOf('tests/fixtures/user.ts', 'ts')).toBe(FileClass.Test)
+    expect(censusHelper.fileClassOf('src/seedUsers.ts', 'ts')).toBe(FileClass.Source)
+    expect(censusHelper.fileClassOf('src/exportReport.ts', 'ts')).toBe(FileClass.Source)
+    expect(censusHelper.fileClassOf('bin/cli.ts', 'ts')).toBe(FileClass.Source)
     // What the rule is for: a payload, and the one language that is a dump as often as it is code.
-    expect(fileClassOf('fixtures/orders.csv', 'csv')).toBe(FileClass.Data)
-    expect(fileClassOf('db/dumps/2024.sql', 'sql')).toBe(FileClass.Data)
-    expect(fileClassOf('db/migrations/0001_init.sql', 'sql')).toBe(FileClass.Source)
+    expect(censusHelper.fileClassOf('fixtures/orders.csv', 'csv')).toBe(FileClass.Data)
+    expect(censusHelper.fileClassOf('db/dumps/2024.sql', 'sql')).toBe(FileClass.Data)
+    expect(censusHelper.fileClassOf('db/migrations/0001_init.sql', 'sql')).toBe(FileClass.Source)
   })
 
   test('storyComplexity scales on what the extraction actually found', () => {
@@ -298,17 +297,17 @@ describe('viable-common - the conversion contracts', () => {
   test('binaryByExtension answers a tail it knows and defers on one it does not', () => {
     // The verdict a probe alone gets wrong: a small `.ico` with no NUL in its first bytes reads as
     // text, which is how a census on a laptop and the same census in the slot disagreed.
-    expect(binaryByExtension('assets/logo.ico')).toBe(true)
-    expect(binaryByExtension('assets/logo.PNG')).toBe(true)
-    expect(binaryByExtension('sources/web/src/app.tsx')).toBe(false)
-    expect(binaryByExtension('archive.tar.gz')).toBe(true)
+    expect(censusHelper.binaryByExtension('assets/logo.ico')).toBe(true)
+    expect(censusHelper.binaryByExtension('assets/logo.PNG')).toBe(true)
+    expect(censusHelper.binaryByExtension('sources/web/src/app.tsx')).toBe(false)
+    expect(censusHelper.binaryByExtension('archive.tar.gz')).toBe(true)
     // Nothing to go on, so the caller has to read it: no tail at all, a dotfile (which
     // `path.extname` also answers nothing for), and a tail neither list carries.
-    expect(binaryByExtension('Makefile')).toBeNull()
-    expect(binaryByExtension('.env')).toBeNull()
-    expect(binaryByExtension('data.parquet')).toBeNull()
+    expect(censusHelper.binaryByExtension('Makefile')).toBeNull()
+    expect(censusHelper.binaryByExtension('.env')).toBeNull()
+    expect(censusHelper.binaryByExtension('data.parquet')).toBeNull()
     // The tail of the last SEGMENT, never of the path.
-    expect(binaryByExtension('release.d/manifest')).toBeNull()
+    expect(censusHelper.binaryByExtension('release.d/manifest')).toBeNull()
   })
 
   test('a head read is bounded, and the binary probe is smaller than the head', () => {

package/tests/design.spec.ts

@@ -2,13 +2,10 @@ import { describe, expect, test } from 'bun:test'
 import Ajv from 'ajv'
 import { ProjectArea } from '../src/areas/consts.js'
 import { SpecCategory } from '../src/ba/consts.js'
-import {
-  DesignStaleness, STORY_DESIGN_VERSION, StoryDesignSchema, designHash, designStaleness,
-  emptyStoryDesign, screenMapOf, userStoryOfDesign,
-} from '../src/design/index.js'
+import { DesignStaleness, STORY_DESIGN_VERSION, StoryDesignSchema, storyDesignHelper } from '../src/design/index.js'
 import type { StoryDesign } from '../src/design/index.js'
 
-const design = (extra: Partial<StoryDesign> = {}): StoryDesign => emptyStoryDesign({
+const design = (extra: Partial<StoryDesign> = {}): StoryDesign => storyDesignHelper.emptyStoryDesign({
   code: 'US-ABC12',
   narrative: 'A visitor books a slot.',
   area: ProjectArea.User,
@@ -45,7 +42,7 @@ describe('viable-common - the design aggregate', () => {
   test('derives the UserStory the coders take, carrying the story code', () => {
     // The scaffold stamps every placeholder it draws with the code, so a run keyed by anything
     // else cannot recognise its own reservation.
-    const story = userStoryOfDesign(withScreens())
+    const story = storyDesignHelper.userStoryOfDesign(withScreens())
 
     expect(story.code).toBe('US-ABC12')
     expect(story.area).toBe(ProjectArea.User)
@@ -60,11 +57,11 @@ describe('viable-common - the design aggregate', () => {
     const broken = withScreens()
     broken.screens[0].components = ['BookingList', 'Ghost']
 
-    expect(userStoryOfDesign(broken).screens[0].components.map(entry => entry.name)).toEqual(['BookingList'])
+    expect(storyDesignHelper.userStoryOfDesign(broken).screens[0].components.map(entry => entry.name)).toEqual(['BookingList'])
   })
 
   test('screenMapOf is the shape every UX and UI prompt takes', () => {
-    expect(screenMapOf(withScreens())).toEqual({ 'booking/list/overview': ['BookingList'] })
+    expect(storyDesignHelper.screenMapOf(withScreens())).toEqual({ 'booking/list/overview': ['BookingList'] })
   })
 })
 
@@ -78,7 +75,7 @@ describe('viable-common - design staleness', () => {
   }
 
   test('answers fresh when nothing moved', () => {
-    expect(designStaleness(fresh(), now)).toBe(DesignStaleness.Fresh)
+    expect(storyDesignHelper.designStaleness(fresh(), now)).toBe(DesignStaleness.Fresh)
   })
 
   test('ranks by severity: version, then narrative, then project, then tree', () => {
@@ -86,17 +83,17 @@ describe('viable-common - design staleness', () => {
     // them the most expensive of the four.
     const versioned = fresh()
     versioned.version = STORY_DESIGN_VERSION + 1
-    expect(designStaleness(versioned, now)).toBe(DesignStaleness.Version)
+    expect(storyDesignHelper.designStaleness(versioned, now)).toBe(DesignStaleness.Version)
 
-    expect(designStaleness(fresh(), { ...now, narrativeHash: 'x' })).toBe(DesignStaleness.Narrative)
-    expect(designStaleness(fresh(), { ...now, projectHash: 'x' })).toBe(DesignStaleness.Project)
-    expect(designStaleness(fresh(), { ...now, registryHash: 'x' })).toBe(DesignStaleness.Tree)
+    expect(storyDesignHelper.designStaleness(fresh(), { ...now, narrativeHash: 'x' })).toBe(DesignStaleness.Narrative)
+    expect(storyDesignHelper.designStaleness(fresh(), { ...now, projectHash: 'x' })).toBe(DesignStaleness.Project)
+    expect(storyDesignHelper.designStaleness(fresh(), { ...now, registryHash: 'x' })).toBe(DesignStaleness.Tree)
   })
 
   test('the hash is stable and distinguishes its inputs', () => {
-    expect(designHash('a', 'b')).toBe(designHash('a', 'b'))
-    expect(designHash('a', 'b')).not.toBe(designHash('a', 'c'))
-    expect(designHash('a', undefined)).toBe(designHash('a'))
+    expect(storyDesignHelper.designHash('a', 'b')).toBe(storyDesignHelper.designHash('a', 'b'))
+    expect(storyDesignHelper.designHash('a', 'b')).not.toBe(storyDesignHelper.designHash('a', 'c'))
+    expect(storyDesignHelper.designHash('a', undefined)).toBe(storyDesignHelper.designHash('a'))
   })
 })
 

package/tests/error-status.spec.ts

@@ -19,6 +19,7 @@ const DECLARED: Record<string, number | undefined> = {
   ConnectOpRefused: 422,
   ConnectOutOfCredits: 402,
   ConnectConsentRequired: 428,
+  ConnectConfirmationRequired: 428,
   ConnectOpTimeout: undefined,
   ProjectResourceError: undefined,
   ProjectNotFound: 404,
@@ -41,7 +42,7 @@ describe('viable-common refusals — declared HTTP statuses', () => {
     expect(classes.map(([name]) => name).sort()).toEqual(Object.keys(DECLARED).sort())
   })
 
-  test('balance 402, an absent target 404, a conflicting state 409, refused content 422, a consent only a person gives 428; faults nothing', () => {
+  test('balance 402, an absent target 404, a conflicting state 409, refused content 422, a consent or a confirmation only a person gives 428; faults nothing', () => {
     for (const [name, Class] of classes) {
       expect([name, statusOf(new Class('x'))]).toEqual([name, DECLARED[name]])
     }
@@ -60,5 +61,10 @@ describe('viable-common refusals — declared HTTP statuses', () => {
       new connect.ConnectConsentRequired(connect.ConnectConsentRequired.encode('story', 'https://x.test/?consent=1')).marshal()
     )
     expect([statusOf(consent), (consent as connect.ConnectConsentRequired).consentUrl]).toEqual([428, 'https://x.test/?consent=1'])
+    const confirmation = ResilientError.ensure(new connect.ConnectConfirmationRequired(connect.ConnectConfirmationRequired.encode({
+      action: 'convert-proceed', cap: 1_000_000, spent: 420_000, estimate: 300_000, fromAllowance: 300_000,
+      fromCreditLimits: 0, moneyUsd: 0,
+    })).marshal())
+    expect([statusOf(confirmation), (confirmation as connect.ConnectConfirmationRequired).spent]).toEqual([428, 420_000])
   })
 })

package/tests/planning.spec.ts

@@ -2,32 +2,15 @@ import { describe, expect, test } from 'bun:test'
 import Ajv from 'ajv'
 import addFormats from 'ajv-formats'
 import { ResilientError } from '@owlmeans/error'
-import {
-  canTransit, CodeScope, CodeStyle, intrinsicOf, IntrinsicStatus, makeSchemaRegistry,
-  SpecificationFormat, TITLE_MAX, transitionsFrom, WorkcardKind,
-} from '@owlmeans/planning'
-import type { Specification } from '@owlmeans/planning'
+import { CodeScope, CodeStyle, IntrinsicStatus, makeSchemaRegistry, SpecificationFormat, TITLE_MAX, WorkcardKind, type Specification, statusHelper } from '@owlmeans/planning'
 import { ProjectArea } from '../src/areas/consts.js'
 import { ConnectingStoryKind, SpecCategory, StoryKind } from '../src/ba/consts.js'
-import { mergeConnectingStories } from '../src/ba/helpers.js'
-import { STORY_DESIGN_VERSION } from '../src/design/consts.js'
-import { emptyStoryDesign } from '../src/design/helpers.js'
-import { StoryActor } from '../src/design/runtime.js'
+import { connectingStoryHelper } from '../src/ba/connecting.js'
+import { STORY_DESIGN_VERSION, StoryActor } from '../src/design/consts.js'
+import { storyDesignHelper } from '../src/design/story.js'
 import type { StoryDesign } from '../src/design/types.js'
-import {
-  hasLandingSentence, LANDING_STORY_SENTENCE, withLandingSentence,
-} from '../src/index.js'
-import {
-  isUserChannel, isViableProject, isViableStory, ProjectAgentOccupied, ProjectNotFound,
-  ProjectStoryMissconfigured, projectBriefOf, storyDraftOf, storyWriteInputOf, userStoryOf,
-  VIABLE_FLOW_SCHEMAS, VIABLE_PROJECT_FLOW, VIABLE_PROJECT_FLOW_SCHEMA, VIABLE_PROJECT_TYPE,
-  VIABLE_PROJECT_TYPE_SCHEMA, VIABLE_RESERVED_TYPE_SCHEMAS, VIABLE_SPEC_TYPE, VIABLE_STORY_FLOW,
-  VIABLE_STORY_FLOW_SCHEMA,
-  VIABLE_STORY_TYPE, VIABLE_STORY_TYPE_SCHEMA, VIABLE_TYPE_SCHEMAS, ViableChannel,
-  ViableProjectFieldsSchema, ViableProjectStatus, ViableProjectTransition, ViableRelationship,
-  ViableSpecCategory, ViableStoryFieldsSchema, ViableStoryStatus, ViableStoryTransition,
-} from '../src/planning/index.js'
-import type { ViableProjectCard, ViableStoryCard } from '../src/planning/index.js'
+import { LANDING_STORY_SENTENCE, landingSentenceHelper } from '../src/index.js'
+import { ProjectAgentOccupied, ProjectNotFound, ProjectStoryMissconfigured, VIABLE_FLOW_SCHEMAS, VIABLE_PROJECT_FLOW, VIABLE_PROJECT_FLOW_SCHEMA, VIABLE_PROJECT_TYPE, VIABLE_PROJECT_TYPE_SCHEMA, VIABLE_RESERVED_TYPE_SCHEMAS, VIABLE_SPEC_TYPE, VIABLE_STORY_FLOW, VIABLE_STORY_FLOW_SCHEMA, VIABLE_STORY_TYPE, VIABLE_STORY_TYPE_SCHEMA, VIABLE_TYPE_SCHEMAS, ViableChannel, ViableProjectFieldsSchema, ViableProjectStatus, ViableProjectTransition, ViableRelationship, ViableSpecCategory, ViableStoryFieldsSchema, ViableStoryStatus, ViableStoryTransition, type ViableProjectCard, type ViableStoryCard, viableCardHelper, viableSpecHelper } from '../src/planning/index.js'
 
 const at = '2026-09-16T10:00:00.000Z'
 
@@ -91,7 +74,7 @@ const spec = (category: string, body: string, revision?: number): Specification
   ...(revision != null ? { revision } : {}),
 })
 
-const designed = (): StoryDesign => emptyStoryDesign({
+const designed = (): StoryDesign => storyDesignHelper.emptyStoryDesign({
   code: 'US-OLD00',
   narrative: 'The narrative the design was written against.',
   area: ProjectArea.Guest,
@@ -121,30 +104,30 @@ describe('viable-common - the story flow', () => {
   test('maps a failed story onto PLANNED, so done is the closed count and a retry is a start', () => {
     const flow = VIABLE_STORY_FLOW_SCHEMA
 
-    expect(intrinsicOf(flow, ViableStoryStatus.Planned)).toBe(IntrinsicStatus.Planned)
-    expect(intrinsicOf(flow, ViableStoryStatus.InProgress)).toBe(IntrinsicStatus.InProgress)
-    expect(intrinsicOf(flow, ViableStoryStatus.Completed)).toBe(IntrinsicStatus.Closed)
-    expect(intrinsicOf(flow, ViableStoryStatus.Failed)).toBe(IntrinsicStatus.Planned)
+    expect(statusHelper.intrinsicOf(flow, ViableStoryStatus.Planned)).toBe(IntrinsicStatus.Planned)
+    expect(statusHelper.intrinsicOf(flow, ViableStoryStatus.InProgress)).toBe(IntrinsicStatus.InProgress)
+    expect(statusHelper.intrinsicOf(flow, ViableStoryStatus.Completed)).toBe(IntrinsicStatus.Closed)
+    expect(statusHelper.intrinsicOf(flow, ViableStoryStatus.Failed)).toBe(IntrinsicStatus.Planned)
   })
 
   test('starts from planned or failed only, and resets from anywhere', () => {
     const flow = VIABLE_STORY_FLOW_SCHEMA
     const { Planned, InProgress, Completed, Failed } = ViableStoryStatus
 
-    expect(canTransit(flow, ViableStoryTransition.Start, Planned)).toBe(true)
-    expect(canTransit(flow, ViableStoryTransition.Start, Failed)).toBe(true)
-    expect(canTransit(flow, ViableStoryTransition.Start, InProgress)).toBe(false)
-    expect(canTransit(flow, ViableStoryTransition.Start, Completed)).toBe(false)
-    expect(canTransit(flow, ViableStoryTransition.Complete, InProgress)).toBe(true)
-    expect(canTransit(flow, ViableStoryTransition.Fail, InProgress)).toBe(true)
-    expect(canTransit(flow, ViableStoryTransition.Fail, Planned)).toBe(false)
+    expect(statusHelper.canTransit(flow, ViableStoryTransition.Start, Planned)).toBe(true)
+    expect(statusHelper.canTransit(flow, ViableStoryTransition.Start, Failed)).toBe(true)
+    expect(statusHelper.canTransit(flow, ViableStoryTransition.Start, InProgress)).toBe(false)
+    expect(statusHelper.canTransit(flow, ViableStoryTransition.Start, Completed)).toBe(false)
+    expect(statusHelper.canTransit(flow, ViableStoryTransition.Complete, InProgress)).toBe(true)
+    expect(statusHelper.canTransit(flow, ViableStoryTransition.Fail, InProgress)).toBe(true)
+    expect(statusHelper.canTransit(flow, ViableStoryTransition.Fail, Planned)).toBe(false)
     for (const status of Object.values(ViableStoryStatus)) {
-      expect(canTransit(flow, ViableStoryTransition.Reset, status)).toBe(true)
+      expect(statusHelper.canTransit(flow, ViableStoryTransition.Reset, status)).toBe(true)
     }
   })
 
   test('offers a completed story nothing but a reset', () => {
-    expect(transitionsFrom(VIABLE_STORY_FLOW_SCHEMA, ViableStoryStatus.Completed).map(rule => rule.name))
+    expect(statusHelper.transitionsFrom(VIABLE_STORY_FLOW_SCHEMA, ViableStoryStatus.Completed).map(rule => rule.name))
       .toEqual([ViableStoryTransition.Reset])
   })
 })
@@ -155,15 +138,15 @@ describe('viable-common - the project flow', () => {
     const { Draft, Confirmed, Active, Archived } = ViableProjectStatus
 
     expect(flow.statuses.find(status => status.initial === true)?.key).toBe(Draft)
-    expect(intrinsicOf(flow, Draft)).toBe(IntrinsicStatus.Planned)
-    expect(intrinsicOf(flow, Confirmed)).toBe(IntrinsicStatus.InProgress)
-    expect(intrinsicOf(flow, Active)).toBe(IntrinsicStatus.InProgress)
-    expect(intrinsicOf(flow, Archived)).toBe(IntrinsicStatus.Closed)
-    expect(canTransit(flow, ViableProjectTransition.Confirm, Draft)).toBe(true)
-    expect(canTransit(flow, ViableProjectTransition.Confirm, Active)).toBe(false)
-    expect(canTransit(flow, ViableProjectTransition.Activate, Confirmed)).toBe(true)
-    expect(canTransit(flow, ViableProjectTransition.Archive, Active)).toBe(true)
-    expect(canTransit(flow, ViableProjectTransition.Reopen, Archived)).toBe(true)
+    expect(statusHelper.intrinsicOf(flow, Draft)).toBe(IntrinsicStatus.Planned)
+    expect(statusHelper.intrinsicOf(flow, Confirmed)).toBe(IntrinsicStatus.InProgress)
+    expect(statusHelper.intrinsicOf(flow, Active)).toBe(IntrinsicStatus.InProgress)
+    expect(statusHelper.intrinsicOf(flow, Archived)).toBe(IntrinsicStatus.Closed)
+    expect(statusHelper.canTransit(flow, ViableProjectTransition.Confirm, Draft)).toBe(true)
+    expect(statusHelper.canTransit(flow, ViableProjectTransition.Confirm, Active)).toBe(false)
+    expect(statusHelper.canTransit(flow, ViableProjectTransition.Activate, Confirmed)).toBe(true)
+    expect(statusHelper.canTransit(flow, ViableProjectTransition.Archive, Active)).toBe(true)
+    expect(statusHelper.canTransit(flow, ViableProjectTransition.Reopen, Archived)).toBe(true)
   })
 })
 
@@ -314,15 +297,15 @@ describe('viable-common - the viable field schemas', () => {
 
 describe('viable-common - the viable card helpers', () => {
   test('recognises a card by kind AND type', () => {
-    expect(isViableStory(storyCard())).toBe(true)
-    expect(isViableStory(storyCard({ type: 'notion:task' }))).toBe(false)
-    expect(isViableProject(projectCard())).toBe(true)
-    expect(isViableProject(storyCard())).toBe(false)
+    expect(viableCardHelper.isViableStory(storyCard())).toBe(true)
+    expect(viableCardHelper.isViableStory(storyCard({ type: 'notion:task' }))).toBe(false)
+    expect(viableCardHelper.isViableProject(projectCard())).toBe(true)
+    expect(viableCardHelper.isViableProject(storyCard())).toBe(false)
   })
 
   test('userStoryOf lets the card win on narrative, code, area and actor, and takes screens from the design', () => {
     const card = storyCard({ fields: { area: ProjectArea.User, primary: true, actor: StoryActor.Worker } })
-    const story = userStoryOf(card, designed())
+    const story = viableCardHelper.userStoryOf(card, designed())
 
     expect(story.story).toBe(card.title)
     expect(story.code).toBe('US-ABC12')
@@ -330,12 +313,12 @@ describe('viable-common - the viable card helpers', () => {
     expect(story.actor).toBe(StoryActor.Worker)
     expect(story.screens.map(screen => screen.name)).toEqual(['booking/list/overview'])
     expect(story.entities.map(entity => entity.name)).toEqual(['Booking'])
-    expect(userStoryOf(card).screens).toEqual([])
-    expect(storyDraftOf(card)).toEqual({ story: card.title, area: ProjectArea.User })
+    expect(viableCardHelper.userStoryOf(card).screens).toEqual([])
+    expect(viableCardHelper.storyDraftOf(card)).toEqual({ story: card.title, area: ProjectArea.User })
   })
 
   test('projectBriefOf reads the highest revision per part and answers an unwritten part empty', () => {
-    const brief = projectBriefOf(projectCard(), [
+    const brief = viableSpecHelper.projectBriefOf(projectCard(), [
       spec(ViableSpecCategory.Specification, 'first', 1),
       spec(ViableSpecCategory.Specification, 'second', 2),
       spec(ViableSpecCategory.Vision, 'the vision'),
@@ -349,62 +332,62 @@ describe('viable-common - the viable card helpers', () => {
 
   test('storyWriteInputOf takes code, narrative and primary from the card, and refuses a card with no code', () => {
     const content = {
-      userStory: userStoryOf(storyCard()), screenPaths: {}, componentPaths: {}, transitions: [],
+      userStory: viableCardHelper.userStoryOf(storyCard()), screenPaths: {}, componentPaths: {}, transitions: [],
       section: 'Booking',
     }
 
-    expect(storyWriteInputOf(storyCard(), content)).toEqual(expect.objectContaining({
+    expect(viableCardHelper.storyWriteInputOf(storyCard(), content)).toEqual(expect.objectContaining({
       code: 'US-ABC12', narrative: 'A member books a slot.', primary: true,
       status: ViableStoryStatus.Planned, section: 'Booking',
     }))
-    expect(storyWriteInputOf(storyCard(), { ...content, status: ViableStoryStatus.Completed }).status)
+    expect(viableCardHelper.storyWriteInputOf(storyCard(), { ...content, status: ViableStoryStatus.Completed }).status)
       .toBe(ViableStoryStatus.Completed)
-    expect(() => storyWriteInputOf(storyCard({ code: undefined }), content))
+    expect(() => viableCardHelper.storyWriteInputOf(storyCard({ code: undefined }), content))
       .toThrow(ProjectStoryMissconfigured)
   })
 
   test('storyWriteInputOf copies the landing flag from the card, and only when it is set', () => {
     const content = {
-      userStory: userStoryOf(storyCard()), screenPaths: {}, componentPaths: {}, transitions: [],
+      userStory: viableCardHelper.userStoryOf(storyCard()), screenPaths: {}, componentPaths: {}, transitions: [],
     }
     const landing = storyCard({ fields: { area: ProjectArea.User, primary: false, landing: true } })
 
-    expect(storyWriteInputOf(landing, content).landing).toBe(true)
-    expect('landing' in storyWriteInputOf(storyCard(), content)).toBe(false)
+    expect(viableCardHelper.storyWriteInputOf(landing, content).landing).toBe(true)
+    expect('landing' in viableCardHelper.storyWriteInputOf(storyCard(), content)).toBe(false)
   })
 
   test('only a person writes through the web and connect channels', () => {
-    expect(isUserChannel(ViableChannel.Web)).toBe(true)
-    expect(isUserChannel(ViableChannel.Connect)).toBe(true)
-    expect(isUserChannel(ViableChannel.Pipeline)).toBe(false)
-    expect(isUserChannel(undefined)).toBe(false)
+    expect(viableCardHelper.isUserChannel(ViableChannel.Web)).toBe(true)
+    expect(viableCardHelper.isUserChannel(ViableChannel.Connect)).toBe(true)
+    expect(viableCardHelper.isUserChannel(ViableChannel.Pipeline)).toBe(false)
+    expect(viableCardHelper.isUserChannel(undefined)).toBe(false)
   })
 })
 
 describe('viable-common - the landing sentence', () => {
   test('is appended once, with one space, and a resumed step never adds a second copy', () => {
-    const once = withLandingSentence('A member books a slot.')
+    const once = landingSentenceHelper.withLandingSentence('A member books a slot.')
 
     expect(once).toBe(`A member books a slot. ${LANDING_STORY_SENTENCE}`)
-    expect(withLandingSentence(once)).toBe(once)
-    expect(hasLandingSentence(once)).toBe(true)
-    expect(hasLandingSentence('A member books a slot.')).toBe(false)
+    expect(landingSentenceHelper.withLandingSentence(once)).toBe(once)
+    expect(landingSentenceHelper.hasLandingSentence(once)).toBe(true)
+    expect(landingSentenceHelper.hasLandingSentence('A member books a slot.')).toBe(false)
   })
 
   test('is recognised whatever whitespace a person left around it', () => {
     const rewrapped = `A member books a slot.\n${LANDING_STORY_SENTENCE.replace('; after', ';\n  after')}`
 
-    expect(hasLandingSentence(rewrapped)).toBe(true)
-    expect(withLandingSentence(rewrapped)).toBe(rewrapped)
+    expect(landingSentenceHelper.hasLandingSentence(rewrapped)).toBe(true)
+    expect(landingSentenceHelper.withLandingSentence(rewrapped)).toBe(rewrapped)
   })
 
   test('never makes a title longer than a card accepts, and never cuts the narrative', () => {
     const long = 'x'.repeat(TITLE_MAX - 10)
 
-    expect(withLandingSentence(long)).toBe(long)
-    expect(withLandingSentence('x'.repeat(TITLE_MAX - LANDING_STORY_SENTENCE.length - 1)).length)
+    expect(landingSentenceHelper.withLandingSentence(long)).toBe(long)
+    expect(landingSentenceHelper.withLandingSentence('x'.repeat(TITLE_MAX - LANDING_STORY_SENTENCE.length - 1)).length)
       .toBe(TITLE_MAX)
-    expect(withLandingSentence('  ')).toBe(LANDING_STORY_SENTENCE)
+    expect(landingSentenceHelper.withLandingSentence('  ')).toBe(LANDING_STORY_SENTENCE)
   })
 })
 
@@ -415,7 +398,7 @@ describe('viable-common - the follows anchor', () => {
       { story: 'Two', area: ProjectArea.User },
       { story: 'Three', area: ProjectArea.Admin },
     ]
-    const merged = mergeConnectingStories(flow, [
+    const merged = connectingStoryHelper.mergeConnectingStories(flow, [
       { story: 'Queue', area: ProjectArea.Admin, kind: ConnectingStoryKind.Queue, after: 9 },
       { story: 'Tracker', area: ProjectArea.User, kind: ConnectingStoryKind.Tracker, after: 1 },
     ])