@remnic/core 9.50.0 → 9.50.1

package/src/dependency-revalidation-routing.test.ts

@@ -0,0 +1,165 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { parseConfig } from "./config.js";
+import { ExtractionEngine } from "./extraction.js";
+
+type TestMessage = { role: "system" | "user" | "assistant"; content: string };
+type TestOptions = { maxTokens?: number; signal?: AbortSignal };
+
+const superseded = { id: "support-old", content: "The service uses port 4000." };
+const replacement = { id: "support-new", content: "The service uses port 5000." };
+const dependents = [{ id: "dependent", category: "fact", content: "Port 4000 must be open." }];
+const response = {
+  content: JSON.stringify({
+    verdicts: [{ memoryId: "dependent", verdict: "invalidated", reason: "The port changed." }],
+  }),
+};
+
+function assertInvalidated(result: Awaited<ReturnType<ExtractionEngine["revalidateDependents"]>>): void {
+  assert.deepEqual(result, {
+    verdicts: [{ memoryId: "dependent", verdict: "invalidated", reason: "The port changed." }],
+  });
+}
+
+test("revalidation keeps the official OpenAI base URL on the Responses API", async () => {
+  const engine = new ExtractionEngine(
+    parseConfig({ openaiApiKey: "fixture-key", openaiBaseUrl: "https://api.openai.com/v1" }),
+  );
+  const signal = new AbortController().signal;
+  let calls = 0;
+  let request: Record<string, unknown> | undefined;
+  let requestOptions: { signal?: AbortSignal } | undefined;
+  Reflect.set(engine, "client", {
+    baseURL: "https://api.openai.com/v1",
+    responses: {
+      async create(body: Record<string, unknown>, options: { signal?: AbortSignal }) {
+        calls += 1;
+        request = body;
+        requestOptions = options;
+        return { output_text: response.content };
+      },
+    },
+  });
+  assertInvalidated(await engine.revalidateDependents(superseded, replacement, dependents, signal));
+  assert.equal(calls, 1);
+  assert.equal(request?.model, "gpt-5.5");
+  assert.equal(request?.max_output_tokens, 1024);
+  assert.match(String(request?.instructions), /revalidate dependent memory claims/i);
+  assert.match(String(request?.input), /SUPERSEDED MEMORY.*support-old/s);
+  assert.equal(requestOptions?.signal, signal);
+});
+
+test("revalidation uses the client's effective custom base URL", async () => {
+  const engine = new ExtractionEngine(
+    parseConfig({
+      openaiApiKey: "fixture-key",
+      openaiBaseUrl: "https://api.openai.com/v1",
+    }),
+  );
+  const signal = new AbortController().signal;
+  let chatRequest: Record<string, unknown> | undefined;
+  let chatOptions: { signal?: AbortSignal } | undefined;
+  let responsesCalls = 0;
+  Reflect.set(engine, "client", {
+    baseURL: "https://inference.example.test/v1",
+    chat: {
+      completions: {
+        async create(body: Record<string, unknown>, options: { signal?: AbortSignal }) {
+          chatRequest = body;
+          chatOptions = options;
+          return { choices: [{ message: response }] };
+        },
+      },
+    },
+    responses: {
+      async create() {
+        responsesCalls += 1;
+        throw new Error("custom endpoint does not implement /responses");
+      },
+    },
+  });
+
+  assertInvalidated(await engine.revalidateDependents(superseded, replacement, dependents, signal));
+  assert.equal(responsesCalls, 0);
+  assert.equal(chatRequest?.model, "gpt-5.5");
+  assert.equal(chatRequest?.max_tokens, 1024);
+  assert.ok(Array.isArray(chatRequest?.messages));
+  assert.equal(chatOptions?.signal, signal);
+});
+
+test("revalidation falls back to the direct route when the injected fast route rejects", async () => {
+  const engine = new ExtractionEngine(
+    parseConfig({ openaiApiKey: "fixture-key", openaiBaseUrl: "https://api.openai.com/v1" }),
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    async () => null,
+  );
+  const signal = new AbortController().signal;
+  let fastCalls = 0;
+  let directCalls = 0;
+  let fastMessages: TestMessage[] | undefined;
+  let fastOptions: TestOptions | undefined;
+  let request: Record<string, unknown> | undefined;
+  let requestOptions: { signal?: AbortSignal } | undefined;
+  Reflect.set(engine, "fastChatCompletion", async (messages: TestMessage[], options: TestOptions) => {
+    fastCalls += 1;
+    fastMessages = messages;
+    fastOptions = options;
+    throw new Error("fast route unavailable");
+  });
+  Reflect.set(engine, "client", {
+    baseURL: "https://api.openai.com/v1",
+    responses: {
+      async create(body: Record<string, unknown>, options: { signal?: AbortSignal }) {
+        directCalls += 1;
+        request = body;
+        requestOptions = options;
+        return { output_text: response.content };
+      },
+    },
+  });
+
+  assertInvalidated(await engine.revalidateDependents(superseded, replacement, dependents, signal));
+  assert.equal(fastCalls, 1);
+  assert.equal(directCalls, 1);
+  assert.equal(fastMessages?.[0]?.role, "system");
+  assert.match(fastMessages?.[1]?.content ?? "", /support-new/);
+  assert.equal(fastOptions?.maxTokens, 1024);
+  assert.equal(fastOptions?.signal, signal);
+  assert.equal(request?.max_output_tokens, 1024);
+  assert.equal(requestOptions?.signal, signal);
+});
+
+test("revalidation preserves the gateway fallback route for the legacy constructor", async () => {
+  const engine = new ExtractionEngine(parseConfig({ modelSource: "gateway" }));
+  const signal = new AbortController().signal;
+  let fastCalls = 0;
+  let fallbackCalls = 0;
+  let fallbackMessages: TestMessage[] | undefined;
+  let fallbackOptions: TestOptions | undefined;
+  Reflect.set(engine, "fastChatCompletion", async () => {
+    fastCalls += 1;
+    return null;
+  });
+  Reflect.set(engine, "fallbackLlm", {
+    async chatCompletion(
+      messages: TestMessage[],
+      options: TestOptions,
+    ) {
+      fallbackCalls += 1;
+      fallbackMessages = messages;
+      fallbackOptions = options;
+      return response;
+    },
+  });
+
+  assertInvalidated(await engine.revalidateDependents(superseded, replacement, dependents, signal));
+  assert.equal(fastCalls, 1);
+  assert.equal(fallbackCalls, 1);
+  assert.equal(fallbackMessages?.[0]?.role, "system");
+  assert.match(fallbackMessages?.[1]?.content ?? "", /dependent/);
+  assert.equal(fallbackOptions?.maxTokens, 1024);
+  assert.equal(fallbackOptions?.signal, signal);
+});

