@remnic/core 9.50.0 → 9.50.2

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;

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

@@ -0,0 +1,119 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  revalidateDependentsViaLlm,
+  type RevalidationDeps,
+} from "./dependency-revalidation.js";
+
+type Dependent = { id: string; category: string; content: string };
+type CompletionOptions = {
+  operation?: string;
+  priority?: "background" | "recall-critical";
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  temperature?: number;
+  maxTokens?: number;
+};
+
+type CompletionCall = {
+  messages: Array<{ role: string; content: string }>;
+  options: CompletionOptions;
+};
+
+const superseded = { id: "old", content: "old supporting fact" };
+const replacement = { id: "new", content: "new supporting fact" };
+
+function dependents(count: number): Dependent[] {
+  return Array.from({ length: count }, (_, index) => ({
+    id: `dependent-${String(index + 1).padStart(2, "0")}`,
+    category: index % 2 === 0 ? "fact" : "decision",
+    content: `dependent claim ${index + 1}`,
+  }));
+}
+
+function makeDeps(payload: unknown, calls: CompletionCall[]): RevalidationDeps {
+  return {
+    fastChatCompletion: async (messages, options) => {
+      calls.push({ messages, options });
+      return { content: JSON.stringify(payload) };
+    },
+    parseJsonObject: (raw) => JSON.parse(raw ?? "null") as unknown,
+  };
+}
+
+test("revalidation uses only the injected fast completion seam", async () => {
+  const calls: CompletionCall[] = [];
+  const signal = new AbortController().signal;
+  const requested = dependents(1);
+
+  await revalidateDependentsViaLlm(
+    makeDeps({ verdicts: [{ memoryId: requested[0]!.id, verdict: "still_valid" }] }, calls),
+    superseded,
+    replacement,
+    requested,
+    { signal, timeoutMs: 37 },
+  );
+
+  const call = calls[0];
+  assert.ok(call);
+  assert.equal(call.options.operation, "dependency_revalidation");
+  assert.equal(call.options.priority, "background");
+  assert.equal(call.options.timeoutMs, 37);
+  assert.equal(call.options.signal, signal);
+});
+
+test("revalidation normalizes one verdict per dependent for one, five, and ten dependents", async () => {
+  for (const count of [1, 5, 10]) {
+    const requested = dependents(count);
+    const calls: CompletionCall[] = [];
+    const result = await revalidateDependentsViaLlm(
+      makeDeps(
+        {
+          verdicts: [
+            ...requested.map((dependent) => ({ memoryId: dependent.id, verdict: "invalidated" })),
+            { memoryId: "unknown-id", verdict: "invalidated" },
+            { memoryId: requested[0]!.id, verdict: "still_valid" },
+          ],
+        },
+        calls,
+      ),
+      superseded,
+      replacement,
+      requested,
+      { timeoutMs: 37 },
+    );
+
+    assert.equal(result.verdicts.length, count);
+    assert.deepEqual(
+      result.verdicts.map((verdict) => verdict.memoryId),
+      requested.map((dependent) => dependent.id),
+    );
+    assert.equal(new Set(result.verdicts.map((verdict) => verdict.memoryId)).size, count);
+    assert.equal(calls.length, 1);
+  }
+});
+
+test("revalidation rejects empty completion output", async () => {
+  for (const content of [null, "", "   "]) {
+    const deps: RevalidationDeps = {
+      fastChatCompletion: async () => content === null ? null : { content },
+      parseJsonObject: (raw) => JSON.parse(raw ?? "null") as unknown,
+    };
+    await assert.rejects(
+      revalidateDependentsViaLlm(deps, superseded, replacement, dependents(1)),
+      /no dependency revalidation output/,
+    );
+  }
+});
+
+test("revalidation defaults invalid verdict enums to uncertain", async () => {
+  const requested = dependents(1);
+  const result = await revalidateDependentsViaLlm(
+    makeDeps({ verdicts: [{ memoryId: requested[0]!.id, verdict: "approved" }] }, []),
+    superseded,
+    replacement,
+    requested,
+  );
+  assert.deepEqual(result.verdicts, [{ memoryId: requested[0]!.id, verdict: "uncertain" }]);
+});

package/src/orchestration/dependency-revalidation.ts

@@ -4,8 +4,6 @@
  * Extracted from ExtractionEngine to keep extraction.ts under its ratchet
  * ceiling. The ExtractionEngine.revalidateDependents method delegates here.
  */
