0xray 4.0.22 → 4.0.23

package/dist/inference/inference-proposal-generator.js

@@ -1,3 +1,87 @@
+function primitivesForSessions(corpus, sessionIds) {
+    const wanted = new Set(sessionIds);
+    const names = [];
+    for (const session of corpus.sessions) {
+        if (!wanted.has(session.sessionId))
+            continue;
+        const listed = session.matched_primitives ?? session.matchedPrimitives ?? [];
+        for (const name of listed)
+            names.push(name);
+    }
+    return [...new Set(names.filter((name) => name.length > 0))];
+}
+function signalsForPattern(corpus, pattern) {
+    const names = primitivesForSessions(corpus, pattern.sessions);
+    if (pattern.name.length > 0)
+        names.push(pattern.name);
+    return [...new Set(names)];
+}
+/** Solid band starts at 0.82. Landed work with no wrong turn clears it. */
+const LANDED_RESONANCE = 0.85;
+const WRONG_TURN_RESONANCE = 0.4;
+function resonanceForNamedSignal(corpus, sessionIds) {
+    const sessions = corpus.sessions.filter((session) => sessionIds.includes(session.sessionId));
+    if (sessions.some((session) => (session.wrongTurns?.length ?? 0) > 0))
+        return WRONG_TURN_RESONANCE;
+    if (sessions.some((session) => (session.approaches?.length ?? 0) > 0 || (session.solutions?.length ?? 0) > 0)) {
+        return LANDED_RESONANCE;
+    }
+    let confidence = 0.7;
+    for (const session of sessions) {
+        for (const pattern of session.patterns) {
+            if (pattern.confidence > confidence)
+                confidence = pattern.confidence;
+        }
+    }
+    return confidence;
+}
+function sessionsForWrongTurn(corpus, turn) {
+    return corpus.sessions
+        .filter((session) => session.wrongTurns.includes(turn))
+        .map((session) => session.sessionId);
+}
+const LESSON_TEXT_CAP = 400;
+/** The trace a graded line stores. Wrong turns, then approaches, then solutions. */
+function lessonTrace(corpus, sessionIds) {
+    const wanted = new Set(sessionIds);
+    const lines = [];
+    for (const session of corpus.sessions) {
+        if (!wanted.has(session.sessionId))
+            continue;
+        for (const turn of session.wrongTurns ?? []) {
+            if (turn.trim())
+                lines.push(turn.trim());
+        }
+        for (const line of [...(session.approaches ?? []), ...(session.solutions ?? [])]) {
+            if (line.trim())
+                lines.push(line.trim());
+        }
+    }
+    return [...new Set(lines)].join("; ").slice(0, LESSON_TEXT_CAP);
+}
+function sortedSessionIds(sessionIds) {
+    return [...new Set(sessionIds.filter((sessionId) => sessionId.length > 0))].sort();
+}
+/** Sessions already included in a prior proposal of this exact prefix. */
+function coveredSessions(history, prefix) {
+    const seen = new Set();
+    for (const cycle of history ?? []) {
+        for (const proposal of cycle.proposals) {
+            if (!proposal.id.startsWith(prefix))
+                continue;
+            for (const sessionId of proposal.id.slice(prefix.length).split(",")) {
+                if (sessionId.length > 0)
+                    seen.add(sessionId);
+            }
+        }
+    }
+    return seen;
+}
+/** Sessions that have not already been graded under this prefix. */
+function freshSessions(history, prefix, sessionIds) {
+    const covered = coveredSessions(history, prefix);
+    return sortedSessionIds(sessionIds).filter((sessionId) => !covered.has(sessionId));
+}
 function classifyProposalType(problemPattern) {
     const lower = problemPattern.toLowerCase();
     if (lower.includes("bug") || lower.includes("fix") || lower.includes("stability"))
@@ -63,6 +147,8 @@ function adjustConfidenceFromHistory(proposals, history) {
         }
     }
     for (const proposal of proposals) {
+        if (proposal.id.startsWith("named:"))
+            continue;
         const approved = approvedTypes.get(proposal.type) ?? 0;
         const rejected = rejectedTypes.get(proposal.type) ?? 0;
         const total = approved + rejected;
@@ -80,15 +166,21 @@ function adjustConfidenceFromHistory(proposals, history) {
 export function generateProposals(corpus, history) {
     const proposals = [];
     for (const problem of corpus.recurringProblems) {
+        const prefix = `problem:${problem.pattern}:`;
+        const sessions = freshSessions(history, prefix, problem.sessions);
+        if (sessions.length === 0)
+            continue;
         proposals.push({
-            id: `prop-${Date.now()}-${proposals.length}`,
+            id: `${prefix}${sessions.join(",")}`,
             type: classifyProposalType(problem.pattern),
             title: generateTitle(problem),
             description: `Recurring across ${problem.occurrences} sessions: ${problem.pattern}`,
-            evidence: problem.sessions.map((s) => `Seen in session ${s}`),
+            evidence: sessions.map((s) => `Seen in session ${s}`),
             confidence: Math.min(0.95, 0.5 + problem.occurrences * 0.15),
             source: "recurring_problem",
             status: "pending",
+            namedSignals: primitivesForSessions(corpus, sessions),
+            lesson: lessonTrace(corpus, sessions),
         });
     }
     const seenPatterns = new Set(corpus.recurringProblems.map((p) => p.pattern));
@@ -99,8 +191,14 @@ export function generateProposals(corpus, history) {
             continue;
         if (proposals.length >= 5)
             break;
+        const prefix = `problem:${normalized}:`;
+        const sessions = freshSessions(history, prefix, [session]);
+        if (sessions.length === 0) {
+            seenPatterns.add(normalized);
+            continue;
+        }
         proposals.push({
-            id: `prop-${Date.now()}-${proposals.length}`,
+            id: `${prefix}${sessions.join(",")}`,
             type: classifyProposalType(problem),
             title: `Investigate: ${problem.substring(0, 80)}`,
             description: `Observed in session ${session}: ${problem}`,
@@ -108,15 +206,21 @@ export function generateProposals(corpus, history) {
             confidence: 0.4,
             source: "recurring_problem",
             status: "pending",
+            namedSignals: primitivesForSessions(corpus, sessions),
+            lesson: lessonTrace(corpus, sessions),
         });
         seenPatterns.add(normalized);
     }
     for (const pattern of corpus.recurringPatterns) {
         if (pattern.occurrences < 2)
             continue;
+        const prefix = `pattern:${pattern.name}:`;
+        const sessions = freshSessions(history, prefix, pattern.sessions);
+        if (sessions.length === 0)
+            continue;
         const type = patternToProposalType(pattern);
         proposals.push({
-            id: `prop-${Date.now()}-${proposals.length}`,
+            id: `${prefix}${sessions.join(",")}`,
             type,
             title: `Codify ${pattern.name} pattern`,
             description: `${pattern.name} detected across ${pattern.occurrences} sessions (avg confidence: ${Math.round(pattern.avgConfidence * 100)}%). ${pattern.description}`,
@@ -124,13 +228,19 @@ export function generateProposals(corpus, history) {
             confidence: pattern.avgConfidence,
             source: "recurring_pattern",
             status: "pending",
+            namedSignals: signalsForPattern(corpus, { ...pattern, sessions }),
+            lesson: lessonTrace(corpus, sessions),
         });
     }
     const wrongTurns = corpus.allWrongTurns.slice(0, 2);
     for (const wt of wrongTurns) {
         const summary = wt.length > 50 ? `${wt.substring(0, 47)}...` : wt;
+        const prefix = `wrong:${wt}:`;
+        const sessions = freshSessions(history, prefix, sessionsForWrongTurn(corpus, wt));
+        if (sessions.length === 0)
+            continue;
         proposals.push({
-            id: `prop-${Date.now()}-${proposals.length}`,
+            id: `${prefix}${sessions.join(",")}`,
             type: "guard",
             title: `Guard against: ${summary}`,
             description: `Recurring wrong turn detected: ${wt}. Add a guard or validation to prevent this pattern.`,
@@ -138,9 +248,42 @@ export function generateProposals(corpus, history) {
             confidence: 0.7,
             source: "wrong_turn",
             status: "pending",
+            namedSignals: primitivesForSessions(corpus, sessions),
+            lesson: lessonTrace(corpus, sessions),
         });
     }
     const sorted = proposals.sort((a, b) => b.confidence - a.confidence).slice(0, 3);
+    const alreadyNamed = new Set(sorted.flatMap((proposal) => proposal.namedSignals ?? []));
+    const bySignal = new Map();
+    for (const session of corpus.sessions) {
+        const listed = session.matched_primitives ?? session.matchedPrimitives ?? [];
+        for (const name of listed) {
+            if (name.length === 0 || alreadyNamed.has(name))
+                continue;
+            const sessions = bySignal.get(name) ?? [];
+            if (!sessions.includes(session.sessionId))
+                sessions.push(session.sessionId);
+            bySignal.set(name, sessions);
+        }
+    }
+    for (const [name, sessionIds] of bySignal) {
+        const sessions = freshSessions(history, `named:${name}:`, sessionIds);
+        if (sessions.length === 0)
+            continue;
+        const id = `named:${name}:${sessions.join(",")}`;
+        sorted.push({
+            id,
+            type: "codify",
+            title: `Grade named signal ${name}`,
+            description: `Sessions ${sessions.join(", ")} named ${name}.`,
+            evidence: sessions.map((sessionId) => `Seen in session ${sessionId}`),
+            confidence: resonanceForNamedSignal(corpus, sessions),
+            source: "recurring_pattern",
+            status: "pending",
+            namedSignals: [name],
+            lesson: lessonTrace(corpus, sessions),
+        });
+    }
     if (history && history.length > 0) {
         adjustConfidenceFromHistory(sorted, history);
         sorted.sort((a, b) => b.confidence - a.confidence);

package/dist/inference/session-capture.d.ts

@@ -13,6 +13,10 @@ export interface SessionInference {
     reasoningChain: ReasoningLink[];
     patterns: StructuralPattern[];
     metrics: SessionMetrics;
+    /** Signals this session already named. Session JSON stores this list. */
+    matched_primitives?: string[];
+    /** Same list after load, so callers can read either field. */
+    matchedPrimitives?: string[];
 }
 export interface ReasoningLink {
     from: string;

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/openclaw/plugin/xray-pre-tool/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xray-pre-tool",
-  "version": "4.0.22",
+  "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

@@ -5,4 +5,9 @@ export declare function isExplicitMemoryRoutingOptOut(config: MemoryRoutingConfi
  *  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',
@@ -99,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;
+}