@elevasis/core 0.24.0 → 0.25.0

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

@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { ModelIdSchema } from './shared'
+import { DescriptionSchema, LabelSchema, ModelIdSchema } from './shared'
 import { SystemPathSchema, SystemLifecycleSchema } from './systems'
 import { ActionInvocationSchema } from './actions'
 import { OntologyIdSchema } from '../ontology'
@@ -57,13 +57,35 @@ export const EventDescriptorSchema = EventEmissionDescriptorSchema.extend({
   ownerKind: z.enum(['resource', 'entity']).meta({ label: 'Owner kind' })
 })
 
-export const ResourceOntologyBindingSchema = z.object({
-  implements: z.array(OntologyIdSchema).optional(),
-  reads: z.array(OntologyIdSchema).optional(),
-  writes: z.array(OntologyIdSchema).optional(),
-  usesCatalogs: z.array(OntologyIdSchema).optional(),
-  emits: z.array(OntologyIdSchema).optional()
-})
+export const ResourceOntologyBindingSchema = z
+  .object({
+    actions: z.array(OntologyIdSchema).optional(),
+    primaryAction: OntologyIdSchema.optional(),
+    reads: z.array(OntologyIdSchema).optional(),
+    writes: z.array(OntologyIdSchema).optional(),
+    usesCatalogs: z.array(OntologyIdSchema).optional(),
+    emits: z.array(OntologyIdSchema).optional()
+  })
+  .superRefine((binding, ctx) => {
+    if (binding.primaryAction === undefined) return
+    if (binding.actions?.includes(binding.primaryAction)) return
+
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['primaryAction'],
+      message: 'Resource ontology primaryAction must be included in actions'
+    })
+  })
+
+type OntologyRefInput = string | { id: string }
+type ResourceOntologyBindingInput = {
+  actions?: OntologyRefInput[]
+  primaryAction?: OntologyRefInput
+  reads?: OntologyRefInput[]
+  writes?: OntologyRefInput[]
+  usesCatalogs?: OntologyRefInput[]
+  emits?: OntologyRefInput[]
+}
 
 export const CodeReferenceSchema = z.object({
   path: z
@@ -83,7 +105,11 @@ const ResourceEntryBaseSchema = z.object({
   /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
   order: z.number().default(0),
   /** Required single System membership — value is a dot-separated system path (e.g. "sales.lead-gen"). */
-  systemPath: SystemPathSchema.meta({ ref: 'system' }),
+  systemPath: SystemPathSchema.meta({ ref: 'system' }),
+  /** Executable display title owned by the OM Resource descriptor. */
+  title: LabelSchema.optional(),
+  /** Executable display description owned by the OM Resource descriptor. */
+  description: DescriptionSchema.optional(),
   /** Optional role responsible for maintaining this resource. */
   ownerRoleId: ModelIdSchema.meta({ ref: 'role' }).optional(),
   status: ResourceGovernanceStatusSchema,
@@ -97,12 +123,10 @@ const ResourceEntryBaseSchema = z.object({
   codeRefs: z.array(CodeReferenceSchema).default([])
 })
 
-export const WorkflowResourceEntrySchema = ResourceEntryBaseSchema.extend({
-  kind: z.literal('workflow'),
-  /** Mirrors WorkflowConfig.actionKey when the runtime workflow has one. */
-  actionKey: z.string().trim().min(1).max(255).optional(),
-  emits: z.array(EventEmissionDescriptorSchema).optional()
-})
+export const WorkflowResourceEntrySchema = ResourceEntryBaseSchema.extend({
+  kind: z.literal('workflow'),
+  emits: z.array(EventEmissionDescriptorSchema).optional()
+})
 
 export const AgentResourceEntrySchema = ResourceEntryBaseSchema.extend({
   kind: z.literal('agent'),
@@ -155,13 +179,32 @@ export function defineResource<const TResource extends ResourceEntry>(resource:
   return ResourceEntrySchema.parse(resource) as TResource
 }
 
-export function defineResources<const TResources extends Record<string, ResourceEntry>>(
-  resources: TResources
-): TResources {
+export function defineResources<const TResources extends Record<string, ResourceEntry>>(
+  resources: TResources
+): TResources {
   return Object.fromEntries(
     Object.entries(resources).map(([key, resource]) => [key, ResourceEntrySchema.parse(resource)])
-  ) as TResources
-}
+  ) as TResources
+}
+
+function ontologyIdFrom(input: OntologyRefInput): string {
+  return typeof input === 'string' ? input : input.id
+}
+
+function ontologyIdArrayFrom(input: OntologyRefInput[] | undefined): string[] | undefined {
+  return input?.map(ontologyIdFrom)
+}
+
+export function defineResourceOntology(input: ResourceOntologyBindingInput): ResourceOntologyBinding {
+  return ResourceOntologyBindingSchema.parse({
+    actions: ontologyIdArrayFrom(input.actions),
+    primaryAction: input.primaryAction === undefined ? undefined : ontologyIdFrom(input.primaryAction),
+    reads: ontologyIdArrayFrom(input.reads),
+    writes: ontologyIdArrayFrom(input.writes),
+    usesCatalogs: ontologyIdArrayFrom(input.usesCatalogs),
+    emits: ontologyIdArrayFrom(input.emits)
+  })
+}
 
 export type ResourceId = z.infer<typeof ResourceIdSchema>
 export type ResourceKind = z.infer<typeof ResourceKindSchema>

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

@@ -0,0 +1,261 @@
+import { z } from 'zod'
+import { OntologyIdSchema, parseOntologyId } from '../ontology'
+import { JsonValueSchema, SystemPathSchema } from './systems'
+import { ModelIdSchema } from './shared'
+import { ResourceIdSchema, type ResourceEntry } from './resources'
+
+// ---------------------------------------------------------------------------
+// Topology domain
+// ---------------------------------------------------------------------------
+//
+// Topology captures durable operational wiring. It stays separate from
+// ontology, which describes semantic meaning.
+
+const SecretLikeMetadataKeySchema = /(?:secret|password|passwd|token|api[-_]?key|credential|private[-_]?key)/i
+const SecretLikeMetadataValueSchema =
+  /(?:sk-[A-Za-z0-9_-]{12,}|pk_live_[A-Za-z0-9_-]{12,}|eyJ[A-Za-z0-9_-]{20,}|-----BEGIN (?:RSA |OPENSSH |EC )?PRIVATE KEY-----)/
+
+export const OmTopologyNodeKindSchema = z.enum([
+  'system',
+  'resource',
+  'ontology',
+  'policy',
+  'role',
+  'trigger',
+  'humanCheckpoint',
+  'externalResource'
+])
+
+export const OmTopologyRelationshipKindSchema = z.enum(['triggers', 'uses', 'approval'])
+
+export const OmTopologyNodeRefSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('system'), id: ModelIdSchema }),
+  z.object({ kind: z.literal('resource'), id: ResourceIdSchema }),
+  z.object({ kind: z.literal('ontology'), id: OntologyIdSchema }),
+  z.object({ kind: z.literal('policy'), id: ModelIdSchema }),
+  z.object({ kind: z.literal('role'), id: ModelIdSchema }),
+  z.object({ kind: z.literal('trigger'), id: ResourceIdSchema }),
+  z.object({ kind: z.literal('humanCheckpoint'), id: ResourceIdSchema }),
+  z.object({ kind: z.literal('externalResource'), id: ResourceIdSchema })
+])
+
+export const OmTopologyMetadataSchema = z
+  .record(z.string().trim().min(1).max(120), JsonValueSchema)
+  .superRefine((metadata, ctx) => {
+    function visit(value: unknown, path: Array<string | number>): void {
+      if (typeof value === 'string' && SecretLikeMetadataValueSchema.test(value)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path,
+          message: 'Topology metadata must not contain secret-like values'
+        })
+        return
+      }
+
+      if (Array.isArray(value)) {
+        value.forEach((entry, index) => visit(entry, [...path, index]))
+        return
+      }
+
+      if (typeof value !== 'object' || value === null) return
+
+      Object.entries(value).forEach(([key, entry]) => {
+        if (SecretLikeMetadataKeySchema.test(key)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [...path, key],
+            message: `Topology metadata key "${key}" looks secret-like`
+          })
+        }
+        visit(entry, [...path, key])
+      })
+    }
+
+    visit(metadata, [])
+  })
+
+export const OmTopologyRelationshipSchema = z.object({
+  from: OmTopologyNodeRefSchema,
+  kind: OmTopologyRelationshipKindSchema,
+  to: OmTopologyNodeRefSchema,
+  systemPath: SystemPathSchema.optional(),
+  required: z.boolean().optional(),
+  metadata: OmTopologyMetadataSchema.optional()
+})
+
+export const OmTopologyDomainSchema = z
+  .object({
+    version: z.literal(1).default(1),
+    relationships: z.record(z.string().trim().min(1).max(255), OmTopologyRelationshipSchema).default({})
+  })
+  .default({ version: 1, relationships: {} })
+
+export const DEFAULT_ORGANIZATION_MODEL_TOPOLOGY: z.infer<typeof OmTopologyDomainSchema> = {
+  version: 1,
+  relationships: {}
+}
+
+export type OmTopologyNodeKind = z.infer<typeof OmTopologyNodeKindSchema>
+export type OmTopologyRelationshipKind = z.infer<typeof OmTopologyRelationshipKindSchema>
+export type OmTopologyNodeRef = z.infer<typeof OmTopologyNodeRefSchema>
+export type OmTopologyMetadata = z.infer<typeof OmTopologyMetadataSchema>
+export type OmTopologyRelationship = z.infer<typeof OmTopologyRelationshipSchema>
+export type OmTopologyDomain = z.infer<typeof OmTopologyDomainSchema>
+
+type TypedIdObject = { id: string }
+type TopologyRefFactoryInput = string | TypedIdObject
+type TopologyRelationshipInput = Omit<OmTopologyRelationship, 'from' | 'to'> & {
+  from: OmTopologyNodeInput
+  to: OmTopologyNodeInput
+}
+type TopologyRelationshipOptions = Omit<Partial<OmTopologyRelationship>, 'from' | 'kind' | 'to'>
+export type OmTopologyNodeInput = OmTopologyNodeRef | ResourceEntry
+
+function idFrom(input: TopologyRefFactoryInput): string {
+  return typeof input === 'string' ? input : input.id
+}
+
+function parseRef(kind: OmTopologyNodeKind, id: string): OmTopologyNodeRef {
+  return OmTopologyNodeRefSchema.parse({ kind, id })
+}
+
+function isNodeRef(input: unknown): input is OmTopologyNodeRef {
+  return OmTopologyNodeRefSchema.safeParse(input).success
+}
+
+function isResourceEntry(input: unknown): input is ResourceEntry {
+  if (typeof input !== 'object' || input === null) return false
+  const candidate = input as Partial<ResourceEntry>
+  return (
+    typeof candidate.id === 'string' &&
+    typeof candidate.systemPath === 'string' &&
+    typeof candidate.status === 'string' &&
+    ['workflow', 'agent', 'integration', 'script'].includes(String(candidate.kind))
+  )
+}
+
+export const topologyRef = {
+  system: (system: TopologyRefFactoryInput) => parseRef('system', idFrom(system)),
+  resource: (resource: TopologyRefFactoryInput) => parseRef('resource', idFrom(resource)),
+  ontology: (record: TopologyRefFactoryInput) => parseRef('ontology', idFrom(record)),
+  policy: (policy: TopologyRefFactoryInput) => parseRef('policy', idFrom(policy)),
+  role: (role: TopologyRefFactoryInput) => parseRef('role', idFrom(role)),
+  trigger: (trigger: TopologyRefFactoryInput) => parseRef('trigger', idFrom(trigger)),
+  humanCheckpoint: (checkpoint: TopologyRefFactoryInput) => parseRef('humanCheckpoint', idFrom(checkpoint)),
+  externalResource: (externalResource: TopologyRefFactoryInput) => parseRef('externalResource', idFrom(externalResource))
+} as const
+
+export const topologyRelationship = {
+  triggers: (from: OmTopologyNodeInput, to: OmTopologyNodeInput, options: TopologyRelationshipOptions = {}) =>
+    defineTopologyRelationship({
+      ...options,
+      from,
+      kind: 'triggers',
+      to
+    }),
+  uses: (from: OmTopologyNodeInput, to: OmTopologyNodeInput, options: TopologyRelationshipOptions = {}) =>
+    defineTopologyRelationship({
+      ...options,
+      from,
+      kind: 'uses',
+      to
+    }),
+  approval: (from: OmTopologyNodeInput, to: OmTopologyNodeInput, options: TopologyRelationshipOptions = {}) =>
+    defineTopologyRelationship({
+      ...options,
+      from,
+      kind: 'approval',
+      to
+    }),
+  usesIntegration: (
+    from: OmTopologyNodeInput,
+    integration: OmTopologyNodeInput,
+    options: TopologyRelationshipOptions = {}
+  ) =>
+    defineTopologyRelationship({
+      required: true,
+      ...options,
+      from,
+      kind: 'uses',
+      to: integration
+    }),
+  requestsApproval: (
+    from: OmTopologyNodeInput,
+    checkpoint: TopologyRefFactoryInput,
+    options: TopologyRelationshipOptions = {}
+  ) =>
+    defineTopologyRelationship({
+      required: true,
+      ...options,
+      from,
+      kind: 'approval',
+      to: topologyRef.humanCheckpoint(checkpoint)
+    }),
+  checkpointRoutesTo: (
+    checkpoint: TopologyRefFactoryInput,
+    to: OmTopologyNodeInput,
+    options: TopologyRelationshipOptions = {}
+  ) =>
+    defineTopologyRelationship({
+      required: true,
+      ...options,
+      from: topologyRef.humanCheckpoint(checkpoint),
+      kind: 'triggers',
+      to
+    })
+} as const
+
+export function compileTopologyNodeRef(input: OmTopologyNodeInput): OmTopologyNodeRef {
+  if (isNodeRef(input)) return input
+  if (isResourceEntry(input)) return topologyRef.resource(input)
+
+  throw new Error('Topology node refs must be typed node objects or serializable { kind, id } refs')
+}
+
+export function parseTopologyNodeRef(input: string | OmTopologyNodeRef): OmTopologyNodeRef {
+  if (typeof input !== 'string') return OmTopologyNodeRefSchema.parse(input)
+
+  const separatorIndex = input.indexOf(':')
+  if (separatorIndex === -1) {
+    throw new Error(`Topology node ref "${input}" must use <kind>:<id>`)
+  }
+
+  const kind = input.slice(0, separatorIndex)
+  const id = input.slice(separatorIndex + 1)
+  if (!OmTopologyNodeKindSchema.safeParse(kind).success) {
+    throw new Error(`Topology node ref "${input}" has unsupported kind "${kind}"`)
+  }
+
+  return OmTopologyNodeRefSchema.parse({ kind, id })
+}
+
+export function defineTopologyRelationship(input: TopologyRelationshipInput): OmTopologyRelationship {
+  return OmTopologyRelationshipSchema.parse({
+    ...input,
+    from: compileTopologyNodeRef(input.from),
+    to: compileTopologyNodeRef(input.to)
+  })
+}
+
+export function defineTopology(
+  relationships: Record<string, TopologyRelationshipInput> | TopologyRelationshipInput[]
+): OmTopologyDomain {
+  const entries = Array.isArray(relationships)
+    ? relationships.map((relationship, index) => [`relationship-${index + 1}`, relationship] as const)
+    : Object.entries(relationships)
+
+  return OmTopologyDomainSchema.parse({
+    version: 1,
+    relationships: Object.fromEntries(entries.map(([key, relationship]) => [key, defineTopologyRelationship(relationship)]))
+  })
+}
+
+export function isOntologyTopologyRef(value: unknown): value is Extract<OmTopologyNodeRef, { kind: 'ontology' }> {
+  if (!isNodeRef(value) || value.kind !== 'ontology') return false
+  try {
+    parseOntologyId(value.id)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/organization-model/graph/build.ts

@@ -8,10 +8,11 @@ import type {
   OrganizationGraphNode,
   OrganizationGraphNodeKind
 } from './types'
-import type { ActionInvocation } from '../domains/actions'
-import type { Entity } from '../domains/entities'
-import type { ResourceEntry } from '../domains/resources'
-import type { EventDescriptor, OrganizationModelSidebarNode } from '../types'
+import type { ActionInvocation } from '../domains/actions'
+import type { Entity } from '../domains/entities'
+import type { ResourceEntry } from '../domains/resources'
+import type { OmTopologyNodeRef } from '../domains/topology'
+import type { EventDescriptor, OrganizationModelSidebarNode } from '../types'
 import {
   getAllPipelines,
   getAllBuildTemplates,
@@ -286,8 +287,40 @@ export function buildOrganizationGraph(input: BuildOrganizationGraphInput): Orga
     systemPathByRef.set(path, path)
     systemPathByRef.set(system.id, path)
   }
-  const validSystemRefs = new Set(systemPathByRef.keys())
-  const systemNodeId = (systemRef: string) => nodeId('system', systemPathByRef.get(systemRef) ?? systemRef)
+  const validSystemRefs = new Set(systemPathByRef.keys())
+  const systemNodeId = (systemRef: string) => nodeId('system', systemPathByRef.get(systemRef) ?? systemRef)
+
+  function topologyNodeId(ref: OmTopologyNodeRef): string {
+    if (ref.kind === 'system') return systemNodeId(ref.id)
+    if (ref.kind === 'resource') return nodeId('resource', ref.id)
+    if (ref.kind === 'ontology') return ontologyGraphNodeId(ref.id)
+    if (ref.kind === 'policy') return nodeId('policy', ref.id)
+    if (ref.kind === 'role') return nodeId('role', ref.id)
+    return nodeId('resource', ref.id)
+  }
+
+  function ensureTopologyNode(ref: OmTopologyNodeRef): string {
+    const id = topologyNodeId(ref)
+    if (nodeIds.has(id)) return id
+
+    if (ref.kind === 'resource') {
+      ensureResourceNode(nodes, nodeIds, resourceNodesById, ref.id)
+      return id
+    }
+
+    if (ref.kind === 'trigger' || ref.kind === 'humanCheckpoint' || ref.kind === 'externalResource') {
+      pushUniqueNode(nodes, nodeIds, {
+        id,
+        kind: 'resource',
+        label: ref.id,
+        sourceId: ref.id,
+        resourceType:
+          ref.kind === 'trigger' ? 'trigger' : ref.kind === 'humanCheckpoint' ? 'human_checkpoint' : 'external'
+      })
+    }
+
+    return id
+  }
 
   for (const { path, system } of systemsWithPaths.sort((a, b) => a.path.localeCompare(b.path))) {
     const id = nodeId('system', path)
@@ -649,7 +682,7 @@ export function buildOrganizationGraph(input: BuildOrganizationGraphInput): Orga
       })
     }
 
