@elevasis/core 0.22.0 → 0.24.0

package/src/knowledge/queries.ts

@@ -1,53 +1,100 @@
-import type { OrganizationGraph } from '../organization-model/graph/types'
+import type { OrganizationGraph } from '../organization-model/graph/types'
 import type { OrgKnowledgeKind, OrgKnowledgeNode } from '../organization-model/domains/knowledge'
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Graph node ID prefix for knowledge nodes.
- * Graph node IDs follow the convention: `knowledge:<om-node-id>`
- * e.g. `knowledge:knowledge.outreach-playbook`
- */
+import { OntologyIdSchema, ontologyGraphNodeId } from '../organization-model/ontology'
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Graph node ID prefix for knowledge nodes.
+ * Graph node IDs follow the convention: `knowledge:<om-node-id>`
+ * e.g. `knowledge:knowledge.outreach-playbook`
+ */
 function toGraphNodeId(omNodeId: string): string {
   return `knowledge:${omNodeId}`
 }
 
-/**
- * Resolve the sourceId of every knowledge node in the graph, keyed by graph
- * node ID.  The `sourceId` on a knowledge graph node is the OM node id
- * (e.g. `knowledge.outreach-playbook`).
- */
-function buildKnowledgeSourceIdMap(graph: OrganizationGraph): Map<string, string> {
-  const map = new Map<string, string>()
-  for (const node of graph.nodes) {
-    if (node.kind === 'knowledge' && node.sourceId) {
-      map.set(node.id, node.sourceId)
-    }
+function toTargetGraphNodeId(nodeId: string): string {
+  if (
+    nodeId.startsWith('system:') ||
+    nodeId.startsWith('knowledge:') ||
+    nodeId.startsWith('resource:') ||
+    nodeId.startsWith('content-node:') ||
+    nodeId.startsWith('ontology:')
+  ) {
+    return nodeId
   }
-  return map
-}
 
-// ---------------------------------------------------------------------------
-// Query functions
-// ---------------------------------------------------------------------------
+  const ontologyId = OntologyIdSchema.safeParse(nodeId)
+  if (ontologyId.success) {
+    return ontologyGraphNodeId(ontologyId.data)
+  }
 
-/**
- * Returns all knowledge nodes whose `governs` edges point to the given
- * featureId (graph node ID: `feature:<featureId>`).
- *
- * @param graph   - The built OrganizationGraph.
- * @param featureId - The dotted feature id (e.g. `sales.crm`).
- */
-export function byFeature(
+  return `system:${nodeId}`
+}
+
+/**
+ * Resolve the sourceId of every knowledge node in the graph, keyed by graph
+ * node ID.  The `sourceId` on a knowledge graph node is the OM node id
+ * (e.g. `knowledge.outreach-playbook`).
+ */
+function buildKnowledgeSourceIdMap(graph: OrganizationGraph): Map<string, string> {
+  const map = new Map<string, string>()
+  for (const node of graph.nodes) {
+    if (node.kind === 'knowledge' && node.sourceId) {
+      map.set(node.id, node.sourceId)
+    }
+  }
+  return map
+}
+
+// ---------------------------------------------------------------------------
+// Query functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns all knowledge nodes whose `governs` edges point to the given
+ * systemId (graph node ID: `system:<systemId>`).
+ *
+ * @param graph   - The built OrganizationGraph.
+ * @param systemId - The dotted system id (e.g. `sales.crm`).
+ */
+export function bySystem(
+  graph: OrganizationGraph,
+  systemId: string,
+  knowledgeNodes: OrgKnowledgeNode[]
+): OrgKnowledgeNode[] {
+  const targetGraphNodeId = `system:${systemId}`
+
+  // Find all knowledge graph node IDs that have a `governs` edge to the target
+  const governingKnowledgeNodeIds = new Set<string>()
+  for (const edge of graph.edges) {
+    if (edge.kind === 'governs' && edge.targetId === targetGraphNodeId && edge.sourceId.startsWith('knowledge:')) {
+      governingKnowledgeNodeIds.add(edge.sourceId)
+    }
+  }
+
+  // Build a lookup from graph-node-id -> OM sourceId
+  const sourceIdMap = buildKnowledgeSourceIdMap(graph)
+
+  // Collect the OM node ids that correspond to those graph nodes
+  const matchingOmIds = new Set<string>()
+  for (const graphNodeId of governingKnowledgeNodeIds) {
+    const omId = sourceIdMap.get(graphNodeId)
+    if (omId) matchingOmIds.add(omId)
+  }
+
+  return knowledgeNodes.filter((n) => matchingOmIds.has(n.id))
+}
+
+export function byOntology(
   graph: OrganizationGraph,
-  featureId: string,
+  ontologyId: string,
   knowledgeNodes: OrgKnowledgeNode[]
 ): OrgKnowledgeNode[] {
-  const targetGraphNodeId = `feature:${featureId}`
+  const targetGraphNodeId = toTargetGraphNodeId(ontologyId)
 
-  // Find all knowledge graph node IDs that have a `governs` edge to the target
   const governingKnowledgeNodeIds = new Set<string>()
   for (const edge of graph.edges) {
     if (edge.kind === 'governs' && edge.targetId === targetGraphNodeId && edge.sourceId.startsWith('knowledge:')) {
@@ -55,10 +102,7 @@ export function byFeature(
     }
   }
 
-  // Build a lookup from graph-node-id -> OM sourceId
   const sourceIdMap = buildKnowledgeSourceIdMap(graph)
-
-  // Collect the OM node ids that correspond to those graph nodes
   const matchingOmIds = new Set<string>()
   for (const graphNodeId of governingKnowledgeNodeIds) {
     const omId = sourceIdMap.get(graphNodeId)
@@ -67,190 +111,198 @@ export function byFeature(
 
   return knowledgeNodes.filter((n) => matchingOmIds.has(n.id))
 }
-
-/**
- * Returns all knowledge nodes whose `kind` matches the given kind.
- *
- * @param graph          - The built OrganizationGraph (unused structurally; kept for API symmetry).
- * @param kind           - The knowledge kind (`'playbook' | 'strategy' | 'reference'`).
- * @param knowledgeNodes - Flat array of OrgKnowledgeNode from the OrganizationModel.
- */
-export function byKind(
-  _graph: OrganizationGraph,
-  kind: OrgKnowledgeKind,
-  knowledgeNodes: OrgKnowledgeNode[]
-): OrgKnowledgeNode[] {
-  return knowledgeNodes.filter((n) => n.kind === kind)
-}
-
-/**
- * Returns all knowledge nodes where `ownerIds` includes the given `ownerId`.
- *
- * @param _graph         - The built OrganizationGraph (unused; kept for API symmetry).
- * @param ownerId        - The owner id string (matches values in `node.ownerIds`).
- * @param knowledgeNodes - Flat array of OrgKnowledgeNode from the OrganizationModel.
- */
-export function byOwner(
-  _graph: OrganizationGraph,
-  ownerId: string,
-  knowledgeNodes: OrgKnowledgeNode[]
-): OrgKnowledgeNode[] {
-  return knowledgeNodes.filter((n) => n.ownerIds.includes(ownerId))
-}
-
-/**
- * Returns the IDs of the graph nodes that the given knowledge node governs
- * (outgoing `governs` edges from the knowledge graph node).
- *
- * The graph node ID for a knowledge OM node with id `X` is `knowledge:X`.
- *
- * @param graph    - The built OrganizationGraph.
- * @param nodeId   - The OM knowledge node id (e.g. `knowledge.outreach-playbook`).
- *                   Also accepts the graph node ID format (`knowledge:knowledge.outreach-playbook`).
- * @returns Array of target graph node IDs (e.g. `['feature:sales.crm', ...]`).
- */
-export function governs(graph: OrganizationGraph, nodeId: string): string[] {
-  const graphNodeId = nodeId.startsWith('knowledge:') ? nodeId : toGraphNodeId(nodeId)
-
-  const results: string[] = []
-  for (const edge of graph.edges) {
-    if (edge.kind === 'governs' && edge.sourceId === graphNodeId) {
-      results.push(edge.targetId)
-    }
-  }
-  return results
-}
-
-/**
- * Returns the IDs of the knowledge graph nodes that govern the given node
- * (incoming `governs` edges pointing to `nodeId`).
- *
- * @param graph   - The built OrganizationGraph.
- * @param nodeId  - The target graph node ID (e.g. `feature:sales.crm`) or a
- *                  bare feature id (e.g. `sales.crm` — will be prefixed with `feature:`).
- * @returns Array of source graph node IDs (e.g. `['knowledge:knowledge.outreach-playbook', ...]`).
- */
+
+/**
+ * Returns all knowledge nodes whose `kind` matches the given kind.
+ *
+ * @param graph          - The built OrganizationGraph (unused structurally; kept for API symmetry).
+ * @param kind           - The knowledge kind (`'playbook' | 'strategy' | 'reference'`).
+ * @param knowledgeNodes - Flat array of OrgKnowledgeNode from the OrganizationModel.
+ */
+export function byKind(
+  _graph: OrganizationGraph,
+  kind: OrgKnowledgeKind,
+  knowledgeNodes: OrgKnowledgeNode[]
+): OrgKnowledgeNode[] {
+  return knowledgeNodes.filter((n) => n.kind === kind)
+}
+
+/**
+ * Returns all knowledge nodes where `ownerIds` includes the given `ownerId`.
+ *
+ * @param _graph         - The built OrganizationGraph (unused; kept for API symmetry).
+ * @param ownerId        - The owner id string (matches values in `node.ownerIds`).
+ * @param knowledgeNodes - Flat array of OrgKnowledgeNode from the OrganizationModel.
+ */
+export function byOwner(
+  _graph: OrganizationGraph,
+  ownerId: string,
+  knowledgeNodes: OrgKnowledgeNode[]
+): OrgKnowledgeNode[] {
+  return knowledgeNodes.filter((n) => n.ownerIds.includes(ownerId))
+}
+
+/**
+ * Returns the IDs of the graph nodes that the given knowledge node governs
+ * (outgoing `governs` edges from the knowledge graph node).
+ *
+ * The graph node ID for a knowledge OM node with id `X` is `knowledge:X`.
+ *
+ * @param graph    - The built OrganizationGraph.
+ * @param nodeId   - The OM knowledge node id (e.g. `knowledge.outreach-playbook`).
+ *                   Also accepts the graph node ID format (`knowledge:knowledge.outreach-playbook`).
+ * @returns Array of target graph node IDs (e.g. `['system:sales.crm', ...]`).
+ */
+export function governs(graph: OrganizationGraph, nodeId: string): string[] {
+  const graphNodeId = nodeId.startsWith('knowledge:') ? nodeId : toGraphNodeId(nodeId)
+
+  const results: string[] = []
+  for (const edge of graph.edges) {
+    if (edge.kind === 'governs' && edge.sourceId === graphNodeId) {
+      results.push(edge.targetId)
+    }
+  }
+  return results
+}
+
+/**
+ * Returns the IDs of the knowledge graph nodes that govern the given node
+ * (incoming `governs` edges pointing to `nodeId`).
+ *
+ * @param graph   - The built OrganizationGraph.
+ * @param nodeId  - The target graph node ID (e.g. `system:sales.crm`) or a
+ *                  bare system id (e.g. `sales.crm` — will be prefixed with `system:`).
+ * @returns Array of source graph node IDs (e.g. `['knowledge:knowledge.outreach-playbook', ...]`).
+ */
 export function governedBy(graph: OrganizationGraph, nodeId: string): string[] {
-  // Accept both `feature:sales.crm` and bare `sales.crm`
-  const targetId =
-    nodeId.startsWith('feature:') || nodeId.startsWith('knowledge:') || nodeId.startsWith('resource:')
-      ? nodeId
-      : `feature:${nodeId}`
-
-  const results: string[] = []
-  for (const edge of graph.edges) {
-    if (edge.kind === 'governs' && edge.targetId === targetId) {
-      results.push(edge.sourceId)
-    }
+  // Accept prefixed graph IDs, bare system IDs, and bare ontology IDs.
+  const targetId = toTargetGraphNodeId(nodeId)
+
+  const results: string[] = []
+  for (const edge of graph.edges) {
+    if (edge.kind === 'governs' && edge.targetId === targetId) {
+      results.push(edge.sourceId)
+    }
+  }
+  return results
+}
+
+// ---------------------------------------------------------------------------
+// Path parser
+// ---------------------------------------------------------------------------
+
+/** The recognized mount axes for Knowledge Map paths. */
+export type KnowledgeMount = 'by-system' | 'by-ontology' | 'by-kind' | 'by-owner' | 'graph' | 'node'
+
+/**
+ * The result of parsing a Knowledge Map path string.
+ *
+ * Shape: `{ mount: KnowledgeMount, args: string[] }`
+ *
+ * Per-mount arg arrays:
+ * - `by-system`:  `[systemId]`   (e.g. `['sales.crm']`)
+ * - `by-ontology`:`[ontologyId]` (e.g. `['sales.crm:object/deal']`)
+ * - `by-kind`:    `[kind]`       (e.g. `['playbook']`)
+ * - `by-owner`:   `[ownerId]`    (e.g. `['role.ops-lead']`)
+ * - `graph`:      `[nodeId, verb]` where verb is `'governs'` or `'governed-by'`
+ * - `node`:       `[nodeId]`     (single node lookup, no sub-path)
+ */
+export interface ParsedKnowledgePath {
+  mount: KnowledgeMount
+  args: string[]
+}
+
+/**
+ * Parses a Knowledge Map path string into a `{ mount, args }` descriptor.
+ *
+ * Supported path patterns:
+ *   `/by-system/<systemId>`           -> `{ mount: 'by-system', args: ['<systemId>'] }`
+ *   `/by-ontology/<ontologyId>`       -> `{ mount: 'by-ontology', args: ['<ontologyId>'] }`
+ *   `/by-kind/<kind>`                 → `{ mount: 'by-kind',    args: ['<kind>'] }`
+ *   `/by-owner/<ownerId>`             → `{ mount: 'by-owner',   args: ['<ownerId>'] }`
+ *   `/graph/<nodeId>/governs`         → `{ mount: 'graph',      args: ['<nodeId>', 'governs'] }`
+ *   `/graph/<nodeId>/governed-by`     → `{ mount: 'graph',      args: ['<nodeId>', 'governed-by'] }`
+ *   `/<nodeId>`                       → `{ mount: 'node',       args: ['<nodeId>'] }`
+ *
+ * The path MUST start with `/`.  Trailing slashes are stripped before parsing.
+ *
+ * @throws {Error} If the path is empty, missing a leading slash, or does not
+ *   match any supported mount pattern.
+ */
+export function parsePath(pathString: string): ParsedKnowledgePath {
+  if (!pathString || typeof pathString !== 'string') {
+    throw new Error('parsePath: path must be a non-empty string')
+  }
+
+  if (!pathString.startsWith('/')) {
+    throw new Error(`parsePath: path must start with "/", got: "${pathString}"`)
+  }
+
+  // Strip trailing slashes then split
+  const normalized = pathString.replace(/\/+$/, '')
+  const segments = normalized.split('/').filter((s) => s.length > 0)
+
+  if (segments.length === 0) {
+    throw new Error(`parsePath: path resolves to root with no mount: "${pathString}"`)
+  }
+
+  const [first, ...rest] = segments
+
+  // /by-system/<systemId>
+  if (first === 'by-system') {
+    if (rest.length === 0) {
+      throw new Error(`parsePath: /by-system requires a systemId argument, got: "${pathString}"`)
+    }
+    return { mount: 'by-system', args: [rest.join('/')] }
   }
-  return results
-}
 
-// ---------------------------------------------------------------------------
-// Path parser
-// ---------------------------------------------------------------------------
-
-/** The recognized mount axes for Knowledge Map paths. */
-export type KnowledgeMount = 'by-feature' | 'by-kind' | 'by-owner' | 'graph' | 'node'
-
-/**
- * The result of parsing a Knowledge Map path string.
- *
- * Shape: `{ mount: KnowledgeMount, args: string[] }`
- *
- * Per-mount arg arrays:
- * - `by-feature`: `[featureId]`  (e.g. `['sales.crm']`)
- * - `by-kind`:    `[kind]`       (e.g. `['playbook']`)
- * - `by-owner`:   `[ownerId]`    (e.g. `['role.ops-lead']`)
- * - `graph`:      `[nodeId, verb]` where verb is `'governs'` or `'governed-by'`
- * - `node`:       `[nodeId]`     (single node lookup, no sub-path)
- */
-export interface ParsedKnowledgePath {
-  mount: KnowledgeMount
-  args: string[]
-}
-
-/**
- * Parses a Knowledge Map path string into a `{ mount, args }` descriptor.
- *
- * Supported path patterns:
- *   `/by-feature/<featureId>`         → `{ mount: 'by-feature', args: ['<featureId>'] }`
- *   `/by-kind/<kind>`                 → `{ mount: 'by-kind',    args: ['<kind>'] }`
- *   `/by-owner/<ownerId>`             → `{ mount: 'by-owner',   args: ['<ownerId>'] }`
- *   `/graph/<nodeId>/governs`         → `{ mount: 'graph',      args: ['<nodeId>', 'governs'] }`
- *   `/graph/<nodeId>/governed-by`     → `{ mount: 'graph',      args: ['<nodeId>', 'governed-by'] }`
- *   `/<nodeId>`                       → `{ mount: 'node',       args: ['<nodeId>'] }`
- *
- * The path MUST start with `/`.  Trailing slashes are stripped before parsing.
- *
- * @throws {Error} If the path is empty, missing a leading slash, or does not
- *   match any supported mount pattern.
- */
-export function parsePath(pathString: string): ParsedKnowledgePath {
-  if (!pathString || typeof pathString !== 'string') {
-    throw new Error('parsePath: path must be a non-empty string')
-  }
-
-  if (!pathString.startsWith('/')) {
-    throw new Error(`parsePath: path must start with "/", got: "${pathString}"`)
-  }
-
-  // Strip trailing slashes then split
-  const normalized = pathString.replace(/\/+$/, '')
-  const segments = normalized.split('/').filter((s) => s.length > 0)
-
-  if (segments.length === 0) {
-    throw new Error(`parsePath: path resolves to root with no mount: "${pathString}"`)
-  }
-
-  const [first, ...rest] = segments
-
-  // /by-feature/<featureId>
-  if (first === 'by-feature') {
-    if (rest.length === 0) {
-      throw new Error(`parsePath: /by-feature requires a featureId argument, got: "${pathString}"`)
-    }
-    return { mount: 'by-feature', args: [rest.join('/')] }
-  }
-
-  // /by-kind/<kind>
-  if (first === 'by-kind') {
+  // /by-ontology/<ontologyId>
+  if (first === 'by-ontology') {
     if (rest.length === 0) {
-      throw new Error(`parsePath: /by-kind requires a kind argument, got: "${pathString}"`)
-    }
-    return { mount: 'by-kind', args: [rest[0]] }
-  }
-
-  // /by-owner/<ownerId>
-  if (first === 'by-owner') {
-    if (rest.length === 0) {
-      throw new Error(`parsePath: /by-owner requires an ownerId argument, got: "${pathString}"`)
-    }
-    return { mount: 'by-owner', args: [rest.join('/')] }
-  }
-
-  // /graph/<nodeId>/governs  or  /graph/<nodeId>/governed-by
-  if (first === 'graph') {
-    if (rest.length < 2) {
-      throw new Error(`parsePath: /graph requires <nodeId>/<verb> (governs|governed-by), got: "${pathString}"`)
+      throw new Error(`parsePath: /by-ontology requires an ontologyId argument, got: "${pathString}"`)
     }
-    const graphNodeId = rest.slice(0, -1).join('/')
-    const verb = rest[rest.length - 1]
-    if (verb !== 'governs' && verb !== 'governed-by') {
-      throw new Error(
-        `parsePath: /graph/<nodeId> verb must be "governs" or "governed-by", got: "${verb}" in "${pathString}"`
-      )
-    }
-    return { mount: 'graph', args: [graphNodeId, verb] }
+    return { mount: 'by-ontology', args: [rest.join('/')] }
   }
-
-  // /<nodeId>  (single node)
-  // first must not be a recognized mount prefix
-  if (segments.length === 1) {
-    return { mount: 'node', args: [first] }
-  }
-
-  throw new Error(
-    `parsePath: unrecognized path pattern "${pathString}". Supported: /by-feature/<id>, /by-kind/<kind>, /by-owner/<id>, /graph/<nodeId>/governs, /graph/<nodeId>/governed-by, /<nodeId>`
-  )
-}
+
+  // /by-kind/<kind>
+  if (first === 'by-kind') {
+    if (rest.length === 0) {
+      throw new Error(`parsePath: /by-kind requires a kind argument, got: "${pathString}"`)
+    }
+    return { mount: 'by-kind', args: [rest[0]] }
+  }
+
+  // /by-owner/<ownerId>
+  if (first === 'by-owner') {
+    if (rest.length === 0) {
+      throw new Error(`parsePath: /by-owner requires an ownerId argument, got: "${pathString}"`)
+    }
+    return { mount: 'by-owner', args: [rest.join('/')] }
+  }
+
+  // /graph/<nodeId>/governs  or  /graph/<nodeId>/governed-by
+  if (first === 'graph') {
+    if (rest.length < 2) {
+      throw new Error(`parsePath: /graph requires <nodeId>/<verb> (governs|governed-by), got: "${pathString}"`)
+    }
+    const graphNodeId = rest.slice(0, -1).join('/')
+    const verb = rest[rest.length - 1]
+    if (verb !== 'governs' && verb !== 'governed-by') {
+      throw new Error(
+        `parsePath: /graph/<nodeId> verb must be "governs" or "governed-by", got: "${verb}" in "${pathString}"`
+      )
+    }
+    return { mount: 'graph', args: [graphNodeId, verb] }
+  }
+
+  // /<nodeId>  (single node)
+  // first must not be a recognized mount prefix
+  if (segments.length === 1) {
+    return { mount: 'node', args: [first] }
+  }
+
+  throw new Error(
+    `parsePath: unrecognized path pattern "${pathString}". Supported: /by-system/<id>, /by-kind/<kind>, /by-owner/<id>, /graph/<nodeId>/governs, /graph/<nodeId>/governed-by, /<nodeId>`
+  )
+}
+