@elevasis/core 0.42.1 → 0.43.0

package/src/organization-model/__tests__/schema-refinements.test.ts

@@ -4,6 +4,15 @@ import { DEFAULT_ORGANIZATION_MODEL } from '../defaults'
 import { refineOrganizationModel } from '../schema-refinements'
 import type { OrganizationModel } from '../types'
 
+type RefinementCase = {
+  name: string
+  model: OrganizationModel
+  expected: {
+    message: string
+    path: Array<string | number>
+  }
+}
+
 function collectRefinementIssues(model: OrganizationModel): z.ZodIssue[] {
   const issues: z.ZodIssue[] = []
   const ctx = {
@@ -16,6 +25,21 @@ function collectRefinementIssues(model: OrganizationModel): z.ZodIssue[] {
   return issues
 }
 
+function makeModel(overrides: Partial<OrganizationModel>): OrganizationModel {
+  return {
+    ...DEFAULT_ORGANIZATION_MODEL,
+    systems: {
+      test: {
+        id: 'test',
+        order: 10,
+        label: 'Test',
+        lifecycle: 'active'
+      }
+    },
+    ...overrides
+  }
+}
+
 describe('refineOrganizationModel', () => {
   it('emits resource systemPath issues through the extracted refinement boundary', () => {
     const model: OrganizationModel = {
@@ -69,4 +93,158 @@ describe('refineOrganizationModel', () => {
       true
     )
   })
+
+  it.each<RefinementCase>([
+    {
+      name: 'system parent cycle',
+      model: makeModel({
+        systems: {
+          a: { id: 'a', order: 10, label: 'A', parentSystemId: 'b' },
+          b: { id: 'b', order: 20, label: 'B', parentSystemId: 'a' }
+        }
+      }),
+      expected: {
+        path: ['systems', 'a', 'parentSystemId'],
+        message: 'System "a" has a parent cycle'
+      }
+    },
+    {
+      name: 'role reportsToId cycle',
+      model: makeModel({
+        roles: {
+          'role.a': { id: 'role.a', order: 10, title: 'Role A', reportsToId: 'role.b' },
+          'role.b': { id: 'role.b', order: 20, title: 'Role B', reportsToId: 'role.a' }
+        }
+      }),
+      expected: {
+        path: ['roles', 'role.a', 'reportsToId'],
+        message: 'Role "role.a" has a reportsToId cycle'
+      }
+    },
+    {
+      name: 'duplicate sidebar paths',
+      model: makeModel({
+        navigation: {
+          ...DEFAULT_ORGANIZATION_MODEL.navigation,
+          sidebar: {
+            primary: {
+              first: { type: 'surface', label: 'First', path: '/shared', surfaceType: 'page', order: 10 },
+              second: { type: 'surface', label: 'Second', path: '/shared/', surfaceType: 'page', order: 20 }
+            },
+            bottom: {}
+          }
+        }
+      }),
+      expected: {
+        path: ['navigation', 'sidebar', 'primary', 'second', 'path'],
+        message: 'Sidebar surface path "/shared/" duplicates surface "first"'
+      }
+    },
+    {
+      name: 'topology invalid refs',
+      model: makeModel({
+        topology: {
+          version: 1,
+          relationships: {
+            missing: {
+              from: { kind: 'system', id: 'missing' },
+              kind: 'uses',
+              to: { kind: 'system', id: 'test' }
+            }
+          }
+        }
+      }),
+      expected: {
+        path: ['topology', 'relationships', 'missing', 'from'],
+        message: 'Topology relationship "missing" from references unknown system "missing"'
+      }
+    },
+    {
+      name: 'knowledge kind target mismatch',
+      model: makeModel({
+        roles: {
+          'role.ops': { id: 'role.ops', order: 10, title: 'Ops' }
+        },
+        knowledge: {
+          'knowledge.strategy': {
+            id: 'knowledge.strategy',
+            kind: 'strategy',
+            title: 'Strategy',
+            summary: 'Strategy summary',
+            body: 'Body',
+            updatedAt: '2026-06-04',
+            ownerIds: [],
+            links: [{ target: { kind: 'role', id: 'role.ops' }, nodeId: 'role:role.ops' }]
+          }
+        }
+      }),
+      expected: {
+        path: ['knowledge', 'knowledge.strategy', 'links', 0, 'target', 'kind'],
+        message: 'Knowledge node "knowledge.strategy" kind "strategy" cannot govern role targets'
+      }
+    },
+    {
+      name: 'entity unknown system',
+      model: makeModel({
+        entities: {
+          lead: { id: 'lead', order: 10, label: 'Lead', ownedBySystemId: 'missing' }
+        }
+      }),
+      expected: {
+        path: ['entities', 'lead', 'ownedBySystemId'],
+        message: 'Entity "lead" references unknown ownedBySystemId "missing"'
+      }
+    },
+    {
+      name: 'policy unknown action',
+      model: makeModel({
+        policies: {
+          'policy.test': {
+            id: 'policy.test',
+            order: 10,
+            label: 'Test Policy',
+            trigger: { kind: 'action-invocation', actionId: 'missing.action' },
+            actions: [{ kind: 'invoke-action', actionId: 'missing.action' }],
+            appliesTo: { systemIds: [], actionIds: ['missing.action'], resourceIds: [], roleIds: [] }
+          }
+        }
+      }),
+      expected: {
+        path: ['policies', 'policy.test', 'appliesTo', 'actionIds', 0],
+        message: 'Policy "policy.test" applies to unknown action "missing.action"'
+      }
+    },
+    {
+      name: 'active system with no enabled descendants',
+      model: makeModel({
+        systems: {
+          parent: {
+            id: 'parent',
+            order: 10,
+            label: 'Parent',
+            lifecycle: 'active',
+            systems: {
+              child: { id: 'child', order: 10, label: 'Child', lifecycle: 'archived' }
+            }
+          }
+        }
+      }),
+      expected: {
+        path: ['systems', 'parent', 'lifecycle'],
+        message: 'System "parent" is active but has no active descendants'
+      }
+    }
+  ])('emits focused refinement issues for $name', ({ model, expected }) => {
+    const issues = collectRefinementIssues(model)
+
+    expect(issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: z.ZodIssueCode.custom,
+          path: expected.path,
+          message: expected.message
+        })
+      ])
+    )
+  })
 })

