@ixo/oracle-runtime-workers 0.37.2 → 0.39.0

package/src/core/capability-router.ts

@@ -1,29 +1,36 @@
 import {
   AmbiguousDecisionProviderError,
+  CAPABILITY_PRELOAD_BATCH_SIZE,
+  CAPABILITY_PRELOAD_WARM_THRESHOLD,
   CAPABILITY_ROUTER_MODES,
   CAPABILITY_ROUTE_DECISION_NAME,
   DecisionProviderUnavailableError,
-  capabilityRouteDecision,
-  decideCapabilityRoute,
+  capabilityPreloadDecision,
+  decideCapabilityPreload,
   toRoutableCapabilities,
+  type CapabilityPreloadVerdict,
   type CapabilityRouterMode,
+  type DecisionEvaluateOptions,
   type DecisionEvaluator,
   type DecisionTraceOptions,
   type RoutableCapability,
 } from '@ixo/common/ai/decisions';
-import type { Logger } from '../plugin-api/types';
-import { unmetRequirements } from './manifest';
+import type { Logger, PluginManifest } from '../plugin-api/types';
 import type { RegisteredManifest } from './registries';
 
 /**
- * Predicts, before the first model call of a turn, which on-demand plugin the
- * user's message needs and preloads that plugin's tools for the turn, so the
- * model does not spend a round trip on `load_capability`.
+ * Predicts, before the first model call of a turn, every plugin the user's
+ * message needs from what is left to load, so the model does not spend a
+ * round trip on `load_capability`. A plugin it misses is still one
+ * `load_capability` away.
  *
- * The preload is one-turn state only: it is admitted by the capability gate
- * and visible as loaded to tool handlers, but never written to the graph's
- * `loadedPlugins` channel. The router fails open — any evaluation failure
- * preloads nothing and the turn proceeds exactly as without a router.
+ * A preload is a normal load: the turn writes it to the graph's
+ * `loadedPlugins` channel and it stays until a cold turn unloads it, so the
+ * tool list changes once. It costs the cache miss a `load_capability` would,
+ * without the extra call. On a turn the provider's cache has lost anyway it
+ * costs no miss at all, which is why a warm turn asks for a higher score
+ * (`CAPABILITY_ROUTER_WARM_THRESHOLD`). The router fails open — any evaluation
+ * failure preloads nothing and the turn proceeds exactly as without a router.
  */
 export interface CapabilityRouterOptions {
   evaluator: DecisionEvaluator;
@@ -38,26 +45,23 @@ export interface CapabilityRouterOptions {
 
 export interface CapabilityRouteTurn {
   mode: CapabilityRouterMode;
-  /** Every registered manifest; the router picks the routable candidates. */
-  manifests: readonly RegisteredManifest[];
-  /** Plugins the thread has already loaded (the checkpointed channel). */
-  loaded: ReadonlySet<string>;
   /**
-   * Plugins the user's delegation leaves with nothing to use (all of their
-   * tools admin-plane and not granted): never offered to the router. A
-   * function is called only when the router actually evaluates (not when
-   * it is off, or the message is empty), so the host does not compute the
-   * set for nothing.
+   * What a `load_capability` could load right now (`createMainAgent` works
+   * this out from the turn's own tools): the plugins with an on-demand tool
+   * the thread has not loaded, `always` ones with `onDemandTools` included,
+   * that the user's delegation may use.
    */
-  hidden?: ReadonlySet<string> | (() => Promise<ReadonlySet<string>>);
-  /**
-   * The user's delegation, as `ctx.ucan.hasCapability`: a plugin whose
-   * `manifest.requires` it does not grant is never offered (the gate would
-   * refuse every one of its tools). Omitted, `requires` is not checked.
-   */
-  hasCapability?: (resource: string, action: string) => boolean;
+  candidates: readonly RegisteredManifest[];
+  /** The score a preload needs; the calibration profile's when omitted. */
+  threshold?: number;
   /** The user's message text for this turn. */
   text: string;
+  /**
+   * The thread's latest visible turns, oldest first, so a follow-up such as
+   * "send half to Bob" can be routed. Called only when the router evaluates;
+   * when it fails the router evaluates the message alone.
+   */
+  recentTurns?: () => Promise<readonly string[]>;
   requestId: string;
   /** The turn's abort signal; only an awaited (`on`) evaluation is bound to it. */
   signal?: AbortSignal;
@@ -85,35 +89,43 @@ export function capabilityRouterMode(value: unknown): CapabilityRouterMode {
   return CAPABILITY_ROUTER_MODES.find((mode) => mode === value) ?? 'off';
 }
 
+/** The score a preload needs this turn: the operator's, else the default. */
+export function preloadThreshold(
+  cold: boolean,
+  env: {
+    CAPABILITY_ROUTER_COLD_THRESHOLD?: unknown;
+    CAPABILITY_ROUTER_WARM_THRESHOLD?: unknown;
+  },
+): { threshold?: number } {
+  const set = cold
+    ? env.CAPABILITY_ROUTER_COLD_THRESHOLD
+    : env.CAPABILITY_ROUTER_WARM_THRESHOLD;
+  if (typeof set === 'number') return { threshold: set };
+  return cold ? {} : { threshold: CAPABILITY_PRELOAD_WARM_THRESHOLD };
+}
+
 /**
- * The manifests the router may choose from: effectively on-demand plugins the
- * thread has not loaded yet. `always` plugins are already bound and `silent`
- * ones are never surfaced, so predicting them is pointless; a `hidden` one
- * (no tool the user's delegation reaches), or one whose `requires` the
- * delegation (`hasCapability`) does not grant, is not even named to the
- * router.
+ * What the router reads about a plugin: its summary and the `whenToUse` lines
+ * the manifest already carries. The summary alone often leaves out what a
+ * plugin does ("retire tokens", "cancel a reminder"), and a yes/no question
+ * then scores far below the preload threshold.
  */
+function routingSummary(manifest: PluginManifest): string {
+  return manifest.whenToUse.length > 0
+    ? `${manifest.summary} Use when: ${manifest.whenToUse.join(' ')}`
+    : manifest.summary;
+}
+
+/** The Decision's view of the candidates. */
 export function routableCandidates(
-  manifests: readonly RegisteredManifest[],
-  loaded: ReadonlySet<string>,
-  hidden: ReadonlySet<string> = NOTHING,
-  hasCapability?: (resource: string, action: string) => boolean,
+  candidates: readonly RegisteredManifest[],
 ): RoutableCapability[] {
   return toRoutableCapabilities(
-    manifests
-      .filter(
-        ({ pluginName, manifest }) =>
-          (manifest.visibility ?? 'on-demand') === 'on-demand' &&
-          !loaded.has(pluginName) &&
-          !hidden.has(pluginName) &&
-          (hasCapability === undefined ||
-            unmetRequirements(manifest, hasCapability).length === 0),
-      )
-      .map(({ pluginName, manifest }) => ({
-        name: pluginName,
-        title: manifest.title,
-        summary: manifest.summary,
-      })),
+    candidates.map(({ pluginName, manifest }) => ({
+      name: pluginName,
+      title: manifest.title,
+      summary: routingSummary(manifest),
+    })),
   );
 }
 
@@ -144,6 +156,23 @@ function list(names: readonly string[]): string {
   return `[${names.join(', ')}]`;
 }
 
+/** The likeliest candidates, for refitting the threshold from real traffic. */
+function topScores(verdict: CapabilityPreloadVerdict): string {
+  return verdict.scores
+    .slice(0, 3)
+    .map(({ name, probability }) => `${name}:${probability.toFixed(2)}`)
+    .join(',');
+}
+
+/** Splits candidates into lists one Decision request can carry. */
+function batches<T>(items: readonly T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let start = 0; start < items.length; start += size) {
+    chunks.push(items.slice(start, start + size));
+  }
+  return chunks;
+}
+
 export function createCapabilityRouter(
   options: CapabilityRouterOptions,
 ): CapabilityRouter {
@@ -183,47 +212,51 @@ export function createCapabilityRouter(
 
   return async (turn) => {
     if (turn.mode === 'off') return NOTHING;
+    // No score reaches it: nothing to spend a Decision on.
+    if ((turn.threshold ?? 0) > 1) return NOTHING;
     const text = turn.text.trim();
     if (!text) return NOTHING;
-    let hidden: ReadonlySet<string> | undefined;
-    try {
-      hidden =
-        typeof turn.hidden === 'function' ? await turn.hidden() : turn.hidden;
-    } catch (error) {
-      // Fail open like any other router failure: no preload this turn.
-      logger.warn(
-        `[capability-router] request=${turn.requestId} mode=${turn.mode} status=fallback reason=${errorName(error)} (hidden plugins unavailable)`,
-      );
-      return NOTHING;
-    }
-    const capabilities = routableCandidates(
-      turn.manifests,
-      turn.loaded,
-      hidden,
-      turn.hasCapability,
-    );
+    const capabilities = routableCandidates(turn.candidates);
     if (capabilities.length === 0) return NOTHING;
 
-    // The turn is prepared from a checkpoint read without its messages, so
-    // the router sees the current message only; `recentTurns` stays empty.
-    const input = { text, recentTurns: [], capabilities };
     const { requestId } = turn;
+    let recentTurns: string[] = [];
+    const evaluateAll = async (options?: DecisionEvaluateOptions) => {
+      try {
+        recentTurns = [...((await turn.recentTurns?.()) ?? [])];
+      } catch (error) {
+        logger.warn(
+          `[capability-router] request=${requestId} mode=${turn.mode} status=degraded reason=${errorName(error)} (recent turns unavailable)`,
+        );
+      }
+      return Promise.all(
+        batches(capabilities, CAPABILITY_PRELOAD_BATCH_SIZE).map((batch) =>
+          evaluator.evaluate(
+            capabilityPreloadDecision,
+            { text, recentTurns, capabilities: batch },
+            options,
+          ),
+        ),
+      );
+    };
 
     if (turn.mode === 'shadow') {
       const started = now();
       background(
-        evaluator
-          .evaluate(capabilityRouteDecision, input, turn.trace)
-          .then((evaluation) => {
-            const verdict = decideCapabilityRoute(evaluation, capabilities);
+        evaluateAll(turn.trace)
+          .then((evaluations) => {
+            const verdict = decideCapabilityPreload(
+              evaluations,
+              capabilities,
+              turn.threshold,
+            );
             logger.log(
               `[capability-router-shadow] request=${requestId} status=ok ` +
-                `needsCapability=${verdict.needsCapability.toFixed(2)} ` +
-                `capability=${verdict.capability ?? '-'} ` +
-                `capabilityConfidence=${verdict.capabilityConfidence?.toFixed(2) ?? '-'} ` +
-                `wouldPreload=${list(verdict.preload)} reason=${verdict.reason} ` +
+                `top=${topScores(verdict)} ` +
+                `wouldPreload=${list(verdict.preload)} ` +
+                `threshold=${turn.threshold ?? 'profile'} ` +
                 `calibrationProfile=${verdict.calibrationProfileRef ?? '-'} ` +
-                `latencyMs=${now() - started} provider=${evaluation.provider} model=${evaluation.model}`,
+                `latencyMs=${now() - started} provider=${evaluations[0]?.provider} model=${evaluations[0]?.model}`,
             );
             turn.onShadowVerdict?.(verdict.preload);
           })
@@ -240,25 +273,23 @@ export function createCapabilityRouter(
       return NOTHING;
     }
 
+    const started = now();
     try {
-      const evaluation = await evaluator.evaluate(
-        capabilityRouteDecision,
-        input,
-        {
-          ...turn.trace,
-          ...(turn.signal && { signal: turn.signal }),
-        },
+      const evaluations = await evaluateAll({
+        ...turn.trace,
+        ...(turn.signal && { signal: turn.signal }),
+      });
+      const verdict = decideCapabilityPreload(
+        evaluations,
+        capabilities,
+        turn.threshold,
       );
-      const verdict = decideCapabilityRoute(evaluation, capabilities);
-      if (verdict.preload.length === 0) {
-        logger.debug?.(
-          `[capability-router] request=${requestId} mode=on status=none reason=${verdict.reason} candidates=${capabilities.length}`,
-        );
-        return NOTHING;
-      }
       logger.log(
-        `[capability-router] request=${requestId} preloaded=${list(verdict.preload)} candidates=${capabilities.length}`,
+        `[capability-router] request=${requestId} mode=on status=${verdict.preload.length > 0 ? 'ok' : 'none'} ` +
+          `preloaded=${list(verdict.preload)} top=${topScores(verdict)} threshold=${turn.threshold ?? 'profile'} ` +
+          `candidates=${capabilities.length} recentTurns=${recentTurns.length} latencyMs=${now() - started}`,
       );
+      if (verdict.preload.length === 0) return NOTHING;
       return new Set(verdict.preload);
     } catch (error) {
       if (unavailable(error)) {

package/src/core/context-budget.ts

@@ -12,12 +12,23 @@
  *   - `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;
+ *   - `staleResultTurns`   — on a turn that opens after `cacheColdMs` of
+ *                            quiet, tool results older than this many turns
+ *                            leave the request (`read_result` reads them
+ *                            back). Whatever the window: this is about what
+ *                            a call costs, not about what fits;
  *   - `resultCapChars`     — a tool result larger than this is stored whole
  *                            and the model sees head + tail + a handle;
  *   - `requestCapTokens`   — a request that is still larger than this after
  *                            pruning is refused instead of sent to fail;
  *   - `outputReserveTokens`— the room left for the reply.
  *
+ * A large window says nothing about what a request should cost, so the
+ * fractions are bounded in tokens too (`summarizeMaxTokens`, `pruneMaxTokens`,
+ * `resultCapMaxChars`): a million-token window would otherwise never condense
+ * a thread that long ago stopped being worth re-sending, and would pass the
+ * 272k-token point where providers such as OpenAI double the price.
+ *
  * Token counts are chars/4 estimates (`estimateTokensApprox`), never billing.
  */
 import type { Logger } from '../plugin-api/types';
@@ -30,12 +41,34 @@ export const CHARS_PER_TOKEN = 4;
 export interface ContextKnobs {
   /** Fraction of the window at which the history is summarized (default 0.6). */
   summarizeFraction: number;
+  /** Ceiling on the summarize threshold in tokens, whatever the window (default 200,000). */
+  summarizeMaxTokens: number;
   /** Fraction of the window above which old tool results are pruned per request (default 0.35). */
   pruneFraction: number;
+  /** Ceiling on the prune threshold in tokens, whatever the window (default 100,000). */
+  pruneMaxTokens: number;
+  /**
+   * Finished turns whose tool results stay whole when a cold turn trims the
+   * older ones out of the request (default 2; 0 never trims).
+   */
+  staleResultTurns: number;
+  /**
+   * Quiet time after which a turn counts as cold: the provider's prompt
+   * cache is gone, so changing the prefix costs nothing. Default 2,100,000
+   * (35 minutes): on `gpt-5.6-luna`, Bedrock and OpenAI routes alike, a prefix
+   * left idle for 20 minutes still hit and one left for 35 missed. 0 makes
+   * every turn cold.
+   */
+  cacheColdMs: number;
+  /**
+   * Turns an on-demand capability stays loaded without being used (default
+   * 3). It is unloaded on the first cold turn after that; 0 never unloads.
+   */
+  pluginIdleTurns: number;
   /** Fraction of the window one tool result may occupy before it is capped (default 0.12). */
   resultCapFraction: number;
   /**
-   * Ceiling on the result cap in chars (default 200,000 ≈ 50k tokens): a
+   * Ceiling on the result cap in chars (default 64,000 ≈ 16k tokens): a
    * million-token window does not make a half-megabyte tool result a good
    * idea — the rest stays reachable through `read_result`.
    */
@@ -52,9 +85,14 @@ export interface ContextKnobs {
 
 export const DEFAULT_CONTEXT_KNOBS: ContextKnobs = {
   summarizeFraction: 0.6,
+  summarizeMaxTokens: 200_000,
   pruneFraction: 0.35,
+  pruneMaxTokens: 100_000,
+  staleResultTurns: 2,
+  cacheColdMs: 2_100_000,
+  pluginIdleTurns: 3,
   resultCapFraction: 0.12,
-  resultCapMaxChars: 200_000,
+  resultCapMaxChars: 64_000,
   requestFraction: 0.95,
   outputReserveTokens: 8_000,
   keepMessages: 10,
@@ -66,6 +104,9 @@ export interface ContextBudget {
   origin: ContextWindowResolution['origin'];
   summarizeAtTokens: number;
   pruneAtTokens: number;
+  staleResultTurns: number;
+  cacheColdMs: number;
+  pluginIdleTurns: number;
   resultCapChars: number;
   requestCapTokens: number;
   outputReserveTokens: number;
@@ -118,10 +159,37 @@ export function contextKnobs(
       'CONTEXT_SUMMARIZE_FRACTION',
       DEFAULT_CONTEXT_KNOBS.summarizeFraction,
     ),
+    summarizeMaxTokens:
+      int(
+        'CONTEXT_SUMMARIZE_MAX_TOKENS',
+        DEFAULT_CONTEXT_KNOBS.summarizeMaxTokens,
+        1_000,
+      ) ?? DEFAULT_CONTEXT_KNOBS.summarizeMaxTokens,
     pruneFraction: fraction(
       'CONTEXT_PRUNE_FRACTION',
       DEFAULT_CONTEXT_KNOBS.pruneFraction,
     ),
+    pruneMaxTokens:
+      int(
+        'CONTEXT_PRUNE_MAX_TOKENS',
+        DEFAULT_CONTEXT_KNOBS.pruneMaxTokens,
+        1_000,
+      ) ?? DEFAULT_CONTEXT_KNOBS.pruneMaxTokens,
+    staleResultTurns:
+      int(
+        'CONTEXT_STALE_RESULT_TURNS',
+        DEFAULT_CONTEXT_KNOBS.staleResultTurns,
+        0,
+      ) ?? DEFAULT_CONTEXT_KNOBS.staleResultTurns,
+    cacheColdMs:
+      int('CONTEXT_CACHE_COLD_MS', DEFAULT_CONTEXT_KNOBS.cacheColdMs, 0) ??
+      DEFAULT_CONTEXT_KNOBS.cacheColdMs,
+    pluginIdleTurns:
+      int(
+        'CONTEXT_PLUGIN_IDLE_TURNS',
+        DEFAULT_CONTEXT_KNOBS.pluginIdleTurns,
+        0,
+      ) ?? DEFAULT_CONTEXT_KNOBS.pluginIdleTurns,
     resultCapFraction: fraction(
       'CONTEXT_RESULT_CAP_FRACTION',
       DEFAULT_CONTEXT_KNOBS.resultCapFraction,
@@ -199,11 +267,13 @@ export function contextBudgetFor(
   );
   const summarizeAtTokens = Math.min(
     Math.floor(window * knobs.summarizeFraction),
+    knobs.summarizeMaxTokens,
     requestCapTokens,
     summaryInputTokens,
   );
   const pruneAtTokens = Math.min(
     Math.floor(window * knobs.pruneFraction),
+    knobs.pruneMaxTokens,
     summarizeAtTokens,
   );
   return {
@@ -212,6 +282,9 @@ export function contextBudgetFor(
     origin: resolution.origin,
     summarizeAtTokens,
     pruneAtTokens,
+    staleResultTurns: knobs.staleResultTurns,
+    cacheColdMs: knobs.cacheColdMs,
+    pluginIdleTurns: knobs.pluginIdleTurns,
     resultCapChars: Math.min(
       Math.floor(window * knobs.resultCapFraction) * CHARS_PER_TOKEN,
       knobs.resultCapMaxChars,
@@ -226,11 +299,50 @@ export function contextBudgetFor(
   };
 }
 
-/** chars/4 over a message's content, whatever its shape. */
+/**
+ * What one image block costs the model, whatever its byte size. Providers
+ * bill an image by its pixels, not by its base64: every one the runtime
+ * sends is scaled to a 1568 px long edge by the provider (or before, by the
+ * `IMAGES` binding), which is at most ~3,300 tokens on the costliest
+ * provider formula (width × height / 750). Counting the base64 at chars/4
+ * instead made one resized phone photo look like ~128k tokens, enough for
+ * the context guard to refuse the turn on a model with a smaller window.
+ */
+export const IMAGE_BLOCK_TOKENS = 3_300;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * An image content block in any of the shapes a message carries: the
+ * LangChain data block the attachments build (`type: 'image'` with `data`
+ * or `url`) or the OpenAI chat shape (`type: 'image_url'`). File blocks are
+ * not images: a document's cost does follow its size, and native documents
+ * are kept small (`NATIVE_DOCUMENT_MAX_BYTES`).
+ */
+function isImageBlock(block: unknown): boolean {
+  return (
+    isRecord(block) && (block.type === 'image' || block.type === 'image_url')
+  );
+}
+
+/**
+ * chars/4 over a message's content, whatever its shape; each image block
+ * counts {@link IMAGE_BLOCK_TOKENS} instead of its base64.
+ */
 export function estimateContentTokens(content: unknown): number {
   if (typeof content === 'string') return estimateTokensApprox(content);
   if (content == null) return 0;
   try {
+    if (Array.isArray(content) && content.some(isImageBlock)) {
+      const images = content.filter(isImageBlock).length;
+      const rest = content.filter((block) => !isImageBlock(block));
+      return (
+        images * IMAGE_BLOCK_TOKENS +
+        (rest.length ? estimateTokensApprox(JSON.stringify(rest)) : 0)
+      );
+    }
     return estimateTokensApprox(JSON.stringify(content));
   } catch {
     return 0;
@@ -282,5 +394,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}`;
+  return `model=${b.model} window=${b.windowTokens} (${b.origin}) summarizeAt=${b.summarizeAtTokens} pruneAt=${b.pruneAtTokens} staleTurns=${b.staleResultTurns} coldMs=${b.cacheColdMs} pluginIdle=${b.pluginIdleTurns} resultCap=${b.resultCapChars}c requestCap=${b.requestCapTokens} reserve=${b.outputReserveTokens} summaryInput=${b.summaryInputTokens}`;
 }

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

@@ -7,6 +7,7 @@ import { z } from 'zod';
 
 const documentEntry = z.object({
   id: z.string(),
+  name: z.string().optional(),
   uri: z.string().nullable(),
   cid: z.string().nullable(),
   required_for_tasks: z.array(z.string()).optional(),
@@ -51,13 +52,84 @@ export function isPrivateEntry(entry: DomainDocumentEntry): boolean {
   return entry.access_policy !== 'public' || entry.sensitivity !== 'public';
 }
 
+/**
+ * How much of a domain the prompt carries on every call.
+ *
+ * - `compact`: the frontmatter keys `domain.md` §3 lists as "always load",
+ *   without the id lists and vocabulary URIs behind them, and a one-row-per-
+ *   document index. Everything else stays one `read_domain_document` away.
+ * - `full`: the whole brief, with the permissions of every document.
+ */
+export type DomainBriefDetail = 'compact' | 'full';
+
+/** One row of the compact index; permissions only where they are not the open default. */
+function compactEntry(entry: DomainDocumentEntry): Record<string, unknown> {
+  const { read, cite, summarize } = entry.agent_use;
+  return {
+    id: entry.id,
+    ...(entry.name ? { name: entry.name } : {}),
+    role: entry.role,
+    pass: entry.disclosure_pass,
+    ...(entry.required_for_tasks?.length
+      ? { tasks: entry.required_for_tasks }
+      : {}),
+    ...(isPrivateEntry(entry)
+      ? {
+          access_policy: entry.access_policy,
+          sensitivity: entry.sensitivity,
+        }
+      : {}),
+    ...(read && cite && summarize ? {} : { agent_use: entry.agent_use }),
+  };
+}
+
+/** The compact brief: what §3 of the specification has an agent always load. */
+function compactBrief(document: DomainDocument): Record<string, unknown> {
+  const front = document.frontmatter;
+  const domain = record(front.domain);
+  const constitution = record(front.constitution);
+  const source = record(front.source_of_truth);
+  const execution = record(constitution.execution);
+  return {
+    domain: {
+      id: domain.id,
+      type: domain.type,
+      status: domain.status,
+      purpose: domain.purpose,
+      operating_boundary: domain.operating_boundary,
+    },
+    constitution: {
+      status: constitution.status,
+      legal_effect: record(constitution.legal_effect).status,
+      execution_mode: execution.mode,
+      failure_policy: execution.failure_policy,
+      ai_mode: record(constitution.constitutional_ai).mode,
+    },
+    source_of_truth: {
+      iid_document: source.iid_document,
+      conflict_resolution_order: source.conflict_resolution_order,
+    },
+    agent_default_mode: front.agent_default_mode,
+    controllers: record(front.controllers).summary,
+    rights: record(front.rights).agent_baseline,
+    privacy: { default_policy: record(front.privacy).default_policy },
+    critical_do_not: front.critical_do_not,
+    documents: entries(document).map(compactEntry),
+  };
+}
+
 /**
  * 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.
+ * (without URIs or CIDs), at `detail`. Serialized once per CID and detail by
+ * the resolver.
  */
-export function briefBody(document: DomainDocument): Record<string, unknown> {
+export function briefBody(
+  document: DomainDocument,
+  detail: DomainBriefDetail = 'compact',
+): Record<string, unknown> {
+  if (detail === 'compact') return compactBrief(document);
   const front = document.frontmatter;
   return {
     domain: front.domain,

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

@@ -1,3 +1,4 @@
+export type { DomainBriefDetail } from './document';
 export type {
   DocumentRequest,
   DomainAnchor,

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

@@ -25,6 +25,7 @@
 import type { DomainDocument } from '@ixo/domain.md/workers';
 import { z } from 'zod';
 import { estimateTokensApprox } from '../manifest';
+import type { DomainBriefDetail } from './document';
 import { briefBody, record } from './document';
 import { boundFindings } from './findings';
 import { decode, INDEX_MAX_BYTES, verifyBytes } from './integrity';
@@ -109,7 +110,7 @@ interface ParsedIndex {
   findings: string[];
   unresolvedChecks: string[];
   document?: DomainDocument;
-  brief?: { json: string; tokens: number };
+  briefs?: Partial<Record<DomainBriefDetail, { json: string; tokens: number }>>;
   /** Keyed by `<did>\n<manifest cid>`; only deterministic outcomes are kept. */
   capsules: LruMap<string, CapsuleResult>;
 }
@@ -320,20 +321,22 @@ export class DomainContextResolver {
 
   /**
    * The serialized brief of a verified snapshot and its token estimate,
-   * computed once per index CID.
+   * computed once per index CID and detail.
    */
   brief(
     snapshot: DomainSnapshot,
+    detail: DomainBriefDetail = 'compact',
   ): { json: string; tokens: number } | undefined {
     if (!snapshot.document) return undefined;
     const entry = snapshot.anchor
       ? this.parsed.get(snapshot.anchor.cid)
       : undefined;
-    if (entry?.brief && entry.document === snapshot.document)
-      return entry.brief;
-    const json = JSON.stringify(briefBody(snapshot.document));
+    const cached = entry?.briefs?.[detail];
+    if (cached && entry?.document === snapshot.document) return cached;
+    const json = JSON.stringify(briefBody(snapshot.document, detail));
     const brief = { json, tokens: estimateTokensApprox(json) };
-    if (entry && entry.document === snapshot.document) entry.brief = brief;
+    if (entry && entry.document === snapshot.document)
+      entry.briefs = { ...entry.briefs, [detail]: brief };
     return brief;
   }