@elevasis/core 0.21.0 → 0.23.0

package/src/organization-model/schema.ts

@@ -1,35 +1,103 @@
 import { z } from 'zod'
+import { lookupContentType } from './content-kinds/index'
 import { OrganizationModelBrandingSchema } from './domains/branding'
-import { OrganizationModelSalesSchema } from './domains/sales'
-import { OrganizationModelProjectsSchema } from './domains/projects'
-import { FeatureSchema } from './domains/features'
-import { OrganizationModelProspectingSchema } from './domains/prospecting'
-import { OrganizationModelNavigationSchema } from './domains/navigation'
+import { OrganizationModelNavigationSchema, type SidebarNode } from './domains/navigation'
 import { IdentityDomainSchema, DEFAULT_ORGANIZATION_MODEL_IDENTITY } from './domains/identity'
 import { CustomersDomainSchema, DEFAULT_ORGANIZATION_MODEL_CUSTOMERS } from './domains/customers'
 import { OfferingsDomainSchema, DEFAULT_ORGANIZATION_MODEL_OFFERINGS } from './domains/offerings'
 import { RolesDomainSchema, DEFAULT_ORGANIZATION_MODEL_ROLES } from './domains/roles'
 import { GoalsDomainSchema, DEFAULT_ORGANIZATION_MODEL_GOALS } from './domains/goals'
-import { OperationsDomainSchema } from './domains/operations'
-import { StatusesDomainSchema } from './domains/statuses'
 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 { 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'
 
+// Phase 4 cut: 'sales', 'prospecting', 'projects', 'statuses' removed.
+// domainMetadata.knowledge covers versioning for the knowledge flat-map (D7).
+export const OrganizationModelDomainKeySchema = z.enum([
+  'branding',
+  'identity',
+  'customers',
+  'offerings',
+  'roles',
+  'goals',
+  'systems',
+  'resources',
+  'actions',
+  'entities',
+  'policies',
+  'knowledge'
+])
+
+export const OrganizationModelDomainMetadataSchema = z.object({
+  version: z.literal(1).default(1),
+  lastModified: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'lastModified must be an ISO date string (YYYY-MM-DD)')
+})
+
+export const DEFAULT_ORGANIZATION_MODEL_DOMAIN_METADATA: Record<
+  z.infer<typeof OrganizationModelDomainKeySchema>,
+  z.infer<typeof OrganizationModelDomainMetadataSchema>
+> = {
+  branding: { version: 1, lastModified: '2026-05-10' },
+  identity: { version: 1, lastModified: '2026-05-10' },
+  customers: { version: 1, lastModified: '2026-05-10' },
+  offerings: { version: 1, lastModified: '2026-05-10' },
+  roles: { version: 1, lastModified: '2026-05-10' },
+  goals: { version: 1, lastModified: '2026-05-10' },
+  systems: { version: 1, lastModified: '2026-05-10' },
+  resources: { version: 1, lastModified: '2026-05-10' },
+  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' }
+}
+
+export const OrganizationModelDomainMetadataByDomainSchema = z
+  .object({
+    branding: OrganizationModelDomainMetadataSchema,
+    identity: OrganizationModelDomainMetadataSchema,
+    customers: OrganizationModelDomainMetadataSchema,
+    offerings: OrganizationModelDomainMetadataSchema,
+    roles: OrganizationModelDomainMetadataSchema,
+    goals: OrganizationModelDomainMetadataSchema,
+    systems: OrganizationModelDomainMetadataSchema,
+    resources: OrganizationModelDomainMetadataSchema,
+    actions: OrganizationModelDomainMetadataSchema,
+    entities: OrganizationModelDomainMetadataSchema,
+    policies: OrganizationModelDomainMetadataSchema,
+    knowledge: OrganizationModelDomainMetadataSchema
+  })
+  .partial()
+  .default(DEFAULT_ORGANIZATION_MODEL_DOMAIN_METADATA)
+  .transform((metadata) => ({ ...DEFAULT_ORGANIZATION_MODEL_DOMAIN_METADATA, ...metadata }))
+
+// Phase 4 schema cut (D8):
+//   REMOVED top-level fields: sales, prospecting, projects, statuses
+//   ADDED navigation.sidebar as the authored shell tree
+//   knowledge: now Record<id, OrgKnowledgeNode> flat map (D3); version/lastModified in domainMetadata.knowledge (D7)
+//
+// Clean migration rule:
+//   NO top-level surfaces / navigationGroups compatibility fields.
+//   Surfaces are derived from navigation.sidebar routeable leaves.
 const OrganizationModelSchemaBase = z.object({
   version: z.literal(1).default(1),
-  features: z.array(FeatureSchema).default([]),
+  domainMetadata: OrganizationModelDomainMetadataByDomainSchema,
   branding: OrganizationModelBrandingSchema,
-  navigation: OrganizationModelNavigationSchema.default({ surfaces: [], groups: [] }),
-  sales: OrganizationModelSalesSchema,
-  prospecting: OrganizationModelProspectingSchema,
-  projects: OrganizationModelProjectsSchema,
+  navigation: OrganizationModelNavigationSchema,
   identity: IdentityDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_IDENTITY),
   customers: CustomersDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_CUSTOMERS),
   offerings: OfferingsDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_OFFERINGS),
   roles: RolesDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_ROLES),
   goals: GoalsDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_GOALS),
