@owlmeans/viable-common 0.0.44 → 0.0.45

package/src/agent/presentation.ts

@@ -3,190 +3,224 @@ import { agentLoopActions, codeActions, documentActions, structuredActions } fro
 import { AgentCodeLanguage, AgentMarkdownKind, AgentMessageCategory, AgentMessageRole, AgentStructuredKind } from './consts.js'
 import type { RecordValue } from './types.local.js'
 import type { AgentMessageClassificationInput, AgentMessagePresentation } from './types.js'
+import type { AgentPresentationHelper } from './presentation/types.js'
+
+export const createAgentPresentationHelper = (): AgentPresentationHelper => {
+  const asRecord = (value: unknown): RecordValue | undefined =>
+    value != null && typeof value === 'object' && !Array.isArray(value)
+      ? value as RecordValue
+      : undefined
+
+  const actionOf = (input: AgentMessageClassificationInput): string => input.action?.toLowerCase() ?? ''
+
+  const sourceOf = (input: AgentMessageClassificationInput): string =>
+    `${input.agent ?? ''} ${input.helper ?? ''}`.toLowerCase()
+
+  const contentOf = (input: AgentMessageClassificationInput): string => input.text?.trim() ?? ''
+
+  /**
+   * Source extraction is an internal context-reduction pass. Its terminal tool call contains only
+   * line ranges, which are useful to the coder but add no useful information to a person's journal.
+   */
+  const isAgentMessageHidden = (input: AgentMessageClassificationInput): boolean =>
+    actionOf(input) === 'source-extract'
+
+  /** Maps the attribution that reached the event boundary to the visual specialist family. */
+  const agentMessageRoleOf = (input: AgentMessageClassificationInput): AgentMessageRole => {
+    const source = sourceOf(input)
+    const action = actionOf(input)
+
+    if (action === 'arbitrary-modification' || source.includes('orchestrator')) return AgentMessageRole.Orchestrator
+    if (source.includes('fix')) return AgentMessageRole.Repair
+    if (source.includes('coder') || source.includes('developer') || codeActions.has(action)) return AgentMessageRole.Developer
+    if (source.includes('visual') || source.includes('ui-helper')) return AgentMessageRole.VisualDesign
+    if (source.includes('ux-')) return AgentMessageRole.Ux
+    if (source.includes('business') || source.includes('ba-') || source.includes('analysis') || source.includes('analyst')) return AgentMessageRole.Analytical
+    if (source.includes('product') || source.includes('naming')) return AgentMessageRole.Product
+    if (source.includes('architect') || source.includes('arch') || source.includes('layout-helper') ||
+      source.includes('api-helper') || source.includes('access-helper') || source.includes('datalayer-helper') ||
+      source.includes('domain') || source.includes('nav-helper') || source.includes('ui-com-helper') ||
+      source.includes('ui-state-helper')) return AgentMessageRole.Architect
+    return AgentMessageRole.Technical
+  }
 
-const asRecord = (value: unknown): RecordValue | undefined =>
-  value != null && typeof value === 'object' && !Array.isArray(value)
-    ? value as RecordValue
-    : undefined
+  /** Pulls a schema argument out of LangChain's serialised tool-call shape. */
+  const agentToolCallArguments = (value: unknown): unknown => {
+    if (!Array.isArray(value) || value.length !== 1) return value
+    const call = asRecord(value[0])
+    return call?.args ?? value
+  }
 
-const actionOf = (input: AgentMessageClassificationInput): string => input.action?.toLowerCase() ?? ''
+  const structuredKindOf = (value: unknown): AgentStructuredKind | undefined => {
+    if (value == null) return undefined
 
-const sourceOf = (input: AgentMessageClassificationInput): string =>
-  `${input.agent ?? ''} ${input.helper ?? ''}`.toLowerCase()
+    const toolArgs = agentToolCallArguments(value)
+    const object = asRecord(toolArgs)
+    if (object == null) {
+      if (Array.isArray(toolArgs)) return AgentStructuredKind.GenericList
+      return undefined
+    }
 
-const contentOf = (input: AgentMessageClassificationInput): string => input.text?.trim() ?? ''
+    // Checked ahead of the single-array shapes below: a scaffold plan carries its own `stories`
+    // array (so the StoryPlan check would otherwise swallow it), and a runtime decision straight
+    // from the MODEL never carries `actor`/`worker` — those are added only once the decision is
+    // persisted onto a StoryDesign — so requiring them here missed every live model call.
+    if ('identity' in object && 'guestHome' in object && 'areas' in object && 'stories' in object) {
+      return AgentStructuredKind.ScaffoldPlan
+    }
+    if (Array.isArray(object.jobs) && Array.isArray(object.agents) && 'kv' in object) {
+      return AgentStructuredKind.RuntimeDecision
+    }
 
-/**
- * Source extraction is an internal context-reduction pass. Its terminal tool call contains only
- * line ranges, which are useful to the coder but add no useful information to a person's journal.
- */
-export const isAgentMessageHidden = (input: AgentMessageClassificationInput): boolean =>
-  actionOf(input) === 'source-extract'
-
-/** Maps the attribution that reached the event boundary to the visual specialist family. */
-export const agentMessageRoleOf = (input: AgentMessageClassificationInput): AgentMessageRole => {
-  const source = sourceOf(input)
-  const action = actionOf(input)
-
-  if (action === 'arbitrary-modification' || source.includes('orchestrator')) return AgentMessageRole.Orchestrator
-  if (source.includes('fix')) return AgentMessageRole.Repair
-  if (source.includes('coder') || source.includes('developer') || codeActions.has(action)) return AgentMessageRole.Developer
-  if (source.includes('visual') || source.includes('ui-helper')) return AgentMessageRole.VisualDesign
-  if (source.includes('ux-')) return AgentMessageRole.Ux
-  if (source.includes('business') || source.includes('ba-') || source.includes('analysis') || source.includes('analyst')) return AgentMessageRole.Analytical
-  if (source.includes('product') || source.includes('naming')) return AgentMessageRole.Product
-  if (source.includes('architect') || source.includes('arch') || source.includes('layout-helper') ||
-    source.includes('api-helper') || source.includes('access-helper') || source.includes('datalayer-helper') ||
-    source.includes('domain') || source.includes('nav-helper') || source.includes('ui-com-helper') ||
-    source.includes('ui-state-helper')) return AgentMessageRole.Architect
-  return AgentMessageRole.Technical
-}
+    if (Array.isArray(object.files)) return AgentStructuredKind.ArtifactSelection
+    if (Array.isArray(object.entities)) return AgentStructuredKind.EntitySelection
+    if (Array.isArray(object.stories)) return AgentStructuredKind.StoryPlan
+    if (Array.isArray(object.screens)) return AgentStructuredKind.ScreenPlan
+    if (Array.isArray(object.components)) return AgentStructuredKind.ComponentPlan
+    if (Array.isArray(object.transitions)) return AgentStructuredKind.TransitionPlan
+    if (Array.isArray(object.entries)) return AgentStructuredKind.EntrypointSelection
+    if (Array.isArray(object.candidates)) return AgentStructuredKind.CandidateRanking
+    if (Object.values(object).some(value => {
+      const entry = asRecord(value)
+      return entry != null && Array.isArray(entry.permissions) && 'level' in entry
+    })) return AgentStructuredKind.AccessPolicy
+    return AgentStructuredKind.GenericRecord
+  }
 
-/** Pulls a schema argument out of LangChain's serialised tool-call shape. */
-export const agentToolCallArguments = (value: unknown): unknown => {
-  if (!Array.isArray(value) || value.length !== 1) return value
-  const call = asRecord(value[0])
-  return call?.args ?? value
-}
+  const decisionAction = (action: string): boolean =>
+    action.startsWith('should-') || action.startsWith('is-') || action.includes('blueprint-case') || action.includes('choose-case')
 
-const structuredKindOf = (value: unknown): AgentStructuredKind | undefined => {
-  if (value == null) return undefined
+  const fileExtensionLanguage = (path: string): AgentCodeLanguage => {
+    const name = path.toLowerCase().split('?')[0]
+    if (/\.(tsx|jsx)$/.test(name)) return AgentCodeLanguage.ReactTsx
+    if (/\.css$/.test(name)) return AgentCodeLanguage.Css
+    if (/\.(ts|mts|cts|js|mjs|cjs)$/.test(name)) return AgentCodeLanguage.TypeScript
+    if (/\.json$/.test(name)) return AgentCodeLanguage.Json
+    return AgentCodeLanguage.Other
+  }
 
-  const toolArgs = agentToolCallArguments(value)
-  const object = asRecord(toolArgs)
-  if (object == null) {
-    if (Array.isArray(toolArgs)) return AgentStructuredKind.GenericList
-    return undefined
+  /** Finds the language of a unified diff from its destination (or source) file path. */
+  const agentDiffLanguageOf = (text: string): AgentCodeLanguage => {
+    const match = text.match(/^\+\+\+\s+(?:b\/)?(.+)$/m) ?? text.match(/^---\s+(?:a\/)?(.+)$/m)
+    return match == null ? AgentCodeLanguage.Other : fileExtensionLanguage(match[1])
   }
 
-  // Checked ahead of the single-array shapes below: a scaffold plan carries its own `stories`
-  // array (so the StoryPlan check would otherwise swallow it), and a runtime decision straight
-  // from the MODEL never carries `actor`/`worker` — those are added only once the decision is
-  // persisted onto a StoryDesign — so requiring them here missed every live model call.
-  if ('identity' in object && 'guestHome' in object && 'areas' in object && 'stories' in object) {
-    return AgentStructuredKind.ScaffoldPlan
+  const fencedLanguageOf = (text: string): AgentCodeLanguage | undefined => {
+    const match = text.match(/^```([\w+-]+)/m)
+    const language = match?.[1]?.toLowerCase()
+    if (language == null) return undefined
+    if (['tsx', 'jsx', 'react'].includes(language)) return AgentCodeLanguage.ReactTsx
+    if (language === 'css') return AgentCodeLanguage.Css
+    if (['ts', 'typescript', 'js', 'javascript'].includes(language)) return AgentCodeLanguage.TypeScript
+    if (language === 'json') return AgentCodeLanguage.Json
+    return AgentCodeLanguage.Other
   }
-  if (Array.isArray(object.jobs) && Array.isArray(object.agents) && 'kv' in object) {
-    return AgentStructuredKind.RuntimeDecision
+
+  /** Conservative code detection; prose with one identifier remains plain text. */
+  const agentCodeLanguageOf = (text: string): AgentCodeLanguage => {
+    const content = text.trim().replace(/^```[\w+-]*\n?|\n?```$/g, '')
+    const fenced = fencedLanguageOf(text)
+    if (fenced != null) return fenced
+    if (content === '') return AgentCodeLanguage.Other
+    try {
+      JSON.parse(content)
+      if (/^[{[]/.test(content)) return AgentCodeLanguage.Json
+    } catch {
+      // The remaining heuristics deliberately require source-like syntax.
+    }
+    if (/<[A-Za-z][\w.:-]*(?:\s[^>]*)?\/>|<[A-Za-z][\w.:-]*(?:\s[^>]*)?>/.test(content) &&
+      /\b(import|export|const|function|return)\b/.test(content)) return AgentCodeLanguage.ReactTsx
+    if (/(^|\n)\s*(?:[.#][\w-]+|[a-z][\w-]*(?:\[[^\]]+\])?)\s*\{[^}]*:[^}]*\}/.test(content)) {
+      return AgentCodeLanguage.Css
+    }
+    if (/\b(import|export|interface|type|const|let|function|class)\b/.test(content) &&
+      /[;{}]|=>/.test(content)) return AgentCodeLanguage.TypeScript
+    return AgentCodeLanguage.Other
   }
 
-  if (Array.isArray(object.files)) return AgentStructuredKind.ArtifactSelection
-  if (Array.isArray(object.entities)) return AgentStructuredKind.EntitySelection
-  if (Array.isArray(object.stories)) return AgentStructuredKind.StoryPlan
-  if (Array.isArray(object.screens)) return AgentStructuredKind.ScreenPlan
-  if (Array.isArray(object.components)) return AgentStructuredKind.ComponentPlan
-  if (Array.isArray(object.transitions)) return AgentStructuredKind.TransitionPlan
-  if (Array.isArray(object.entries)) return AgentStructuredKind.EntrypointSelection
-  if (Array.isArray(object.candidates)) return AgentStructuredKind.CandidateRanking
-  if (Object.values(object).some(value => {
-    const entry = asRecord(value)
-    return entry != null && Array.isArray(entry.permissions) && 'level' in entry
-  })) return AgentStructuredKind.AccessPolicy
-  return AgentStructuredKind.GenericRecord
-}
+  const isUnifiedDiff = (text: string): boolean =>
+    /^---\s+.+\n\+\+\+\s+.+/m.test(text) || (/^@@\s+[-+]/m.test(text) && /^(?:\+|-)[^+-]/m.test(text))
 
-const decisionAction = (action: string): boolean =>
-  action.startsWith('should-') || action.startsWith('is-') || action.includes('blueprint-case') || action.includes('choose-case')
+  const markdownKindOf = (text: string): AgentMarkdownKind | undefined => {
+    if (/^#{1,6}\s+/m.test(text) || /^>\s+/m.test(text) || /^\|.+\|\s*$/m.test(text)) {
+      return AgentMarkdownKind.Documentation
+    }
+    const listItems = text.match(/^\s*(?:[-*+]\s+|\d+[.)]\s+)/gm)?.length ?? 0
+    return listItems >= 2 ? AgentMarkdownKind.Documentation : undefined
+  }
 
-const fileExtensionLanguage = (path: string): AgentCodeLanguage => {
-  const name = path.toLowerCase().split('?')[0]
-  if (/\.(tsx|jsx)$/.test(name)) return AgentCodeLanguage.ReactTsx
-  if (/\.css$/.test(name)) return AgentCodeLanguage.Css
-  if (/\.(ts|mts|cts|js|mjs|cjs)$/.test(name)) return AgentCodeLanguage.TypeScript
-  if (/\.json$/.test(name)) return AgentCodeLanguage.Json
-  return AgentCodeLanguage.Other
-}
+  const isGenericStructure = (kind: AgentStructuredKind | undefined): boolean =>
+    kind == null || kind === AgentStructuredKind.GenericRecord || kind === AgentStructuredKind.GenericList ||
+    kind === AgentStructuredKind.GenericValue
+
+  const classifyAgentMessage = (input: AgentMessageClassificationInput): AgentMessagePresentation => {
+    const role = agentMessageRoleOf(input)
+    const action = actionOf(input)
+    const text = contentOf(input)
+    const structure = structuredKindOf(input.value)
+
+    if (input.outputType === 'tool_calls') {
+      // A single pinned-schema call resolves to its own card; everything else — several calls in
+      // one turn, an unconstrained agent-loop action, or a shape too generic to be informative —
+      // is a tool call, not a schema result.
+      const isMultiCall = Array.isArray(input.value) && input.value.length > 1
+      const isToolCalls = isMultiCall || agentLoopActions.has(action) || isGenericStructure(structure)
+      return {
+        category: AgentMessageCategory.Structured,
+        structure: isToolCalls ? AgentStructuredKind.ToolCalls : structure!,
+        role,
+      }
+    }
+    if (structure != null) return { category: AgentMessageCategory.Structured, structure, role }
+    const actionStructure = structuredActions[action]
+    if (actionStructure != null) return { category: AgentMessageCategory.Structured, structure: actionStructure, role }
+    if (decisionAction(action)) return { category: AgentMessageCategory.Structured, structure: AgentStructuredKind.Decision, role }
+    if (isUnifiedDiff(text) || action === 'update-code') {
+      return { category: AgentMessageCategory.Diff, language: agentDiffLanguageOf(text), role }
+    }
+    if (codeActions.has(action) || fencedLanguageOf(text) != null || agentCodeLanguageOf(text) !== AgentCodeLanguage.Other) {
+      return { category: AgentMessageCategory.Code, language: agentCodeLanguageOf(text), role }
+    }
+    const document = documentActions[action] ?? markdownKindOf(text)
+    if (document != null) return { category: AgentMessageCategory.Markdown, document, role }
+    if (input.value != null) {
+      return {
+        category: AgentMessageCategory.Structured,
+        structure: Array.isArray(input.value) ? AgentStructuredKind.GenericList : AgentStructuredKind.GenericValue,
+        role,
+      }
+    }
+    return { category: AgentMessageCategory.Plain, role }
+  }
 
-/** Finds the language of a unified diff from its destination (or source) file path. */
-export const agentDiffLanguageOf = (text: string): AgentCodeLanguage => {
-  const match = text.match(/^\+\+\+\s+(?:b\/)?(.+)$/m) ?? text.match(/^---\s+(?:a\/)?(.+)$/m)
-  return match == null ? AgentCodeLanguage.Other : fileExtensionLanguage(match[1])
+  return {
+    isAgentMessageHidden, agentMessageRoleOf, agentToolCallArguments, agentDiffLanguageOf, agentCodeLanguageOf,
+    isUnifiedDiff, classifyAgentMessage,
+  }
 }
 
-const fencedLanguageOf = (text: string): AgentCodeLanguage | undefined => {
-  const match = text.match(/^```([\w+-]+)/m)
-  const language = match?.[1]?.toLowerCase()
-  if (language == null) return undefined
-  if (['tsx', 'jsx', 'react'].includes(language)) return AgentCodeLanguage.ReactTsx
-  if (language === 'css') return AgentCodeLanguage.Css
-  if (['ts', 'typescript', 'js', 'javascript'].includes(language)) return AgentCodeLanguage.TypeScript
-  if (language === 'json') return AgentCodeLanguage.Json
-  return AgentCodeLanguage.Other
-}
+export const agentPresentationHelper = createAgentPresentationHelper()
 
-/** Conservative code detection; prose with one identifier remains plain text. */
-export const agentCodeLanguageOf = (text: string): AgentCodeLanguage => {
-  const content = text.trim().replace(/^```[\w+-]*\n?|\n?```$/g, '')
-  const fenced = fencedLanguageOf(text)
-  if (fenced != null) return fenced
-  if (content === '') return AgentCodeLanguage.Other
-  try {
-    JSON.parse(content)
-    if (/^[{[]/.test(content)) return AgentCodeLanguage.Json
-  } catch {
-    // The remaining heuristics deliberately require source-like syntax.
-  }
-  if (/<[A-Za-z][\w.:-]*(?:\s[^>]*)?\/>|<[A-Za-z][\w.:-]*(?:\s[^>]*)?>/.test(content) &&
-    /\b(import|export|const|function|return)\b/.test(content)) return AgentCodeLanguage.ReactTsx
-  if (/(^|\n)\s*(?:[.#][\w-]+|[a-z][\w-]*(?:\[[^\]]+\])?)\s*\{[^}]*:[^}]*\}/.test(content)) {
-    return AgentCodeLanguage.Css
-  }
-  if (/\b(import|export|interface|type|const|let|function|class)\b/.test(content) &&
-    /[;{}]|=>/.test(content)) return AgentCodeLanguage.TypeScript
-  return AgentCodeLanguage.Other
-}
+/** @deprecated compat:factory-refactor — use `agentPresentationHelper.isAgentMessageHidden(…)` */
+export const isAgentMessageHidden = (input: AgentMessageClassificationInput): boolean =>
+  agentPresentationHelper.isAgentMessageHidden(input)
 
-export const isUnifiedDiff = (text: string): boolean =>
-  /^---\s+.+\n\+\+\+\s+.+/m.test(text) || (/^@@\s+[-+]/m.test(text) && /^(?:\+|-)[^+-]/m.test(text))
+/** @deprecated compat:factory-refactor — use `agentPresentationHelper.agentMessageRoleOf(…)` */
+export const agentMessageRoleOf = (input: AgentMessageClassificationInput): AgentMessageRole =>
+  agentPresentationHelper.agentMessageRoleOf(input)
 
-const markdownKindOf = (text: string): AgentMarkdownKind | undefined => {
-  if (/^#{1,6}\s+/m.test(text) || /^>\s+/m.test(text) || /^\|.+\|\s*$/m.test(text)) {
-    return AgentMarkdownKind.Documentation
-  }
-  const listItems = text.match(/^\s*(?:[-*+]\s+|\d+[.)]\s+)/gm)?.length ?? 0
-  return listItems >= 2 ? AgentMarkdownKind.Documentation : undefined
-}
+/** @deprecated compat:factory-refactor — use `agentPresentationHelper.agentToolCallArguments(…)` */
+export const agentToolCallArguments = (value: unknown): unknown => agentPresentationHelper.agentToolCallArguments(value)
 
-const isGenericStructure = (kind: AgentStructuredKind | undefined): boolean =>
-  kind == null || kind === AgentStructuredKind.GenericRecord || kind === AgentStructuredKind.GenericList ||
-  kind === AgentStructuredKind.GenericValue
-
-export const classifyAgentMessage = (input: AgentMessageClassificationInput): AgentMessagePresentation => {
-  const role = agentMessageRoleOf(input)
-  const action = actionOf(input)
-  const text = contentOf(input)
-  const structure = structuredKindOf(input.value)
-
-  if (input.outputType === 'tool_calls') {
-    // A single pinned-schema call resolves to its own card; everything else — several calls in
-    // one turn, an unconstrained agent-loop action, or a shape too generic to be informative —
-    // is a tool call, not a schema result.
-    const isMultiCall = Array.isArray(input.value) && input.value.length > 1
-    const isToolCalls = isMultiCall || agentLoopActions.has(action) || isGenericStructure(structure)
-    return {
-      category: AgentMessageCategory.Structured,
-      structure: isToolCalls ? AgentStructuredKind.ToolCalls : structure!,
-      role,
-    }
-  }
-  if (structure != null) return { category: AgentMessageCategory.Structured, structure, role }
-  const actionStructure = structuredActions[action]
-  if (actionStructure != null) return { category: AgentMessageCategory.Structured, structure: actionStructure, role }
-  if (decisionAction(action)) return { category: AgentMessageCategory.Structured, structure: AgentStructuredKind.Decision, role }
-  if (isUnifiedDiff(text) || action === 'update-code') {
-    return { category: AgentMessageCategory.Diff, language: agentDiffLanguageOf(text), role }
-  }
-  if (codeActions.has(action) || fencedLanguageOf(text) != null || agentCodeLanguageOf(text) !== AgentCodeLanguage.Other) {
-    return { category: AgentMessageCategory.Code, language: agentCodeLanguageOf(text), role }
-  }
-  const document = documentActions[action] ?? markdownKindOf(text)
-  if (document != null) return { category: AgentMessageCategory.Markdown, document, role }
-  if (input.value != null) {
-    return {
-      category: AgentMessageCategory.Structured,
-      structure: Array.isArray(input.value) ? AgentStructuredKind.GenericList : AgentStructuredKind.GenericValue,
-      role,
-    }
-  }
-  return { category: AgentMessageCategory.Plain, role }
-}
+/** @deprecated compat:factory-refactor — use `agentPresentationHelper.agentDiffLanguageOf(…)` */
+export const agentDiffLanguageOf = (text: string): AgentCodeLanguage => agentPresentationHelper.agentDiffLanguageOf(text)
+
+/** @deprecated compat:factory-refactor — use `agentPresentationHelper.agentCodeLanguageOf(…)` */
+export const agentCodeLanguageOf = (text: string): AgentCodeLanguage => agentPresentationHelper.agentCodeLanguageOf(text)
+
+/** @deprecated compat:factory-refactor — use `agentPresentationHelper.isUnifiedDiff(…)` */
+export const isUnifiedDiff = (text: string): boolean => agentPresentationHelper.isUnifiedDiff(text)
+
+/** @deprecated compat:factory-refactor — use `agentPresentationHelper.classifyAgentMessage(…)` */
+export const classifyAgentMessage = (input: AgentMessageClassificationInput): AgentMessagePresentation =>
+  agentPresentationHelper.classifyAgentMessage(input)

package/src/agent/types.local.ts

@@ -1 +1,3 @@
-export type RecordValue = Record<string, unknown>
+export interface RecordValue {
+  [key: string]: unknown
+}

package/src/areas/index.ts

@@ -1,4 +1,5 @@
 export type * from './types.js'
+export type * from './tenancy/types.js'
 
 export * from './consts.js'
 export * from './tenancy.js'

package/src/areas/tenancy/types.ts

@@ -0,0 +1,23 @@
+import type { Blueprint } from '../../blueprint/types.js'
+import type { ProjectArea } from '../consts.js'
+import type { ProjectTenancy } from '../types.js'
+
+/** Which of a product's audiences act inside a tenant organization. */
+export interface TenancyHelper {
+  /**
+   * The tenancy of a resolved blueprint.
+   *
+   * Total, like `landingGatePreferenceOf`: an absent layer, an absent key and a value this deploy
+   * cannot read all answer {@link NO_TENANCY}. Only a literal `true` turns a flag on, because a flag
+   * read as on by mistake splits a product's people into organizations nobody asked for, while one
+   * read as off leaves the application exactly as it was before tenancy existed.
+   */
+  tenancyOf: (blueprint?: Pick<Blueprint, 'experience'> | null) => ProjectTenancy
+  /**
+   * Whether an AREA's people act inside a tenant organization.
+   *
+   * Guest has no organization to act in, and admin is the project owner, who stands above every
+   * tenant rather than inside one — so both are never tenanted, whatever the flags say.
+   */
+  tenantedArea: (area: ProjectArea, tenancy: ProjectTenancy) => boolean
+}

package/src/areas/tenancy.ts

@@ -1,33 +1,34 @@
 import type { Blueprint } from '../blueprint/types.js'
 import { ProjectArea, NO_TENANCY } from './consts.js'
 import type { ProjectTenancy } from './types.js'
+import type { TenancyHelper } from './tenancy/types.js'
 
-/**
- * The tenancy of a resolved blueprint.
- *
- * Total, like `landingGatePreferenceOf`: an absent layer, an absent key and a value this deploy
- * cannot read all answer {@link NO_TENANCY}. Only a literal `true` turns a flag on, because a flag
- * read as on by mistake splits a product's people into organizations nobody asked for, while one
- * read as off leaves the application exactly as it was before tenancy existed.
- */
-export const tenancyOf = (blueprint?: Pick<Blueprint, 'experience'> | null): ProjectTenancy => {
-  const tenancy = blueprint?.experience?.tenancy
-  const operators = tenancy?.operators === true
-  const users = tenancy?.users === true
+export const createTenancyHelper = (): TenancyHelper => {
+  const tenancyOf = (blueprint?: Pick<Blueprint, 'experience'> | null): ProjectTenancy => {
+    const tenancy = blueprint?.experience?.tenancy
+    const operators = tenancy?.operators === true
+    const users = tenancy?.users === true
 
-  return operators || users ? Object.freeze({ operators, users }) : NO_TENANCY
-}
+    return operators || users ? Object.freeze({ operators, users }) : NO_TENANCY
+  }
 
-/**
- * Whether an AREA's people act inside a tenant organization.
- *
- * Guest has no organization to act in, and admin is the project owner, who stands above every
- * tenant rather than inside one — so both are never tenanted, whatever the flags say.
- */
-export const tenantedArea = (area: ProjectArea, tenancy: ProjectTenancy): boolean => {
-  switch (area) {
-    case ProjectArea.User: return tenancy.users === true
-    case ProjectArea.Operator: return tenancy.operators === true
-    default: return false
+  const tenantedArea = (area: ProjectArea, tenancy: ProjectTenancy): boolean => {
+    switch (area) {
+      case ProjectArea.User: return tenancy.users === true
+      case ProjectArea.Operator: return tenancy.operators === true
+      default: return false
+    }
   }
+
+  return { tenancyOf, tenantedArea }
 }
+
+export const tenancyHelper = createTenancyHelper()
+
+/** @deprecated compat:factory-refactor — use `tenancyHelper.tenancyOf(…)` */
+export const tenancyOf = (blueprint?: Pick<Blueprint, 'experience'> | null): ProjectTenancy =>
+  tenancyHelper.tenancyOf(blueprint)
+
+/** @deprecated compat:factory-refactor — use `tenancyHelper.tenantedArea(…)` */
+export const tenantedArea = (area: ProjectArea, tenancy: ProjectTenancy): boolean =>
+  tenancyHelper.tenantedArea(area, tenancy)

package/src/ba/connecting/types.ts

@@ -0,0 +1,45 @@
+import type { StoryDraft } from '../../areas/types.js'
+import type { ConnectingStoryDraft, MergedStoryDraft } from '../types.js'
+
+/** The connecting stories of a flow: how many it may carry, and where each one lands. */
+export interface ConnectingStoryHelper {
+  /**
+   * How many connecting stories one flow may carry.
+   *
+   * An N-step chain has N-1 joints, and a connecting story exists to bridge one of them — so the
+   * flow sizes its own supporting cast, and a three-step product can never end up with eight list
+   * screens. It is a CEILING, not a target: the prompt is told to write as few as its rules actually
+   * derived, and most flows land well below this.
+   *
+   * The real reason for a hard number: every story here becomes a full develop run the project's
+   * owner pays for.
+   */
+  connectingStoryCap: (flowCount: number) => number
+  /**
+   * Interleave the connecting stories into the flow they were derived from.
+   *
+   * `after` is an ANCHOR, not a position: it names the flow story whose result the connecting story
+   * displays, so the connecting story lands immediately behind it — which is also immediately in
+   * front of the step it leads into. The result is ONE ordered list, and it is the order records are
+   * created in.
+   *
+   * This is the only place the anchor is interpreted. Both halves of the feature — the prompt that
+   * produces it and the pipeline that persists the result — read it through here, or the two drift
+   * and nothing fails loudly enough to notice. The CLAMPED anchor is carried out on each connective
+   * entry as `after`, which is what the story card's `follows` relationship is written from.
+   *
+   * Four properties are deliberate:
+   *
+   * - **The flow subsequence is never disturbed.** Strip the connecting stories back out and you have
+   *   `flow`, in `flow` order: story N still implements numbered step N. Everything that finds the
+   *   primary story depends on that.
+   * - **Nothing precedes the first flow story.** An anchor below 1 is clamped up rather than opening a
+   *   position in front of the flow — nothing can be listed before the step that produced it, and
+   *   story 1 stays the enabling action.
+   * - **A placement is advice; the story is work already paid for.** An anchor past the end means
+   *   "at the end", and one that is not a number at all means the front of the flow. Neither is a
+   *   reason to lose a story.
+   * - **Ties keep the model's order**, which is the only ranking anything has.
+   */
+  mergeConnectingStories: (flow: StoryDraft[], connecting: ConnectingStoryDraft[]) => MergedStoryDraft[]
+}

package/src/ba/connecting.ts

@@ -0,0 +1,64 @@
+import type { StoryDraft } from "../areas/types.js"
+import type { ConnectingStoryDraft, MergedStoryDraft } from "./types.js"
+import { StoryKind } from "./consts.js"
+import type { ConnectingStoryHelper } from './connecting/types.js'
+
+export const createConnectingStoryHelper = (): ConnectingStoryHelper => {
+  const connectingStoryCap = (flowCount: number): number => Math.max(flowCount - 1, 0)
+
+  /** Collapse case and whitespace, so "the same story twice" is recognised as such. */
+  const canonical = (story: string): string => story.trim().replace(/\s+/g, ' ').toLowerCase()
+
+  const mergeConnectingStories = (
+    flow: StoryDraft[], connecting: ConnectingStoryDraft[]
+  ): MergedStoryDraft[] => {
+    if (flow.length < 1) {
+      return []
+    }
+
+    const seen = new Set(flow.map(({ story }) => canonical(story)))
+    const placed: Array<{ draft: ConnectingStoryDraft, at: number }> = []
+
+    for (const draft of connecting) {
+      const text = canonical(draft.story)
+      // A connecting story that repeats a flow story is not a second story: it is one develop run
+      // spent twice AND — since the home-screen detector matches its answer back by exact text — a
+      // second record that answer could resolve to.
+      if (text === '' || seen.has(text)) {
+        continue
+      }
+      seen.add(text)
+
+      const after = Number(draft.after)
+      placed.push({
+        draft,
+        at: Number.isFinite(after) ? Math.min(Math.max(Math.trunc(after), 1), flow.length) : 1,
+      })
+    }
+
+    // Over the cap, the LATEST-anchored go: a story late in the flow gates the fewest steps behind
+    // it, while the queue that hands step 1 to step 2 is what makes everything after it reachable.
+    // The sort is stable, so two stories on the same step keep the order they were derived in.
+    const surviving = placed
+      .map((entry, order) => ({ ...entry, order }))
+      .sort((a, b) => a.at - b.at || a.order - b.order)
+      .slice(0, connectingStoryCap(flow.length))
+
+    // Bucket N holds what comes immediately after flow story N (1-based, as the prompt numbers them).
+    const buckets: ConnectingStoryDraft[][] = flow.map(() => [])
+    for (const { draft, at } of surviving) {
+      buckets[at - 1]!.push(draft)
+    }
+
+    return flow.flatMap(({ story, area }, index) => [
+      { story, area, kind: StoryKind.Flow },
+      ...buckets[index]!.map(draft => (
+        { story: draft.story.trim(), area: draft.area, kind: StoryKind.Connective, after: index + 1 }
+      )),
+    ])
+  }
+
+  return { connectingStoryCap, mergeConnectingStories }
+}
+
+export const connectingStoryHelper = createConnectingStoryHelper()