@owlmeans/viable-common 0.0.43 → 0.0.45

package/src/convert/utils.ts

@@ -0,0 +1,7 @@
+import { conversionDocHelper } from './docs.js'
+
+/** @deprecated compat:factory-refactor — use `conversionDocHelper.conversionStoryDoc(…)` */
+export const conversionStoryDoc = (code: string): string => conversionDocHelper.conversionStoryDoc(code)
+
+/** @deprecated compat:factory-refactor — use `conversionDocHelper.conversionSeedDoc(…)` */
+export const conversionSeedDoc = (name: string): string => conversionDocHelper.conversionSeedDoc(name)

package/src/design/consts.ts

@@ -6,6 +6,8 @@
  * the fields it is missing were absent because they had not been designed and which because the
  * shape did not have them yet. Those are different questions with different answers.
  */
+import type { StoryDesignRuntime } from './types.js'
+
 export const STORY_DESIGN_VERSION = 1
 
 /** How far a design may drift from the project it was written against before it is stale. */
@@ -21,3 +23,49 @@ export enum DesignStaleness {
   /** The generated tree moved under it. Re-run the stages that read the tree. */
   Tree = 'tree',
 }
+
+/** Who acts in a story. */
+export enum StoryActor {
+  /** A person, in one of the four areas. Every story until something says otherwise. */
+  Human = 'human',
+  /**
+   * The application's own LLM agent.
+   *
+   * An EPHEMERAL role: it holds no permissions and has no area of its own, because there is nobody
+   * to sign in as it. A story belongs to it when the work is the agent's — the human half is a
+   * separate, paired story that starts the work and watches it.
+   */
+  Agent = 'agent',
+  /** A queue consumer. Ephemeral in exactly the same sense. */
+  Worker = 'worker',
+}
+
+/** The ephemeral actors — those a permission may never be granted to. */
+export const EPHEMERAL_ACTORS: StoryActor[] = [StoryActor.Agent, StoryActor.Worker]
+
+/**
+ * The three shapes that can perform work with a model, cheapest first.
+ *
+ * They are not interchangeable and the difference is who decides the order. A CALL is one prompt
+ * and one answer; a PIPELINE runs steps this application named in advance; an AGENT is handed
+ * tools and works out its own path. Each step up buys capability with latency, money and a
+ * failure mode, so the right answer is the simplest shape that does the job — and for most work
+ * that asks for a model at all, it is a call.
+ */
+export enum StoryAgentKind {
+  /** One prompt, one answer, optionally schema-shaped. The default. */
+  Call = 'call',
+  /** Ordered steps decided by the application, not by the model. */
+  Pipeline = 'pipeline',
+  /** The model chooses its own path through the tools it was given. */
+  Agent = 'agent',
+}
+
+/** What a design carries when nobody has asked the question — and when the answer was "no". */
+export const NO_RUNTIME: StoryDesignRuntime = {
+  actor: StoryActor.Human,
+  worker: false,
+  jobs: [],
+  agents: [],
+  kv: false,
+}

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

@@ -14,129 +14,31 @@
  * emits exactly the tree it emitted before any of this existed.
  */
 
-/** Who acts in a story. */
-export enum StoryActor {
-  /** A person, in one of the four areas. Every story until something says otherwise. */
-  Human = 'human',
-  /**
-   * The application's own LLM agent.
-   *
-   * An EPHEMERAL role: it holds no permissions and has no area of its own, because there is nobody
-   * to sign in as it. A story belongs to it when the work is the agent's — the human half is a
-   * separate, paired story that starts the work and watches it.
-   */
-  Agent = 'agent',
-  /** A queue consumer. Ephemeral in exactly the same sense. */
-  Worker = 'worker',
-}
-
-/** The ephemeral actors — those a permission may never be granted to. */
-export const EPHEMERAL_ACTORS: StoryActor[] = [StoryActor.Agent, StoryActor.Worker]
+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)
 
-/** One queued unit of work. */
-export interface StoryDesignJob {
-  /** The queue it is enqueued onto. */
-  queue: string
-  /** The job name, which becomes the backend-only `job:<name>` protocol alias. */
-  name: string
-  /** The processor module, relative to the worker package's `src`. */
-  path: string
-  /** What it does, in one sentence, for the coder that writes the processor. */
-  purpose: string
-  /**
-   * Why it may not run on the request path.
-   *
-   * Recorded because it is the thing a later run has to be able to disagree with. "It might be
-   * slow" is not a reason; "it calls a model" and "it walks every row of a table the user owns"
-   * are.
-   */
-  reason: string
-  /**
-   * Whether running it twice is safe, and how it was made so.
-   *
-   * A worker can die mid-job; the lock expires and the step re-runs. There is no way to make that
-   * automatic, so the answer is written down where the processor's author has to read it.
-   */
-  idempotency: string
-}
+  const runtimeOf = (design?: { runtime?: StoryDesignRuntime }): StoryDesignRuntime =>
+    design?.runtime ?? NO_RUNTIME
 
