@elevasis/core 0.21.0 → 0.23.0

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

@@ -0,0 +1,249 @@
+/**
+ * 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
+ */
+
+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 { 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)
+}

package/src/organization-model/organization-graph.mdx

@@ -1,6 +1,6 @@
 ---
 title: Organization Graph
-description: Organization OS graph layer documentation for the organization graph derived from flat Organization Model features and resource metadata links.
+description: Organization OS graph layer documentation for the organization graph derived from Organization Model Systems, resources, capabilities, and typed links.
 ---
 
 ## Overview
@@ -24,30 +24,31 @@ Graph contracts live in `@repo/core`; rendering lives in `@repo/ui`.
 Node kinds:
 
 - `organization`
-- `feature`
-- `surface`
-- `entity`
+- `system`
+- `role`
 - `capability`
 - `resource`
+- `knowledge`
+- `policy`
 
 Edge kinds:
 
 - `contains`
 - `references`
-- `exposes`
 - `maps_to`
-- `operates-on`
 - `uses`
+- `governs`
+- `governed-by`
 
-Feature nodes come from the flat `OrganizationModel.features` array. Their graph IDs use `feature:<id>`, such as `feature:sales.crm`.
+System nodes come from the id-keyed `OrganizationModel.systems` map. Their graph IDs use `system:<id>`, such as `system:sales.crm`.
 
-Resource edges come from resource metadata:
+Resource and capability edges are derived from canonical OM maps:
 
 ```ts
-links: [
-  { nodeId: 'feature:sales.lead-gen', kind: 'operates-on' },
-  { nodeId: 'integration:instantly', kind: 'uses' }
-]
+// ResourceEntry.systemPath => system -> resource contains
+// SystemEntry.capabilities[] => system -> capability uses
+// Capability.resourceId => capability -> resource maps_to
+// AgentResource.invocations[] => agent resource -> invocation target uses/references
 ```
 
 ## Build Pipeline
