@elevasis/core 0.24.0 → 0.24.1

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/index.ts

@@ -73,9 +73,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, {

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

@@ -135,17 +135,22 @@ Resource identity is authored in the OM Resources domain. Operations imports des
 ```ts
 import { defineResources } from '@elevasis/core/organization-model'
 
-export const resourceDescriptors = defineResources({
-  leadImport: {
-    id: 'lgn-01c-apollo-import-workflow',
-    kind: 'workflow',
-    systemPath: 'sales.lead-gen',
-    ownerRoleId: 'role-ops-lead',
-    status: 'active',
-    actionKey: 'lead-gen.company.apollo-import',
-    codeRefs: [
-      {
-        path: 'packages/elevasis-operations/src/sales/prospecting/scrape/apollo-import.ts',
+export const resourceDescriptors = defineResources({
+  leadImport: {
+    id: 'lgn-01c-apollo-import-workflow',
+    title: 'Apollo Import',
+    description: 'Imports Apollo company records into the lead generation pipeline.',
+    kind: 'workflow',
+    systemPath: 'sales.lead-gen',
+    ownerRoleId: 'role-ops-lead',
+    status: 'active',
+    ontology: {
+      actions: ['sales.lead-gen:action/company.apollo-import'],
+      primaryAction: 'sales.lead-gen:action/company.apollo-import'
+    },
+    codeRefs: [
+      {
+        path: 'packages/elevasis-operations/src/sales/prospecting/scrape/apollo-import.ts',
         role: 'entrypoint',
         symbol: 'lgnApolloImportWorkflow'
       }

package/src/organization-model/published.ts

@@ -107,10 +107,11 @@ export {
   AgentKindSchema,
   AgentResourceEntrySchema,
   CodeReferenceRoleSchema,
-  CodeReferenceSchema,
-  DEFAULT_ORGANIZATION_MODEL_RESOURCES,
-  defineResource,
-  defineResources,
+  CodeReferenceSchema,
+  DEFAULT_ORGANIZATION_MODEL_RESOURCES,
+  defineResource,
+  defineResourceOntology,
+  defineResources,
   EventDescriptorSchema,
   EventEmissionDescriptorSchema,
   EventIdSchema,
@@ -121,11 +122,27 @@ export {
   ResourceKindSchema,
   ResourceOntologyBindingSchema,
   ResourcesDomainSchema,
-  ScriptResourceEntrySchema,
-  ScriptResourceLanguageSchema,
-  ScriptResourceSourceSchema,
-  WorkflowResourceEntrySchema
-} from './domains/resources'
+  ScriptResourceEntrySchema,
+  ScriptResourceLanguageSchema,
+  ScriptResourceSourceSchema,
+  WorkflowResourceEntrySchema
+} from './domains/resources'
+export {
+  compileTopologyNodeRef,
+  DEFAULT_ORGANIZATION_MODEL_TOPOLOGY,
+  defineTopology,
+  defineTopologyRelationship,
+  isOntologyTopologyRef,
+  OmTopologyDomainSchema,
+  OmTopologyMetadataSchema,
+  OmTopologyNodeKindSchema,
+  OmTopologyNodeRefSchema,
+  OmTopologyRelationshipKindSchema,
+  OmTopologyRelationshipSchema,
+  parseTopologyNodeRef,
+  topologyRelationship,
+  topologyRef
+} from './domains/topology'
 export {
   ActionsDomainSchema,
   ActionIdSchema,
@@ -249,10 +266,16 @@ export type {
   OrganizationModelResourceKind,
   OrganizationModelResourceOntologyBinding,
   OrganizationModelResources,
-  OrganizationModelScriptResourceEntry,
-  OrganizationModelScriptResourceLanguage,
-  OrganizationModelScriptResourceSource,
-  OrganizationModelWorkflowResourceEntry,
+  OrganizationModelScriptResourceEntry,
+  OrganizationModelScriptResourceLanguage,
+  OrganizationModelScriptResourceSource,
+  OrganizationModelTopology,
+  OrganizationModelTopologyMetadata,
+  OrganizationModelTopologyNodeKind,
+  OrganizationModelTopologyNodeRef,
+  OrganizationModelTopologyRelationship,
+  OrganizationModelTopologyRelationshipKind,
+  OrganizationModelWorkflowResourceEntry,
   OrganizationModelActions,
   OrganizationModelAction,
   OrganizationModelActionId,

package/src/organization-model/schema.ts

@@ -8,8 +8,9 @@ import { OfferingsDomainSchema, DEFAULT_ORGANIZATION_MODEL_OFFERINGS } from './d
 import { RolesDomainSchema, DEFAULT_ORGANIZATION_MODEL_ROLES } from './domains/roles'
 import { GoalsDomainSchema, DEFAULT_ORGANIZATION_MODEL_GOALS } from './domains/goals'
 import { KnowledgeDomainSchema } from './domains/knowledge'
-import { SystemsDomainSchema, DEFAULT_ORGANIZATION_MODEL_SYSTEMS, type SystemEntry } from './domains/systems'
-import { ResourcesDomainSchema, DEFAULT_ORGANIZATION_MODEL_RESOURCES } from './domains/resources'
+import { SystemsDomainSchema, DEFAULT_ORGANIZATION_MODEL_SYSTEMS, type SystemEntry } from './domains/systems'
+import { ResourcesDomainSchema, DEFAULT_ORGANIZATION_MODEL_RESOURCES } from './domains/resources'
+import { OmTopologyDomainSchema, DEFAULT_ORGANIZATION_MODEL_TOPOLOGY, type OmTopologyNodeRef } from './domains/topology'
 import { ActionsDomainSchema, DEFAULT_ORGANIZATION_MODEL_ACTIONS } from './domains/actions'
 import { EntitiesDomainSchema, DEFAULT_ORGANIZATION_MODEL_ENTITIES } from './domains/entities'
 import { PoliciesDomainSchema, DEFAULT_ORGANIZATION_MODEL_POLICIES } from './domains/policies'
@@ -33,7 +34,8 @@ export const OrganizationModelDomainKeySchema = z.enum([
   'systems',
   'ontology',
   'resources',
-  'actions',
+  'topology',
+  'actions',
   'entities',
   'policies',
   'knowledge'
@@ -57,7 +59,8 @@ export const DEFAULT_ORGANIZATION_MODEL_DOMAIN_METADATA: Record<
   systems: { version: 1, lastModified: '2026-05-10' },
   ontology: { version: 1, lastModified: '2026-05-14' },
   resources: { version: 1, lastModified: '2026-05-10' },
-  actions: { version: 1, lastModified: '2026-05-10' },
+  topology: { version: 1, lastModified: '2026-05-14' },
+  actions: { version: 1, lastModified: '2026-05-10' },
   entities: { version: 1, lastModified: '2026-05-10' },
   policies: { version: 1, lastModified: '2026-05-10' },
   knowledge: { version: 1, lastModified: '2026-05-10' }
@@ -74,7 +77,8 @@ export const OrganizationModelDomainMetadataByDomainSchema = z
     systems: OrganizationModelDomainMetadataSchema,
     ontology: OrganizationModelDomainMetadataSchema,
     resources: OrganizationModelDomainMetadataSchema,
-    actions: OrganizationModelDomainMetadataSchema,
+    topology: OrganizationModelDomainMetadataSchema,
+    actions: OrganizationModelDomainMetadataSchema,
     entities: OrganizationModelDomainMetadataSchema,
     policies: OrganizationModelDomainMetadataSchema,
     knowledge: OrganizationModelDomainMetadataSchema
@@ -104,7 +108,8 @@ const OrganizationModelSchemaBase = z.object({
   systems: SystemsDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_SYSTEMS),
   ontology: OntologyScopeSchema.default(DEFAULT_ONTOLOGY_SCOPE),
   resources: ResourcesDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_RESOURCES),
-  actions: ActionsDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_ACTIONS),
+  topology: OmTopologyDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_TOPOLOGY),
+  actions: ActionsDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_ACTIONS),
   entities: EntitiesDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_ENTITIES),
   policies: PoliciesDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_POLICIES),
   // D3: flat Record<id, OrgKnowledgeNode> — no wrapper object
@@ -526,6 +531,32 @@ export const OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((
   } satisfies Record<OntologyKind, Record<string, unknown>>
   const ontologyIds = new Set(Object.values(ontologyIndexByKind).flatMap((index) => Object.keys(index)))
 
+  function topologyTargetExists(ref: OmTopologyNodeRef): boolean {
+    if (ref.kind === 'system') return systemsById.has(ref.id)
+    if (ref.kind === 'resource') return resourcesById.has(ref.id)
+    if (ref.kind === 'ontology') return ontologyIds.has(ref.id)
+    if (ref.kind === 'policy') return policiesById.has(ref.id)
+    if (ref.kind === 'role') return rolesById.has(ref.id)
+
+    // Trigger, human checkpoint, and external resource refs are projected
+    // topology nodes during the bridge period; their owning runtime indexes are
+    // validated by deployment projection in later waves.
+    return true
+  }
+
+  Object.entries(model.topology.relationships).forEach(([relationshipId, relationship]) => {
+    ;(['from', 'to'] as const).forEach((side) => {
+      const ref = relationship[side]
+      if (topologyTargetExists(ref)) return
+
+      addIssue(
+        ctx,
+        ['topology', 'relationships', relationshipId, side],
+        `Topology relationship "${relationshipId}" ${side} references unknown ${ref.kind} "${ref.id}"`
+      )
+    })
+  })
+
   const ontologyReferenceKeyKinds = {
     valueType: 'value-type',
     catalogType: 'catalog',
@@ -694,15 +725,23 @@ export const OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((
 
   function validateResourceOntologyBinding(
     resourceId: string,
-    bindingKey: 'implements' | 'reads' | 'writes' | 'usesCatalogs' | 'emits',
+    bindingKey: 'actions' | 'primaryAction' | 'reads' | 'writes' | 'usesCatalogs' | 'emits',
     expectedKind: OntologyKind,
-    ids: string[] | undefined
+    ids: string[] | string | undefined
   ): void {
-    ids?.forEach((ontologyId, ontologyIndex) => {
+    const ontologyIds = ids === undefined ? [] : Array.isArray(ids) ? ids : [ids]
+
+    ontologyIds.forEach((ontologyId, ontologyIndex) => {
       if (ontologyIndexByKind[expectedKind][ontologyId] === undefined) {
         addIssue(
           ctx,
-          ['resources', resourceId, 'ontology', bindingKey, ontologyIndex],
+          [
+            'resources',
+            resourceId,
+            'ontology',
+            bindingKey,
+            ...(Array.isArray(ids) ? [ontologyIndex] : [])
+          ],
           `Resource "${resourceId}" ontology binding "${bindingKey}" references unknown ${expectedKind} ontology ID "${ontologyId}"`
         )
       }
@@ -713,7 +752,8 @@ export const OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((
     const binding = resource.ontology
     if (binding === undefined) return
 
-    validateResourceOntologyBinding(resource.id, 'implements', 'action', binding.implements)
+    validateResourceOntologyBinding(resource.id, 'actions', 'action', binding.actions)
+    validateResourceOntologyBinding(resource.id, 'primaryAction', 'action', binding.primaryAction)
     validateResourceOntologyBinding(resource.id, 'reads', 'object', binding.reads)
     validateResourceOntologyBinding(resource.id, 'writes', 'object', binding.writes)
     validateResourceOntologyBinding(resource.id, 'usesCatalogs', 'catalog', binding.usesCatalogs)