@ixo/oracle-runtime-workers 0.15.0 → 0.17.0

package/README.md

@@ -91,7 +91,7 @@ Every variable, binding and migration is explained in
 | `POST/GET /sessions`, `POST/GET /messages/:id`        | The chat API                                          |
 | `GET /runs/:runId`, `GET /sessions/:id/messages`      | Re-join a durable run; one page of a transcript       |
 | `/delegation`, `/models`, `/socket.io/`, `/byo-llm/*` | Delegation, models, realtime channel, BYO LLM         |
-| `POST /channels/turn`                                 | IXO Channels ingress (its own channel UCAN policy)    |
+| `POST /channels/turn`                                 | IXO Channels ingress; refusals carry a `code`         |
 | `POST /messages/:sessionId/:messageId/feedback`       | Anonymous feedback on a reply (when configured)       |
 | `/topic-deliverables/:operationId`                    | Owner-only Topic deliverables (when enabled)          |
 | `GET /a/:id`, `GET /a/:id/data`                       | Artefact links opened from chat apps (public)         |
@@ -136,6 +136,9 @@ lifetime are in [operations](docs/operations.md).
   deliverable API, admin-plane tools, anonymous feedback, the POD Creator
   and ixo-transaction plugins (see the pages above and
   [node-parity](docs/node-parity.md#workers-only)).
+- Observe-only domain context (off by default): the oracle's and the
+  selected subject's anchored `domain.md` in the prompt, with provenance
+  ([configuration](docs/configuration.md#domain-context-observe-only-rollout)).
 - Open: the memory engine's recall ranking on accounts with a long history;
   the storage cost of task-holding users at scale (R2 page tier, see
   [architecture](docs/architecture.md#storage-cost-planning)).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.15.0",
+  "version": "0.17.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": {
@@ -34,6 +34,7 @@
     "@blocknote/server-util": "0.29.1",
     "@composio/core": "0.10.0",
     "@composio/langchain": "0.9.2",
+    "@ixo/domain.md": "^0.3.1",
     "@ixo/editor": "6.0.1",
     "@ixo/matrix-bot-workers-sdk": "0.7.0",
     "@ixo/matrix-crdt": "^1.2.5",
@@ -52,12 +53,13 @@
     "linkedom": "^0.18.12",
     "marked": "^16.4.0",
     "matrix-js-sdk": "^42.2.0",
+    "multiformats": "14.0.4",
     "superjson": "1.13.3",
     "wa-sqlite": "1.0.0",
     "yjs": "13.6.32",
     "zod": "^4.4.3",
-    "@ixo/common": "1.6.0",
     "@ixo/ixo-transaction": "0.1.0",
+    "@ixo/common": "1.6.0",
     "@ixo/ucan": "2.2.1"
   },
   "devDependencies": {

package/src/channels/auth.ts

@@ -58,7 +58,11 @@ export async function authenticateChannel(
     token.length > 32_000 ||
     headers.get('x-auth-type')?.toLowerCase() !== 'ucan'
   )
-    throw new ChannelError(401, 'A channel UCAN invocation is required');
+    throw new ChannelError(
+      401,
+      'A channel UCAN invocation is required',
+      'unauthorized',
+    );
   const validator = await createUCANValidator({
     serverDid: config.oracleDid,
     rootIssuers: ['*'],
@@ -88,7 +92,11 @@ export async function authenticateChannel(
     chain[1] !== config.channelDid ||
     result.invoker !== config.channelDid
   )
-    throw new ChannelError(401, 'Invalid user-rooted channel invocation');
+    throw new ChannelError(
+      401,
+      'Invalid user-rooted channel invocation',
+      'unauthorized',
+    );
   const now = Math.floor(Date.now() / 1000);
   const invocation = await parseDelegation(token);
   const proof = invocation.proofs[0];
@@ -109,6 +117,7 @@ export async function authenticateChannel(
     throw new ChannelError(
       401,
       'A bounded, direct user channel grant is required',
+      'unauthorized',
     );
   if (
     !result.expiration ||
@@ -121,6 +130,7 @@ export async function authenticateChannel(
     throw new ChannelError(
       401,
       'Channel invocations must expire within 60 seconds',
+      'unauthorized',
     );
   const nb = result.capability?.nb;
   if (
@@ -130,7 +140,11 @@ export async function authenticateChannel(
     nb.bindingRevision !== input.bindingRevision ||
     nb.oracleDid !== config.oracleDid
   )
-    throw new ChannelError(403, 'Channel scope does not match this request');
+    throw new ChannelError(
+      403,
+      'Channel scope does not match this request',
+      'scope_mismatch',
+    );
   const hash = await channelRequestHash(raw);
   if (
     result.facts?.length !== 1 ||
@@ -140,6 +154,7 @@ export async function authenticateChannel(
     throw new ChannelError(
       403,
       'Invocation does not authorize this request body',
+      'scope_mismatch',
     );
   return {
     userDid,
@@ -168,7 +183,11 @@ export function channelAuthConfig(
   >,
 ): ChannelAuthConfig {
   if (!env.CHANNEL_SERVICE_DID)
-    throw new ChannelError(503, 'Channels are not configured');
+    throw new ChannelError(
+      503,
+      'Channels are not configured',
+      'not_configured',
+    );
   const resolver = createCompositeDIDResolver([
     sharedIxoDIDResolver(env.BLOCKSYNC_GRAPHQL_URL),
     channelWebResolver,
@@ -204,15 +223,23 @@ export async function assertActiveChannelBinding(
   >,
 ): Promise<void> {
   if (!identity.channel)
-    throw new ChannelError(403, 'Channel identity is required');
+    throw new ChannelError(
+      403,
+      'Channel identity is required',
+      'identity_required',
+    );
   if (!env.AUTH_HUB_CHANNEL_SERVICE_KEY || (!env.AUTH_HUB && !env.AUTH_HUB_URL))
-    throw new ChannelError(503, 'Channel binding validation is not configured');
+    throw new ChannelError(
+      503,
+      'Channel binding validation is not configured',
+      'not_configured',
+    );
   const url = new URL(
     '/api/internal/channels/validate-binding',
     env.AUTH_HUB_URL ?? 'https://auth-hub.internal',
   );
   if (url.protocol !== 'https:')
-    throw new ChannelError(503, 'Auth Hub requires HTTPS');
+    throw new ChannelError(503, 'Auth Hub requires HTTPS', 'not_configured');
   const request = new Request(url, {
     method: 'POST',
     headers: {
@@ -235,15 +262,31 @@ export async function assertActiveChannelBinding(
       ? env.AUTH_HUB.fetch(request)
       : fetch(request));
   } catch {
-    throw new ChannelError(503, 'Channel binding validation is unavailable');
+    throw new ChannelError(
+      503,
+      'Channel binding validation is unavailable',
+      'binding_check_unavailable',
+    );
   }
   if (!response.ok)
-    throw new ChannelError(503, 'Channel binding validation is unavailable');
+    throw new ChannelError(
+      503,
+      'Channel binding validation is unavailable',
+      'binding_check_unavailable',
+    );
   const parsed = BindingVerdict.safeParse(await response.json());
   if (!parsed.success)
-    throw new ChannelError(503, 'Invalid channel binding validation response');
+    throw new ChannelError(
+      503,
+      'Invalid channel binding validation response',
+      'binding_check_unavailable',
+    );
   if (!parsed.data.active)
-    throw new ChannelError(403, 'Channel binding is inactive');
+    throw new ChannelError(
+      403,
+      'Channel binding is inactive',
+      'binding_inactive',
+    );
 }
 
 /**

package/src/channels/contract.ts

@@ -66,34 +66,130 @@ export interface ChannelTurnResponse {
   plan?: ReplyPlan;
 }
 
+export type ChannelErrorStatus =
+  | 400
+  | 401
+  | 403
+  | 404
+  | 409
+  | 410
+  | 413
+  | 428
+  | 429
+  | 503;
+
+/**
+ * The machine-readable reason a channel turn was refused. The gateway maps
+ * a refusal by `code` first and by HTTP status second. 428 (Precondition
+ * Required) means a precondition on the user's side is missing: fix it
+ * (authorize the oracle again, finish setting up the Companion room) and
+ * retry; it is never a transient outage.
+ *
+ * | code                              | status | meaning                                               |
+ * | --------------------------------- | ------ | ----------------------------------------------------- |
+ * | `invalid_request`                 | 400    | body missing, not UTF-8, not JSON, or the wrong shape |
+ * | `unauthorized`                    | 401    | no valid user-rooted channel invocation               |
+ * | `scope_mismatch`                  | 403    | the invocation does not cover this binding or body    |
+ * | `identity_mismatch`               | 403    | the channel identity does not match the request       |
+ * | `identity_required`               | 403    | the binding check got no channel identity             |
+ * | `binding_inactive`                | 403    | the Auth Hub reports the binding inactive             |
+ * | `channel_grant_not_tool_authority`| 403    | a channel request carried a delegation header         |
+ * | `session_not_found`               | 404    | the session is not the user's Companion session       |
+ * | `request_conflict`                | 409    | the request id already belongs to another message     |
+ * | `session_conflict`                | 409    | the channel is already bound to another session       |
+ * | `room_not_encrypted`              | 409    | the Companion room is not end-to-end encrypted        |
+ * | `response_expired`                | 410    | the run was pruned; the request cannot run again      |
+ * | `request_too_large`               | 413    | the body is over 64 kB                                |
+ * | `room_not_ready`                  | 428    | the user has no Companion room yet                    |
+ * | `delegation_required`             | 428    | no usable delegation to this oracle (see below)       |
+ * | `rate_limited`                    | 429    | too many requests for this user                       |
+ * | `not_configured`                  | 503    | channels or binding validation are not configured     |
+ * | `binding_check_unavailable`       | 503    | the Auth Hub binding check failed or answered badly   |
+ * | `unavailable`                     | 503    | any other failure (the shell logs it)                 |
+ */
+export type ChannelErrorCode =
+  | 'invalid_request'
+  | 'unauthorized'
+  | 'scope_mismatch'
+  | 'identity_mismatch'
+  | 'identity_required'
+  | 'binding_inactive'
+  | 'channel_grant_not_tool_authority'
+  | 'session_not_found'
+  | 'request_conflict'
+  | 'session_conflict'
+  | 'room_not_encrypted'
+  | 'response_expired'
+  | 'request_too_large'
+  | 'room_not_ready'
+  | 'delegation_required'
+  | 'rate_limited'
+  | 'not_configured'
+  | 'binding_check_unavailable'
+  | 'unavailable';
+
 export type ChannelTurnOutcome =
   | { ok: true; result: ChannelTurnResponse }
   | {
       ok: false;
-      status: 400 | 401 | 403 | 404 | 409 | 410 | 413 | 429 | 503;
+      status: ChannelErrorStatus;
+      code: ChannelErrorCode;
       message: string;
     };
 
 export class ChannelError extends Error {
   constructor(
-    readonly status: 400 | 401 | 403 | 404 | 409 | 410 | 413 | 429 | 503,
+    readonly status: ChannelErrorStatus,
     message: string,
+    readonly code: ChannelErrorCode,
   ) {
     super(message);
+    this.name = 'ChannelError';
   }
 }
 
+/**
+ * The least lifetime a delegation must have left for a channel turn to be
+ * admitted (seconds): a turn, its tool calls and its owner-copy flush must
+ * not outlive the delegation they run under.
+ */
+export const CHANNEL_DELEGATION_MIN_REMAINING_SECONDS = 900;
+
+/** The user's delegation to this oracle as the user object holds it. */
+export interface ChannelDelegation {
+  raw?: string;
+  /** Unix seconds: the delegation's effective expiry; absent = unknown. */
+  expiration?: number;
+}
+
+export function delegationRequiredError(): ChannelError {
+  return new ChannelError(
+    428,
+    'Companion delegation required: the user must authorize this oracle again',
+    'delegation_required',
+  );
+}
+
 /**
  * A channel turn runs under the user's stored delegation to this oracle,
- * like a Matrix turn. Without one there is no tool authority to run under;
- * the turn is refused with an explicit error instead of running degraded.
+ * like a Matrix turn. Without one, with an unknown expiry, or with less than
+ * `CHANNEL_DELEGATION_MIN_REMAINING_SECONDS` left, there is no tool
+ * authority to run under: the turn is refused with an explicit 428
+ * `delegation_required` instead of running degraded (memory, files and the
+ * sandbox would fail silently).
  */
-export function requireChannelDelegation(present: boolean): void {
-  if (!present)
-    throw new ChannelError(
-      409,
-      'Companion delegation required: the user must authorize this oracle again',
-    );
+export function requireChannelDelegation(
+  delegation: ChannelDelegation | undefined,
+  nowSeconds: number,
+): void {
+  if (
+    !delegation?.raw ||
+    typeof delegation.expiration !== 'number' ||
+    !Number.isFinite(delegation.expiration) ||
+    delegation.expiration <=
+      nowSeconds + CHANNEL_DELEGATION_MIN_REMAINING_SECONDS
+  )
+    throw delegationRequiredError();
 }
 
 export async function channelRequestHash(raw: string): Promise<string> {
@@ -108,7 +204,12 @@ export async function channelRequestHash(raw: string): Promise<string> {
 
 export async function readChannelBody(request: Request): Promise<string> {
   const reader = request.body?.getReader();
-  if (!reader) throw new ChannelError(400, 'A channel turn is required');
+  if (!reader)
+    throw new ChannelError(
+      400,
+      'A channel turn is required',
+      'invalid_request',
+    );
   const chunks: Uint8Array[] = [];
   let size = 0;
   while (true) {
@@ -117,7 +218,11 @@ export async function readChannelBody(request: Request): Promise<string> {
     size += chunk.value.byteLength;
     if (size > 64_000) {
       await reader.cancel();
-      throw new ChannelError(413, 'Channel request is too large');
+      throw new ChannelError(
+        413,
+        'Channel request is too large',
+        'request_too_large',
+      );
     }
     chunks.push(chunk.value);
   }
@@ -132,6 +237,10 @@ export async function readChannelBody(request: Request): Promise<string> {
       bytes,
     );
   } catch {
-    throw new ChannelError(400, 'Channel request must be UTF-8');
+    throw new ChannelError(
+      400,
+      'Channel request must be UTF-8',
+      'invalid_request',
+    );
   }
 }

package/src/channels/turns.ts

@@ -23,7 +23,10 @@ interface ReceiptRow extends Record<string, string | number | null> {
 export interface ChannelTurnsHost {
   createSession(identity: TurnIdentity, markerTxnId: string): Promise<string>;
   assertSession(identity: TurnIdentity, sessionId: string): Promise<void>;
-  /** Throws a `ChannelError` when the user has no stored delegation for this oracle. */
+  /**
+   * Throws a `ChannelError` (428 `delegation_required`) when the user has no
+   * usable delegation for this oracle: none, or one too close to expiry.
+   */
   requireDelegation(identity: TurnIdentity): Promise<void>;
   getRun(runId: string): Promise<RunRecord | undefined>;
   /** The Reply Plan (JSON) a finished run was built into, if any. */
@@ -167,6 +170,7 @@ export class ChannelTurns {
       throw new ChannelError(
         403,
         'Channel identity does not match this request',
+        'identity_mismatch',
       );
     const runId = `channel_${await channelRequestHash(JSON.stringify([input.bindingId, input.requestId]))}`;
     // Checked before a receipt is written: the receipt of a pruned run is
@@ -175,6 +179,7 @@ export class ChannelTurns {
       throw new ChannelError(
         410,
         'Channel response has expired; this request cannot execute again',
+        'response_expired',
       );
     const admitted = await this.db.run(
       `INSERT OR IGNORE INTO channel_requests
@@ -191,6 +196,7 @@ export class ChannelTurns {
       throw new ChannelError(
         409,
         'This request ID already belongs to another message',
+        'request_conflict',
       );
     let sessionId = receipt.session_id;
     // The session is checked when this request is bound to it, and again
@@ -203,7 +209,11 @@ export class ChannelTurns {
         [input.bindingId],
       );
       if (binding && input.sessionId && binding.session_id !== input.sessionId)
-        throw new ChannelError(409, 'This channel already has another session');
+        throw new ChannelError(
+          409,
+          'This channel already has another session',
+          'session_conflict',
+        );
       sessionId =
         binding?.session_id ??
         input.sessionId ??

package/src/core/budgeted-llm.ts

@@ -2,18 +2,26 @@
  * The turn's LLM adapter, metered: every model it hands out carries a
  * callback that reserves the call against the `TurnBudget` before the
  * provider is contacted and settles the reservation to the provider's
- * reported usage when the call ends. Helper models (summarizer, attachment
+ * reported usage when the call ends. The reservation refuses a call only
+ * once the turn is aborted or past its deadline; the tokens are accounted
+ * for the turn's usage report, never limited. Helper models (summarizer, attachment
  * extraction, a plugin's own `ctx.llm.get`) are covered the same way as the
  * main model, since they all come from this adapter.
  *
  * The same handler is also put in the graph's run config (`callbacks`) so a
  * model the host constructed elsewhere and passed in directly is still
  * charged; a call reported through both paths is counted once.
+ *
+ * The handler also traces each call for operators: `[llm] start` and
+ * `[llm] end … in N ms` at debug level, and `[llm] … still running after
+ * N s` every minute while a call is open, so a stalled call can be told
+ * from a long one. Only the role, model id and tags are logged — never
+ * message content or credentials.
  */
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { LLMResult } from '@langchain/core/outputs';
-import type { ChatOpenAIFields, ModelRole } from '../plugin-api/types';
+import type { ChatOpenAIFields, Logger, ModelRole } from '../plugin-api/types';
 import {
   estimateContentTokens,
   messageContentTokens,
@@ -21,6 +29,13 @@ import {
 } from './context-budget';
 import type { LlmAdapter } from './runtime-context';
 import type { TurnBudget } from './turn-budget';
+import { NOOP_LOGGER } from './utils';
+
+/** How often an open model call is reported as still running. */
+export const LLM_HEARTBEAT_MS = 60_000;
+
+/** Metadata key `budgetedLlm` stamps on the models it hands out. */
+const ROLE_METADATA_KEY = 'oracle_model_role';
 
 export interface BudgetedLlmOptions {
   budget: TurnBudget;
@@ -28,11 +43,19 @@ export interface BudgetedLlmOptions {
   outputReserveTokens: number;
   /** The turn's abort signal: a call after the abort is refused before it starts. */
   signal?: AbortSignal;
+  /** Receives the per-call trace (`[llm] start` / `end` / still running). */
+  logger?: Logger;
 }
 
 export interface BudgetedLlm extends LlmAdapter {
   /** Put this in the run config's `callbacks` as well. */
   readonly callback: BaseCallbackHandler;
+  /**
+   * End of the turn: clears every heartbeat still open and the abort
+   * listener. LangChain reports no end for a stream its consumer stopped
+   * reading early, and a live interval keeps the object resident.
+   */
+  dispose(): void;
 }
 
 /**
@@ -128,7 +151,10 @@ function reportedTotalTokens(output: LLMResult): number | undefined {
 
 class TurnBudgetHandler extends BaseCallbackHandler {
   name = 'TurnBudgetHandler';
-  /** A refused reservation must fail the model call, not be logged and ignored. */
+  /**
+   * A refused reservation (aborted turn, passed deadline) must fail the
+   * model call, not be logged and ignored.
+   */
   raiseError = true;
   awaitHandlers = true;
   private readonly reservations = new Map<
@@ -137,9 +163,75 @@ class TurnBudgetHandler extends BaseCallbackHandler {
   >();
   /** Tool-schema estimate per tool list, for this turn (see `toolListKey`). */
   private readonly toolTokens = new Map<string, number>();
+  /** Open calls, for the trace: what they are, when they started, their heartbeat. */
+  private readonly open = new Map<
+    string,
+    {
+      what: string;
+      started: number;
+      heartbeat: ReturnType<typeof setInterval>;
+    }
+  >();
+  private readonly logger: Logger;
+  private readonly onAbort = (): void => this.closeAll();
 
   constructor(private readonly options: BudgetedLlmOptions) {
     super();
+    this.logger = options.logger ?? NOOP_LOGGER;
+    // A call the abort cut short may never report its end; its heartbeat
+    // must not outlive the turn (a live timer keeps the object resident).
+    options.signal?.addEventListener('abort', this.onAbort, { once: true });
+  }
+
+  dispose(): void {
+    this.closeAll();
+    this.options.signal?.removeEventListener('abort', this.onAbort);
+  }
+
+  private traceStart(
+    runId: string,
+    extraParams: Record<string, unknown> | undefined,
+    tags: string[] | undefined,
+    metadata: Record<string, unknown> | undefined,
+  ): void {
+    const role = metadata?.[ROLE_METADATA_KEY];
+    const invocation = extraParams?.invocation_params;
+    const invocationModel =
+      invocation && typeof invocation === 'object' && 'model' in invocation
+        ? invocation.model
+        : undefined;
+    const model =
+      typeof invocationModel === 'string'
+        ? invocationModel
+        : typeof metadata?.ls_model_name === 'string'
+          ? metadata.ls_model_name
+          : 'unknown';
+    const what = `role=${typeof role === 'string' ? role : 'unknown'} model=${model}`;
+    this.logger.debug?.(
+      `[llm] start ${what} tags=${(tags ?? []).join(',') || '-'}`,
+    );
+    const started = Date.now();
+    const heartbeat = setInterval(() => {
+      this.logger.log(
+        `[llm] ${what} still running after ${Math.round((Date.now() - started) / 1000)} s`,
+      );
+    }, LLM_HEARTBEAT_MS);
+    this.open.set(runId, { what, started, heartbeat });
+  }
+
+  private traceEnd(runId: string, outcome: 'end' | 'error'): void {
+    const call = this.open.get(runId);
+    if (!call) return;
+    clearInterval(call.heartbeat);
+    this.open.delete(runId);
+    this.logger.debug?.(
+      `[llm] ${outcome} ${call.what} in ${Date.now() - call.started} ms`,
+    );
+  }
+
+  private closeAll(): void {
+    for (const call of this.open.values()) clearInterval(call.heartbeat);
+    this.open.clear();
   }
 
   handleChatModelStart(
@@ -148,7 +240,7 @@ class TurnBudgetHandler extends BaseCallbackHandler {
     runId: string,
     _parentRunId?: string,
     extraParams?: Record<string, unknown>,
-    _tags?: string[],
+    tags?: string[],
     metadata?: Record<string, unknown>,
   ): void {
     // The handler can reach the same call twice (model-level and run-level
@@ -167,9 +259,12 @@ class TurnBudgetHandler extends BaseCallbackHandler {
       tokens,
       summary: metadata?.lc_source === SUMMARIZATION_SOURCE,
     });
+    // Traced only once admitted: a refused call never starts a heartbeat.
+    this.traceStart(runId, extraParams, tags, metadata);
   }
 
   handleLLMEnd(output: LLMResult, runId: string): void {
+    this.traceEnd(runId, 'end');
     const reservation = this.reservations.get(runId);
     if (reservation === undefined) return;
     this.reservations.delete(runId);
@@ -179,6 +274,7 @@ class TurnBudgetHandler extends BaseCallbackHandler {
   }
 
   handleLLMError(_error: unknown, runId: string): void {
+    this.traceEnd(runId, 'error');
     const reservation = this.reservations.get(runId);
     this.reservations.delete(runId);
     // A failed call keeps its reservation: the provider may have consumed
@@ -186,7 +282,7 @@ class TurnBudgetHandler extends BaseCallbackHandler {
     // is the exception: the summarizer swallows the failure, the turn goes on
     // with its history unchanged and does not try again (summarization.ts),
     // so its reservation — the whole history it was handed — is given back
-    // instead of starving the rest of the turn.
+    // rather than reported as usage of the turn.
     if (reservation?.summary)
       this.options.budget.releaseModel(reservation.tokens);
   }
@@ -214,8 +310,21 @@ export function budgetedLlm(
   const callback = new TurnBudgetHandler(options);
   return {
     callback,
+    dispose: () => callback.dispose(),
     get(role: ModelRole, params?: ChatOpenAIFields): BaseChatModel {
-      const model = adapter.get(role, params);
+      // The role rides on the model's run metadata, for the call trace. It
+      // goes in through the constructor params: `ChatOpenAI.bindTools`
+      // rebuilds the model from them, dropping anything set afterwards. The
+      // instance is stamped too, for adapters that ignore params.
+      const callerMetadata: unknown = params?.metadata;
+      const metadata = {
+        ...(callerMetadata && typeof callerMetadata === 'object'
+          ? callerMetadata
+          : {}),
+        [ROLE_METADATA_KEY]: String(role),
+      };
+      const model = adapter.get(role, { ...params, metadata });
+      model.metadata = { ...model.metadata, ...metadata };
       attach(model, callback);
       return model;
     },