@elevasis/core 0.23.0 → 0.24.0

package/src/organization-model/helpers.ts

@@ -1,279 +1,327 @@
 import type { OrganizationModel, OrganizationModelSystemEntry } from './types'
 import type { ContentNode } from './content-kinds/types'
+import type { JsonValue } from './domains/systems'
 import type { ResourceEntry } from './domains/resources'
-
+
 // W1A has landed: ContentNode and SystemEntry (with content + subsystems) are now
 // defined in their canonical locations.
-// Phase 4: removed locally-scoped inferred types for deleted compound-domain schemas
-// (SalesPipeline, ProspectingBuildTemplate, etc.). migration-helpers.ts imports them directly.
-
-/**
- * SystemEntry extended with the recursive tree slots (`content`, `subsystems`).
- * `OrganizationModelSystemEntry` is inferred from `SystemEntrySchema: ZodType<SystemEntry>`
- * so it already carries these fields; this alias re-exports it under the tree-walker name
- * for clarity at call sites.
- */
+// Phase 4: removed locally-scoped inferred types for deleted compound-domain schemas
+// (SalesPipeline, ProspectingBuildTemplate, etc.). migration-helpers.ts imports them directly.
+
+/**
+ * SystemEntry extended with the recursive tree slots (`content`, `subsystems`).
+ * `OrganizationModelSystemEntry` is inferred from `SystemEntrySchema: ZodType<SystemEntry>`
+ * so it already carries these fields; this alias re-exports it under the tree-walker name
+ * for clarity at call sites.
+ */
 export type { ContentNode }
 export type SystemEntryWithTree = OrganizationModelSystemEntry
 
