@ixo/oracle-runtime-workers 0.16.0 → 0.17.0

package/README.md

@@ -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.16.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,13 +53,14 @@
     "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/ixo-transaction": "0.1.0",
     "@ixo/common": "1.6.0",
-    "@ixo/ucan": "2.2.1",
-    "@ixo/ixo-transaction": "0.1.0"
+    "@ixo/ucan": "2.2.1"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.22.0",

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;
     },

package/src/core/context-budget.ts

@@ -3,8 +3,12 @@
  * (`context-window.ts`) so that they scale with the model:
  *
  *   - `summarizeAtTokens`  — the history is condensed once it is this large
- *                            (default half the window; Hermes fires at 50%),
- *                            never above what the summarizer may read;
+ *                            (default 60% of the window, whatever its size;
+ *                            never above the request cap nor above what the
+ *                            summarizer reads, which only binds below a
+ *                            ~34k window). The summary is written by the
+ *                            turn's own model (the `summarizer` role), so no
+ *                            second window bounds it;
  *   - `pruneAtTokens`      — above this, old tool results are demoted to
  *                            one-liners in the request (no model call, no
  *                            state change) before the model sees them;
@@ -24,7 +28,7 @@ import { NOOP_LOGGER } from './utils';
 export const CHARS_PER_TOKEN = 4;
 
 export interface ContextKnobs {
-  /** Fraction of the window at which the history is summarized (default 0.5). */
+  /** Fraction of the window at which the history is summarized (default 0.6). */
   summarizeFraction: number;
   /** Fraction of the window above which old tool results are pruned per request (default 0.35). */
   pruneFraction: number;
@@ -47,7 +51,7 @@ export interface ContextKnobs {
 }
 
 export const DEFAULT_CONTEXT_KNOBS: ContextKnobs = {
-  summarizeFraction: 0.5,
+  summarizeFraction: 0.6,
   pruneFraction: 0.35,
   resultCapFraction: 0.12,
   resultCapMaxChars: 200_000,
@@ -66,13 +70,11 @@ export interface ContextBudget {
   requestCapTokens: number;
   outputReserveTokens: number;
   /**
-   * The summarizer's own input limit (what it may read to write the summary):
-   * the smaller of what the main model's request cap and the summarizing
-   * model's own request cap leave, less a margin for the summary prompt.
+   * The summarizer's input limit (what it may read to write the summary):
+   * the main model's request cap less a margin for the summary prompt. The
+   * summarizer is the main model, so its request has the same room.
    */
   summaryInputTokens: number;
-  /** The summarizing model's window, when the host resolved it. */
-  summaryWindowTokens?: number;
   summarizeTriggerMessages?: number;
   keepMessages: number;
 }
@@ -170,34 +172,31 @@ function requestCapFor(
 }
 
 /**
- * The budget for a turn on `resolution.model`. `summarizer` is the window of
- * the model that writes the summary (the `routing` role), resolved the same
- * way: the history it is handed is bounded by its own window too, not only
- * by the main model's. Omitted, the main model's window alone bounds it.
+ * The budget for a turn on `resolution.model`, from that model's window
+ * alone: the summary is written by the same model (the `summarizer` role),
+ * so no other window bounds what it reads.
  */
 export function contextBudgetFor(
   resolution: ContextWindowResolution,
   knobs: ContextKnobs = DEFAULT_CONTEXT_KNOBS,
-  summarizer?: ContextWindowResolution,
 ): ContextBudget {
   const window = resolution.tokens;
   const { requestCapTokens, outputReserveTokens } = requestCapFor(
     window,
     knobs,
   );
-  const summaryRequestCap = summarizer
-    ? Math.min(
-        requestCapTokens,
-        requestCapFor(summarizer.tokens, knobs).requestCapTokens,
-      )
-    : requestCapTokens;
+  // The summarizer keeps only the newest `summaryInputTokens` of what it is
+  // asked to condense (LangChain trims with `strategy: 'last'`; the summary
+  // prompt needs its own room in the request) and drops the rest unread —
+  // the earlier summary first. Summarizing therefore starts no later than
+  // that limit, so the thread's memory is never lost unread. With the
+  // default knobs this only binds below a window of ~34.3k tokens (60% of
+  // the window exceeds 95% less the reply reserve and the prompt margin);
+  // above it the trigger is the plain fraction.
   const summaryInputTokens = Math.max(
     1_000,
-    summaryRequestCap - SUMMARY_PROMPT_MARGIN_TOKENS,
+    requestCapTokens - SUMMARY_PROMPT_MARGIN_TOKENS,
   );
-  // The summarizer keeps only the newest `summaryInputTokens` of what it is
-  // asked to condense and drops the rest unread — the earlier summary first.
-  // Summarizing starts no later than that, so nothing is lost unsummarized.
   const summarizeAtTokens = Math.min(
     Math.floor(window * knobs.summarizeFraction),
     requestCapTokens,
@@ -220,7 +219,6 @@ export function contextBudgetFor(
     requestCapTokens,
     outputReserveTokens,
     summaryInputTokens,
-    ...(summarizer ? { summaryWindowTokens: summarizer.tokens } : {}),
     ...(knobs.summarizeTriggerMessages !== undefined
       ? { summarizeTriggerMessages: knobs.summarizeTriggerMessages }
       : {}),
@@ -284,5 +282,5 @@ export function messageToolCallTokens(
 }
 
 export function describeBudget(b: ContextBudget): string {
-  return `model=${b.model} window=${b.windowTokens} (${b.origin}) summarizeAt=${b.summarizeAtTokens} pruneAt=${b.pruneAtTokens} resultCap=${b.resultCapChars}c requestCap=${b.requestCapTokens} reserve=${b.outputReserveTokens} summaryInput=${b.summaryInputTokens}${b.summaryWindowTokens !== undefined ? ` (summarizer window ${b.summaryWindowTokens})` : ''}`;
+  return `model=${b.model} window=${b.windowTokens} (${b.origin}) summarizeAt=${b.summarizeAtTokens} pruneAt=${b.pruneAtTokens} resultCap=${b.resultCapChars}c requestCap=${b.requestCapTokens} reserve=${b.outputReserveTokens} summaryInput=${b.summaryInputTokens}`;
 }

package/src/core/context-window.ts

@@ -8,22 +8,30 @@
  *
  * Resolution order, first hit wins:
  *
- *   1. an operator override for the exact model id (`MODEL_CONTEXT_OVERRIDES`);
- *   2. the OpenRouter `/models` listing (the same cached fetch that serves
+ *   1. a window **learned** from the provider (below);
+ *   2. an operator override for the exact model id (`MODEL_CONTEXT_OVERRIDES`,
+ *      optional — nothing needs one);
+ *   3. the OpenRouter `/models` listing (the same cached fetch that serves
  *      the price catalog) — for OpenRouter ids directly, and for BYO
  *      provider-native ids through the vendor prefix (`gpt-…` → `openai/gpt-…`);
- *   3. the deployment default (`MODEL_CONTEXT_TOKENS`, 100k unless set).
+ *   4. the built-in table (`BUILTIN_CONTEXT_WINDOWS` in `llm.ts`: the
+ *      curated catalog's `contextTokens` plus every other id the runtime
+ *      sends), looked up the same way — so an unreachable catalogue does not
+ *      shrink a known model to the default;
+ *   5. the deployment default (`MODEL_CONTEXT_TOKENS`, 100k unless set), only
+ *      for a model nothing above knows.
  *
- * On top of that, a window is **learned downwards**: when a provider rejects
- * a request as too long and names its limit, that smaller number is kept for
- * the model (persistently, when the host supplies a store) and wins over the
- * catalog from then on. A provider's error is the one source that is never
+ * A window is **learned downwards**: when a provider rejects a request as
+ * too long and names its limit, that smaller number is kept for the model
+ * (persistently, when the host supplies a store) and wins over every other
+ * source from then on. A provider's error is the one source that is never
  * wrong about its own limit; nothing is ever learned upwards.
  *
  * Modelled on Hermes Agent's `get_model_context_length` chain, trimmed to the
  * sources this runtime has.
  */
 import type { Logger } from '../plugin-api/types';
+import { BUILTIN_CONTEXT_WINDOWS } from './llm';
 import { NOOP_LOGGER } from './utils';
 
 export const DEFAULT_CONTEXT_TOKENS = 100_000;
@@ -35,6 +43,7 @@ export type ContextWindowOrigin =
   | 'override'
   | 'learned'
   | 'catalog'
+  | 'builtin'
   | 'default';
 
 export interface ContextWindowResolution {
@@ -42,7 +51,7 @@ export interface ContextWindowResolution {
   model: string;
   tokens: number;
   origin: ContextWindowOrigin;
-  /** The catalog id that answered, when the catalog did. */
+  /** The catalog (or built-in table) id that answered, when one did. */
   catalogId?: string;
 }
 
@@ -61,15 +70,20 @@ export interface ContextWindowResolverOptions {
   config: ContextWindowConfig;
   /** OpenRouter model id → context window (tokens). */
   catalog: () => Promise<ReadonlyMap<string, number>>;
+  /**
+   * Known model id → context window (tokens), consulted after the catalogue
+   * with the same candidate ids. Default {@link BUILTIN_CONTEXT_WINDOWS}.
+   */
+  builtin?: ReadonlyMap<string, number>;
   learned?: LearnedWindowStore;
   logger?: Logger;
 }
 
 /**
  * `MODEL_CONTEXT_OVERRIDES="openai/gpt-5.6-luna=400000, gpt-5.6-terra=1000000"`
- * — comma-separated `<model id>=<tokens>`; malformed entries are skipped
- * with a warning. `MODEL_CONTEXT_TOKENS` is the default for models nothing
- * else knows (min 16k).
+ * — optional, comma-separated `<model id>=<tokens>`; malformed entries are
+ * skipped with a warning. `MODEL_CONTEXT_TOKENS` is the default for models
+ * nothing else knows (min 16k).
  */
 export function contextWindowConfig(
   env: Record<string, unknown>,
@@ -212,8 +226,14 @@ export class ContextWindowResolver {
     const base = await this.baseline(model, opts.byoProvider);
     const learned = await this.learned(model);
     if (learned !== undefined && learned < base.tokens) {
+      this.logger.debug?.(
+        `[context] ${model}: window ${learned} (learned; ${base.origin} says ${base.tokens})`,
+      );
       return { ...base, tokens: learned, origin: 'learned' };
     }
+    this.logger.debug?.(
+      `[context] ${model}: window ${base.tokens} (${base.origin}${base.catalogId ? ` ${base.catalogId}` : ''})`,
+    );
     return base;
   }
 
@@ -235,13 +255,20 @@ export class ContextWindowResolver {
         `[context] model catalog unavailable: ${error instanceof Error ? error.message : String(error)}`,
       );
     }
+    const candidates = catalogCandidates(model, byoProvider);
     if (catalog) {
-      for (const candidate of catalogCandidates(model, byoProvider)) {
+      for (const candidate of candidates) {
         const tokens = catalog.get(candidate);
         if (tokens !== undefined && isWindow(tokens))
           return { model, tokens, origin: 'catalog', catalogId: candidate };
       }
     }
+    const builtin = this.options.builtin ?? BUILTIN_CONTEXT_WINDOWS;
+    for (const candidate of candidates) {
+      const tokens = builtin.get(candidate);
+      if (tokens !== undefined && isWindow(tokens))
+        return { model, tokens, origin: 'builtin', catalogId: candidate };
+    }
     return { model, tokens: config.defaultTokens, origin: 'default' };
   }
 

package/src/core/domain-context/document.ts

@@ -0,0 +1,100 @@
+/**
+ * Reading a validated `domain.md` frontmatter: the document index entries and
+ * the brief (the bounded slice of the frontmatter the prompt carries).
+ */
+import type { DomainDocument } from '@ixo/domain.md/workers';
+import { z } from 'zod';
+
+const documentEntry = z.object({
+  id: z.string(),
+  uri: z.string().nullable(),
+  cid: z.string().nullable(),
+  required_for_tasks: z.array(z.string()).optional(),
+  freshness: z
+    .object({
+      last_verified: z.string().nullable(),
+      max_age: z.string().nullable(),
+    })
+    .optional(),
+  role: z.string(),
+  media_type: z.string(),
+  disclosure_pass: z.number(),
+  sensitivity: z.string(),
+  access_policy: z.string(),
+  agent_use: z.object({
+    read: z.boolean(),
+    cite: z.boolean(),
+    summarize: z.boolean(),
+  }),
+});
+export type DomainDocumentEntry = z.infer<typeof documentEntry>;
+
+const entriesSchema = z.object({ entries: z.array(documentEntry) });
+
+/** The document index; empty when the frontmatter carries none (or a malformed one). */
+export function entries(
+  document: DomainDocument | undefined,
+): DomainDocumentEntry[] {
+  const result = entriesSchema.safeParse(document?.frontmatter.documents);
+  return result.success ? result.data.entries : [];
+}
+
+/** `value` as a plain object, or `{}`. */
+export function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? { ...value }
+    : {};
+}
+
+/** A linked document is private unless both its access policy and its sensitivity are `public`. */
+export function isPrivateEntry(entry: DomainDocumentEntry): boolean {
+  return entry.access_policy !== 'public' || entry.sensitivity !== 'public';
+}
+
+/**
+ * The parts of the frontmatter the model needs to orient itself: purpose and
+ * boundary, constitution, sources of truth, default agent mode, controllers,
+ * baseline rights, privacy, the critical don'ts and the document index
+ * (without URIs or CIDs). Serialized once per CID by the resolver.
+ */
+export function briefBody(document: DomainDocument): Record<string, unknown> {
+  const front = document.frontmatter;
+  return {
+    domain: front.domain,
+    constitution: front.constitution,
+    source_of_truth: front.source_of_truth,
+    agent_default_mode: front.agent_default_mode,
+    controllers: record(front.controllers).summary,
+    rights: record(front.rights).agent_baseline,
+    privacy: front.privacy,
+    critical_do_not: front.critical_do_not,
+    documents: entries(document).map((entry) => ({
+      id: entry.id,
+      role: entry.role,
+      disclosure_pass: entry.disclosure_pass,
+      required_for_tasks: entry.required_for_tasks,
+      agent_use: entry.agent_use,
+      access_policy: entry.access_policy,
+      sensitivity: entry.sensitivity,
+    })),
+  };
+}
+
+/**
+ * ISO 8601 durations of days and time parts (`P180D`, `PT12H`, `P1DT2H`) in
+ * milliseconds; `undefined` for any other form (years, months and weeks are
+ * calendar-dependent and refused).
+ */
+export function durationMs(value: string): number | undefined {
+  const match = /^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/.exec(
+    value,
+  );
+  if (!match) return undefined;
+  const ms =
+    (Number(match[1] ?? 0) * 86_400 +
+      Number(match[2] ?? 0) * 3_600 +
+      Number(match[3] ?? 0) * 60 +
+      Number(match[4] ?? 0)) *
+    1000;
+  return ms > 0 ? ms : undefined;
+}

package/src/core/domain-context/findings.ts

@@ -0,0 +1,25 @@
+/**
+ * Finding codes are diagnostics that reach the prompt block, the
+ * `router_update` stream and `domain_context_runs`, so every list of them is
+ * bounded where it enters a snapshot: a hostile index can make the validator
+ * report one finding per bad entry, tens of thousands in all.
+ */
+
+/** Most entries one finding list holds, `findings-truncated` included. */
+export const MAX_FINDINGS = 32;
+/** Last entry of a list that was cut to {@link MAX_FINDINGS}. */
+export const FINDINGS_TRUNCATED = 'findings-truncated';
+
+/**
+ * `codes` without duplicates, in first-seen order, at most
+ * {@link MAX_FINDINGS} entries. A cut list (or one that already carried
+ * `findings-truncated`) keeps its first codes and ends with
+ * `findings-truncated`, so a bounded list can be extended and bounded again.
+ */
+export function boundFindings(codes: Iterable<string>): string[] {
+  const unique = new Set(codes);
+  const truncated = unique.delete(FINDINGS_TRUNCATED);
+  const list = [...unique];
+  if (!truncated && list.length <= MAX_FINDINGS) return list;
+  return [...list.slice(0, MAX_FINDINGS - 1), FINDINGS_TRUNCATED];
+}

package/src/core/domain-context/index.ts

@@ -0,0 +1,28 @@
+export type {
+  DocumentRequest,
+  DomainAnchor,
+  DomainCapsuleInspection,
+  DomainContextOptions,
+  DomainContextPins,
+  DomainContextProvenance,
+  DomainDocumentRead,
+  DomainSnapshot,
+  DomainTransport,
+} from './types';
+export {
+  ANCHOR_LOOKUP_TIMEOUT_MS,
+  DEFAULT_ANCHOR_TTL_MS,
+  DomainContextResolver,
+  PINNED_ANCHOR_SOURCE,
+} from './resolver';
+export { createDomainTransport, DOCUMENT_READ_TIMEOUT_MS } from './transport';
+export {
+  DEFAULT_PASS1,
+  DOCUMENT_PAGE_CHARS,
+  DOMAIN_CONTEXT_CLOSE,
+  DOMAIN_CONTEXT_OPEN,
+  DOMAIN_CONTEXT_PRECEDENCE,
+  prepareDomainContext,
+  provenance,
+  RESOLUTION_TIMEOUT_MS,
+} from './turn-context';