-  statuses: StatusesDomainSchema.default({ entries: [] }),
-  operations: OperationsDomainSchema.default({ entries: [] }),
-  knowledge: KnowledgeDomainSchema.default({ nodes: [] })
+  systems: SystemsDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_SYSTEMS),
+  resources: ResourcesDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_RESOURCES),
+  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
+  knowledge: KnowledgeDomainSchema.default({})
 })
 
 function addIssue(ctx: z.RefinementCtx, path: Array<string | number>, message: string): void {
@@ -40,174 +108,648 @@ function addIssue(ctx: z.RefinementCtx, path: Array<string | number>, message: s
   })
 }
 
-function collectIds<T extends { id: string }>(
-  items: T[],
-  ctx: z.RefinementCtx,
-  collectionPath: Array<string | number>,
-  label: string
-): Map<string, T> {
-  const itemsById = new Map<string, T>()
-
-  items.forEach((item, index) => {
-    if (itemsById.has(item.id)) {
-      addIssue(ctx, [...collectionPath, index, 'id'], `${label} id "${item.id}" must be unique`)
-      return
-    }
-
-    itemsById.set(item.id, item)
-  })
-
-  return itemsById
+function isLifecycleEnabled(lifecycle: string | undefined, enabled: boolean | undefined): boolean {
+  if (enabled === false) return false
+  return lifecycle !== 'deprecated' && lifecycle !== 'archived'
 }
 
-const LEGACY_FEATURE_ALIASES = new Map<string, string>([
-  ['crm', 'sales.crm'],
-  ['lead-gen', 'sales.lead-gen'],
-  ['submitted-requests', 'monitoring.submitted-requests']
-])
+function defaultSystemPathFor(id: string): string {
+  return `/${id.replaceAll('.', '/')}`
+}
 
-function hasFeature(featuresById: Map<string, unknown>, featureId: string): boolean {
-  return featuresById.has(featureId) || featuresById.has(LEGACY_FEATURE_ALIASES.get(featureId) ?? '')
+function asRoleHolderArray(
+  heldBy: NonNullable<z.infer<typeof OrganizationModelSchemaBase>['roles'][string]['heldBy']>
+) {
+  return Array.isArray(heldBy) ? heldBy : [heldBy]
 }
 
-function defaultFeaturePathFor(id: string): string {
-  return `/${id.replaceAll('.', '/')}`
+function isKnowledgeKindCompatibleWithTarget(knowledgeKind: string, targetKind: string): boolean {
+  if (knowledgeKind === 'reference') return true
+  if (knowledgeKind === 'playbook') {
+    return ['system', 'resource', 'stage', 'action'].includes(targetKind)
+  }
+  if (knowledgeKind === 'strategy') {
+    return ['system', 'goal', 'offering', 'customer-segment'].includes(targetKind)
+  }
+  return false
 }
 
 export const OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((model, ctx) => {
-  const featuresById = collectIds(model.features, ctx, ['features'], 'Feature')
-  const featureIdsByEffectivePath = new Map<string, string>()
+  // Collect ALL system entries recursively — top-level systems plus any nested subsystems.
+  // Wave 2 canonical OM authors nested subsystems (e.g. sys → subsystems → 'lead-gen' with id
+  // 'sys.lead-gen'). Resource systemPath cross-refs must resolve against the full flattened set.
+  type SystemWithPath = { path: string; schemaPath: Array<string | number>; system: SystemEntry }
 
-  model.features.forEach((feature, featureIndex) => {
-    const segments = feature.id.split('.')
-    if (segments.length > 1) {
-      const parentId = segments.slice(0, -1).join('.')
-      if (!featuresById.has(parentId)) {
-        addIssue(
-          ctx,
-          ['features', featureIndex, 'id'],
-          `Feature "${feature.id}" references unknown parent "${parentId}"`
-        )
+  function collectAllSystems(
+    systems: Record<string, SystemEntry>,
+    prefix = '',
+    schemaPath: Array<string | number> = ['systems']
+  ): SystemWithPath[] {
+    const result: SystemWithPath[] = []
+    for (const [key, system] of Object.entries(systems)) {
+      const path = prefix ? `${prefix}.${key}` : key
+      const currentSchemaPath = [...schemaPath, key]
+      result.push({ path, schemaPath: currentSchemaPath, system })
+      if (system.subsystems !== undefined) {
+        result.push(...collectAllSystems(system.subsystems, path, [...currentSchemaPath, 'subsystems']))
       }
     }
+    return result
+  }
+
+  const allSystems = collectAllSystems(model.systems)
+  const systemsById = new Map<string, SystemEntry>()
+  for (const { path, system } of allSystems) {
+    systemsById.set(path, system)
+    systemsById.set(system.id, system)
+  }
+
+  const systemIdsByEffectivePath = new Map<string, string>()
+  allSystems.forEach(({ path, schemaPath, system }) => {
+    if (system.parentSystemId !== undefined && !systemsById.has(system.parentSystemId)) {
+      addIssue(
+        ctx,
+        [...schemaPath, 'parentSystemId'],
+        `System "${system.id}" references unknown parent "${system.parentSystemId}"`
+      )
+    }
 
-    const hasChildren = model.features.some(
-      (candidate) => candidate.id.startsWith(`${feature.id}.`) && candidate.id !== feature.id
-    )
-    const contributesRoutePath = feature.path !== undefined || !hasChildren
+    const hasChildren =
+      Object.keys(system.subsystems ?? {}).length > 0 ||
+      allSystems.some((candidate) => candidate.path.startsWith(`${path}.`) && !candidate.path.slice(path.length + 1).includes('.'))
+    const contributesRoutePath = system.ui?.path !== undefined || system.path !== undefined || !hasChildren
     if (contributesRoutePath) {
-      const effectivePath = feature.path ?? defaultFeaturePathFor(feature.id)
-      const existingFeatureId = featureIdsByEffectivePath.get(effectivePath)
-      if (existingFeatureId !== undefined) {
+      const effectivePath = system.ui?.path ?? system.path ?? defaultSystemPathFor(path)
+      const existingSystemId = systemIdsByEffectivePath.get(effectivePath)
+      if (existingSystemId !== undefined) {
         addIssue(
           ctx,
-          ['features', featureIndex, feature.path === undefined ? 'id' : 'path'],
-          `Feature "${feature.id}" effective path "${effectivePath}" duplicates feature "${existingFeatureId}"`
+          [...schemaPath, system.ui?.path !== undefined ? 'ui' : 'path'],
+          `System "${path}" effective path "${effectivePath}" duplicates system "${existingSystemId}"`
         )
       } else {
-        featureIdsByEffectivePath.set(effectivePath, feature.id)
+        systemIdsByEffectivePath.set(effectivePath, path)
       }
     }
 
-    if (hasChildren && feature.enabled) {
-      const hasEnabledDescendant = model.features.some(
-        (candidate) => candidate.id.startsWith(`${feature.id}.`) && candidate.enabled
-      )
+    if (hasChildren && isLifecycleEnabled(system.lifecycle, system.enabled)) {
+      const hasEnabledDescendant =
+        Object.values(system.subsystems ?? {}).some((candidate) =>
+          isLifecycleEnabled(candidate.lifecycle, candidate.enabled)
+        ) ||
+        allSystems.some(
+          (candidate) =>
+            candidate.path.startsWith(`${path}.`) &&
+            !candidate.path.slice(path.length + 1).includes('.') &&
+            isLifecycleEnabled(candidate.system.lifecycle, candidate.system.enabled)
+        )
       if (!hasEnabledDescendant) {
         addIssue(
           ctx,
-          ['features', featureIndex, 'enabled'],
-          `Feature "${feature.id}" is enabled but has no enabled descendants`
+          [...schemaPath, 'lifecycle'],
+          `System "${path}" is active but has no active descendants`
         )
       }
     }
   })
 
-  const surfacesById = collectIds(model.navigation.surfaces, ctx, ['navigation', 'surfaces'], 'Navigation surface')
+  allSystems.forEach(({ schemaPath, system }) => {
+    const visited = new Set<string>()
+    let currentParentId = system.parentSystemId
+
+    while (currentParentId !== undefined) {
+      if (currentParentId === system.id || visited.has(currentParentId)) {
+        addIssue(ctx, [...schemaPath, 'parentSystemId'], `System "${system.id}" has a parent cycle`)
+        return
+      }
+
+      visited.add(currentParentId)
+      currentParentId = systemsById.get(currentParentId)?.parentSystemId
+    }
+  })
 
-  if (model.navigation.defaultSurfaceId !== undefined && !surfacesById.has(model.navigation.defaultSurfaceId)) {
-    addIssue(
-      ctx,
-      ['navigation', 'defaultSurfaceId'],
-      `Navigation defaultSurfaceId references unknown surface "${model.navigation.defaultSurfaceId}"`
-    )
+  type CollectedSidebarSurface = {
+    id: string
+    node: Extract<SidebarNode, { type: 'surface' }>
+    path: Array<string | number>
   }
 
-  model.navigation.groups.forEach((group, groupIndex) => {
-    group.surfaceIds.forEach((surfaceId, surfaceIndex) => {
-      if (!surfacesById.has(surfaceId)) {
-        addIssue(
-          ctx,
-          ['navigation', 'groups', groupIndex, 'surfaceIds', surfaceIndex],
-          `Navigation group "${group.id}" references unknown surface "${surfaceId}"`
-        )
+  function normalizeRoutePath(path: string): string {
+    return path.length > 1 ? path.replace(/\/+$/, '') : path
+  }
+
+  const sidebarNodeIds = new Map<string, Array<string | number>>()
+  const sidebarSurfacePaths = new Map<string, string>()
+  const sidebarSurfaces: CollectedSidebarSurface[] = []
+
+  function collectSidebarNodes(
+    nodes: Record<string, SidebarNode>,
+    schemaPath: Array<string | number>
+  ): void {
+    Object.entries(nodes).forEach(([nodeId, node]) => {
+      const nodePath = [...schemaPath, nodeId]
+      const existingNodePath = sidebarNodeIds.get(nodeId)
+      if (existingNodePath !== undefined) {
+        addIssue(ctx, nodePath, `Sidebar node id "${nodeId}" duplicates another sidebar node`)
+      } else {
+        sidebarNodeIds.set(nodeId, nodePath)
       }
-    })
-  })
 
-  model.navigation.surfaces.forEach((surface, surfaceIndex) => {
-    if (surface.featureId !== undefined && !hasFeature(featuresById, surface.featureId)) {
-      addIssue(
-        ctx,
-        ['navigation', 'surfaces', surfaceIndex, 'featureId'],
-        `Navigation surface "${surface.id}" references unknown feature "${surface.featureId}"`
-      )
-    }
+      if (node.type === 'group') {
+        collectSidebarNodes(node.children, [...nodePath, 'children'])
+        return
+      }
 
-    surface.featureIds.forEach((featureId, featureIndex) => {
-      if (!hasFeature(featuresById, featureId)) {
+      sidebarSurfaces.push({ id: nodeId, node, path: nodePath })
+      const normalizedPath = normalizeRoutePath(node.path)
+      const existingSurfaceId = sidebarSurfacePaths.get(normalizedPath)
+      if (existingSurfaceId !== undefined) {
         addIssue(
           ctx,
-          ['navigation', 'surfaces', surfaceIndex, 'featureIds', featureIndex],
-          `Navigation surface "${surface.id}" references unknown feature "${featureId}"`
+          [...nodePath, 'path'],
+          `Sidebar surface path "${node.path}" duplicates surface "${existingSurfaceId}"`
         )
+      } else {
+        sidebarSurfacePaths.set(normalizedPath, nodeId)
       }
+
+      node.targets?.systems?.forEach((systemId, systemIndex) => {
+        if (!systemsById.has(systemId)) {
+          addIssue(
+            ctx,
+            [...nodePath, 'targets', 'systems', systemIndex],
+            `Sidebar surface "${nodeId}" references unknown system "${systemId}"`
+          )
+        }
+      })
     })
-  })
+  }
+
+  collectSidebarNodes(model.navigation.sidebar.primary, ['navigation', 'sidebar', 'primary'])
+  collectSidebarNodes(model.navigation.sidebar.bottom, ['navigation', 'sidebar', 'bottom'])
 
   // Offerings -> CustomerSegment cross-ref: targetSegmentIds must resolve
-  const segmentsById = new Map(model.customers.segments.map((seg) => [seg.id, seg]))
-  model.offerings.products.forEach((product, productIndex) => {
+  const segmentsById = new Map(Object.entries(model.customers))
+  Object.values(model.offerings).forEach((product) => {
     product.targetSegmentIds.forEach((segmentId, segmentIndex) => {
       if (!segmentsById.has(segmentId)) {
         addIssue(
           ctx,
-          ['offerings', 'products', productIndex, 'targetSegmentIds', segmentIndex],
+          ['offerings', product.id, 'targetSegmentIds', segmentIndex],
           `Product "${product.id}" references unknown customer segment "${segmentId}"`
         )
       }
     })
 
-    // Offerings -> Feature cross-ref: deliveryFeatureId must resolve (when present)
-    if (product.deliveryFeatureId !== undefined && !hasFeature(featuresById, product.deliveryFeatureId)) {
+    // Offerings -> System cross-ref: deliveryFeatureId must resolve (when present)
+    if (product.deliveryFeatureId !== undefined && !systemsById.has(product.deliveryFeatureId)) {
       addIssue(
         ctx,
-        ['offerings', 'products', productIndex, 'deliveryFeatureId'],
-        `Product "${product.id}" references unknown delivery feature "${product.deliveryFeatureId}"`
+        ['offerings', product.id, 'deliveryFeatureId'],
+        `Product "${product.id}" references unknown delivery system "${product.deliveryFeatureId}"`
       )
     }
   })
 
   // Goals -> period-range validation: periodEnd must be strictly after periodStart
-  model.goals.objectives.forEach((objective, index) => {
+  Object.values(model.goals).forEach((objective) => {
     if (objective.periodEnd <= objective.periodStart) {
       addIssue(
         ctx,
-        ['goals', 'objectives', index, 'periodEnd'],
+        ['goals', objective.id, 'periodEnd'],
         `Goal "${objective.id}" has periodEnd "${objective.periodEnd}" which must be strictly after periodStart "${objective.periodStart}"`
       )
     }
   })
 
+  const goalsById = new Map(Object.entries(model.goals))
+  // Phase 4: knowledge is now a flat Record<id, OrgKnowledgeNode> — no .nodes array
+  const knowledgeById = new Map(Object.entries(model.knowledge))
+  const actionsById = new Map(Object.entries(model.actions))
+  const entitiesById = new Map(Object.entries(model.entities))
+  const policiesById = new Map(Object.entries(model.policies))
+
+  sidebarSurfaces.forEach(({ id, node, path }) => {
+    node.targets?.entities?.forEach((entityId, entityIndex) => {
+      if (!entitiesById.has(entityId)) {
+        addIssue(
+          ctx,
+          [...path, 'targets', 'entities', entityIndex],
+          `Sidebar surface "${id}" references unknown entity "${entityId}"`
+        )
+      }
+    })
+
+    node.targets?.actions?.forEach((actionId, actionIndex) => {
+      if (!actionsById.has(actionId)) {
+        addIssue(
+          ctx,
+          [...path, 'targets', 'actions', actionIndex],
+          `Sidebar surface "${id}" references unknown action "${actionId}"`
+        )
+      }
+    })
+  })
+
+  Object.values(model.entities).forEach((entity) => {
+    if (!systemsById.has(entity.ownedBySystemId)) {
+      addIssue(
+        ctx,
+        ['entities', entity.id, 'ownedBySystemId'],
+        `Entity "${entity.id}" references unknown ownedBySystemId "${entity.ownedBySystemId}"`
+      )
+    }
+
+    entity.links?.forEach((link, linkIndex) => {
+      if (!entitiesById.has(link.toEntity)) {
+        addIssue(
+          ctx,
+          ['entities', entity.id, 'links', linkIndex, 'toEntity'],
+          `Entity "${entity.id}" links to unknown entity "${link.toEntity}"`
+        )
+      }
+    })
+  })
+
   // Roles -> reportsToId cross-ref: each reportsToId must resolve to another role in the same collection
-  const rolesById = new Map(model.roles.roles.map((role) => [role.id, role]))
-  model.roles.roles.forEach((role, roleIndex) => {
+  const rolesById = new Map(Object.entries(model.roles))
+  Object.values(model.roles).forEach((role) => {
     if (role.reportsToId !== undefined && !rolesById.has(role.reportsToId)) {
       addIssue(
         ctx,
-        ['roles', 'roles', roleIndex, 'reportsToId'],
+        ['roles', role.id, 'reportsToId'],
         `Role "${role.id}" references unknown reportsToId "${role.reportsToId}"`
       )
     }
   })
+
+  Object.values(model.roles).forEach((role) => {
+    const visited = new Set<string>()
+    let currentReportsToId = role.reportsToId
+
+    while (currentReportsToId !== undefined) {
+      if (currentReportsToId === role.id || visited.has(currentReportsToId)) {
+        addIssue(ctx, ['roles', role.id, 'reportsToId'], `Role "${role.id}" has a reportsToId cycle`)
+        return
+      }
+
+      visited.add(currentReportsToId)
+      currentReportsToId = rolesById.get(currentReportsToId)?.reportsToId
+    }
+  })
+
+  Object.values(model.roles).forEach((role) => {
+    role.responsibleFor?.forEach((systemId, systemIndex) => {
+      if (!systemsById.has(systemId)) {
+        addIssue(
+          ctx,
+          ['roles', role.id, 'responsibleFor', systemIndex],
+          `Role "${role.id}" references unknown responsibleFor system "${systemId}"`
+        )
+      }
+    })
+  })
+
+  allSystems.forEach(({ schemaPath, system }) => {
+    if (system.responsibleRoleId !== undefined && !rolesById.has(system.responsibleRoleId)) {
+      addIssue(
+        ctx,
+        [...schemaPath, 'responsibleRoleId'],
+        `System "${system.id}" references unknown responsibleRoleId "${system.responsibleRoleId}"`
+      )
+    }
+
+    system.governedByKnowledge?.forEach((nodeId, nodeIndex) => {
+      if (!knowledgeById.has(nodeId)) {
+        addIssue(
+          ctx,
+          [...schemaPath, 'governedByKnowledge', nodeIndex],
+          `System "${system.id}" references unknown knowledge node "${nodeId}"`
+        )
+      }
+    })
+
+    system.drivesGoals?.forEach((goalId, goalIndex) => {
+      if (!goalsById.has(goalId)) {
+        addIssue(
+          ctx,
+          [...schemaPath, 'drivesGoals', goalIndex],
+          `System "${system.id}" references unknown goal "${goalId}"`
+        )
+      }
+    })
+
+    system.actions?.forEach((actionRef, actionIndex) => {
+      if (!actionsById.has(actionRef.actionId)) {
+        addIssue(
+          ctx,
+          [...schemaPath, 'actions', actionIndex, 'actionId'],
+          `System "${system.id}" references unknown action "${actionRef.actionId}"`
+        )
+      }
+    })
+
+    system.policies?.forEach((policyId, policyIndex) => {
+      if (!policiesById.has(policyId)) {
+        addIssue(
+          ctx,
+          [...schemaPath, 'policies', policyIndex],
+          `System "${system.id}" references unknown policy "${policyId}"`
+        )
+      }
+    })
+  })
+
+  Object.values(model.actions).forEach((action) => {
+    action.affects?.forEach((entityId, entityIndex) => {
+      if (!entitiesById.has(entityId)) {
+        addIssue(
+          ctx,
+          ['actions', action.id, 'affects', entityIndex],
+          `Action "${action.id}" affects unknown entity "${entityId}"`
+        )
+      }
+    })
+  })
+
+  // Phase 4: sales / prospecting / projects compound-domain entity cross-ref checks removed.
+  // Those entity bindings now live in system.content (Wave 2 canonicalOrganizationModel).
+
+  const resourcesById = new Map(Object.entries(model.resources))
+  sidebarSurfaces.forEach(({ id, node, path }) => {
+    node.targets?.resources?.forEach((resourceId, resourceIndex) => {
+      if (!resourcesById.has(resourceId)) {
+        addIssue(
+          ctx,
+          [...path, 'targets', 'resources', resourceIndex],
+          `Sidebar surface "${id}" references unknown resource "${resourceId}"`
+        )
+      }
+    })
+  })
+  // Phase 4: stageIds previously sourced from model.prospecting.*Stages; stages now live in
+  // system.content as schema:stage nodes. knowledge 'stage' target validation is kept permissive
+  // (always false) — Wave 2 will wire a content-based stage lookup when canonical OM lands.
+  const stageIds = new Set<string>()
+  const actionIds = new Set(Object.keys(model.actions))
+  const offeringsById = new Map(Object.entries(model.offerings))
+
+  Object.values(model.policies).forEach((policy) => {
+    policy.appliesTo.systemIds.forEach((systemId, systemIndex) => {
+      if (!systemsById.has(systemId)) {
+        addIssue(
+          ctx,
+          ['policies', policy.id, 'appliesTo', 'systemIds', systemIndex],
+          `Policy "${policy.id}" applies to unknown system "${systemId}"`
+        )
+      }
+    })
+
+    policy.appliesTo.actionIds.forEach((actionId, actionIndex) => {
+      if (!actionsById.has(actionId)) {
+        addIssue(
+          ctx,
+          ['policies', policy.id, 'appliesTo', 'actionIds', actionIndex],
+          `Policy "${policy.id}" applies to unknown action "${actionId}"`
+        )
+      }
+    })
+
+    policy.actions.forEach((action, actionIndex) => {
+      if (action.kind === 'invoke-action' && !actionsById.has(action.actionId)) {
+        addIssue(
+          ctx,
+          ['policies', policy.id, 'actions', actionIndex, 'actionId'],
+          `Policy "${policy.id}" invokes unknown action "${action.actionId}"`
+        )
+      }
+      if (
+        (action.kind === 'notify-role' || action.kind === 'require-approval') &&
+        action.roleId !== undefined &&
+        !rolesById.has(action.roleId)
+      ) {
+        addIssue(
+          ctx,
+          ['policies', policy.id, 'actions', actionIndex, 'roleId'],
+          `Policy "${policy.id}" references unknown role "${action.roleId}"`
+        )
+      }
+    })
+
+    if (policy.trigger.kind === 'action-invocation' && !actionsById.has(policy.trigger.actionId)) {
+      addIssue(
+        ctx,
+        ['policies', policy.id, 'trigger', 'actionId'],
+        `Policy "${policy.id}" references unknown trigger action "${policy.trigger.actionId}"`
+      )
+    }
+  })
+
+  function knowledgeTargetExists(kind: string, id: string): boolean {
+    if (kind === 'system') return systemsById.has(id)
+    if (kind === 'resource') return resourcesById.has(id)
+    if (kind === 'knowledge') return knowledgeById.has(id)
+    if (kind === 'stage') return stageIds.has(id)
+    if (kind === 'action') return actionIds.has(id)
+    if (kind === 'role') return rolesById.has(id)
+    if (kind === 'goal') return goalsById.has(id)
+    if (kind === 'customer-segment') return segmentsById.has(id)
+    if (kind === 'offering') return offeringsById.has(id)
+    return false
+  }
+
+  // Phase 4: model.knowledge is now Record<id, OrgKnowledgeNode> — iterate Object.values
+  Object.entries(model.knowledge).forEach(([nodeId, node]) => {
+    node.links.forEach((link, linkIndex) => {
+      if (!knowledgeTargetExists(link.target.kind, link.target.id)) {
+        addIssue(
+          ctx,
+          ['knowledge', nodeId, 'links', linkIndex, 'target'],
+          `Knowledge node "${node.id}" references unknown ${link.target.kind} target "${link.target.id}"`
+        )
+      }
+
+      if (!isKnowledgeKindCompatibleWithTarget(node.kind, link.target.kind)) {
+        addIssue(
+          ctx,
+          ['knowledge', nodeId, 'links', linkIndex, 'target', 'kind'],
+          `Knowledge node "${node.id}" kind "${node.kind}" cannot govern ${link.target.kind} targets`
+        )
+      }
+
+      // `governedByKnowledge` is validated one-way on target nodes above. Knowledge
+      // links may be authored first and remain valid as forward references.
+    })
+  })
+
+  Object.values(model.resources).forEach((resource) => {
+    if (!systemsById.has(resource.systemPath)) {
+      addIssue(
+        ctx,
+        ['resources', resource.id, 'systemPath'],
+        `Resource "${resource.id}" references unknown system path "${resource.systemPath}"`
+      )
+    }
+
+    if (resource.ownerRoleId !== undefined && !rolesById.has(resource.ownerRoleId)) {
+      addIssue(
+        ctx,
+        ['resources', resource.id, 'ownerRoleId'],
+        `Resource "${resource.id}" references unknown ownerRoleId "${resource.ownerRoleId}"`
+      )
+    }
+
+    if (resource.kind === 'agent' && resource.actsAsRoleId !== undefined && !rolesById.has(resource.actsAsRoleId)) {
+      addIssue(
+        ctx,
+        ['resources', resource.id, 'actsAsRoleId'],
+        `Agent resource "${resource.id}" references unknown actsAsRoleId "${resource.actsAsRoleId}"`
+      )
+    }
+  })
+
+  Object.values(model.roles).forEach((role) => {
+    if (role.heldBy === undefined) return
+
+    asRoleHolderArray(role.heldBy).forEach((holder, holderIndex) => {
+      if (holder.kind !== 'agent') return
+
+      const resource = resourcesById.get(holder.agentId)
+      if (resource === undefined) {
+        addIssue(
+          ctx,
+          ['roles', role.id, 'heldBy', Array.isArray(role.heldBy) ? holderIndex : 'agentId'],
+          `Role "${role.id}" references unknown agent holder resource "${holder.agentId}"`
+        )
+        return
+      }
+
+      if (resource.kind !== 'agent') {
+        addIssue(
+          ctx,
+          ['roles', role.id, 'heldBy', Array.isArray(role.heldBy) ? holderIndex : 'agentId'],
+          `Role "${role.id}" agent holder "${holder.agentId}" must reference an agent resource`
+        )
+      }
+    })
+  })
+
+  // Phase 4: model.knowledge is now Record<id, OrgKnowledgeNode>
+  Object.entries(model.knowledge).forEach(([nodeId, node]) => {
+    node.ownerIds.forEach((roleId, ownerIndex) => {
+      if (!rolesById.has(roleId)) {
+        addIssue(
+          ctx,
+          ['knowledge', nodeId, 'ownerIds', ownerIndex],
+          `Knowledge node "${node.id}" references unknown owner role "${roleId}"`
+        )
+      }
+    })
+  })
+
+  // ---------------------------------------------------------------------------
+  // B3, B4, B5, L19 — ContentNode refines (Phase 3, Wave 1A)
+  // ---------------------------------------------------------------------------
+  //
+  // These refines apply recursively to every system in the model tree
+  // (top-level systems + nested subsystems at any depth).
+  //
+  // B3 — Cycle detection: parentContentId chain must not form a cycle.
+  // B4 — Same-system-only: parentContentId must resolve within the same content map.
+  // B5 — Payload validation: registered (kind, type) pairs validate data against
+  //       the registered payloadSchema; unregistered pairs pass through (per D2).
+  // L19 — Same-meta-kind parent: when both child and parent are registered, they
+  //        must share the same `kind` (meta-category).
+
+  type SystemLike = {
+    id?: string
+    content?: Record<string, { kind: string; type: string; parentContentId?: string; data?: Record<string, unknown> }>
+    subsystems?: Record<string, SystemLike>
+  }
+
+  function validateSystemContent(system: SystemLike, systemPath: Array<string | number>): void {
+    const content = system.content
+    if (content === undefined || Object.keys(content).length === 0) {
+      // Recurse into subsystems even when own content is absent.
+      if (system.subsystems !== undefined) {
+        Object.entries(system.subsystems).forEach(([childKey, child]) => {
+          validateSystemContent(child, [...systemPath, 'subsystems', childKey])
+        })
+      }
+      return
+    }
+
+    // B4 — verify every parentContentId resolves within this content map.
+    Object.entries(content).forEach(([localId, node]) => {
+      if (node.parentContentId !== undefined && !(node.parentContentId in content)) {
+        addIssue(
+          ctx,
+          [...systemPath, 'content', localId, 'parentContentId'],
+          `Content node "${localId}" parentContentId "${node.parentContentId}" does not resolve within the same system`
+        )
+      }
+    })
+
+    // B3 — cycle detection on parentContentId chains within this content map.
+    Object.entries(content).forEach(([localId, node]) => {
+      const visited = new Set<string>()
+      let currentId: string | undefined = node.parentContentId
+
+      while (currentId !== undefined) {
+        if (currentId === localId || visited.has(currentId)) {
+          addIssue(
+            ctx,
+            [...systemPath, 'content', localId, 'parentContentId'],
+            `Content node "${localId}" has a parentContentId cycle`
+          )
+          break
+        }
+        visited.add(currentId)
+        currentId = content[currentId]?.parentContentId
+      }
+    })
+
+    // B5 + L19 — per-node payload validation and same-meta-kind parent constraint.
+    Object.entries(content).forEach(([localId, node]) => {
+      const childDef = lookupContentType(node.kind, node.type)
+
+      // B5 — validate data against registered payloadSchema when pair is known.
+      if (childDef !== undefined && node.data !== undefined) {
+        const result = childDef.payloadSchema.safeParse(node.data)
+        if (!result.success) {
+          addIssue(
+            ctx,
+            [...systemPath, 'content', localId, 'data'],
+            `Content node "${localId}" (${node.kind}:${node.type}) data failed payload validation: ${result.error.message}`
+          )
+        }
+      }
+
+      // L19 — when both child and parent are registered, they must share the same kind.
+      if (node.parentContentId !== undefined && childDef !== undefined) {
+        const parentNode = content[node.parentContentId]
+        if (parentNode !== undefined) {
+          const parentDef = lookupContentType(parentNode.kind, parentNode.type)
+          if (parentDef !== undefined && childDef.kind !== parentDef.kind) {
+            addIssue(
+              ctx,
+              [...systemPath, 'content', localId, 'parentContentId'],
+              `Content node "${localId}" kind "${childDef.kind}" cannot parent under "${node.parentContentId}" kind "${parentDef.kind}": parentContentId must be same-meta-kind (per L19)`
+            )
+          }
+        }
+      }
+    })
+
+    // Recurse into subsystems.
+    if (system.subsystems !== undefined) {
+      Object.entries(system.subsystems).forEach(([childKey, child]) => {
+        validateSystemContent(child, [...systemPath, 'subsystems', childKey])
+      })
+    }
+  }
+
+  Object.entries(model.systems).forEach(([systemKey, system]) => {
+    validateSystemContent(system as SystemLike, ['systems', systemKey])
+  })
 })