@ixo/oracle-runtime-workers 0.33.1 → 0.34.0

package/README.md

@@ -104,22 +104,22 @@ lifetime are in [operations](docs/operations.md).
 
 ## Documentation
 
-| Page                                                     | What it covers                                                                                     |
-| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| [architecture](docs/architecture.md)                     | The objects, the gateway split, self-sovereign storage, cost model, workerd rules, tasks           |
-| [node-parity](docs/node-parity.md)                       | What is identical to the Node runtime, what differs, what is Workers-only, what is not ported      |
-| [configuration](docs/configuration.md)                   | Wrangler config, migrations, every env var and binding, `createOracleWorker` options, setup        |
-| [operations](docs/operations.md)                         | Routes, status fields, gateway and user-object lifecycle, the ChatGPT proxy, the runbook           |
-| [chat-delivery](docs/chat-delivery.md)                   | Chat replies on WhatsApp and Matrix: profiles, Reply Plans, artefacts and their links              |
-| [channels](docs/channels.md)                             | The IXO Channels ingress: authorization, retries, Reply Plans, Matrix continuity                   |
-| [frontend-bridge](docs/frontend-bridge.md)               | Browser tools and AG-UI actions over the socket: one invocation, one socket, unknown outcomes      |
-| [pod-creator](docs/pod-creator.md)                       | The POD Creator plugin: roles, state in `ctx.kv`, the create path and its launch gate              |
-| [ixo-transaction](docs/ixo-transaction.md)               | The opt-in wallet-signing plugin: chain ids, signing outcomes, the mainnet receipt rule            |
-| [action-proposals](docs/action-proposals.md)             | Action cards: a transfer prepared from chat, signed in the Portal, verified on chain, receipted    |
-| [topic-action-proposals](docs/topic-action-proposals.md) | Topic cards: discussion drafts and claim-access grants as multi-step journals with one-use permits |
-| [chain-tools](docs/chain-tools.md)                       | The bundled `ixo-chain` reader: live balances, batched Blocksync reads, retries and limits         |
-| [testing](docs/testing.md)                               | Unit, harness e2e, the devnet feature matrix, stress                                               |
-| [load-tests](docs/load-tests.md)                         | Measurements and the findings that shaped the gateway                                              |
+| Page                                                     | What it covers                                                                                                          |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| [architecture](docs/architecture.md)                     | The objects, the gateway split, self-sovereign storage, cost model, workerd rules, tasks                                |
+| [node-parity](docs/node-parity.md)                       | What is identical to the Node runtime, what differs, what is Workers-only, what is not ported                           |
+| [configuration](docs/configuration.md)                   | Wrangler config, migrations, every env var and binding, `createOracleWorker` options, setup                             |
+| [operations](docs/operations.md)                         | Routes, status fields, gateway and user-object lifecycle, the ChatGPT proxy, the runbook                                |
+| [chat-delivery](docs/chat-delivery.md)                   | Chat replies on WhatsApp and Matrix: profiles, Reply Plans, artefacts and their links                                   |
+| [channels](docs/channels.md)                             | The IXO Channels ingress: authorization, retries, Reply Plans, Matrix continuity                                        |
+| [frontend-bridge](docs/frontend-bridge.md)               | Browser tools and AG-UI actions over the socket: one invocation, one socket, unknown outcomes                           |
+| [pod-creator](docs/pod-creator.md)                       | The POD Creator plugin: roles, state in `ctx.kv`, the create path and its launch gate                                   |
+| [ixo-transaction](docs/ixo-transaction.md)               | The opt-in wallet-signing plugin: chain ids, signing outcomes, the mainnet receipt rule                                 |
+| [action-proposals](docs/action-proposals.md)             | Action cards: a transfer prepared from chat, signed in the Portal, verified on chain, receipted                         |
+| [topic-action-proposals](docs/topic-action-proposals.md) | Topic cards: discussion drafts and claim-access grants as multi-step journals with one-use permits                      |
+| [chain-tools](docs/chain-tools.md)                       | The bundled `ixo-chain` reader: live balances, the 30 lookup kinds, names from the IXO Names worker, retries and limits |
+| [testing](docs/testing.md)                               | Unit, harness e2e, the devnet feature matrix, stress                                                                    |
+| [load-tests](docs/load-tests.md)                         | Measurements and the findings that shaped the gateway                                                                   |
 
 ## Status (September 2026)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.33.1",
