@owlmeans/viable-common 0.0.43 → 0.0.45

package/src/topology/card.ts

@@ -1,106 +1,101 @@
 import { SubProject } from '../slot/consts.js'
 import { TOPOLOGY_VERSION } from './consts.js'
-import { orderPackages } from './helpers.js'
-import type { TargetPackageDescriptor, TargetPackageKind, TopologyDescriptor } from './types.js'
+import { topologyHelper } from './resolve.js'
+import type { TargetPackageDescriptor, TargetPackageKind, TopologyDescriptor, TopologyMeta } from './types.js'
+import { KINDS, ROLES } from './consts.local.js'
+import type { TopologyCardHelper } from './card/types.js'
 
-/** What `.agents/memory/topology.md` carries in its frontmatter. */
-export interface TopologyMeta extends TopologyDescriptor {
-  version: number
-  updatedAt: string
-}
+export const createTopologyCardHelper = (): TopologyCardHelper => {
+  const asStrings = (value: unknown): string[] =>
+    Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : []
 
-const ROLES = new Set<string>(Object.values(SubProject))
-const KINDS = new Set<TargetPackageKind>(['library', 'bundle'])
+  /**
+   * Read a package descriptor out of whatever the file held.
+   *
+   * Everything is narrowed rather than trusted: the file is on the target's volume, where a person,
+   * a GitHub pull or a previous platform version may have written it. A descriptor that cannot be
+   * narrowed is DROPPED, never repaired — a package with no name or no recognisable role would
+   * otherwise resolve a path somewhere real and wrong.
+   */
+  const parsePackage = (value: unknown): TargetPackageDescriptor | null => {
+    if (value == null || typeof value !== 'object') return null
+    const raw = value as Record<string, unknown>
+    const name = typeof raw.name === 'string' ? raw.name.trim() : ''
+    if (name === '' || name.includes('/') || name.startsWith('.')) return null
+    const roles = asStrings(raw.roles).filter((role): role is SubProject => ROLES.has(role))
+    if (roles.length === 0) return null
+    const kind = KINDS.has(raw.kind as TargetPackageKind) ? raw.kind as TargetPackageKind : 'bundle'
+    const areas = asStrings(raw.areas)
+    const queues = asStrings(raw.queues)
 
-const asStrings = (value: unknown): string[] =>
-  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : []
+    return {
+      name,
+      roles,
+      kind,
+      dependsOn: asStrings(raw.dependsOn),
+      ...(areas.length > 0 ? { areas: areas as TargetPackageDescriptor['areas'] } : {}),
+      ...(queues.length > 0 ? { queues } : {}),
+    }
+  }
 
-/**
- * Read a package descriptor out of whatever the file held.
- *
- * Everything is narrowed rather than trusted: the file is on the target's volume, where a person,
- * a GitHub pull or a previous platform version may have written it. A descriptor that cannot be
- * narrowed is DROPPED, never repaired — a package with no name or no recognisable role would
- * otherwise resolve a path somewhere real and wrong.
- */
-const parsePackage = (value: unknown): TargetPackageDescriptor | null => {
-  if (value == null || typeof value !== 'object') return null
-  const raw = value as Record<string, unknown>
-  const name = typeof raw.name === 'string' ? raw.name.trim() : ''
-  if (name === '' || name.includes('/') || name.startsWith('.')) return null
-  const roles = asStrings(raw.roles).filter((role): role is SubProject => ROLES.has(role))
-  if (roles.length === 0) return null
-  const kind = KINDS.has(raw.kind as TargetPackageKind) ? raw.kind as TargetPackageKind : 'bundle'
-  const areas = asStrings(raw.areas)
-  const queues = asStrings(raw.queues)
+  const parseTopologyMeta = (data: unknown): TopologyDescriptor | null => {
+    if (data == null || typeof data !== 'object') return null
+    const raw = data as Record<string, unknown>
+    if (typeof raw.dir !== 'string' || raw.dir.trim() === '') return null
+    const packages = Array.isArray(raw.packages)
+      ? raw.packages.map(parsePackage).filter((pkg): pkg is TargetPackageDescriptor => pkg != null)
+      : []
+    if (packages.length === 0) return null
 
-  return {
-    name,
-    roles,
-    kind,
-    dependsOn: asStrings(raw.dependsOn),
-    ...(areas.length > 0 ? { areas: areas as TargetPackageDescriptor['areas'] } : {}),
-    ...(queues.length > 0 ? { queues } : {}),
+    return {
+      id: typeof raw.id === 'string' && raw.id !== '' ? raw.id : 'recorded',
+      dir: raw.dir.trim(),
+      packages,
+    }
   }
-}
 
-/**
- * Narrow a parsed frontmatter block into a topology, or answer `null`.
- *
- * `null` means "use the layout default", and every caller treats it that way. A topology file
- * written by a platform version this one cannot read must not stop a project from building — the
- * arrangement it describes is almost certainly still the default one.
- */
-export const parseTopologyMeta = (data: unknown): TopologyDescriptor | null => {
-  if (data == null || typeof data !== 'object') return null
-  const raw = data as Record<string, unknown>
-  if (typeof raw.dir !== 'string' || raw.dir.trim() === '') return null
-  const packages = Array.isArray(raw.packages)
-    ? raw.packages.map(parsePackage).filter((pkg): pkg is TargetPackageDescriptor => pkg != null)
-    : []
-  if (packages.length === 0) return null
+  const topologyMeta = (topology: TopologyDescriptor): TopologyMeta => ({
+    ...topology,
+    packages: topologyHelper.orderPackages(topology.packages),
+    version: TOPOLOGY_VERSION,
+    updatedAt: new Date().toISOString(),
+  })
+
+  const renderTopologyCard = (topology: TopologyDescriptor): string => {
+    const ordered = topologyHelper.orderPackages(topology.packages)
+    const rows = ordered.map(pkg => {
+      const deps = pkg.dependsOn.length > 0 ? pkg.dependsOn.join(', ') : '—'
+      const extra = [
+        ...(pkg.areas != null ? [`areas: ${pkg.areas.join(', ')}`] : []),
+        ...(pkg.queues != null ? [`queues: ${pkg.queues.join(', ')}`] : []),
+      ].join('; ')
 
-  return {
-    id: typeof raw.id === 'string' && raw.id !== '' ? raw.id : 'recorded',
-    dir: raw.dir.trim(),
-    packages,
+      return `| \`${topology.dir}/${pkg.name}\` | ${pkg.roles.join(', ')} | ${pkg.kind} | ${deps} | ${extra === '' ? '—' : extra} |`
+    })
+
+    return [
+      '# Topology',
+      '',
+      'Which packages this project has, what each one is, and which compile against which.',
+      'Built in the order of the table — a `library` must be built before anything importing it.',
+      '',
+      '| Package | Roles | Kind | Depends on | Notes |',
+      '|---|---|---|---|---|',
+      ...rows,
+      '',
+    ].join('\n')
   }
+
+  return { parseTopologyMeta, topologyMeta, renderTopologyCard }
 }
 
-export const topologyMeta = (topology: TopologyDescriptor): TopologyMeta => ({
-  ...topology,
-  packages: orderPackages(topology.packages),
-  version: TOPOLOGY_VERSION,
-  updatedAt: new Date().toISOString(),
-})
+export const topologyCardHelper = createTopologyCardHelper()
 
-/**
- * The body of `.agents/memory/topology.md` — what a model reads, and what a person reads.
- *
- * Rendered from the descriptor rather than maintained beside it, for the same reason the layout
- * tables are: a card that disagrees with the frontmatter teaches the wrong tree.
- */
-export const renderTopologyCard = (topology: TopologyDescriptor): string => {
-  const ordered = orderPackages(topology.packages)
-  const rows = ordered.map(pkg => {
-    const deps = pkg.dependsOn.length > 0 ? pkg.dependsOn.join(', ') : '—'
-    const extra = [
-      ...(pkg.areas != null ? [`areas: ${pkg.areas.join(', ')}`] : []),
-      ...(pkg.queues != null ? [`queues: ${pkg.queues.join(', ')}`] : []),
-    ].join('; ')
+/** @deprecated compat:factory-refactor — use `topologyCardHelper.parseTopologyMeta(…)` */
+export const parseTopologyMeta = (data: unknown): TopologyDescriptor | null => topologyCardHelper.parseTopologyMeta(data)
 
-    return `| \`${topology.dir}/${pkg.name}\` | ${pkg.roles.join(', ')} | ${pkg.kind} | ${deps} | ${extra === '' ? '—' : extra} |`
-  })
+/** @deprecated compat:factory-refactor — use `topologyCardHelper.topologyMeta(…)` */
+export const topologyMeta = (topology: TopologyDescriptor): TopologyMeta => topologyCardHelper.topologyMeta(topology)
 
-  return [
-    '# Topology',
-    '',
-    'Which packages this project has, what each one is, and which compile against which.',
-    'Built in the order of the table — a `library` must be built before anything importing it.',
-    '',
-    '| Package | Roles | Kind | Depends on | Notes |',
-    '|---|---|---|---|---|',
-    ...rows,
-    '',
-  ].join('\n')
-}
+/** @deprecated compat:factory-refactor — use `topologyCardHelper.renderTopologyCard(…)` */
+export const renderTopologyCard = (topology: TopologyDescriptor): string => topologyCardHelper.renderTopologyCard(topology)

package/src/topology/consts.local.ts

@@ -0,0 +1,6 @@
+import { SubProject } from '../slot/consts.js'
+import type { TargetPackageKind } from './types.js'
+
+export const ROLES = new Set<string>(Object.values(SubProject))
+
+export const KINDS = new Set<TargetPackageKind>(['library', 'bundle'])

package/src/topology/helpers.ts

@@ -1,138 +1,33 @@
-import { TargetLayout } from '../integrity/consts.js'
 import type { ProjectArea } from '../areas/consts.js'
 import type { SubProject } from '../slot/consts.js'
-import { LAYOUT_TOPOLOGIES, DEFAULT_TOPOLOGY } from './consts.js'
-import type {
-  ResolvedTopology, TargetPackageDescriptor, TopologyDescriptor,
-} from './types.js'
+import { topologyHelper } from './resolve.js'
+import type { ResolvedTopology, TargetPackageDescriptor, TopologyDescriptor } from './types.js'
 
-/**
- * Order the packages so that nothing is built before what it compiles against.
- *
- * Kahn's algorithm, with two deliberate tolerances. An edge to a package the topology does not
- * hold is DROPPED rather than fatal — a project may declare a dependency on something a pull has
- * not brought in yet, and refusing to order the tree would take the whole build down over one
- * name. A cycle leaves its members unvisited, and they are appended in declaration order: a cycle
- * cannot be built correctly in any order, so the useful behaviour is to build it in the order
- * somebody wrote rather than to throw.
- */
-export const orderPackages = (packages: TargetPackageDescriptor[]): TargetPackageDescriptor[] => {
-  const known = new Set(packages.map(pkg => pkg.name))
-  const index = new Map(packages.map((pkg, at) => [pkg.name, at]))
-  const pending = new Map(packages.map(pkg => [
-    pkg.name, pkg.dependsOn.filter(dep => known.has(dep) && dep !== pkg.name).length,
-  ]))
-  const dependents = new Map<string, string[]>()
-  for (const pkg of packages) {
-    for (const dep of pkg.dependsOn) {
-      if (!known.has(dep) || dep === pkg.name) continue
-      dependents.set(dep, [...dependents.get(dep) ?? [], pkg.name])
-    }
-  }
+/** @deprecated compat:factory-refactor — use `topologyHelper.orderPackages(…)` */
+export const orderPackages = (packages: TargetPackageDescriptor[]): TargetPackageDescriptor[] =>
+  topologyHelper.orderPackages(packages)
 
-  const byName = new Map(packages.map(pkg => [pkg.name, pkg]))
-  const out: TargetPackageDescriptor[] = []
-  // Ready packages are taken in DECLARATION order, not in the order they became ready. Both are
-  // correct builds; only one is the same list every time and the same list a person wrote, and
-  // this order is compared against the shipped layout tables by a test.
-  const ready = packages.filter(pkg => pending.get(pkg.name) === 0).map(pkg => pkg.name)
-  const take = (): string | undefined => {
-    if (ready.length === 0) return undefined
-    let at = 0
-    for (let i = 1; i < ready.length; i++) {
-      if ((index.get(ready[i]) ?? 0) < (index.get(ready[at]) ?? 0)) at = i
-    }
+/** @deprecated compat:factory-refactor — use `topologyHelper.resolveTopology(…)` */
+export const resolveTopology = (topology: TopologyDescriptor): ResolvedTopology =>
+  topologyHelper.resolveTopology(topology)
 
-    return ready.splice(at, 1)[0]
-  }
+/** @deprecated compat:factory-refactor — use `topologyHelper.packageForRole(…)` */
+export const packageForRole = (topology: ResolvedTopology, role: SubProject): TargetPackageDescriptor | null =>
+  topologyHelper.packageForRole(topology, role)
 
-  for (let name = take(); name != null; name = take()) {
-    const pkg = byName.get(name)
-    if (pkg == null) continue
-    out.push(pkg)
-    for (const next of dependents.get(name) ?? []) {
-      const left = (pending.get(next) ?? 0) - 1
-      pending.set(next, left)
-      if (left === 0) ready.push(next)
-    }
-  }
-
-  const seen = new Set(out.map(pkg => pkg.name))
-
-  return [...out, ...packages.filter(pkg => !seen.has(pkg.name))]
-}
-
-/** Resolve the derived halves — build order, library order and the role index. */
-export const resolveTopology = (topology: TopologyDescriptor): ResolvedTopology => {
-  const ordered = orderPackages(topology.packages)
-  const byRole: Partial<Record<SubProject, TargetPackageDescriptor[]>> = {}
-  for (const pkg of ordered) {
-    for (const role of pkg.roles) {
-      byRole[role] = [...byRole[role] ?? [], pkg]
-    }
-  }
-
-  return {
-    ...topology,
-    packages: ordered,
-    build: ordered.map(pkg => pkg.name),
-    libraries: ordered.filter(pkg => pkg.kind === 'library').map(pkg => pkg.name),
-    byRole,
-  }
-}
-
-/** The default topology for a layout already decided. */
-export const topologyOf = (layout: TargetLayout): TopologyDescriptor =>
-  LAYOUT_TOPOLOGIES[layout] ?? DEFAULT_TOPOLOGY
-
-/**
- * The directory a role names, or `null` when this topology has no package for it.
- *
- * `null` rather than the role's own name: a command aimed at a package the tree does not have must
- * fail where it is issued. Answering with a plausible directory runs it somewhere real and wrong,
- * which is how a type check once ran against the shared package instead of the one under repair.
- */
-export const packageForRole = (
-  topology: ResolvedTopology, role: SubProject
-): TargetPackageDescriptor | null => topology.byRole[role]?.[0] ?? null
-
-/** Every package holding a role — more than one only where a topology splits that role. */
-export const packagesForRole = (
-  topology: ResolvedTopology, role: SubProject
-): TargetPackageDescriptor[] => topology.byRole[role] ?? []
-
-/** The package serving an area, for a topology that splits the browser app across several. */
+/** @deprecated compat:factory-refactor — use `topologyHelper.packageForArea(…)` */
 export const packageForArea = (
   topology: ResolvedTopology, role: SubProject, area: ProjectArea
-): TargetPackageDescriptor | null => {
-  const candidates = packagesForRole(topology, role)
-  return candidates.find(pkg => pkg.areas?.includes(area) === true)
-    ?? candidates.find(pkg => pkg.areas == null)
-    ?? candidates[0]
-    ?? null
-}
+): TargetPackageDescriptor | null => topologyHelper.packageForArea(topology, role, area)
 
-/** `<dir>/<package>` — the only place a topology directory is composed. */
+/** @deprecated compat:factory-refactor — use `topologyHelper.packageDir(…)` */
 export const packageDir = (topology: TopologyDescriptor, pkg: TargetPackageDescriptor): string =>
-  `${topology.dir}/${pkg.name}`
+  topologyHelper.packageDir(topology, pkg)
 
-/**
- * Merge a package into a topology, by name.
- *
- * This is the ADOPTION path: a package that arrived with a GitHub pull is classified once and
- * recorded here, so the next run addresses the tree that exists rather than re-deriving one that
- * does not. Replacing by name rather than appending keeps a re-classification idempotent.
- */
-export const withPackage = (
-  topology: TopologyDescriptor, pkg: TargetPackageDescriptor
-): TopologyDescriptor => ({
-  ...topology,
-  packages: topology.packages.some(known => known.name === pkg.name)
-    ? topology.packages.map(known => known.name === pkg.name ? pkg : known)
-    : [...topology.packages, pkg],
-})
+/** @deprecated compat:factory-refactor — use `topologyHelper.withPackage(…)` */
+export const withPackage = (topology: TopologyDescriptor, pkg: TargetPackageDescriptor): TopologyDescriptor =>
+  topologyHelper.withPackage(topology, pkg)
 
-/** Whether two topologies describe the same arrangement — used to skip a needless rewrite. */
+/** @deprecated compat:factory-refactor — use `topologyHelper.sameTopology(…)` */
 export const sameTopology = (a: TopologyDescriptor, b: TopologyDescriptor): boolean =>
-  JSON.stringify(orderPackages(a.packages)) === JSON.stringify(orderPackages(b.packages))
-    && a.dir === b.dir
+  topologyHelper.sameTopology(a, b)

package/src/topology/index.ts

@@ -1,5 +1,8 @@
 export type * from './types.js'
+export type * from './resolve/types.js'
+export type * from './card/types.js'
 
 export * from './consts.js'
+export * from './resolve.js'
 export * from './helpers.js'
 export * from './card.js'

package/src/topology/resolve/types.ts

@@ -0,0 +1,47 @@
+import type { ProjectArea } from '../../areas/consts.js'
+import type { TargetLayout } from '../../integrity/consts.js'
+import type { SubProject } from '../../slot/consts.js'
+import type { ResolvedTopology, TargetPackageDescriptor, TopologyDescriptor } from '../types.js'
+
+/** A target's package arrangement: build order, the role index, and where each package lives. */
+export interface TopologyHelper {
+  /**
+   * Order the packages so that nothing is built before what it compiles against.
+   *
+   * Kahn's algorithm, with two deliberate tolerances. An edge to a package the topology does not
+   * hold is DROPPED rather than fatal — a project may declare a dependency on something a pull has
+   * not brought in yet, and refusing to order the tree would take the whole build down over one
+   * name. A cycle leaves its members unvisited, and they are appended in declaration order: a cycle
+   * cannot be built correctly in any order, so the useful behaviour is to build it in the order
+   * somebody wrote rather than to throw.
+   */
+  orderPackages: (packages: TargetPackageDescriptor[]) => TargetPackageDescriptor[]
+  /** Resolve the derived halves — build order, library order and the role index. */
+  resolveTopology: (topology: TopologyDescriptor) => ResolvedTopology
+  /** The default topology for a layout already decided. */
+  topologyOf: (layout: TargetLayout) => TopologyDescriptor
+  /**
+   * The directory a role names, or `null` when this topology has no package for it.
+   *
+   * `null` rather than the role's own name: a command aimed at a package the tree does not have must
+   * fail where it is issued. Answering with a plausible directory runs it somewhere real and wrong,
+   * which is how a type check once ran against the shared package instead of the one under repair.
+   */
+  packageForRole: (topology: ResolvedTopology, role: SubProject) => TargetPackageDescriptor | null
+  /** Every package holding a role — more than one only where a topology splits that role. */
+  packagesForRole: (topology: ResolvedTopology, role: SubProject) => TargetPackageDescriptor[]
+  /** The package serving an area, for a topology that splits the browser app across several. */
+  packageForArea: (topology: ResolvedTopology, role: SubProject, area: ProjectArea) => TargetPackageDescriptor | null
+  /** `<dir>/<package>` — the only place a topology directory is composed. */
+  packageDir: (topology: TopologyDescriptor, pkg: TargetPackageDescriptor) => string
+  /**
+   * Merge a package into a topology, by name.
+   *
+   * This is the ADOPTION path: a package that arrived with a GitHub pull is classified once and
+   * recorded here, so the next run addresses the tree that exists rather than re-deriving one that
+   * does not. Replacing by name rather than appending keeps a re-classification idempotent.
+   */
+  withPackage: (topology: TopologyDescriptor, pkg: TargetPackageDescriptor) => TopologyDescriptor
+  /** Whether two topologies describe the same arrangement — used to skip a needless rewrite. */
+  sameTopology: (a: TopologyDescriptor, b: TopologyDescriptor) => boolean
+}

package/src/topology/resolve.ts

@@ -0,0 +1,118 @@
+import { TargetLayout } from '../integrity/consts.js'
+import type { ProjectArea } from '../areas/consts.js'
+import type { SubProject } from '../slot/consts.js'
+import { LAYOUT_TOPOLOGIES, DEFAULT_TOPOLOGY } from './consts.js'
+import type {
+  ResolvedTopology, TargetPackageDescriptor, TopologyDescriptor,
+} from './types.js'
+import type { TopologyHelper } from './resolve/types.js'
+
+export const createTopologyHelper = (): TopologyHelper => {
+  const orderPackages = (packages: TargetPackageDescriptor[]): TargetPackageDescriptor[] => {
+    const known = new Set(packages.map(pkg => pkg.name))
+    const index = new Map(packages.map((pkg, at) => [pkg.name, at]))
+    const pending = new Map(packages.map(pkg => [
+      pkg.name, pkg.dependsOn.filter(dep => known.has(dep) && dep !== pkg.name).length,
+    ]))
+    const dependents = new Map<string, string[]>()
+    for (const pkg of packages) {
+      for (const dep of pkg.dependsOn) {
+        if (!known.has(dep) || dep === pkg.name) continue
+        dependents.set(dep, [...dependents.get(dep) ?? [], pkg.name])
+      }
+    }
+
+    const byName = new Map(packages.map(pkg => [pkg.name, pkg]))
+    const out: TargetPackageDescriptor[] = []
+    // Ready packages are taken in DECLARATION order, not in the order they became ready. Both are
+    // correct builds; only one is the same list every time and the same list a person wrote, and
+    // this order is compared against the shipped layout tables by a test.
+    const ready = packages.filter(pkg => pending.get(pkg.name) === 0).map(pkg => pkg.name)
+    const take = (): string | undefined => {
+      if (ready.length === 0) return undefined
+      let at = 0
+      for (let i = 1; i < ready.length; i++) {
+        if ((index.get(ready[i]) ?? 0) < (index.get(ready[at]) ?? 0)) at = i
+      }
+
+      return ready.splice(at, 1)[0]
+    }
+
+    for (let name = take(); name != null; name = take()) {
+      const pkg = byName.get(name)
+      if (pkg == null) continue
+      out.push(pkg)
+      for (const next of dependents.get(name) ?? []) {
+        const left = (pending.get(next) ?? 0) - 1
+        pending.set(next, left)
+        if (left === 0) ready.push(next)
+      }
+    }
+
+    const seen = new Set(out.map(pkg => pkg.name))
+
+    return [...out, ...packages.filter(pkg => !seen.has(pkg.name))]
+  }
+
+  const resolveTopology = (topology: TopologyDescriptor): ResolvedTopology => {
+    const ordered = orderPackages(topology.packages)
+    const byRole: Partial<Record<SubProject, TargetPackageDescriptor[]>> = {}
+    for (const pkg of ordered) {
+      for (const role of pkg.roles) {
+        byRole[role] = [...byRole[role] ?? [], pkg]
+      }
+    }
+
+    return {
+      ...topology,
+      packages: ordered,
+      build: ordered.map(pkg => pkg.name),
+      libraries: ordered.filter(pkg => pkg.kind === 'library').map(pkg => pkg.name),
+      byRole,
+    }
+  }
+
+  const topologyOf = (layout: TargetLayout): TopologyDescriptor =>
+    LAYOUT_TOPOLOGIES[layout] ?? DEFAULT_TOPOLOGY
+
+  const packageForRole = (
+    topology: ResolvedTopology, role: SubProject
+  ): TargetPackageDescriptor | null => topology.byRole[role]?.[0] ?? null
+
+  const packagesForRole = (
+    topology: ResolvedTopology, role: SubProject
+  ): TargetPackageDescriptor[] => topology.byRole[role] ?? []
+
+  const packageForArea = (
+    topology: ResolvedTopology, role: SubProject, area: ProjectArea
+  ): TargetPackageDescriptor | null => {
+    const candidates = packagesForRole(topology, role)
+    return candidates.find(pkg => pkg.areas?.includes(area) === true)
+      ?? candidates.find(pkg => pkg.areas == null)
+      ?? candidates[0]
+      ?? null
+  }
+
+  const packageDir = (topology: TopologyDescriptor, pkg: TargetPackageDescriptor): string =>
+    `${topology.dir}/${pkg.name}`
+
+  const withPackage = (
+    topology: TopologyDescriptor, pkg: TargetPackageDescriptor
+  ): TopologyDescriptor => ({
+    ...topology,
+    packages: topology.packages.some(known => known.name === pkg.name)
+      ? topology.packages.map(known => known.name === pkg.name ? pkg : known)
+      : [...topology.packages, pkg],
+  })
+
+  const sameTopology = (a: TopologyDescriptor, b: TopologyDescriptor): boolean =>
+    JSON.stringify(orderPackages(a.packages)) === JSON.stringify(orderPackages(b.packages))
+      && a.dir === b.dir
+
+  return {
+    orderPackages, resolveTopology, topologyOf, packageForRole, packagesForRole, packageForArea, packageDir,
+    withPackage, sameTopology,
+  }
+}
+
+export const topologyHelper = createTopologyHelper()

package/src/topology/types.ts

@@ -84,3 +84,9 @@ export interface ResolvedTopology extends TopologyDescriptor {
   /** Role → the packages holding it, in topology order. */
   byRole: Partial<Record<SubProject, TargetPackageDescriptor[]>>
 }
+
+/** What `.agents/memory/topology.md` carries in its frontmatter. */
+export interface TopologyMeta extends TopologyDescriptor {
+  version: number
+  updatedAt: string
+}

package/tests/blueprint.spec.ts

@@ -1,8 +1,7 @@
 import { describe, expect, test } from 'bun:test'
 import { landingGatePreferenceOf, LandingGatePreference } from '../src/blueprint/index.js'
 import type { Blueprint } from '../src/blueprint/index.js'
-import { ViableSkill } from '../src/skills/consts.js'
-import { ViablePersona } from '../src/skills/roles.js'
+import { ViablePersona, ViableSkill } from '../src/skills/consts.js'
 
 /** Just enough of a blueprint to read a preference from — the shape a test builds. */
 const base = (extra: Partial<Blueprint> = {}): Blueprint => ({

package/tests/branding.spec.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'bun:test'
 
-import { BRANDING_ENV_KEYS, brandingEnv } from '../src/branding.js'
-import { metadataConfigs, metadataLists } from '../src/consts.js'
+import { brandingEnv } from '../src/branding.js'
+import { BRANDING_ENV_KEYS, metadataConfigs, metadataLists } from '../src/consts.js'
 
 /**
  * `BRANDING_CREDIT` is the one key whose ABSENCE means something different from an explicit

package/tests/connect-convert.spec.ts

@@ -8,7 +8,7 @@ import { connectProtocols } from '../src/connect/entrypoints.js'
 import { connectRef } from '../src/connect/references.js'
 import {
   ConnectCapabilitiesSchema, ConnectConvertCreateBodySchema, ConnectConvertProceedBodySchema,
-  ConnectInquiryParamsSchema, ConnectPipelineResumeBodySchema, InquiryAnswerSchema
+  ConnectConvertStartBodySchema, ConnectInquiryParamsSchema, ConnectPipelineResumeBodySchema, InquiryAnswerSchema
 } from '../src/connect/schemas.js'
 import { ConnectExecutor } from '../src/connect/consts.js'
 import { InquiryKind } from '@owlmeans/llm-common'
@@ -39,6 +39,7 @@ describe('viable-common - the conversion additions to the connector contract', (
       ['InquiryAnswerSchema', InquiryAnswerSchema],
       ['ConnectInquiryParamsSchema', ConnectInquiryParamsSchema],
       ['ConnectConvertCreateBodySchema', ConnectConvertCreateBodySchema],
+      ['ConnectConvertStartBodySchema', ConnectConvertStartBodySchema],
       ['ConnectConvertProceedBodySchema', ConnectConvertProceedBodySchema],
       ['ConnectPipelineResumeBodySchema', ConnectPipelineResumeBodySchema],
       ['ConnectCapabilitiesSchema', ConnectCapabilitiesSchema],
@@ -81,6 +82,25 @@ describe('viable-common - the conversion additions to the connector contract', (
     expect(proceed({ decision: 'teleport' })).toBe(false)
   })
 
+  test('start and proceed carry the person\'s confirmation, and nothing else new', () => {
+    const ajv = compiler()
+    const start = ajv.compile(ConnectConvertStartBodySchema as never)
+    const proceed = ajv.compile(ConnectConvertProceedBodySchema as never)
+
+    expect(start({})).toBe(true)
+    expect(start({ confirm: true })).toBe(true)
+    // An unset optional serialised as `null` is "not confirmed", never a refused body.
+    expect(start({ confirm: null })).toBe(true)
+    expect(start({ confirm: 'yes' })).toBe(false)
+    expect(start({ restart: true })).toBe(false)
+    expect(proceed({ decision: ConversionDecision.Implement, confirm: true })).toBe(true)
+    expect(proceed({ decision: ConversionDecision.Implement, confirm: 1 })).toBe(false)
+  })
+
+  test('the start declares its body, so a confirmation reaches the handler', () => {
+    expect(entrypointOf(connect.convert.start).contract?.requestSchemas.body).toEqual(ConnectConvertStartBodySchema as never)
+  })
+
   test('capabilities accept an executor kind this platform has never heard of', () => {
     // The SDK and the platform ship separately: a connector built against a newer package must not
     // be refused a session because it advertises one more capability than this platform knows.