@owlmeans/viable-common 0.0.44 → 0.0.45

package/src/convert/utils.ts

@@ -1,8 +1,7 @@
-import { CONVERSION_SEED_DATA_DIR, CONVERSION_SEED_DIR, CONVERSION_STORY_DIR } from './consts.js'
+import { conversionDocHelper } from './docs.js'
 
-export const conversionStoryDoc = (code: string): string => `${CONVERSION_STORY_DIR}/${code}.md`
+/** @deprecated compat:factory-refactor — use `conversionDocHelper.conversionStoryDoc(…)` */
+export const conversionStoryDoc = (code: string): string => conversionDocHelper.conversionStoryDoc(code)
 
-export const conversionSeedDoc = (name: string): string => `${CONVERSION_SEED_DIR}/${name}.md`
-
-export const conversionSeedData = (name: string, ext: string): string =>
-  `${CONVERSION_SEED_DATA_DIR}/${name}.${ext}`
+/** @deprecated compat:factory-refactor — use `conversionDocHelper.conversionSeedDoc(…)` */
+export const conversionSeedDoc = (name: string): string => conversionDocHelper.conversionSeedDoc(name)

package/src/design/helpers.ts

@@ -1,259 +1,34 @@
-import { SpecCategory } from '../ba/consts.js'
-import type { Entity, StoryComponent, StoryScreen, UserStory } from '../ba/types.js'
-import { DesignStaleness, STORY_DESIGN_VERSION } from './consts.js'
+import type { UserStory } from '../ba/types.js'
+import type { DesignStaleness } from './consts.js'
+import { storyDesignHelper } from './story.js'
 import type { StoryDesign } from './types.js'
 
