@ixo/oracle-runtime-workers 0.13.0 → 0.15.0

package/src/core/prompt-composer.ts

@@ -87,7 +87,13 @@ export interface ComposePromptInput {
   userPreferencesContext: string;
   /** Memory-engine context blocks. */
   userContext: UserContextData | undefined;
-  /** Time context (timezone + current time). */
+  /**
+   * Date context (`formatDateContext`): the day and the user's timezone. Only
+   * values stable for a whole day belong here — the system prompt opens
+   * every request, so anything that changes per turn would stop the
+   * provider's prompt cache at this point on every turn. The exact time
+   * rides on the turn's own message (`renderTurnTimeNote`).
+   */
   timeContext: string;
   /** Currently-viewed entity DID, if any. */
   currentEntityDid: string;
@@ -95,8 +101,22 @@ export interface ComposePromptInput {
   oracleNameOverride?: string;
   /** Degraded-services notice appended after the main prompt body. */
   degradedServicesBlock?: string;
+  /**
+   * How to write for the surface the reply lands on (chat delivery). Empty on
+   * Portal turns, which render a streamed document.
+   */
+  surfaceBlock?: string;
+  /**
+   * Operating guides of the plugins the turn starts with in use, already in
+   * their final order (`OraclePlugin.operatingGuide`). Rendered after every
+   * other section, under one heading; empty renders nothing.
+   */
+  operatingGuides?: readonly string[];
 }
 
+/** Heading of the section that carries the in-use plugins' operating guides. */
+export const OPERATING_GUIDES_HEADING = '## Capabilities in use';
+
 /** Headers used for each populated memory-context sub-section. */
 const CONTEXT_SECTION_LABELS: Record<ContextSlot, string> = {
   identity: 'Personal identity',
@@ -403,7 +423,7 @@ const TEMPLATE = `{{{ORACLE_SECTION}}}
 {{/DISCOVERY_PRINCIPLE}}
 - Being proactive does **not** mean charging ahead blind. Pause and ask the user a short clarifying question when: (a) the request has multiple plausible interpretations and picking wrong would waste their time, (b) a capability scan surfaces several equally-good fits and you can't tell which they want, (c) you're about to take an irreversible or costly action (deleting data, sending a message, publishing, spending tokens on a long job), or (d) a required input is missing and you'd have to guess. One clarifying question beats five minutes of wrong work — but don't ask for things you can reasonably infer from context.
 - When a tool or sub-agent succeeds, report the result. Never refuse after a successful tool call — including for credentials, tokens, identity data, or block/document operations.
-- When a tool or sub-agent fails, surface the failure to the user and ask how to proceed. Don't silently retry.
+- The runtime retries a transient failure of a read-only tool once by itself. When a tool or sub-agent still fails, surface the failure to the user and ask how to proceed. Never repeat a write whose outcome is unknown without first verifying what happened, and never claim an authorization you were not given.
 - When delegating to a sub-agent, give it scope, intent, and the context it needs — sub-agents have no access to your conversation history.
 - Match the user's communication style. Be concise. Use Unicode emoji directly (\`🔥\`), never text shortcodes (\`:fire:\`).
 - When a capability turns out to be a strong fit for the user's recurring work, surface it explicitly and — if memory tools are available — offer to save the pattern for next time. Don't save silently; ask first.
@@ -412,6 +432,10 @@ const TEMPLATE = `{{{ORACLE_SECTION}}}
 
 {{{COMMUNICATION_STYLE}}}
 {{/COMMUNICATION_STYLE}}
+{{#SURFACE_BLOCK}}
+
+{{{SURFACE_BLOCK}}}
+{{/SURFACE_BLOCK}}
 {{#CUSTOM_INSTRUCTIONS}}
 
 ## Custom Instructions
@@ -425,7 +449,7 @@ const TEMPLATE = `{{{ORACLE_SECTION}}}
 {{{CONTEXT_BLOCK}}}
 {{/CONTEXT_BLOCK}}
 
-**Current time:** {{TIME_CONTEXT}}
+**Current date:** {{TIME_CONTEXT}}
 {{#CURRENT_ENTITY_DID}}
 
 **Current entity:** {{CURRENT_ENTITY_DID}}
@@ -479,6 +503,7 @@ export async function composePrompt(
       input.capabilityDiscovery === false ? '' : DISCOVERY_PRINCIPLE,
     CUSTOM_INSTRUCTIONS: input.customInstructions,
     COMMUNICATION_STYLE: communicationStyle,
+    SURFACE_BLOCK: input.surfaceBlock ?? '',
     CONTEXT_BLOCK: buildContextBlock(input.userContext),
     TIME_CONTEXT: input.timeContext,
     CURRENT_ENTITY_DID: input.currentEntityDid,
@@ -486,15 +511,95 @@ export async function composePrompt(
     USER_PREFERENCES_CONTEXT: input.userPreferencesContext,
   });
 
+  // After the stable sections: the set changes only when a plugin is loaded,
+  // so the prefix before it stays cacheable across that change too.
+  const guides = (input.operatingGuides ?? []).filter((g) => g.trim() !== '');
+  const withGuides =
+    guides.length > 0
+      ? `${rendered}\n${OPERATING_GUIDES_HEADING}\n\n${guides.join('\n\n')}\n`
+      : rendered;
+
   if (input.degradedServicesBlock && input.degradedServicesBlock.length > 0) {
-    return `${rendered}\n\n---\n\n## Degraded services\n\n${input.degradedServicesBlock}\n`;
+    return `${withGuides}\n\n---\n\n## Degraded services\n\n${input.degradedServicesBlock}\n`;
+  }
+  return withGuides;
+}
+
+interface ZonedParts {
+  weekday: string;
+  date: string;
+  time: string;
+  /** The IANA zone the parts are in: the one asked for, or `UTC` when it is not a zone. */
+  zone: string;
+}
+
+/** `instant` as calendar parts in `timeZone`, or in UTC when that is not a usable zone. */
+function zonedParts(instant: Date, timeZone: string | undefined): ZonedParts {
+  const zone = timeZone?.trim() || 'UTC';
+  let parts: Intl.DateTimeFormatPart[];
+  try {
+    parts = new Intl.DateTimeFormat('en-US', {
+      timeZone: zone,
+      weekday: 'long',
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      hourCycle: 'h23',
+    }).formatToParts(instant);
+  } catch {
+    if (zone === 'UTC') throw new RangeError('Invalid date');
+    return zonedParts(instant, 'UTC');
   }
-  return rendered;
+  const part = (type: Intl.DateTimeFormatPartTypes): string =>
+    parts.find((p) => p.type === type)?.value ?? '';
+  return {
+    weekday: part('weekday'),
+    date: `${part('year')}-${part('month')}-${part('day')}`,
+    time: `${part('hour')}:${part('minute')}`,
+    zone,
+  };
+}
+
+function parseInstant(value: string | undefined): Date | undefined {
+  if (!value) return undefined;
+  const instant = new Date(value);
+  return Number.isNaN(instant.getTime()) ? undefined : instant;
+}
+
+/**
+ * The system prompt's date line: the day in the user's timezone and the
+ * zone (`Saturday, 2026-10-03 (Europe/Berlin)`). Nothing finer than the day,
+ * so the prompt stays byte-identical across the turns of a day. A timezone
+ * that is not an IANA zone is not rendered; the day is then UTC's.
+ */
+export function formatDateContext(
+  timezone: string | undefined,
+  currentTime: string | undefined,
+): string {
+  const instant = parseInstant(currentTime);
+  if (!instant) return 'Not available.';
+  const { weekday, date, zone } = zonedParts(instant, timezone);
+  return `${weekday}, ${date} (${zone})`;
+}
+
+/**
+ * The exact time for the turn's own message (`Current time: Saturday,
+ * 2026-10-03 14:05 (Europe/Berlin)`): it belongs on the message the user
+ * sent this turn, where it is part of the history from then on, not in the
+ * system prompt that opens every request. Pure: same inputs, same text.
+ */
+export function renderTurnTimeNote(now: Date, timezone?: string): string {
+  if (Number.isNaN(now.getTime())) return 'Current time: not available.';
+  const { weekday, date, time, zone } = zonedParts(now, timezone);
+  return `Current time: ${weekday}, ${date} ${time} (${zone})`;
 }
 
 /**
- * Format a (timezone, currentTime) pair into a stable prompt block. Public so
- * forks driving their own `composePrompt` calls can re-use it.
+ * Format a (timezone, currentTime) pair into a prompt block, time included.
+ * Kept for forks driving their own `composePrompt` calls; the runtime's own
+ * prompt uses `formatDateContext`, which does not change within a day.
  */
 export function formatTimeContext(
   timezone: string | undefined,

package/src/core/registries.ts

@@ -1,3 +1,4 @@
+import type { DecisionRegistration } from '@ixo/common/ai/decisions';
 import type { z } from 'zod';
 import type { OraclePlugin } from '../plugin-api/oracle-plugin';
 import type {
@@ -17,7 +18,7 @@ import {
 import { computeSubAgentToolName } from './subagent-as-tool';
 
 /**
- * The six registries the runtime composes. Instances are created per
+ * The seven registries the runtime composes. Instances are created per
  * `createRuntimeCore()` call — never at module scope — so an isolate that
  * boots two oracles (tests, or a multi-tenant shell) never shares caches.
  */
@@ -28,6 +29,7 @@ export interface Registries {
   manifests: ManifestRegistry;
   configSchema: ConfigSchemaRegistry;
   sharedState: SharedStateRegistry;
+  decisions: DecisionRegistry;
 }
 
 /** Build a fresh, empty set of registries. */
@@ -39,6 +41,7 @@ export function createRegistries(): Registries {
     manifests: new ManifestRegistry(),
     configSchema: new ConfigSchemaRegistry(),
     sharedState: new SharedStateRegistry(),
+    decisions: new DecisionRegistry(),
   };
 }
 
@@ -83,6 +86,31 @@ export interface ToolSummary {
   origin: 'boot' | 'request';
 }
 
+/** Where `load_capability` reads the tools a plugin contributes. */
+export interface ToolSummarySource {
+  toolSummariesForPlugin(
+    pluginName: string,
+  ): Array<{ name: string; description: string }>;
+}
+
+/**
+ * One turn's view of its own collected tools (boot and request-time), in
+ * collection order — never another turn's.
+ */
+export function turnToolSummaries(
+  tools: ReadonlyArray<{ pluginName: string; tool: PluginTool }>,
+): ToolSummarySource {
+  return {
+    toolSummariesForPlugin: (pluginName) =>
+      tools
+        .filter((entry) => entry.pluginName === pluginName)
+        .map(({ tool }) => ({
+          name: tool.name,
+          description: tool.description,
+        })),
+  };
+}
+
 /**
  * Stores plugins that contribute tools and resolves them lazily by invoking
  * each plugin's `getTools(buildCtx)` once at collection time.
@@ -105,19 +133,11 @@ export interface ToolSummary {
 export class ToolRegistry {
   private readonly plugins: OraclePlugin[] = [];
   private bootCache: RegisteredTool[] | null = null;
-  /**
-   * Metadata snapshot of the most recent `collect()`. Deliberately NOT the
-   * tool objects: request-time tools close over that request's
-   * `RuntimeContext`, and retaining them here would pin a full request
-   * graph in memory between turns.
-   */
-  private collectedMeta: ToolSummary[] | null = null;
 
   /** Add a plugin whose `getTools` will be called at `collect()` time. */
   register(plugin: OraclePlugin): void {
     this.plugins.push(plugin);
     this.bootCache = null;
-    this.collectedMeta = null;
   }
 
   /**
@@ -184,6 +204,11 @@ export class ToolRegistry {
    * Combined boot + request collection used by the main agent build. Uses
    * the cached boot output when present so per-request rebuilds skip the
    * `getTools` invocations that don't depend on runtime state.
+   *
+   * The request-time part is returned to the caller only, never kept: the
+   * registry is shared by every turn of the isolate, so nothing one user's
+   * turn collected may be read back by another (`turnToolSummaries` gives a
+   * turn its own view).
    */
   async collect(
     buildCtx: PluginContext,
@@ -191,19 +216,13 @@ export class ToolRegistry {
   ): Promise<RegisteredTool[]> {
     const boot = await this.collectBoot(buildCtx);
     const request = rtCtx ? await this.collectRequest(rtCtx) : [];
-    const out = [...boot, ...request];
-    this.collectedMeta = out.map(({ pluginName, tool, origin }) => ({
-      pluginName,
-      name: tool.name,
-      description: tool.description,
-      origin,
-    }));
-    return out;
+    return rtCtx
+      ? withoutShadowingRequestTools([...boot, ...request], rtCtx.logger)
+      : boot;
   }
 
-  /** Summaries source: the last full collection, else the boot cache. */
+  /** Summaries of the boot-time tools (the boot checks read these). */
   private summaries(): ToolSummary[] {
-    if (this.collectedMeta !== null) return this.collectedMeta;
     return (this.bootCache ?? []).map(({ pluginName, tool, origin }) => ({
       pluginName,
       name: tool.name,
@@ -212,15 +231,12 @@ export class ToolRegistry {
     }));
   }
 
-  /** The flat list of tool names produced by the most recent `collect()`. */
+  /** The flat list of boot-time tool names. */
   toolNames(): string[] {
     return this.summaries().map((entry) => entry.name);
   }
 
-  /**
-   * Tool names contributed by a given plugin in the most recent `collect()`
-   * (or `collectBoot()` if no full collection has happened yet).
-   */
+  /** Boot-time tool names contributed by a given plugin. */
   toolNamesForPlugin(pluginName: string): string[] {
     return this.summaries()
       .filter((entry) => entry.pluginName === pluginName)
@@ -228,8 +244,9 @@ export class ToolRegistry {
   }
 
   /**
-   * Name/description of the tools a given plugin contributed in the most
-   * recent collection. Summaries, not the tool objects — see `collectedMeta`.
+   * Name/description of the boot-time tools a given plugin contributed.
+   * Summaries, not the tool objects. A turn that also has request-time tools
+   * reads its own collection instead (`turnToolSummaries`).
    */
   toolSummariesForPlugin(
     pluginName: string,
@@ -245,7 +262,7 @@ export class ToolRegistry {
    * actual conflict.
    */
   assertNoCollisions(): void {
-    if (this.collectedMeta === null && this.bootCache === null) {
+    if (this.bootCache === null) {
       throw new Error('ToolRegistry.assertNoCollisions called before collect');
     }
     const seen = new Map<string, string>();
@@ -268,6 +285,86 @@ export class ToolRegistry {
   }
 }
 
+/**
+ * A request-time tool (most of them declared by the client in the turn body,
+ * such as the Portal's browser tools) may not take a name another tool of the
+ * turn already has: the model would call one name while the runtime ran
+ * either tool. The colliding request tool is dropped for this turn with one
+ * warning — the server tool (or the first request tool of that name) stays,
+ * and the turn runs. Failing the turn instead would break every turn of a
+ * client release that happens to declare a clashing name. Boot-time
+ * collisions are `assertNoCollisions`' job; the names the registry cannot
+ * see (the meta-tools, the runtime's per-turn tools, sub-agent tool names)
+ * are reserved by `dropShadowingRequestEntries` when the agent is built.
+ */
+function withoutShadowingRequestTools(
+  tools: readonly RegisteredTool[],
+  logger: { warn(message: string): void },
+): RegisteredTool[] {
+  const owner = new Map<string, string>();
+  const out: RegisteredTool[] = [];
+  for (const entry of tools) {
+    const { pluginName, tool, origin } = entry;
+    const previous = owner.get(tool.name);
+    if (previous !== undefined && origin === 'request') {
+      logger.warn(
+        `${LOG_PREFIX} request tool "${tool.name}" of plugin "${pluginName}" dropped for this turn: the name is already taken by plugin "${previous}"`,
+      );
+      continue;
+    }
+    if (previous === undefined) owner.set(tool.name, pluginName);
+    out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * Drop the request-time tools and sub-agents whose name is already taken.
+ * Request-time contributions are recomputed every turn and some carry names
+ * a client declared (browser tools, AG-UI actions), so none of them may stand
+ * in for a tool the server owns: a name in `reservedNames` (the turn's
+ * boot-time tools and sub-agents, the meta-tools and the runtime's per-turn
+ * tools), or one an earlier request-time entry of the same turn already
+ * claimed, is dropped with one warning naming the plugin. Sub-agents are
+ * compared by the tool name they are bound under. Boot-time entries pass
+ * through untouched; their collisions are a boot error
+ * (`assertNoCollisions`).
+ */
+export function dropShadowingRequestEntries(opts: {
+  tools: readonly RegisteredTool[];
+  requestSubAgents: readonly RegisteredSubAgent[];
+  reservedNames: Iterable<string>;
+  logger: { warn(message: string): void };
+}): { tools: RegisteredTool[]; requestSubAgents: RegisteredSubAgent[] } {
+  const taken = new Set(opts.reservedNames);
+  const drop = (pluginName: string, name: string, kind: string): void =>
+    opts.logger.warn(
+      `${LOG_PREFIX} plugin "${pluginName}" request-time ${kind} "${name}" dropped: the name is already taken this turn`,
+    );
+  const tools: RegisteredTool[] = [];
+  for (const entry of opts.tools) {
+    if (entry.origin === 'request') {
+      if (taken.has(entry.tool.name)) {
+        drop(entry.pluginName, entry.tool.name, 'tool');
+        continue;
+      }
+      taken.add(entry.tool.name);
+    }
+    tools.push(entry);
+  }
+  const requestSubAgents: RegisteredSubAgent[] = [];
+  for (const entry of opts.requestSubAgents) {
+    const toolName = computeSubAgentToolName(entry.subAgent.name);
+    if (taken.has(toolName)) {
+      drop(entry.pluginName, toolName, 'sub-agent');
+      continue;
+    }
+    taken.add(toolName);
+    requestSubAgents.push(entry);
+  }
+  return { tools, requestSubAgents };
+}
+
 // ── Sub-agent registry ──────────────────────────────────────────────────────
 
 /** A collected sub-agent tagged with the plugin that contributed it. */
@@ -286,17 +383,11 @@ export interface RegisteredSubAgent {
 export class SubAgentRegistry {
   private readonly plugins: OraclePlugin[] = [];
   private bootCache: RegisteredSubAgent[] | null = null;
-  /** Names-only snapshot of the most recent `collect()` (see ToolRegistry). */
-  private collectedNames: Array<{
-    pluginName: string;
-    subAgentName: string;
-  }> | null = null;
 
   /** Add a plugin whose `getSubAgents` will be called at `collect()` time. */
   register(plugin: OraclePlugin): void {
     this.plugins.push(plugin);
     this.bootCache = null;
-    this.collectedNames = null;
   }
 
   /** Run every plugin's `getSubAgents(buildCtx)` once and cache the result. */
@@ -343,24 +434,21 @@ export class SubAgentRegistry {
     return perPlugin.flat();
   }
 
-  /** Combined boot + request collection used by the main agent build. */
+  /**
+   * Combined boot + request collection used by the main agent build. As
+   * with `ToolRegistry.collect`, the request-time part is not kept.
+   */
   async collect(
     buildCtx: PluginContext,
     rtCtx?: RuntimeContext,
   ): Promise<RegisteredSubAgent[]> {
     const boot = this.collectBoot(buildCtx);
     const request = rtCtx ? await this.collectRequest(rtCtx) : [];
-    const out = [...boot, ...request];
-    this.collectedNames = out.map(({ pluginName, subAgent }) => ({
-      pluginName,
-      subAgentName: subAgent.name,
-    }));
-    return out;
+    return [...boot, ...request];
   }
 
-  /** Names source: the last full collection, else the boot cache. */
+  /** Names of the boot-time sub-agents (the boot checks read these). */
   private names(): Array<{ pluginName: string; subAgentName: string }> {
-    if (this.collectedNames !== null) return this.collectedNames;
     return (this.bootCache ?? []).map(({ pluginName, subAgent }) => ({
       pluginName,
       subAgentName: subAgent.name,
@@ -368,8 +456,8 @@ export class SubAgentRegistry {
   }
 
   /**
-   * The *wrapped* tool names contributed by a given plugin in the most recent
-   * collection. Each entry passes through `computeSubAgentToolName` — the
+   * The *wrapped* tool names of the boot-time sub-agents a given plugin
+   * contributes. Each entry passes through `computeSubAgentToolName` — the
    * same transform `createSubagentAsTool` applies — so the names returned
    * here match what the agent will actually see.
    */
@@ -384,7 +472,7 @@ export class SubAgentRegistry {
    * message names both plugin names so the boot log points at the conflict.
    */
   assertNoCollisions(): void {
-    if (this.collectedNames === null && this.bootCache === null) {
+    if (this.bootCache === null) {
       throw new Error(
         'SubAgentRegistry.assertNoCollisions called before collect',
       );
@@ -424,8 +512,6 @@ export interface RegisteredMiddleware {
  * Order is preserved as registration order — the loader applies any
  * dependency-driven topological reordering before registering plugins here.
  *
- * Middlewares are boot-time-only — there's no per-request hook. The
- * registry caches the first `collect(buildCtx)` result.
  */
 export class MiddlewareRegistry {
   private readonly plugins: OraclePlugin[] = [];
@@ -450,6 +536,17 @@ export class MiddlewareRegistry {
     return out;
   }
 
+  async collectRequest(ctx: RuntimeContext): Promise<RegisteredMiddleware[]> {
+    const entries = await Promise.all(
+      this.plugins.map(async (plugin) =>
+        ((await plugin.getRequestMiddlewares?.(ctx)) ?? []).map(
+          (middleware) => ({ pluginName: plugin.name, middleware }),
+        ),
+      ),
+    );
+    return entries.flat();
+  }
+
   /** Middlewares have no names, so no collision is possible. */
   assertNoCollisions(): void {
     // Intentional no-op — middleware order is established by the loader.
@@ -475,17 +572,35 @@ export interface ManifestCrossCheckResult {
  */
 export class ManifestRegistry {
   private readonly entries: RegisteredManifest[] = [];
+  /** Plugin name → `operatingGuide`, kept apart from the manifests (never rendered with them). */
+  private readonly guides = new Map<string, string>();
 
   /**
    * Record a plugin's manifest. A fork-supplied `override` is merged shallowly
    * over the plugin's own manifest, so every downstream reader sees the
-   * effective manifest.
+   * effective manifest. A non-blank `operatingGuide` is recorded beside it.
    */
   register(plugin: OraclePlugin, override?: PluginManifestOverride): void {
     this.entries.push({
       pluginName: plugin.name,
       manifest: mergeManifestOverride(plugin.manifest, override),
     });
+    const guide = plugin.operatingGuide?.trim();
+    if (guide) this.guides.set(plugin.name, guide);
+  }
+
+  /** The plugin's operating guide, trimmed; `undefined` when it has none. */
+  operatingGuide(pluginName: string): string | undefined {
+    return this.guides.get(pluginName);
+  }
+
+  /** Every registered operating guide, by plugin name in code-point order. */
+  operatingGuides(): Array<{ pluginName: string; guide: string }> {
+    return [...this.guides]
+      .map(([pluginName, guide]) => ({ pluginName, guide }))
+      .sort((a, b) =>
+        a.pluginName < b.pluginName ? -1 : a.pluginName > b.pluginName ? 1 : 0,
+      );
   }
 
   /** Registered manifests in registration order. */
@@ -640,3 +755,93 @@ export class SharedStateRegistry {
     }
   }
 }
+
+// ── Decision registry ───────────────────────────────────────────────────────
+
+/** A collected decision tagged with the plugin that contributed it. */
+export interface RegisteredDecision {
+  pluginName: string;
+  decision: DecisionRegistration;
+}
+
+interface DecisionBootCache {
+  entries: RegisteredDecision[];
+  /** First registration per name; duplicates surface in `assertNoCollisions`. */
+  byName: Map<string, RegisteredDecision>;
+}
+
+/**
+ * Stores the bounded semantic decisions plugins contribute through
+ * `getDecisions(ctx)`. Collected once per isolate (in `warm()`); the
+ * `DecisionRuntime` resolves `evaluateByName` through `get`. Name collisions
+ * across plugins are a boot error.
+ */
+export class DecisionRegistry {
+  private readonly plugins: OraclePlugin[] = [];
+  private bootCache: DecisionBootCache | null = null;
+
+  register(plugin: OraclePlugin): void {
+    this.plugins.push(plugin);
+    this.bootCache = null;
+  }
+
+  /** Collect every plugin's decisions once; later calls return the cache. */
+  collect(buildCtx: PluginContext): RegisteredDecision[] {
+    if (this.bootCache !== null) return this.bootCache.entries;
+
+    const entries: RegisteredDecision[] = [];
+    const byName = new Map<string, RegisteredDecision>();
+    for (const plugin of this.plugins) {
+      if (!plugin.getDecisions) continue;
+      for (const decision of plugin.getDecisions(buildCtx)) {
+        const entry: RegisteredDecision = { pluginName: plugin.name, decision };
+        entries.push(entry);
+        if (!byName.has(decision.name)) byName.set(decision.name, entry);
+      }
+    }
+    this.bootCache = { entries, byName };
+    return entries;
+  }
+
+  get(name: string): RegisteredDecision | undefined {
+    if (this.bootCache === null) {
+      throw new Error('DecisionRegistry.get called before collect');
+    }
+    return this.bootCache.byName.get(name);
+  }
+
+  namesForPlugin(pluginName: string): string[] {
+    if (this.bootCache === null) return [];
+    return this.bootCache.entries
+      .filter((entry) => entry.pluginName === pluginName)
+      .map((entry) => entry.decision.name);
+  }
+
+  /** Throw if two plugins contribute decisions under the same name. */
+  assertNoCollisions(): void {
+    if (this.bootCache === null) {
+      throw new Error(
+        'DecisionRegistry.assertNoCollisions called before collect',
+      );
+    }
+
+    const seen = new Map<string, string>();
+    const collisions: string[] = [];
+    for (const { pluginName, decision } of this.bootCache.entries) {
+      const previous = seen.get(decision.name);
+      if (previous && previous !== pluginName) {
+        collisions.push(
+          `Decision "${decision.name}" registered by both "${previous}" and "${pluginName}"`,
+        );
+      } else if (!previous) {
+        seen.set(decision.name, pluginName);
+      }
+    }
+
+    if (collisions.length > 0) {
+      throw new Error(
+        `DecisionRegistry: decision name collisions detected:\n  - ${collisions.join('\n  - ')}`,
+      );
+    }
+  }
+}