@elevasis/core 0.21.0 → 0.23.0

package/src/execution/engine/agent/core/__tests__/error-passthrough.test.ts

@@ -35,9 +35,10 @@ vi.mock('../../memory/processor', () => ({
 const mockAdapterFactory: LLMAdapterFactory = vi.fn() as unknown as LLMAdapterFactory
 
 const createTestAgent = (): Agent => {
-  const config: AgentConfig = {
-    type: 'agent',
-    resourceId: 'test-agent',
+  const config: AgentConfig = {
+    type: 'agent',
+    kind: 'utility',
+    resourceId: 'test-agent',
     name: 'Test Agent',
     description: 'Agent for error passthrough testing',
     environment: 'dev',

package/src/execution/engine/agent/core/types.ts

@@ -3,9 +3,10 @@
  * Types for autonomous agents with tools, memory, and constraints
  */
 
-import type { Contract, ExecutionContext } from '../../base/types'
-import type { ResourceDefinition } from '../../../../platform/registry/types'
-import { Tool } from '../../tools/types'
+import type { Contract, ExecutionContext } from '../../base/types'
+import type { ResourceDefinition } from '../../../../platform/registry/types'
+import type { AgentResourceEntry } from '../../../../organization-model/domains/resources'
+import { Tool } from '../../tools/types'
 import type { AgentMemory } from '../memory/types'
 import type { LLMAdapter } from '../../llm/types'
 import type { ModelConfig } from '../../llm/model-info'
@@ -27,17 +28,22 @@ export type { AgentMemory }
  * Uses `any` for optional params so both the real createLLMAdapter (with typed
  * AIUsageCollector/AICallContext) and the worker proxy (which ignores them) satisfy the type.
  */
-export type LLMAdapterFactory = (
-  config: ModelConfig,
-  ...args: any[]
-) => LLMAdapter
-
-// Agent configuration
-export interface AgentConfig extends ResourceDefinition {
-  type: 'agent'
-
-  // Agent behavior
-  systemPrompt: string // System prompt defining agent behavior
+export type LLMAdapterFactory = (
+  config: ModelConfig,
+  ...args: any[]
+) => LLMAdapter
+
+export type AgentKind = 'orchestrator' | 'specialist' | 'utility' | 'platform'
+
+// Agent configuration
+export interface AgentConfig extends ResourceDefinition {
+  type: 'agent'
+  /** OM descriptor backing canonical identity and governance metadata. */
+  resource?: AgentResourceEntry
+  kind: AgentKind
+
+  // Agent behavior
+  systemPrompt: string // System prompt defining agent behavior
 
   // Execution constraints (simplified for v1)
   constraints?: AgentConstraints
@@ -83,7 +89,11 @@ export interface AgentConfig extends ResourceDefinition {
   memoryPreferences?: string
 
   // Lifecycle callbacks for observability (optional) - DEFERRED
-}
+}
+
+export type DescriptorBackedAgentConfig = Omit<AgentConfig, 'resourceId' | 'type' | 'resource'> & {
+  resource: AgentResourceEntry
+}
 
 // Execution constraints to prevent runaway agents
 export interface AgentConstraints {

package/src/execution/engine/agent/index.ts

@@ -7,10 +7,12 @@
 export { Agent } from './core/agent'
 
 // Types
-export type {
-  AgentConfig,
-  AgentConstraints,
-  AgentDefinition,
+export type {
+  AgentKind,
+  AgentConfig,
+  DescriptorBackedAgentConfig,
+  AgentConstraints,
+  AgentDefinition,
   IterationContext,
   LLMAdapterFactory
 } from './core/types'

package/src/execution/engine/agent/reasoning/__tests__/request-builder.test.ts

@@ -8,9 +8,10 @@ import { z } from 'zod'
 describe('buildReasoningRequest', () => {
   // Helper: Create minimal iteration context
   const createMockContext = (overrides?: Partial<IterationContext>): IterationContext => {
-    const config: AgentConfig = {
-      type: 'agent',
-      resourceId: 'test-agent',
+    const config: AgentConfig = {
+      type: 'agent',
+      kind: 'utility',
+      resourceId: 'test-agent',
       name: 'Test Agent',
       description: 'Test agent',
       version: '1.0.0',
@@ -95,9 +96,10 @@ describe('buildReasoningRequest', () => {
 
     it('should set includeMessageAction to true when sessionCapable is true', () => {
       const context = createMockContext({
-        config: {
-          type: 'agent',
-          resourceId: 'test-agent',
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
           name: 'Test Agent',
           description: 'Test agent',
           version: '1.0.0',
@@ -113,9 +115,10 @@ describe('buildReasoningRequest', () => {
 
     it('should set includeMessageAction to false when sessionCapable is false', () => {
       const context = createMockContext({
-        config: {
-          type: 'agent',
-          resourceId: 'test-agent',
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
           name: 'Test Agent',
           description: 'Test agent',
           version: '1.0.0',
@@ -142,9 +145,10 @@ describe('buildReasoningRequest', () => {
 
     it('should include hardened security rules when sessionCapable is true', () => {
       const context = createMockContext({
-        config: {
-          type: 'agent',
-          resourceId: 'test-agent',
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
           name: 'Test Agent',
           description: 'Test agent',
           version: '1.0.0',
@@ -161,9 +165,10 @@ describe('buildReasoningRequest', () => {
 
     it('should omit security section when securityLevel is none', () => {
       const context = createMockContext({
-        config: {
-          type: 'agent',
-          resourceId: 'test-agent',
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
           name: 'Test Agent',
           description: 'Test agent',
           version: '1.0.0',
@@ -179,9 +184,10 @@ describe('buildReasoningRequest', () => {
 
     it('should allow explicit hardened override on non-session agent', () => {
       const context = createMockContext({
-        config: {
-          type: 'agent',
-          resourceId: 'test-agent',
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
           name: 'Test Agent',
           description: 'Test agent',
           version: '1.0.0',

package/src/execution/engine/index.ts

@@ -14,6 +14,7 @@ export {
   type WorkflowStepDefinition,
   type StepHandler,
   type WorkflowConfig,
+  type DescriptorBackedWorkflowConfig,
   type WorkflowDefinition,
   type NextConfig,
   type LinearNext,
@@ -59,7 +60,9 @@ export {
 // Agent exports (from agent module)
 export {
   Agent,
+  type AgentKind,
   type AgentConfig,
+  type DescriptorBackedAgentConfig,
   type AgentConstraints,
   type AgentMemory,
   type AgentDefinition,

package/src/execution/engine/workflow/types.ts

@@ -7,14 +7,21 @@ import type { z } from 'zod'
 
 import type { ExecutionContext } from '../base/types'
 import type { ResourceDefinition } from '../../../platform/registry/types'
+import type { WorkflowResourceEntry } from '../../../organization-model/domains/resources'
 import type { ResourceMetricsConfig } from '../../../operations/observability/types'
 import type { ExecutionInterface } from '../interface/types'
 
 // Workflow configuration
 export interface WorkflowConfig extends ResourceDefinition {
   type: 'workflow'
-  /** Lead-gen capability key for registry derivation (e.g. 'lead-gen.company.apollo-import') */
-  capabilityKey?: string
+  /** OM descriptor backing canonical identity and governance metadata. */
+  resource?: WorkflowResourceEntry
+  /** Lead-gen action key for registry derivation (e.g. 'lead-gen.company.apollo-import') */
+  actionKey?: string
+}
+
+export type DescriptorBackedWorkflowConfig = Omit<WorkflowConfig, 'resourceId' | 'type' | 'resource'> & {
+  resource: WorkflowResourceEntry
 }
 
 // Workflow step definition

package/src/knowledge/README.md

@@ -1,4 +1,4 @@
-# @elevasis/core/knowledge
+# @elevasis/core/knowledge
 
 Pure query layer over the organization graph. Browser-safe (no Node APIs); shared by the SDK CLI, platform CLI, and the `@elevasis/ui/knowledge` browser.
 
@@ -6,18 +6,18 @@ Pure query layer over the organization graph. Browser-safe (no Node APIs); share
 
 | Export                                        | Purpose                                                                                                                             |
 | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `byFeature(graph, featureId, knowledgeNodes)` | Knowledge nodes that govern the given feature.                                                                                      |
+| `bySystem(graph, systemId, knowledgeNodes)` | Knowledge nodes that govern the given system.                                                                                      |
 | `byKind(graph, kind, knowledgeNodes)`         | Filter knowledge nodes by `OrgKnowledgeKind`.                                                                                       |
 | `byOwner(graph, ownerId, knowledgeNodes)`     | Knowledge nodes whose `ownerIds` includes the given owner.                                                                          |
-| `governs(graph, nodeId)`                      | Outgoing `governs` targets (governed-feature ids) from a knowledge node.                                                            |
-| `governedBy(graph, nodeId)`                   | Incoming `governs` sources (governing knowledge-node ids) into a feature.                                                           |
-| `parsePath(pathString)`                       | Parse `/by-feature/$id`, `/by-kind/$kind`, `/by-owner/$id`, `/graph/$id/{governs,governed-by}`, or `/$id`. Throws on invalid input. |
+| `governs(graph, nodeId)`                      | Outgoing `governs` targets (governed-system ids) from a knowledge node.                                                            |
+| `governedBy(graph, nodeId)`                   | Incoming `governs` sources (governing knowledge-node ids) into a system.                                                           |
+| `parsePath(pathString)`                       | Parse `/by-system/$id`, `/by-kind/$kind`, `/by-owner/$id`, `/graph/$id/{governs,governed-by}`, or `/$id`. Throws on invalid input. |
 | `formatText`, `formatJson`, `formatIdsOnly`   | Output formatters used by the `knowledge:*` CLI subcommands.                                                                        |
 
 ## Path syntax
 
 ```
-/by-feature/<featureId>
+/by-system/<systemId>
 /by-kind/<playbook|strategy|reference>
 /by-owner/<ownerId>
 /graph/<nodeId>/governs
@@ -27,6 +27,7 @@ Pure query layer over the organization graph. Browser-safe (no Node APIs); share
 
 ## JSON envelope
 
-`formatJson` returns `{ path, mount, args, results }` — the same wrapped envelope used by `pnpm exec elevasis knowledge:ls --json` and `pnpm exec elevasis-sdk knowledge:ls --json`.
+`formatJson` returns `{ path, mount, args, results }` — the same wrapped envelope used by `pnpm exec elevasis knowledge:ls --json` and `pnpm exec elevasis-sdk knowledge:ls --json`.
 
 `governs` and `governedBy` accept either bare or graph-namespaced ids (`knowledge.foo` or `knowledge:knowledge.foo`).
+

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

@@ -1,5 +1,5 @@
-import { describe, expect, it } from 'vitest'
-import { byFeature, byKind, byOwner, governs, governedBy, parsePath } from '../queries'
+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'
@@ -10,8 +10,8 @@ import type { OrgKnowledgeNode } from '../../organization-model/domains/knowledg
 
 /**
  * Three knowledge nodes covering all three kinds.
- * - playbook-a governs feature:sales.crm and feature:sales.lead-gen
- * - strategy-b governs feature:sales.lead-gen
+ * - 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"
  */
@@ -22,7 +22,7 @@ const NODES: OrgKnowledgeNode[] = [
     title: 'Playbook A',
     summary: 'Playbook A summary.',
     body: '## Playbook A\n\nContent.',
-    links: [{ nodeId: 'feature:sales.crm' }, { nodeId: 'feature:sales.lead-gen' }],
+    links: [{ nodeId: 'system:sales.crm' }, { nodeId: 'system:sales.lead-gen' }],
     ownerIds: [],
     updatedAt: '2026-01-01'
   },
@@ -32,7 +32,7 @@ const NODES: OrgKnowledgeNode[] = [
     title: 'Strategy B',
     summary: 'Strategy B summary.',
     body: '## Strategy B\n\nContent.',
-    links: [{ nodeId: 'feature:sales.lead-gen' }],
+    links: [{ nodeId: 'system:sales.lead-gen' }],
     ownerIds: ['role.ops-lead'],
     updatedAt: '2026-01-02'
   },
@@ -67,13 +67,13 @@ const GRAPH: OrganizationGraph = {
   organizationModelVersion: 1,
   nodes: [
     { id: 'organization-model', kind: 'organization', label: 'Organization Model' },
-    { id: 'feature:sales.crm', kind: 'feature', label: 'CRM', sourceId: 'sales.crm', featureId: 'sales.crm' },
+    { id: 'system:sales.crm', kind: 'system', label: 'CRM', sourceId: 'sales.crm', systemId: 'sales.crm' },
     {
-      id: 'feature:sales.lead-gen',
-      kind: 'feature',
+      id: 'system:sales.lead-gen',
+      kind: 'system',
       label: 'Lead Gen',
       sourceId: 'sales.lead-gen',
-      featureId: 'sales.lead-gen'
+      systemId: 'sales.lead-gen'
     },
     {
       id: 'knowledge:knowledge.playbook-a',
@@ -128,50 +128,50 @@ const GRAPH: OrganizationGraph = {
     },
     // governs edges
     {
-      id: 'edge:governs:knowledge:knowledge.playbook-a:feature:sales.crm',
+      id: 'edge:governs:knowledge:knowledge.playbook-a:system:sales.crm',
       kind: 'governs',
       sourceId: 'knowledge:knowledge.playbook-a',
-      targetId: 'feature:sales.crm'
+      targetId: 'system:sales.crm'
     },
     {
-      id: 'edge:governs:knowledge:knowledge.playbook-a:feature:sales.lead-gen',
+      id: 'edge:governs:knowledge:knowledge.playbook-a:system:sales.lead-gen',
       kind: 'governs',
       sourceId: 'knowledge:knowledge.playbook-a',
-      targetId: 'feature:sales.lead-gen'
+      targetId: 'system:sales.lead-gen'
     },
     {
-      id: 'edge:governs:knowledge:knowledge.strategy-b:feature:sales.lead-gen',
+      id: 'edge:governs:knowledge:knowledge.strategy-b:system:sales.lead-gen',
       kind: 'governs',
       sourceId: 'knowledge:knowledge.strategy-b',
-      targetId: 'feature:sales.lead-gen'
+      targetId: 'system:sales.lead-gen'
     }
   ]
 }
 
 // ---------------------------------------------------------------------------
-// byFeature
+// bySystem
 // ---------------------------------------------------------------------------
 
-describe('byFeature', () => {
-  it('returns nodes that have governs edges to the given feature', () => {
-    const result = byFeature(GRAPH, 'sales.crm', NODES)
+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 feature', () => {
-    const result = byFeature(GRAPH, 'sales.lead-gen', NODES)
+  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 feature', () => {
-    const result = byFeature(GRAPH, 'feature.does-not-exist', NODES)
+  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 = byFeature(GRAPH, 'sales.crm', NODES)
+    const result = bySystem(GRAPH, 'sales.crm', NODES)
     expect(result[0].body).toBeDefined()
     expect(result[0].links).toBeDefined()
     expect(result[0].ownerIds).toBeDefined()
@@ -237,17 +237,17 @@ describe('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(['feature:sales.crm', 'feature:sales.lead-gen'].sort())
+    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(['feature:sales.crm', 'feature:sales.lead-gen'].sort())
+    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(['feature:sales.lead-gen'])
+    expect(result).toEqual(['system:sales.lead-gen'])
   })
 
   it('returns empty array for a node with no governs edges', () => {
@@ -266,69 +266,69 @@ describe('governs', () => {
 // ---------------------------------------------------------------------------
 
 describe('governedBy', () => {
-  it('returns knowledge graph node IDs for incoming governs edges (prefixed feature id)', () => {
-    const result = governedBy(GRAPH, 'feature:sales.lead-gen')
+  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 feature id (auto-prefixes with feature:)', () => {
+  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, 'feature:dashboard')
+    const result = governedBy(GRAPH, 'system:dashboard')
     expect(result).toHaveLength(0)
   })
 
   it('returns empty array for unknown target node id', () => {
-    const result = governedBy(GRAPH, 'feature:does-not-exist')
+    const result = governedBy(GRAPH, 'system:does-not-exist')
     expect(result).toHaveLength(0)
   })
 })
 
 // ---------------------------------------------------------------------------
-// parsePath — happy paths (all five mount axes)
+// parsePath — happy paths (all five mount axes)
 // ---------------------------------------------------------------------------
 
-describe('parsePath — happy paths', () => {
-  it('/by-kind/playbook → mount:by-kind args:[playbook]', () => {
+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]', () => {
+  it('/by-kind/strategy → mount:by-kind args:[strategy]', () => {
     expect(parsePath('/by-kind/strategy')).toEqual({ mount: 'by-kind', args: ['strategy'] })
   })
 
-  it('/by-feature/sales.crm → mount:by-feature args:[sales.crm]', () => {
-    expect(parsePath('/by-feature/sales.crm')).toEqual({ mount: 'by-feature', args: ['sales.crm'] })
+  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-feature/sales/crm (slash-delimited) → mount:by-feature args:[sales/crm]', () => {
-    // featureId with slashes is joined and passed as-is for the caller to interpret
-    expect(parsePath('/by-feature/sales/crm')).toEqual({ mount: 'by-feature', 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]', () => {
+  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]', () => {
+  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]', () => {
+  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]', () => {
+  it('/<nodeId> single segment → mount:node args:[nodeId]', () => {
     expect(parsePath('/knowledge.outreach-playbook')).toEqual({
       mount: 'node',
       args: ['knowledge.outreach-playbook']
@@ -341,10 +341,10 @@ describe('parsePath — happy paths', () => {
 })
 
 // ---------------------------------------------------------------------------
-// parsePath — invalid inputs (5+)
+// parsePath — invalid inputs (5+)
 // ---------------------------------------------------------------------------
 
-describe('parsePath — invalid inputs', () => {
+describe('parsePath — invalid inputs', () => {
   it('throws on empty string', () => {
     expect(() => parsePath('')).toThrow('parsePath: path must be a non-empty string')
   })
@@ -357,8 +357,8 @@ describe('parsePath — invalid inputs', () => {
     expect(() => parsePath('/')).toThrow('parsePath: path resolves to root with no mount')
   })
 
-  it('throws on /by-feature with no featureId argument', () => {
-    expect(() => parsePath('/by-feature')).toThrow('/by-feature requires a featureId argument')
+  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', () => {
@@ -385,11 +385,11 @@ describe('parsePath — invalid inputs', () => {
 })
 
 // ---------------------------------------------------------------------------
-// parsePath — edge cases
+// parsePath — edge cases
 // ---------------------------------------------------------------------------
 
 describe('parsePath edge cases', () => {
-  // Whitespace handling — the parser does NOT trim the incoming string.
+  // 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 "/"')
@@ -409,13 +409,13 @@ describe('parsePath edge cases', () => {
     expect(parsePath('/by-kind/playbook///')).toEqual({ mount: 'by-kind', args: ['playbook'] })
   })
 
-  // Lone-slash variants — a path of only slashes normalises to an empty
+  // 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.
+  // 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
@@ -423,16 +423,16 @@ describe('parsePath edge cases', () => {
     expect(result.args[0]).toBe('Playbook')
   })
 
-  // Feature ID: dot notation passes through unchanged.
-  it('/by-feature/sales.crm preserves dot notation', () => {
-    expect(parsePath('/by-feature/sales.crm')).toEqual({ mount: 'by-feature', args: ['sales.crm'] })
+  // 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'] })
   })
 
-  // Feature ID: slash notation joins rest segments with '/'.
-  // The parser does NOT convert slashes to dots — the caller must normalise.
-  it('/by-feature/sales/crm joins segments with slash (no dot conversion)', () => {
-    const result = parsePath('/by-feature/sales/crm')
-    expect(result.mount).toBe('by-feature')
+  // 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')
   })
@@ -446,7 +446,7 @@ describe('parsePath edge cases', () => {
     expect(result.args).toHaveLength(1)
   })
 
-  // /by-owner joins rest with '/' (same behaviour as /by-feature).
+  // /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')
@@ -454,7 +454,7 @@ describe('parsePath edge cases', () => {
   })
 
   // 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 '/'.
+  // 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')
@@ -467,7 +467,7 @@ describe('parsePath edge cases', () => {
     expect(() => parsePath('/graph')).toThrow('/graph requires <nodeId>/<verb>')
   })
 
-  // /node mount — single-segment path works for any non-reserved first segment.
+  // /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'] })
   })
@@ -504,7 +504,7 @@ describe('formatText', () => {
 })
 
 // ---------------------------------------------------------------------------
-// formatJson — envelope shape
+// formatJson — envelope shape
 // ---------------------------------------------------------------------------
 
 describe('formatJson', () => {
@@ -538,8 +538,8 @@ describe('formatJson', () => {
 
   it('preserves args array in envelope', () => {
     const raw = formatJson({
-      path: '/by-feature/sales.crm',
-      parsed: { mount: 'by-feature', args: ['sales.crm'] },
+      path: '/by-system/sales.crm',
+      parsed: { mount: 'by-system', args: ['sales.crm'] },
       results: []
     })
     expect(JSON.parse(raw)).toMatchObject({ args: ['sales.crm'] })
@@ -549,13 +549,13 @@ describe('formatJson', () => {
     const raw = formatJson({
       path: '/graph/knowledge.playbook-a/governs',
       parsed: { mount: 'graph', args: ['knowledge.playbook-a', 'governs'] },
-      results: ['feature:sales.crm', 'feature:sales.lead-gen']
+      results: ['system:sales.crm', 'system:sales.lead-gen']
     })
     const parsed = JSON.parse(raw) as { results: string[] }
-    expect(parsed.results).toEqual(['feature:sales.crm', 'feature:sales.lead-gen'])
+    expect(parsed.results).toEqual(['system:sales.crm', 'system:sales.lead-gen'])
   })
 
-  it('envelope is NOT flat { results } — must have path/mount/args siblings', () => {
+  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'] },
@@ -587,7 +587,8 @@ describe('formatIdsOnly', () => {
   })
 
   it('returns newline-separated strings for string[] (governs results)', () => {
-    const output = formatIdsOnly(['feature:sales.crm', 'feature:sales.lead-gen'])
-    expect(output).toBe('feature:sales.crm\nfeature:sales.lead-gen')
+    const output = formatIdsOnly(['system:sales.crm', 'system:sales.lead-gen'])
+    expect(output).toBe('system:sales.crm\nsystem:sales.lead-gen')
   })
 })
+