-/**
- * The in-memory aggregate the coders take, derived from the design ALONE.
- *
- * Derived rather than stored, and derived HERE rather than at the platform: the aggregate is what
- * every generation helper reads, and a second place that assembles it is a second place that can
- * assemble it differently. The `code` in particular is load-bearing - the scaffold stamps every
- * placeholder it draws with it, so a run keyed by anything else cannot recognise its own
- * reservation.
- *
- * For a context with no card behind it. Where a story card exists, `userStoryOf(card, design)` is
- * the reader: the card wins on the narrative, code, area and actor, which a person may have
- * changed since the design was written.
- */
-export const userStoryOfDesign = (design: StoryDesign): UserStory => {
-  const componentOf = (name: string): StoryComponent | null => {
-    const component = design.components.find(entry => entry.name === name)
-    if (component == null) {
-      return null
-    }
+/** @deprecated compat:factory-refactor — use `storyDesignHelper.userStoryOfDesign(…)` */
+export const userStoryOfDesign = (design: StoryDesign): UserStory => storyDesignHelper.userStoryOfDesign(design)
 
-    return {
-      name: component.name,
-      description: '',
-      specs: {
-        [SpecCategory.UX]: component.specs.ux,
-        [SpecCategory.UI]: component.specs.ui,
-      } as Record<SpecCategory, string>,
-      entities: component.entities.map(entity => ({
-        name: entity, description: '', attributes: [],
-      } satisfies Entity)),
-    }
-  }
+/** @deprecated compat:factory-refactor — use `storyDesignHelper.screenMapOf(…)` */
+export const screenMapOf = (design: StoryDesign): Record<string, string[]> => storyDesignHelper.screenMapOf(design)
 
-  const screens: StoryScreen[] = design.screens.map(screen => ({
-    name: screen.name,
-    description: '',
-    ...(screen.section != null ? { section: screen.section } : {}),
-    specs: {
-      [SpecCategory.UX]: screen.specs.ux,
-      [SpecCategory.UI]: screen.specs.ui,
-    } as Record<SpecCategory, string>,
-    components: screen.components
-      .map(componentOf)
-      .filter((component): component is StoryComponent => component != null),
-  }))
+/** @deprecated compat:factory-refactor — use `storyDesignHelper.designPaths(…)` */
+export const designPaths = (design: StoryDesign): string[] => storyDesignHelper.designPaths(design)
 
-  return {
-    story: design.narrative,
-    code: design.code,
-    area: design.area,
-    entity: null as unknown as string,
-    entities: design.entities.map(entity => ({
-      name: entity.name, description: entity.description, attributes: [],
-    } satisfies Entity)),
-    screens,
-  }
-}
-
-/** Screen name to component names - the shape every UX and UI prompt takes. */
-export const screenMapOf = (design: StoryDesign): Record<string, string[]> =>
-  design.screens.reduce<Record<string, string[]>>((map, screen) => {
-    map[screen.name] = [...screen.components]
-
-    return map
-  }, {})
-
-/** Every path the design names, in the order the implementation stage visits them. */
-export const designPaths = (design: StoryDesign): string[] => [
-  ...design.types.map(entry => entry.path),
-  ...design.resources.map(entry => entry.path),
-  ...design.models.map(entry => entry.path),
-  ...design.api.map(entry => entry.path),
-  ...design.stores.map(entry => entry.path),
-  ...design.components.flatMap(entry => [entry.viewModelPath, entry.path]),
-  ...design.screens.map(entry => entry.path),
-]
-
-/**
- * How far the world has moved since the design was written.
- *
- * Ordered by severity, and each answer has one correct reaction: a version mismatch REFUSES, a
- * changed narrative re-designs, a changed project warns and continues, a moved tree re-runs only
- * the stages that read the tree. Collapsing them into a boolean would make every one of those the
- * most expensive of the four.
- */
+/** @deprecated compat:factory-refactor — use `storyDesignHelper.designStaleness(…)` */
 export const designStaleness = (
   design: StoryDesign,
   now: { narrativeHash: string, projectHash: string, registryHash: string },
-): DesignStaleness => {
-  if (design.version !== STORY_DESIGN_VERSION) {
-    return DesignStaleness.Version
-  }
-  if (design.provenance.narrativeHash !== now.narrativeHash) {
-    return DesignStaleness.Narrative
-  }
-  if (design.provenance.projectHash !== now.projectHash) {
-    return DesignStaleness.Project
-  }
-  if (design.provenance.registryHash !== now.registryHash) {
-    return DesignStaleness.Tree
-  }
-
-  return DesignStaleness.Fresh
-}
-
-/**
- * A stable, dependency-free hash of arbitrary text.
- *
- * FNV-1a, because what is being detected is "did this change", not "is this authentic" - and a
- * design record must be readable by a browser bundle, a worker and a test with no crypto import
- * between them.
- */
-export const designHash = (...parts: Array<string | undefined>): string => {
-  const text = parts.filter(part => part != null).join(' ')
-  let hash = 0x811c9dc5
-  for (let at = 0; at < text.length; at += 1) {
-    hash ^= text.charCodeAt(at)
-    hash = Math.imul(hash, 0x01000193) >>> 0
-  }
+): DesignStaleness => storyDesignHelper.designStaleness(design, now)
 
-  return hash.toString(16).padStart(8, '0')
-}
+/** @deprecated compat:factory-refactor — use `storyDesignHelper.designHash(…)` */
+export const designHash = (...parts: Array<string | undefined>): string => storyDesignHelper.designHash(...parts)
 
