@ixo/oracle-runtime-workers 0.33.1 → 0.34.0

package/src/plugins/ixo-chain/names/collect.ts

@@ -0,0 +1,180 @@
+/**
+ * The identifiers a tool result carries, for its `names` map, and the
+ * upkeep of that map while the result is cut to size.
+ *
+ * An identifier is a whole string value in a form the IXO Names worker
+ * names: an `ixo1…` address of an account (42 characters) or a contract
+ * (62), its bech32 checksum valid; a `did:ixo:ixo1…` or `did:ixo:wasm:ixo1…`
+ * DID of such an address; an entity DID (`did:ixo:entity:<32 hex>`); an
+ * `ixovaloper1…` address; or a claim collection id (sent as
+ * `collection:<id>`) in a field named `collectionId`, or the `id` of a
+ * `claim_collection` result or of a `claim_collections` result's items.
+ * A field named `collection` is not read as one: a token's `collection` is
+ * text its minter chose. An address inside a memo or an excerpt is text,
+ * not an identifier. Denoms are not collected: balances already name their
+ * tokens. Who raised a dispute (`disputer`, `disputerDid`) is never named.
+ * A `names` map already on the result is never read as part of it.
+ */
+import type { UserIdentity } from '../../../core/user-identity';
+import { isBech32 } from '../queries';
+import { isRecord } from '../summaries';
+import type { NameMap } from './types';
+
+/** The most identifiers one tool result asks names for, the best placed first. */
+export const MAX_IDENTIFIERS = 40;
+/** An account address, and a contract address. */
+const ADDRESS_LENGTHS: ReadonlySet<number> = new Set([42, 62]);
+/** BIP-173's longest bech32 string. */
+const BECH32_MAX = 90;
+const ACCOUNT_DID_PREFIX = 'did:ixo:';
+const CONTRACT_DID_PREFIX = 'did:ixo:wasm:';
+const ENTITY_DID = /^did:ixo:entity:[0-9a-f]{32}$/;
+const COLLECTION_ID = /^\d{1,12}$/;
+/** Fields whose identifiers are never named: a dispute's filer (the `disputes` kind). */
+const UNNAMED_FIELDS: ReadonlySet<string> = new Set([
+  'disputer',
+  'disputerDid',
+]);
+
+/**
+ * The rows of a `chain_lookup` result whose own `id` is a claim collection
+ * id: the `data` of an answered `claim_collection` request, the
+ * `data.items` of an answered `claim_collections` request.
+ */
+function collectionRowsOf(node: Record<string, unknown>): unknown[] {
+  if (node.ok !== true || !isRecord(node.data)) return [];
+  if (node.kind === 'claim_collection') return [node.data];
+  if (node.kind === 'claim_collections' && Array.isArray(node.data.items))
+    return node.data.items;
+  return [];
+}
+
+/**
+ * `value` (under the key `field`) as an identifier the Names worker names, or
+ * null; `inCollectionRow` when `field` is a key of a collection row (see
+ * {@link collectionRowsOf}).
+ */
+function identifierOf(
+  value: string,
+  field: string | undefined,
+  inCollectionRow: boolean,
+): string | null {
+  if (
+    (field === 'collectionId' || (inCollectionRow && field === 'id')) &&
+    COLLECTION_ID.test(value)
+  )
+    return `collection:${value}`;
+  if (ENTITY_DID.test(value)) return value;
+  const address = value.startsWith(`${CONTRACT_DID_PREFIX}ixo1`)
+    ? value.slice(CONTRACT_DID_PREFIX.length)
+    : value.startsWith(`${ACCOUNT_DID_PREFIX}ixo1`)
+      ? value.slice(ACCOUNT_DID_PREFIX.length)
+      : value;
+  if (ADDRESS_LENGTHS.has(address.length) && isBech32(address, 'ixo'))
+    return value;
+  return address === value &&
+    value.length <= BECH32_MAX &&
+    isBech32(value, 'ixovaloper')
+    ? value
+    : null;
+}
+
+/** One walk over a tool result: where it reports, and the collection rows it has met. */
+interface Walk {
+  found: (identifier: string, rank: number) => void;
+  collectionRows: WeakSet<object>;
+}
+
+/**
+ * Calls `walk.found` for every identifier in `node` with its rank: the
+ * highest list index on its path, so an identifier in the first rows of
+ * every list ranks before one further down any of them. `inCollectionRow`:
+ * `node` is a value directly under a collection row.
+ */
+function visit(
+  node: unknown,
+  rank: number,
+  field: string | undefined,
+  inCollectionRow: boolean,
+  walk: Walk,
+): void {
+  if (field !== undefined && UNNAMED_FIELDS.has(field)) return;
+  if (typeof node === 'string') {
+    const identifier = identifierOf(node, field, inCollectionRow);
+    if (identifier) walk.found(identifier, rank);
+  } else if (Array.isArray(node))
+    node.forEach((item, index) =>
+      visit(item, Math.max(rank, index), field, false, walk),
+    );
+  else if (isRecord(node)) {
+    for (const row of collectionRowsOf(node))
+      if (isRecord(row)) walk.collectionRows.add(row);
+    const isCollectionRow = walk.collectionRows.has(node);
+    for (const [key, inner] of Object.entries(node))
+      visit(inner, rank, key, isCollectionRow, walk);
+  }
+}
+
+/** {@link visit} over a tool result, leaving out its `names` map. */
+function eachIdentifier(
+  result: unknown,
+  found: (identifier: string, rank: number) => void,
+): void {
+  const walk: Walk = { found, collectionRows: new WeakSet() };
+  if (!isRecord(result)) {
+    visit(result, 0, undefined, false, walk);
+    return;
+  }
+  for (const [key, inner] of Object.entries(result))
+    if (key !== 'names') visit(inner, 0, key, false, walk);
+}
+
+/**
+ * The identifiers to name in `result`, without the user's own address and
+ * DID (the model already knows the user): each once, those in the top rows
+ * of lists first (then in the order they appear), at most
+ * {@link MAX_IDENTIFIERS}.
+ */
+export function collectIdentifiers(
+  result: unknown,
+  identity: UserIdentity,
+): string[] {
+  const own = new Set([identity.did]);
+  if (identity.address) {
+    own.add(identity.address);
+    own.add(`${ACCOUNT_DID_PREFIX}${identity.address}`);
+  }
+  // Insertion order is the order of first appearance; the sort is stable.
+  const best = new Map<string, number>();
+  eachIdentifier(result, (identifier, rank) => {
+    if (own.has(identifier)) return;
+    const known = best.get(identifier);
+    if (known === undefined || rank < known) best.set(identifier, rank);
+  });
+  return [...best]
+    .sort((a, b) => a[1] - b[1])
+    .slice(0, MAX_IDENTIFIERS)
+    .map(([identifier]) => identifier);
+}
+
+/** Leaves out the entries of `answer.names` whose identifier is no longer in `answer`. */
+export function pruneNames(answer: { names?: NameMap }): void {
+  const { names } = answer;
+  if (!names) return;
+  const present = new Set<string>();
+  eachIdentifier(answer, (identifier) => present.add(identifier));
+  answer.names = Object.fromEntries(
+    Object.entries(names).filter(([identifier]) => present.has(identifier)),
+  );
+}
+
+/**
+ * Leaves out the last entry of `answer.names` (the map lists the best
+ * placed identifiers first); false when there is none to leave out.
+ */
+export function dropLastName(answer: { names?: NameMap }): boolean {
+  const entries = Object.entries(answer.names ?? {});
+  if (!entries.length) return false;
+  answer.names = Object.fromEntries(entries.slice(0, -1));
+  return true;
+}