-    pushOntologyBindingEdges(edges, edgeIds, resourceNode.id, 'implements', resource.ontology?.implements)
+    pushOntologyBindingEdges(edges, edgeIds, resourceNode.id, 'actions', resource.ontology?.actions)
     pushOntologyBindingEdges(edges, edgeIds, resourceNode.id, 'reads', resource.ontology?.reads)
     pushOntologyBindingEdges(edges, edgeIds, resourceNode.id, 'writes', resource.ontology?.writes)
     pushOntologyBindingEdges(edges, edgeIds, resourceNode.id, 'uses_catalog', resource.ontology?.usesCatalogs)
@@ -698,9 +731,9 @@ export function buildOrganizationGraph(input: BuildOrganizationGraphInput): Orga
     }
   }
 
-  for (const policy of Object.values(organizationModel.policies).sort(
-    (a, b) => a.order - b.order || a.id.localeCompare(b.id)
-  )) {
+  for (const policy of Object.values(organizationModel.policies).sort(
+    (a, b) => a.order - b.order || a.id.localeCompare(b.id)
+  )) {
     const id = nodeId('policy', policy.id)
     pushUniqueNode(nodes, nodeIds, {
       id,
@@ -787,11 +820,26 @@ export function buildOrganizationGraph(input: BuildOrganizationGraphInput): Orga
           targetId: nodeId('role', effect.roleId),
           label: effect.kind
         })
-      }
-    }
-  }
-
-  for (const segment of Object.values(organizationModel.customers).sort(
+      }
+    }
+  }
+
+  for (const [relationshipId, relationship] of Object.entries(organizationModel.topology.relationships).sort(([a], [b]) =>
+    a.localeCompare(b)
+  )) {
+    const sourceId = ensureTopologyNode(relationship.from)
+    const targetId = ensureTopologyNode(relationship.to)
+
+    pushUniqueEdge(edges, edgeIds, {
+      id: edgeId(relationship.kind, sourceId, targetId, `topology-${relationshipId}`),
+      kind: relationship.kind,
+      sourceId,
+      targetId,
+      relationshipType: relationship.kind
+    })
+  }
+
+  for (const segment of Object.values(organizationModel.customers).sort(
     (a, b) => a.order - b.order || a.id.localeCompare(b.id)
   )) {
     const id = nodeId('customer-segment', segment.id)

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

@@ -33,10 +33,11 @@ export const OrganizationGraphEdgeKindSchema = z.enum([
   'affects',
   'emits',
   'originates_from',
-  'triggers',
-  'applies_to',
+  'triggers',
+  'approval',
+  'applies_to',
   'effects',
-  'implements',
+  'actions',
   'reads',
   'writes',
   'uses_catalog'

package/src/organization-model/graph/types.ts

@@ -32,11 +32,12 @@ export type OrganizationGraphEdgeKind =
   | 'links'
   | 'affects'
   | 'emits'
-  | 'originates_from'
-  | 'triggers'
-  | 'applies_to'
+  | 'originates_from'
+  | 'triggers'
+  | 'approval'
+  | 'applies_to'
   | 'effects'
-  | 'implements'
+  | 'actions'
   | 'reads'
   | 'writes'
   | 'uses_catalog'

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,
@@ -73,9 +74,10 @@ export type {
   ActionRegistry
 } from './domains/prospecting'
 export { ProjectsDomainStateSchema } from './domains/projects'
-export * from './domains/systems'
-export * from './domains/resources'
-export {
+export * from './domains/systems'
+export * from './domains/resources'
+export * from './domains/topology'
+export {
   DEFAULT_ORGANIZATION_MODEL_NAVIGATION,
   getSortedSidebarEntries,
   NavigationGroupSchema,

package/src/organization-model/ontology.ts

@@ -496,7 +496,6 @@ function addLegacyEntityProjections(
             }
           }
         : {}),
-      legacyEntityId: entity.id,
       ...(entity.rowSchema !== undefined ? { rowSchema: entity.rowSchema } : {}),
       ...(entity.stateCatalogId !== undefined ? { stateCatalogId: entity.stateCatalogId } : {})
     }
@@ -524,8 +523,7 @@ function addLegacyEntityProjections(
         from: legacyObjectId(entity),
         to: legacyObjectId(targetEntity),
         cardinality: link.kind,
-        ...(link.via !== undefined ? { via: link.via } : {}),
-        legacyEntityId: entity.id
+        ...(link.via !== undefined ? { via: link.via } : {})
       }
 
       addRecord(index, diagnostics, sourcesById, 'linkTypes', linkType, {
@@ -606,8 +604,7 @@ function addSystemContentProjections(
         ? { appliesTo: formatOntologyId({ scope: systemPath, kind: 'object', localId: node.data['entityId'] }) }
         : {}),
       ...(Object.keys(entries).length > 0 ? { entries } : {}),
-      ...(node.data !== undefined ? { data: node.data } : {}),
-      legacyContentId: `${systemPath}:${localId}`
+      ...(node.data !== undefined ? { data: node.data } : {})
     }
 
     addRecord(index, diagnostics, sourcesById, 'catalogTypes', catalogType, {