@elevasis/core 0.24.1 → 0.25.0

package/src/organization-model/__tests__/deprecate-helpers.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest'
+import {
+  getSystemDeprecationDependents,
+  type OrganizationModel,
+  type OmTopologyDomain
+} from '../index'
+
+const model = {
+  systems: {
+    sales: {
+      id: 'sales',
+      order: 1,
+      label: 'Sales',
+      lifecycle: 'active',
+      systems: {
+        crm: {
+          id: 'sales.crm',
+          order: 2,
+          label: 'CRM',
+          lifecycle: 'active'
+        }
+      }
+    }
+  },
+  resources: {
+    'crm-active-workflow': {
+      id: 'crm-active-workflow',
+      order: 1,
+      kind: 'workflow',
+      systemPath: 'sales.crm',
+      status: 'active',
+      codeRefs: []
+    },
+    'crm-archived-workflow': {
+      id: 'crm-archived-workflow',
+      order: 2,
+      kind: 'workflow',
+      systemPath: 'sales.crm',
+      status: 'archived',
+      codeRefs: []
+    }
+  },
+  knowledge: {},
+  topology: {
+    version: 1,
+    relationships: {
+      'crm-active-uses-sales': {
+        from: { kind: 'resource', id: 'crm-active-workflow' },
+        kind: 'uses',
+        to: { kind: 'system', id: 'sales' }
+      },
+      'archived-resource-edge': {
+        from: { kind: 'resource', id: 'crm-archived-workflow' },
+        kind: 'uses',
+        to: { kind: 'system', id: 'sales' }
+      }
+    }
+  } satisfies OmTopologyDomain
+} as OrganizationModel
+
+describe('getSystemDeprecationDependents', () => {
+  it('enumerates active resources and topology edges for a system tree', () => {
+    const dependents = getSystemDeprecationDependents(model, 'sales', { includeDescendants: true })
+
+    expect(dependents.resources.map((resource) => resource.id)).toEqual(['crm-active-workflow'])
+    expect(dependents.topologyEdges.map((edge) => edge.id).sort()).toEqual([
+      'archived-resource-edge',
+      'crm-active-uses-sales'
+    ])
+  })
+})

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