package/src/plugins/ixo-chain/names/types.ts

@@ -0,0 +1,25 @@
+/**
+ * The `names` map a tool result carries: the IXO Names worker's name for
+ * each identifier in the result, keyed by the raw identifier, so a name is
+ * never mistaken for the identifier itself. The result keeps every address
+ * and DID as it was.
+ */
+
+export interface NameInfo {
+  /**
+   * The text to call the identifier by, as the worker cleaned it (at most
+   * 120 characters). Still data written by anyone, never instructions.
+   */
+  name: string;
+  /**
+   * Where the worker found it: `table`, `matrix`, `entity`, `entity-alias`,
+   * `entity-account`, `dao`, `validator`, `collection`, `denom-registry`,
+   * `denom-metadata` or `ibc-trace`.
+   */
+  source: string;
+  /** True when the holder picked the name themselves (anyone can pick a look-alike). */
+  selfChosen: boolean;
+}
+
+/** `identifier → name` for one tool result; identifiers without a name are absent. */
+export type NameMap = Record<string, NameInfo>;

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

@@ -9,16 +9,19 @@
  * on its own: its counts and top rows, with the request that reads the
  * rest, or why it failed. The answer is cut to {@link MAX_RESULT_CHARS},
  * top rows first, and an answer without any failure is kept per isolate