@@ -61,9 +62,9 @@ interface BuildOrganizationGraphInput {
 
 `buildOrganizationGraph`:
 
-1. Reads flat Organization Model features and derives `feature:*` nodes.
-2. Reads Command View resources, including integration resources, as `resource` nodes with `resourceType` metadata.
-3. Emits authored graph links from resource/entity/capability metadata.
+1. Reads Organization Model Systems and derives `system:*` nodes.
+2. Reads OM resources, including workflow, agent, integration, and script resources, as `resource` nodes.
+3. Emits derived graph links from System, Resource, Capability, Agent invocation, and Knowledge contracts.
 4. Bridges Command View runtime topology into resource nodes and relationship edges.
 5. Returns a renderer-agnostic DTO.
 

package/src/organization-model/organization-model.mdx

@@ -1,11 +1,11 @@
 ---
 title: Organization Model
-description: Organization OS Model layer documentation for the flat feature hierarchy, semantic domains, resource graph links, and curated @elevasis/core public API.
+description: Organization OS Model layer documentation for the System hierarchy, semantic domains, resource descriptors, and curated @elevasis/core public API.
 ---
 
 ## Overview
 
-The organization model is the semantic contract that maps an organization's product shape to flat feature hierarchy, business semantics, shell navigation, and graph binding. It is schema-first, versioned, and validated.
+The organization model is the semantic contract that maps an organization's System hierarchy, business semantics, shell navigation, resource governance, and graph binding. It is schema-first, versioned, and validated.
 
 The model is authored in `@repo/core` and published through the curated `@elevasis/core/organization-model` surface.
 
@@ -24,7 +24,7 @@ The model is authored in `@repo/core` and published through the curated `@elevas
 Top-level fields on `OrganizationModel`:
 
 - `version`
-- `features`
+- `domainMetadata`
 - `branding`
 - `navigation`
 - `sales`
@@ -35,22 +35,28 @@ Top-level fields on `OrganizationModel`:
 - `offerings`
 - `roles`
 - `goals`
+- `systems`
+- `resources`
+- `capabilities`
+- `policies`
 - `statuses`
-- `operations`
+- `knowledge`
 
-Resources are not authored inside `OrganizationModel`. Deployable workflows, agents, triggers, integrations, external resources, and human checkpoints declare graph links on their resource metadata.
+The pure collection domains are id-keyed maps: `systems`, `roles`, `goals`, `customers`, `offerings`, `resources`, `capabilities`, `policies`, and `statuses`. The map key must match the entry `id`. Entries carry `order` for deterministic ordered views; use `listDomain(record)` when order matters.
 
-## Feature Shape
+Resource identity is authored inside `OrganizationModel.resources`. Runtime workflows, agents, integrations, and scripts import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
 
-`OrganizationModel.features` is a flat array. Hierarchy is derived from dotted IDs:
+## System Shape
+
+`OrganizationModel.systems` is the canonical semantic domain map. Hierarchy is derived from `parentSystemId` and dotted IDs:
 
 ```ts
-features: [
-  { id: 'dashboard', label: 'Dashboard', enabled: true, path: '/', uiPosition: 'sidebar-primary' },
-  { id: 'sales', label: 'Sales', enabled: true, uiPosition: 'sidebar-primary' },
-  { id: 'sales.crm', label: 'CRM', enabled: true, path: '/crm' },
-  { id: 'operations.resources', label: 'Resources', enabled: true, path: '/operations/resources' }
-]
+systems: {
+  dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },
+  sales: { id: 'sales', order: 20, label: 'Sales', lifecycle: 'active' },
+  clients: { id: 'clients', order: 30, label: 'Clients', lifecycle: 'active' },
+  projects: { id: 'projects', order: 40, label: 'Projects', lifecycle: 'active' }
+}
 ```
 
 Authored fields:
@@ -58,42 +64,98 @@ Authored fields:
 - `id`
 - `label`
 - `description`
-- `enabled`
-- `path`
-- `icon`
-- `color`
-- `uiPosition`
+- `kind`
+- `parentSystemId`
+- `ui`
+- `lifecycle`
 - `requiresAdmin`
-- `devOnly`
+- `capabilities`
+- `policies`
+- `order`
+
+Systems describe ownership, hierarchy, lifecycle, access, and governance. Sidebar presentation lives in `navigation.sidebar`, not on System entries. UI-backed Systems may still provide `ui.path` for route matching during the migration, but `ui.surfaces` is not an authored contract. `lifecycle` replaces the old feature enabled/dev-only split.
+
+## Navigation Shape
+
+`OrganizationModel.navigation.sidebar` is the authored shell tree. It has `primary` and `bottom` sections whose records contain recursive group nodes and routeable surface nodes:
 
-Containers omit `path`; leaves provide `path`. `uiPosition`, `requiresAdmin`, and `devOnly` inherit from ancestors.
-Development-only features remain defined and enabled with `devOnly: true`; shell consumers hide those entries and route paths outside development mode while preserving the semantic contract.
+```ts
+navigation: {
+  sidebar: {
+    primary: {
+      dashboard: {
+        type: 'surface',
+        order: 10,
+        label: 'Dashboard',
+        path: '/',
+        surfaceType: 'dashboard',
+        targets: { systems: ['dashboard'] }
+      },
+      business: {
+        type: 'group',
+        order: 20,
+        label: 'Business',
+        children: {
+          sales: {
+            type: 'surface',
+            order: 10,
+            label: 'Sales',
+            path: '/sales',
+            surfaceType: 'page',
+            targets: { systems: ['sales'] }
+          },
+          clients: {
+            type: 'surface',
+            order: 20,
+            label: 'Clients',
+            path: '/clients',
+            surfaceType: 'list',
+            targets: { systems: ['clients'] }
+          }
+        }
+      }
+    },
+    bottom: {}
+  }
+}
+```
 
-Navigation surfaces may also carry `devOnly` for compatibility with the legacy/domain navigation model. `knowledge.command-view` is intentionally development-only while its graph visualization modes continue to mature.
+Dashboard is ordered before Business in the primary sidebar. Business is a navigation group only; it is not a System and it is not a URL namespace. Routeable leaves are projected into flat surface DTOs by `projectOrganizationSurfaces(model)`.
 
-## Graph IDs and Resource Links
+## Graph IDs and Resource Descriptors
 
 Cross-collection links use kind-prefixed graph IDs:
 
-- `feature:sales.crm`
+- `system:sales.crm`
 - `integration:instantly`
 - `resource:lead-import`
-- `capability:operations.queue.review`
+- `action:operations.queue.review`
 
-Example resource metadata:
+Resource identity is authored in the OM Resources domain. Operations imports descriptors from `organizationModel.resources` and derives runtime `resourceId` / `type` while attaching executable behavior.
 
 ```ts