-/** An LLM agent or pipeline generated INTO the target. */
-export interface StoryDesignAgent {
-  /** Its alias in the target's own agent registry. */
-  alias: string
-  /** The module, relative to the shared backend package's `src`. */
-  path: string
-  /** What it is for. */
-  purpose: string
-  /** Which of the three shapes this is — a call, a pipeline, or a tool-using agent. */
-  kind: StoryAgentKind
-  /** The job that runs it — an agent is never invoked on the request path. */
-  job?: string
-}
+  const needsRuntime = (runtime: StoryDesignRuntime): boolean =>
+    runtime.worker || runtime.jobs.length > 0 || runtime.agents.length > 0
 
-/**
- * The three shapes that can perform work with a model, cheapest first.
- *
- * They are not interchangeable and the difference is who decides the order. A CALL is one prompt
- * and one answer; a PIPELINE runs steps this application named in advance; an AGENT is handed
- * tools and works out its own path. Each step up buys capability with latency, money and a
- * failure mode, so the right answer is the simplest shape that does the job — and for most work
- * that asks for a model at all, it is a call.
- */
-export enum StoryAgentKind {
-  /** One prompt, one answer, optionally schema-shaped. The default. */
-  Call = 'call',
-  /** Ordered steps decided by the application, not by the model. */
-  Pipeline = 'pipeline',
-  /** The model chooses its own path through the tools it was given. */
-  Agent = 'agent',
+  return { isEphemeralActor, runtimeOf, needsRuntime }
 }
 
-/**
- * The gate, as the design stage recorded it.
- *
- * Absent on a design written before this existed, and read as "none of it" everywhere — which is
- * both the safe answer and the true one for every story developed until now.
- */
-export interface StoryDesignRuntime {
-  actor: StoryActor
-  /** Whether this story puts work on the queue at all. */
-  worker: boolean
-  jobs: StoryDesignJob[]
-  agents: StoryDesignAgent[]
-  /**
-   * Whether this story's data belongs in the key/value store rather than in Postgres.
-   *
-   * Postgres is the default and being wrong with it is cheap. This is true only for data with an
-   * expiry, a lock, a counter or a fan-out, and a bounded, namespaced key set.
-   */
-  kv: boolean
-  /**
-   * Which HUMAN story shows the progress of this story's queued work.
-   *
-   * An ephemeral actor cannot report to anybody: there is no screen it owns and no session it runs
-   * in. A story that enqueues work therefore names the story whose screen carries the job feed, and
-   * the permission to enqueue and to watch is granted to that area's role.
-   */
-  feedback?: string
-}
+export const storyRuntimeHelper = createStoryRuntimeHelper()
 
-/** What a design carries when nobody has asked the question — and when the answer was "no". */
-export const NO_RUNTIME: StoryDesignRuntime = {
-  actor: StoryActor.Human,
-  worker: false,
-  jobs: [],
-  agents: [],
-  kv: false,
-}
+/** @deprecated compat:factory-refactor — use `storyRuntimeHelper.isEphemeralActor(…)` */
+export const isEphemeralActor = (actor?: StoryActor): boolean => storyRuntimeHelper.isEphemeralActor(actor)
 
-/** Read the gate off a design, total over a design that predates it. */
+/** @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/schemas.ts

@@ -1,9 +1,8 @@
 import type { JSONSchemaType } from 'ajv'
 
 import { ProjectArea } from '../areas/consts.js'
-import { StoryActor, StoryAgentKind } from './runtime.js'
-import type { StoryDesignAgent, StoryDesignJob } from './runtime.js'
-import type { StoryDesign } from './types.js'
+import { StoryActor, StoryAgentKind } from './consts.js'
+import type { StoryDesign, RuntimeDecision } from './types.js'
 
 /**
  * The design shape, validated where the shape is DEFINED.
@@ -375,10 +374,3 @@ export const RuntimeDecisionSchema = {
   // is that they are usually empty.
 } as unknown as JSONSchemaType<RuntimeDecision>
 
-/** What the gate answers with — the model's half of {@link StoryDesignRuntime}. */
-export interface RuntimeDecision {
-  kv: boolean
-  feedback: string
-  jobs: StoryDesignJob[]
-  agents: StoryDesignAgent[]
-}

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
+}