-/** An empty design, so every stage can fill its own slice without inventing the shape. */
+/** @deprecated compat:factory-refactor — use `storyDesignHelper.emptyStoryDesign(…)` */
 export const emptyStoryDesign = (
   input: Pick<StoryDesign, 'code' | 'narrative' | 'area'> & Partial<StoryDesign>,
-): StoryDesign => ({
-  version: STORY_DESIGN_VERSION,
-  reserved: {},
-  entities: [],
-  screens: [],
-  components: [],
-  types: [],
-  resources: [],
-  models: [],
-  api: [],
-  stores: [],
-  transitions: [],
-  access: { list: {}, resolvedAt: {} },
-  provenance: {
-    designedAt: new Date().toISOString(),
-    narrativeHash: '',
-    projectHash: '',
-    registryHash: '',
-    paths: [],
-  },
-  ...input,
-})
-
-/**
- * The design, small enough to hand a model, complete enough to act on.
- *
- * What a free-flight agent needs is names and counts: which screens exist, what is on them, which
- * types and endpoints the story implies. The UX and UI prose is the bulk of a design and none of
- * it helps an agent decide what to do next, so it is deliberately left out.
- */
-export const designDigest = (design: StoryDesign): string => {
-  const lines: string[] = [
-    `Story ${design.code} (${design.area}): ${design.narrative}`,
-  ]
-  if (design.reserved.section != null || design.reserved.screen != null) {
-    lines.push(`Reserved: section=${design.reserved.section ?? '-'} screen=${design.reserved.screen ?? '-'}`)
-  }
-  lines.push('', 'Screens:')
-  for (const screen of design.screens) {
-    lines.push(
-      `- ${screen.name} -> ${screen.path} (alias ${screen.alias}`
-      + `${screen.section != null ? `, section ${screen.section}` : ''}`
-      + `${screen.adopted ? ', existing' : ''}) renders ${screen.components.join(', ') || '-'}`,
-    )
-  }
-  lines.push('', 'Components:')
-  for (const component of design.components) {
-    lines.push(
-      `- ${component.name} -> ${component.path} (+ ${component.viewModelPath})`
-      + `${component.entities.length > 0 ? ` about ${component.entities.join(', ')}` : ''}`,
-    )
-  }
-  lines.push('', 'Data layer:')
-  for (const type of design.types) {
-    lines.push(`- type ${type.path} (${type.entity})`)
-  }
-  for (const resource of design.resources) {
-    lines.push(`- resource ${resource.path} (${resource.entity})`)
-  }
-  for (const model of design.models) {
-    lines.push(`- model ${model.path} (${model.entities.join(', ')})`)
-  }
-  for (const api of design.api) {
-    lines.push(
-      `- api ${api.path} (${api.entity})`
-      + `${api.endpoints.length > 0 ? `: ${api.endpoints.map(e => e.alias).join(', ')}` : ''}`,
-    )
-  }
-  for (const store of design.stores) {
-    lines.push(`- store ${store.path} (${store.entity})`)
-  }
-  if (design.transitions.length > 0) {
-    lines.push('', 'Transitions:')
-    for (const transition of design.transitions) {
-      lines.push(`- ${transition.from} -> ${transition.to} (${transition.action})`)
-    }
-  }
-  const guarded = Object.keys(design.access.list)
-  if (guarded.length > 0) {
-    lines.push('', `Access declared on: ${guarded.join(', ')}`)
-  }
-
-  return lines.join('\n')
-}
-
-/**
- * Apply a patch to a design, refusing anything that would rename an allocated artifact.
- *
- * A path or an alias is registry-owned. Changing one behind the registry's back leaves two
- * spellings of the same thing in a project, and no number of fix attempts repairs that — the
- * compiler sees a missing module and the fixer, reasonably, renames the reference to match
- * whichever spelling it found first.
- *
- * Returns the reason as a STRING when it refuses, so a model can read it and take the other route.
- */
-export const amendStoryDesign = (
-  design: StoryDesign, patch: Record<string, unknown>,
-): StoryDesign | string => {
-  const forbidden: string[] = []
-
-  const checkList = <T extends { path?: string, alias?: string, name?: string }>(
-    key: string, current: T[], next: unknown,
-  ): void => {
-    if (!Array.isArray(next)) return
-    for (const entry of next as T[]) {
-      const known = current.find(item => item.name === entry.name)
-      if (known == null) continue
-      if (entry.path != null && known.path != null && entry.path !== known.path) {
-        forbidden.push(`${key}.${String(entry.name)}.path`)
-      }
-      if (entry.alias != null && known.alias != null && entry.alias !== known.alias) {
-        forbidden.push(`${key}.${String(entry.name)}.alias`)
-      }
-    }
-  }
-
-  checkList('screens', design.screens, patch.screens)
-  checkList('components', design.components, patch.components)
+): StoryDesign => storyDesignHelper.emptyStoryDesign(input)
 
