Formalize knowledge and agency layers

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+- Added typed Knowledge and Agency operation layers to the embedded API and
+  operation catalogs.
+- Moved retail Agent Intent dispatch behind a compatibility adapter without
+  removing or renaming existing operations.
+
 ## 0.3.0-alpha.3
 
 - Added a reproducible SRE comparison between a competent conventional

README.md

@@ -22,6 +22,9 @@ single governed system. It is designed for applications that need to answer:
 - What conflicts with it?
 - Which workflow or external action depended on it?
 
+The public API separates these responsibilities into a Knowledge layer, an
+Agency layer, and a compatibility adapter for the original retail workflow.
+
 ## Capabilities
 
 - Bitemporal assertions with evidence, epistemic kind, perspective, and typed
@@ -130,6 +133,8 @@ import { AgenticKernel, SqliteStore } from "agentic-data-kernel";
 
 const store = new SqliteStore(".data/app.db");
 const kernel = new AgenticKernel(store);
+
+const { knowledge, agency, retail } = kernel;
 ```
 
 The npm package provides:
@@ -342,12 +347,15 @@ HTTP / MCP / TypeScript / CLI
              |
    identity, scope, purpose
              |
- knowledge + workflow kernel
-   | assertions and evidence
-   | conflict resolution
-   | hybrid retrieval
-   | timers and state machines
-   | effects and receipts
+  Knowledge layer
+   | assertions, evidence, retrieval
+   | resolution, lineage, explanation
+             +
+   Agency layer
+   | workflows, effects, receipts
+             +
+ retail compatibility adapter
+   | inventory, orders, payment timers
              |
  SQLite development adapter
              or

benchmarks/sre/results/report.md

@@ -2,9 +2,9 @@
 
 Generated from `summary.json`.
 
-Source revision: `8f550182ed7441b42ee475f5d4de372949c2622f`
+Source revision: `34e3048f473404cdbc0292d0075b7bae40738184`
 
-Source hash: `1922383ad9b79b244ae960c12943e44af727cb08daf084c6a5dda5cd5a77021e`
+Source hash: `170c987cc84217860ce29feabceacd863684ed5abd73397c700947635d23755a`
 
 ## Correctness
 
@@ -24,7 +24,7 @@ Both variants must resolve every run with one delivery and one reconciliation.
 
 The adapter delegates to the shipped SRE scenario, which contains
 929 nonblank TypeScript source lines inside the
-dependency. The full kernel dependency contains 13292
+dependency. The full kernel dependency contains 13750
 nonblank TypeScript source lines.
 
 The benchmark runner and engine-specific audit verification contain
@@ -44,8 +44,8 @@ operated, or upgraded.
 
 | Variant | Median milliseconds |
 | --- | ---: |
-| Conventional PostgreSQL | 73.64 |
-| Agentic Data Kernel | 1119.30 |
+| Conventional PostgreSQL | 61.04 |
+| Agentic Data Kernel | 869.38 |
 
 Runtime is not a headline metric. The variants perform different work and this
 deterministic smoke benchmark is not a latency study.

benchmarks/sre/results/summary.json

@@ -4,8 +4,8 @@
   "environment": {
     "node": "v22.22.2",
     "postgres": "18.6 (Debian 18.6-1.pgdg12+2)",
-    "commit": "8f550182ed7441b42ee475f5d4de372949c2622f",
-    "sourceHash": "1922383ad9b79b244ae960c12943e44af727cb08daf084c6a5dda5cd5a77021e"
+    "commit": "34e3048f473404cdbc0292d0075b7bae40738184",
+    "sourceHash": "170c987cc84217860ce29feabceacd863684ed5abd73397c700947635d23755a"
   },
   "runs": [
     {
@@ -31,7 +31,7 @@
           "provider reconciliation": true,
           "verification and terminal state": true
         },
-        "durationMs": 70.12690000000009
+        "durationMs": 85.97399999999993
       },
       "operatedTables": 8,
       "databaseBytes": 540672
@@ -59,7 +59,7 @@
           "provider reconciliation": true,
           "verification and terminal state": true
         },
-        "durationMs": 917.8879
+        "durationMs": 967.3033000000001
       },
       "operatedTables": 18,
       "databaseBytes": 1572864
@@ -87,7 +87,7 @@
           "provider reconciliation": true,
           "verification and terminal state": true
         },
-        "durationMs": 92.02959999999985
+        "durationMs": 61.03850000000011
       },
       "operatedTables": 8,
       "databaseBytes": 540672
@@ -115,7 +115,7 @@
           "provider reconciliation": true,
           "verification and terminal state": true
         },
-        "durationMs": 1119.3008
+        "durationMs": 864.3142000000003
       },
       "operatedTables": 18,
       "databaseBytes": 1572864
@@ -143,7 +143,7 @@
           "provider reconciliation": true,
           "verification and terminal state": true
         },
-        "durationMs": 73.63929999999982
+        "durationMs": 59.98480000000018
       },
       "operatedTables": 8,
       "databaseBytes": 540672
@@ -171,7 +171,7 @@
           "provider reconciliation": true,
           "verification and terminal state": true
         },
-        "durationMs": 1167.6057
+        "durationMs": 869.3758999999995
       },
       "operatedTables": 18,
       "databaseBytes": 1572864
@@ -266,7 +266,7 @@
       "authoredTables": 0,
       "operatedTables": 18,
       "scenarioSourceLines": 929,
-      "dependencySourceLines": 13292
+      "dependencySourceLines": 13750
     }
   },
   "benchmarkHarness": {
@@ -277,8 +277,8 @@
     "agenticDataKernelMedian": 1572864
   },
   "runtimeMillisecondsInformational": {
-    "conventionalPostgresMedian": 73.63929999999982,
-    "agenticDataKernelMedian": 1119.3008
+    "conventionalPostgresMedian": 61.03850000000011,
+    "agenticDataKernelMedian": 869.3758999999995
   },
   "explanationQuestions": 9,
   "claims": {

docs/API.md

@@ -37,26 +37,48 @@ separate idempotency namespace.
 In the PostgreSQL profile, the supplied principal must exactly match the
 authenticated API key.
 
+## Operation layers
+
+Agent Intent keeps one backward-compatible operation union and one execution
+endpoint. Operations are now grouped into three explicit layers:
+
+| Layer | Responsibility |
+| --- | --- |
+| Knowledge | Entities, artifacts, temporal assertions, resolution, retrieval, lineage, and explanation |
+| Agency | Generic workflows, controlled effects, workflow reads, and effect reads |
+| Retail compatibility | Inventory reservation, payment, order expiry, and existing retail workflow behavior |
+
+The embedded TypeScript API exposes these as `kernel.knowledge`,
+`kernel.agency`, and `kernel.retail`. Existing methods such as
+`kernel.assert(...)`, `kernel.createWorkflow(...)`, and
+`kernel.reserveInventory(...)` remain available with unchanged behavior.
+`kernel.agency.getMachine(...)` returns either a generic workflow or retail
+order record, while `kernel.retail.getOrder(...)` requires a retail order.
+
+The PostgreSQL, HTTP, MCP, and CLI profiles continue to use the same Agent
+Intent envelope. `GET /v1/catalog` now reports the layer for each available
+operation. No operation name was removed or renamed.
+
 ## Operations
 
-| Operation | Scope | Description |
-| --- | --- | --- |
-| `put_entity` | `data:write` | Create or update an entity identity |
-| `put_artifact` | `data:write` | Store immutable source evidence |
-| `assert` | `data:write` | Add or supersede a typed temporal assertion |
-| `resolve` | `data:read` | Return known, unknown, conflicting, or policy-selected values |
-| `search` | `data:read` | Run hybrid retrieval with optional graph filters |
-| `create_workflow` | `workflows:run` | Create a non-retail durable workflow |
-| `advance_workflow` | `workflows:run` | Commit a guarded workflow transition |
-| `request_effect` | `effects:write` | Request an authorized generic external effect |
-| `add_lineage` | `data:write` | Add a typed causal link between durable records |
-| `explain` | `data:read` | Traverse bounded typed causal lineage |
-| `seed_inventory` | `inventory:admin` | Create initial inventory for a SKU and location |
-| `reserve_inventory` | `orders:write` | Reserve stock and start an order workflow |
-| `request_payment` | `effects:write` | Reserve effect budget and create a payment intent |
-| `get_machine` | `data:read` | Read current workflow state |
-| `list_effects` | `data:read` | Read effect state |
-| `process_timers` | `workflows:run` | Process timers using database server time |
+| Operation | Layer | Scope | Description |
+| --- | --- | --- | --- |
+| `put_entity` | Knowledge | `data:write` | Create or update an entity identity |
+| `put_artifact` | Knowledge | `data:write` | Store immutable source evidence |
+| `assert` | Knowledge | `data:write` | Add or supersede a typed temporal assertion |
+| `resolve` | Knowledge | `data:read` | Return known, unknown, conflicting, or policy-selected values |
+| `search` | Knowledge | `data:read` | Run hybrid retrieval with optional graph filters |
+| `add_lineage` | Knowledge | `data:write` | Add a typed causal link between durable records |
+| `explain` | Knowledge | `data:read` | Traverse bounded typed causal lineage |
+| `create_workflow` | Agency | `workflows:run` | Create a non-retail durable workflow |
+| `advance_workflow` | Agency | `workflows:run` | Commit a guarded workflow transition |
+| `request_effect` | Agency | `effects:write` | Request an authorized generic external effect |
+| `get_machine` | Agency | `data:read` | Read current workflow state |
+| `list_effects` | Agency | `data:read` | Read effect state |
+| `seed_inventory` | Retail compatibility | `inventory:admin` | Create initial inventory for a SKU and location |
+| `reserve_inventory` | Retail compatibility | `orders:write` | Reserve stock and start an order workflow |
+| `request_payment` | Retail compatibility | `effects:write` | Reserve effect budget and create a payment intent |
+| `process_timers` | Retail compatibility | `workflows:run` | Process retail reservation timers using database server time |
 
 `record_payment_outcome` exists only in the development profile. The production
 profile accepts terminal effect state only from the effect worker.
@@ -221,7 +243,10 @@ Temporal, status, tenant, optional field, and graph constraints remain inside
 candidate selection so bounded retrieval does not reintroduce stale or
 out-of-scope rows.
 
-## Retail workflow
+## Retail compatibility workflow
+
+Retail operations remain supported behind the compatibility adapter while the
+generic Agency layer stays independent of retail order invariants.
 
 ```text
 new -> reserved -> payment_pending -> confirmed

