@ixo/oracle-runtime-workers 0.23.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
   "private": false,
   "publishConfig": {

package/src/core/env.ts

@@ -129,7 +129,10 @@ export const baseEnvSchema = z.object({
   ORACLE_DID: z.string().min(1),
   /**
    * On-chain entity DID surfaced to the agent as `identity.entityDid`. Falls
-   * back to `ORACLE_DID` when unset (see `createRuntimeCore`).
+   * back to `ORACLE_DID` when unset (see `createRuntimeCore`) for rooms and
+   * feedback. The memory plugin redeclares it as required
+   * (`did:ixo:entity:<32 hex>`): the Memory Engine keys every space by it and
+   * never receives the fallback.
    */
   ORACLE_ENTITY_DID: z.string().min(1).optional(),
   NETWORK: z.enum(['mainnet', 'testnet', 'devnet']).default('mainnet'),

package/src/do/user-oracle-do.ts

@@ -381,6 +381,10 @@ import {
   fetchMemorySchemaDump,
   getMemorySchemaDump,
 } from '../plugins/memory/memory-tools';
+import {
+  MEMORY_ENTITY_HEADER,
+  memoryEntityDid,
+} from '../plugins/memory/memory-entity';
 import {
   contentToText,
   isSummarizationMessage,
@@ -4341,6 +4345,9 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           const v = this.core.validatedEnv['MEMORY_ENGINE_URL'];
           return typeof v === 'string' && v.length > 0 ? v : undefined;
         })(),
+        // The configured entity only: `identity.entityDid` falls back to
+        // `ORACLE_DID`, which the engine refuses as a space key.
+        entityDid: memoryEntityDid(this.core.validatedEnv['ORACLE_ENTITY_DID']),
         getSession: async (id) => {
           const snapshot = this.historySnapshots.get(id);
           const row =
@@ -4429,7 +4436,11 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       this.userContextFetcher ??= new UserContextFetcher(
         {
           memoryEngineUrl: settings.engineUrl,
-          oracleDid: this.env.ORACLE_DID,
+          // The configured entity only: `identity.entityDid` falls back to
+          // `ORACLE_DID`, which the engine refuses as a space key.
+          entityDid: memoryEntityDid(
+            this.core.validatedEnv['ORACLE_ENTITY_DID'],
+          ),
           // Looked up per call, not captured: a working-copy reset replaces
           // the ambient services while a gather may still be running.
           ucan: {
@@ -5383,6 +5394,15 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       if (!ambient || typeof url !== 'string' || url.length === 0) {
         return { error: 'MEMORY_MCP_URL is not configured' };
       }
+      const entityDid = memoryEntityDid(
+        this.core.validatedEnv['ORACLE_ENTITY_DID'],
+      );
+      if (!entityDid) {
+        return {
+          error:
+            'ORACLE_ENTITY_DID is not a domain entity DID (did:ixo:entity:<32 hex>)',
+        };
+      }
       const memoryDid = await ambient.ucan.resolveServiceDid(url);
       if (!memoryDid)
         return { error: 'memory engine DID could not be resolved' };
@@ -5400,6 +5420,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         Authorization: `Bearer ${invocation}`,
         'X-Auth-Type': 'ucan',
         'User-Agent': 'LangChain-MCP-Client/1.0',
+        [MEMORY_ENTITY_HEADER]: entityDid,
         ...(room?.roomId ? { 'x-room-id': room.roomId } : {}),
       };
       try {

package/src/memory/session-history-indexer.ts

@@ -16,7 +16,10 @@
  *  - Auth is the oracle's two-hop UCAN invocation minted from the user's
  *    delegation (`ixo:memory` / `memory/*`) — no delegation, no indexing.
  *  - Endpoint: `POST <MEMORY_ENGINE_URL>/messages` with `x-room-id`, as
- *    `@ixo/common`'s `MemoryEngineService.processConversationHistory`.
+ *    `@ixo/common`'s `MemoryEngineService.processConversationHistory`, plus
+ *    `x-oracle-entity-did`: the engine keys the user's space by the oracle's
+ *    domain entity (`ORACLE_ENTITY_DID`). Without one nothing is indexed
+ *    (one warning per indexer) and the watermark stays put.
  *  - A per-session lock prevents overlapping runs; a failed upload is
  *    retried 3× with a 10 s pause (Node's numbers).
  *
@@ -24,6 +27,7 @@
  * preferred name is set; here the fallback is the literal "Me" straight away.
  */
 import type { Logger } from '../plugin-api/types';
+import { MEMORY_ENTITY_HEADER } from '../plugins/memory/memory-entity';
 
 export interface HistoryMessage {
   /** LangChain message type: `human` | `ai` | `tool` | `system`. */
@@ -53,6 +57,12 @@ export interface SpeakerLabels {
 export interface SessionHistoryIndexerDeps {
   /** `MEMORY_ENGINE_URL`; undefined disables indexing (memory plugin absent). */
   memoryEngineUrl: string | undefined;
+  /**
+   * The configured `ORACLE_ENTITY_DID` (a well-formed domain entity DID),
+   * sent as `x-oracle-entity-did`. Never the `ORACLE_DID` fallback:
+   * undefined → every session is `skipped`.
+   */
+  entityDid: string | undefined;
   getSession(sessionId: string): Promise<IndexableSession | undefined>;
   /** The session transcript, summarisation bookkeeping already removed. */
   listMessages(sessionId: string): Promise<HistoryMessage[]>;
@@ -153,6 +163,9 @@ export class SessionHistoryIndexer {
 
   private readonly requestTimeoutMs: number;
 
+  /** The missing-entity warning has been logged (it is logged once). */
+  private warnedNoEntity = false;
+
   constructor(private readonly deps: SessionHistoryIndexerDeps) {
     this.fetchImpl = deps.fetchImpl ?? fetch.bind(globalThis);
     this.sleep =
@@ -187,6 +200,16 @@ export class SessionHistoryIndexer {
       );
       return 'skipped';
     }
+    const entityDid = this.deps.entityDid;
+    if (!entityDid) {
+      if (!this.warnedNoEntity) {
+        this.warnedNoEntity = true;
+        logger.warn(
+          `[history-indexer] ORACLE_ENTITY_DID is not a domain entity DID (did:ixo:entity:<32 hex>); the memory engine keys every space by it, so session history is not indexed`,
+        );
+      }
+      return 'skipped';
+    }
     if (this.inFlight.has(sessionId)) {
       logger.log(
         `[history-indexer] session ${sessionId} is already being indexed, skipping`,
@@ -197,7 +220,7 @@ export class SessionHistoryIndexer {
     try {
       for (let attempt = 1; attempt <= this.maxRetries; attempt += 1) {
         try {
-          const outcome = await this.processOnce(sessionId);
+          const outcome = await this.processOnce(sessionId, entityDid);
           if (outcome === 'processed') {
             logger.log(
               `[history-indexer] indexed session ${sessionId} into the memory engine`,
@@ -223,7 +246,10 @@ export class SessionHistoryIndexer {
     }
   }
 
-  private async processOnce(sessionId: string): Promise<IndexOutcome> {
+  private async processOnce(
+    sessionId: string,
+    entityDid: string,
+  ): Promise<IndexOutcome> {
     const { deps } = this;
     const { logger } = deps;
     const memoryEngineUrl = deps.memoryEngineUrl!.replace(/\/+$/, '');
@@ -306,6 +332,7 @@ export class SessionHistoryIndexer {
         headers: {
           Authorization: `Bearer ${invocation}`,
           'X-Auth-Type': 'ucan',
+          [MEMORY_ENTITY_HEADER]: entityDid,
           'x-room-id': roomId,
           'Content-Type': 'application/json',
         },

package/src/memory/user-context-fetcher.ts

@@ -9,7 +9,8 @@
  * memory-context block before the model's first call.
  *
  * Policy:
- *  - The result is a function of the room (and the oracle), not the session,
+ *  - The result is a function of the room (and the oracle's domain entity,
+ *    which keys every memory space on the engine), not the session,
  *    so the cache is keyed by room: a new session in the same room reuses it.
  *    Positive entries live `cacheTtlMs` (5 min) in an LRU of `maxCachedRooms`.
  *    A successful batch is cached even when every slot is empty — "no
@@ -25,7 +26,9 @@
  *    a memory write and after session history is indexed.
  *  - A missing signing key or a failed invocation mint is a skip, never a
  *    negative-cache entry: the user may delegate `ixo:memory` before the next
- *    turn.
+ *    turn. So is a missing domain entity (`ORACLE_ENTITY_DID`): the engine
+ *    refuses a request that names none, so none is sent; it is warned about
+ *    once per fetcher.
  *  - One gather per room at a time; a second caller joins it. The blocking
  *    `fetch` waits at most `blockingCapMs`; past the cap the gather keeps
  *    running and fills the cache for later turns (the caller keeps the
@@ -41,6 +44,7 @@
  */
 import type { MemoryContextSection } from '../core/prompt-composer';
 import type { Logger, UserContextData } from '../plugin-api/types';
+import { MEMORY_ENTITY_HEADER } from '../plugins/memory/memory-entity';
 import type {
   ComparisonOperator,
   EntityType,
@@ -99,15 +103,17 @@ const RECENT_WINDOW_DAYS = 90;
  * brittle), `node_labels` only where it discriminates, and the `recent`
  * slot bounded to the last 90 days explicitly (the server's
  * `recent_memory` strategy injects the same lower bound and keeps an
- * existing one).
+ * existing one). `oracle_dids` names the oracle's domain entity.
  */
 export function buildUserContextQueries(
-  oracleDid: string,
+  entityDid: string,
   now: Date,
 ): UserContextQuery[] {
   const recentSince = new Date(now.getTime());
   recentSince.setUTCDate(recentSince.getUTCDate() - RECENT_WINDOW_DAYS);
-  const oracle_dids = [oracleDid];
+  // The wire name predates entity keying; the engine reads its entries as
+  // domain entity DIDs (the knowledge spaces the queries also search).
+  const oracle_dids = [entityDid];
   return [
     {
       oracle_dids,
@@ -471,8 +477,13 @@ function perSlot<T>(
 export interface UserContextFetcherDeps {
   /** `MEMORY_ENGINE_URL`; undefined → every call is `skipped`, no request. */
   memoryEngineUrl: string | undefined;
-  /** `ORACLE_DID` — the knowledge space the queries search (`oracle_dids`). */
-  oracleDid: string;
+  /**
+   * The configured `ORACLE_ENTITY_DID` (a well-formed domain entity DID) —
+   * sent as `x-oracle-entity-did` and as the queries' `oracle_dids`. Never
+   * the `ORACLE_DID` fallback: undefined → every call is `skipped`
+   * (`no-entity`), no request, one warning per fetcher.
+   */
+  entityDid: string | undefined;
   /** The user's UCAN surface, bound to the user's DID by the caller. */
   ucan: {
     hasSigningKey(): boolean;
@@ -515,6 +526,7 @@ const DEFAULT_MAX_CACHED_ROOMS = 64;
 
 export type UserContextSkipReason =
   | 'no-engine-url'
+  | 'no-entity'
   | 'no-signing-key'
   | 'no-invocation'
   | 'recently-failed'
@@ -616,6 +628,9 @@ export class UserContextFetcher {
 
   private readonly maxCachedRooms: number;
 
+  /** The missing-entity warning has been logged (it is logged once). */
+  private warnedNoEntity = false;
+
   constructor(
     private readonly deps: UserContextFetcherDeps,
     options: UserContextFetcherOptions = {},
@@ -773,6 +788,16 @@ export class UserContextFetcher {
       );
       return { kind: 'skipped', reason: 'no-engine-url' };
     }
+    const entityDid = this.deps.entityDid;
+    if (!entityDid) {
+      if (!this.warnedNoEntity) {
+        this.warnedNoEntity = true;
+        logger.warn(
+          `[user-context] skipped: ORACLE_ENTITY_DID is not a domain entity DID (did:ixo:entity:<32 hex>); the memory engine keys every space by it, so no first-turn context is gathered`,
+        );
+      }
+      return { kind: 'skipped', reason: 'no-entity' };
+    }
     if (!roomId) {
       logger.warn(`[user-context] skipped: no oracle room for this turn`);
       return { kind: 'skipped', reason: 'no-room' };
@@ -807,7 +832,7 @@ export class UserContextFetcher {
 
     const entry: InFlightGather = {
       startedAt: this.now(),
-      promise: this.gather(engineUrl, roomId).then(
+      promise: this.gather(engineUrl, entityDid, roomId).then(
         (result) => this.settle(roomId, entry, result),
         (err: unknown) =>
           this.settle(roomId, entry, {
@@ -870,6 +895,7 @@ export class UserContextFetcher {
   /** Mint the invocation, run the batch, map the slots. Never rejects. */
   private async gather(
     engineUrl: string,
+    entityDid: string,
     roomId: string,
   ): Promise<GatherResult> {
     const { logger, ucan } = this.deps;
@@ -905,14 +931,12 @@ export class UserContextFetcher {
         headers: {
           Authorization: `Bearer ${invocation}`,
           'X-Auth-Type': 'ucan',
+          [MEMORY_ENTITY_HEADER]: entityDid,
           'x-room-id': roomId,
           'Content-Type': 'application/json',
         },
         body: JSON.stringify({
-          queries: buildUserContextQueries(
-            this.deps.oracleDid,
-            new Date(this.now()),
-          ),
+          queries: buildUserContextQueries(entityDid, new Date(this.now())),
         }),
         signal: AbortSignal.timeout(this.requestTimeoutMs),
       });

package/src/plugins/memory/index.ts

@@ -12,6 +12,10 @@ export {
   type MemoryMcpFactory,
   type UpstreamMcpTool,
 } from './memory-tools';
+export {
+  MEMORY_ENTITY_HEADER,
+  ORACLE_ENTITY_DID_PATTERN,
+} from './memory-entity';
 export { buildMemoryHeaders } from './memory-ucan';
 export { MemoryPlugin, type MemoryPluginOptions } from './memory.plugin';
 export type * from './types';

package/src/plugins/memory/memory-entity.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+
+/**
+ * The Memory Engine keys every memory space by the oracle's domain entity
+ * (`did:ixo:entity:<32 hex>`): the user's personal space is
+ * `sha256(<userDid>-<entityDid>)` and the shared knowledge spaces are the
+ * entity's. Every engine request names the entity in this header; the engine
+ * refuses a request without it and checks (on chain) that the entity lists
+ * the oracle's agent account as a Matrix admin.
+ */
+export const MEMORY_ENTITY_HEADER = 'x-oracle-entity-did';
+
+/** The shape the Memory Engine accepts for {@link MEMORY_ENTITY_HEADER}. */
+export const ORACLE_ENTITY_DID_PATTERN = /^did:ixo:entity:[0-9a-f]{32}$/;
+
+const ENTITY_REQUIRED_MESSAGE =
+  "ORACLE_ENTITY_DID is required by the memory plugin: set it to the oracle's domain entity DID (did:ixo:entity: followed by 32 lower-case hex characters). The Memory Engine keys every memory space by that entity and refuses requests without it.";
+
+const ENTITY_SHAPE_MESSAGE =
+  "ORACLE_ENTITY_DID must be the oracle's domain entity DID (did:ixo:entity: followed by 32 lower-case hex characters); the Memory Engine refuses any other value.";
+
+/**
+ * `ORACLE_ENTITY_DID` as the memory plugin requires it. The core schema keeps
+ * the variable optional (rooms and feedback fall back to `ORACLE_DID`); the
+ * memory plugin redeclares it so an oracle with `MEMORY_MCP_URL` and no
+ * entity fails at boot. The engine never receives the `ORACLE_DID` fallback.
+ */
+export const oracleEntityDidSchema = z
+  .string({
+    error: (issue) =>
+      issue.input === undefined
+        ? ENTITY_REQUIRED_MESSAGE
+        : ENTITY_SHAPE_MESSAGE,
+  })
+  .regex(ORACLE_ENTITY_DID_PATTERN, ENTITY_SHAPE_MESSAGE);
+
+/**
+ * The configured `ORACLE_ENTITY_DID` when it is a well-formed domain entity
+ * DID, else `undefined`. For the engine paths outside the plugin (first-turn
+ * prefetch, session-history indexing, the memory debug route): they read the
+ * merged env directly and run wherever `MEMORY_ENGINE_URL` survives
+ * validation, which another plugin than this one may declare, so the
+ * plugin's schema does not cover them.
+ */
+export function memoryEntityDid(value: unknown): string | undefined {
+  return typeof value === 'string' && ORACLE_ENTITY_DID_PATTERN.test(value)
+    ? value
+    : undefined;
+}

package/src/plugins/memory/memory-tools.ts

@@ -28,8 +28,9 @@ export const MEMORY_CLEAR_MCP_NAME = 'memory-engine__clear';
  * destructive `clear` stays in the default set. `add_oracle_knowledge` is in
  * the set so the controllers and owners of any oracle can grow its shared
  * knowledge from chat without a per-oracle code change: the Memory Engine
- * itself checks on chain that the caller controls or owns an entity linked to
- * the oracle and refuses everyone else, so listing the tool for every user
+ * itself checks on chain that the caller is a member (controller, owner,
+ * Matrix admin or DAO member) of the oracle's domain entity and refuses
+ * everyone else, so listing the tool for every user
  * costs one tool description and grants nothing. Forks that want a different
  * surface (drop `clear`, add `delete_edge`) pass an explicit list via plugin
  * options.
@@ -370,7 +371,8 @@ function buildLazyUpstreamTools(
 
 /**
  * Default factory: authenticates with the per-request UCAN headers from
- * {@link buildMemoryHeaders}, then serves the upstream tool list.
+ * {@link buildMemoryHeaders} (which name the oracle's domain entity,
+ * `entityDid`), then serves the upstream tool list.
  *
  * The first request per isolate connects and lists tools exactly like the
  * old always-fetch path, then snapshots the definitions. Subsequent requests
@@ -384,9 +386,10 @@ function buildLazyUpstreamTools(
  */
 export function createDefaultMemoryMcpFactory(
   memoryMcpUrl: string,
+  entityDid: string,
 ): MemoryMcpFactory {
   return async (runCtx) => {
-    const headers = await buildMemoryHeaders(runCtx, memoryMcpUrl);
+    const headers = await buildMemoryHeaders(runCtx, memoryMcpUrl, entityDid);
     if (!headers) return null;
 
     const cached = toolDefsCache.get(memoryMcpUrl);

package/src/plugins/memory/memory-ucan.ts

@@ -1,6 +1,7 @@
 import type { RuntimeContext } from '../../plugin-api/types';
 import { MEMORY_CAPABILITY } from '../delegated-capabilities';
 import { mintInvocationSafely, resolveServiceDidSafely } from '../ucan-failure';
+import { MEMORY_ENTITY_HEADER } from './memory-entity';
 
 /**
  * Build the headers needed to call the Memory Engine MCP server on behalf of
@@ -9,7 +10,13 @@ import { mintInvocationSafely, resolveServiceDidSafely } from '../ucan-failure';
  *   1. Resolve the memory service DID via `runCtx.ucan.resolveServiceDid`
  *      (delegates the did:web lookup + cache to the UCAN service).
  *   2. Mint an `ixo:memory` invocation using the user's signing key.
- *   3. Layer the resulting Bearer token plus the active `x-room-id`.
+ *   3. Layer the resulting Bearer token, the oracle's domain entity
+ *      (`x-oracle-entity-did`, which keys every memory space on the engine)
+ *      and the active `x-room-id`.
+ *
+ * `entityDid` is the configured `ORACLE_ENTITY_DID` (validated by the memory
+ * plugin's `configSchema`), passed in because `RuntimeContext` carries no
+ * oracle identity. It is never the core's `ORACLE_DID` fallback.
  *
  * UCAN-only — no Matrix-OpenID fallback. If resolution or minting fails for
  * any reason (no signing key, no cached delegation, did:web unresolved,
@@ -22,6 +29,7 @@ import { mintInvocationSafely, resolveServiceDidSafely } from '../ucan-failure';
 export async function buildMemoryHeaders(
   runCtx: RuntimeContext,
   memoryMcpUrl: string,
+  entityDid: string,
 ): Promise<Record<string, string> | null> {
   const memoryDid = await resolveServiceDidSafely(
     runCtx,
@@ -44,6 +52,7 @@ export async function buildMemoryHeaders(
     Authorization: `Bearer ${invocation}`,
     'X-Auth-Type': 'ucan',
     'User-Agent': 'LangChain-MCP-Client/1.0',
+    [MEMORY_ENTITY_HEADER]: entityDid,
   };
   if (runCtx.session.roomId) {
     headers['x-room-id'] = runCtx.session.roomId;

package/src/plugins/memory/memory.plugin.ts

@@ -14,12 +14,16 @@ import {
   fetchMemoryTools,
   type MemoryMcpFactory,
 } from './memory-tools';
+import { oracleEntityDidSchema } from './memory-entity';
 
 const configSchema = z.object({
   MEMORY_MCP_URL: z.string().url('MEMORY_MCP_URL must be a valid HTTP(S) URL.'),
   MEMORY_ENGINE_URL: z
     .string()
     .url('MEMORY_ENGINE_URL must be a valid HTTP(S) URL.'),
+  // The Memory Engine keys every space by the oracle's domain entity; an
+  // oracle without one gets no memory at all, so it fails at boot instead.
+  ORACLE_ENTITY_DID: oracleEntityDidSchema,
 });
 
 const manifest: PluginManifest = {
@@ -51,9 +55,11 @@ const manifest: PluginManifest = {
 export interface MemoryPluginOptions {
   /**
    * Override the MCP-tools factory. Defaults to an HTTP MCP client against
-   * `MEMORY_MCP_URL` authenticated with a per-request UCAN invocation.
+   * `MEMORY_MCP_URL` authenticated with a per-request UCAN invocation and
+   * the oracle's domain entity (`ORACLE_ENTITY_DID`, the engine's
+   * `x-oracle-entity-did` header).
    */
-  mcpFactory?: (memoryMcpUrl: string) => MemoryMcpFactory;
+  mcpFactory?: (memoryMcpUrl: string, entityDid: string) => MemoryMcpFactory;
   /**
    * Filter the upstream tool surface. Defaults to {@link DEFAULT_MEMORY_TOOLS}
    * (search + add + add-oracle-knowledge + delete-episode + clear). Pass an
@@ -62,9 +68,15 @@ export interface MemoryPluginOptions {
   selectedTools?: readonly string[];
 }
 
-function resolveMemoryUrl(config: MergedConfig): string {
+function resolveMemoryConfig(config: MergedConfig): {
+  memoryMcpUrl: string;
+  entityDid: string;
+} {
   const parsed = configSchema.parse(config);
-  return parsed.MEMORY_MCP_URL;
+  return {
+    memoryMcpUrl: parsed.MEMORY_MCP_URL,
+    entityDid: parsed.ORACLE_ENTITY_DID,
+  };
 }
 
 /**
@@ -90,7 +102,10 @@ export class MemoryPlugin extends OraclePlugin {
 
   override readonly autoDetectHint = 'MEMORY_MCP_URL';
 
-  private readonly mcpFactory: (memoryMcpUrl: string) => MemoryMcpFactory;
+  private readonly mcpFactory: (
+    memoryMcpUrl: string,
+    entityDid: string,
+  ) => MemoryMcpFactory;
 
   private readonly selectedTools: readonly string[];
 
@@ -107,8 +122,8 @@ export class MemoryPlugin extends OraclePlugin {
   }
 
   override async getRequestTools(rtCtx: RuntimeContext): Promise<PluginTool[]> {
-    const memoryUrl = resolveMemoryUrl(rtCtx.config);
-    const factory = this.mcpFactory(memoryUrl);
+    const { memoryMcpUrl, entityDid } = resolveMemoryConfig(rtCtx.config);
+    const factory = this.mcpFactory(memoryMcpUrl, entityDid);
     return fetchMemoryTools(rtCtx, factory, this.selectedTools);
   }