-export function defaultPathFor(id: string): string {
-  return `/${id.replaceAll('.', '/')}`
-}
-
-export function parentIdOf(id: string): string | undefined {
-  const index = id.lastIndexOf('.')
-  return index === -1 ? undefined : id.slice(0, index)
-}
-
-/**
- * Return all entries of an OM domain map sorted by their declared `order` field.
- * Use this whenever iteration order matters for UI or deterministic output.
- */
-export function listDomain<T extends { id: string; order: number }>(record: Record<string, T>): T[] {
-  return Object.values(record).sort((a, b) => a.order - b.order)
-}
-
-export function findById(
-  systems: Record<string, OrganizationModelSystemEntry>,
-  id: string
-): OrganizationModelSystemEntry | undefined {
-  return systems[id]
-}
-
-export function findByPath(
-  systems: Record<string, OrganizationModelSystemEntry>,
-  path: string
-): OrganizationModelSystemEntry | undefined {
-  return Object.values(systems).find((system) => (system.path ?? system.ui?.path ?? defaultPathFor(system.id)) === path)
-}
-
-export function childrenOf(
-  systems: Record<string, OrganizationModelSystemEntry>,
-  id: string
-): OrganizationModelSystemEntry[] {
-  const prefix = `${id}.`
-  return Object.values(systems).filter(
-    (system) => system.id.startsWith(prefix) && !system.id.slice(prefix.length).includes('.')
-  )
-}
-
-export function topLevel(systems: Record<string, OrganizationModelSystemEntry>): OrganizationModelSystemEntry[] {
-  return Object.values(systems).filter((system) => !system.id.includes('.'))
-}
-
-export function ancestorsOf(
-  systems: Record<string, OrganizationModelSystemEntry>,
-  id: string
-): OrganizationModelSystemEntry[] {
-  const segments = id.split('.')
-  const ids = segments.map((_, index) => segments.slice(0, index + 1).join('.'))
-  return ids
-    .map((ancestorId) => findById(systems, ancestorId))
-    .filter((system): system is OrganizationModelSystemEntry => Boolean(system))
+function childSystemsOf(system: SystemEntryWithTree): Record<string, SystemEntryWithTree> {
+  return system.systems ?? system.subsystems ?? {}
 }
-
-export function parentOf(
-  systems: Record<string, OrganizationModelSystemEntry>,
-  id: string
-): OrganizationModelSystemEntry | undefined {
-  const parentId = parentIdOf(id)
-  return parentId ? findById(systems, parentId) : undefined
-}
-
-function inheritedValue<T>(
-  systems: Record<string, OrganizationModelSystemEntry>,
-  id: string,
-  getValue: (system: OrganizationModelSystemEntry) => T | undefined
-): T | undefined {
-  return ancestorsOf(systems, id)
-    .slice()
-    .reverse()
-    .map(getValue)
-    .find((value): value is T => value !== undefined)
-}
-
-export function uiPositionFor(systems: Record<string, OrganizationModelSystemEntry>, id: string) {
-  return inheritedValue(systems, id, (system) => system.uiPosition)
-}
-
-export function requiresAdminFor(systems: Record<string, OrganizationModelSystemEntry>, id: string): boolean {
-  return inheritedValue(systems, id, (system) => system.requiresAdmin) ?? false
-}
-
-export function devOnlyFor(systems: Record<string, OrganizationModelSystemEntry>, id: string): boolean {
-  return inheritedValue(systems, id, (system) => system.devOnly || system.lifecycle === 'beta' || undefined) ?? false
-}
-
-// ---------------------------------------------------------------------------
-// Recursive system-tree helpers (Wave 1B)
-// These operate on the NEW recursive System shape introduced by W1A, where
-// `model.systems` is `Record<LocalId, SystemEntry>` (nested via `subsystems`).
-// `SystemEntry` here is the extended interface defined at the top of this file.
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve a system by its dot-separated path string.
- *
- * `getSystem(model, 'sales.crm.dispositions')` walks:
- *   `model.systems['sales'] → .subsystems['crm'] → .subsystems['dispositions']`
- *
- * Returns `undefined` if any segment is missing.
- */
-export function getSystem(model: OrganizationModel, path: string): SystemEntryWithTree | undefined {
-  const segments = path.split('.')
-  // model.systems is typed as Record<string, OrganizationModelSystemEntry>; cast
-  // to SystemEntryWithTree (which extends it with optional content + subsystems).
-  let current: Record<string, SystemEntryWithTree> = model.systems as Record<string, SystemEntryWithTree>
-  let node: SystemEntryWithTree | undefined
+
+export function defaultPathFor(id: string): string {
+  return `/${id.replaceAll('.', '/')}`
+}
+
+export function parentIdOf(id: string): string | undefined {
+  const index = id.lastIndexOf('.')
+  return index === -1 ? undefined : id.slice(0, index)
+}
+
+/**
+ * Return all entries of an OM domain map sorted by their declared `order` field.
+ * Use this whenever iteration order matters for UI or deterministic output.
+ */
+export function listDomain<T extends { id: string; order: number }>(record: Record<string, T>): T[] {
+  return Object.values(record).sort((a, b) => a.order - b.order)
+}
+
+export function findById(
+  systems: Record<string, OrganizationModelSystemEntry>,
+  id: string
+): OrganizationModelSystemEntry | undefined {
+  return systems[id]
+}
+
+export function findByPath(
+  systems: Record<string, OrganizationModelSystemEntry>,
+  path: string
+): OrganizationModelSystemEntry | undefined {
+  return Object.values(systems).find((system) => (system.path ?? system.ui?.path ?? defaultPathFor(system.id)) === path)
+}
+
+export function childrenOf(
+  systems: Record<string, OrganizationModelSystemEntry>,
+  id: string
+): OrganizationModelSystemEntry[] {
+  const prefix = `${id}.`
+  return Object.values(systems).filter(
+    (system) => system.id.startsWith(prefix) && !system.id.slice(prefix.length).includes('.')
+  )
+}
+
+export function topLevel(systems: Record<string, OrganizationModelSystemEntry>): OrganizationModelSystemEntry[] {
+  return Object.values(systems).filter((system) => !system.id.includes('.'))
+}
+
+export function ancestorsOf(
+  systems: Record<string, OrganizationModelSystemEntry>,
+  id: string
+): OrganizationModelSystemEntry[] {
+  const segments = id.split('.')
+  const ids = segments.map((_, index) => segments.slice(0, index + 1).join('.'))
+  return ids
+    .map((ancestorId) => findById(systems, ancestorId))
+    .filter((system): system is OrganizationModelSystemEntry => Boolean(system))
+}
+
+export function parentOf(
+  systems: Record<string, OrganizationModelSystemEntry>,
+  id: string
+): OrganizationModelSystemEntry | undefined {
+  const parentId = parentIdOf(id)
+  return parentId ? findById(systems, parentId) : undefined
+}
+
+function inheritedValue<T>(
+  systems: Record<string, OrganizationModelSystemEntry>,
+  id: string,
+  getValue: (system: OrganizationModelSystemEntry) => T | undefined
+): T | undefined {
+  return ancestorsOf(systems, id)
+    .slice()
+    .reverse()
+    .map(getValue)
+    .find((value): value is T => value !== undefined)
+}
+
+export function uiPositionFor(systems: Record<string, OrganizationModelSystemEntry>, id: string) {
+  return inheritedValue(systems, id, (system) => system.uiPosition)
+}
+
+export function requiresAdminFor(systems: Record<string, OrganizationModelSystemEntry>, id: string): boolean {
+  return inheritedValue(systems, id, (system) => system.requiresAdmin) ?? false
+}
+
+export function devOnlyFor(systems: Record<string, OrganizationModelSystemEntry>, id: string): boolean {
+  return inheritedValue(systems, id, (system) => system.devOnly || system.lifecycle === 'beta' || undefined) ?? false
+}
+
+// ---------------------------------------------------------------------------
+// Recursive system-tree helpers (Wave 1B)
+// These operate on the NEW recursive System shape introduced by W1A, where
+// `model.systems` is `Record<LocalId, SystemEntry>` (nested via `subsystems`).
+// `SystemEntry` here is the extended interface defined at the top of this file.
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a system by its dot-separated path string.
+ *
+ * `getSystem(model, 'sales.crm.dispositions')` walks:
+ *   `model.systems['sales'] → .subsystems['crm'] → .subsystems['dispositions']`
+ *
+ * Returns `undefined` if any segment is missing.
+ */
+export function getSystem(model: OrganizationModel, path: string): SystemEntryWithTree | undefined {
+  const segments = path.split('.')
+  // model.systems is typed as Record<string, OrganizationModelSystemEntry>; cast
+  // to SystemEntryWithTree (which extends it with optional content + subsystems).
+  let current: Record<string, SystemEntryWithTree> = model.systems as Record<string, SystemEntryWithTree>
+  let node: SystemEntryWithTree | undefined
   for (const seg of segments) {
     node = current[seg]
     if (node === undefined) return undefined
-    current = node.subsystems ?? {}
+    current = childSystemsOf(node)
   }
-  return node
-}
-
-/**
- * Return the root-first ancestor chain for a system path, including the system
- * itself as the last element.
- *
- * `getSystemAncestors(model, 'sales.crm')` → `[salesEntry, crmEntry]`
- *
- * Returns an empty array if the path cannot be resolved.
- */
-export function getSystemAncestors(model: OrganizationModel, path: string): SystemEntryWithTree[] {
-  const segments = path.split('.')
-  const result: SystemEntryWithTree[] = []
-  let current: Record<string, SystemEntryWithTree> = model.systems as Record<string, SystemEntryWithTree>
-  for (const seg of segments) {
+  return node
+}
+
+/**
+ * Return the root-first ancestor chain for a system path, including the system
+ * itself as the last element.
+ *
+ * `getSystemAncestors(model, 'sales.crm')` → `[salesEntry, crmEntry]`
+ *
+ * Returns an empty array if the path cannot be resolved.
+ */
+export function getSystemAncestors(model: OrganizationModel, path: string): SystemEntryWithTree[] {
+  const segments = path.split('.')
+  const result: SystemEntryWithTree[] = []
+  let current: Record<string, SystemEntryWithTree> = model.systems as Record<string, SystemEntryWithTree>
+  for (const seg of segments) {
     const node = current[seg]
     if (node === undefined) return []
     result.push(node)
-    current = node.subsystems ?? {}
+    current = childSystemsOf(node)
   }
-  return result
-}
-
-/**
- * Flat depth-first enumeration of every system in the model tree.
- * Each entry carries the computed full path and the system node.
- * Order: parent before children (pre-order DFS).
- *
- * Example result paths: `'sales'`, `'sales.crm'`, `'sales.crm.dispositions'`
- */
-export function listAllSystems(model: OrganizationModel): Array<{ path: string; system: SystemEntryWithTree }> {
-  const results: Array<{ path: string; system: SystemEntryWithTree }> = []
-
-  function walk(map: Record<string, SystemEntryWithTree>, prefix: string): void {
-    for (const [localId, system] of Object.entries(map)) {
+  return result
+}
+
+/**
+ * Flat depth-first enumeration of every system in the model tree.
+ * Each entry carries the computed full path and the system node.
+ * Order: parent before children (pre-order DFS).
+ *
+ * Example result paths: `'sales'`, `'sales.crm'`, `'sales.crm.dispositions'`
+ */
+export function listAllSystems(model: OrganizationModel): Array<{ path: string; system: SystemEntryWithTree }> {
+  const results: Array<{ path: string; system: SystemEntryWithTree }> = []
+
+  function walk(map: Record<string, SystemEntryWithTree>, prefix: string): void {
+    for (const [localId, system] of Object.entries(map)) {
       const fullPath = prefix ? `${prefix}.${localId}` : localId
       results.push({ path: fullPath, system })
-      if (system.subsystems) {
-        walk(system.subsystems, fullPath)
+      const childSystems = childSystemsOf(system)
+      if (Object.keys(childSystems).length > 0) {
+        walk(childSystems, fullPath)
       }
     }
   }
+
+  walk(model.systems as Record<string, SystemEntryWithTree>, '')
+  return results
+}
+
+/**
+ * Resolve a content node by its qualified id (`<system-path>:<local-content-id>`).
+ *
+ * `getContent(model, 'sales.crm:default-pipeline')` resolves the `sales.crm`
+ * system and then looks up `system.content['default-pipeline']`.
+ *
+ * Returns `undefined` if the system or local id is not found, or if the
+ * qualified id does not contain exactly one `:` separator.
+ */
+export function getContent(model: OrganizationModel, qualifiedId: string): ContentNode | undefined {
+  const colonIndex = qualifiedId.indexOf(':')
+  if (colonIndex === -1) return undefined
+  const systemPath = qualifiedId.slice(0, colonIndex)
+  const localId = qualifiedId.slice(colonIndex + 1)
+  if (!systemPath || !localId) return undefined
+  const system = getSystem(model, systemPath)
+  return system?.content?.[localId]
+}
+
+/**
+ * Resolve the layered content view for a system.
+ *
+ * Returns:
+ * - `own`: the system's direct `content` map (empty record if none).
+ * - `inherited`: ancestor content nodes that are NOT shadowed by `own` or by a
+ *   closer ancestor (depth-wins cascade, same as CSS specificity).
+ *
+ * Shadow rule: if two ancestors both declare `content['x']`, the deeper one
+ * wins. If the system itself declares `content['x']`, neither ancestor entry
+ * for `'x'` appears in `inherited`.
+ *
+ * `resolveSystemContent(model, 'sales.crm')` with both `sales.content['x']`
+ * and `sales.crm.content['x']` defined → `own` contains `'x'`, `inherited`
+ * contains NO entry for `'x'` from `sales`.
+ */
+export function resolveSystemContent(
+  model: OrganizationModel,
+  path: string
+): { own: Record<string, ContentNode>; inherited: Array<{ fromPath: string; node: ContentNode; localId: string }> } {
+  const ancestors = getSystemAncestors(model, path)
+  if (ancestors.length === 0) return { own: {}, inherited: [] }
+
+  const system = ancestors[ancestors.length - 1]
+  const own: Record<string, ContentNode> = { ...(system.content ?? {}) }
+
+  // Collect ancestor entries depth-first (deepest ancestor first, excluding self).
+  // We reconstruct paths for each ancestor by slicing the path segments.
+  const segments = path.split('.')
+  const shadowedIds = new Set(Object.keys(own))
+  const inherited: Array<{ fromPath: string; node: ContentNode; localId: string }> = []
+
+  // Iterate ancestors from deepest-parent to root so deeper wins.
+  for (let i = ancestors.length - 2; i >= 0; i--) {
+    const ancestor = ancestors[i]
+    const ancestorPath = segments.slice(0, i + 1).join('.')
+    const contentMap = ancestor.content ?? {}
+    for (const [localId, node] of Object.entries(contentMap)) {
+      if (!shadowedIds.has(localId)) {
+        shadowedIds.add(localId)
+        inherited.push({ fromPath: ancestorPath, node, localId })
+      }
+    }
+  }
+
+  // Re-order inherited so shallower ancestors come first (root-first display order).
+  inherited.reverse()
+
+  return { own, inherited }
+}
 
-  walk(model.systems as Record<string, SystemEntryWithTree>, '')
-  return results
+function isPlainJsonObject(value: JsonValue | undefined): value is Record<string, JsonValue> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
-/**
- * Resolve a content node by its qualified id (`<system-path>:<local-content-id>`).
- *
- * `getContent(model, 'sales.crm:default-pipeline')` resolves the `sales.crm`
- * system and then looks up `system.content['default-pipeline']`.
- *
- * Returns `undefined` if the system or local id is not found, or if the
- * qualified id does not contain exactly one `:` separator.
- */
-export function getContent(model: OrganizationModel, qualifiedId: string): ContentNode | undefined {
-  const colonIndex = qualifiedId.indexOf(':')
-  if (colonIndex === -1) return undefined
-  const systemPath = qualifiedId.slice(0, colonIndex)
-  const localId = qualifiedId.slice(colonIndex + 1)
-  if (!systemPath || !localId) return undefined
-  const system = getSystem(model, systemPath)
-  return system?.content?.[localId]
+function mergeJsonConfig(
+  base: Record<string, JsonValue>,
+  override: Record<string, JsonValue>
+): Record<string, JsonValue> {
+  const result: Record<string, JsonValue> = { ...base }
+
+  for (const [key, value] of Object.entries(override)) {
+    const existing = result[key]
+    result[key] =
+      isPlainJsonObject(existing) && isPlainJsonObject(value) ? mergeJsonConfig(existing, value) : value
+  }
+
+  return result
 }
 
 /**
- * Resolve the layered content view for a system.
- *
- * Returns:
- * - `own`: the system's direct `content` map (empty record if none).
- * - `inherited`: ancestor content nodes that are NOT shadowed by `own` or by a
- *   closer ancestor (depth-wins cascade, same as CSS specificity).
+ * Resolve a system's effective local config.
  *
- * Shadow rule: if two ancestors both declare `content['x']`, the deeper one
- * wins. If the system itself declares `content['x']`, neither ancestor entry
- * for `'x'` appears in `inherited`.
- *
- * `resolveSystemContent(model, 'sales.crm')` with both `sales.content['x']`
- * and `sales.crm.content['x']` defined → `own` contains `'x'`, `inherited`
- * contains NO entry for `'x'` from `sales`.
+ * Bridge-era `content` entries with `(kind, type) === ('config', 'kv')` are
+ * projected first, then first-class `system.config` overlays them. This keeps
+ * direct config authoring authoritative while continuing to read old content.
  */
-export function resolveSystemContent(
-  model: OrganizationModel,
-  path: string
-): { own: Record<string, ContentNode>; inherited: Array<{ fromPath: string; node: ContentNode; localId: string }> } {
-  const ancestors = getSystemAncestors(model, path)
-  if (ancestors.length === 0) return { own: {}, inherited: [] }
-
-  const system = ancestors[ancestors.length - 1]
-  const own: Record<string, ContentNode> = { ...(system.content ?? {}) }
-
-  // Collect ancestor entries depth-first (deepest ancestor first, excluding self).
-  // We reconstruct paths for each ancestor by slicing the path segments.
-  const segments = path.split('.')
-  const shadowedIds = new Set(Object.keys(own))
-  const inherited: Array<{ fromPath: string; node: ContentNode; localId: string }> = []
+export function resolveSystemConfig(model: OrganizationModel, path: string): Record<string, JsonValue> {
+  const system = getSystem(model, path)
+  if (system === undefined) return {}
 
-  // Iterate ancestors from deepest-parent to root so deeper wins.
-  for (let i = ancestors.length - 2; i >= 0; i--) {
-    const ancestor = ancestors[i]
-    const ancestorPath = segments.slice(0, i + 1).join('.')
-    const contentMap = ancestor.content ?? {}
-    for (const [localId, node] of Object.entries(contentMap)) {
-      if (!shadowedIds.has(localId)) {
-        shadowedIds.add(localId)
-        inherited.push({ fromPath: ancestorPath, node, localId })
-      }
+  let resolved: Record<string, JsonValue> = {}
+  for (const node of Object.values(system.content ?? {})) {
+    if (node.kind !== 'config' || node.type !== 'kv') continue
+    const entries = node.data?.entries
+    if (isPlainJsonObject(entries as JsonValue)) {
+      resolved = mergeJsonConfig(resolved, entries as Record<string, JsonValue>)
     }
   }
 
-  // Re-order inherited so shallower ancestors come first (root-first display order).
-  inherited.reverse()
-
-  return { own, inherited }
+  return mergeJsonConfig(resolved, system.config ?? {})
 }
 
 /**
  * Return all resources whose `systemPath` belongs to the given system.
- *
- * When `includeDescendants` is false (default), only resources whose
- * `systemPath` exactly matches `systemPath` are returned.
- *
- * When `includeDescendants` is true, resources attached to any descendant
- * system are also included. Descendant matching is segment-aware: the path
- * `'sales'` does NOT match `'salesforce.foo'` because segment boundaries are
- * enforced by splitting on `'.'`.
- *
- * @example
- * getResourcesForSystem(model, 'sales')
- * // → resources where systemPath === 'sales'
- *
- * getResourcesForSystem(model, 'sales', { includeDescendants: true })
- * // → resources where systemPath === 'sales' OR systemPath starts with 'sales.'
- */
-export function getResourcesForSystem(
-  model: OrganizationModel,
-  systemPath: string,
-  options: { includeDescendants?: boolean } = {}
-): ResourceEntry[] {
-  const { includeDescendants = false } = options
-  const prefix = systemPath + '.'
-  return Object.values(model.resources ?? {}).filter(
-    (r) => r.systemPath === systemPath || (includeDescendants && r.systemPath.startsWith(prefix))
-  )
-}
+ *
+ * When `includeDescendants` is false (default), only resources whose
+ * `systemPath` exactly matches `systemPath` are returned.
+ *
+ * When `includeDescendants` is true, resources attached to any descendant
+ * system are also included. Descendant matching is segment-aware: the path
+ * `'sales'` does NOT match `'salesforce.foo'` because segment boundaries are
+ * enforced by splitting on `'.'`.
+ *
+ * @example
+ * getResourcesForSystem(model, 'sales')
+ * // → resources where systemPath === 'sales'
+ *
+ * getResourcesForSystem(model, 'sales', { includeDescendants: true })
+ * // → resources where systemPath === 'sales' OR systemPath starts with 'sales.'
+ */
+export function getResourcesForSystem(
+  model: OrganizationModel,
+  systemPath: string,
+  options: { includeDescendants?: boolean } = {}
+): ResourceEntry[] {
+  const { includeDescendants = false } = options
+  const prefix = systemPath + '.'
+  return Object.values(model.resources ?? {}).filter(
+    (r) => r.systemPath === systemPath || (includeDescendants && r.systemPath.startsWith(prefix))
+  )
+}