scripts/test-package.mjs

@@ -102,9 +102,11 @@ try {
     smokeModule,
     `import {
   AgenticKernel,
-  SqliteStore,
-  formatTraceExplanation,
-} from "agentic-data-kernel";
+      KNOWLEDGE_OPERATION_NAMES,
+      KnowledgeLayer,
+      SqliteStore,
+      formatTraceExplanation,
+    } from "agentic-data-kernel";
 import {
   OpenAiCompatibleEmbeddingProvider,
   postgresMigrationDirectory,
@@ -124,6 +126,12 @@ try {
   if (typeof formatTraceExplanation !== "function") {
     throw new Error("Trace formatter export is unavailable");
   }
+  if (
+    !(kernel.knowledge instanceof KnowledgeLayer) ||
+    !KNOWLEDGE_OPERATION_NAMES.includes("assert")
+  ) {
+    throw new Error("Layered API exports are unavailable");
+  }
   if (
     !existsSync(join(postgresMigrationDirectory, "001_core.sql")) ||
     !existsSync(join(postgresMigrationDirectory, "002_embedding_space.sql")) ||
@@ -146,9 +154,11 @@ try {
     typeSmokeModule,
     `import {
   AgenticKernel,
-  SqliteStore,
-  formatTraceExplanation,
-} from "agentic-data-kernel";
+      type KnowledgeOperationName,
+      KnowledgeLayer,
+      SqliteStore,
+      formatTraceExplanation,
+    } from "agentic-data-kernel";
 import {
   type EmbeddingSpace,
   ProductionDatabase,
@@ -157,6 +167,8 @@ import {
 
 const store = new SqliteStore(":memory:");
 const kernel: AgenticKernel = new AgenticKernel(store);
+const knowledgeLayer: KnowledgeLayer = kernel.knowledge;
+const knowledgeOperation: KnowledgeOperationName = "assert";
 const formatter: typeof formatTraceExplanation = formatTraceExplanation;
 const databaseType: typeof ProductionDatabase = ProductionDatabase;
 const migrationPath: string = postgresMigrationDirectory;
@@ -166,6 +178,8 @@ const embeddingSpace: EmbeddingSpace = {
   dimensions: 768,
 };
 void kernel;
+void knowledgeLayer;
+void knowledgeOperation;
 void formatter;
 void databaseType;
 void migrationPath;

src/index.ts

@@ -10,6 +10,31 @@ export type {
   IntentEnvelope,
   IntentExecutionResult,
 } from "./ir.js";
+export {
+  AGENCY_OPERATION_NAMES,
+  AgencyLayer,
+  DEVELOPMENT_OPERATION_NAMES,
+  KNOWLEDGE_OPERATION_NAMES,
+  KnowledgeLayer,
+  isAgencyOperation,
+  isKnowledgeOperation,
+  isRetailCompatibilityOperation,
+  operationLayer,
+  operationLayerCatalog,
+  PRODUCTION_OPERATION_NAMES,
+  RETAIL_COMPATIBILITY_OPERATION_NAMES,
+  RetailCompatibilityAdapter,
+} from "./layers.js";
+export type {
+  AgencyOperation,
+  AgencyOperationName,
+  AgentOperationName,
+  KnowledgeOperation,
+  KnowledgeOperationName,
+  OperationLayer,
+  RetailCompatibilityOperation,
+  RetailCompatibilityOperationName,
+} from "./layers.js";
 export { SqliteStore } from "./store.js";
 export {
   formatTraceExplanation,