- * for {@link OVERVIEW_TTL_MS}.
+ * for {@link OVERVIEW_TTL_MS}. Its `names` are not kept: each call adds
+ * its own to its own copy, cutting top rows ({@link cutTopRow}) to make
+ * room.
  */
 import { z } from 'zod';
 import type { UserIdentity } from '../../core/user-identity';
 import { balancesKind } from './balances';
 import {
+  ReadsInFlight,
   hasBudget,
   throwIfAborted,
   tooLarge,
-  untilAborted,
+  untilDeadline,
   type ChainCall,
   type Failure,
   type Outcome,
@@ -34,6 +37,7 @@ import {
   type LookupOptions,
   type LookupResult,
 } from './lookup';
+import type { NameMap } from './names/types';
 import { accountOf, type Subject } from './queries';
 import type { Absent } from './rest';
 import { isRecord } from './summaries';
@@ -639,6 +643,8 @@ export type OverviewAnswer = {
   address: string;
   subject: Subject;
   sections: Partial<Record<Section, SectionAnswer>>;
+  /** What the identifiers in the answer are called (added after the cache, per call). */
+  names?: NameMap;
 };
 
 export type OverviewFailure = {
@@ -655,6 +661,23 @@ const LEFT_OUT = tooLarge(
   'Left out to keep the answer small; ask for this section on its own.',
 );
 
+type MoreArgs = (part: Part) => Record<string, unknown>;
+
+/** The account is named in `more` only when it is not the user's (the kinds' default). */
+const moreArgsOf =
+  (account: { address: string; subject: Subject }): MoreArgs =>
+  (part) =>
+    account.subject === 'user'
+      ? { ...part.args }
+      : { ...part.args, [part.account]: account.address };
+
+/** The request that reads the rest of `part`. */
+function moreOf(part: Part, moreArgs: MoreArgs): More {
+  return part.tool
+    ? { tool: part.tool, args: moreArgs(part) }
+    : { kind: part.kind.name, args: moreArgs(part) };
+}
+
 /** A part that answered, with its rows. */
 interface Answered {
   part: Part;
@@ -712,7 +735,7 @@ function gather(
 function render(
   gathered: Gathered,
   limit: number,
-  moreArgs: (part: Part) => Record<string, unknown>,
+  moreArgs: MoreArgs,
 ): SectionAnswer {
   const { answered, failed, tagged } = gathered;
   const first = failed[0];
@@ -751,11 +774,7 @@ function render(
     (entry, index) =>
       entry.rows.more || entry.rows.rows.length > (shown[index] ?? 0),
   );
-  const more: More | undefined = !rest
-    ? undefined
-    : rest.part.tool
-      ? { tool: rest.part.tool, args: moreArgs(rest.part) }
-      : { kind: rest.part.kind.name, args: moreArgs(rest.part) };
+  const more = rest ? moreOf(rest.part, moreArgs) : undefined;
   return {
     ok: true,
     summary: { counts, ...(totals ? { totals } : {}), top },
@@ -814,12 +833,7 @@ async function readOverview(
     return index;
   });
   const answers = await runRequests(call, identity, requests, options);
-  // The account is named in `more` only when it is not the user's (the
-  // kinds' default).
-  const moreArgs = (part: Part) =>
-    account.subject === 'user'
-      ? { ...part.args }
-      : { ...part.args, [part.account]: account.address };
+  const moreArgs = moreArgsOf(account);
   const state = sections.map((section) => {
     const results = planned.flatMap((entry, index) =>
       entry.section === section ? [answers[requestOf[index] ?? -1]] : [],
@@ -894,6 +908,48 @@ async function readOverview(
   return answer;
 }
 
+/**
+ * One cut of a rendered answer that must make room (for its `names`): the
+ * last top row of the largest section that still has one, as a smaller
+ * `limit` renders it. The section is marked `truncated`, and its `more`
+ * names the first of its parts with rows not shown. False when no section
+ * has a top row left.
+ */
+export function cutTopRow(answer: OverviewAnswer): boolean {
+  let largest: Section | undefined;
+  let largestSize = -1;
+  for (const section of SECTIONS) {
+    const shown = answer.sections[section];
+    if (!shown?.ok || !shown.summary.top.length) continue;
+    const bytes = size(shown);
+    if (bytes > largestSize) {
+      largest = section;
+      largestSize = bytes;
+    }
+  }
+  const shown = largest ? answer.sections[largest] : undefined;
+  if (!largest || !shown?.ok) return false;
+  const row = shown.summary.top.pop();
+  const parts = PARTS[largest];
+  // A section of several parts tags each top row with its part's `list`.
+  const cut =
+    parts.length > 1
+      ? parts.find((part) => isRecord(row) && row.list === part.list)
+      : parts[0];
+  if (cut) {
+    const moreArgs = moreArgsOf(answer);
+    // -1 when the section has no `more` yet.
+    const current = JSON.stringify(shown.more);
+    const named = parts.findIndex(
+      (part) => JSON.stringify(moreOf(part, moreArgs)) === current,
+    );
+    if (named < 0 || parts.indexOf(cut) < named)
+      shown.more = moreOf(cut, moreArgs);
+  }
+  shown.truncated = true;
+  return true;
+}
+
 /* ── cache ────────────────────────────────────────────────────────────── */
 
 /**
@@ -937,17 +993,19 @@ function timedOut(answer: OverviewAnswer): boolean {
  * Overview answers per isolate: each complete one kept for
  * {@link OVERVIEW_TTL_MS}, at most {@link OVERVIEW_CACHE_LIMIT} (the
  * oldest dropped first). A read in flight is shared by every call that
- * asks the same; a joining call waits on its own turn's abort only and
- * throws its own abort reason. It reads again itself when the shared read
- * ended in the starting turn's abort, or when that read ran out of time
- * and the joining call still has budget. Every call gets its own copy.
+ * asks the same; a joining call waits until its own deadline at most, on
+ * its own turn's abort only, and throws its own abort reason. It reads
+ * again itself when the shared read ended in the starting turn's abort, or
+ * when that read ran out of time and the joining call still has budget. A
+ * read that died with its actor is replaced by the next caller past its
+ * age limit ({@link ReadsInFlight}). Every call gets its own copy.
  */
 class OverviewCache {
   private readonly answers = new Map<
     string,
     { answer: OverviewAnswer; expiresAt: number }
   >();
-  private readonly inflight = new Map<string, Promise<OverviewAnswer>>();
+  private readonly inflight = new ReadsInFlight<OverviewAnswer>();
 
   async get(
     key: string,
@@ -957,19 +1015,22 @@ class OverviewCache {
     const hit = this.answers.get(key);
     if (hit && hit.expiresAt > Date.now()) return structuredClone(hit.answer);
     if (hit) this.answers.delete(key);
-    const running = this.inflight.get(key);
-    if (!running) return this.start(key, read);
-    let shared: OverviewAnswer;
+    const running = this.inflight.joinable(key);
+    if (!running) return this.start(key, call, read);
+    let shared: OverviewAnswer | undefined;
     try {
-      shared = await untilAborted(running, call.signal);
+      shared = await untilDeadline(running, call);
     } catch {
       // This turn's abort, or the starting turn's (the only error a read
       // throws): only this turn's is thrown; after the other's this call
       // reads on its own.
       throwIfAborted(call.signal);
-      return this.start(key, read);
+      return this.start(key, call, read);
     }
-    if (timedOut(shared) && hasBudget(call)) return this.start(key, read);
+    // Its own deadline came first. With no budget left this read asks
+    // nothing: every section is the spent budget's timeout. It is not shared.
+    if (shared === undefined) return read();
+    if (timedOut(shared) && hasBudget(call)) return this.start(key, call, read);
     return structuredClone(shared);
   }
 
@@ -980,17 +1041,14 @@ class OverviewCache {
 
   private async start(
     key: string,
+    call: ChainCall,
     read: () => Promise<OverviewAnswer>,
   ): Promise<OverviewAnswer> {
-    const pending = read();
-    this.inflight.set(key, pending);
-    try {
-      const answer = await pending;
-      if (complete(answer)) this.remember(key, answer);
-      return answer;
-    } finally {
-      if (this.inflight.get(key) === pending) this.inflight.delete(key);
-    }
+    const answer = await this.inflight.track(key, call, read());
+    if (complete(answer)) this.remember(key, answer);
+    // The calls joining this read copy `answer` when they wake; the
+    // caller adds its names to its own copy.
+    return structuredClone(answer);
   }
 
   private remember(key: string, answer: OverviewAnswer): void {