@elevasis/core 0.23.0 → 0.24.0

package/src/organization-model/migration-helpers.ts

@@ -1,249 +1,252 @@
-/**
- * Migration helpers — Phase 4 internals swap
- *
- * External signatures are UNCHANGED from the pre-Phase-4 era so callers remain
- * mechanical. Internally, all compound-domain reads (model.sales.pipelines,
- * model.prospecting.*, model.projects.*) are replaced by walking system.content
- * via listAllSystems() and filtering by (kind, type).
- *
- * Registry entries used:
- *   'schema:pipeline'      — one pipeline per owning system
- *   'schema:stage'         — stage within a pipeline; parentContentId = pipeline local id
- *   'schema:template'      — prospecting build template
- *   'schema:template-step' — step within a template; parentContentId = template local id
- *   'schema:status-flow'   — status set for a project/milestone/task scope
- *   'schema:status'        — single status within a flow; parentContentId = status-flow local id
- */
-
+/**
+ * Migration helpers — Phase 4 internals swap
+ *
+ * External signatures are UNCHANGED from the pre-Phase-4 era so callers remain
+ * mechanical. Internally, compatibility reads for old compound-domain data
+ * walk System.content via listAllSystems() and filter by (kind, type).
+ *
+ * Compatibility registry entries read:
+ *   'schema:pipeline'      — one pipeline per owning system
+ *   'schema:stage'         — stage within a pipeline; parentContentId = pipeline local id
+ *   'schema:template'      — prospecting build template
+ *   'schema:template-step' — step within a template; parentContentId = template local id
+ *   'schema:status-flow'   — status set for a project/milestone/task scope
+ *   'schema:status'        — single status within a flow; parentContentId = status-flow local id
+ */
+
 import type { OrganizationModel } from './types'
 import type { z } from 'zod'
 import type { SalesPipelineSchema, SalesStageSchema } from './domains/sales'
-import type { ProspectingBuildTemplateSchema, ProspectingLifecycleStageSchema } from './domains/prospecting'
-import type { ProjectsDomainStateSchema } from './domains/projects'
+import type { ProspectingBuildTemplateSchema, ProspectingLifecycleStageSchema } from './domains/prospecting'
+import type { ProjectsDomainStateSchema } from './domains/projects'
 import { listAllSystems } from './helpers'
 
