@elevasis/core 0.23.0 → 0.24.0

package/src/knowledge/__tests__/queries.test.ts

@@ -1,73 +1,74 @@
-import { describe, expect, it } from 'vitest'
-import { bySystem, byKind, byOwner, governs, governedBy, parsePath } from '../queries'
-import { formatText, formatJson, formatIdsOnly } from '../format'
-import type { OrganizationGraph } from '../../organization-model/graph/types'
-import type { OrgKnowledgeNode } from '../../organization-model/domains/knowledge'
-
-// ---------------------------------------------------------------------------
-// Synthetic fixtures
-// ---------------------------------------------------------------------------
-
-/**
- * Three knowledge nodes covering all three kinds.
- * - playbook-a governs system:sales.crm and system:sales.lead-gen
- * - strategy-b governs system:sales.lead-gen
- * - reference-c has no links (no governs edges)
- * - playbook-d is owned by "role.ops-lead"
- */
-const NODES: OrgKnowledgeNode[] = [
-  {
-    id: 'knowledge.playbook-a',
-    kind: 'playbook',
-    title: 'Playbook A',
-    summary: 'Playbook A summary.',
-    body: '## Playbook A\n\nContent.',
-    links: [{ nodeId: 'system:sales.crm' }, { nodeId: 'system:sales.lead-gen' }],
-    ownerIds: [],
-    updatedAt: '2026-01-01'
-  },
-  {
-    id: 'knowledge.strategy-b',
-    kind: 'strategy',
-    title: 'Strategy B',
-    summary: 'Strategy B summary.',
-    body: '## Strategy B\n\nContent.',
-    links: [{ nodeId: 'system:sales.lead-gen' }],
-    ownerIds: ['role.ops-lead'],
-    updatedAt: '2026-01-02'
-  },
-  {
-    id: 'knowledge.reference-c',
-    kind: 'reference',
-    title: 'Reference C',
-    summary: 'Reference C summary.',
-    body: '## Reference C\n\nContent.',
-    links: [],
-    ownerIds: [],
-    updatedAt: '2026-01-03'
-  },
-  {
-    id: 'knowledge.playbook-d',
-    kind: 'playbook',
-    title: 'Playbook D',
-    summary: 'Playbook D summary.',
-    body: '## Playbook D\n\nContent.',
-    links: [],
-    ownerIds: ['role.ops-lead', 'role.ceo'],
-    updatedAt: '2026-01-04'
-  }
-]
-
-/**
- * Minimal synthetic OrganizationGraph derived from the above nodes.
- * Graph node IDs follow the convention: `knowledge:<om-node-id>`
- */
-const GRAPH: OrganizationGraph = {
-  version: 1,
-  organizationModelVersion: 1,
-  nodes: [
-    { id: 'organization-model', kind: 'organization', label: 'Organization Model' },
-    { id: 'system:sales.crm', kind: 'system', label: 'CRM', sourceId: 'sales.crm', systemId: 'sales.crm' },
+import { describe, expect, it } from 'vitest'
+import { bySystem, byOntology, byKind, byOwner, governs, governedBy, parsePath } from '../queries'
+import { byOntology as publicByOntology } from '../index'
+import { formatText, formatJson, formatIdsOnly } from '../format'
+import type { OrganizationGraph } from '../../organization-model/graph/types'
+import type { OrgKnowledgeNode } from '../../organization-model/domains/knowledge'
+
+// ---------------------------------------------------------------------------
+// Synthetic fixtures
+// ---------------------------------------------------------------------------
+
+/**
+ * Three knowledge nodes covering all three kinds.
+ * - playbook-a governs system:sales.crm and system:sales.lead-gen
+ * - strategy-b governs system:sales.lead-gen
+ * - reference-c has no links (no governs edges)
+ * - playbook-d is owned by "role.ops-lead"
+ */
+const NODES: OrgKnowledgeNode[] = [
+  {
+    id: 'knowledge.playbook-a',
+    kind: 'playbook',
+    title: 'Playbook A',
+    summary: 'Playbook A summary.',
+    body: '## Playbook A\n\nContent.',
+    links: [{ nodeId: 'system:sales.crm' }, { nodeId: 'system:sales.lead-gen' }],
+    ownerIds: [],
+    updatedAt: '2026-01-01'
+  },
+  {
+    id: 'knowledge.strategy-b',
+    kind: 'strategy',
+    title: 'Strategy B',
+    summary: 'Strategy B summary.',
+    body: '## Strategy B\n\nContent.',
+    links: [{ nodeId: 'system:sales.lead-gen' }],
+    ownerIds: ['role.ops-lead'],
+    updatedAt: '2026-01-02'
+  },
+  {
+    id: 'knowledge.reference-c',
+    kind: 'reference',
+    title: 'Reference C',
+    summary: 'Reference C summary.',
+    body: '## Reference C\n\nContent.',
+    links: [],
+    ownerIds: [],
+    updatedAt: '2026-01-03'
+  },
+  {
+    id: 'knowledge.playbook-d',
+    kind: 'playbook',
+    title: 'Playbook D',
+    summary: 'Playbook D summary.',
+    body: '## Playbook D\n\nContent.',
+    links: [],
+    ownerIds: ['role.ops-lead', 'role.ceo'],
+    updatedAt: '2026-01-04'
+  }
+]
+
+/**
+ * Minimal synthetic OrganizationGraph derived from the above nodes.
+ * Graph node IDs follow the convention: `knowledge:<om-node-id>`
+ */
+const GRAPH: OrganizationGraph = {
+  version: 1,
+  organizationModelVersion: 1,
+  nodes: [
+    { id: 'organization-model', kind: 'organization', label: 'Organization Model' },
+    { id: 'system:sales.crm', kind: 'system', label: 'CRM', sourceId: 'sales.crm', systemId: 'sales.crm' },
     {
       id: 'system:sales.lead-gen',
       kind: 'system',
@@ -76,23 +77,29 @@ const GRAPH: OrganizationGraph = {
       systemId: 'sales.lead-gen'
     },
     {
-      id: 'knowledge:knowledge.playbook-a',
-      kind: 'knowledge',
-      label: 'Playbook A',
-      sourceId: 'knowledge.playbook-a'
-    },
-    {
-      id: 'knowledge:knowledge.strategy-b',
-      kind: 'knowledge',
-      label: 'Strategy B',
-      sourceId: 'knowledge.strategy-b'
+      id: 'ontology:sales.crm:object/deal',
+      kind: 'ontology',
+      label: 'Deal',
+      sourceId: 'sales.crm:object/deal'
     },
     {
-      id: 'knowledge:knowledge.reference-c',
+      id: 'knowledge:knowledge.playbook-a',
       kind: 'knowledge',
-      label: 'Reference C',
-      sourceId: 'knowledge.reference-c'
-    },
+      label: 'Playbook A',
+      sourceId: 'knowledge.playbook-a'
+    },
+    {
+      id: 'knowledge:knowledge.strategy-b',
+      kind: 'knowledge',
+      label: 'Strategy B',
+      sourceId: 'knowledge.strategy-b'
+    },
+    {
+      id: 'knowledge:knowledge.reference-c',
+      kind: 'knowledge',
+      label: 'Reference C',
+      sourceId: 'knowledge.reference-c'
+    },
     {
       id: 'knowledge:knowledge.playbook-d',
       kind: 'knowledge',
@@ -100,495 +107,579 @@ const GRAPH: OrganizationGraph = {
       sourceId: 'knowledge.playbook-d'
     }
   ],
-  edges: [
-    // contains edges (organization -> knowledge nodes)
-    {
-      id: 'edge:contains:organization-model:knowledge:knowledge.playbook-a',
-      kind: 'contains',
-      sourceId: 'organization-model',
-      targetId: 'knowledge:knowledge.playbook-a'
-    },
+  edges: [
+    // contains edges (organization -> knowledge nodes)
+    {
+      id: 'edge:contains:organization-model:knowledge:knowledge.playbook-a',
+      kind: 'contains',
+      sourceId: 'organization-model',
+      targetId: 'knowledge:knowledge.playbook-a'
+    },
+    {
+      id: 'edge:contains:organization-model:knowledge:knowledge.strategy-b',
+      kind: 'contains',
+      sourceId: 'organization-model',
+      targetId: 'knowledge:knowledge.strategy-b'
+    },
+    {
+      id: 'edge:contains:organization-model:knowledge:knowledge.reference-c',
+      kind: 'contains',
+      sourceId: 'organization-model',
+      targetId: 'knowledge:knowledge.reference-c'
+    },
+    {
+      id: 'edge:contains:organization-model:knowledge:knowledge.playbook-d',
+      kind: 'contains',
+      sourceId: 'organization-model',
+      targetId: 'knowledge:knowledge.playbook-d'
+    },
+    // governs edges
+    {
+      id: 'edge:governs:knowledge:knowledge.playbook-a:system:sales.crm',
+      kind: 'governs',
+      sourceId: 'knowledge:knowledge.playbook-a',
+      targetId: 'system:sales.crm'
+    },
+    {
+      id: 'edge:governs:knowledge:knowledge.playbook-a:system:sales.lead-gen',
+      kind: 'governs',
+      sourceId: 'knowledge:knowledge.playbook-a',
+      targetId: 'system:sales.lead-gen'
+    },
     {
-      id: 'edge:contains:organization-model:knowledge:knowledge.strategy-b',
-      kind: 'contains',
-      sourceId: 'organization-model',
-      targetId: 'knowledge:knowledge.strategy-b'
-    },
-    {
-      id: 'edge:contains:organization-model:knowledge:knowledge.reference-c',
-      kind: 'contains',
-      sourceId: 'organization-model',
-      targetId: 'knowledge:knowledge.reference-c'
-    },
-    {
-      id: 'edge:contains:organization-model:knowledge:knowledge.playbook-d',
-      kind: 'contains',
-      sourceId: 'organization-model',
-      targetId: 'knowledge:knowledge.playbook-d'
-    },
-    // governs edges
-    {
-      id: 'edge:governs:knowledge:knowledge.playbook-a:system:sales.crm',
-      kind: 'governs',
-      sourceId: 'knowledge:knowledge.playbook-a',
-      targetId: 'system:sales.crm'
-    },
-    {
-      id: 'edge:governs:knowledge:knowledge.playbook-a:system:sales.lead-gen',
+      id: 'edge:governs:knowledge:knowledge.strategy-b:system:sales.lead-gen',
       kind: 'governs',
-      sourceId: 'knowledge:knowledge.playbook-a',
+      sourceId: 'knowledge:knowledge.strategy-b',
       targetId: 'system:sales.lead-gen'
     },
     {
-      id: 'edge:governs:knowledge:knowledge.strategy-b:system:sales.lead-gen',
+      id: 'edge:governs:knowledge:knowledge.playbook-d:ontology:sales.crm:object/deal',
       kind: 'governs',
-      sourceId: 'knowledge:knowledge.strategy-b',
-      targetId: 'system:sales.lead-gen'
+      sourceId: 'knowledge:knowledge.playbook-d',
+      targetId: 'ontology:sales.crm:object/deal'
     }
   ]
 }
-
-// ---------------------------------------------------------------------------
-// bySystem
-// ---------------------------------------------------------------------------
-
+
+// ---------------------------------------------------------------------------
+// bySystem
+// ---------------------------------------------------------------------------
+
 describe('bySystem', () => {
-  it('returns nodes that have governs edges to the given system', () => {
-    const result = bySystem(GRAPH, 'sales.crm', NODES)
-    expect(result).toHaveLength(1)
-    expect(result[0].id).toBe('knowledge.playbook-a')
-  })
-
-  it('returns multiple nodes when multiple knowledge nodes govern the same system', () => {
-    const result = bySystem(GRAPH, 'sales.lead-gen', NODES)
-    const ids = result.map((n) => n.id).sort()
-    expect(ids).toEqual(['knowledge.playbook-a', 'knowledge.strategy-b'].sort())
-  })
-
-  it('returns empty array when no node governs the system', () => {
-    const result = bySystem(GRAPH, 'system.does-not-exist', NODES)
-    expect(result).toHaveLength(0)
-  })
-
-  it('returns full OrgKnowledgeNode objects (not just graph stubs)', () => {
-    const result = bySystem(GRAPH, 'sales.crm', NODES)
-    expect(result[0].body).toBeDefined()
-    expect(result[0].links).toBeDefined()
-    expect(result[0].ownerIds).toBeDefined()
+  it('returns nodes that have governs edges to the given system', () => {
+    const result = bySystem(GRAPH, 'sales.crm', NODES)
+    expect(result).toHaveLength(1)
+    expect(result[0].id).toBe('knowledge.playbook-a')
+  })
+
+  it('returns multiple nodes when multiple knowledge nodes govern the same system', () => {
+    const result = bySystem(GRAPH, 'sales.lead-gen', NODES)
+    const ids = result.map((n) => n.id).sort()
+    expect(ids).toEqual(['knowledge.playbook-a', 'knowledge.strategy-b'].sort())
+  })
+
+  it('returns empty array when no node governs the system', () => {
+    const result = bySystem(GRAPH, 'system.does-not-exist', NODES)
+    expect(result).toHaveLength(0)
+  })
+
+  it('returns full OrgKnowledgeNode objects (not just graph stubs)', () => {
+    const result = bySystem(GRAPH, 'sales.crm', NODES)
+    expect(result[0].body).toBeDefined()
+    expect(result[0].links).toBeDefined()
+    expect(result[0].ownerIds).toBeDefined()
   })
 })
 
 // ---------------------------------------------------------------------------
-// byKind
+// byOntology
 // ---------------------------------------------------------------------------
 
-describe('byKind', () => {
-  it('returns all playbook nodes', () => {
-    const result = byKind(GRAPH, 'playbook', NODES)
-    expect(result).toHaveLength(2)
-    expect(result.every((n) => n.kind === 'playbook')).toBe(true)
-  })
-
-  it('returns strategy nodes', () => {
-    const result = byKind(GRAPH, 'strategy', NODES)
-    expect(result).toHaveLength(1)
-    expect(result[0].id).toBe('knowledge.strategy-b')
-  })
-
-  it('returns reference nodes', () => {
-    const result = byKind(GRAPH, 'reference', NODES)
-    expect(result).toHaveLength(1)
-    expect(result[0].id).toBe('knowledge.reference-c')
-  })
-
-  it('returns empty array when no nodes match the kind', () => {
-    const result = byKind(GRAPH, 'playbook', [])
-    expect(result).toHaveLength(0)
+describe('byOntology', () => {
+  it('returns nodes that have governs edges to the given ontology id', () => {
+    const result = byOntology(GRAPH, 'sales.crm:object/deal', NODES)
+    expect(result.map((node) => node.id)).toEqual(['knowledge.playbook-d'])
+  })
+
+  it('accepts an ontology graph node id', () => {
+    const result = byOntology(GRAPH, 'ontology:sales.crm:object/deal', NODES)
+    expect(result.map((node) => node.id)).toEqual(['knowledge.playbook-d'])
+  })
+
+  it('routes raw ontology ids to ontology graph nodes instead of bridge-era system ids', () => {
+    const graph: OrganizationGraph = {
+      ...GRAPH,
+      nodes: [
+        ...GRAPH.nodes,
+        {
+          id: 'system:sales.crm:object/deal',
+          kind: 'system',
+          label: 'Bridge-shaped System',
+          sourceId: 'sales.crm:object/deal',
+          systemId: 'sales.crm:object/deal'
+        },
+        {
+          id: 'knowledge:knowledge.system-shaped',
+          kind: 'knowledge',
+          label: 'System Shaped',
+          sourceId: 'knowledge.system-shaped'
+        }
+      ],
+      edges: [
+        ...GRAPH.edges,
+        {
+          id: 'edge:governs:knowledge:knowledge.system-shaped:system:sales.crm:object/deal',
+          kind: 'governs',
+          sourceId: 'knowledge:knowledge.system-shaped',
+          targetId: 'system:sales.crm:object/deal'
+        }
+      ]
+    }
+    const nodes: OrgKnowledgeNode[] = [
+      ...NODES,
+      {
+        id: 'knowledge.system-shaped',
+        kind: 'reference',
+        title: 'System Shaped',
+        summary: 'Should not match raw ontology lookup.',
+        body: 'Body.',
+        links: [{ nodeId: 'system:sales.crm:object/deal' }],
+        ownerIds: [],
+        updatedAt: '2026-05-14'
+      }
+    ]
+
+    expect(byOntology(graph, 'sales.crm:object/deal', nodes).map((node) => node.id)).toEqual([
+      'knowledge.playbook-d'
+    ])
+  })
+
+  it('is exported from the public knowledge query API', () => {
+    expect(publicByOntology).toBe(byOntology)
+    expect(publicByOntology(GRAPH, 'sales.crm:object/deal', NODES).map((node) => node.id)).toEqual([
+      'knowledge.playbook-d'
+    ])
   })
 })
 
 // ---------------------------------------------------------------------------
-// byOwner
-// ---------------------------------------------------------------------------
-
-describe('byOwner', () => {
-  it('returns nodes where ownerIds includes the given owner', () => {
-    const result = byOwner(GRAPH, 'role.ops-lead', NODES)
-    const ids = result.map((n) => n.id).sort()
-    expect(ids).toEqual(['knowledge.playbook-d', 'knowledge.strategy-b'].sort())
-  })
-
-  it('returns nodes for a second owner', () => {
-    const result = byOwner(GRAPH, 'role.ceo', NODES)
-    expect(result).toHaveLength(1)
-    expect(result[0].id).toBe('knowledge.playbook-d')
-  })
-
-  it('returns empty array when ownerId is not present in any node', () => {
-    const result = byOwner(GRAPH, 'role.unknown', NODES)
-    expect(result).toHaveLength(0)
-  })
+// byKind
+// ---------------------------------------------------------------------------
+
+describe('byKind', () => {
+  it('returns all playbook nodes', () => {
+    const result = byKind(GRAPH, 'playbook', NODES)
+    expect(result).toHaveLength(2)
+    expect(result.every((n) => n.kind === 'playbook')).toBe(true)
+  })
+
+  it('returns strategy nodes', () => {
+    const result = byKind(GRAPH, 'strategy', NODES)
+    expect(result).toHaveLength(1)
+    expect(result[0].id).toBe('knowledge.strategy-b')
+  })
+
+  it('returns reference nodes', () => {
+    const result = byKind(GRAPH, 'reference', NODES)
+    expect(result).toHaveLength(1)
+    expect(result[0].id).toBe('knowledge.reference-c')
+  })
+
+  it('returns empty array when no nodes match the kind', () => {
+    const result = byKind(GRAPH, 'playbook', [])
+    expect(result).toHaveLength(0)
+  })
 })
 
 // ---------------------------------------------------------------------------
-// governs
+// byOwner
 // ---------------------------------------------------------------------------
-
-describe('governs', () => {
-  it('returns target graph node IDs for outgoing governs edges (OM node id input)', () => {
-    const result = governs(GRAPH, 'knowledge.playbook-a')
-    expect(result.sort()).toEqual(['system:sales.crm', 'system:sales.lead-gen'].sort())
-  })
-
-  it('accepts graph node ID format input', () => {
-    const result = governs(GRAPH, 'knowledge:knowledge.playbook-a')
-    expect(result.sort()).toEqual(['system:sales.crm', 'system:sales.lead-gen'].sort())
-  })
-
-  it('returns single target for a node with one link', () => {
-    const result = governs(GRAPH, 'knowledge.strategy-b')
-    expect(result).toEqual(['system:sales.lead-gen'])
-  })
-
+
+describe('byOwner', () => {
+  it('returns nodes where ownerIds includes the given owner', () => {
+    const result = byOwner(GRAPH, 'role.ops-lead', NODES)
+    const ids = result.map((n) => n.id).sort()
+    expect(ids).toEqual(['knowledge.playbook-d', 'knowledge.strategy-b'].sort())
+  })
+
+  it('returns nodes for a second owner', () => {
+    const result = byOwner(GRAPH, 'role.ceo', NODES)
+    expect(result).toHaveLength(1)
+    expect(result[0].id).toBe('knowledge.playbook-d')
+  })
+
+  it('returns empty array when ownerId is not present in any node', () => {
+    const result = byOwner(GRAPH, 'role.unknown', NODES)
+    expect(result).toHaveLength(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// governs
+// ---------------------------------------------------------------------------
+
+describe('governs', () => {
+  it('returns target graph node IDs for outgoing governs edges (OM node id input)', () => {
+    const result = governs(GRAPH, 'knowledge.playbook-a')
+    expect(result.sort()).toEqual(['system:sales.crm', 'system:sales.lead-gen'].sort())
+  })
+
+  it('accepts graph node ID format input', () => {
+    const result = governs(GRAPH, 'knowledge:knowledge.playbook-a')
+    expect(result.sort()).toEqual(['system:sales.crm', 'system:sales.lead-gen'].sort())
+  })
+
+  it('returns single target for a node with one link', () => {
+    const result = governs(GRAPH, 'knowledge.strategy-b')
+    expect(result).toEqual(['system:sales.lead-gen'])
+  })
+
   it('returns empty array for a node with no governs edges', () => {
     const result = governs(GRAPH, 'knowledge.reference-c')
     expect(result).toHaveLength(0)
   })
-
-  it('returns empty array for an unknown nodeId', () => {
-    const result = governs(GRAPH, 'knowledge.does-not-exist')
-    expect(result).toHaveLength(0)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// governedBy
-// ---------------------------------------------------------------------------
-
-describe('governedBy', () => {
-  it('returns knowledge graph node IDs for incoming governs edges (prefixed system id)', () => {
-    const result = governedBy(GRAPH, 'system:sales.lead-gen')
-    const sorted = result.sort()
-    expect(sorted).toEqual(['knowledge:knowledge.playbook-a', 'knowledge:knowledge.strategy-b'].sort())
-  })
-
-  it('accepts bare system id (auto-prefixes with system:)', () => {
-    const result = governedBy(GRAPH, 'sales.crm')
-    expect(result).toEqual(['knowledge:knowledge.playbook-a'])
-  })
-
-  it('returns empty array when no knowledge node governs the target', () => {
-    const result = governedBy(GRAPH, 'system:dashboard')
-    expect(result).toHaveLength(0)
-  })
-
+
+  it('returns empty array for an unknown nodeId', () => {
+    const result = governs(GRAPH, 'knowledge.does-not-exist')
+    expect(result).toHaveLength(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// governedBy
+// ---------------------------------------------------------------------------
+
+describe('governedBy', () => {
+  it('returns knowledge graph node IDs for incoming governs edges (prefixed system id)', () => {
+    const result = governedBy(GRAPH, 'system:sales.lead-gen')
+    const sorted = result.sort()
+    expect(sorted).toEqual(['knowledge:knowledge.playbook-a', 'knowledge:knowledge.strategy-b'].sort())
+  })
+
+  it('accepts bare system id (auto-prefixes with system:)', () => {
+    const result = governedBy(GRAPH, 'sales.crm')
+    expect(result).toEqual(['knowledge:knowledge.playbook-a'])
+  })
+
+  it('returns empty array when no knowledge node governs the target', () => {
+    const result = governedBy(GRAPH, 'system:dashboard')
+    expect(result).toHaveLength(0)
+  })
+
   it('returns empty array for unknown target node id', () => {
     const result = governedBy(GRAPH, 'system:does-not-exist')
     expect(result).toHaveLength(0)
   })
 })
-
-// ---------------------------------------------------------------------------
-// parsePath — happy paths (all five mount axes)
-// ---------------------------------------------------------------------------
-
-describe('parsePath — happy paths', () => {
-  it('/by-kind/playbook → mount:by-kind args:[playbook]', () => {
-    expect(parsePath('/by-kind/playbook')).toEqual({ mount: 'by-kind', args: ['playbook'] })
-  })
-
-  it('/by-kind/strategy → mount:by-kind args:[strategy]', () => {
-    expect(parsePath('/by-kind/strategy')).toEqual({ mount: 'by-kind', args: ['strategy'] })
-  })
-
-  it('/by-system/sales.crm → mount:by-system args:[sales.crm]', () => {
-    expect(parsePath('/by-system/sales.crm')).toEqual({ mount: 'by-system', args: ['sales.crm'] })
-  })
-
-  it('/by-system/sales/crm (slash-delimited) → mount:by-system args:[sales/crm]', () => {
-    // systemId with slashes is joined and passed as-is for the caller to interpret
-    expect(parsePath('/by-system/sales/crm')).toEqual({ mount: 'by-system', args: ['sales/crm'] })
-  })
-
+
+// ---------------------------------------------------------------------------
+// parsePath — happy paths (all five mount axes)
+// ---------------------------------------------------------------------------
+
+describe('parsePath — happy paths', () => {
+  it('/by-kind/playbook → mount:by-kind args:[playbook]', () => {
+    expect(parsePath('/by-kind/playbook')).toEqual({ mount: 'by-kind', args: ['playbook'] })
+  })
+
+  it('/by-kind/strategy → mount:by-kind args:[strategy]', () => {
+    expect(parsePath('/by-kind/strategy')).toEqual({ mount: 'by-kind', args: ['strategy'] })
+  })
+
+  it('/by-system/sales.crm → mount:by-system args:[sales.crm]', () => {
+    expect(parsePath('/by-system/sales.crm')).toEqual({ mount: 'by-system', args: ['sales.crm'] })
+  })
+
+  it('/by-system/sales/crm (slash-delimited) → mount:by-system args:[sales/crm]', () => {
+    // systemId with slashes is joined and passed as-is for the caller to interpret
+    expect(parsePath('/by-system/sales/crm')).toEqual({ mount: 'by-system', args: ['sales/crm'] })
+  })
+
   it('/by-owner/role.ops-lead → mount:by-owner args:[role.ops-lead]', () => {
     expect(parsePath('/by-owner/role.ops-lead')).toEqual({ mount: 'by-owner', args: ['role.ops-lead'] })
   })
 
-  it('/graph/knowledge.outreach-playbook/governs → mount:graph args:[knowledge.outreach-playbook,governs]', () => {
-    expect(parsePath('/graph/knowledge.outreach-playbook/governs')).toEqual({
-      mount: 'graph',
-      args: ['knowledge.outreach-playbook', 'governs']
+  it('/by-ontology/sales.crm:object/deal → mount:by-ontology args:[sales.crm:object/deal]', () => {
+    expect(parsePath('/by-ontology/sales.crm:object/deal')).toEqual({
+      mount: 'by-ontology',
+      args: ['sales.crm:object/deal']
     })
   })
 
-  it('/graph/knowledge.outreach-playbook/governed-by → mount:graph args:[knowledge.outreach-playbook,governed-by]', () => {
-    expect(parsePath('/graph/knowledge.outreach-playbook/governed-by')).toEqual({
-      mount: 'graph',
-      args: ['knowledge.outreach-playbook', 'governed-by']
-    })
-  })
-
-  it('/<nodeId> single segment → mount:node args:[nodeId]', () => {
-    expect(parsePath('/knowledge.outreach-playbook')).toEqual({
-      mount: 'node',
-      args: ['knowledge.outreach-playbook']
-    })
-  })
-
-  it('trailing slash is stripped before parsing', () => {
-    expect(parsePath('/by-kind/playbook/')).toEqual({ mount: 'by-kind', args: ['playbook'] })
-  })
-})
-
-// ---------------------------------------------------------------------------
-// parsePath — invalid inputs (5+)
-// ---------------------------------------------------------------------------
-
-describe('parsePath — invalid inputs', () => {
-  it('throws on empty string', () => {
-    expect(() => parsePath('')).toThrow('parsePath: path must be a non-empty string')
-  })
-
-  it('throws when path does not start with /', () => {
-    expect(() => parsePath('by-kind/playbook')).toThrow('parsePath: path must start with "/"')
-  })
-
-  it('throws on bare root path "/"', () => {
-    expect(() => parsePath('/')).toThrow('parsePath: path resolves to root with no mount')
-  })
-
-  it('throws on /by-system with no systemId argument', () => {
-    expect(() => parsePath('/by-system')).toThrow('/by-system requires a systemId argument')
-  })
-
-  it('throws on /by-kind with no kind argument', () => {
-    expect(() => parsePath('/by-kind')).toThrow('/by-kind requires a kind argument')
-  })
-
-  it('throws on /by-owner with no ownerId argument', () => {
-    expect(() => parsePath('/by-owner')).toThrow('/by-owner requires an ownerId argument')
-  })
-
-  it('throws on /graph with only nodeId (missing verb)', () => {
-    expect(() => parsePath('/graph/knowledge.outreach-playbook')).toThrow('/graph requires <nodeId>/<verb>')
-  })
-
-  it('throws on /graph/<nodeId>/<unknown-verb>', () => {
-    expect(() => parsePath('/graph/knowledge.outreach-playbook/list')).toThrow(
-      'verb must be "governs" or "governed-by"'
-    )
-  })
-
-  it('throws on multi-segment path with unrecognized first segment', () => {
-    expect(() => parsePath('/unknown-mount/some-arg')).toThrow('unrecognized path pattern')
-  })
-})
-
-// ---------------------------------------------------------------------------
-// parsePath — edge cases
-// ---------------------------------------------------------------------------
-
-describe('parsePath edge cases', () => {
-  // Whitespace handling — the parser does NOT trim the incoming string.
-  // A path with leading whitespace does not start with '/' so it throws.
-  it('throws on path with leading whitespace', () => {
-    expect(() => parsePath(' /by-kind/playbook')).toThrow('parsePath: path must start with "/"')
-  })
-
-  // Trailing whitespace becomes part of the last segment (not stripped).
-  // The segment is non-empty so parsing proceeds and the whitespace is
-  // included verbatim in the returned arg.
-  it('preserves trailing whitespace inside the last segment', () => {
-    const result = parsePath('/by-kind/playbook ')
-    expect(result.mount).toBe('by-kind')
-    expect(result.args[0]).toBe('playbook ')
-  })
-
-  // Multiple trailing slashes are all stripped (regex /\/+$/).
-  it('strips multiple trailing slashes', () => {
-    expect(parsePath('/by-kind/playbook///')).toEqual({ mount: 'by-kind', args: ['playbook'] })
-  })
-
-  // Lone-slash variants — a path of only slashes normalises to an empty
-  // segments list and must throw the root-with-no-mount error.
-  it('throws on path consisting only of slashes', () => {
-    expect(() => parsePath('///')).toThrow('parsePath: path resolves to root with no mount')
-  })
-
-  // Case sensitivity — parsePath does not normalise case.
-  // 'Playbook' (capitalised) is passed through as-is to the caller.
-  it('preserves node-id case (no case normalisation)', () => {
-    // /by-kind takes rest[0] verbatim
-    const result = parsePath('/by-kind/Playbook')
-    expect(result.args[0]).toBe('Playbook')
-  })
-
-  // system id: dot notation passes through unchanged.
-  it('/by-system/sales.crm preserves dot notation', () => {
-    expect(parsePath('/by-system/sales.crm')).toEqual({ mount: 'by-system', args: ['sales.crm'] })
-  })
-
-  // system id: slash notation joins rest segments with '/'.
-  // The parser does NOT convert slashes to dots — the caller must normalise.
-  it('/by-system/sales/crm joins segments with slash (no dot conversion)', () => {
-    const result = parsePath('/by-system/sales/crm')
-    expect(result.mount).toBe('by-system')
-    // args[0] is 'sales/crm', NOT 'sales.crm'
-    expect(result.args[0]).toBe('sales/crm')
-  })
-
-  // /by-kind silently ignores extra path segments beyond the kind argument.
-  it('/by-kind/playbook/extra silently uses only first kind segment', () => {
-    // First segment after 'by-kind' is taken; extra is ignored.
-    const result = parsePath('/by-kind/playbook/extra')
-    expect(result.mount).toBe('by-kind')
-    expect(result.args[0]).toBe('playbook')
-    expect(result.args).toHaveLength(1)
-  })
-
-  // /by-owner joins rest with '/' (same behaviour as /by-system).
-  it('/by-owner/role.ops-lead/sub joins segments with slash', () => {
-    const result = parsePath('/by-owner/role.ops-lead/sub')
-    expect(result.mount).toBe('by-owner')
-    expect(result.args[0]).toBe('role.ops-lead/sub')
-  })
-
-  // Graph node ID may contain a colon prefix (e.g. knowledge:knowledge.foo).
-  // The parser accepts it — the rest before the verb is joined with '/'.
-  it('/graph/<prefixed-nodeId>/governs round-trips the prefixed id', () => {
-    const result = parsePath('/graph/knowledge:knowledge.test-node/governs')
-    expect(result.mount).toBe('graph')
-    expect(result.args[0]).toBe('knowledge:knowledge.test-node')
-    expect(result.args[1]).toBe('governs')
-  })
-
-  // /graph with no arguments at all (just '/graph').
-  it('throws on /graph with no nodeId or verb', () => {
-    expect(() => parsePath('/graph')).toThrow('/graph requires <nodeId>/<verb>')
-  })
-
-  // /node mount — single-segment path works for any non-reserved first segment.
-  it('single-segment non-reserved path is treated as node mount', () => {
-    expect(parsePath('/knowledge.my-doc')).toEqual({ mount: 'node', args: ['knowledge.my-doc'] })
-  })
-})
-
-// ---------------------------------------------------------------------------
-// formatText
-// ---------------------------------------------------------------------------
-
-describe('formatText', () => {
-  it('returns "(no results)" for empty array', () => {
-    expect(formatText([])).toBe('(no results)')
-  })
-
-  it('includes header row with KIND and ID columns', () => {
-    const output = formatText([NODES[0]])
-    expect(output).toContain('KIND')
-    expect(output).toContain('ID')
-    expect(output).toContain('TITLE')
-  })
-
-  it('includes node id and title in output', () => {
-    const output = formatText([NODES[0]])
-    expect(output).toContain('knowledge.playbook-a')
-    expect(output).toContain('Playbook A')
-  })
-
-  it('truncates long summaries', () => {
-    const longSummary = 'x'.repeat(200)
-    const node: OrgKnowledgeNode = { ...NODES[0], summary: longSummary }
-    const output = formatText([node])
-    expect(output).toContain('...')
-  })
-})
-
-// ---------------------------------------------------------------------------
-// formatJson — envelope shape
-// ---------------------------------------------------------------------------
-
-describe('formatJson', () => {
-  it('returns a JSON string with top-level keys: path, mount, args, results', () => {
-    const raw = formatJson({
-      path: '/by-kind/playbook',
-      parsed: { mount: 'by-kind', args: ['playbook'] },
-      results: [NODES[0]]
-    })
-    const parsed = JSON.parse(raw) as Record<string, unknown>
-    expect(Object.keys(parsed).sort()).toEqual(['args', 'mount', 'path', 'results'].sort())
-  })
-
-  it('preserves path in envelope', () => {
-    const raw = formatJson({
-      path: '/by-kind/playbook',
-      parsed: { mount: 'by-kind', args: ['playbook'] },
-      results: []
-    })
-    expect(JSON.parse(raw)).toMatchObject({ path: '/by-kind/playbook' })
-  })
-
-  it('preserves mount in envelope', () => {
-    const raw = formatJson({
-      path: '/by-kind/strategy',
-      parsed: { mount: 'by-kind', args: ['strategy'] },
-      results: []
-    })
-    expect(JSON.parse(raw)).toMatchObject({ mount: 'by-kind' })
-  })
-
-  it('preserves args array in envelope', () => {
-    const raw = formatJson({
-      path: '/by-system/sales.crm',
-      parsed: { mount: 'by-system', args: ['sales.crm'] },
-      results: []
-    })
-    expect(JSON.parse(raw)).toMatchObject({ args: ['sales.crm'] })
-  })
-
-  it('includes results in envelope for string[] (governs/governedBy)', () => {
-    const raw = formatJson({
-      path: '/graph/knowledge.playbook-a/governs',
-      parsed: { mount: 'graph', args: ['knowledge.playbook-a', 'governs'] },
-      results: ['system:sales.crm', 'system:sales.lead-gen']
-    })
-    const parsed = JSON.parse(raw) as { results: string[] }
-    expect(parsed.results).toEqual(['system:sales.crm', 'system:sales.lead-gen'])
-  })
-
-  it('envelope is NOT flat { results } — must have path/mount/args siblings', () => {
-    const raw = formatJson({
-      path: '/by-kind/playbook',
-      parsed: { mount: 'by-kind', args: ['playbook'] },
-      results: [NODES[0]]
-    })
-    const parsed = JSON.parse(raw) as Record<string, unknown>
-    // Must NOT be flat (only results key)
-    expect(parsed).toHaveProperty('path')
-    expect(parsed).toHaveProperty('mount')
-    expect(parsed).toHaveProperty('args')
-    expect(parsed).toHaveProperty('results')
-  })
-})
-
-// ---------------------------------------------------------------------------
-// formatIdsOnly
-// ---------------------------------------------------------------------------
-
-describe('formatIdsOnly', () => {
-  it('returns empty string for empty array', () => {
-    expect(formatIdsOnly([])).toBe('')
-  })
-
-  it('returns newline-separated ids for OrgKnowledgeNode array', () => {
-    const output = formatIdsOnly([NODES[0], NODES[1]])
-    const lines = output.split('\n')
-    expect(lines).toContain('knowledge.playbook-a')
-    expect(lines).toContain('knowledge.strategy-b')
-  })
-
-  it('returns newline-separated strings for string[] (governs results)', () => {
-    const output = formatIdsOnly(['system:sales.crm', 'system:sales.lead-gen'])
-    expect(output).toBe('system:sales.crm\nsystem:sales.lead-gen')
-  })
-})
+  it('/graph/knowledge.outreach-playbook/governs → mount:graph args:[knowledge.outreach-playbook,governs]', () => {
+    expect(parsePath('/graph/knowledge.outreach-playbook/governs')).toEqual({
+      mount: 'graph',
+      args: ['knowledge.outreach-playbook', 'governs']
+    })
+  })
+
+  it('/graph/knowledge.outreach-playbook/governed-by → mount:graph args:[knowledge.outreach-playbook,governed-by]', () => {
+    expect(parsePath('/graph/knowledge.outreach-playbook/governed-by')).toEqual({
+      mount: 'graph',
+      args: ['knowledge.outreach-playbook', 'governed-by']
+    })
+  })
+
+  it('/<nodeId> single segment → mount:node args:[nodeId]', () => {
+    expect(parsePath('/knowledge.outreach-playbook')).toEqual({
+      mount: 'node',
+      args: ['knowledge.outreach-playbook']
+    })
+  })
+
+  it('trailing slash is stripped before parsing', () => {
+    expect(parsePath('/by-kind/playbook/')).toEqual({ mount: 'by-kind', args: ['playbook'] })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// parsePath — invalid inputs (5+)
+// ---------------------------------------------------------------------------
+
+describe('parsePath — invalid inputs', () => {
+  it('throws on empty string', () => {
+    expect(() => parsePath('')).toThrow('parsePath: path must be a non-empty string')
+  })
+
+  it('throws when path does not start with /', () => {
+    expect(() => parsePath('by-kind/playbook')).toThrow('parsePath: path must start with "/"')
+  })
+
+  it('throws on bare root path "/"', () => {
+    expect(() => parsePath('/')).toThrow('parsePath: path resolves to root with no mount')
+  })
+
+  it('throws on /by-system with no systemId argument', () => {
+    expect(() => parsePath('/by-system')).toThrow('/by-system requires a systemId argument')
+  })
+
+  it('throws on /by-kind with no kind argument', () => {
+    expect(() => parsePath('/by-kind')).toThrow('/by-kind requires a kind argument')
+  })
+
+  it('throws on /by-owner with no ownerId argument', () => {
+    expect(() => parsePath('/by-owner')).toThrow('/by-owner requires an ownerId argument')
+  })
+
+  it('throws on /graph with only nodeId (missing verb)', () => {
+    expect(() => parsePath('/graph/knowledge.outreach-playbook')).toThrow('/graph requires <nodeId>/<verb>')
+  })
+
+  it('throws on /graph/<nodeId>/<unknown-verb>', () => {
+    expect(() => parsePath('/graph/knowledge.outreach-playbook/list')).toThrow(
+      'verb must be "governs" or "governed-by"'
+    )
+  })
+
+  it('throws on multi-segment path with unrecognized first segment', () => {
+    expect(() => parsePath('/unknown-mount/some-arg')).toThrow('unrecognized path pattern')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// parsePath — edge cases
+// ---------------------------------------------------------------------------
+
+describe('parsePath edge cases', () => {
+  // Whitespace handling — the parser does NOT trim the incoming string.
+  // A path with leading whitespace does not start with '/' so it throws.
+  it('throws on path with leading whitespace', () => {
+    expect(() => parsePath(' /by-kind/playbook')).toThrow('parsePath: path must start with "/"')
+  })
+
+  // Trailing whitespace becomes part of the last segment (not stripped).
+  // The segment is non-empty so parsing proceeds and the whitespace is
+  // included verbatim in the returned arg.
+  it('preserves trailing whitespace inside the last segment', () => {
+    const result = parsePath('/by-kind/playbook ')
+    expect(result.mount).toBe('by-kind')
+    expect(result.args[0]).toBe('playbook ')
+  })
+
+  // Multiple trailing slashes are all stripped (regex /\/+$/).
+  it('strips multiple trailing slashes', () => {
+    expect(parsePath('/by-kind/playbook///')).toEqual({ mount: 'by-kind', args: ['playbook'] })
+  })
+
+  // Lone-slash variants — a path of only slashes normalises to an empty
+  // segments list and must throw the root-with-no-mount error.
+  it('throws on path consisting only of slashes', () => {
+    expect(() => parsePath('///')).toThrow('parsePath: path resolves to root with no mount')
+  })
+
+  // Case sensitivity — parsePath does not normalise case.
+  // 'Playbook' (capitalised) is passed through as-is to the caller.
+  it('preserves node-id case (no case normalisation)', () => {
+    // /by-kind takes rest[0] verbatim
+    const result = parsePath('/by-kind/Playbook')
+    expect(result.args[0]).toBe('Playbook')
+  })
+
+  // system id: dot notation passes through unchanged.
+  it('/by-system/sales.crm preserves dot notation', () => {
+    expect(parsePath('/by-system/sales.crm')).toEqual({ mount: 'by-system', args: ['sales.crm'] })
+  })
+
+  // system id: slash notation joins rest segments with '/'.
+  // The parser does NOT convert slashes to dots — the caller must normalise.
+  it('/by-system/sales/crm joins segments with slash (no dot conversion)', () => {
+    const result = parsePath('/by-system/sales/crm')
+    expect(result.mount).toBe('by-system')
+    // args[0] is 'sales/crm', NOT 'sales.crm'
+    expect(result.args[0]).toBe('sales/crm')
+  })
+
+  // /by-kind silently ignores extra path segments beyond the kind argument.
+  it('/by-kind/playbook/extra silently uses only first kind segment', () => {
+    // First segment after 'by-kind' is taken; extra is ignored.
+    const result = parsePath('/by-kind/playbook/extra')
+    expect(result.mount).toBe('by-kind')
+    expect(result.args[0]).toBe('playbook')
+    expect(result.args).toHaveLength(1)
+  })
+
+  // /by-owner joins rest with '/' (same behaviour as /by-system).
+  it('/by-owner/role.ops-lead/sub joins segments with slash', () => {
+    const result = parsePath('/by-owner/role.ops-lead/sub')
+    expect(result.mount).toBe('by-owner')
+    expect(result.args[0]).toBe('role.ops-lead/sub')
+  })
+
+  // Graph node ID may contain a colon prefix (e.g. knowledge:knowledge.foo).
+  // The parser accepts it — the rest before the verb is joined with '/'.
+  it('/graph/<prefixed-nodeId>/governs round-trips the prefixed id', () => {
+    const result = parsePath('/graph/knowledge:knowledge.test-node/governs')
+    expect(result.mount).toBe('graph')
+    expect(result.args[0]).toBe('knowledge:knowledge.test-node')
+    expect(result.args[1]).toBe('governs')
+  })
+
+  // /graph with no arguments at all (just '/graph').
+  it('throws on /graph with no nodeId or verb', () => {
+    expect(() => parsePath('/graph')).toThrow('/graph requires <nodeId>/<verb>')
+  })
+
+  // /node mount — single-segment path works for any non-reserved first segment.
+  it('single-segment non-reserved path is treated as node mount', () => {
+    expect(parsePath('/knowledge.my-doc')).toEqual({ mount: 'node', args: ['knowledge.my-doc'] })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// formatText
+// ---------------------------------------------------------------------------
+
+describe('formatText', () => {
+  it('returns "(no results)" for empty array', () => {
+    expect(formatText([])).toBe('(no results)')
+  })
+
+  it('includes header row with KIND and ID columns', () => {
+    const output = formatText([NODES[0]])
+    expect(output).toContain('KIND')
+    expect(output).toContain('ID')
+    expect(output).toContain('TITLE')
+  })
+
+  it('includes node id and title in output', () => {
+    const output = formatText([NODES[0]])
+    expect(output).toContain('knowledge.playbook-a')
+    expect(output).toContain('Playbook A')
+  })
+
+  it('truncates long summaries', () => {
+    const longSummary = 'x'.repeat(200)
+    const node: OrgKnowledgeNode = { ...NODES[0], summary: longSummary }
+    const output = formatText([node])
+    expect(output).toContain('...')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// formatJson — envelope shape
+// ---------------------------------------------------------------------------
+
+describe('formatJson', () => {
+  it('returns a JSON string with top-level keys: path, mount, args, results', () => {
+    const raw = formatJson({
+      path: '/by-kind/playbook',
+      parsed: { mount: 'by-kind', args: ['playbook'] },
+      results: [NODES[0]]
+    })
+    const parsed = JSON.parse(raw) as Record<string, unknown>
+    expect(Object.keys(parsed).sort()).toEqual(['args', 'mount', 'path', 'results'].sort())
+  })
+
+  it('preserves path in envelope', () => {
+    const raw = formatJson({
+      path: '/by-kind/playbook',
+      parsed: { mount: 'by-kind', args: ['playbook'] },
+      results: []
+    })
+    expect(JSON.parse(raw)).toMatchObject({ path: '/by-kind/playbook' })
+  })
+
+  it('preserves mount in envelope', () => {
+    const raw = formatJson({
+      path: '/by-kind/strategy',
+      parsed: { mount: 'by-kind', args: ['strategy'] },
+      results: []
+    })
+    expect(JSON.parse(raw)).toMatchObject({ mount: 'by-kind' })
+  })
+
+  it('preserves args array in envelope', () => {
+    const raw = formatJson({
+      path: '/by-system/sales.crm',
+      parsed: { mount: 'by-system', args: ['sales.crm'] },
+      results: []
+    })
+    expect(JSON.parse(raw)).toMatchObject({ args: ['sales.crm'] })
+  })
+
+  it('includes results in envelope for string[] (governs/governedBy)', () => {
+    const raw = formatJson({
+      path: '/graph/knowledge.playbook-a/governs',
+      parsed: { mount: 'graph', args: ['knowledge.playbook-a', 'governs'] },
+      results: ['system:sales.crm', 'system:sales.lead-gen']
+    })
+    const parsed = JSON.parse(raw) as { results: string[] }
+    expect(parsed.results).toEqual(['system:sales.crm', 'system:sales.lead-gen'])
+  })
+
+  it('envelope is NOT flat { results } — must have path/mount/args siblings', () => {
+    const raw = formatJson({
+      path: '/by-kind/playbook',
+      parsed: { mount: 'by-kind', args: ['playbook'] },
+      results: [NODES[0]]
+    })
+    const parsed = JSON.parse(raw) as Record<string, unknown>
+    // Must NOT be flat (only results key)
+    expect(parsed).toHaveProperty('path')
+    expect(parsed).toHaveProperty('mount')
+    expect(parsed).toHaveProperty('args')
+    expect(parsed).toHaveProperty('results')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// formatIdsOnly
+// ---------------------------------------------------------------------------
+
+describe('formatIdsOnly', () => {
+  it('returns empty string for empty array', () => {
+    expect(formatIdsOnly([])).toBe('')
+  })
+
+  it('returns newline-separated ids for OrgKnowledgeNode array', () => {
+    const output = formatIdsOnly([NODES[0], NODES[1]])
+    const lines = output.split('\n')
+    expect(lines).toContain('knowledge.playbook-a')
+    expect(lines).toContain('knowledge.strategy-b')
+  })
+
+  it('returns newline-separated strings for string[] (governs results)', () => {
+    const output = formatIdsOnly(['system:sales.crm', 'system:sales.lead-gen'])
+    expect(output).toBe('system:sales.crm\nsystem:sales.lead-gen')
+  })
+})