@elevasis/core 0.1.0 → 0.2.1

package/src/organization-model/__tests__/resolve.test.ts

@@ -22,6 +22,18 @@ describe('organization-model', () => {
 
   it('replaces arrays when a downstream override supplies a full slice', () => {
     const model = resolveOrganizationModel({
+      domains: [
+        {
+          id: 'crm',
+          label: 'CRM',
+          description: 'Custom CRM workspace',
+          color: 'blue',
+          entityIds: [],
+          surfaceIds: ['custom.home'],
+          resourceIds: [],
+          capabilityIds: []
+        }
+      ],
       navigation: {
         defaultSurfaceId: 'custom.home',
         surfaces: [
@@ -44,4 +56,200 @@ describe('organization-model', () => {
     expect(model.navigation.surfaces).toHaveLength(1)
     expect(model.navigation.surfaces[0]?.path).toBe('/home')
   })
+
+  describe('deepMerge semantics', () => {
+    it('returns defaults when no override is provided', () => {
+      const model = resolveOrganizationModel(undefined)
+
+      expect(model.version).toBe(1)
+      expect(model.branding.organizationName).toBe('Default Organization')
+      expect(model.branding.productName).toBe('Elevasis')
+      expect(model.branding.shortName).toBe('Elevasis')
+      expect(model.domains).toHaveLength(4)
+      expect(model.navigation.defaultSurfaceId).toBe('crm.pipeline')
+      expect(model.navigation.surfaces).toHaveLength(5)
+      expect(model.navigation.groups).toHaveLength(2)
+    })
+
+    it('preserves sibling fields when overriding a nested property', () => {
+      const model = resolveOrganizationModel({
+        branding: {
+          organizationName: 'OverriddenOrg'
+        }
+      })
+
+      expect(model.branding.organizationName).toBe('OverriddenOrg')
+      expect(model.branding.productName).toBe('Elevasis')
+      expect(model.branding.shortName).toBe('Elevasis')
+    })
+
+    it('replaces arrays entirely rather than merging', () => {
+      // Override domains with a single-item array that has no surfaceIds, so no
+      // cross-reference validation is needed. This proves the array is replaced (1 item)
+      // rather than merged/concatenated (would be 5 = 4 defaults + 1).
+      const model = resolveOrganizationModel({
+        domains: [
+          {
+            id: 'crm',
+            label: 'CRM',
+            description: 'CRM only',
+            color: 'blue',
+            entityIds: [],
+            surfaceIds: [],
+            resourceIds: [],
+            capabilityIds: []
+          }
+        ],
+        navigation: {
+          defaultSurfaceId: 'home',
+          surfaces: [
+            {
+              id: 'home',
+              label: 'Home',
+              path: '/home',
+              surfaceType: 'page',
+              domainIds: [],
+              entityIds: [],
+              resourceIds: [],
+              capabilityIds: []
+            }
+          ],
+          groups: []
+        }
+      })
+
+      expect(model.domains).toHaveLength(1)
+      expect(model.domains[0]?.id).toBe('crm')
+    })
+
+    it('ignores undefined values in the override', () => {
+      const model = resolveOrganizationModel({
+        branding: {
+          organizationName: 'Test',
+          productName: undefined
+        }
+      })
+
+      expect(model.branding.organizationName).toBe('Test')
+      expect(model.branding.productName).toBe('Elevasis')
+    })
+  })
+
+  describe('navigation group normalization', () => {
+    // A self-consistent single-surface override: one domain pointing at one surface,
+    // one surface pointing back at that domain. Groups are intentionally NOT overridden
+    // so normalization fires.
+    const singleSurfaceOverride = {
+      domains: [
+        {
+          id: 'crm',
+          label: 'CRM',
+          description: 'CRM workspace',
+          color: 'blue',
+          entityIds: [],
+          surfaceIds: ['crm.pipeline'],
+          resourceIds: [],
+          capabilityIds: []
+        }
+      ],
+      navigation: {
+        defaultSurfaceId: 'crm.pipeline',
+        surfaces: [
+          {
+            id: 'crm.pipeline',
+            label: 'Pipeline',
+            path: '/crm/pipeline',
+            surfaceType: 'graph' as const,
+            domainIds: ['crm'],
+            entityIds: [],
+            resourceIds: [],
+            capabilityIds: []
+          }
+        ]
+        // groups intentionally omitted — normalization must filter inherited groups
+      }
+    }
+
+    it('filters inherited groups to match overridden surfaces', () => {
+      // Only crm.pipeline is present. The default 'primary-workspace' group references
+      // crm.pipeline, lead-gen.lists, and projects.index. After normalization it should
+      // only contain crm.pipeline.
+      // The 'primary-operations' group references operations surfaces that are now gone,
+      // so it should be dropped entirely.
+      const model = resolveOrganizationModel(singleSurfaceOverride)
+
+      expect(model.navigation.surfaces).toHaveLength(1)
+      expect(model.navigation.surfaces[0]?.id).toBe('crm.pipeline')
+
+      // Only the workspace group survives (it has crm.pipeline); operations group is gone
+      expect(model.navigation.groups).toHaveLength(1)
+      expect(model.navigation.groups[0]?.id).toBe('primary-workspace')
+      expect(model.navigation.groups[0]?.surfaceIds).toEqual(['crm.pipeline'])
+    })
+
+    it('removes groups with no valid surface references', () => {
+      const model = resolveOrganizationModel(singleSurfaceOverride)
+
+      // The operations group (operations.organization-graph, operations.command-view)
+      // references surfaces not present in the override — it must be removed entirely
+      const operationsGroup = model.navigation.groups.find((g) => g.id === 'primary-operations')
+      expect(operationsGroup).toBeUndefined()
+    })
+
+    it('skips normalization when groups are explicitly overridden', () => {
+      // When groups are explicitly provided alongside surfaces, normalization is skipped.
+      // The group references only crm.pipeline (which is in the surface list).
+      const model = resolveOrganizationModel({
+        domains: [
+          {
+            id: 'crm',
+            label: 'CRM',
+            description: 'CRM workspace',
+            color: 'blue',
+            entityIds: [],
+            surfaceIds: ['crm.pipeline'],
+            resourceIds: [],
+            capabilityIds: []
+          }
+        ],
+        navigation: {
+          defaultSurfaceId: 'crm.pipeline',
+          surfaces: [
+            {
+              id: 'crm.pipeline',
+              label: 'Pipeline',
+              path: '/crm/pipeline',
+              surfaceType: 'graph',
+              domainIds: ['crm'],
+              entityIds: [],
+              resourceIds: [],
+              capabilityIds: []
+            }
+          ],
+          groups: [
+            {
+              id: 'custom-group',
+              label: 'Custom',
+              placement: 'primary',
+              surfaceIds: ['crm.pipeline']
+            }
+          ]
+        }
+      })
+
+      // Groups come from the override exactly — no filtering applied
+      expect(model.navigation.groups).toHaveLength(1)
+      expect(model.navigation.groups[0]?.id).toBe('custom-group')
+      expect(model.navigation.groups[0]?.surfaceIds).toEqual(['crm.pipeline'])
+    })
+  })
+
+  describe('defineOrganizationModel', () => {
+    it('returns the input unchanged', () => {
+      const input = { branding: { organizationName: 'Test', productName: 'TestOS', shortName: 'T' } }
+      const output = defineOrganizationModel(input)
+
+      expect(output).toBe(input)
+    })
+  })
 })

package/src/organization-model/defaults.ts

@@ -31,7 +31,7 @@ export const DEFAULT_ORGANIZATION_MODEL: OrganizationModel = {
     },
     {
       id: 'delivery',
-      label: 'Delivery',
+      label: 'Projects',
       description: 'Projects, milestones, and client work execution',
       color: 'orange',
       entityIds: ['delivery.project', 'delivery.milestone', 'delivery.task'],

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

@@ -0,0 +1,262 @@
+---
+title: Organization Graph
+description: Organization OS Graph layer documentation for the Cytoscape-based organization graph, derived from the organization model and bridged with Command View runtime topology through the shared feature provider.
+---
+
+## Overview
+
+Within Organization OS, the organization graph is the dedicated **Graph** layer. It treats the organization model as the top-level ontology and bridges in Command View runtime topology so one graph can support semantic exploration and operations-oriented tracing. It is not a replacement renderer for Command View; it is a shared graph product that subsumes Command View as one operational lens.
+
+Graph contracts live in `@repo/core` alongside the organization model. Rendering lives in `@repo/ui` with Cytoscape.js. The command-center route is a thin wrapper over the shared page.
+
+## Status
+
+First implementation slices are live end-to-end. Command View now delegates to the graph through a command-view lens preset. Layout iteration on the one-panel graph + command surface is ongoing; graph contracts and provider bridge are stable.
+
+Graph types are intentionally **not** part of the published `@elevasis/core` surface yet. Graph adoption remains monorepo-first.
+
+## Source of Truth
+
+- `packages/core/src/organization-model/graph/types.ts` -- node/edge DTO shapes
+- `packages/core/src/organization-model/graph/schema.ts` -- runtime validation
+- `packages/core/src/organization-model/graph/build.ts` -- `buildOrganizationGraph(...)` derivation
+- `packages/core/src/organization-model/__tests__/graph.test.ts` -- derivation and bridge tests
+- `packages/ui/src/features/operations/OrganizationGraphPage.tsx` -- shared Cytoscape page
+- `packages/ui/src/features/operations/CommandViewPage.tsx` -- command-view lens delegating to the graph
+- `packages/ui/src/features/operations/organization-graph/` -- filter helpers, detail-state helpers, path tracing, operational summary
+- `packages/ui/src/features/operations/manifest.ts` -- `organizationGraph.surfaceId = 'operations.organization-graph'`
+- `apps/command-center/src/routes/operations/organization-graph.index.tsx` -- route wrapper
+
+## Product Jobs
+
+The graph helps users:
+
+- orient themselves in the organization model
+- discover how domains, capabilities, surfaces, entities, resources, and workflows connect
+- trace upstream/downstream dependencies
+- understand ownership and implementation boundaries
+- assess blast radius before changing a workflow, agent, feature, or integration
+- operate across strategy, operations, and debugging through different lenses on the same graph
+
+The graph does not replace workflow editors, execution-run visualizers, or builder-style authoring canvases. React Flow remains the better fit for editor/execution visuals; Cytoscape fits the exploration-oriented ontology graph.
+
+## Architecture
+
+### Unified graph model
+
+The implementation uses one typed graph, not separate semantic and implementation taxonomies.
+
+- Node kinds: `organization`, `feature`, `domain`, `surface`, `entity`, `capability`, `resource`
+- Edge kinds: `contains`, `references`, `exposes`, `maps_to`
+- `resource` nodes carry `resourceType` metadata: `workflow`, `agent`, `trigger`, `integration`, `external`, or `human_checkpoint`
+- `references` edges may also carry `relationshipType`: `triggers`, `uses`, or `approval`
+
+This means runtime topology is represented as bridged `resource` nodes plus relationship metadata on shared edge types, rather than as a second disconnected edge/node vocabulary.
+
+### Compatibility rules with the organization model
+
+- `OrganizationModelSchema` is the source of truth for semantic structure. The graph does not introduce a second ontology.
+- Graph node IDs and references reuse organization-model IDs wherever those IDs already exist.
+- `domain` nodes derive from `organizationModel.domains`.
+- `surface` nodes derive from `organizationModel.navigation.surfaces`; graph routing respects surface `path` and `defaultSurfaceId`.
+- Feature gating and labels respect `organizationModel.features.enabled` and `.labels`.
+- Implementation-resource bridging prefers `organizationModel.resourceMappings`.
+- Graph defaults remain valid when produced by `resolveOrganizationModel()`.
+- If the graph needs a concept the model cannot express, extend the model first.
+
+### Shared DTO
+
+```ts
+type OrganizationGraphNodeKind =
+  | 'organization'
+  | 'feature'
+  | 'domain'
+  | 'surface'
+  | 'entity'
+  | 'capability'
+  | 'resource'
+
+type OrganizationGraphEdgeKind = 'contains' | 'references' | 'exposes' | 'maps_to'
+
+interface OrganizationGraph {
+  version: 1
+  organizationModelVersion: OrganizationModel['version']
+  nodes: OrganizationGraphNode[]
+  edges: OrganizationGraphEdge[]
+}
+```
+
+`OrganizationGraphNode` also includes optional `sourceId`, `description`, `enabled`, `featureKey`, `surfaceType`, and `resourceType`. `OrganizationGraphEdge` includes optional `label` and `relationshipType`.
+
+### Build pipeline
+
+```ts
+interface BuildOrganizationGraphInput {
+  organizationModel: OrganizationModel
+  commandViewData?: CommandViewData
+}
+```
+
+`buildOrganizationGraph` accepts optional topology input so the semantic graph still renders when operational bridging is sparse. The derivation flow is additive and upsert-oriented:
+
+1. Resolve the active organization model.
+2. Derive semantic nodes and edges from domains, features, surfaces, entities, capabilities, and resource mappings.
+3. Upsert bridged runtime resources from Command View data into shared `resource` nodes.
+4. Merge topology relationships onto the same DTO using `references` or `maps_to` edges plus optional `relationshipType`.
+5. Hand the resulting graph to UI-level lensing, filtering, and Cytoscape projection.
+
+Keeping assembly outside the renderer keeps graph semantics testable without UI and prevents Cytoscape concepts from leaking into business logic.
+
+### Ownership split
+
+- `@repo/core` owns normalized node/edge types, schemas, and build/derivation helpers.
+- `@repo/ui` owns Cytoscape element conversion, layout presets, selection/hover/expansion/viewport state, detail panels, and presentation helpers.
+- `apps/command-center` owns route wiring and page-level integration.
+
+## Interaction Model
+
+### Lenses
+
+The graph ships with two lens presets in UI code:
+
+- `default` -- title "Organization Graph", initial mode `map`, no preset filters
+- `command-view` -- title "Command View", initial mode `trace`, filters preset to `nodeKinds: ['resource']` and `topologyPresence: 'topology-only'`
+
+Lenses do not change the core DTO. They configure how the shared graph is initially presented.
+
+### Modes
+
+- **Map mode** -- clustered for broad graph orientation
+- **Trace mode** -- directed layout that privileges path readability
+- **Impact mode** -- centered radial/concentric layout around the current focus
+
+Layouts are deterministic presets, not unconstrained force simulation:
+
+- `map` uses Cytoscape `cose`
+- `trace` uses directed `breadthfirst`
+- `impact` uses degree-based `concentric`
+
+### Interactions
+
+Primary set, kept small and high-value:
+
+- click node for detail panel
+- click edge for relationship meaning
+- hover for adjacency preview
+- search and jump to node
+- expand immediate neighbors
+- isolate selected node + N-hop neighborhood
+- switch mode
+- pin selected nodes
+- highlight shortest or most relevant path between two nodes
+- filter by node kind, domain, capability, feature, status, environment
+
+Deferred: freeform node placement, collaborative annotations, graph editing/authoring, arbitrary canvas drawing.
+
+### Filtering
+
+The filter state lives in `useOrganizationGraphFilters()` and the toolbar UI in `OrganizationGraphFilterToolbar`.
+
+Filter inputs:
+
+- `search`
+- `nodeKinds`
+- `topologyPresence: 'all' | 'semantic-only' | 'topology-only'`
+
+Presence is derived per node:
+
+- `resource` nodes are `topology-only`
+- nodes with only semantic edges are `semantic-only`
+- nodes with both semantic and topology edges are treated as bridge nodes internally
+
+Search matches node IDs, labels, descriptions, source IDs, feature keys, surface/resource types, edge labels, edge kinds, and `relationshipType`.
+
+The page applies `useDeferredValue()` to the active filters so graph search stays responsive while typing.
+
+### Path tracing
+
+The visible Cytoscape surface projects a **filtered** shared graph DTO rather than rendering the full graph unconditionally. Path tracing resolves and highlights directed paths inside the current visible projection, so filtering and tracing stay coherent.
+
+Renderer-agnostic helpers under `packages/ui/src/features/operations/organization-graph/path-tracing/` implement shortest-path logic independent of Cytoscape.
+
+## Provider Integration
+
+The graph is exposed through `ElevasisFeaturesProvider` rather than as app-local glue:
+
+- `FeatureModule.organizationGraph.surfaceId` declares a manifest's bridge point.
+- `operationsManifest` declares `organizationGraph.surfaceId = 'operations.organization-graph'`.
+- The provider resolves that against `organizationModel.navigation.surfaces` and exposes the result as `organizationGraph` in context.
+- Shared UI/operations code stays manifest-driven while remaining aware of semantic organization topology.
+
+## Command View Integration
+
+`CommandViewPage` now delegates to `OrganizationGraphPage` through a command-view lens preset. The lens restores high-value operational context through:
+
+- route-level execution-health cards
+- selection-aware resource and human-checkpoint summaries inside the shared graph detail panel
+- follow-up actions for recent executions and pending tasks inside the detail panel
+- dedicated command-view sidebar content (`Command View` labeling and node filters live in the subshell sidebar, not on the graph canvas)
+
+Operational summary and drill-down derivation is covered by tests under `packages/ui/src/features/operations/organization-graph/__tests__/`.
+
+The detail experience is shared through `OrganizationGraphDetailPanel`, which can render both semantic context and command-view-specific follow-up sections.
+
+## Cytoscape Responsibility Split
+
+Cytoscape owns:
+
+- element rendering
+- compound/group visualization
+- neighborhood traversal and selection state
+- path highlighting
+- collapsed/expanded cluster behavior
+- layout execution
+- viewport mechanics (pan, zoom, fit, focus)
+
+React owns:
+
+- mode switching
+- side panels and inspectors
+- search and command-palette entry
+- route state and deep-linking
+- server data fetching
+- persistence of saved filters and views
+
+## Package Boundary
+
+- `packages/ui/package.json` declares Cytoscape on the published UI surface.
+- `packages/ui/tsup.config.ts` and `packages/ui/rollup.dts.config.mjs` keep Cytoscape **externalized** for publish output.
+- Graph DTO types are internal to `@repo/core`. The published `@elevasis/core` wrapper still exposes only the narrow organization-model API. External graph adoption should not be assumed.
+
+## Theming
+
+The shared Cytoscape page reads CSS custom properties at runtime via `window.getComputedStyle(document.documentElement)`. Nodes, edges, overlays, and glass panels stay aligned with the active UI theme instead of relying on a fixed graph-only palette.
+
+## Cytoscape States
+
+The renderer applies CSS-class-style state markers to highlight context and traces:
+
+- `.is-faded`
+- `.is-context`
+- `.is-selected`
+- `.is-connected`
+- `.is-trace-node`
+- `.is-trace-endpoint`
+- `.is-trace-edge`
+
+These classes drive neighborhood focus, selection emphasis, and trace-path highlighting without changing the underlying DTO.
+
+## Migration Guardrails
+
+- Do not move canonical graph interfaces into `packages/ui`.
+- Do not redefine organization-model semantics in app-local graph config.
+- Do not make the graph contract depend on Cytoscape-specific types.
+- Existing Command View relationships bridge into `relationshipType = triggers | uses | approval` -- do not overload those operational labels with new semantic meaning.
+
+## Verification
+
+- `pnpm --filter @repo/core test -- organization-model graph`
+- `pnpm --filter @repo/ui test -- commandViewDrillDown commandViewOperationalSummary organizationGraphDetail`
+- `pnpm --filter @repo/ui build`
+- `pnpm --filter @repo/ui build:publish`
+- `pnpm --filter command-center build`