@elevasis/core 0.22.0 → 0.24.0

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

@@ -20,7 +20,16 @@ describe('OrganizationModelIconTokenSchema', () => {
   })
 
   it('rejects random strings outside the built-in and custom namespaces', () => {
-    for (const token of ['crm', 'lead-gen', 'settings', 'random.icon', 'custom.', 'custom.Bad']) {
+    for (const token of [
+      'nav.crm',
+      'feature.sales',
+      'surface.dashboard',
+      'action.approve',
+      'status.success',
+      'random.icon',
+      'custom.',
+      'custom.Bad'
+    ]) {
       expect(OrganizationModelIconTokenSchema.safeParse(token).success).toBe(false)
     }
   })

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

@@ -1,18 +1,22 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import {
   OrgKnowledgeNodeSchema,
   OrgKnowledgeKindSchema,
   KnowledgeDomainSchema,
-  KnowledgeLinkSchema
+  KnowledgeLinkSchema,
+  KnowledgeTargetKindSchema,
+  KnowledgeTargetRefSchema
 } from '../domains/knowledge'
 import { OrganizationGraphEdgeKindSchema } from '../graph/schema'
 import { buildOrganizationGraph } from '../graph/build'
 import { DEFAULT_ORGANIZATION_MODEL, DEFAULT_ORGANIZATION_MODEL_KNOWLEDGE } from '../defaults'
 import { resolveOrganizationModel } from '../resolve'
+import { compileOrganizationOntology } from '../ontology'
+import { byOntology, governedBy, parsePath } from '../../knowledge/queries'
 import type { OrganizationModel } from '../types'
 
 // ---------------------------------------------------------------------------
-// OrgKnowledgeNodeSchema — shape and validation
+// OrgKnowledgeNodeSchema — shape and validation
 // ---------------------------------------------------------------------------
 
 describe('OrgKnowledgeNodeSchema', () => {
@@ -87,10 +91,10 @@ describe('OrgKnowledgeNodeSchema', () => {
   it('accepts an optional semantic icon token', () => {
     const node = OrgKnowledgeNodeSchema.parse({
       ...makeNode('playbook'),
-      icon: 'knowledge.playbook'
+      icon: 'playbook'
     })
 
-    expect(node.icon).toBe('knowledge.playbook')
+    expect(node.icon).toBe('playbook')
   })
 
   it('rejects an unknown icon token', () => {
@@ -101,6 +105,33 @@ describe('OrgKnowledgeNodeSchema', () => {
 
     expect(result.success).toBe(false)
   })
+
+  it('accepts an optional externalUrl', () => {
+    const node = OrgKnowledgeNodeSchema.parse({
+      ...makeNode('reference'),
+      externalUrl: 'https://docs.elevasis.com/technical/architecture'
+    })
+
+    expect(node.externalUrl).toBe('https://docs.elevasis.com/technical/architecture')
+  })
+
+  it('rejects an invalid externalUrl', () => {
+    const result = OrgKnowledgeNodeSchema.safeParse({
+      ...makeNode('reference'),
+      externalUrl: 'not-a-url'
+    })
+
+    expect(result.success).toBe(false)
+  })
+
+  it('accepts an optional generated sourceFilePath', () => {
+    const node = OrgKnowledgeNodeSchema.parse({
+      ...makeNode('reference'),
+      sourceFilePath: 'packages/elevasis-core/src/knowledge/nodes/platform/reference.mdx'
+    })
+
+    expect(node.sourceFilePath).toBe('packages/elevasis-core/src/knowledge/nodes/platform/reference.mdx')
+  })
 })
 
 describe('resolveOrganizationModel with knowledge owner roles', () => {
@@ -117,8 +148,9 @@ describe('resolveOrganizationModel with knowledge owner roles', () => {
   it('passes when ownerIds reference declared role ids', () => {
     expect(() =>
       resolveOrganizationModel({
-        roles: { roles: [{ id: 'role.ops-lead', title: 'Ops Lead' }] },
-        knowledge: { nodes: [node] }
+        roles: { 'role.ops-lead': { id: 'role.ops-lead', order: 10, title: 'Ops Lead' } },
+        // Phase 4: knowledge is a flat Record<id, OrgKnowledgeNode>
+        knowledge: { 'knowledge.test-owner': node }
       })
     ).not.toThrow()
   })
@@ -126,14 +158,123 @@ describe('resolveOrganizationModel with knowledge owner roles', () => {
   it('throws when ownerIds reference unknown role ids', () => {
     expect(() =>
       resolveOrganizationModel({
-        knowledge: { nodes: [node] }
+        knowledge: { 'knowledge.test-owner': node }
       })
     ).toThrow(/unknown owner role/)
   })
 })
 
+describe('resolveOrganizationModel with ontology knowledge targets', () => {
+  it('accepts knowledge links that directly target compiled ontology records', () => {
+    expect(() =>
+      resolveOrganizationModel({
+        systems: {
+          'sales.crm': {
+            id: 'sales.crm',
+            order: 10,
+            label: 'CRM',
+            enabled: true,
+            ontology: {
+              objectTypes: {
+                'sales.crm:object/deal': {
+                  id: 'sales.crm:object/deal',
+                  label: 'Deal'
+                }
+              }
+            }
+          }
+        },
+        knowledge: {
+          'knowledge.deal-policy': {
+            id: 'knowledge.deal-policy',
+            kind: 'reference',
+            title: 'Deal Policy',
+            summary: 'How deal records are governed.',
+            body: 'Deal policy.',
+            links: [{ target: { kind: 'ontology', id: 'sales.crm:object/deal' } }],
+            updatedAt: '2026-05-14'
+          }
+        }
+      })
+    ).not.toThrow()
+  })
+
+  it('rejects knowledge links to unknown ontology records', () => {
+    expect(() =>
+      resolveOrganizationModel({
+        knowledge: {
+          'knowledge.missing-ontology': {
+            id: 'knowledge.missing-ontology',
+            kind: 'reference',
+            title: 'Missing Ontology',
+            summary: 'References a missing ontology record.',
+            body: 'Missing.',
+            links: [{ target: { kind: 'ontology', id: 'sales.crm:object/missing' } }],
+            updatedAt: '2026-05-14'
+          }
+        }
+      })
+    ).toThrow(/unknown ontology target/)
+  })
+
+  it('compiles authored ontology targets without requiring legacy provenance fields', () => {
+    const model = resolveOrganizationModel({
+      systems: {
+        'sales.crm': {
+          id: 'sales.crm',
+          order: 10,
+          label: 'CRM',
+          enabled: true,
+          ontology: {
+            objectTypes: {
+              'sales.crm:object/deal': {
+                id: 'sales.crm:object/deal',
+                label: 'Deal'
+              }
+            },
+            actionTypes: {
+              'sales.crm:action/update-deal': {
+                id: 'sales.crm:action/update-deal',
+                label: 'Update Deal',
+                actsOn: ['sales.crm:object/deal']
+              }
+            },
+            catalogTypes: {
+              'sales.crm:catalog/pipeline': {
+                id: 'sales.crm:catalog/pipeline',
+                label: 'Pipeline',
+                appliesTo: 'sales.crm:object/deal'
+              }
+            }
+          }
+        }
+      },
+      knowledge: {
+        'knowledge.pipeline-policy': {
+          id: 'knowledge.pipeline-policy',
+          kind: 'reference',
+          title: 'Pipeline Policy',
+          summary: 'How pipeline ontology is governed.',
+          body: 'Pipeline policy.',
+          links: [{ target: { kind: 'ontology', id: 'sales.crm:catalog/pipeline' } }],
+          updatedAt: '2026-05-14'
+        }
+      }
+    })
+    const compiled = compileOrganizationOntology(model)
+
+    expect(compiled.diagnostics).toEqual([])
+    expect(compiled.ontology.objectTypes['sales.crm:object/deal']).not.toHaveProperty('legacyEntityId')
+    expect(compiled.ontology.actionTypes['sales.crm:action/update-deal']).not.toHaveProperty('legacyActionId')
+    expect(compiled.ontology.catalogTypes['sales.crm:catalog/pipeline']).not.toHaveProperty('legacyContentId')
+    expect(model.knowledge['knowledge.pipeline-policy']?.links[0]?.nodeId).toBe(
+      'ontology:sales.crm:catalog/pipeline'
+    )
+  })
+})
+
 // ---------------------------------------------------------------------------
-// OrgKnowledgeKindSchema — enum shape
+// OrgKnowledgeKindSchema — enum shape
 // ---------------------------------------------------------------------------
 
 describe('OrgKnowledgeKindSchema', () => {
@@ -150,7 +291,7 @@ describe('OrgKnowledgeKindSchema', () => {
 })
 
 // ---------------------------------------------------------------------------
-// OrganizationGraphEdgeKindSchema — governs edge is present
+// OrganizationGraphEdgeKindSchema — governs edge is present
 // ---------------------------------------------------------------------------
 
 describe('OrganizationGraphEdgeKindSchema', () => {
@@ -160,60 +301,79 @@ describe('OrganizationGraphEdgeKindSchema', () => {
 })
 
 // ---------------------------------------------------------------------------
-// DEFAULT_ORGANIZATION_MODEL_KNOWLEDGE — post Wave 2a: nodes is empty array
+// DEFAULT_ORGANIZATION_MODEL_KNOWLEDGE — Phase 4: flat Record<id, OrgKnowledgeNode> (D3).
+// The wrapper shape { version, lastModified, nodes[] } was removed; versioning
+// is in domainMetadata.knowledge. The default is an empty map {}.
 // ---------------------------------------------------------------------------
 
 describe('DEFAULT_ORGANIZATION_MODEL_KNOWLEDGE', () => {
-  it('has an empty nodes array after Wave 2a pilot literal removal', () => {
-    expect(DEFAULT_ORGANIZATION_MODEL_KNOWLEDGE.nodes).toEqual([])
+  it('is an empty object (flat map with no pre-seeded nodes)', () => {
+    expect(DEFAULT_ORGANIZATION_MODEL_KNOWLEDGE).toEqual({})
   })
 
   it('passes KnowledgeDomainSchema.parse without throwing', () => {
     expect(() => KnowledgeDomainSchema.parse(DEFAULT_ORGANIZATION_MODEL_KNOWLEDGE)).not.toThrow()
   })
+
+  it('does not have a .nodes array (wrapper shape was removed in Phase 4)', () => {
+    expect(DEFAULT_ORGANIZATION_MODEL_KNOWLEDGE).not.toHaveProperty('nodes')
+  })
+
+  it('does not have a .version field (moved to domainMetadata.knowledge)', () => {
+    expect(DEFAULT_ORGANIZATION_MODEL_KNOWLEDGE).not.toHaveProperty('version')
+  })
 })
 
 // ---------------------------------------------------------------------------
-// buildOrganizationGraph — knowledge nodes + governs edges
-// Synthetic OM used so tests are independent of DEFAULT_ORGANIZATION_MODEL
-// knowledge nodes (empty after Wave 2a, Decision 2-B).
+// buildOrganizationGraph — knowledge nodes + governs edges
+// Synthetic OM authored via flat Record<id, OrgKnowledgeNode> per Phase 4 schema.
 // ---------------------------------------------------------------------------
 
+// Phase 4: knowledge is a flat Record<id, OrgKnowledgeNode> — no .nodes array wrapper.
 const SYNTHETIC_OM: OrganizationModel = {
   ...DEFAULT_ORGANIZATION_MODEL,
+  systems: Object.fromEntries(
+    Object.entries(DEFAULT_ORGANIZATION_MODEL.systems).map(([key, system]) => [
+      key,
+      key === 'sales.crm' || key === 'sales.lead-gen'
+        ? { ...system, governedByKnowledge: ['knowledge.test-playbook-1'] }
+        : system
+    ])
+  ),
   knowledge: {
-    nodes: [
-      {
-        id: 'knowledge.test-playbook-1',
-        kind: 'playbook',
-        title: 'Test Playbook',
-        summary: 'Test playbook summary.',
-        body: '## Overview\n\nContent.',
-        links: [{ nodeId: 'feature:sales.crm' }, { nodeId: 'feature:sales.lead-gen' }],
-        ownerIds: [],
-        updatedAt: '2026-01-01'
-      },
-      {
-        id: 'knowledge.test-strategy-1',
-        kind: 'strategy',
-        title: 'Test Strategy',
-        summary: 'Test strategy summary.',
-        body: '## Strategy\n\nContent.',
-        links: [{ nodeId: 'feature:sales.lead-gen' }],
-        ownerIds: [],
-        updatedAt: '2026-01-02'
-      },
-      {
-        id: 'knowledge.test-reference-1',
-        kind: 'reference',
-        title: 'Test Reference',
-        summary: 'Test reference summary.',
-        body: '## Reference\n\nContent.',
-        links: [],
-        ownerIds: [],
-        updatedAt: '2026-01-03'
-      }
-    ]
+    'knowledge.test-playbook-1': {
+      id: 'knowledge.test-playbook-1',
+      kind: 'playbook',
+      title: 'Test Playbook',
+      summary: 'Test playbook summary.',
+      body: '## Overview\n\nContent.',
+      links: [
+        { target: { kind: 'system', id: 'sales.crm' }, nodeId: 'system:sales.crm' },
+        { target: { kind: 'system', id: 'sales.lead-gen' }, nodeId: 'system:sales.lead-gen' }
+      ],
+      ownerIds: [],
+      updatedAt: '2026-01-01'
+    },
+    'knowledge.test-strategy-1': {
+      id: 'knowledge.test-strategy-1',
+      kind: 'strategy',
+      title: 'Test Strategy',
+      summary: 'Test strategy summary.',
+      body: '## Strategy\n\nContent.',
+      links: [],
+      ownerIds: [],
+      updatedAt: '2026-01-02'
+    },
+    'knowledge.test-reference-1': {
+      id: 'knowledge.test-reference-1',
+      kind: 'reference',
+      title: 'Test Reference',
+      summary: 'Test reference summary.',
+      body: '## Reference\n\nContent.',
+      links: [],
+      ownerIds: [],
+      updatedAt: '2026-01-03'
+    }
   }
 }
 
@@ -222,11 +382,11 @@ describe('buildOrganizationGraph with knowledge', () => {
 
   it('emits a knowledge node for each synthetic node', () => {
     const knowledgeNodes = graph.nodes.filter((n) => n.kind === 'knowledge')
-    expect(knowledgeNodes.length).toBe(SYNTHETIC_OM.knowledge.nodes.length)
+    expect(knowledgeNodes.length).toBe(Object.keys(SYNTHETIC_OM.knowledge).length)
   })
 
   it('knowledge nodes carry sourceId matching the OM node id', () => {
-    for (const omNode of SYNTHETIC_OM.knowledge.nodes) {
+    for (const omNode of Object.values(SYNTHETIC_OM.knowledge)) {
       const graphNode = graph.nodes.find((n) => n.sourceId === omNode.id)
       expect(graphNode).toBeDefined()
       expect(graphNode?.kind).toBe('knowledge')
@@ -236,12 +396,12 @@ describe('buildOrganizationGraph with knowledge', () => {
 
   it('emits governs edges for nodes that have links', () => {
     const governsEdges = graph.edges.filter((e) => e.kind === 'governs')
-    const totalLinks = SYNTHETIC_OM.knowledge.nodes.reduce((sum, n) => sum + n.links.length, 0)
+    const totalLinks = Object.values(SYNTHETIC_OM.knowledge).reduce((sum, n) => sum + n.links.length, 0)
     expect(governsEdges.length).toBe(totalLinks)
   })
 
   it('links targetId resolves to an existing graph node id for at least one node', () => {
-    const nodeWithLinks = SYNTHETIC_OM.knowledge.nodes.find((n) => n.links.length > 0)
+    const nodeWithLinks = Object.values(SYNTHETIC_OM.knowledge).find((n) => n.links.length > 0)
     expect(nodeWithLinks).toBeDefined()
 
     const graphNodeIds = new Set(graph.nodes.map((n) => n.id))
@@ -255,16 +415,116 @@ describe('buildOrganizationGraph with knowledge', () => {
     const defaultKnowledgeNodes = defaultGraph.nodes.filter((n) => n.kind === 'knowledge')
     expect(defaultKnowledgeNodes).toHaveLength(0)
   })
+
+  it('emits governs edges from knowledge directly to ontology graph nodes', () => {
+    const model = resolveOrganizationModel({
+      systems: {
+        'sales.crm': {
+          id: 'sales.crm',
+          order: 10,
+          label: 'CRM',
+          enabled: true,
+          ontology: {
+            objectTypes: {
+              'sales.crm:object/deal': {
+                id: 'sales.crm:object/deal',
+                label: 'Deal'
+              }
+            }
+          }
+        }
+      },
+      knowledge: {
+        'knowledge.deal-policy': {
+          id: 'knowledge.deal-policy',
+          kind: 'reference',
+          title: 'Deal Policy',
+          summary: 'How deal records are governed.',
+          body: 'Deal policy.',
+          links: [{ target: { kind: 'ontology', id: 'sales.crm:object/deal' } }],
+          ownerIds: [],
+          updatedAt: '2026-05-14'
+        }
+      }
+    })
+    const ontologyGraph = buildOrganizationGraph({ organizationModel: model })
+
+    expect(
+      ontologyGraph.edges.find(
+        (edge) =>
+          edge.kind === 'governs' &&
+          edge.sourceId === 'knowledge:knowledge.deal-policy' &&
+          edge.targetId === 'ontology:sales.crm:object/deal'
+      )
+    ).toBeDefined()
+  })
+
+  it('knowledge query helpers traverse ontology graph node IDs', () => {
+    const model = resolveOrganizationModel({
+      systems: {
+        'sales.crm': {
+          id: 'sales.crm',
+          order: 10,
+          label: 'CRM',
+          enabled: true,
+          ontology: {
+            objectTypes: {
+              'sales.crm:object/deal': {
+                id: 'sales.crm:object/deal',
+                label: 'Deal'
+              }
+            }
+          }
+        }
+      },
+      knowledge: {
+        'knowledge.deal-policy': {
+          id: 'knowledge.deal-policy',
+          kind: 'reference',
+          title: 'Deal Policy',
+          summary: 'How deal records are governed.',
+          body: 'Deal policy.',
+          links: [{ target: { kind: 'ontology', id: 'sales.crm:object/deal' } }],
+          ownerIds: [],
+          updatedAt: '2026-05-14'
+        }
+      }
+    })
+    const ontologyGraph = buildOrganizationGraph({ organizationModel: model })
+    const nodes = Object.values(model.knowledge)
+
+    expect(byOntology(ontologyGraph, 'sales.crm:object/deal', nodes).map((node) => node.id)).toEqual([
+      'knowledge.deal-policy'
+    ])
+    expect(governedBy(ontologyGraph, 'ontology:sales.crm:object/deal')).toEqual(['knowledge:knowledge.deal-policy'])
+    expect(parsePath('/by-ontology/sales.crm:object/deal')).toEqual({
+      mount: 'by-ontology',
+      args: ['sales.crm:object/deal']
+    })
+  })
 })
 
 // ---------------------------------------------------------------------------
-// KnowledgeLinkSchema — nodeId format validation
+// KnowledgeLinkSchema — nodeId format validation
 // ---------------------------------------------------------------------------
 
 describe('KnowledgeLinkSchema', () => {
-  it('accepts a valid kind:dotted-path nodeId', () => {
-    expect(() => KnowledgeLinkSchema.parse({ nodeId: 'feature:sales.crm' })).not.toThrow()
-    expect(() => KnowledgeLinkSchema.parse({ nodeId: 'feature:sales.lead-gen' })).not.toThrow()
+  it('accepts and normalizes a canonical typed target', () => {
+    const link = KnowledgeLinkSchema.parse({ target: { kind: 'system', id: 'sales.crm' } })
+
+    expect(link).toEqual({
+      target: { kind: 'system', id: 'sales.crm' },
+      nodeId: 'system:sales.crm'
+    })
+  })
+
+  it('accepts and normalizes a legacy kind:dotted-path nodeId', () => {
+    const link = KnowledgeLinkSchema.parse({ nodeId: 'system:sales.lead-gen' })
+
+    expect(link).toEqual({
+      target: { kind: 'system', id: 'sales.lead-gen' },
+      nodeId: 'system:sales.lead-gen'
+    })
   })
 
   it('accepts resource: and knowledge: prefixed node IDs', () => {
@@ -272,8 +532,20 @@ describe('KnowledgeLinkSchema', () => {
     expect(() => KnowledgeLinkSchema.parse({ nodeId: 'knowledge:knowledge.test-doc' })).not.toThrow()
   })
 
+  it('accepts content-node: prefixed node IDs (D4 — KnowledgeTargetKindSchema includes content-node)', () => {
+    expect(() => KnowledgeLinkSchema.parse({ nodeId: 'content-node:sales.crm:default-pipeline' })).not.toThrow()
+  })
+
+  it('accepts and normalizes ontology graph node IDs', () => {
+    const link = KnowledgeLinkSchema.parse({ nodeId: 'ontology:sales.crm:object/deal' })
+
+    expect(link).toEqual({
+      target: { kind: 'ontology', id: 'sales.crm:object/deal' },
+      nodeId: 'ontology:sales.crm:object/deal'
+    })
+  })
+
   it('rejects a bare dotted ID with no kind: prefix', () => {
-    // NodeIdStringSchema requires kind:dotted-path format
     expect(KnowledgeLinkSchema.safeParse({ nodeId: 'sales.crm' }).success).toBe(false)
   })
 
@@ -282,8 +554,7 @@ describe('KnowledgeLinkSchema', () => {
   })
 
   it('rejects a nodeId with uppercase characters', () => {
-    // NodeIdStringSchema regex requires lowercase
-    expect(KnowledgeLinkSchema.safeParse({ nodeId: 'Feature:Sales.CRM' }).success).toBe(false)
+    expect(KnowledgeLinkSchema.safeParse({ nodeId: 'system:Sales.CRM' }).success).toBe(false)
   })
 
   it('rejects a link missing the nodeId field', () => {
@@ -295,8 +566,95 @@ describe('KnowledgeLinkSchema', () => {
   })
 })
 
+describe('KnowledgeTargetRefSchema', () => {
+  it('accepts modeled target kinds', () => {
+    expect(KnowledgeTargetRefSchema.safeParse({ kind: 'system', id: 'sales.crm' }).success).toBe(true)
+    expect(KnowledgeTargetRefSchema.safeParse({ kind: 'customer-segment', id: 'customer.enterprise' }).success).toBe(
+      true
+    )
+  })
+
+  it('accepts content-node as a target kind (D4)', () => {
+    expect(KnowledgeTargetKindSchema.safeParse('content-node').success).toBe(true)
+    expect(KnowledgeTargetRefSchema.safeParse({ kind: 'content-node', id: 'sales.crm:default-pipeline' }).success).toBe(
+      true
+    )
+  })
+
+  it('keeps content-node targets as compatibility pass-through links', () => {
+    const link = KnowledgeLinkSchema.parse({
+      target: { kind: 'content-node', id: 'sales.crm:default-pipeline' }
+    })
+
+    expect(link).toEqual({
+      target: { kind: 'content-node', id: 'sales.crm:default-pipeline' },
+      nodeId: 'content-node:sales.crm:default-pipeline'
+    })
+  })
+
+  it('accepts ontology as a target kind when the id is a valid ontology id', () => {
+    expect(KnowledgeTargetKindSchema.safeParse('ontology').success).toBe(true)
+    expect(KnowledgeTargetRefSchema.safeParse({ kind: 'ontology', id: 'sales.crm:object/deal' }).success).toBe(true)
+  })
+
+  it('rejects ontology targets with malformed ontology ids', () => {
+    expect(KnowledgeTargetRefSchema.safeParse({ kind: 'ontology', id: 'sales.crm.deal' }).success).toBe(false)
+  })
+
+  it('rejects unknown target kinds', () => {
+    expect(KnowledgeTargetKindSchema.safeParse('integration').success).toBe(false)
+    expect(KnowledgeTargetRefSchema.safeParse({ kind: 'integration', id: 'hubspot' }).success).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// KnowledgeDomainSchema — flat Record shape (Phase 4 D3)
+// ---------------------------------------------------------------------------
+
+describe('KnowledgeDomainSchema — flat Record<id, OrgKnowledgeNode>', () => {
+  it('accepts an empty map', () => {
+    expect(KnowledgeDomainSchema.safeParse({}).success).toBe(true)
+  })
+
+  it('defaults to empty map when undefined', () => {
+    const result = KnowledgeDomainSchema.safeParse(undefined)
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data).toEqual({})
+    }
+  })
+
+  it('accepts a Record keyed by knowledge node ids', () => {
+    const result = KnowledgeDomainSchema.safeParse({
+      'knowledge.my-playbook': {
+        id: 'knowledge.my-playbook',
+        kind: 'playbook',
+        title: 'My Playbook',
+        summary: 'A test playbook.',
+        body: '## Content',
+        links: [],
+        ownerIds: [],
+        updatedAt: '2026-05-01'
+      }
+    })
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects the old wrapper shape { version, lastModified, nodes[] }', () => {
+    // The old wrapper-with-array shape does not parse as a Record<id, OrgKnowledgeNode>
+    const result = KnowledgeDomainSchema.safeParse({
+      version: 1,
+      lastModified: '2026-05-10',
+      nodes: []
+    })
+    // Each key ('version', 'lastModified', 'nodes') would be parsed as a knowledge node id,
+    // and the values are not valid OrgKnowledgeNodeSchema — so this should fail
+    expect(result.success).toBe(false)
+  })
+})
+
 // ---------------------------------------------------------------------------
-// OrgKnowledgeNodeSchema — field length constraints
+// OrgKnowledgeNodeSchema — field length constraints
 // ---------------------------------------------------------------------------
 
 describe('OrgKnowledgeNodeSchema length constraints', () => {
@@ -347,7 +705,6 @@ describe('OrgKnowledgeNodeSchema length constraints', () => {
   })
 
   it('rejects id with uppercase characters', () => {
-    // ModelIdSchema requires lowercase kebab/dot/underscore separated IDs
     const result = OrgKnowledgeNodeSchema.safeParse({ ...BASE, id: 'Knowledge.Test' })
     expect(result.success).toBe(false)
   })