0xray 4.0.21 → 4.0.23

package/dist/integrations/governance/index.d.ts

@@ -39,6 +39,11 @@ export declare class InferenceGovernanceIntegration extends BaseIntegration {
      * Check if governance is enabled and available
      */
     isAvailable(): boolean;
+    /**
+     * Start the Dynamo client when a caller required external governance
+     * and boot skipped it because inference_governance.enabled is false.
+     */
+    ensureDynamoClient(): Promise<void>;
     /**
      * Check a single inference proposal via the appropriate governance tool
      *

package/dist/integrations/governance/index.js

@@ -7,7 +7,7 @@
  * @since 2026-05-11
  */
 import { BaseIntegration } from '../base/index.js';
-import { DEFAULT_GOVERNANCE_CONFIG } from './types.js';
+import { DEFAULT_GOVERNANCE_CONFIG, resolveDynamoBaseUrl } from './types.js';
 import { GovernanceClient } from './governance-client.js';
 import { frameworkLogger } from '../../core/framework-logger.js';
 import { featuresConfigLoader } from '../../core/features-config.js';
@@ -84,7 +84,27 @@ export class InferenceGovernanceIntegration extends BaseIntegration {
      * Check if governance is enabled and available
      */
     isAvailable() {
-        return this.configData.enabled && this.client !== null && this.status === 'initialized';
+        return this.client !== null && this.status === 'initialized';
+    }
+    /**
+     * Start the Dynamo client when a caller required external governance
+     * and boot skipped it because inference_governance.enabled is false.
+     */
+    async ensureDynamoClient() {
+        if (this.status !== 'initialized') {
+            await this.initialize();
+        }
+        if (this.client !== null) {
+            return;
+        }
+        const endpoint = resolveDynamoBaseUrl(this.configData.endpointUrl);
+        this.client = new GovernanceClient({
+            baseUrl: endpoint,
+            timeoutMs: this.configData.requestTimeoutMs,
+        });
+        await this.log('info', 'Dynamo client armed for required external governance', {
+            endpoint,
+        });
     }
     /**
      * Check a single inference proposal via the appropriate governance tool

package/dist/integrations/governance/types.d.ts

@@ -56,6 +56,17 @@ export interface GovernanceIntegrationConfig {
         voteWeightMultiplier: number;
     };
 }
+/**
+ * Public Dynamo Solar SSOT. Used only when a caller requires external
+ * governance and neither features nor GOVERNANCE_ENDPOINT names a host.
+ * The client posts to /call_connected_tool on this origin.
+ */
+export declare const PUBLIC_DYNAMO_SSOT = "https://mcp-production-80e2.up.railway.app";
+/**
+ * Origin for POST /call_connected_tool.
+ * Preference: configured endpoint, then GOVERNANCE_ENDPOINT, then the public SSOT.
+ */
+export declare function resolveDynamoBaseUrl(configured: string): string;
 /**
  * Default governance configuration
  */

package/dist/integrations/governance/types.js

@@ -6,6 +6,22 @@
  *
  * @since 2026-05-11
  */
+/**
+ * Public Dynamo Solar SSOT. Used only when a caller requires external
+ * governance and neither features nor GOVERNANCE_ENDPOINT names a host.
+ * The client posts to /call_connected_tool on this origin.
+ */
+export const PUBLIC_DYNAMO_SSOT = 'https://mcp-production-80e2.up.railway.app';
+/**
+ * Origin for POST /call_connected_tool.
+ * Preference: configured endpoint, then GOVERNANCE_ENDPOINT, then the public SSOT.
+ */
+export function resolveDynamoBaseUrl(configured) {
+    const fromConfig = configured.trim();
+    const fromEnv = (process.env.GOVERNANCE_ENDPOINT || '').trim();
+    const raw = fromConfig || fromEnv || PUBLIC_DYNAMO_SSOT;
+    return raw.replace(/\/governance\/?$/, '').replace(/\/$/, '');
+}
 /**
  * Default governance configuration
  */

package/dist/integrations/hooks/station-hook-runtime.cjs

@@ -395,6 +395,30 @@ function pruneKeywordDest(root) {
   return { removed, kept: kept.length };
 }
 
+const STACK_LAW_FIELDS = [
+  "definition",
+  "tags",
+  "priority",
+  "evaluation_criteria",
+  "validation_experiment",
+  "example_inference_snippet",
+  "implementation_notes",
+];
+
+/** Stack text cadences onto an existing project law. Observation stats stay. */
+function refreshStackLaw(existing, signal) {
+  let dirty = false;
+  for (const field of STACK_LAW_FIELDS) {
+    if (signal[field] == null) continue;
+    const next = signal[field];
+    const prev = existing[field];
+    if (JSON.stringify(prev) === JSON.stringify(next)) continue;
+    existing[field] = next;
+    dirty = true;
+  }
+  return dirty;
+}
+
 function mergeMissingSignals(destPath, incoming) {
   if (!incoming.length || !existsSync(destPath)) return 0;
   let data;
@@ -404,24 +428,35 @@ function mergeMissingSignals(destPath, incoming) {
     return 0;
   }
   if (!Array.isArray(data.signals)) return 0;
-  const have = new Set(
-    data.signals.map((signal) => String((signal && signal.name) || "").trim()).filter(Boolean),
-  );
-  let added = 0;
+  const byName = new Map();
+  for (const signal of data.signals) {
+    const name = String((signal && signal.name) || "").trim();
+    if (name) byName.set(name, signal);
+  }
+  let changed = 0;
   for (const signal of incoming) {
     const name = String(signal.name).trim();
-    if (!name || have.has(name)) continue;
-    data.signals.push({
-      ...signal,
-      name,
-      tags: Array.isArray(signal.tags) ? signal.tags : [],
-      definition: typeof signal.definition === "string" ? signal.definition : name,
-    });
-    have.add(name);
-    added += 1;
+    if (!name) continue;
+    const existing = byName.get(name);
+    if (!existing) {
+      const created = {
+        ...signal,
+        name,
+        tags: Array.isArray(signal.tags) ? signal.tags : [],
+        definition: typeof signal.definition === "string" ? signal.definition : name,
+      };
+      data.signals.push(created);
+      byName.set(name, created);
+      changed += 1;
+      continue;
+    }
+    if (refreshStackLaw(existing, signal)) changed += 1;
+  }
+  if (changed) {
+    data.last_updated = new Date().toISOString();
+    writeFileSync(destPath, `${JSON.stringify(data, null, 2)}\n`);
   }
-  if (added) writeFileSync(destPath, `${JSON.stringify(data, null, 2)}\n`);
-  return added;
+  return changed;
 }
 
 /** Hydrate project dest from seed + stack. Subject repo-* stay off dest. */
@@ -661,6 +696,7 @@ function maybeCaptureSessionOnHeadMove(root) {
     from: stamp && stamp.head ? stamp.head : commits[commits.length - 1] ? commits[commits.length - 1].hash : git.head,
     to: git.head,
   };
+  const patterns = patternsFromGit(root, commits, span);
   const session = {
     sessionId,
     timestamp: new Date().toISOString(),
@@ -669,8 +705,8 @@ function maybeCaptureSessionOnHeadMove(root) {
     approaches,
     wrongTurns: [],
     solutions: [],
-    patterns: patternsFromGit(root, commits, span),
-    matched_primitives: [],
+    patterns,
+    matched_primitives: preferLawHits(patterns.map((row) => row && row.name)),
     metrics: { commits: commits.length },
   };
   const outDir = join(root, "docs", "inference");
@@ -754,8 +790,16 @@ function growDestOnWake(root) {
     const line = String(out).trim().split("\n").filter(Boolean).at(-1) || "{}";
     const parsed = JSON.parse(line);
     const pruned = pruneKeywordDest(root);
-    if (!parsed || typeof parsed !== "object") return { pruned };
-    return { ...parsed, pruned: pruned.removed, destCount: countCuratedSignals(destSignalsPath(root)) };
+    const destCount = countCuratedSignals(destSignalsPath(root)) || 0;
+    if (!parsed || typeof parsed !== "object") return { pruned: pruned.removed, destCount };
+    const heated = Array.isArray(parsed.heated) ? parsed.heated.length : 0;
+    return {
+      ...parsed,
+      observed: heated,
+      pruned: pruned.removed,
+      destCount,
+      after: destCount,
+    };
   } catch {
     return null;
   }
@@ -811,6 +855,28 @@ function retainCompactFields(existing, extra = {}) {
   return kept;
 }
 
+/** Persist heated length. A number stays a number. An array is a count. Never drop a number to 0. */
+function workingGrowSnapshot(grow) {
+  if (!grow || typeof grow !== "object") return null;
+  if (typeof grow.after !== "number") {
+    return typeof grow.skipped === "string" ? grow.skipped : null;
+  }
+  const observed =
+    typeof grow.observed === "number"
+      ? grow.observed
+      : Array.isArray(grow.observed)
+        ? grow.observed.length
+        : Array.isArray(grow.heated)
+          ? grow.heated.length
+          : 0;
+  return {
+    before: grow.before,
+    after: grow.after,
+    imported: grow.imported,
+    observed,
+  };
+}
+
 function formatWorkingLine(working) {
   if (!working || typeof working !== "object") return null;
   const matched = stationSafeSignals(working.matchedSignals);
@@ -826,7 +892,7 @@ function buildRepertoireResume(root) {
   const modulePath = resolveRepertoireProviderModule(root);
   const mr = readMemoryRoutingConfig(root);
   if (!modulePath) {
-    return "Repertoire: not installed (memory_routing stays off)";
+    return "Repertoire: module unresolved";
   }
   const destPath = destSignalsPath(root);
   let signalsPath = existsSync(destPath) ? destPath : mr.config && mr.config.signalsPath;
@@ -932,15 +998,8 @@ function applyStationHeat(root, host, extra = {}, existing = {}) {
   if (pickup) workingSnapshot.pickup = pickup;
   if (matchText) workingSnapshot.matchText = matchText;
   if (captured) workingSnapshot.sessionCapture = captured;
-  if (grow && grow.skipped) workingSnapshot.grow = grow.skipped;
-  if (grow && typeof grow.after === "number") {
-    workingSnapshot.grow = {
-      before: grow.before,
-      after: grow.after,
-      imported: grow.imported,
-      observed: Array.isArray(grow.observed) ? grow.observed.length : 0,
-    };
-  }
+  const growReceipt = workingGrowSnapshot(grow);
+  if (growReceipt) workingSnapshot.grow = growReceipt;
   if (matchedSignals.length) workingSnapshot.matchedSignals = matchedSignals.slice(0, 8);
   const opProcNames = readOpProcNames(root);
   if (opProcNames.length) workingSnapshot.opProcNames = opProcNames;
@@ -1108,7 +1167,7 @@ function formatStationMarkdown(fields) {
   } else {
     lines.push("Git: n/a");
   }
-  lines.push(fields.repertoireResume || "Repertoire: not installed (memory_routing stays off)");
+  lines.push(fields.repertoireResume || "Repertoire: module unresolved");
   if (fields.workingLine) {
     lines.push(fields.workingLine);
   }
@@ -1165,6 +1224,7 @@ module.exports = {
   readNotesPickup,
   maybeCaptureSessionOnHeadMove,
   formatWorkingLine,
+  workingGrowSnapshot,
   applyStationHeat,
   isStockTicket,
   readStationTicketField,

package/dist/integrations/hooks/station-hook-runtime.mjs

@@ -28,6 +28,7 @@ export const patternsFromGit = impl.patternsFromGit;
 export const readNotesPickup = impl.readNotesPickup;
 export const maybeCaptureSessionOnHeadMove = impl.maybeCaptureSessionOnHeadMove;
 export const formatWorkingLine = impl.formatWorkingLine;
+export const workingGrowSnapshot = impl.workingGrowSnapshot;
 export const applyStationHeat = impl.applyStationHeat;
 export const isStockTicket = impl.isStockTicket;
 export const readStationTicketField = impl.readStationTicketField;

package/dist/integrations/hooks/station-memory-ingest.mjs

@@ -128,13 +128,15 @@ async function growDest(projectRoot) {
         sources: [...(kernel.sources || []), ...cleanup.sources],
       });
       const after = service.signalsManager.load().signals.length;
+      const heatedNames = Array.isArray(diary.heated) ? diary.heated : [];
       process.stdout.write(
         `${JSON.stringify({
           before,
           after,
           imported: sessions.imported,
-          observed: 0,
-          heated: diary.heated,
+          observed: heatedNames.length,
+          heated: heatedNames,
+          destCount: after,
         })}\n`,
       );
       return;

package/dist/integrations/openclaw/plugin/xray-pre-tool/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xray-pre-tool",
-  "version": "4.0.21",
+  "version": "4.0.23",
   "private": true,
   "type": "module",
   "description": "0xRay constitution + temperament PreToolUse for OpenClaw",

package/dist/mcps/governance.server.d.ts

@@ -20,6 +20,8 @@ declare class GovernanceServer extends XrayKnowledgeSkillBase {
     protected setupToolHandlers(): void;
     /** Align tool default with features.json inference_governance.enabled (P0.2). */
     private resolveRequireExternal;
+    /** Boot stays flag-gated. A required external call starts the client on demand. */
+    private armRequiredDynamo;
     private handleGovernProposals;
     private handleGovernReflection;
     private handleGetActiveCodex;

package/dist/mcps/governance.server.js

@@ -196,8 +196,19 @@ class GovernanceServer extends XrayKnowledgeSkillBase {
             return false;
         }
     }
+    /** Boot stays flag-gated. A required external call starts the client on demand. */
+    async armRequiredDynamo(requireExternal) {
+        if (!requireExternal)
+            return;
+        const integration = await initializeGovernanceIntegration();
+        if (!integration.isAvailable()) {
+            await integration.ensureDynamoClient();
+        }
+    }
     async handleGovernProposals(args) {
         const service = getGovernanceService();
+        const requireExternal = this.resolveRequireExternal(args.options?.require_external);
+        await this.armRequiredDynamo(requireExternal);
         const request = {
             proposals: args.proposals.map((p, i) => ({
                 id: p.id || `prop-${Date.now()}-${i}`,
@@ -210,7 +221,7 @@ class GovernanceServer extends XrayKnowledgeSkillBase {
             })),
             context: args.context || {},
             options: {
-                requireExternalDynamo: this.resolveRequireExternal(args.options?.require_external),
+                requireExternalDynamo: requireExternal,
             },
         };
         frameworkLogger.log("governance-mcp", "delegating-to-governance-service", "info", {

package/dist/memory-routing/index.d.ts

@@ -1,5 +1,5 @@
 export type { MemoryRoutingProvider, MemoryRoutingContext, MemoryInheritedContext, MemoryAgentCapability, MemoryOrchestrationTask, MemoryThinDispatchResult, MemoryRoutingConfig, OrchestratorFeedbackEntry, } from './types.js';
-export { getMemoryRoutingProvider, getMemoryRoutingProviderSync, getMemoryRoutingConfig, resetMemoryRoutingProvider, initializeMemoryRouting, } from './provider-registry.js';
+export { getMemoryRoutingProvider, getMemoryRoutingProviderSync, ensureMemoryRoutingProviderSync, getMemoryRoutingConfig, resetMemoryRoutingProvider, initializeMemoryRouting, } from './provider-registry.js';
 export { NullMemoryRoutingProvider, createMemoryRoutingProvider } from './null-provider.js';
 export { loadMemoryRoutingProvider, isLeftoverMemoryRoutingOff, isExplicitMemoryRoutingOptOut, resolveLeftoverEnabledConfig, } from './provider-loader.js';
 export { validateMemoryRoutingConfig } from './validate-config.js';

package/dist/memory-routing/index.js

@@ -1,4 +1,4 @@
-export { getMemoryRoutingProvider, getMemoryRoutingProviderSync, getMemoryRoutingConfig, resetMemoryRoutingProvider, initializeMemoryRouting, } from './provider-registry.js';
+export { getMemoryRoutingProvider, getMemoryRoutingProviderSync, ensureMemoryRoutingProviderSync, getMemoryRoutingConfig, resetMemoryRoutingProvider, initializeMemoryRouting, } from './provider-registry.js';
 export { NullMemoryRoutingProvider, createMemoryRoutingProvider } from './null-provider.js';
 export { loadMemoryRoutingProvider, isLeftoverMemoryRoutingOff, isExplicitMemoryRoutingOptOut, resolveLeftoverEnabledConfig, } from './provider-loader.js';
 export { validateMemoryRoutingConfig } from './validate-config.js';

package/dist/memory-routing/lesson-pickup.d.ts

@@ -0,0 +1,2 @@
+/** Refresh the Station lessons section from dest. Leaves the rest of the card alone. */
+export declare function writeLessonPickup(projectRoot: string): void;

package/dist/memory-routing/lesson-pickup.js

@@ -0,0 +1,57 @@
+import * as fs from "fs";
+import * as path from "path";
+const START = "<!-- lessons -->";
+const END = "<!-- /lessons -->";
+const DEST = path.join(".xray", "state", "repertoire", "curated_signals.json");
+const FLOOR = 0.55;
+function aboveFloor(value) {
+    return typeof value === "number" && value > FLOOR && Math.abs(value - FLOOR) > 1e-4;
+}
+function lessonBlock(signals) {
+    const lines = ["## Lessons"];
+    const graded = signals.filter((signal) => typeof signal.name === "string"
+        && aboveFloor(signal.observation_stats?.avg_confidence)
+        && (signal.lessons?.length ?? 0) > 0);
+    if (graded.length === 0) {
+        lines.push("No graded lines above the floor.");
+        return lines.join("\n");
+    }
+    for (const signal of graded) {
+        lines.push(`### ${signal.name}`);
+        if (typeof signal.definition === "string" && signal.definition.length > 0) {
+            lines.push(signal.definition);
+        }
+        for (const lesson of signal.lessons ?? []) {
+            const text = lesson.text.length > 0 ? lesson.text : "graded";
+            lines.push(`- ${lesson.decision} \`${lesson.taskId}\` — ${text}`);
+        }
+    }
+    return lines.join("\n");
+}
+/** Refresh the Station lessons section from dest. Leaves the rest of the card alone. */
+export function writeLessonPickup(projectRoot) {
+    const stationPath = path.join(projectRoot, ".xray", "state", "STATION.md");
+    if (!fs.existsSync(stationPath))
+        return;
+    const destPath = path.join(projectRoot, DEST);
+    let signals = [];
+    if (fs.existsSync(destPath)) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(destPath, "utf-8"));
+            if (parsed && typeof parsed === "object" && "signals" in parsed && Array.isArray(parsed.signals)) {
+                signals = parsed.signals;
+            }
+        }
+        catch {
+            signals = [];
+        }
+    }
+    const section = `${START}\n${lessonBlock(signals)}\n${END}`;
+    const current = fs.readFileSync(stationPath, "utf-8");
+    const pattern = /<!-- lessons -->[\s\S]*?<!-- \/lessons -->/;
+    const next = pattern.test(current)
+        ? current.replace(pattern, section)
+        : `${current.trimEnd()}\n\n${section}\n`;
+    if (next !== current)
+        fs.writeFileSync(stationPath, next);
+}

package/dist/memory-routing/provider-loader.d.ts

@@ -1,6 +1,13 @@
 import type { MemoryRoutingConfig, MemoryRoutingProvider } from './types.js';
 export declare function isExplicitMemoryRoutingOptOut(config: MemoryRoutingConfig): boolean;
-/** Leftover shipped default: enabled false + provider null. Not an explicit opt-out. */
+/** Leftover shipped default: enabled false + provider null. Not an explicit opt-out.
+ *  resolveLeftoverEnabledConfig migrates old tarballs when the organ is on disk.
+ *  Explicit opt-out is enabled: false + provider: repertoire. */
 export declare function isLeftoverMemoryRoutingOff(config: MemoryRoutingConfig): boolean;
 export declare function resolveLeftoverEnabledConfig(config: MemoryRoutingConfig, cwd: string): MemoryRoutingConfig | null;
+/**
+ * First route cannot wait on the async import. Node loads this ESM with require.
+ * Returns null when routing is off or the module cannot be constructed.
+ */
+export declare function loadMemoryRoutingProviderSync(config: MemoryRoutingConfig, cwd?: string): MemoryRoutingProvider | null;
 export declare function loadMemoryRoutingProvider(config: MemoryRoutingConfig, cwd?: string): Promise<MemoryRoutingProvider>;

package/dist/memory-routing/provider-loader.js

@@ -1,4 +1,5 @@
 import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { resolve, dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { frameworkLogger } from '../core/framework-logger.js';
@@ -19,6 +20,7 @@ function resolveUnavailableReason(provider) {
         return null;
     }
 }
+const require = createRequire(import.meta.url);
 const REPERTOIRE_CANDIDATE_PATHS = [
     'node_modules/@0xray/repertoire/dist/provider/memory-routing-provider.js',
     'vendor/@0xray/repertoire/dist/provider/memory-routing-provider.js',
@@ -59,7 +61,9 @@ function defaultPathForProvider(provider, cwd) {
 export function isExplicitMemoryRoutingOptOut(config) {
     return config.enabled === false && config.provider === 'repertoire';
 }
-/** Leftover shipped default: enabled false + provider null. Not an explicit opt-out. */
+/** Leftover shipped default: enabled false + provider null. Not an explicit opt-out.
+ *  resolveLeftoverEnabledConfig migrates old tarballs when the organ is on disk.
+ *  Explicit opt-out is enabled: false + provider: repertoire. */
 export function isLeftoverMemoryRoutingOff(config) {
     if (config.enabled === true)
         return false;
@@ -97,6 +101,50 @@ export function resolveLeftoverEnabledConfig(config, cwd) {
         enabled.config = config.config;
     return enabled;
 }
+function providerFromModule(mod, modulePath, effective) {
+    const factory = mod.createMemoryRoutingProvider ?? mod.default?.createMemoryRoutingProvider;
+    if (typeof factory !== 'function') {
+        throw new Error(`Module ${modulePath} must export createMemoryRoutingProvider()`);
+    }
+    const provider = factory((effective.config ?? {}));
+    if (!provider?.id || typeof provider.isAvailable !== 'function') {
+        throw new Error(`Invalid memory routing provider from ${modulePath}`);
+    }
+    return provider;
+}
+function resolveEffectiveProvider(config, cwd) {
+    const validation = validateMemoryRoutingConfig(config);
+    if (!validation.valid)
+        return null;
+    const leftover = resolveLeftoverEnabledConfig(validation.normalized, cwd);
+    const effective = leftover ?? validation.normalized;
+    if (!effective.enabled || effective.provider === 'null')
+        return null;
+    const modulePath = resolveModulePath(effective.module_path, cwd) ??
+        defaultPathForProvider(effective.provider, cwd);
+    if (!modulePath)
+        return null;
+    return { effective, modulePath };
+}
+/**
+ * First route cannot wait on the async import. Node loads this ESM with require.
+ * Returns null when routing is off or the module cannot be constructed.
+ */
+export function loadMemoryRoutingProviderSync(config, cwd = process.cwd()) {
+    const resolved = resolveEffectiveProvider(config, cwd);
+    if (!resolved)
+        return null;
+    try {
+        const mod = require(resolved.modulePath);
+        const provider = providerFromModule(mod, resolved.modulePath, resolved.effective);
+        if (!provider.isAvailable())
+            return null;
+        return provider;
+    }
+    catch {
+        return null;
+    }
+}
 export async function loadMemoryRoutingProvider(config, cwd = process.cwd()) {
     const validation = validateMemoryRoutingConfig(config);
     if (!validation.valid) {

package/dist/memory-routing/provider-registry.d.ts

@@ -1,8 +1,13 @@
 import type { MemoryRoutingConfig, MemoryRoutingProvider } from './types.js';
 export declare function getMemoryRoutingConfig(): MemoryRoutingConfig;
 export declare function getMemoryRoutingProvider(forceReload?: boolean): Promise<MemoryRoutingProvider>;
-/** Synchronous accessor — returns shared null singleton until async load completes. */
+/** Synchronous accessor — returns shared null singleton until a load completes. */
 export declare function getMemoryRoutingProviderSync(): MemoryRoutingProvider;
+/**
+ * The first scoreAndRoute call loads the organ before it routes.
+ * A later sync read sees the same provider. Off or a missing module stays null.
+ */
+export declare function ensureMemoryRoutingProviderSync(): MemoryRoutingProvider;
 export declare function resetMemoryRoutingProvider(): void;
-/** Kick off background load at module init. */
+/** Kick off load at module init. Sync require first so a later route does not require() an ESM module while its dynamic import is still in flight. */
 export declare function initializeMemoryRouting(): void;

package/dist/memory-routing/provider-registry.js

@@ -1,6 +1,6 @@
 import { featuresConfigLoader } from '../core/features-config.js';
 import { NullMemoryRoutingProvider } from './null-provider.js';
-import { loadMemoryRoutingProvider, resolveLeftoverEnabledConfig } from './provider-loader.js';
+import { loadMemoryRoutingProvider, loadMemoryRoutingProviderSync, resolveLeftoverEnabledConfig, } from './provider-loader.js';
 import { validateMemoryRoutingConfig } from './validate-config.js';
 let cachedProvider = null;
 let loadPromise = null;
@@ -12,30 +12,50 @@ export function getMemoryRoutingConfig() {
         validation.normalized);
 }
 export async function getMemoryRoutingProvider(forceReload = false) {
-    if (!forceReload && cachedProvider)
+    if (!forceReload && cachedProvider && cachedProvider.id !== 'null')
         return cachedProvider;
     if (!forceReload && loadPromise)
         return loadPromise;
     const config = getMemoryRoutingConfig();
     loadPromise = loadMemoryRoutingProvider(config).then((provider) => {
+        if (provider.id === 'null' && cachedProvider && cachedProvider.id !== 'null') {
+            loadPromise = null;
+            return cachedProvider;
+        }
         cachedProvider = provider;
         loadPromise = null;
         return provider;
     });
     return loadPromise;
 }
-/** Synchronous accessor — returns shared null singleton until async load completes. */
+/** Synchronous accessor — returns shared null singleton until a load completes. */
 export function getMemoryRoutingProviderSync() {
     return cachedProvider ?? nullProviderSingleton;
 }
+/**
+ * The first scoreAndRoute call loads the organ before it routes.
+ * A later sync read sees the same provider. Off or a missing module stays null.
+ */
+export function ensureMemoryRoutingProviderSync() {
+    if (cachedProvider && cachedProvider.id !== 'null')
+        return cachedProvider;
+    const config = getMemoryRoutingConfig();
+    if (!config.enabled)
+        return cachedProvider ?? nullProviderSingleton;
+    const loaded = loadMemoryRoutingProviderSync(config);
+    if (!loaded || loaded.id === 'null')
+        return cachedProvider ?? nullProviderSingleton;
+    cachedProvider = loaded;
+    return loaded;
+}
 export function resetMemoryRoutingProvider() {
     cachedProvider = null;
     loadPromise = null;
 }
-/** Kick off background load at module init. */
+/** Kick off load at module init. Sync require first so a later route does not require() an ESM module while its dynamic import is still in flight. */
 export function initializeMemoryRouting() {
-    const config = getMemoryRoutingConfig();
-    if (config.enabled) {
+    const loaded = ensureMemoryRoutingProviderSync();
+    if (loaded.id === 'null' && getMemoryRoutingConfig().enabled) {
         void getMemoryRoutingProvider();
     }
 }

package/dist/memory-routing/record-lesson.d.ts

@@ -0,0 +1,16 @@
+export interface LessonInput {
+    operation: string;
+    success: boolean;
+    taskId: string;
+    assignedAgent: string;
+    sessionId: string;
+    /** Signals the finished task already named. When set, text matching is not used. */
+    signals?: string[];
+    /** Approaches, solutions, or the wrong turn from the sessions that named the law. */
+    lesson?: string;
+}
+/**
+ * A finished task names the signals its text actually matched and says
+ * whether the outcome was good. That is the one-tenth step. No match, no write.
+ */
+export declare function recordLesson(input: LessonInput): string[];

package/dist/memory-routing/record-lesson.js

@@ -0,0 +1,26 @@
+import { ensureMemoryRoutingProviderSync } from "./provider-registry.js";
+/**
+ * A finished task names the signals its text actually matched and says
+ * whether the outcome was good. That is the one-tenth step. No match, no write.
+ */
+export function recordLesson(input) {
+    const provider = ensureMemoryRoutingProviderSync();
+    if (provider.id === "null" || !provider.ingestFeedback)
+        return [];
+    const named = input.signals ?? provider.buildRoutingContext(input.operation).matchedSignals;
+    const names = [...new Set(named.filter((name) => name.length > 0))];
+    if (names.length === 0)
+        return [];
+    provider.ingestFeedback({
+        timestamp: new Date().toISOString(),
+        sessionId: input.sessionId,
+        taskId: input.taskId,
+        assignedAgent: input.assignedAgent,
+        memorySignals: names,
+        complexity: 0,
+        success: input.success,
+        durationMs: 0,
+        lesson: input.lesson ?? "",
+    });
+    return names;
+}