+  "version": "0.34.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": {
@@ -67,9 +67,9 @@
     "protobufjs": "^7.6.5",
     "@ixo/topic-protocol": "1.0.0-rc.8",
     "survey-core": "2.3.11",
-    "@ixo/common": "1.7.1",
+    "@ixo/ixo-transaction": "0.2.0",
     "@ixo/ucan": "2.3.0",
-    "@ixo/ixo-transaction": "0.2.0"
+    "@ixo/common": "1.7.1"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.22.0",

package/src/hub-actions/transfer.ts

@@ -406,6 +406,16 @@ const HUB_TRANSIENT_CODES: Readonly<Record<number, readonly string[]>> = {
   503: ['transfer_unavailable'],
 };
 
+/**
+ * Auth Hub's 409 `sequence_reserved`: another card of the owner's is still
+ * waiting for their review and holds the account's next transaction, so no
+ * new card can be made until that one is approved or declined. Plain words
+ * and the next step; the account's sequence is never named (the model
+ * repeated "reserved transaction sequence" to the person on devnet).
+ */
+export const PENDING_CARD_WORDS =
+  'The owner already has another card waiting for their review, so this one cannot be prepared yet. Tell them, in these words or close to them: “You already have another card waiting for your review. Approve or decline that one first, then I can prepare this.” Do not retry until they have, and never mention sequences or anything technical.';
+
 function hubErrorBody(
   body: unknown,
 ): { error: string; reason?: string } | null {
@@ -436,6 +446,8 @@ const HUB_REASON_MAX = 200;
  *   `not_authorized`, `operation_not_registered`: the transfer or
  *   transaction as asked cannot go ahead (with the Hub's reason, quoted and
  *   labelled as data, see `quoteHubText`);
+ * - 409 `sequence_reserved`: another card is waiting for the owner's
+ *   review; approve or decline it first (`PENDING_CARD_WORDS`);
  * - 409 `sequence_mismatch`, 503 `transfer_unavailable`: temporary, try
  *   again shortly;
  * - any other 409: the account may not use this operation (deterministic,
@@ -484,10 +496,16 @@ export function hubPrepareRefusal(
       undefined,
       status,
     );
+  if (status === 409 && parsed.error === 'sequence_reserved')
+    return new HubActionRefused('refused', PENDING_CARD_WORDS, undefined, 409);
   if (HUB_TRANSIENT_CODES[status]?.includes(parsed.error))
     return new HubActionRefused(
       'refused',
-      `Auth Hub is temporarily unavailable for this (${parsed.error}); try again shortly.`,
+      // A sequence race is named by its effect only: the code would read as
+      // jargon if repeated to the person.
+      parsed.error === 'sequence_mismatch'
+        ? 'Auth Hub could not prepare this just now because the account changed while it was being prepared; try again shortly.'
+        : `Auth Hub is temporarily unavailable for this (${parsed.error}); try again shortly.`,
       undefined,
       status,
     );

package/src/plugins/ixo-chain/denoms.ts

@@ -34,9 +34,10 @@
  */
 import { z } from 'zod';
 import {
+  ReadsInFlight,
   hasBudget,
   throwIfAborted,
-  untilAborted,
+  untilDeadline,
   type ChainCall,
 } from './http';
 import { restJson } from './rest';
@@ -253,15 +254,17 @@ type Lookup<T> = { value: T | null } | 'failed' | 'timeout' | 'aborted';
  * read in flight is shared by every call of the isolate that needs the
  * same key; none is started with less than 1 s of the budget left. A call
  * that joined a read which then timed out or was aborted by its launching
- * turn reads again itself while its own budget allows; it waits on its own
- * turn's abort, never another's.
+ * turn reads again itself while its own budget allows; it waits until its
+ * own deadline at most (`timeout` then), on its own turn's abort, never
+ * another's. A read that died with its actor is replaced by the next
+ * caller past its age limit ({@link ReadsInFlight}).
  */
 class ReadCache<T> {
   private readonly answers = new Map<
     string,
     { lookup: Lookup<T>; expiresAt: number }
   >();
-  private readonly inflight = new Map<string, Promise<Lookup<T>>>();
+  private readonly inflight = new ReadsInFlight<Lookup<T>>();
 
   constructor(private readonly foundTtlMs: number) {}
 
@@ -273,22 +276,22 @@ class ReadCache<T> {
     const id = `${call.restUrl}|${key}`;
     const hit = this.answers.get(id);
     if (hit && hit.expiresAt > Date.now()) return hit.lookup;
-    const running = this.inflight.get(id);
+    const running = this.inflight.joinable(id);
     if (running) {
-      const lookup = await untilAborted(running, call.signal);
+      const lookup = (await untilDeadline(running, call)) ?? 'timeout';
       return (lookup === 'timeout' || lookup === 'aborted') && hasBudget(call)
         ? this.get(call, key, read)
         : lookup;
     }
     if (!hasBudget(call)) return 'timeout';
-    const pending = read()
-      .then((lookup) => {
+    return this.inflight.track(
+      id,
+      call,
+      read().then((lookup) => {
         this.remember(id, lookup);
         return lookup;
-      })
-      .finally(() => this.inflight.delete(id));
-    this.inflight.set(id, pending);
-    return pending;
+      }),
+    );
   }
 
   clear(): void {

package/src/plugins/ixo-chain/http.ts

@@ -1,5 +1,5 @@
 /**
- * The network edge shared by the chain REST and Blocksync reads: one bounded
+ * The network edge shared by the chain REST, Blocksync and names reads: one bounded
  * HTTP exchange per attempt, the retry policy around it, and the per-user
  * permits every attempt takes. Upstream failures become a {@link Failure}
  * the tools hand to the model; nothing here throws for them. Only the
@@ -11,11 +11,12 @@ import {
 } from '../../core/domain-context/transport';
 
 /**
- * Where a read goes. `chain` and `blocksync` are ixo-chain's; the Yoma
- * plugin (`../yoma`) adds the Jambo worker's job list and the documents
- * entities link to (profiles, forms), under the same policy.
+ * Where a read goes. `chain`, `blocksync` and `names` (the IXO Names
+ * worker) are ixo-chain's; the Yoma plugin (`../yoma`) adds the Jambo
+ * worker's job list and the documents entities link to (profiles, forms),
+ * under the same policy.
  */
-export type Source = 'chain' | 'blocksync' | 'job-list' | 'document';
+export type Source = 'chain' | 'blocksync' | 'names' | 'job-list' | 'document';
 
 export type FailureReason =
   | 'rate_limited'
@@ -48,6 +49,12 @@ export const MAX_RETRY_DELAY_MS = 5_000;
 export const TOOL_BUDGET_MS = 20_000;
 /** An attempt, the first one included, is not started with less time than this left in the budget. */
 export const MIN_ATTEMPT_MS = 1_000;
+/**
+ * How long past its call's deadline a read still counts as running. Every
+ * wait inside a read ends by that deadline, so a read older than this will
+ * never settle: it died with the actor that started it.
+ */
+export const READ_GRACE_MS = 1_000;
 /**
  * How long a 429, 502, 503, 504 or network error answers the isolate's
  * other reads of that upstream without asking it.
@@ -66,6 +73,7 @@ export const ERROR_BODY_MAX_BYTES = 8 * 1024;
 const SOURCE_NAME: Record<Source, string> = {
   chain: 'The chain node',
   blocksync: 'Blocksync',
+  names: 'The IXO Names worker',
   'job-list': 'The Yoma job list',
   document: 'The document host',
 };
@@ -158,7 +166,11 @@ export type Attempt<T> =
       ok: false;
       failure: Failure;
       retry: boolean;
-      /** The upstream's `Retry-After`, at most {@link MAX_RETRY_DELAY_MS}. */
+      /**
+       * The upstream's `Retry-After` on a 429/502/503/504. {@link withRetry}
+       * waits it only when the attempt asks for a retry, which
+       * {@link exchange} does for at most {@link MAX_RETRY_DELAY_MS}.
+       */
       retryAfterMs?: number;
       /**
        * A 429, 502, 503, 504 or network error: the upstream is marked
@@ -211,6 +223,70 @@ export function untilAborted<T>(
   );
 }
 
+/**
+ * `shared` as this call waits for it, as {@link untilAborted}, and no longer
+ * than the call's own deadline: `undefined` then. The read may belong to an
+ * actor that died, and such a read never settles.
+ */
+export async function untilDeadline<T>(
+  shared: Promise<T>,
+  call: Pick<ChainCall, 'deadline' | 'signal'>,
+): Promise<T | undefined> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<undefined>((resolve) => {
+    timer = setTimeout(
+      () => resolve(undefined),
+      Math.max(0, call.deadline - Date.now()),
+    );
+  });
+  try {
+    return await untilAborted(Promise.race([shared, deadline]), call.signal);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Reads in flight that other calls may join, by key. The map is shared by
+ * every Durable Object of the isolate, while a read lives and dies with the
+ * actor that started it: a dead one never settles, so its `finally` never
+ * runs. Age recovers it instead: past its call's deadline and
+ * {@link READ_GRACE_MS} a read is forgotten by the next caller, who reads
+ * for itself. A replaced read that settles after all leaves its
+ * replacement in place.
+ */
+export class ReadsInFlight<T> {
+  private readonly reads = new Map<
+    string,
+    { read: Promise<T>; forgetAt: number }
+  >();
+
+  /** The read of `key` a call can join, if one is running. */
+  joinable(key: string): Promise<T> | undefined {
+    const entry = this.reads.get(key);
+    if (!entry) return undefined;
+    if (entry.forgetAt > Date.now()) return entry.read;
+    this.reads.delete(key);
+    return undefined;
+  }
+
+  /** Shares `read`, started for `call`, until it settles; what comes back is what joiners get. */
+  track(key: string, call: ChainCall, read: Promise<T>): Promise<T> {
+    const entry = {
+      read: read.finally(() => {
+        if (this.reads.get(key) === entry) this.reads.delete(key);
+      }),
+      forgetAt: call.deadline + READ_GRACE_MS,
+    };
+    this.reads.set(key, entry);
+    return entry.read;
+  }
+
+  clear(): void {
+    this.reads.clear();
+  }
+}
+
 /** Resolves after `ms`; rejects with the turn's abort reason if it ends first. */
 function sleep(ms: number, signal: AbortSignal): Promise<void> {
   return new Promise((resolve, reject) => {
@@ -349,9 +425,12 @@ const REDIRECTED = 'ixo-chain-redirect';
 
 /* ── per-user permits ─────────────────────────────────────────────────── */
 
-/** One user's permits: how many are taken, and the reads waiting for one, oldest first. */
+/**
+ * One user's permits: those taken, each with the moment it counts as lost,
+ * and the reads waiting for one, oldest first.
+ */
 interface Permits {
-  taken: number;
+  held: Set<{ lostAt: number }>;
   waiting: Set<() => void>;
 }
 
@@ -366,19 +445,18 @@ export function usersReading(): number {
   return permitsByUser.size;
 }
 
-/** Gives a permit back: to the oldest waiting read, else to the user's pool. */
-function releaserOf(user: string, permits: Permits): () => void {
-  let released = false;
+/**
+ * Takes a permit for `call`, as the function that gives it back: to the
+ * oldest waiting read, else to the user's pool.
+ */
+function holdPermit(call: ChainCall, permits: Permits): () => void {
+  const permit = { lostAt: call.deadline + READ_GRACE_MS };
+  permits.held.add(permit);
   return () => {
-    if (released) return;
-    released = true;
+    if (!permits.held.delete(permit)) return;
     const next = permits.waiting.values().next();
-    if (!next.done) {
-      next.value();
-      return;
-    }
-    permits.taken -= 1;
-    if (permits.taken === 0) permitsByUser.delete(user);
+    if (!next.done) next.value();
+    else if (permits.held.size === 0) permitsByUser.delete(call.user);
   };
 }
 
@@ -386,28 +464,29 @@ function releaserOf(user: string, permits: Permits): () => void {
  * One of the call's user's {@link USER_READ_PERMITS} permits, as the
  * function that gives it back; null when none frees up while the call
  * still has {@link MIN_ATTEMPT_MS} of its budget left. Rejects with the
- * turn's abort reason when the turn ends while it waits.
+ * turn's abort reason when the turn ends while it waits. A permit past its
+ * read's deadline and {@link READ_GRACE_MS} is taken back here, by the next
+ * caller: a read that died with its actor never returns the one it holds.
  */
 function takePermit(call: ChainCall): Promise<(() => void) | null> {
-  const permits = permitsByUser.get(call.user) ?? {
-    taken: 0,
-    waiting: new Set<() => void>(),
+  const permits: Permits = permitsByUser.get(call.user) ?? {
+    held: new Set(),
+    waiting: new Set(),
   };
   permitsByUser.set(call.user, permits);
-  if (permits.taken < USER_READ_PERMITS) {
-    permits.taken += 1;
-    return Promise.resolve(releaserOf(call.user, permits));
-  }
+  for (const permit of permits.held)
+    if (permit.lostAt <= Date.now()) permits.held.delete(permit);
+  if (permits.held.size < USER_READ_PERMITS)
+    return Promise.resolve(holdPermit(call, permits));
   return new Promise((resolve, reject) => {
     const leave = () => {
       permits.waiting.delete(handOver);
       clearTimeout(timer);
       call.signal.removeEventListener('abort', onAbort);
     };
-    // A released permit passes straight to this read: `taken` is unchanged.
     const handOver = () => {
       leave();
-      resolve(releaserOf(call.user, permits));
+      resolve(holdPermit(call, permits));
     };
     const onAbort = () => {
       leave();
@@ -546,6 +625,7 @@ async function exchangeHolding(
             retry: false,
             unhealthy: true,
             status,
+            retryAfterMs: wait,
             note: `HTTP ${status}, Retry-After ${Math.ceil(wait / 1000)} s`,
           };
         return {

package/src/plugins/ixo-chain/ixo-chain.plugin.ts

@@ -24,8 +24,18 @@ import {
 } from './http';
 import { KINDS, kindByName, kindNames } from './kinds/registry';
 import type { KindDef } from './kinds/types';
-import { chainLookup, MAX_RESULT_CHARS, shrink } from './lookup';
-import { accountOverview, overviewSchema } from './overview';
+import {
+  chainLookup,
+  cutRow,
+  cutRowAcross,
+  fitNames,
+  MAX_RESULT_CHARS,
+  shrink,
+} from './lookup';
+import { NAMES_URLS, resolveNames } from './names/client';
+import { collectIdentifiers } from './names/collect';
+import type { NameMap } from './names/types';
+import { accountOverview, cutTopRow, overviewSchema } from './overview';
 import { accountOf, type Subject } from './queries';
 import { restJson } from './rest';
 
@@ -54,6 +64,10 @@ const configSchema = z.object({
       if (!parsed.ok) ctx.addIssue({ code: 'custom', message: parsed.error });
     })
     .optional(),
+  /** The IXO Names worker's origin; defaults per `NETWORK`. https only. */
+  IXO_NAMES_URL: rpcOriginSchema.optional(),
+  /** `off` leaves `names` out of every answer; unset or `on` adds them. */
+  IXO_NAMES: z.enum(['on', 'off']).default('on'),
 });
 
 type Network = z.infer<typeof NetworkSchema>;
@@ -73,6 +87,37 @@ export function chainRestUrl(config: MergedConfig): string {
     : CHAIN_REST_URLS[networkOf(config)];
 }
 
+/** The names worker's origin: `IXO_NAMES_URL` when set, else the network's default. */
+export function namesUrl(config: MergedConfig): string {
+  const override = configSchema.shape.IXO_NAMES_URL.safeParse(
+    config.IXO_NAMES_URL,
+  );
+  // The worker's routes sit at the origin's root.
+  return override.success && override.data
+    ? new URL(override.data).origin
+    : NAMES_URLS[networkOf(config)];
+}
+
+/** The longest `x-client-id` the worker takes. */
+const CLIENT_ID_MAX = 64;
+
+/**
+ * The stable id the oracle asks the names worker under:
+ * `ixo-chain-<ORACLE_NAME as a slug, or "oracle">-<network>`, at most 64
+ * characters of `[a-z0-9-]`.
+ */
+export function namesClientId(config: MergedConfig): string {
+  const network = networkOf(config);
+  const name = typeof config.ORACLE_NAME === 'string' ? config.ORACLE_NAME : '';
+  const room = CLIENT_ID_MAX - `ixo-chain--${network}`.length;
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .slice(0, room)
+    .replace(/^-+|-+$/g, '');
+  return `ixo-chain-${slug || 'oracle'}-${network}`;
+}
+
 /**
  * `BLOCKSYNC_GRAPHQL_URL` when it parses as an http(s) URL, else `''`. The
  * env schema only requires a string (the local harness serves http); a
@@ -131,6 +176,49 @@ function invalidInput(detail: string): Failure {
   return { reason: 'invalid_input', detail, retryable: false };
 }
 
+/* ── names ────────────────────────────────────────────────────────────── */
+
+/** The longest a call waits for its names. */
+export const NAMES_BUDGET_MS = 4_000;
+/** What the names wait leaves of the call's budget. */
+export const NAMES_RESERVE_MS = 1_000;
+
+/**
+ * `answer` with the `names` of the identifiers it carries (the user's own
+ * left out), then fitted to {@link MAX_RESULT_CHARS} with `cutRows` cutting
+ * its rows first. Waits at most {@link NAMES_BUDGET_MS}, and never into the
+ * last {@link NAMES_RESERVE_MS} of the call's budget. Unchanged when names
+ * are off, it carries no identifier or none was named in time; only the
+ * turn's abort is thrown.
+ */
+async function withNames<T extends { names?: NameMap }>(
+  call: ChainCall,
+  ctx: RuntimeContext,
+  answer: T,
+  cutRows: () => boolean,
+): Promise<T> {
+  if (ctx.config.IXO_NAMES === 'off') return answer;
+  const identifiers = collectIdentifiers(answer, identityOf(ctx));
+  if (!identifiers.length) return answer;
+  const deadline = Math.min(
+    Date.now() + NAMES_BUDGET_MS,
+    call.deadline - NAMES_RESERVE_MS,
+  );
+  if (deadline <= Date.now()) return answer;
+  const names = await resolveNames(identifiers, {
+    network: call.network,
+    baseUrl: namesUrl(ctx.config),
+    clientId: namesClientId(ctx.config),
+    fetch: call.fetch,
+    deadline,
+    signal: call.signal,
+  });
+  if (!Object.keys(names).length) return answer;
+  answer.names = names;
+  fitNames(answer, cutRows);
+  return answer;
+}
+
 /* ── get_account_balances ─────────────────────────────────────────────── */
 
 // `address` is bounded by `accountOf`'s patterns, not by a length cap here.
@@ -174,6 +262,7 @@ async function getAccountBalances(
     tokens: BalanceToken[];
     moreDenoms?: true;
     truncated?: boolean;
+    names?: NameMap;
   } = {
     ok: true,
     network: call.network,
@@ -185,7 +274,7 @@ async function getAccountBalances(
     ...(moreDenoms ? { moreDenoms: true } : {}),
   };
   shrink(answer, answer.tokens, MAX_RESULT_CHARS);
-  return answer;
+  return withNames(call, ctx, answer, () => cutRow(answer, answer.tokens));
 }
 
 /* ── chain_lookup ─────────────────────────────────────────────────────── */
@@ -216,35 +305,42 @@ function registeredKind(name: string): KindDef {
   return kind;
 }
 
-function lookupHandler(input: unknown, ctx: RuntimeContext): Promise<unknown> {
+async function lookupHandler(
+  input: unknown,
+  ctx: RuntimeContext,
+): Promise<unknown> {
   // The tool layer validates `input` against the schema before the
   // handler runs (an unknown kind or key rejects the whole call there); a
   // mismatch here is a programmer error and throws.
   const { requests } = chainLookupSchema.parse(input);
   const call = chainCall(ctx);
-  return chainLookup(
+  const answer = await chainLookup(
     call,
     identityOf(ctx),
     requests.map(({ kind, args }) => ({ kind: registeredKind(kind), args })),
     { ibcDenoms: ibcDenomsOf(ctx, call) },
   );
+  return withNames(call, ctx, answer, () => cutRowAcross(answer.results));
 }
 
 /* ── get_account_overview ─────────────────────────────────────────────── */
 
-function overviewHandler(
+async function overviewHandler(
   input: unknown,
   ctx: RuntimeContext,
 ): Promise<unknown> {
   // Validated by the tool layer before the handler runs.
   const { address, sections } = overviewSchema.parse(input);
   const call = chainCall(ctx);
-  return accountOverview(
+  const answer = await accountOverview(
     call,
     identityOf(ctx),
     { address, sections },
     { ibcDenoms: ibcDenomsOf(ctx, call) },
   );
+  return answer.ok
+    ? withNames(call, ctx, answer, () => cutTopRow(answer))
+    : answer;
 }
 
 /* ── describe_chain_kinds ─────────────────────────────────────────────── */
@@ -373,20 +469,29 @@ const ORIGIN_RULE =
 const LOOKUP_UNITS_RULE =
   '`amountBaseUnits` is base units (uixo ÷ 1,000,000 = IXO), an `amount` beside a `symbol` converted; 1155 token amounts are whole units.';
 
-/** Says the overview is broad and costly; its units and text rules are `chain_lookup`'s, bound beside it. */
+/**
+ * Every answer's `names` map (`{ [id]: { name, source, selfChosen } }`);
+ * in the guide and the `chain_lookup` description, which the other tools'
+ * descriptions point to. Anyone can pick a self-chosen name, so the short
+ * address beside it tells look-alikes apart.
+ */
+const NAMES_RULE =
+  'Call people and things by their `names` entry; give an address or DID only when asked; beside a `selfChosen` name the user did not pick, also give the short address (first 12 … last 6 characters).';
+
+/** Says the overview is broad and costly; its units, text and names rules are `chain_lookup`'s, bound beside it. */
 const OVERVIEW_DESCRIPTION = [
   "A broad look at an IXO account (default: the user's) by `sections` (default: all): per section: counts, top 3 rows, `more` (the request for the rest).",
-  'Several reads: for one fact use `get_account_balances` or `chain_lookup`. Units and text as in `chain_lookup`.',
+  'Several reads: for one fact use `get_account_balances` or `chain_lookup`. Units, text and names as in `chain_lookup`.',
 ].join(' ');
 
 // The guide states every rule once, briefly; each tool description carries
 // the ones its own answers need, in full.
 const OPERATING_GUIDE = [
   '### IXO chain reader',
-  '- Broad account questions: `get_account_overview`; one fact: `get_account_balances` or `chain_lookup`.',
+  '- Broad account questions: `get_account_overview`; one fact: `get_account_balances` or `chain_lookup`. Batch questions into one `chain_lookup`.',
   "- `chain` answers are live, `blocksync` ones indexed (seconds behind); say each answer's `network`.",
   "- Units: `amount` beside `symbol` is converted (IXO = uixo ÷ 1,000,000), `amountBaseUnits` not; 1155 token amounts are whole units. Say a token's `origin` when two share a symbol; an unverified token's `trace` is only the sending chain's claim, never what the token is.",
-  '- Batch questions into one `chain_lookup`.',
+  `- ${NAMES_RULE}`,
   `- ${READ_ONLY_RULE}`,
   `- ${UNTRUSTED_TEXT_RULE}`,
 ].join('\n');
@@ -396,9 +501,10 @@ const OPERATING_GUIDE = [
  * gateway, `get_account_overview` (several kinds per account section in
  * one lookup call), and `chain_lookup` over a catalogue of kinds — chain
  * REST reads and one batched Blocksync GraphQL document per call — with
- * `describe_chain_kinds` giving each kind's arguments on request. Public
- * data only: no delegation capability is needed. On unless
- * `IXO_CHAIN_TOOLS=off`.
+ * `describe_chain_kinds` giving each kind's arguments on request. Every
+ * answer but the catalogue's also carries `names` for the identifiers in
+ * it, from the IXO Names worker. Public data only: no delegation
+ * capability is needed. On unless `IXO_CHAIN_TOOLS=off`.
  */
 export class IxoChainPlugin extends OraclePlugin {
   readonly name = 'ixo-chain';
@@ -419,6 +525,7 @@ export class IxoChainPlugin extends OraclePlugin {
           '`amount` is display units (IXO = uixo ÷ 1,000,000), `amountBaseUnits` base units; unverified tokens: base units, full denom; `metadataUnavailable`: may still be verified.',
           ORIGIN_RULE,
           NETWORK_RULE,
+          'Names as in `chain_lookup`.',
           READ_ONLY_RULE,
         ].join(' '),
         schema: balancesSchema,
@@ -440,6 +547,7 @@ export class IxoChainPlugin extends OraclePlugin {
           '`source`: `chain` live, `blocksync` indexed (seconds behind).',
           LOOKUP_UNITS_RULE,
           NETWORK_RULE,
+          NAMES_RULE,
           UNTRUSTED_TEXT_RULE,
         ].join(' '),
         schema: chainLookupSchema,