package/src/extraction.ts

@@ -1,10 +1,11 @@
 import OpenAI from "openai";
+import { isAbortError } from "./abort-error.js";
 import { log } from "./logger.js";
 import { delinearize } from "./delinearize.js";
 import { LocalLlmClient } from "./local-llm.js";
 import { shouldRunProactivePass } from "./proactive-contention.js";
 import { FallbackLlmClient, fallbackLlmRuntimeContextFromConfig, gatewayTaskChainOptions } from "./fallback-llm.js";
-import { revalidateDependentsViaLlm } from "./orchestration/dependency-revalidation.js";
+import { revalidateDependentsViaLlm, type RevalidationFastChatCompletion } from "./orchestration/dependency-revalidation.js";
 import {
   ExtractionResultSchema,
   ConsolidationResultSchema,
@@ -79,7 +80,6 @@ const CONSOLIDATION_RESPONSE_SCHEMA = `{
   "entityUpdates": [{"name": "person-jane-doe", "type": "person", "facts": ["Now leads the backend team", "Recently migrated the user service to TypeScript"]}]
 }`;
 
-
 function extractionEntityType(value: unknown): ExtractedEntityResult["type"] | undefined {
   const type = extractionText(value);
   if (
@@ -152,6 +152,7 @@ export class ExtractionEngine {
     localLlm?: LocalLlmClient,
     gatewayConfig?: GatewayConfig,
     modelRegistry?: ModelRegistry,
+    private readonly fastChatCompletion?: RevalidationFastChatCompletion,
   ) {
     this.profiler = profilerArg ?? new ProfilingCollector({ enabled: false, storageDir: "/tmp/engram-profiler-disabled", maxTraces: 0 });
     if (config.openaiApiKey) {
@@ -186,26 +187,14 @@ export class ExtractionEngine {
     }
   }
 
-  /**
-   * Whether LLM calls should be routed through the gateway model chain
-   * instead of the plugin's own local/OpenAI clients.
-   */
   private get useGatewayModelSource(): boolean {
     return this.config.modelSource === "gateway";
   }
 
-  /**
-   * Whether the local LLM path should be attempted.
-   * Disabled when gateway model source is active (gateway chain replaces local).
-   */
   private get shouldUseLocalLlm(): boolean {
     return resolveLocalLlmCapabilities(this.config).localLlm && !this.useGatewayModelSource;
   }
 
-  /**
-   * Whether the direct OpenAI client should be used.
-   * Disabled when gateway model source is active.
-   */
   private get shouldUseDirectClient(): boolean {
     return !this.useGatewayModelSource && this.client !== null;
   }
@@ -2453,29 +2442,55 @@ Respond with valid JSON matching this schema:
       reason?: string;
     }>;
   }> {
+    const complete: RevalidationFastChatCompletion = async (messages, options) => {
+      try {
+        const fast = await this.fastChatCompletion?.(messages, options);
+        if (fast) return fast;
+      } catch (error) {
+        if (isAbortError(error) || options.signal?.aborted) throw error;
+        log.warn(`dependency revalidation fast route failed: ${error}`);
+      }
+      if (this.shouldUseLocalLlm) {
+        try {
+          const local = await this.localLlm.chatCompletion(messages, options);
+          if (local || !this.config.localLlmFallback) return local;
+        } catch (error) {
+          if (!this.config.localLlmFallback) throw error;
+        }
+      }
+      if (!this.shouldUseDirectClient) {
+        return this.fallbackLlm.chatCompletion(messages, this.withGatewayAgent(options));
+      }
+      const client = this.client;
+      if (!client) return null;
+      if (!shouldAssumeOpenAiChatCompletions(client.baseURL ?? this.config.openaiBaseUrl)) {
+        const response = await client.chat.completions.create(
+          {
+            model: this.config.model,
+            messages,
+            max_tokens: options.maxTokens,
+          },
+          { signal: options.signal },
+        );
+        const content = response.choices[0]?.message?.content;
+        return typeof content === "string" ? { content } : null;
+      }
+      const response = await client.responses.create({
+        model: this.config.model,
+        instructions: messages.find((message) => message.role === "system")?.content,
+        input: messages.filter((message) => message.role !== "system").map((message) => message.content).join("\n\n"),
+        max_output_tokens: options.maxTokens,
+      }, { signal: options.signal });
+      return typeof response.output_text === "string" ? { content: response.output_text } : null;
+    };
     return revalidateDependentsViaLlm(
-      {
-        shouldUseLocalLlm: this.shouldUseLocalLlm,
-        shouldUseDirectClient: this.shouldUseDirectClient,
-        localLlm: this.localLlm,
-        fallbackLlm: this.fallbackLlm,
-        client: this.client,
-        config: this.config,
-        withGatewayAgent: this.withGatewayAgent.bind(this),
-        parseJsonObject: this.parseJsonObject,
-      },
+      { fastChatCompletion: complete, parseJsonObject: this.parseJsonObject },
       superseded,
       replacement,
       dependents,
-      signal,
+      { signal, timeoutMs: this.config.dependencyPropagation.timeoutMs },
     );
   }
-
-
-  /**
-   * Suggest links between a new memory and existing memories (Phase 3A).
-   * Called during extraction to build the knowledge graph.
-   */
   async suggestLinks(
     newMemory: { content: string; category: string },
     candidateMemories: Array<{ id: string; content: string; category: string }>,

package/src/orchestration/dependency-propagation.test.ts

@@ -79,7 +79,7 @@ function config(overrides: Record<string, unknown> = {}): PluginConfig {
 
 function fixture(
   initial: MemoryFile[],
-  verdicts: Verdict[] | Error | ((signal?: AbortSignal) => Promise<never>),
+  verdicts: Verdict[] | Error | ((signal?: AbortSignal) => Promise<{ verdicts: Verdict[] }>),
 ): Fixture {
   const memories = new Map(initial.map((item) => [item.frontmatter.id, item]));
   const calls: Fixture["calls"] = { revalidate: [], supersede: [], frontmatter: [] };
@@ -267,13 +267,24 @@ test("disabled propagation is an immediate no-op for boolean and string false",
       },
     );
 
-    assert.deepEqual(result, {
-      dependentsFound: 0,
-      invalidated: 0,
-      stillValid: 0,
-      uncertain: 0,
-      skipped: "disabled",
-    });
+    assert.deepEqual(
+      {
+        dependentsFound: result.dependentsFound,
+        invalidated: result.invalidated,
+        stillValid: result.stillValid,
+        uncertain: result.uncertain,
+        skipped: result.skipped,
+      },
+      {
+        dependentsFound: 0,
+        invalidated: 0,
+        stillValid: 0,
+        uncertain: 0,
+        skipped: "disabled",
+      },
+    );
+    assert.equal(result.route, null);
+    assert.equal(typeof result.durationMs, "number");
     assert.equal(fixtureValue.calls.revalidate.length, 0);
   }
 });
@@ -295,6 +306,12 @@ test("invalidated verdict supersedes the dependent and persists dependency front
   );
 
   assert.equal(result.invalidated, 1);
+  assert.equal(result.dependentsFound, 1);
+  assert.equal(result.stillValid, 0);
+  assert.equal(result.uncertain, 0);
+  assert.equal(result.skipped, null);
+  assert.equal(result.route, "fast-completion");
+  assert.equal(typeof result.durationMs, "number");
   assert.deepEqual(fixtureValue.calls.supersede, [
     {
       id: "dep",
@@ -387,6 +404,12 @@ test("LLM errors skip the event and perform zero writes", async () => {
     },
   );
 
+  assert.equal(result.dependentsFound, 1);
+  assert.equal(result.invalidated, 0);
+  assert.equal(result.stillValid, 0);
+  assert.equal(result.uncertain, 0);
+  assert.equal(result.route, "fast-completion");
+  assert.equal(typeof result.durationMs, "number");
   assert.equal(result.skipped, "llm_error");
   assert.equal(fixtureValue.calls.supersede.length, 0);
   assert.equal(fixtureValue.calls.frontmatter.length, 0);
@@ -411,11 +434,69 @@ test("LLM timeout aborts the batch and performs zero writes", async () => {
     },
   );
 
+  assert.equal(result.dependentsFound, 1);
+  assert.equal(result.route, "fast-completion");
+  assert.equal(typeof result.durationMs, "number");
   assert.equal(result.skipped, "timeout");
   assert.equal(fixtureValue.calls.supersede.length, 0);
   assert.equal(fixtureValue.calls.frontmatter.length, 0);
 });
 
+test("a completion that ignores AbortSignal returns at the shared deadline", async (t) => {
+  t.mock.timers.enable({ apis: ["setTimeout", "Date"], now: 0 });
+  try {
+    const old = memory("old", { links: [{ targetId: "dep", linkType: "supports" }] });
+    const fixtureValue = fixture([old, memory("dep")], () => new Promise<never>(() => {}));
+    const resultPromise = propagateInvalidation(
+      deps(fixtureValue, { dependencyPropagation: { timeoutMs: 20 } }),
+      {
+        oldMemory: old,
+        replacementId: "new",
+        replacementContent: "replacement",
+        cause: "contradiction",
+        namespaceScope: "namespace-a",
+      },
+    );
+
+    await Promise.resolve();
+    t.mock.timers.tick(20);
+    const result = await resultPromise;
+
+    assert.equal(result.dependentsFound, 1);
+    assert.equal(result.invalidated, 0);
+    assert.equal(result.stillValid, 0);
+    assert.equal(result.uncertain, 0);
+    assert.equal(result.skipped, "timeout");
+    assert.equal(result.route, "fast-completion");
+    assert.equal(result.durationMs, 20);
+    assert.equal(fixtureValue.calls.supersede.length, 0);
+    assert.equal(fixtureValue.calls.frontmatter.length, 0);
+  } finally {
+    t.mock.timers.reset();
+  }
+});
+
+test("a zero timeout disables the deadline", async () => {
+  const old = memory("old", { links: [{ targetId: "dep", linkType: "supports" }] });
+  const fixtureValue = fixture([old, memory("dep")], () =>
+    new Promise((resolve) => setTimeout(() => resolve({
+      verdicts: [{ memoryId: "dep", verdict: "invalidated" }],
+    }), 5)),
+  );
+  const result = await propagateInvalidation(
+    deps(fixtureValue, { dependencyPropagation: { timeoutMs: 0 } }),
+    {
+      oldMemory: old,
+      replacementId: "new",
+      replacementContent: "replacement",
+      cause: "contradiction",
+      namespaceScope: "namespace-a",
+    },
+  );
+  assert.equal(result.invalidated, 1);
+  assert.equal(result.skipped, null);
+});
+
 test("dryRun computes invalidation verdicts without writing", async () => {
   const old = memory("old", { links: [{ targetId: "dep", linkType: "supports" }] });
   const fixtureValue = fixture([old, memory("dep")], [{ memoryId: "dep", verdict: "invalidated" }]);

package/src/orchestration/dependency-propagation.ts

@@ -34,6 +34,8 @@ export interface PropagationResult {
   stillValid: number;
   uncertain: number;
   skipped: "disabled" | "no_dependents" | "llm_error" | "timeout" | null;
+  route: "fast-completion" | null;
+  durationMs: number;
 }
 
 function propagationConfig(config: PluginConfig): DependencyPropagationConfig {
@@ -96,8 +98,13 @@ export function findDependents(
     });
 }
 
-function emptyResult(skipped: PropagationResult["skipped"]): PropagationResult {
-  return { dependentsFound: 0, invalidated: 0, stillValid: 0, uncertain: 0, skipped };
+function emptyResult(
+  skipped: PropagationResult["skipped"],
+  durationMs: number,
+  route: PropagationResult["route"] = null,
+  dependentsFound = 0,
+): PropagationResult {
+  return { dependentsFound, invalidated: 0, stillValid: 0, uncertain: 0, skipped, route, durationMs };
 }
 
 function logResult(event: PropagationEvent, result: PropagationResult): void {
@@ -111,6 +118,8 @@ function logResult(event: PropagationEvent, result: PropagationResult): void {
       stillValid: result.stillValid,
       uncertain: result.uncertain,
       skipped: result.skipped,
+      route: result.route,
+      durationMs: result.durationMs,
     })}`,
   );
 }
@@ -136,16 +145,17 @@ export async function propagateInvalidation(
   deps: { storage: StorageManager; extraction: ExtractionEngine; config: PluginConfig },
   event: PropagationEvent,
 ): Promise<PropagationResult> {
+  const startedAt = Date.now();
   const config = propagationConfig(deps.config);
   if (!isEnabled(config.enabled)) {
-    const result = emptyResult("disabled");
+    const result = emptyResult("disabled", Date.now() - startedAt);
     logResult(event, result);
     return result;
   }
 
   const maxDependents = config.maxDependents;
   if (maxDependents <= 0) {
-    const result = emptyResult("no_dependents");
+    const result = emptyResult("no_dependents", Date.now() - startedAt);
     logResult(event, result);
     return result;
   }
@@ -155,7 +165,7 @@ export async function propagateInvalidation(
     memories = await deps.storage.readAllMemories();
   } catch (error) {
     log.warn(`dependency propagation discovery failed for ${event.oldMemory.frontmatter.id}: ${error}`);
-    const result = emptyResult("llm_error");
+    const result = emptyResult("llm_error", Date.now() - startedAt);
     logResult(event, result);
     return result;
   }
@@ -171,46 +181,67 @@ export async function propagateInvalidation(
   const dependents = discovered.slice(0, Math.max(0, Math.floor(maxDependents)));
 
   if (dependents.length === 0) {
-    const result = emptyResult("no_dependents");
+    const result = emptyResult("no_dependents", Date.now() - startedAt);
     logResult(event, result);
     return result;
   }
 
   const controller = new AbortController();
   const timeoutMs = config.timeoutMs;
-  const timeout = Number.isFinite(timeoutMs) && timeoutMs > 0
-    ? setTimeout(() => controller.abort(new PropagationTimeoutError()), timeoutMs)
+  let timedOut = false;
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const deadline = Number.isFinite(timeoutMs) && timeoutMs > 0
+    ? new Promise<never>((_, reject) => {
+        timeout = setTimeout(() => {
+          timedOut = true;
+          const error = new PropagationTimeoutError();
+          controller.abort(error);
+          reject(error);
+        }, timeoutMs);
+      })
     : undefined;
+  const revalidation = Promise.resolve().then(() => deps.extraction.revalidateDependents(
+    { id: event.oldMemory.frontmatter.id, content: event.oldMemory.content },
+    event.replacementId && event.replacementContent !== null
+      ? { id: event.replacementId, content: event.replacementContent }
+      : null,
+    dependents.map((memory) => ({
+      id: memory.frontmatter.id,
+      category: memory.frontmatter.category,
+      content: memory.content,
+    })),
+    controller.signal,
+  ));
 
   let verdicts: Array<{ memoryId: string; verdict: "still_valid" | "invalidated" | "uncertain"; reason?: string }>;
   try {
-    const response = await deps.extraction.revalidateDependents(
-      { id: event.oldMemory.frontmatter.id, content: event.oldMemory.content },
-      event.replacementId && event.replacementContent !== null
-        ? { id: event.replacementId, content: event.replacementContent }
-        : null,
-      dependents.map((memory) => ({
-        id: memory.frontmatter.id,
-        category: memory.frontmatter.category,
-        content: memory.content,
-      })),
-      controller.signal,
-    );
-    verdicts = response.verdicts;
-    if (controller.signal.aborted) {
-      if (timeout !== undefined) clearTimeout(timeout);
-      const result = emptyResult("timeout");
+    const response = deadline
+      ? await Promise.race([revalidation, deadline])
+      : await revalidation;
+    if (timedOut || controller.signal.aborted) {
+      const result = emptyResult(
+        "timeout",
+        Date.now() - startedAt,
+        "fast-completion",
+        dependents.length,
+      );
       logResult(event, result);
       return result;
     }
+    verdicts = response.verdicts;
   } catch (error) {
-    const result = emptyResult(isTimeoutError(error, controller.signal) ? "timeout" : "llm_error");
+    const result = emptyResult(
+      timedOut || isTimeoutError(error, controller.signal) ? "timeout" : "llm_error",
+      Date.now() - startedAt,
+      "fast-completion",
+      dependents.length,
+    );
     log.warn(`dependency propagation revalidation failed for ${event.oldMemory.frontmatter.id}: ${error}`);
     logResult(event, result);
-    if (timeout !== undefined) clearTimeout(timeout);
     return result;
+  } finally {
+    clearTimeout(timeout!);
   }
-  if (timeout !== undefined) clearTimeout(timeout);
 
   let invalidated = 0;
   let stillValid = 0;
@@ -257,6 +288,8 @@ export async function propagateInvalidation(
     stillValid,
     uncertain,
     skipped: null,
+    route: "fast-completion",
+    durationMs: Date.now() - startedAt,
   };
   logResult(event, result);
   return result;