-  if (forbidden.length > 0) {
-    return `Refused: ${forbidden.join(', ')} name artifacts the project's registry allocated. `
-      + 'A design may change what a screen or a component DOES - its UX, its UI, its section, its '
-      + 'endpoints - but never where it lives or what it is called. Rename through the registry, '
-      + 'or leave the name alone and change the behaviour.'
-  }
+/** @deprecated compat:factory-refactor — use `storyDesignHelper.designDigest(…)` */
+export const designDigest = (design: StoryDesign): string => storyDesignHelper.designDigest(design)
 
-  return { ...design, ...patch } as StoryDesign
-}
+/** @deprecated compat:factory-refactor — use `storyDesignHelper.amendStoryDesign(…)` */
+export const amendStoryDesign = (design: StoryDesign, patch: Record<string, unknown>): StoryDesign | string =>
+  storyDesignHelper.amendStoryDesign(design, patch)

package/src/design/index.ts

@@ -1,5 +1,8 @@
 export * from './consts.js'
+export * from './story.js'
 export * from './helpers.js'
 export * from './schemas.js'
 export type * from './types.js'
+export type * from './story/types.js'
+export type * from './runtime/types.js'
 export * from './runtime.js'

package/src/design/runtime/types.ts

@@ -0,0 +1,14 @@
+import type { StoryActor } from '../consts.js'
+import type { StoryDesignRuntime } from '../types.js'
+
+/**
+ * What a story needs BEYOND a screen, an endpoint and a table — and the standing answer is
+ * "nothing". See `design/runtime.ts`.
+ */
+export interface StoryRuntimeHelper {
+  isEphemeralActor: (actor?: StoryActor) => boolean
+  /** Read the gate off a design, total over a design that predates it. */
+  runtimeOf: (design?: { runtime?: StoryDesignRuntime }) => StoryDesignRuntime
+  /** Whether anything at all was asked for — the one check every new step is gated on. */
+  needsRuntime: (runtime: StoryDesignRuntime) => boolean
+}

package/src/design/runtime.ts

@@ -16,14 +16,29 @@
 
 import { EPHEMERAL_ACTORS, NO_RUNTIME, StoryActor } from './consts.js'
 import type { StoryDesignRuntime } from './types.js'
+import type { StoryRuntimeHelper } from './runtime/types.js'
 
-export const isEphemeralActor = (actor?: StoryActor): boolean =>
-  actor != null && EPHEMERAL_ACTORS.includes(actor)
+export const createStoryRuntimeHelper = (): StoryRuntimeHelper => {
+  const isEphemeralActor = (actor?: StoryActor): boolean =>
+    actor != null && EPHEMERAL_ACTORS.includes(actor)
 
-/** Read the gate off a design, total over a design that predates it. */
+  const runtimeOf = (design?: { runtime?: StoryDesignRuntime }): StoryDesignRuntime =>
+    design?.runtime ?? NO_RUNTIME
+
+  const needsRuntime = (runtime: StoryDesignRuntime): boolean =>
+    runtime.worker || runtime.jobs.length > 0 || runtime.agents.length > 0
+
+  return { isEphemeralActor, runtimeOf, needsRuntime }
+}
+
+export const storyRuntimeHelper = createStoryRuntimeHelper()
+
+/** @deprecated compat:factory-refactor — use `storyRuntimeHelper.isEphemeralActor(…)` */
+export const isEphemeralActor = (actor?: StoryActor): boolean => storyRuntimeHelper.isEphemeralActor(actor)
+
+/** @deprecated compat:factory-refactor — use `storyRuntimeHelper.runtimeOf(…)` */
 export const runtimeOf = (design?: { runtime?: StoryDesignRuntime }): StoryDesignRuntime =>
-  design?.runtime ?? NO_RUNTIME
+  storyRuntimeHelper.runtimeOf(design)
 
-/** Whether anything at all was asked for — the one check every new step is gated on. */
-export const needsRuntime = (runtime: StoryDesignRuntime): boolean =>
-  runtime.worker || runtime.jobs.length > 0 || runtime.agents.length > 0
+/** @deprecated compat:factory-refactor — use `storyRuntimeHelper.needsRuntime(…)` */
+export const needsRuntime = (runtime: StoryDesignRuntime): boolean => storyRuntimeHelper.needsRuntime(runtime)

package/src/design/story/types.ts