-import type { LocalLlmClient } from "../local-llm.js";
-import type { FallbackLlmClient, FallbackLlmOptions } from "../fallback-llm.js";
 
 export interface RevalidationVerdict {
   memoryId: string;
@@ -13,18 +11,20 @@ export interface RevalidationVerdict {
   reason?: string;
 }
 
-export interface RevalidationDeps {
-  shouldUseLocalLlm: boolean;
-  shouldUseDirectClient: boolean;
-  localLlm: LocalLlmClient;
-  fallbackLlm: FallbackLlmClient;
-  client: unknown;
-  config: { model: string; localLlmFallback?: boolean };
-  withGatewayAgent: (opts: {
-    temperature: number;
-    maxTokens: number;
+export type RevalidationFastChatCompletion = (
+  messages: Array<{ role: "system" | "user" | "assistant"; content: string }>,
+  options: {
+    temperature?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+    operation?: string;
+    priority?: "background" | "recall-critical";
     signal?: AbortSignal;
-  }) => FallbackLlmOptions;
+  },
+) => Promise<{ content: string } | null>;
+
+export interface RevalidationDeps {
+  fastChatCompletion: RevalidationFastChatCompletion;
   parseJsonObject: (raw: string | null) => unknown;
 }
 
@@ -95,78 +95,27 @@ export async function revalidateDependentsViaLlm(
   superseded: { id: string; content: string },
   replacement: { id: string; content: string } | null,
   dependents: Array<{ id: string; category: string; content: string }>,
-  signal?: AbortSignal,
+  options: { signal?: AbortSignal; timeoutMs?: number } = {},
 ): Promise<{ verdicts: RevalidationVerdict[] }> {
   const { input, instructionText } = buildPrompt(superseded, replacement, dependents);
   const maxTokens = Math.max(1024, dependents.length * 256);
-
-  let rawContent: string | null = null;
-  if (deps.shouldUseLocalLlm) {
-    try {
-      const response = await deps.localLlm.chatCompletion(
-        [
-          { role: "system", content: instructionText },
-          { role: "user", content: input },
-        ],
-        {
-          temperature: 0.2,
-          maxTokens,
-          operation: "dependency_revalidation",
-          priority: "background",
-          signal,
-        },
-      );
-      rawContent = response?.content ?? null;
-      if (!rawContent && !deps.config.localLlmFallback) {
-        throw new Error("local LLM returned no dependency revalidation output");
-      }
-    } catch (error) {
-      if (!deps.config.localLlmFallback || signal?.aborted) throw error;
-    }
-  }
-
-  if (rawContent === null && !deps.shouldUseDirectClient) {
-    const response = await deps.fallbackLlm.chatCompletion(
-      [
-        { role: "system", content: instructionText },
-        { role: "user", content: input },
-      ],
-      deps.withGatewayAgent({ temperature: 0.2, maxTokens, signal }),
-    );
-    rawContent = response?.content ?? null;
-    if (!rawContent) throw new Error("fallback LLM returned no dependency revalidation output");
-  }
-
-  if (rawContent === null && deps.shouldUseDirectClient) {
-    const chatClient = deps.client as unknown as {
-      chat: {
-        completions: {
-          create(
-            request: {
-              model: string;
-              messages: Array<{ role: string; content: string }>;
-              max_tokens?: number;
-            },
-            options?: { signal?: AbortSignal },
-          ): Promise<{ choices?: Array<{ message?: { content?: string } }> }>;
-        };
-      };
-    };
-    const response = await chatClient.chat.completions.create(
-      {
-        model: deps.config.model,
-        messages: [
-          { role: "system", content: instructionText },
-          { role: "user", content: input },
-        ],
-        max_tokens: maxTokens,
-      },
-      { signal },
-    );
-    rawContent = response.choices?.[0]?.message?.content ?? null;
-    if (!rawContent?.trim()) {
-      throw new Error("direct client returned no dependency revalidation output");
-    }
+  const response = await deps.fastChatCompletion(
+    [
+      { role: "system", content: instructionText },
+      { role: "user", content: input },
+    ],
+    {
+      temperature: 0.2,
+      maxTokens,
+      operation: "dependency_revalidation",
+      priority: "background",
+      timeoutMs: options.timeoutMs,
+      signal: options.signal,
+    },
+  );
+  const rawContent = response?.content ?? null;
+  if (!rawContent?.trim()) {
+    throw new Error("fast completion returned no dependency revalidation output");
   }
 
   return { verdicts: normalizeVerdicts(deps.parseJsonObject(rawContent), dependents) };

package/src/orchestrator.ts

@@ -24,6 +24,7 @@ import { SmartBuffer } from "./buffer.js";
 import { chunkContent, type ChunkingConfig } from "./chunking.js";
 import { semanticChunkContent, type SemanticChunkResult } from "./semantic-chunking.js";
 import { ExtractionEngine } from "./extraction.js";
+import type { RevalidationFastChatCompletion } from "./orchestration/dependency-revalidation.js";
 import { detectPassiveCorrections } from "./correction/passive-correction-detector.js";
 import { capturePassiveCorrections, type PassiveCaptureConfig } from "./correction/passive-capture.js";
 import { createCorrectionService } from "./correction/correction-access-wiring.js";
@@ -1684,6 +1685,7 @@ export class Orchestrator {
       this.localLlm,
       config.gatewayConfig,
       this.modelRegistry,
+      this.fastChatCompletion.bind(this),
     );
     this.lifecyclePolicyCoordinator = new LifecyclePolicyCoordinator({
       config,
@@ -1881,21 +1883,17 @@ export class Orchestrator {
     );
   }
 
-  /**
-   * Execute a fast-tier LLM chat completion.
-   * When gateway model source is active and fastGatewayAgentId is configured,
-   * routes through the gateway chain. Otherwise uses the local fast LLM.
-   */
+  /** Execute a fast-tier completion through the gateway when configured, otherwise the local fast LLM. */
   private async fastChatCompletion(
     messages: Array<{ role: string; content: string }>,
-    options: { temperature?: number; maxTokens?: number; timeoutMs?: number; operation?: string; priority?: "background" | "recall-critical" },
+    options: Parameters<RevalidationFastChatCompletion>[1],
   ): Promise<{ content: string } | null> {
     if (this._fastGatewayLlm && this.config.modelSource === "gateway") {
       const agentId =
         this.config.fastGatewayAgentId || this.config.gatewayAgentId || undefined;
       const result = await this._fastGatewayLlm.chatCompletion(
         messages as Array<{ role: "system" | "user" | "assistant"; content: string }>,
-        { temperature: options.temperature, maxTokens: options.maxTokens, timeoutMs: options.timeoutMs, agentId },
+        { ...options, agentId },
       );
       return result ? { content: result.content } : null;
     }

package/src/runtime/daemon-health.ts

@@ -0,0 +1,53 @@
+import { launchProcessSync } from "./child-process.js";
+import { mergeEnv } from "./env.js";
+import { httpProtocolForHost } from "./http-transport.js";
+
+const HEALTH_EXIT_OK = 0;
+const HEALTH_EXIT_UNAUTHORIZED = 2;
+
+export function checkDaemonHealth(
+  host: string,
+  port: number,
+  authToken?: string,
+  allowInsecureHttp = false,
+): boolean {
+  try {
+    const safePort = Math.trunc(Number(port));
+    if (!Number.isFinite(safePort) || safePort < 1 || safePort > 65535) return false;
+
+    const bareHost = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+    const script = [
+      "const env = process['env'];",
+      "const protocol = env.REMNIC_HEALTH_PROTOCOL;",
+      "if (protocol !== 'http' && protocol !== 'https') process.exit(1);",
+      "const transport = require(protocol);",
+      "const headers = {};",
+      "if (env.REMNIC_HEALTH_TOKEN) headers['authorization'] = 'Bearer ' + env.REMNIC_HEALTH_TOKEN;",
+      "const req = transport.get({",
+      "  host: env.REMNIC_HEALTH_HOST,",
+      "  port: parseInt(env.REMNIC_HEALTH_PORT, 10),",
+      "  path: '/engram/v1/health', headers, timeout: 3000,",
+      "}, (res) => { process.exit(res.statusCode === 200 ? 0 : res.statusCode === 401 ? 2 : 1); });",
+      "req.on('error', () => process.exit(1));",
+      "req.on('timeout', () => { req.destroy(); process.exit(1); });",
+    ].join("\n");
+    const env: NodeJS.ProcessEnv = mergeEnv({
+      REMNIC_HEALTH_HOST: bareHost,
+      REMNIC_HEALTH_PORT: String(safePort),
+      REMNIC_HEALTH_PROTOCOL: httpProtocolForHost(host, allowInsecureHttp),
+    });
+    if (authToken) env.REMNIC_HEALTH_TOKEN = authToken;
+
+    const launchOptions = { timeout: 4000, env };
+    const result = launchProcessSync(process.execPath, ["-e", script], launchOptions);
+    if (result.status === HEALTH_EXIT_OK) return true;
+    if (result.status !== HEALTH_EXIT_UNAUTHORIZED) return false;
+
+    console.error("[remnic/connectors] health probe got 401 — retrying after token cache TTL...");
+    launchProcessSync(process.execPath, ["-e", "setTimeout(() => {}, 6000)"], { timeout: 7000, env: {} });
+    const retry = launchProcessSync(process.execPath, ["-e", script], launchOptions);
+    return retry.status === HEALTH_EXIT_OK;
+  } catch {
+    return false;
+  }
+}

package/src/runtime/http-transport.ts

@@ -0,0 +1,25 @@
+import { isIP } from "node:net";
+
+function normalizedIp(host: string): string {
+  const value = host.trim().replace(/^\[/, "").replace(/\]\.?$/, "").replace(/\.$/, "");
+  if (isIP(value) === 4) return value;
+  if (isIP(value) !== 6) return "";
+  return new URL(`http://[${value}]/`).hostname.slice(1, -1);
+}
+
+export function isLoopbackHost(host: string): boolean {
+  const normalized = host.trim().replace(/^\[/, "").replace(/\]\.?$/, "").replace(/\.$/, "").toLowerCase();
+  if (normalized === "localhost" || normalized.endsWith(".localhost")) return true;
+
+  const ip = normalizedIp(normalized);
+  if (ip === "::1") return true;
+  if (isIP(ip) === 4) return ip.startsWith("127.");
+  if (!ip.startsWith("::ffff:")) return false;
+
+  const [high, low] = ip.slice("::ffff:".length).split(":");
+  return Number.parseInt(high, 16) >>> 8 === 127 || (high === "0" && Number.parseInt(low, 16) >>> 8 === 127);
+}
+
+export function httpProtocolForHost(host: string, allowInsecureHttp = false): "http" | "https" {
+  return isLoopbackHost(host) || allowInsecureHttp ? "http" : "https";
+}