-// ---------------------------------------------------------------------------
-// Locally-scoped inferred types — external signatures use these shapes.
-// ---------------------------------------------------------------------------
-type Pipeline = z.infer<typeof SalesPipelineSchema>
-type Stage = z.infer<typeof SalesStageSchema>
-type BuildTemplate = z.infer<typeof ProspectingBuildTemplateSchema>
-type ProspectingStage = z.infer<typeof ProspectingLifecycleStageSchema>
-type ProjectStatus = z.infer<typeof ProjectsDomainStateSchema>
-
-// ---------------------------------------------------------------------------
-// Sales — Pipelines + Stages
-// ---------------------------------------------------------------------------
-
-/**
- * Return all sales pipelines defined in the model, each tagged with the
- * system path of the owning system.
- *
- * Phase 4: walks every system via listAllSystems(), finds content nodes where
- * (kind, type) === ('schema', 'pipeline'), and reconstructs the Pipeline shape
- * by pulling sibling stage content nodes (parentContentId === pipeline local id).
- */
-export function getAllPipelines(model: OrganizationModel): Array<{ systemPath: string; pipeline: Pipeline }> {
-  const results: Array<{ systemPath: string; pipeline: Pipeline }> = []
-
-  for (const { path: systemPath, system } of listAllSystems(model)) {
-    const content = system.content ?? {}
-
-    for (const [localId, node] of Object.entries(content)) {
-      if (node.kind !== 'schema' || node.type !== 'pipeline') continue
-
-      const data = (node.data ?? {}) as Record<string, unknown>
-      const stages: Stage[] = Object.entries(content)
-        .filter(([, s]) => s.kind === 'schema' && s.type === 'stage' && s.parentContentId === localId)
-        .map(([stageLocalId, s]) => {
-          const sd = (s.data ?? {}) as Record<string, unknown>
-          return {
-            id: stageLocalId,
-            label: s.label ?? stageLocalId,
-            order: typeof sd.order === 'number' ? sd.order : 0,
-            semanticClass: (sd.semanticClass as Stage['semanticClass']) ?? 'open',
-            surfaceIds: Array.isArray(sd.surfaceIds) ? (sd.surfaceIds as string[]) : [],
-            resourceIds: Array.isArray(sd.resourceIds) ? (sd.resourceIds as string[]) : [],
-            color: typeof sd.color === 'string' ? sd.color : undefined
-          } satisfies Stage
-        })
-        .sort((a, b) => a.order - b.order)
-
-      const pipeline: Pipeline = {
-        id: localId,
-        label: node.label ?? localId,
-        entityId: typeof data.entityId === 'string' ? data.entityId : '',
-        stages,
-        ...(typeof node.description === 'string' ? { description: node.description } : {})
-      }
-
-      results.push({ systemPath, pipeline })
-    }
-  }
-
-  return results
-}
-
-/**
- * Return the stages belonging to a given pipeline, identified by systemPath + pipelineLocalId.
- *
- * Phase 4: resolves the system at systemPath, filters its content for stage nodes
- * where parentContentId === pipelineLocalId.
- *
- * @param model - The resolved organization model.
- * @param systemPath - Dot-separated path to the owning system (e.g. 'sales.crm').
- * @param pipelineLocalId - The local content id of the target pipeline node.
- */
-export function getStagesInPipeline(model: OrganizationModel, systemPath: string, pipelineLocalId: string): Stage[] {
-  const allSystems = listAllSystems(model)
-  const entry = allSystems.find((s) => s.path === systemPath)
-  if (!entry) return []
-
-  const content = entry.system.content ?? {}
-  return Object.entries(content)
-    .filter(([, node]) => node.kind === 'schema' && node.type === 'stage' && node.parentContentId === pipelineLocalId)
-    .map(([stageLocalId, s]) => {
-      const sd = (s.data ?? {}) as Record<string, unknown>
-      return {
-        id: stageLocalId,
-        label: s.label ?? stageLocalId,
-        order: typeof sd.order === 'number' ? sd.order : 0,
-        semanticClass: (sd.semanticClass as Stage['semanticClass']) ?? 'open',
-        surfaceIds: Array.isArray(sd.surfaceIds) ? (sd.surfaceIds as string[]) : [],
-        resourceIds: Array.isArray(sd.resourceIds) ? (sd.resourceIds as string[]) : [],
-        color: typeof sd.color === 'string' ? sd.color : undefined
-      } satisfies Stage
-    })
-    .sort((a, b) => a.order - b.order)
-}
-
-// ---------------------------------------------------------------------------
-// Prospecting — Build templates
-// ---------------------------------------------------------------------------
-
-/**
- * Return all prospecting build templates defined in the model.
- *
- * Phase 4: walks every system, finds content nodes where
- * (kind, type) === ('schema', 'template'), reconstructs BuildTemplate shape
- * by pulling sibling template-step nodes (parentContentId === template local id).
- */
-export function getAllBuildTemplates(model: OrganizationModel): BuildTemplate[] {
-  const results: BuildTemplate[] = []
-
-  for (const { system } of listAllSystems(model)) {
-    const content = system.content ?? {}
-
-    for (const [localId, node] of Object.entries(content)) {
-      if (node.kind !== 'schema' || node.type !== 'template') continue
-      const nd = (node.data ?? {}) as Record<string, unknown>
-
-      const steps = Object.entries(content)
-        .filter(([, s]) => s.kind === 'schema' && s.type === 'template-step' && s.parentContentId === localId)
-        .map(([stepLocalId, s]) => {
-          const sd = (s.data ?? {}) as Record<string, unknown>
-          return {
-            id: stepLocalId,
-            label: s.label ?? stepLocalId,
-            ...(s.description ? { description: s.description } : {}),
-            // Pass through all data fields — template-step payload is richer than Pipeline;
-            // Wave 2 authors the canonical shape; Wave 4 verifies round-trip fidelity.
-            ...sd
-          }
-        })
-
-      results.push({
-        id: localId,
-        label: node.label ?? localId,
-        ...(node.description ? { description: node.description } : {}),
-        ...(typeof nd.color === 'string' ? { color: nd.color } : {}),
-        // BuildTemplate requires steps array — cast via spread; Wave 4 adds type-safe assertions.
-        steps: steps as BuildTemplate['steps']
-      })
-    }
-  }
-
-  return results
-}
-
-/**
- * Return the prospecting lifecycle stages for a given entity kind.
- *
- * Phase 4: walks every system, finds content nodes where
- * (kind, type) === ('schema', 'stage') AND data.entityKind === kind.
- * Prospecting stages are distinguished from pipeline stages by the presence of
- * data.entityKind ('company' | 'contact') authored by Wave 2.
- *
- * @param kind - 'company' or 'contact'.
- */
-export function getAllProspectingStages(model: OrganizationModel, kind: 'company' | 'contact'): ProspectingStage[] {
-  const results: ProspectingStage[] = []
-
-  for (const { system } of listAllSystems(model)) {
-    const content = system.content ?? {}
-
-    for (const [localId, node] of Object.entries(content)) {
-      if (node.kind !== 'schema' || node.type !== 'stage') continue
-      const sd = (node.data ?? {}) as Record<string, unknown>
-      if (sd.entityKind !== kind) continue
-
-      results.push({
-        id: localId,
-        label: node.label ?? localId,
-        order: typeof sd.order === 'number' ? sd.order : 0,
-        ...(typeof sd.color === 'string' ? { color: sd.color } : {}),
-        ...(node.description ? { description: node.description } : {})
-      } satisfies ProspectingStage)
-    }
-  }
-
-  return results.sort((a, b) => a.order - b.order)
-}
-
-// ---------------------------------------------------------------------------
-// Projects — Statuses
-// ---------------------------------------------------------------------------
-
-/**
- * Return the project statuses for a given entity type.
- *
- * Phase 4: walks every system, finds status-flow content nodes where
- * data.appliesTo === appliesTo, then collects their child status nodes
- * (parentContentId === status-flow local id), sorted by order.
- *
- * @param appliesTo - 'project', 'milestone', or 'task'.
- */
-export function getAllProjectStatuses(
-  model: OrganizationModel,
-  appliesTo: 'project' | 'milestone' | 'task'
-): ProjectStatus[] {
-  const results: ProjectStatus[] = []
-
-  for (const { system } of listAllSystems(model)) {
-    const content = system.content ?? {}
-
-    // Find the status-flow node for this appliesTo scope.
-    for (const [flowLocalId, flowNode] of Object.entries(content)) {
-      if (flowNode.kind !== 'schema' || flowNode.type !== 'status-flow') continue
-      const fd = (flowNode.data ?? {}) as Record<string, unknown>
-      if (fd.appliesTo !== appliesTo) continue
-
-      // Collect child status nodes.
-      for (const [statusLocalId, statusNode] of Object.entries(content)) {
-        if (statusNode.kind !== 'schema' || statusNode.type !== 'status') continue
-        if (statusNode.parentContentId !== flowLocalId) continue
-
-        const sd = (statusNode.data ?? {}) as Record<string, unknown>
-        results.push({
-          id: statusLocalId,
-          label: statusNode.label ?? statusLocalId,
-          order: typeof sd.order === 'number' ? sd.order : 0,
-          ...(typeof sd.color === 'string' ? { color: sd.color } : {}),
-          ...(statusNode.description ? { description: statusNode.description } : {})
-        } satisfies ProjectStatus)
-      }
-    }
-  }
-
-  return results.sort((a, b) => a.order - b.order)
-}
+// Compatibility boundary: these helpers intentionally keep old tenant
+// System.content schema nodes readable. New schema/catalog authoring belongs in
+// System.ontology, and new system-local settings belong in System.config.
+
+// ---------------------------------------------------------------------------
+// Locally-scoped inferred types — external signatures use these shapes.
+// ---------------------------------------------------------------------------
+type Pipeline = z.infer<typeof SalesPipelineSchema>
+type Stage = z.infer<typeof SalesStageSchema>
+type BuildTemplate = z.infer<typeof ProspectingBuildTemplateSchema>
+type ProspectingStage = z.infer<typeof ProspectingLifecycleStageSchema>
+type ProjectStatus = z.infer<typeof ProjectsDomainStateSchema>
+
+// ---------------------------------------------------------------------------
+// Sales — Pipelines + Stages
+// ---------------------------------------------------------------------------
+
+/**
+ * Return all sales pipelines defined in the model, each tagged with the
+ * system path of the owning system.
+ *
+ * Compatibility bridge: walks every system via listAllSystems(), finds content nodes where
+ * (kind, type) === ('schema', 'pipeline'), and reconstructs the Pipeline shape
+ * by pulling sibling stage content nodes (parentContentId === pipeline local id).
+ */
+export function getAllPipelines(model: OrganizationModel): Array<{ systemPath: string; pipeline: Pipeline }> {
+  const results: Array<{ systemPath: string; pipeline: Pipeline }> = []
+
+  for (const { path: systemPath, system } of listAllSystems(model)) {
+    const content = system.content ?? {}
+
+    for (const [localId, node] of Object.entries(content)) {
+      if (node.kind !== 'schema' || node.type !== 'pipeline') continue
+
+      const data = (node.data ?? {}) as Record<string, unknown>
+      const stages: Stage[] = Object.entries(content)
+        .filter(([, s]) => s.kind === 'schema' && s.type === 'stage' && s.parentContentId === localId)
+        .map(([stageLocalId, s]) => {
+          const sd = (s.data ?? {}) as Record<string, unknown>
+          return {
+            id: stageLocalId,
+            label: s.label ?? stageLocalId,
+            order: typeof sd.order === 'number' ? sd.order : 0,
+            semanticClass: (sd.semanticClass as Stage['semanticClass']) ?? 'open',
+            surfaceIds: Array.isArray(sd.surfaceIds) ? (sd.surfaceIds as string[]) : [],
+            resourceIds: Array.isArray(sd.resourceIds) ? (sd.resourceIds as string[]) : [],
+            color: typeof sd.color === 'string' ? sd.color : undefined
+          } satisfies Stage
+        })
+        .sort((a, b) => a.order - b.order)
+
+      const pipeline: Pipeline = {
+        id: localId,
+        label: node.label ?? localId,
+        entityId: typeof data.entityId === 'string' ? data.entityId : '',
+        stages,
+        ...(typeof node.description === 'string' ? { description: node.description } : {})
+      }
+
+      results.push({ systemPath, pipeline })
+    }
+  }
+
+  return results
+}
+
+/**
+ * Return the stages belonging to a given pipeline, identified by systemPath + pipelineLocalId.
+ *
+ * Compatibility bridge: resolves the system at systemPath, filters its content for stage nodes
+ * where parentContentId === pipelineLocalId.
+ *
+ * @param model - The resolved organization model.
+ * @param systemPath - Dot-separated path to the owning system (e.g. 'sales.crm').
+ * @param pipelineLocalId - The local content id of the target pipeline node.
+ */
+export function getStagesInPipeline(model: OrganizationModel, systemPath: string, pipelineLocalId: string): Stage[] {
+  const allSystems = listAllSystems(model)
+  const entry = allSystems.find((s) => s.path === systemPath)
+  if (!entry) return []
+
+  const content = entry.system.content ?? {}
+  return Object.entries(content)
+    .filter(([, node]) => node.kind === 'schema' && node.type === 'stage' && node.parentContentId === pipelineLocalId)
+    .map(([stageLocalId, s]) => {
+      const sd = (s.data ?? {}) as Record<string, unknown>
+      return {
+        id: stageLocalId,
+        label: s.label ?? stageLocalId,
+        order: typeof sd.order === 'number' ? sd.order : 0,
+        semanticClass: (sd.semanticClass as Stage['semanticClass']) ?? 'open',
+        surfaceIds: Array.isArray(sd.surfaceIds) ? (sd.surfaceIds as string[]) : [],
+        resourceIds: Array.isArray(sd.resourceIds) ? (sd.resourceIds as string[]) : [],
+        color: typeof sd.color === 'string' ? sd.color : undefined
+      } satisfies Stage
+    })
+    .sort((a, b) => a.order - b.order)
+}
+
+// ---------------------------------------------------------------------------
+// Prospecting — Build templates
+// ---------------------------------------------------------------------------
+
+/**
+ * Return all prospecting build templates defined in the model.
+ *
+ * Compatibility bridge: walks every system, finds content nodes where
+ * (kind, type) === ('schema', 'template'), reconstructs BuildTemplate shape
+ * by pulling sibling template-step nodes (parentContentId === template local id).
+ */
+export function getAllBuildTemplates(model: OrganizationModel): BuildTemplate[] {
+  const results: BuildTemplate[] = []
+
+  for (const { system } of listAllSystems(model)) {
+    const content = system.content ?? {}
+
+    for (const [localId, node] of Object.entries(content)) {
+      if (node.kind !== 'schema' || node.type !== 'template') continue
+      const nd = (node.data ?? {}) as Record<string, unknown>
+
+      const steps = Object.entries(content)
+        .filter(([, s]) => s.kind === 'schema' && s.type === 'template-step' && s.parentContentId === localId)
+        .map(([stepLocalId, s]) => {
+          const sd = (s.data ?? {}) as Record<string, unknown>
+          return {
+            id: stepLocalId,
+            label: s.label ?? stepLocalId,
+            ...(s.description ? { description: s.description } : {}),
+            // Pass through all data fields — template-step payload is richer than Pipeline;
+            // Bridge readers preserve the historical shape for round-trip fidelity.
+            ...sd
+          }
+        })
+
+      results.push({
+        id: localId,
+        label: node.label ?? localId,
+        ...(node.description ? { description: node.description } : {}),
+        ...(typeof nd.color === 'string' ? { color: nd.color } : {}),
+        // BuildTemplate requires steps array — cast via spread; Wave 4 adds type-safe assertions.
+        steps: steps as BuildTemplate['steps']
+      })
+    }
+  }
+
+  return results
+}
+
+/**
+ * Return the prospecting lifecycle stages for a given entity kind.
+ *
+ * Compatibility bridge: walks every system, finds content nodes where
+ * (kind, type) === ('schema', 'stage') AND data.entityKind === kind.
+ * Prospecting stages are distinguished from pipeline stages by the presence of
+ * data.entityKind ('company' | 'contact') retained on bridge compatibility nodes.
+ *
+ * @param kind - 'company' or 'contact'.
+ */
+export function getAllProspectingStages(model: OrganizationModel, kind: 'company' | 'contact'): ProspectingStage[] {
+  const results: ProspectingStage[] = []
+
+  for (const { system } of listAllSystems(model)) {
+    const content = system.content ?? {}
+
+    for (const [localId, node] of Object.entries(content)) {
+      if (node.kind !== 'schema' || node.type !== 'stage') continue
+      const sd = (node.data ?? {}) as Record<string, unknown>
+      if (sd.entityKind !== kind) continue
+
+      results.push({
+        id: localId,
+        label: node.label ?? localId,
+        order: typeof sd.order === 'number' ? sd.order : 0,
+        ...(typeof sd.color === 'string' ? { color: sd.color } : {}),
+        ...(node.description ? { description: node.description } : {})
+      } satisfies ProspectingStage)
+    }
+  }
+
+  return results.sort((a, b) => a.order - b.order)
+}
+
+// ---------------------------------------------------------------------------
+// Projects — Statuses
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the project statuses for a given entity type.
+ *
+ * Compatibility bridge: walks every system, finds status-flow content nodes where
+ * data.appliesTo === appliesTo, then collects their child status nodes
+ * (parentContentId === status-flow local id), sorted by order.
+ *
+ * @param appliesTo - 'project', 'milestone', or 'task'.
+ */
+export function getAllProjectStatuses(
+  model: OrganizationModel,
+  appliesTo: 'project' | 'milestone' | 'task'
+): ProjectStatus[] {
+  const results: ProjectStatus[] = []
+
+  for (const { system } of listAllSystems(model)) {
+    const content = system.content ?? {}
+
+    // Find the status-flow node for this appliesTo scope.
+    for (const [flowLocalId, flowNode] of Object.entries(content)) {
+      if (flowNode.kind !== 'schema' || flowNode.type !== 'status-flow') continue
+      const fd = (flowNode.data ?? {}) as Record<string, unknown>
+      if (fd.appliesTo !== appliesTo) continue
+
+      // Collect child status nodes.
+      for (const [statusLocalId, statusNode] of Object.entries(content)) {
+        if (statusNode.kind !== 'schema' || statusNode.type !== 'status') continue
+        if (statusNode.parentContentId !== flowLocalId) continue
+
+        const sd = (statusNode.data ?? {}) as Record<string, unknown>
+        results.push({
+          id: statusLocalId,
+          label: statusNode.label ?? statusLocalId,
+          order: typeof sd.order === 'number' ? sd.order : 0,
+          ...(typeof sd.color === 'string' ? { color: sd.color } : {}),
+          ...(statusNode.description ? { description: statusNode.description } : {})
+        } satisfies ProjectStatus)
+      }
+    }
+  }
+
+  return results.sort((a, b) => a.order - b.order)
+}