@owlmeans/viable-common 0.0.44 → 0.0.45

package/tests/convert.spec.ts

@@ -7,13 +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 { CONVERTED_ORIGIN_DIR, ConversionDecision } from '../src/convert/consts.js'
-import { conversionStoryDoc } from '../src/convert/utils.js'
+import { conversionDocHelper } from '../src/convert/docs.js'
 
 /**
  * Every `*Schema` a module exports.
@@ -176,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)
     }
@@ -209,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', () => {
@@ -297,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/planning.spec.ts

@@ -2,17 +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, 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 { connectingStoryHelper } from '../src/ba/connecting.js'
 import { STORY_DESIGN_VERSION, StoryActor } from '../src/design/consts.js'
-import { emptyStoryDesign } from '../src/design/helpers.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, type ViableProjectCard, type 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'
 
@@ -76,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,
@@ -106,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])
   })
 })
@@ -140,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)
   })
 })
 
@@ -299,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')
@@ -315,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'),
@@ -334,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)
   })
 })
 
@@ -400,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 },
     ])

package/tests/presentation.spec.ts

@@ -1,47 +1,47 @@
 import { describe, expect, test } from 'bun:test'
-import { classifyAgentMessage, isAgentMessageHidden } from '../src/agent/presentation.js'
+import { agentPresentationHelper } from '../src/agent/presentation.js'
 import { AgentCodeLanguage, AgentMarkdownKind, AgentMessageCategory, AgentMessageRole, AgentStructuredKind } from '../src/agent/consts.js'
 
 describe('@owlmeans/viable-common — agent message presentation', () => {
   test('classifies source and unified diffs with their display language', () => {
-    expect(classifyAgentMessage({ action: 'code', text: 'export const App = () => <main />' }))
+    expect(agentPresentationHelper.classifyAgentMessage({ action: 'code', text: 'export const App = () => <main />' }))
       .toMatchObject({ category: AgentMessageCategory.Code, language: AgentCodeLanguage.ReactTsx })
-    expect(classifyAgentMessage({ action: 'update-code', text: '--- a/app.css\n+++ b/app.css\n@@ -1 +1 @@\n-.old {}\n+.new {}' }))
+    expect(agentPresentationHelper.classifyAgentMessage({ action: 'update-code', text: '--- a/app.css\n+++ b/app.css\n@@ -1 +1 @@\n-.old {}\n+.new {}' }))
       .toMatchObject({ category: AgentMessageCategory.Diff, language: AgentCodeLanguage.Css })
-    expect(classifyAgentMessage({ text: '{"ready": true}' }))
+    expect(agentPresentationHelper.classifyAgentMessage({ text: '{"ready": true}' }))
       .toMatchObject({ category: AgentMessageCategory.Code, language: AgentCodeLanguage.Json })
   })
 
   test('unwraps schema tool calls into semantic cards instead of a JSON fallback', () => {
-    expect(classifyAgentMessage({
+    expect(agentPresentationHelper.classifyAgentMessage({
       outputType: 'tool_calls',
       action: 'choose-files-for-fix',
       value: [{ name: 'answer', args: { files: ['src/app.tsx'], why: 'screen entrypoint' } }],
     })).toMatchObject({ category: AgentMessageCategory.Structured, structure: AgentStructuredKind.ArtifactSelection })
-    expect(classifyAgentMessage({ value: { actor: 'human', worker: false, jobs: [], agents: [], kv: false } }))
+    expect(agentPresentationHelper.classifyAgentMessage({ value: { actor: 'human', worker: false, jobs: [], agents: [], kv: false } }))
       .toMatchObject({ category: AgentMessageCategory.Structured, structure: AgentStructuredKind.RuntimeDecision })
     // The model's own runtime-decision call never carries `actor`/`worker` — those are added only
     // once the decision is persisted onto a StoryDesign.
-    expect(classifyAgentMessage({ value: { kv: true, feedback: null, jobs: [], agents: [] } }))
+    expect(agentPresentationHelper.classifyAgentMessage({ value: { kv: true, feedback: null, jobs: [], agents: [] } }))
       .toMatchObject({ category: AgentMessageCategory.Structured, structure: AgentStructuredKind.RuntimeDecision })
     // A scaffold plan carries its own `stories` array — checked ahead of StoryPlan's bare check.
-    expect(classifyAgentMessage({
+    expect(agentPresentationHelper.classifyAgentMessage({
       value: { identity: { name: 'App', description: '' }, guestHome: {}, areas: [], stories: [], motifs: '' },
     })).toMatchObject({ category: AgentMessageCategory.Structured, structure: AgentStructuredKind.ScaffoldPlan })
-    expect(classifyAgentMessage({ value: { unknown: ['still', 'readable'] } }))
+    expect(agentPresentationHelper.classifyAgentMessage({ value: { unknown: ['still', 'readable'] } }))
       .toMatchObject({ category: AgentMessageCategory.Structured, structure: AgentStructuredKind.GenericRecord })
   })
 
   test('routes unconstrained tool-calling loops to ToolCalls even when args shape-match a schema', () => {
     // A single free-flight file read whose args happen to carry `files` — without the action
     // check this reads as an ArtifactSelection card instead of a tool call.
-    expect(classifyAgentMessage({
+    expect(agentPresentationHelper.classifyAgentMessage({
       outputType: 'tool_calls',
       action: 'coding-agent-ask',
       value: [{ name: 'read_sources', args: { files: ['src/app.tsx'] } }],
     })).toMatchObject({ category: AgentMessageCategory.Structured, structure: AgentStructuredKind.ToolCalls })
     // Several calls in the same turn are always ToolCalls, regardless of action.
-    expect(classifyAgentMessage({
+    expect(agentPresentationHelper.classifyAgentMessage({
       outputType: 'tool_calls',
       value: [
         { name: 'read_file', args: { path: 'a.ts' } },
@@ -50,34 +50,34 @@ describe('@owlmeans/viable-common — agent message presentation', () => {
     })).toMatchObject({ category: AgentMessageCategory.Structured, structure: AgentStructuredKind.ToolCalls })
     // A single call whose args shape-match nothing known stays ToolCalls rather than falling
     // through to a generic JSON dump.
-    expect(classifyAgentMessage({
+    expect(agentPresentationHelper.classifyAgentMessage({
       outputType: 'tool_calls',
       value: [{ name: 'run_bun', args: { args: 'install' } }],
     })).toMatchObject({ category: AgentMessageCategory.Structured, structure: AgentStructuredKind.ToolCalls })
   })
 
   test('uses producer metadata for roles and action metadata for documents and decisions', () => {
-    expect(classifyAgentMessage({ agent: 'ba-service', helper: 'ba-helper', action: 'write-specification', text: '# Brief' }))
+    expect(agentPresentationHelper.classifyAgentMessage({ agent: 'ba-service', helper: 'ba-helper', action: 'write-specification', text: '# Brief' }))
       .toMatchObject({ category: AgentMessageCategory.Markdown, document: AgentMarkdownKind.Specification, role: AgentMessageRole.Analytical })
-    expect(classifyAgentMessage({ agent: 'ui-helper', action: 'describe-ui-screen', text: '## Layout' }))
+    expect(agentPresentationHelper.classifyAgentMessage({ agent: 'ui-helper', action: 'describe-ui-screen', text: '## Layout' }))
       .toMatchObject({ role: AgentMessageRole.VisualDesign })
-    expect(classifyAgentMessage({ agent: 'api-helper', action: 'should-update-handler', text: 'true' }))
+    expect(agentPresentationHelper.classifyAgentMessage({ agent: 'api-helper', action: 'should-update-handler', text: 'true' }))
       .toMatchObject({ category: AgentMessageCategory.Structured, structure: AgentStructuredKind.Decision, role: AgentMessageRole.Architect })
-    expect(classifyAgentMessage({ agent: 'runtime-architect', action: 'runtime-gate' }))
+    expect(agentPresentationHelper.classifyAgentMessage({ agent: 'runtime-architect', action: 'runtime-gate' }))
       .toMatchObject({ category: AgentMessageCategory.Structured, structure: AgentStructuredKind.RuntimeDecision, role: AgentMessageRole.Architect })
-    expect(classifyAgentMessage({ helper: 'navigation-analyst', action: 'detect-story-with-home-screen' }))
+    expect(agentPresentationHelper.classifyAgentMessage({ helper: 'navigation-analyst', action: 'detect-story-with-home-screen' }))
       .toMatchObject({ category: AgentMessageCategory.Structured, structure: AgentStructuredKind.CandidateRanking, role: AgentMessageRole.Analytical })
   })
 
   test('keeps ordinary conversation as plain text', () => {
-    expect(classifyAgentMessage({ agent: 'client', action: 'prompt', text: 'Please add a dashboard.' }))
+    expect(agentPresentationHelper.classifyAgentMessage({ agent: 'client', action: 'prompt', text: 'Please add a dashboard.' }))
       .toEqual({ category: AgentMessageCategory.Plain, role: AgentMessageRole.Technical })
   })
 
   test('hides source-extractor range selections from the user-facing journal', () => {
-    expect(isAgentMessageHidden({ action: 'source-extract', value: [{
+    expect(agentPresentationHelper.isAgentMessageHidden({ action: 'source-extract', value: [{
       name: 'select_ranges', args: { ranges: [{ start: 12, end: 18 }] },
     }] })).toBe(true)
-    expect(isAgentMessageHidden({ action: 'declaration-lookup' })).toBe(false)
+    expect(agentPresentationHelper.isAgentMessageHidden({ action: 'declaration-lookup' })).toBe(false)
   })
 })