@@ -31,13 +31,15 @@ describe('organization-model resolve', () => {
     const business = model.navigation.sidebar.primary.business
     expect(business?.type).toBe('group')
     if (business?.type === 'group') {
-      expect(business.children.clients).toMatchObject({
-        type: 'surface',
-        path: '/clients',
-        targets: { systems: ['clients'] }
-      })
-    }
-  })
+      expect(business.children.clients).toMatchObject({
+        type: 'surface',
+        path: '/clients',
+        icon: 'clients',
+        targets: { systems: ['clients'] }
+      })
+    }
+    expect(model.systems.clients?.icon).toBe('clients')
+  })
 
   it('adds tenant systems additively to the merged record', () => {
     const baseSize = Object.keys(resolveOrganizationModel().systems).length

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

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest'
+import { DEFAULT_ORGANIZATION_MODEL, scaffoldOrganizationModel, type OrganizationModel } from '..'
+
+const BASE_MODEL: OrganizationModel = {
+  ...DEFAULT_ORGANIZATION_MODEL,
+  systems: {
+    sales: {
+      id: 'sales',
+      order: 10,
+      label: 'Sales',
+      lifecycle: 'active',
+      systems: {
+        crm: {
+          id: 'sales.crm',
+          order: 20,
+          label: 'CRM',
+          lifecycle: 'active'
+        }
+      }
+    }
+  },
+  resources: {},
+  knowledge: {}
+}
+
+describe('organization-model scaffolders', () => {
+  it('plans the minimal system scaffold without route files', () => {
+    const plan = scaffoldOrganizationModel(BASE_MODEL, {
+      intent: 'system',
+      id: 'sales.partners',
+      label: 'Partners',
+      description: 'Partner operations.',
+      noProject: true
+    })
+
+    expect(plan.intent).toBe('system')
+    expect(plan.id).toBe('sales.partners')
+    expect(plan.edits.map((edit) => edit.path)).toEqual(
+      expect.arrayContaining([
+        'packages/elevasis-core/src/organization-model/systems.ts',
+        'packages/elevasis-core/src/organization-model/navigation.ts',
+        'packages/elevasis-core/src/organization-model/roles.ts',
+        'packages/elevasis-core/src/organization-model/assembly.ts',
+        'packages/elevasis-core/src/organization-model/knowledge.ts'
+      ])
+    )
+    expect(plan.writes.some((write) => write.path.endsWith('manifest.stub.ts'))).toBe(true)
+    expect(plan.writes.some((write) => write.path.includes('/routes/'))).toBe(false)
+    expect(plan.projectCommand).toBeUndefined()
+  })
+
+  it('defaults system scaffolds to a project chain unless skipped', () => {
+    const plan = scaffoldOrganizationModel(BASE_MODEL, {
+      intent: 'system',
+      id: 'sales.enablement',
+      label: 'Enablement'
+    })
+
+    expect(plan.projectCommand).toContain('project:create --link-om sales.enablement')
+  })
+
+  it('keeps ontology/resource/knowledge project chains opt-in', () => {
+    const ontology = scaffoldOrganizationModel(BASE_MODEL, {
+      intent: 'ontology',
+      id: 'deal-score',
+      systemPath: 'sales.crm',
+      kind: 'object'
+    })
+    const resource = scaffoldOrganizationModel(BASE_MODEL, {
+      intent: 'resource',
+      id: 'crm-score-workflow',
+      systemPath: 'sales.crm'
+    })
+    const knowledge = scaffoldOrganizationModel(BASE_MODEL, {
+      intent: 'knowledge',
+      id: 'knowledge.crm-scoring',
+      systemPath: 'sales.crm'
+    })
+
+    expect(ontology.projectCommand).toBeUndefined()
+    expect(resource.projectCommand).toBeUndefined()
+    expect(knowledge.projectCommand).toBeUndefined()
+  })
+
+  it('rejects duplicate system paths during planning', () => {
+    expect(() =>
+      scaffoldOrganizationModel(BASE_MODEL, {
+        intent: 'system',
+        id: 'sales.crm'
+      })
+    ).toThrow('system already exists: sales.crm')
+  })
+})

package/src/organization-model/defaults.ts

@@ -46,7 +46,7 @@ const DEFAULT_ORGANIZATION_MODEL_NAVIGATION: OrganizationModelNavigation = {
       business: {
         type: 'group',
         label: 'Business',
-        icon: 'business',
+        icon: 'briefcase',
         order: 20,
         children: {
           sales: {
@@ -63,7 +63,7 @@ const DEFAULT_ORGANIZATION_MODEL_NAVIGATION: OrganizationModelNavigation = {
             label: 'Clients',
             path: '/clients',
             surfaceType: 'list',
-            icon: 'projects',
+            icon: 'clients',
             order: 20,
             targets: { systems: ['clients'] }
           },
@@ -438,7 +438,7 @@ export const DEFAULT_ORGANIZATION_MODEL: OrganizationModel = {
       enabled: true,
       lifecycle: 'active',
       color: 'orange',
-      icon: 'projects',
+      icon: 'clients',
       path: '/clients'
     },
     operations: {

package/src/organization-model/helpers.ts

@@ -2,6 +2,7 @@ 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'
+import type { OmTopologyRelationship } from './domains/topology'
 
 // W1A has landed: ContentNode and SystemEntry (with content + subsystems) are now
 // defined in their canonical locations.
@@ -314,14 +315,80 @@ export function resolveSystemConfig(model: OrganizationModel, path: string): Rec
  * 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[] {
+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))
-  )
-}
+  return Object.values(model.resources ?? {}).filter(
+    (r) => r.systemPath === systemPath || (includeDescendants && r.systemPath.startsWith(prefix))
+  )
+}
+
+export interface SystemTopologyEdge {
+  id: string
+  relationship: OmTopologyRelationship
+}
+
+export interface SystemDeprecationDependents {
+  resources: ResourceEntry[]
+  topologyEdges: SystemTopologyEdge[]
+}
+
+function systemPathIsInScope(candidate: string, systemPath: string, includeDescendants: boolean): boolean {
+  return candidate === systemPath || (includeDescendants && candidate.startsWith(`${systemPath}.`))
+}
+
+function topologyRelationshipTouchesSystem(
+  relationship: OmTopologyRelationship,
+  systemPath: string,
+  resourceIds: Set<string>,
+  includeDescendants: boolean
+): boolean {
+  if (
+    relationship.systemPath !== undefined &&
+    systemPathIsInScope(relationship.systemPath, systemPath, includeDescendants)
+  ) {
+    return true
+  }
+
+  for (const ref of [relationship.from, relationship.to]) {
+    if (ref.kind === 'system' && systemPathIsInScope(ref.id, systemPath, includeDescendants)) return true
+    if (ref.kind === 'resource' && resourceIds.has(ref.id)) return true
+  }
+
+  return false
+}
+
+export function getTopologyEdgesForSystem(
+  model: OrganizationModel,
+  systemPath: string,
+  options: { includeDescendants?: boolean; resourceIds?: Iterable<string> } = {}
+): SystemTopologyEdge[] {
+  const { includeDescendants = false } = options
+  const resourceIds = new Set(
+    options.resourceIds ?? getResourcesForSystem(model, systemPath, { includeDescendants }).map((r) => r.id)
+  )
+
+  return Object.entries(model.topology?.relationships ?? {})
+    .filter(([, relationship]) =>
+      topologyRelationshipTouchesSystem(relationship, systemPath, resourceIds, includeDescendants)
+    )
+    .map(([id, relationship]) => ({ id, relationship }))
+}
+
+export function getSystemDeprecationDependents(
+  model: OrganizationModel,
+  systemPath: string,
+  options: { includeDescendants?: boolean } = {}
+): SystemDeprecationDependents {
+  const resources = getResourcesForSystem(model, systemPath, options).filter((resource) => resource.status === 'active')
+  const resourceIds = new Set(resources.map((resource) => resource.id))
+
+  return {
+    resources,
+    topologyEdges: getTopologyEdgesForSystem(model, systemPath, { ...options, resourceIds })
+  }
+}

package/src/organization-model/icons.ts

@@ -8,6 +8,7 @@ export const ORGANIZATION_MODEL_ICON_TOKENS = [
   'crm',
   'lead-gen',
   'projects',
+  'clients',
   'operations',
   'monitoring',
   'knowledge',

package/src/organization-model/index.ts

@@ -13,8 +13,9 @@ export * from './resolve'
 export * from './foundation'
 export * from './surface-projection'
 export * from './helpers'
-export * from './migration-helpers'
-export * from './graph'
+export * from './migration-helpers'
+export * from './scaffolders'
+export * from './graph'
 export * from './catalogs/lead-gen'
 export * from './domains/branding'
 // Phase 4: OrganizationModelSalesSchema, OrganizationModelProspectingSchema,

package/src/organization-model/published.ts

@@ -201,8 +201,21 @@ export {
 } from './domains/knowledge'
 export { defineOrganizationModel, resolveOrganizationModel, resolveOrganizationModelWithResources } from './resolve'
 export type { ResolvedSystemEntry, ResolvedOrganizationModel } from './resolve'
-export { createFoundationOrganizationModel } from './foundation'
-
+export { createFoundationOrganizationModel } from './foundation'
+export { scaffoldOrganizationModel } from './scaffolders'
+export type {
+  BaseOmScaffoldSpec,
+  KnowledgeNodeScaffoldSpec,
+  OmScaffoldEdit,
+  OmScaffoldIntent,
+  OmScaffoldPlan,
+  OmScaffoldSpec,
+  OmScaffoldWrite,
+  OntologyRecordScaffoldSpec,
+  ResourceScaffoldSpec,
+  SystemScaffoldSpec
+} from './scaffolders'
+
 export type {
   OntologyActionType,
   OntologyCatalogType,

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

@@ -0,0 +1,84 @@
+import { formatOntologyId, type OntologyKind, type OrganizationModel } from '..'
+import { getSystem, listAllSystems } from '../helpers'
+import type { OmScaffoldPlan } from './types'
+
+export function slugify(input: string): string {
+  return input
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+export function titleize(input: string): string {
+  return input
+    .split(/[-._\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ')
+}
+
+export function assertSystemPathAvailable(model: OrganizationModel, path: string): void {
+  if (getSystem(model, path) !== undefined) {
+    throw new Error(`system already exists: ${path}`)
+  }
+
+  const parent = parentPathOf(path)
+  if (parent !== undefined && getSystem(model, parent) === undefined) {
+    throw new Error(`parent system does not exist: ${parent}`)
+  }
+}
+
+export function assertSystemExists(model: OrganizationModel, path: string): void {
+  if (getSystem(model, path) === undefined) {
+    throw new Error(`system does not exist: ${path}`)
+  }
+}
+
+export function parentPathOf(path: string): string | undefined {
+  const index = path.lastIndexOf('.')
+  return index === -1 ? undefined : path.slice(0, index)
+}
+
+export function localIdOf(path: string): string {
+  return path.split('.').at(-1) ?? path
+}
+
+export function nextSystemOrder(model: OrganizationModel, parentPath?: string): number {
+  const siblings =
+    parentPath === undefined
+      ? listAllSystems(model).filter(({ path }) => !path.includes('.'))
+      : listAllSystems(model).filter(({ path }) => parentPathOf(path) === parentPath)
+  const maxOrder = siblings.reduce((max, { system }) => Math.max(max, system.order), 0)
+  return Math.ceil((maxOrder + 10) / 10) * 10
+}
+
+export function ontologyMapName(kind: OntologyKind): string {
+  const map: Record<OntologyKind, string> = {
+    object: 'objectTypes',
+    link: 'linkTypes',
+    action: 'actionTypes',
+    catalog: 'catalogTypes',
+    event: 'eventTypes',
+    interface: 'interfaceTypes',
+    'value-type': 'valueTypes',
+    property: 'sharedProperties',
+    group: 'groups',
+    surface: 'surfaces'
+  }
+  return map[kind]
+}
+
+export function makeOntologyId(systemPath: string, kind: OntologyKind, localId: string): string {
+  return formatOntologyId({ scope: systemPath, kind, localId: slugify(localId) })
+}
+
+export function addProjectNextStep(plan: OmScaffoldPlan, enabled: boolean, command: string): OmScaffoldPlan {
+  if (!enabled) return plan
+  return {
+    ...plan,
+    projectCommand: command,
+    nextSteps: [...plan.nextSteps, `Run project handoff: ${command}`]
+  }
+}

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

@@ -0,0 +1,19 @@
+import type { OrganizationModel } from '..'
+import { scaffoldKnowledgeNode } from './scaffoldKnowledgeNode'
+import { scaffoldOntologyRecord } from './scaffoldOntologyRecord'
+import { scaffoldResource } from './scaffoldResource'
+import { scaffoldSystem } from './scaffoldSystem'
+import type { OmScaffoldPlan, OmScaffoldSpec } from './types'
+
+export function scaffoldOrganizationModel(model: OrganizationModel, spec: OmScaffoldSpec): OmScaffoldPlan {
+  if (spec.intent === 'system') return scaffoldSystem(model, spec)
+  if (spec.intent === 'ontology') return scaffoldOntologyRecord(model, spec)
+  if (spec.intent === 'resource') return scaffoldResource(model, spec)
+  return scaffoldKnowledgeNode(model, spec)
+}
+
+export * from './types'
+export { scaffoldKnowledgeNode } from './scaffoldKnowledgeNode'
+export { scaffoldOntologyRecord } from './scaffoldOntologyRecord'
+export { scaffoldResource } from './scaffoldResource'
+export { scaffoldSystem } from './scaffoldSystem'

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

@@ -0,0 +1,48 @@
+import type { OrganizationModel } from '..'
+import { assertSystemExists, slugify, titleize } from './helpers'
+import type { KnowledgeNodeScaffoldSpec, OmScaffoldPlan } from './types'
+
+export function scaffoldKnowledgeNode(model: OrganizationModel, spec: KnowledgeNodeScaffoldSpec): OmScaffoldPlan {
+  if (spec.systemPath !== undefined) assertSystemExists(model, spec.systemPath)
+  if (model.knowledge?.[spec.id] !== undefined) {
+    throw new Error(`knowledge node already exists: ${spec.id}`)
+  }
+
+  const title = spec.label ?? titleize(spec.id.replace(/^knowledge\./, ''))
+  const slug = slugify(spec.id.replace(/^knowledge\./, ''))
+  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`
+
+  return {
+    intent: 'knowledge',
+    id: spec.id,
+    summary: `Scaffold ${kind} knowledge node "${spec.id}".`,
+    writes: [
+      {
+        path: `packages/elevasis-core/src/knowledge/nodes/${slug}.mdx.stub`,
+        mode: 'create',
+        description: 'Knowledge node MDX skeleton.',
+        content: `---\nid: ${spec.id}\nkind: ${kind}\ntitle: ${JSON.stringify(title)}\nsummary: ${JSON.stringify(spec.description ?? `${title} knowledge node.`)}\n${links}${ownerIds}updatedAt: 2026-05-15\n---\n\n## Overview\n\nCapture the durable operating knowledge here.\n`
+      }
+    ],
+    edits: [
+      {
+        path: 'packages/elevasis-core/src/organization-model/knowledge.ts',
+        description: 'Register this generated node after replacing the .stub suffix.',
+        snippet: `${JSON.stringify(spec.id)}`
+      }
+    ],
+    warnings: [],
+    nextSteps: [
+      'Replace the .stub suffix after the node is ready to become canonical.',
+      spec.systemPath === undefined
+        ? 'Add links to the OM nodes this knowledge governs.'
+        : `Run pnpm exec elevasis om:verify --scope ${spec.systemPath}.`
+    ],
+    projectCommand:
+      spec.withProject && spec.systemPath !== undefined
+        ? `pnpm exec elevasis project:create --link-om ${spec.systemPath} --title "Add ${title} knowledge" --kind om-change`
+        : undefined
+  }
+}

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

@@ -0,0 +1,38 @@
+import type { OrganizationModel } from '..'
+import { assertSystemExists, makeOntologyId, ontologyMapName, titleize } from './helpers'
+import type { OmScaffoldPlan, OntologyRecordScaffoldSpec } from './types'
+
+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)
+
+  return {
+    intent: 'ontology',
+    id: ontologyId,
+    summary: `Scaffold ${spec.kind} ontology record "${ontologyId}".`,
+    writes: [],
+    edits: [
+      {
+        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)}`}
+}`
+      }
+    ],
+    warnings: [],
+    nextSteps: [
+      'Wire any cross-references using canonical ontology IDs.',
+      `Run pnpm exec elevasis om:verify --scope ${spec.systemPath}.`
+    ],
+    projectCommand: spec.withProject
+      ? `pnpm exec elevasis project:create --link-om ${spec.systemPath} --title "Add ${label} ontology" --kind om-change`
+      : undefined
+  }
+}

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

@@ -0,0 +1,59 @@
+import type { OrganizationModel } from '..'
+import { assertSystemExists, slugify, titleize } from './helpers'
+import type { OmScaffoldPlan, ResourceScaffoldSpec } from './types'
+
+export function scaffoldResource(model: OrganizationModel, spec: ResourceScaffoldSpec): OmScaffoldPlan {
+  assertSystemExists(model, spec.systemPath)
+  if (model.resources?.[spec.id] !== undefined) {
+    throw new Error(`resource already exists: ${spec.id}`)
+  }
+
+  const label = spec.label ?? titleize(spec.id)
+  const kind = spec.kind ?? 'workflow'
+  const slug = slugify(spec.id)
+  const writes = spec.withStubWorkflow
+    ? [
+        {
+          path: `packages/elevasis-core/src/workflows/${slug}.stub.ts`,
+          mode: 'create' as const,
+          description: 'Optional workflow implementation stub. Runtime wiring remains manual.',
+          content: `// Stub only. Replace with a real workflow implementation before registering the resource.\nexport const ${slug.replaceAll('-', '_')}Workflow = {\n  id: ${JSON.stringify(spec.id)}\n}\n`
+        }
+      ]
+    : []
+
+  return {
+    intent: 'resource',
+    id: spec.id,
+    summary: `Scaffold ${kind} Resource "${spec.id}" for System "${spec.systemPath}".`,
+    writes,
+    edits: [
+      {
+        path: 'packages/elevasis-core/src/organization-model/resources.ts',
+        description: 'Add this descriptor to platformResources/platformResourceDescriptors.',
+        snippet: `${JSON.stringify(spec.id)}: {
+  id: ${JSON.stringify(spec.id)},
+  order: 0,
+  kind: ${JSON.stringify(kind)},
+  systemPath: ${JSON.stringify(spec.systemPath)},
+  title: ${JSON.stringify(label)},
+  ${spec.description === undefined ? '' : `description: ${JSON.stringify(spec.description)},\n  `}${spec.ownerRoleId === undefined ? '' : `ownerRoleId: ${JSON.stringify(spec.ownerRoleId)},\n  `}status: 'active',
+  codeRefs: []
+}`
+      },
+      {
+        path: 'packages/elevasis-core/src/organization-model/topology.ts',
+        description: 'Add topology relationships only when this resource triggers, uses, or requires approval from another OM node.',
+        snippet: `// topologyRelationship({ from: topologyRef('resource', ${JSON.stringify(spec.id)}), kind: 'uses', to: ... })`
+      }
+    ],
+    warnings: ['Resource ontology bindings are intentionally omitted until action/read/write contracts are known.'],
+    nextSteps: [
+      'Bind resource.ontology.actions/reads/writes after the ontology records exist.',
+      `Run pnpm exec elevasis om:verify --scope ${spec.systemPath}.`
+    ],
+    projectCommand: spec.withProject
+      ? `pnpm exec elevasis project:create --link-om ${spec.systemPath} --title "Add ${label} resource" --kind om-change`
+      : undefined
+  }
+}