@@ -0,0 +1,67 @@
+import type { UserStory } from '../../ba/types.js'
+import type { DesignStaleness } from '../consts.js'
+import type { StoryDesign } from '../types.js'
+
+/** Reading, digesting, hashing and amending a story's design record. */
+export interface StoryDesignHelper {
+  /**
+   * The in-memory aggregate the coders take, derived from the design ALONE.
+   *
+   * Derived rather than stored, and derived HERE rather than at the platform: the aggregate is what
+   * every generation helper reads, and a second place that assembles it is a second place that can
+   * assemble it differently. The `code` in particular is load-bearing - the scaffold stamps every
+   * placeholder it draws with it, so a run keyed by anything else cannot recognise its own
+   * reservation.
+   *
+   * For a context with no card behind it. Where a story card exists, `userStoryOf(card, design)` is
+   * the reader: the card wins on the narrative, code, area and actor, which a person may have
+   * changed since the design was written.
+   */
+  userStoryOfDesign: (design: StoryDesign) => UserStory
+  /** Screen name to component names - the shape every UX and UI prompt takes. */
+  screenMapOf: (design: StoryDesign) => Record<string, string[]>
+  /** Every path the design names, in the order the implementation stage visits them. */
+  designPaths: (design: StoryDesign) => string[]
+  /**
+   * How far the world has moved since the design was written.
+   *
+   * Ordered by severity, and each answer has one correct reaction: a version mismatch REFUSES, a
+   * changed narrative re-designs, a changed project warns and continues, a moved tree re-runs only
+   * the stages that read the tree. Collapsing them into a boolean would make every one of those the
+   * most expensive of the four.
+   */
+  designStaleness: (
+    design: StoryDesign, now: { narrativeHash: string, projectHash: string, registryHash: string },
+  ) => DesignStaleness
+  /**
+   * A stable, dependency-free hash of arbitrary text.
+   *
+   * FNV-1a, because what is being detected is "did this change", not "is this authentic" - and a
+   * design record must be readable by a browser bundle, a worker and a test with no crypto import
+   * between them.
+   */
+  designHash: (...parts: Array<string | undefined>) => string
+  /** An empty design, so every stage can fill its own slice without inventing the shape. */
+  emptyStoryDesign: (
+    input: Pick<StoryDesign, 'code' | 'narrative' | 'area'> & Partial<StoryDesign>,
+  ) => StoryDesign
+  /**
+   * The design, small enough to hand a model, complete enough to act on.
+   *
+   * What a free-flight agent needs is names and counts: which screens exist, what is on them, which
+   * types and endpoints the story implies. The UX and UI prose is the bulk of a design and none of
+   * it helps an agent decide what to do next, so it is deliberately left out.
+   */
+  designDigest: (design: StoryDesign) => string
+  /**
+   * Apply a patch to a design, refusing anything that would rename an allocated artifact.
+   *
+   * A path or an alias is registry-owned. Changing one behind the registry's back leaves two
+   * spellings of the same thing in a project, and no number of fix attempts repairs that — the
+   * compiler sees a missing module and the fixer, reasonably, renames the reference to match
+   * whichever spelling it found first.
+   *
+   * Returns the reason as a STRING when it refuses, so a model can read it and take the other route.
+   */
+  amendStoryDesign: (design: StoryDesign, patch: Record<string, unknown>) => StoryDesign | string
+}

package/src/design/story.ts