-config: {
-  resourceId: 'lead-import',
-  name: 'Lead Import',
-  type: 'workflow',
-  version: '1.0.0',
-  status: 'prod',
-  links: [{ nodeId: 'feature:sales.lead-gen', kind: 'operates-on' }],
-  category: 'production'
-}
+import { defineResources } from '@elevasis/core/organization-model'
+
+export const resourceDescriptors = defineResources({
+  leadImport: {
+    id: 'lead-import',
+    kind: 'workflow',
+    systemPath: 'sales.lead-gen',
+    ownerRoleId: 'role-ops-lead',
+    status: 'active',
+    actionKey: 'prospecting.lead-import'
+  }
+})
+
+export const resourceGovernanceModel = {
+  systems,
+  resources: resourceDescriptors
+} as const
 ```
 
+Legacy `sys.*` paths may still appear in older examples and external compatibility mirrors.
+For new Organization OS examples, prefer the current semantic System path.
+
 ## Domain Semantics
 
 The model keeps business semantics in named domains:
@@ -102,7 +164,10 @@ The model keeps business semantics in named domains:
 - `prospecting` -- company/contact lifecycle stages
 - `projects` -- project, milestone, and task statuses
 - `identity`, `customers`, `offerings`, `roles`, `goals` -- organizational reality
-- `statuses` and `operations` -- runtime/vibe-layer semantic registries
+- `systems` -- bounded contexts that group governed operational resources
+- `resources` -- governance-only workflow, agent, and integration descriptors
+- `statuses` -- runtime/vibe-layer semantic registry
+- `knowledge` -- playbooks, strategies, references, and graph-governing links
 
 ## Authoring and Resolution
 
@@ -110,27 +175,29 @@ The model keeps business semantics in named domains:
 - `resolveOrganizationModel(partial)` deep-merges a partial override into `DEFAULT_ORGANIZATION_MODEL` and validates the result.
 - `createFoundationOrganizationModel(partial)` resolves the canonical model and returns template-facing helpers.
 - Plain objects merge recursively.
+- Id-keyed domain maps merge additively by key.
 - Arrays replace defaults.
 
 ## Referential Integrity
 
 `OrganizationModelSchema` validates:
 
-- unique feature IDs
-- ancestor existence for dotted feature IDs
-- container/leaf path rules
+- unique System IDs
+- ancestor existence for dotted System IDs and `parentSystemId`
+- UI path rules for Systems with UI presence
 - valid sidebar positions
 - reality-domain cross references such as offering target segments and role reporting lines
+- system, resource, role, knowledge, and goal cross references used by resource governance
 
-Resource graph links are validated during resource registry registration because resources live in deployment specs.
+`DeploymentSpec` remains the runtime/deploy assembly around these descriptors. It is not the source of resource identity.
 
 ## Provider Integration
 
-`ElevasisFeaturesProvider` uses the organization model to:
+`ElevasisSystemsProvider` uses the organization model to:
 
-1. validate each manifest's `featureId`
-2. resolve effective feature access
-3. derive sidebar entries from `features`
+1. validate each manifest's `systemId`
+2. resolve effective system access
+3. derive sidebar entries from `navigation.sidebar`
 4. expose shell helpers such as `childrenOf`, `ancestorsOf`, and `findByPath`
 5. bridge the operations graph into shared UI