package/src/organization-model/cross-ref.ts

@@ -11,7 +11,7 @@
 
 import { compileOrganizationOntology } from './ontology'
 import { listAllSystems } from './helpers'
-import type { OntologyKind } from './ontology'
+import type { OntologyCompilation, OntologyKind } from './ontology'
 import type { OrganizationModel } from './types'
 
 // ---------------------------------------------------------------------------
@@ -69,12 +69,23 @@ export interface OmCrossRefIndex {
   stageIds: Set<string>
 }
 
+export interface OmCompilationContext {
+  crossRefIndex: OmCrossRefIndex
+  ontologyCompilation: OntologyCompilation
+}
+
+const omCompilationContextCache = new WeakMap<OrganizationModel, OmCompilationContext>()
+
 /**
- * Build the OmCrossRefIndex from a resolved OrganizationModel.
+ * Build the OmCrossRefIndex from a resolved OrganizationModel and a compiled
+ * ontology result.
  *
  * Call once per validation pass and share the result across all checks.
  */
-export function buildOmCrossRefIndex(model: OrganizationModel): OmCrossRefIndex {
+function buildOmCrossRefIndexFromOntology(
+  model: OrganizationModel,
+  ontologyCompilation: OntologyCompilation
+): OmCrossRefIndex {
   // Systems: keyed by path AND by system.id (path-OR-id resolution)
   const systemsById = new Map<string, unknown>()
   for (const { path, system } of listAllSystems(model)) {
@@ -91,8 +102,6 @@ export function buildOmCrossRefIndex(model: OrganizationModel): OmCrossRefIndex
   const customerSegmentIds = new Set(Object.keys(model.customers ?? {}))
   const offeringIds = new Set(Object.keys(model.offerings ?? {}))
 
-  const ontologyCompilation = compileOrganizationOntology(model)
-
   const ontologyIndexByKind: Record<OntologyKind, Record<string, unknown>> = {
     object: ontologyCompilation.ontology.objectTypes,
     link: ontologyCompilation.ontology.linkTypes,
@@ -136,6 +145,33 @@ export function buildOmCrossRefIndex(model: OrganizationModel): OmCrossRefIndex
   }
 }
 
+/**
+ * Build and memoize the shared OM compilation context for a resolved model.
+ *
+ * This combines ontology compilation and cross-reference indexing so validation
+ * gates can reuse one ontology pass while preserving browser-safe imports.
+ */
+export function buildOmCompilationContext(model: OrganizationModel): OmCompilationContext {
+  const cached = omCompilationContextCache.get(model)
+  if (cached !== undefined) return cached
+
+  const ontologyCompilation = compileOrganizationOntology(model)
+  const crossRefIndex = buildOmCrossRefIndexFromOntology(model, ontologyCompilation)
+  const context = { crossRefIndex, ontologyCompilation }
+  omCompilationContextCache.set(model, context)
+  return context
+}
+
+/**
+ * Build the OmCrossRefIndex from a resolved OrganizationModel.
+ *
+ * Back-compat helper retained for existing consumers. New validation paths that
+ * also need ontology diagnostics should prefer buildOmCompilationContext().
+ */
+export function buildOmCrossRefIndex(model: OrganizationModel): OmCrossRefIndex {
+  return buildOmCompilationContext(model).crossRefIndex
+}
+
 // ---------------------------------------------------------------------------
 // Canonical resolution functions
 // ---------------------------------------------------------------------------

package/src/organization-model/defaults.ts

@@ -7,11 +7,11 @@
  *
  * It does NOT contain Elevasis-specific identity, systems, or action entries.
  * Runtime consumers that need the full Elevasis canonical model should import
- * `canonicalOrganizationModel` from `@repo/elevasis-core` instead.
+ * `canonicalOrganizationModel` from the tenant-owned organization model package instead.
  *
  * Elevasis-specific systems, actions (LEAD_GEN_ACTION_ENTRIES, CRM_ACTION_ENTRIES,
  * DEFAULT_ORGANIZATION_MODEL_ACTIONS), and the platform system description have been
- * relocated to `@repo/elevasis-core/src/organization-model/`.
+ * relocated to the tenant-owned organization model package.
  */
 import type { OrganizationModel } from './types'
 import { DEFAULT_ORGANIZATION_MODEL_BRANDING } from './domains/branding'

package/src/organization-model/domains/actions.ts

@@ -96,7 +96,7 @@ export const ActionsDomainSchema = z
  * Generic empty default for the actions domain.
  * Elevasis-specific action entries (LEAD_GEN_ACTION_ENTRIES, CRM_ACTION_ENTRIES,
  * DEFAULT_ORGANIZATION_MODEL_ACTIONS) have been relocated to
- * `@repo/elevasis-core/src/organization-model/actions.ts`.
+ * the tenant-owned organization model package.
  * Tenant OM configs supply their own action entries via `resolveOrganizationModel`.
  */
 export const DEFAULT_ORGANIZATION_MODEL_ACTIONS: z.infer<typeof ActionsDomainSchema> = {}

package/src/organization-model/domains/systems.ts

@@ -1,7 +1,6 @@
 import { z, type ZodType } from 'zod'
 import { ActionRefSchema } from './actions'
 import {
-  ColorTokenSchema,
   DescriptionSchema,
   IconNameSchema,
   LabelSchema,
@@ -156,7 +155,6 @@ export interface SystemEntry {
   status?: 'active' | 'deprecated' | 'archived'
   path?: string
   icon?: string
-  color?: string
   uiPosition?: 'sidebar-primary' | 'sidebar-bottom'
   enabled?: boolean
   devOnly?: boolean
@@ -213,8 +211,6 @@ export const SystemEntrySchema: ZodType<SystemEntry> = z
     path: PathSchema.optional(),
     /** @deprecated Use ui.icon. Kept for one-cycle Feature compatibility. */
     icon: IconNameSchema.optional(),
-    /** @deprecated Feature color token, retained for one-cycle compatibility. */
-    color: ColorTokenSchema.optional(),
     /** @deprecated UI placement hint, retained for one-cycle compatibility. */
     uiPosition: UiPositionSchema.optional(),
     /** @deprecated Use lifecycle. */

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

@@ -43,17 +43,18 @@ Edge kinds:
 
 - `contains`
 - `references`
-- `maps_to`
-- `uses`
-- `governs`
-- `governed-by`
-- `links`
-- `affects`
-- `emits`
+- `maps_to`
+- `uses`
+- `governs`
+- `links`
+- `affects`
+- `emits`
 - `originates_from`
 - `triggers`
 - `applies_to`
-- `effects`
+- `effects`
+
+`governed-by` is a Knowledge Graph route verb for traversing incoming `governs` edges; it is not an Organization Graph edge kind.
 
 System nodes come from the id-keyed `OrganizationModel.systems` map. Their graph IDs use `system:<id>`, such as `system:sales.crm`.
 

package/src/organization-model/resolve.ts

@@ -79,13 +79,15 @@ function pruneFlatSystemDescendantCollisions(
 }
 
 function deepMerge<T>(base: T, override: DeepPartial<T> | undefined): T {
-  if (override === undefined) {
-    return base
-  }
-
-  if (Array.isArray(base)) {
-    return (override as T) ?? base
-  }
+  if (override === undefined) {
+    return base
+  }
+
+  // Arrays are override-replaced, not concatenated. Flattened record domains get
+  // additive-by-id object merging; see flatten-additive-merge.test.ts.
+  if (Array.isArray(base)) {
+    return (override as T) ?? base
+  }
 
   if (!isPlainObject(base) || !isPlainObject(override)) {
     return (override as T) ?? base

package/src/organization-model/scaffolders/scaffoldKnowledgeNode.ts

@@ -13,6 +13,7 @@ export function scaffoldKnowledgeNode(model: OrganizationModel, spec: KnowledgeN
   const kind = spec.kind ?? 'reference'
   const links = spec.systemPath === undefined ? '' : `links:\n  - system:${spec.systemPath}\n`
   const ownerIds = spec.ownerRoleId === undefined ? '' : `ownerIds:\n  - ${spec.ownerRoleId}\n`
+  // Non-System scaffolds only create linked projects when explicitly requested.
 
   return {
     intent: 'knowledge',

package/src/organization-model/scaffolders/scaffoldOntologyRecord.ts

@@ -2,12 +2,39 @@ import type { OrganizationModel } from '..'
 import { assertSystemExists, makeOntologyId, ontologyMapName, titleize } from './helpers'
 import type { OmScaffoldPlan, OntologyRecordScaffoldSpec } from './types'
 
+function kindSpecificFields(spec: OntologyRecordScaffoldSpec): Record<string, unknown> {
+  if (spec.kind === 'link') {
+    return {
+      from: makeOntologyId(spec.systemPath, 'object', 'source-object'),
+      to: makeOntologyId(spec.systemPath, 'object', 'target-object')
+    }
+  }
+
+  if (spec.kind === 'action') {
+    return { actsOn: [] }
+  }
+
+  if (spec.kind === 'group') {
+    return { members: [] }
+  }
+
+  return {}
+}
+
 export function scaffoldOntologyRecord(model: OrganizationModel, spec: OntologyRecordScaffoldSpec): OmScaffoldPlan {
   assertSystemExists(model, spec.systemPath)
   const localId = spec.localId ?? spec.id
   const ontologyId = makeOntologyId(spec.systemPath, spec.kind, localId)
   const label = spec.label ?? titleize(localId)
   const mapName = ontologyMapName(spec.kind)
+  const snippetRecord = {
+    id: ontologyId,
+    label,
+    ownerSystemId: spec.systemPath,
+    ...(spec.description === undefined ? {} : { description: spec.description }),
+    ...kindSpecificFields(spec)
+  }
+  // Non-System scaffolds only create linked projects when explicitly requested.
 
   return {
     intent: 'ontology',
@@ -18,12 +45,7 @@ export function scaffoldOntologyRecord(model: OrganizationModel, spec: OntologyR
       {
         path: 'packages/elevasis-core/src/organization-model/systems.ts',
         description: `Add this record under ${spec.systemPath}.ontology.${mapName}.`,
-        snippet: `${JSON.stringify(ontologyId)}: {
-  id: ${JSON.stringify(ontologyId)},
-  label: ${JSON.stringify(label)},
-  ownerSystemId: ${JSON.stringify(spec.systemPath)}${spec.description === undefined ? '' : `,
-  description: ${JSON.stringify(spec.description)}`}
-}`
+        snippet: `${JSON.stringify(ontologyId)}: ${JSON.stringify(snippetRecord, null, 2)}`
       }
     ],
     warnings: [],

package/src/organization-model/scaffolders/scaffoldResource.ts

@@ -11,6 +11,7 @@ export function scaffoldResource(model: OrganizationModel, spec: ResourceScaffol
   const label = spec.label ?? titleize(spec.id)
   const kind = spec.kind ?? 'workflow'
   const slug = slugify(spec.id)
+  // Non-System scaffolds only create linked projects when explicitly requested.
   const writes = spec.withStubWorkflow
     ? [
         {

package/src/organization-model/scaffolders/scaffoldSystem.ts

@@ -22,6 +22,7 @@ export function scaffoldSystem(model: OrganizationModel, spec: SystemScaffoldSpe
   const featureSlug = slugify(systemPath.replaceAll('.', '-'))
   const knowledgeId = `knowledge.${featureSlug}-system-overview`
   const order = nextSystemOrder(model, parentPath)
+  // Systems default to opening a linked project because they usually start a multi-file build chain.
   const withProject = spec.withProject ?? !spec.noProject
 
   const systemEntry = `  ${JSON.stringify(localId)}: {
@@ -53,7 +54,7 @@ export function scaffoldSystem(model: OrganizationModel, spec: SystemScaffoldSpe
         path: `packages/ui/src/features/${featureSlug}/manifest.stub.ts`,
         mode: 'create',
         description: 'SystemModule manifest stub. Route files are intentionally not generated.',
-        content: `import type { SystemModule } from '@repo/ui'\n\nexport const ${featureSlug.replaceAll('-', '_')}Manifest: SystemModule = {\n  systemId: ${JSON.stringify(systemPath)},\n  label: ${JSON.stringify(label)},\n  routes: []\n}\n`
+        content: `import type { SystemModule } from '@repo/ui'\n\nexport const ${featureSlug.replaceAll('-', '_')}Manifest: SystemModule = {\n  key: ${JSON.stringify(featureSlug)},\n  systemId: ${JSON.stringify(systemPath)}\n}\n`
       },
       {
         path: `packages/elevasis-core/src/knowledge/nodes/${featureSlug}-system-overview.mdx.stub`,

package/src/organization-model/schema-refinements.ts

@@ -3,8 +3,8 @@ import type { SidebarNode } from './domains/navigation'
 import { ContractRefSchema } from './domains/resources'
 import type { SystemEntry } from './domains/systems'
 import type { OmTopologyNodeRef } from './domains/topology'
-import { buildOmCrossRefIndex, knowledgeTargetExists, ONTOLOGY_REFERENCE_KEY_KINDS } from './cross-ref'
-import { compileOrganizationOntology, listResolvedOntologyRecords, type OntologyKind } from './ontology'
+import { buildOmCompilationContext, knowledgeTargetExists, ONTOLOGY_REFERENCE_KEY_KINDS } from './cross-ref'
+import { listResolvedOntologyRecords, type OntologyKind } from './ontology'
 import type { OrganizationModel } from './types'
 
 function addIssue(ctx: z.RefinementCtx, path: Array<string | number>, message: string): void {
@@ -403,10 +403,8 @@ export function refineOrganizationModel(model: OrganizationModel, ctx: z.Refinem
     })
   })
   // Shared cross-reference index — single source of truth for (kind, id) resolution.
-  const idx = buildOmCrossRefIndex(model)
+  const { crossRefIndex: idx, ontologyCompilation } = buildOmCompilationContext(model)
   const { ontologyIndexByKind, ontologyIds } = idx
-  // ontologyCompilation retained locally for listResolvedOntologyRecords and diagnostics.
-  const ontologyCompilation = compileOrganizationOntology(model)
 
   function topologyTargetExists(ref: OmTopologyNodeRef): boolean {
     if (ref.kind === 'system') return systemsById.has(ref.id)

package/src/platform/registry/__tests__/validation.test.ts

@@ -960,6 +960,34 @@ describe('validateResourceGovernance', () => {
 })
 
 describe('validateDeclaredSystemInterfaceReadiness', () => {
+  it('allows empty apiInterface markers for systems without scoped API resources', () => {
+    expect(() =>
+      validateDeclaredSystemInterfaceReadiness('test-org', {
+        systems: {
+          'sales.lead-gen': {
+            id: 'sales.lead-gen',
+            label: 'Lead Gen',
+            order: 10,
+            apiInterface: {
+              lifecycle: 'active',
+              readinessProfile: 'sales.lead-gen.api',
+              resourceIds: []
+            }
+          },
+          'sales.crm': {
+            id: 'sales.crm',
+            label: 'CRM',
+            order: 20,
+            apiInterface: {
+              lifecycle: 'active',
+              resourceIds: []
+            }
+          }
+        }
+      })
+    ).not.toThrow()
+  })
+
   it('scans flat system.apiInterface markers', () => {
     let error: unknown
     try {

package/src/platform/registry/validation.ts

@@ -705,6 +705,24 @@ export function validateDeclaredSystemInterfaceReadiness(
     if (system.apiInterface === undefined) continue
 
     const interfaceKey = 'api'
+    const resourceIds = system.apiInterface.resourceIds ?? []
+    if (resourceIds.length === 0) {
+      const readinessProfile = system.apiInterface.readinessProfile
+      if (
+        readinessProfile !== undefined &&
+        !SYSTEM_INTERFACE_PROFILES.some((profile) => profile.readinessProfile === readinessProfile)
+      ) {
+        addSystemInterfaceIssue(issues, orgName, path, interfaceKey, {
+          family: 'SYSTEM_INTERFACE_INVALID',
+          code: 'unknown-readiness-profile',
+          path: `systems.${path}.apiInterface.readinessProfile`,
+          ref: readinessProfile,
+          message: `System Interface "${path}/${interfaceKey}" references unknown readiness profile "${readinessProfile}".`
+        })
+      }
+      continue
+    }
+
     const result = computeInterfaceReadiness(model, { systemPath: path, interfaceKey })
     for (const issue of result.issues) {
       addSystemInterfaceIssue(issues, orgName, path, interfaceKey, issue)

package/src/test-utils/mocks/supabase.ts

@@ -27,7 +27,7 @@ export interface MockSupabaseFixtures {
  *
  * Usage:
  * ```typescript
- * import { createMockSupabaseClient, TEST_USERS, TEST_ORGS } from '@repo/core/test-utils'
+ * import { createMockSupabaseClient, TEST_USERS, TEST_ORGS } from '@elevasis/core/test-utils'
  *
  * const mockClient = createMockSupabaseClient({
  *   users: [TEST_USERS.admin, TEST_USERS.regularUser],

package/src/test-utils/mocks/workos.ts

@@ -18,7 +18,7 @@ export interface UserContext {
  *
  * Usage:
  * ```typescript
- * import { createMockWorkOSClient, TEST_USERS } from '@repo/core/test-utils'
+ * import { createMockWorkOSClient, TEST_USERS } from '@elevasis/core/test-utils'
  *
  * const mockWorkOS = createMockWorkOSClient({
  *   validTokens: {
@@ -72,7 +72,7 @@ export function createMockWorkOSClient(options: {
  *
  * Usage:
  * ```typescript
- * import { createMockVerifyJWT, TEST_USERS } from '@repo/core/test-utils'
+ * import { createMockVerifyJWT, TEST_USERS } from '@elevasis/core/test-utils'
  *
  * const mockVerifyJWT = createMockVerifyJWT({
  *   'valid-token': {