@@ -0,0 +1,221 @@
+import { SpecCategory } from '../ba/consts.js'
+import type { Entity, StoryComponent, StoryScreen, UserStory } from '../ba/types.js'
+import { DesignStaleness, STORY_DESIGN_VERSION } from './consts.js'
+import type { StoryDesign } from './types.js'
+import type { StoryDesignHelper } from './story/types.js'
+
+export const createStoryDesignHelper = (): StoryDesignHelper => {
+  const userStoryOfDesign = (design: StoryDesign): UserStory => {
+    const componentOf = (name: string): StoryComponent | null => {
+      const component = design.components.find(entry => entry.name === name)
+      if (component == null) {
+        return null
+      }
+
+      return {
+        name: component.name,
+        description: '',
+        specs: {
+          [SpecCategory.UX]: component.specs.ux,
+          [SpecCategory.UI]: component.specs.ui,
+        } as Record<SpecCategory, string>,
+        entities: component.entities.map(entity => ({
+          name: entity, description: '', attributes: [],
+        } satisfies Entity)),
+      }
+    }
+
+    const screens: StoryScreen[] = design.screens.map(screen => ({
+      name: screen.name,
+      description: '',
+      ...(screen.section != null ? { section: screen.section } : {}),
+      specs: {
+        [SpecCategory.UX]: screen.specs.ux,
+        [SpecCategory.UI]: screen.specs.ui,
+      } as Record<SpecCategory, string>,
+      components: screen.components
+        .map(componentOf)
+        .filter((component): component is StoryComponent => component != null),
+    }))
+
+    return {
+      story: design.narrative,
+      code: design.code,
+      area: design.area,
+      entity: null as unknown as string,
+      entities: design.entities.map(entity => ({
+        name: entity.name, description: entity.description, attributes: [],
+      } satisfies Entity)),
+      screens,
+    }
+  }
+
+  const screenMapOf = (design: StoryDesign): Record<string, string[]> =>
+    design.screens.reduce<Record<string, string[]>>((map, screen) => {
+      map[screen.name] = [...screen.components]
+
+      return map
+    }, {})
+
+  const designPaths = (design: StoryDesign): string[] => [
+    ...design.types.map(entry => entry.path),
+    ...design.resources.map(entry => entry.path),
+    ...design.models.map(entry => entry.path),
+    ...design.api.map(entry => entry.path),
+    ...design.stores.map(entry => entry.path),
+    ...design.components.flatMap(entry => [entry.viewModelPath, entry.path]),
+    ...design.screens.map(entry => entry.path),
+  ]
+
+  const designStaleness = (
+    design: StoryDesign,
+    now: { narrativeHash: string, projectHash: string, registryHash: string },
+  ): DesignStaleness => {
+    if (design.version !== STORY_DESIGN_VERSION) {
+      return DesignStaleness.Version
+    }
+    if (design.provenance.narrativeHash !== now.narrativeHash) {
+      return DesignStaleness.Narrative
+    }
+    if (design.provenance.projectHash !== now.projectHash) {
+      return DesignStaleness.Project
+    }
+    if (design.provenance.registryHash !== now.registryHash) {
+      return DesignStaleness.Tree
+    }
+
+    return DesignStaleness.Fresh
+  }
+
+  const designHash = (...parts: Array<string | undefined>): string => {
+    const text = parts.filter(part => part != null).join(' ')
+    let hash = 0x811c9dc5
+    for (let at = 0; at < text.length; at += 1) {
+      hash ^= text.charCodeAt(at)
+      hash = Math.imul(hash, 0x01000193) >>> 0
+    }
+
+    return hash.toString(16).padStart(8, '0')
+  }
+
+  const emptyStoryDesign = (
+    input: Pick<StoryDesign, 'code' | 'narrative' | 'area'> & Partial<StoryDesign>,
+  ): StoryDesign => ({
+    version: STORY_DESIGN_VERSION,
+    reserved: {},
+    entities: [],
+    screens: [],
+    components: [],
+    types: [],
+    resources: [],
+    models: [],
+    api: [],
+    stores: [],
+    transitions: [],
+    access: { list: {}, resolvedAt: {} },
+    provenance: {
+      designedAt: new Date().toISOString(),
+      narrativeHash: '',
+      projectHash: '',
+      registryHash: '',
+      paths: [],
+    },
+    ...input,
+  })
+
+  const designDigest = (design: StoryDesign): string => {
+    const lines: string[] = [
+      `Story ${design.code} (${design.area}): ${design.narrative}`,
+    ]
+    if (design.reserved.section != null || design.reserved.screen != null) {
+      lines.push(`Reserved: section=${design.reserved.section ?? '-'} screen=${design.reserved.screen ?? '-'}`)
+    }
+    lines.push('', 'Screens:')
+    for (const screen of design.screens) {
+      lines.push(
+        `- ${screen.name} -> ${screen.path} (alias ${screen.alias}`
+        + `${screen.section != null ? `, section ${screen.section}` : ''}`
+        + `${screen.adopted ? ', existing' : ''}) renders ${screen.components.join(', ') || '-'}`,
+      )
+    }
+    lines.push('', 'Components:')
+    for (const component of design.components) {
+      lines.push(
+        `- ${component.name} -> ${component.path} (+ ${component.viewModelPath})`
+        + `${component.entities.length > 0 ? ` about ${component.entities.join(', ')}` : ''}`,
+      )
+    }
+    lines.push('', 'Data layer:')
+    for (const type of design.types) {
+      lines.push(`- type ${type.path} (${type.entity})`)
+    }
+    for (const resource of design.resources) {
+      lines.push(`- resource ${resource.path} (${resource.entity})`)
+    }
+    for (const model of design.models) {
+      lines.push(`- model ${model.path} (${model.entities.join(', ')})`)
+    }
+    for (const api of design.api) {
+      lines.push(
+        `- api ${api.path} (${api.entity})`
+        + `${api.endpoints.length > 0 ? `: ${api.endpoints.map(e => e.alias).join(', ')}` : ''}`,
+      )
+    }
+    for (const store of design.stores) {
+      lines.push(`- store ${store.path} (${store.entity})`)
+    }
+    if (design.transitions.length > 0) {
+      lines.push('', 'Transitions:')
+      for (const transition of design.transitions) {
+        lines.push(`- ${transition.from} -> ${transition.to} (${transition.action})`)
+      }
+    }
+    const guarded = Object.keys(design.access.list)
+    if (guarded.length > 0) {
+      lines.push('', `Access declared on: ${guarded.join(', ')}`)
+    }
+
+    return lines.join('\n')
+  }
+
+  const amendStoryDesign = (
+    design: StoryDesign, patch: Record<string, unknown>,
+  ): StoryDesign | string => {
+    const forbidden: string[] = []
+
+    const checkList = <T extends { path?: string, alias?: string, name?: string }>(
+      key: string, current: T[], next: unknown,
+    ): void => {
+      if (!Array.isArray(next)) return
+      for (const entry of next as T[]) {
+        const known = current.find(item => item.name === entry.name)
+        if (known == null) continue
+        if (entry.path != null && known.path != null && entry.path !== known.path) {
+          forbidden.push(`${key}.${String(entry.name)}.path`)
+        }
+        if (entry.alias != null && known.alias != null && entry.alias !== known.alias) {
+          forbidden.push(`${key}.${String(entry.name)}.alias`)
+        }
+      }
+    }
+
+    checkList('screens', design.screens, patch.screens)
+    checkList('components', design.components, patch.components)
+
+    if (forbidden.length > 0) {
+      return `Refused: ${forbidden.join(', ')} name artifacts the project's registry allocated. `
+        + 'A design may change what a screen or a component DOES - its UX, its UI, its section, its '
+        + 'endpoints - but never where it lives or what it is called. Rename through the registry, '
+        + 'or leave the name alone and change the behaviour.'
+    }
+
+    return { ...design, ...patch } as StoryDesign
+  }
+
+  return {
+    userStoryOfDesign, screenMapOf, designPaths, designStaleness, designHash, emptyStoryDesign, designDigest,
+    amendStoryDesign,
+  }
+}
+
+export const storyDesignHelper = createStoryDesignHelper()

package/src/dev/types.local.ts

@@ -1,4 +1,4 @@
 import type { AccessBlock } from './types.js'
 
 /** The part of an {@link AccessBlock} a model is asked for. */
-export type ModelAccessBlock = Omit<AccessBlock, 'defaults' | 'entityScoped'>
+export interface ModelAccessBlock extends Omit<AccessBlock, 'defaults' | 'entityScoped'> {}

package/src/integrity/index.ts

@@ -1,4 +1,8 @@
 export * from './consts.js'
+export * from './layout/consts.js'
+export * from './layout.js'
 export * from './utils.js'
 export * from './verify.js'
 export type * from './types.js'
+export type * from './layout/types.js'
+export type * from './verify/types.js'