@remnic/core 9.69.26 → 9.69.28

package/dist/who-knows.js

@@ -9,13 +9,13 @@ import {
   loadWhoKnowsEntities,
   tokenizeTopic,
   validateWhoKnowsInput
-} from "./chunk-2EKJDQZB.js";
-import "./chunk-XSGUMQQQ.js";
+} from "./chunk-INBOGQ3E.js";
+import "./chunk-UY2RORVF.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-46WM6JX2.js";
 import "./chunk-D5F7TKMH.js";
-import "./chunk-2Z4GS5E6.js";
-import "./chunk-6CVNSDCZ.js";
+import "./chunk-ZMNT26KV.js";
+import "./chunk-RFWEDCRC.js";
 import "./chunk-BD7JTBYP.js";
 import "./chunk-OB3XMWX5.js";
 import "./chunk-CYEPCZN5.js";
@@ -24,10 +24,10 @@ import "./chunk-YQNNHLCG.js";
 import "./chunk-4O6WRBGE.js";
 import "./chunk-6KTXE6A3.js";
 import "./chunk-GUMZC2BO.js";
-import "./chunk-227UFSEQ.js";
+import "./chunk-7RZJWZ46.js";
+import "./chunk-A7Q43EUZ.js";
 import "./chunk-ET356KSB.js";
 import "./chunk-72A4L5JJ.js";
-import "./chunk-A7Q43EUZ.js";
 import "./chunk-S2V7RUCL.js";
 import "./chunk-SO7SV523.js";
 import "./chunk-SCU65EZI.js";
@@ -49,10 +49,10 @@ import "./chunk-RBOJCG4T.js";
 import "./chunk-R7QY5ZVB.js";
 import "./chunk-5WITETWU.js";
 import "./chunk-6CIAGZ6X.js";
-import "./chunk-CEH2AFXG.js";
+import "./chunk-C24UZSFW.js";
 import "./chunk-JXN77SGO.js";
-import "./chunk-IUM3VSHI.js";
 import "./chunk-ZLQ37WJX.js";
+import "./chunk-IUM3VSHI.js";
 import "./chunk-3QQTXYZ6.js";
 import "./chunk-BT7NVCML.js";
 import "./chunk-C64XATK7.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.69.26",
+  "version": "9.69.28",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -31,6 +31,16 @@
       "remnic-source": "./src/salvage-envelope.ts",
       "import": "./dist/salvage-envelope.js"
     },
+    "./http-retry": {
+      "types": "./dist/http-retry.d.ts",
+      "remnic-source": "./src/http-retry.ts",
+      "import": "./dist/http-retry.js"
+    },
+    "./http-retry.js": {
+      "types": "./dist/http-retry.d.ts",
+      "remnic-source": "./src/http-retry.ts",
+      "import": "./dist/http-retry.js"
+    },
     "./abort-error.js": {
       "types": "./dist/abort-error.d.ts",
       "remnic-source": "./src/abort-error.ts",
@@ -1215,6 +1225,16 @@
       "remnic-source": "./src/importers/index.ts",
       "import": "./dist/importers/index.js"
     },
+    "./importers/test-utils": {
+      "types": "./dist/importers/test-utils.d.ts",
+      "remnic-source": "./src/importers/test-utils.ts",
+      "import": "./dist/importers/test-utils.js"
+    },
+    "./importers/test-utils.js": {
+      "types": "./dist/importers/test-utils.d.ts",
+      "remnic-source": "./src/importers/test-utils.ts",
+      "import": "./dist/importers/test-utils.js"
+    },
     "./intent": {
       "types": "./dist/intent.d.ts",
       "remnic-source": "./src/intent.ts",
@@ -3227,7 +3247,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.69.26"
+    "@remnic/coding-graph": "^9.69.28"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/http-retry.test.ts

@@ -0,0 +1,281 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  ConnectorApiError,
+  describeNetworkError,
+  discardResponseBody,
+  retryAfterHeaderMs,
+  retryingFetch,
+  stripTrailingSlashes,
+} from "./http-retry.js";
+
+function jsonResponse(body: unknown, status = 200, headers: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify(body), { status, headers });
+}
+
+function scriptFetch(script: Array<() => Response | Promise<Response>>): {
+  fetchImpl: typeof fetch;
+  calls: () => number;
+} {
+  let calls = 0;
+  return {
+    fetchImpl: (async () => {
+      const step = script[Math.min(calls, script.length - 1)];
+      calls += 1;
+      return step();
+    }) as typeof fetch,
+    calls: () => calls,
+  };
+}
+
+test("retries 5xx with exponential backoff, then returns the success response", async () => {
+  const sleeps: number[] = [];
+  const { fetchImpl, calls } = scriptFetch([
+    () => jsonResponse({}, 502),
+    () => jsonResponse({}, 503),
+    () => jsonResponse({ ok: true }),
+  ]);
+  const response = await retryingFetch("https://api.example.invalid/v1", {
+    init: { method: "GET" },
+    fetchImpl,
+    sleep: async (ms) => {
+      sleeps.push(ms);
+    },
+    networkError: () => new ConnectorApiError("network"),
+    retryableError: (r) => new ConnectorApiError(`responded ${r.status}`, r.status),
+  });
+  assert.equal(response.status, 200);
+  assert.deepEqual(await response.json(), { ok: true });
+  assert.equal(calls(), 3);
+  assert.deepEqual(sleeps, [1_000, 2_000]);
+});
+
+test("exhausted retries on 5xx throw the vendor retryable error", async () => {
+  const sleeps: number[] = [];
+  const { fetchImpl, calls } = scriptFetch([() => jsonResponse({}, 503)]);
+  await assert.rejects(
+    retryingFetch("https://api.example.invalid", {
+      fetchImpl,
+      sleep: async (ms) => {
+        sleeps.push(ms);
+      },
+      networkError: () => new ConnectorApiError("network"),
+      retryableError: (r) => new ConnectorApiError(`responded ${r.status}`, r.status),
+    }),
+    (err: unknown) => err instanceof ConnectorApiError && err.status === 503,
+  );
+  assert.equal(calls(), 4);
+  assert.deepEqual(sleeps, [1_000, 2_000, 4_000]);
+});
+
+test("exhausted network failures call networkError with attempt count and timeout flag", async () => {
+  const pathy = new Error("connect ECONNREFUSED /home/user/.cache/loader.js");
+  (pathy as NodeJS.ErrnoException).code = "ECONNREFUSED";
+  const { fetchImpl } = scriptFetch([
+    () => Promise.reject(pathy),
+  ]);
+  let seen: { attempts: number; timedOut: boolean } | undefined;
+  await assert.rejects(
+    retryingFetch("https://api.example.invalid", {
+      fetchImpl,
+      sleep: async () => {},
+      networkError: (err, attempts, context) => {
+        seen = { attempts, ...context };
+        return new ConnectorApiError(`failed after ${attempts}: ${describeNetworkError(err)}`);
+      },
+      retryableError: (r) => new ConnectorApiError(`responded ${r.status}`, r.status),
+    }),
+    (err: unknown) =>
+      err instanceof ConnectorApiError && err.message === "failed after 4: Error (ECONNREFUSED)",
+  );
+  assert.deepEqual(seen, { attempts: 4, timedOut: false });
+});
+
+test("a caller abort mid-flight rethrows the raw error without retrying", async () => {
+  const controller = new AbortController();
+  let calls = 0;
+  const { promise, reject } = Promise.withResolvers<never>();
+  const fetchImpl = (async (_url: string | URL | Request, init?: RequestInit) => {
+    calls += 1;
+    init?.signal?.addEventListener("abort", () =>
+      reject(new DOMException("This operation was aborted", "AbortError")),
+    );
+    return promise;
+  }) as typeof fetch;
+  const pending = retryingFetch("https://api.example.invalid", {
+    fetchImpl,
+    signal: controller.signal,
+    sleep: async () => {
+      throw new Error("must not sleep after a caller abort");
+    },
+    networkError: () => new ConnectorApiError("network"),
+    retryableError: (r) => new ConnectorApiError(`responded ${r.status}`, r.status),
+  });
+  const finished = assert.rejects(
+    pending,
+    (err: unknown) => err instanceof DOMException && err.name === "AbortError",
+  );
+  controller.abort();
+  await finished;
+  assert.equal(calls, 1);
+});
+
+test("Retry-After seconds and HTTP-date override the exponential backoff, capped", async () => {
+  const sleeps: number[] = [];
+  const options = {
+    sleep: async (ms: number) => {
+      sleeps.push(ms);
+    },
+    networkError: () => new ConnectorApiError("network"),
+    retryableError: (r: Response) => new ConnectorApiError(`responded ${r.status}`, r.status),
+  };
+  {
+    const { fetchImpl } = scriptFetch([
+      () => jsonResponse({}, 429, { "retry-after": "7" }),
+      () => jsonResponse([]),
+    ]);
+    await retryingFetch("https://api.example.invalid", { fetchImpl, ...options });
+    assert.deepEqual(sleeps, [7_000]);
+  }
+  {
+    sleeps.length = 0;
+    const { fetchImpl } = scriptFetch([
+      () => jsonResponse({}, 429, { "retry-after": "120" }),
+      () => jsonResponse([]),
+    ]);
+    await retryingFetch("https://api.example.invalid", { fetchImpl, ...options });
+    assert.deepEqual(sleeps, [30_000], "hostile Retry-After is capped at maxRetryDelayMs");
+  }
+  {
+    sleeps.length = 0;
+    const soon = new Date(Date.now() + 3_000).toUTCString();
+    const { fetchImpl } = scriptFetch([
+      () => jsonResponse({}, 429, { "retry-after": soon }),
+      () => jsonResponse([]),
+    ]);
+    await retryingFetch("https://api.example.invalid", { fetchImpl, ...options });
+    assert.ok(sleeps[0] !== undefined && sleeps[0] > 2_000 && sleeps[0] <= 3_000, `HTTP-date delay, got ${sleeps[0]}`);
+  }
+});
+
+test("a vendor retryAfterMs override wins over the header; null falls back", async () => {
+  const sleeps: number[] = [];
+  const { fetchImpl } = scriptFetch([
+    () => jsonResponse({ retryAfter: "2" }, 429),
+    () => jsonResponse([]),
+  ]);
+  await retryingFetch("https://api.example.invalid", {
+    fetchImpl,
+    sleep: async (ms) => {
+      sleeps.push(ms);
+    },
+    retryAfterMs: async (response) => {
+      const body = (await response.clone().json()) as { retryAfter?: unknown };
+      const parsed = Number(body?.retryAfter);
+      return Number.isFinite(parsed) && parsed > 0 ? parsed * 1_000 : null;
+    },
+    networkError: () => new ConnectorApiError("network"),
+    retryableError: (r) => new ConnectorApiError(`responded ${r.status}`, r.status),
+  });
+  assert.deepEqual(sleeps, [2_000]);
+});
+
+test("non-retryable statuses are returned to the caller untouched", async () => {
+  const { fetchImpl, calls } = scriptFetch([() => jsonResponse({ error: "nope" }, 404)]);
+  const response = await retryingFetch("https://api.example.invalid", {
+    fetchImpl,
+    sleep: async () => {},
+    networkError: () => new ConnectorApiError("network"),
+    retryableError: (r) => new ConnectorApiError(`responded ${r.status}`, r.status),
+  });
+  assert.equal(response.status, 404);
+  assert.equal(calls(), 1);
+});
+
+test("buildInit runs once; retries reuse the same init", async () => {
+  const tokens: string[] = [];
+  const { fetchImpl } = scriptFetch([
+    () => jsonResponse({}, 429),
+    () => jsonResponse([]),
+  ]);
+  const seenAuth: (string | null)[] = [];
+  const fetchSpy = (async (url: string | URL | Request, init?: RequestInit) => {
+    seenAuth.push(new Headers(init?.headers).get("authorization"));
+    return fetchImpl(url, init);
+  }) as typeof fetch;
+  await retryingFetch("https://api.example.invalid", {
+    fetchImpl: fetchSpy,
+    sleep: async () => {},
+    buildInit: async () => {
+      const token = `tok-${tokens.length}`;
+      tokens.push(token);
+      return {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}` },
+        body: "{}",
+      };
+    },
+    networkError: () => new ConnectorApiError("network"),
+    retryableError: (r) => new ConnectorApiError(`responded ${r.status}`, r.status),
+  });
+  assert.deepEqual(seenAuth, ["Bearer tok-0", "Bearer tok-0"]);
+  assert.equal(tokens.length, 1);
+});
+
+test("buildInit failures run once, propagate unwrapped, and never fetch", async () => {
+  const failure = new ConnectorApiError("grant revoked: re-authorize");
+  let builds = 0;
+  const { fetchImpl, calls } = scriptFetch([]);
+  await assert.rejects(
+    retryingFetch("https://api.example.invalid", {
+      fetchImpl,
+      sleep: async () => {},
+      buildInit: async () => {
+        builds += 1;
+        throw failure;
+      },
+      networkError: (err, attempts) =>
+        new ConnectorApiError(`network after ${attempts}: ${String(err)}`),
+      retryableError: (r) => new ConnectorApiError(`responded ${r.status}`, r.status),
+    }),
+    (err: unknown) => err === failure,
+  );
+  assert.equal(builds, 1);
+  assert.equal(calls(), 0);
+});
+
+test("backoffBaseMs, maxRetries, and maxRetryDelayMs are honored", async () => {
+  const sleeps: number[] = [];
+  const { fetchImpl } = scriptFetch([() => jsonResponse({}, 500)]);
+  await assert.rejects(
+    retryingFetch("https://api.example.invalid", {
+      fetchImpl,
+      sleep: async (ms) => {
+        sleeps.push(ms);
+      },
+      maxRetries: 2,
+      backoffBaseMs: 500,
+      maxRetryDelayMs: 8_000,
+      networkError: () => new ConnectorApiError("network"),
+      retryableError: (r) => new ConnectorApiError(`responded ${r.status}`, r.status),
+    }),
+    ConnectorApiError,
+  );
+  assert.deepEqual(sleeps, [500, 1_000]);
+});
+
+test("retryAfterHeaderMs parses seconds and rejects garbage", () => {
+  assert.equal(retryAfterHeaderMs(jsonResponse({}, 429, { "retry-after": "1.5" }), 30_000), 1_500);
+  assert.equal(retryAfterHeaderMs(jsonResponse({}, 429, { "retry-after": "" }), 30_000), undefined);
+  assert.equal(retryAfterHeaderMs(jsonResponse({}, 429, { "retry-after": "soon" }), 30_000), undefined);
+  assert.equal(retryAfterHeaderMs(jsonResponse({}, 429), 30_000), undefined);
+});
+
+test("stripTrailingSlashes and discardResponseBody behave as documented", async () => {
+  assert.equal(stripTrailingSlashes("https://api.example.invalid///"), "https://api.example.invalid");
+  assert.equal(stripTrailingSlashes("/"), "");
+  const response = jsonResponse({ b: 1 }, 429);
+  discardResponseBody(response);
+  await response.body?.cancel();
+});

package/src/http-retry.ts

@@ -0,0 +1,183 @@
+/**
+ * Shared retrying fetch for connector packages (issue #2792).
+ *
+ * One copy of the retry loop that six connector clients and the X MCP
+ * client duplicated: attempt counting, per-attempt timeout signal,
+ * 429/5xx retry with Retry-After (seconds or HTTP-date) plus capped
+ * exponential backoff, raw rethrow of caller aborts, and socket
+ * release on retryable responses. Vendors keep everything
+ * request-specific: headers/body, the error classes their callers
+ * match on, and what happens to a successful response body.
+ *
+ * Import via the `@remnic/core/http-retry` subpath (same pattern as
+ * `@remnic/core/abort-error`) — the root index stays untouched.
+ */
+
+export interface RetryingFetchOptions {
+  /** Request init for every attempt. Ignored when `buildInit` is set. */
+  init?: RequestInit;
+  /**
+   * Init builder invoked ONCE, before the retry loop. Request
+   * construction (e.g. token acquisition) must stay outside the
+   * transport retry boundary: a deterministic provider failure —
+   * missing grant, revoked grant, unpersistable token file — runs once
+   * and propagates unwrapped, never retried or vendor-wrapped.
+   */
+  buildInit?: () => RequestInit | Promise<RequestInit>;
+  fetchImpl?: typeof fetch;
+  sleep?: (ms: number) => Promise<void>;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  /** Retries after the first attempt. Default 3 (4 attempts total). */
+  maxRetries?: number;
+  maxRetryDelayMs?: number;
+  /** First backoff step; doubles per attempt. Default 1_000. */
+  backoffBaseMs?: number;
+  /**
+   * Vendor Retry-After parsing (e.g. a body field). A `null`/`undefined`
+   * result falls back to the shared Retry-After header parse, then to
+   * exponential backoff. A number (including 0) is used as-is.
+   */
+  retryAfterMs?: (response: Response) => number | null | undefined | Promise<number | null | undefined>;
+  /** Wraps an exhausted network/timeout failure into the vendor error. */
+  networkError: (err: unknown, attempts: number, context: NetworkErrorContext) => Error;
+  /** Wraps a retryable (429/5xx) response; thrown when retries are exhausted. */
+  retryableError: (response: Response) => Error | Promise<Error>;
+}
+
+export interface NetworkErrorContext {
+  /** True when the helper's own timeout signal fired (not a caller abort). */
+  timedOut: boolean;
+}
+
+/**
+ * Base class for connector API errors: a message plus optional HTTP
+ * status and vendor detail. Vendor subclasses set their own `name`.
+ */
+export class ConnectorApiError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+    readonly detail?: string,
+  ) {
+    super(message);
+    this.name = "ConnectorApiError";
+  }
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_MAX_RETRY_DELAY_MS = 30_000;
+const DEFAULT_BACKOFF_BASE_MS = 1_000;
+
+function defaultSleep(ms: number): Promise<void> {
+  const { promise, resolve } = Promise.withResolvers<void>();
+  setTimeout(resolve, ms);
+  return promise;
+}
+
+/**
+ * Network/timeout failures wrap Node error text that can carry loader
+ * paths or stack fragments; sync errors reach MCP clients verbatim, so
+ * only the error name + code survive.
+ */
+export function describeNetworkError(err: unknown): string {
+  if (!(err instanceof Error)) return "unexpected non-Error failure";
+  const code = (err as NodeJS.ErrnoException).code;
+  return typeof code === "string" && code.length > 0 ? `${err.name} (${code})` : err.name;
+}
+
+/** Loop instead of `/\/+$/` — CodeQL js/polynomial-redos on user-set URLs. */
+export function stripTrailingSlashes(value: string): string {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 0x2f) end--;
+  return value.slice(0, end);
+}
+
+/** Release the socket back to the pool: an unconsumed response body pins the undici connection. */
+export function discardResponseBody(response: Response): void {
+  void response.body?.cancel().catch(() => {});
+}
+
+/**
+ * Parse a `Retry-After` header as delay in ms, capped at `capMs`:
+ * delay-seconds first, then HTTP-date. `undefined` when absent or
+ * unparseable.
+ */
+export function retryAfterHeaderMs(response: Response, capMs: number): number | undefined {
+  const header = response.headers.get("retry-after");
+  if (header === null || header.length === 0) return undefined;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.min(capMs, Math.ceil(seconds * 1_000));
+  }
+  const when = Date.parse(header);
+  if (Number.isFinite(when)) {
+    return Math.min(capMs, Math.max(0, when - Date.now()));
+  }
+  return undefined;
+}
+
+/**
+ * Fetch with retries on network failures, 429, and 5xx. Returns the
+ * final response (ok or non-retryable status) for the caller to
+ * interpret; throws the vendor-wrapped error when retries are exhausted
+ * or the transport fails.
+ */
+export async function retryingFetch(
+  url: string,
+  options: RetryingFetchOptions,
+): Promise<Response> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const sleep = options.sleep ?? defaultSleep;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const maxRetryDelayMs = options.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_DELAY_MS;
+  const backoffBaseMs = options.backoffBaseMs ?? DEFAULT_BACKOFF_BASE_MS;
+  const backoffMs = (attempt: number): number =>
+    Math.min(maxRetryDelayMs, backoffBaseMs * 2 ** attempt);
+  const attempts = maxRetries + 1;
+
+  // Request construction runs once, outside the retry boundary: only
+  // fetch/network/HTTP-retryable failures retry, so initializer/token
+  // provider errors execute once and propagate unchanged (issue #2792).
+  options.signal?.throwIfAborted();
+  const init = options.buildInit ? await options.buildInit() : options.init;
+
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    options.signal?.throwIfAborted();
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    const combined = options.signal
+      ? AbortSignal.any([options.signal, timeoutSignal])
+      : timeoutSignal;
+    let response: Response;
+    try {
+      response = await fetchImpl(url, { ...init, signal: combined });
+    } catch (err) {
+      // The caller's abort always propagates unwrapped and unretried.
+      if (options.signal?.aborted) throw err;
+      if (attempt < maxRetries) {
+        await sleep(backoffMs(attempt));
+        continue;
+      }
+      throw options.networkError(err, attempts, { timedOut: timeoutSignal.aborted });
+    }
+
+    if (response.status === 429 || response.status >= 500) {
+      lastError = await options.retryableError(response);
+      if (attempt < maxRetries) {
+        const override = options.retryAfterMs ? await options.retryAfterMs(response) : undefined;
+        const delay = override ?? retryAfterHeaderMs(response, maxRetryDelayMs) ?? backoffMs(attempt);
+        discardResponseBody(response);
+        await sleep(delay);
+        continue;
+      }
+      discardResponseBody(response);
+      throw lastError;
+    }
+    return response;
+  }
+  // Unreachable: every terminal loop path throws. Kept for exhaustiveness.
+  throw lastError instanceof Error ? lastError : new ConnectorApiError("request failed");
+}

package/src/importers/base.ts

@@ -483,3 +483,48 @@ export async function defaultWriteMemoriesToOrchestrator(
   await target.ingestBulkImportBatch(turns);
   return { memoriesIngested: memories.length };
 }
+
+// ---------------------------------------------------------------------------
+// File-importer factory (issue #2794)
+// ---------------------------------------------------------------------------
+
+/** Parse args `defineFileImporterAdapter` forwards — the keys file adapters use. */
+export interface FileImporterParseArgs {
+  strict?: boolean;
+  filePath?: string;
+}
+
+/** Per-package config consumed by `defineFileImporterAdapter`. */
+export interface FileImporterDefinition<Parsed> {
+  name: string;
+  sourceLabel: string;
+  /** Decode the raw export file. Receives only `strict` / `filePath`. */
+  parse(input: unknown, options: FileImporterParseArgs): Parsed | Promise<Parsed>;
+  /** Flatten the parsed export into `ImportedMemory[]` with provenance. */
+  transform(
+    parsed: Parsed,
+    options: ImporterTransformOptions | undefined,
+  ): ImportedMemory[] | Promise<ImportedMemory[]>;
+}
+
+/**
+ * Build the standard file-importer `ImporterAdapter`: parse with the
+ * `strict`/`filePath` spread, a package-specific `transform`, and `writeTo`
+ * delegating to `defaultWriteMemoriesToOrchestrator` (issue #2794).
+ */
+export function defineFileImporterAdapter<Parsed>(
+  definition: FileImporterDefinition<Parsed>,
+): ImporterAdapter<Parsed> {
+  return {
+    name: definition.name,
+    sourceLabel: definition.sourceLabel,
+    parse(input, options) {
+      return definition.parse(input, {
+        ...(options?.strict !== undefined ? { strict: options.strict } : {}),
+        ...(options?.filePath !== undefined ? { filePath: options.filePath } : {}),
+      });
+    },
+    transform: (parsed, options) => definition.transform(parsed, options),
+    writeTo: defaultWriteMemoriesToOrchestrator,
+  };
+}

package/src/importers/index.test.ts

@@ -0,0 +1,42 @@
+// ---------------------------------------------------------------------------
+// Runtime barrel purity (issue #2794, fix round)
+// ---------------------------------------------------------------------------
+// `makeImporterTestTarget` / `loadImporterFixture` live behind the
+// `@remnic/core/importers/test-utils` subpath ONLY. A static re-export from
+// this barrel would link test-utils.js — and its node:fs/node:path/node:url
+// imports — into every production consumer of `@remnic/core/importers`.
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+
+import * as barrel from "./index.js";
+
+// Namespace record read is deliberate: the harness names must be ABSENT, so
+// they cannot appear on the typed surface of the barrel.
+const surface = barrel as Record<string, unknown>;
+
+const barrelSource = readFileSync(
+  new URL("./index.ts", import.meta.url),
+  "utf-8",
+);
+
+test("runtime barrel does not export the test harness (#2794)", () => {
+  assert.equal(
+    surface.makeImporterTestTarget,
+    undefined,
+    "test harness must stay behind @remnic/core/importers/test-utils",
+  );
+  assert.equal(
+    surface.loadImporterFixture,
+    undefined,
+    "test harness must stay behind @remnic/core/importers/test-utils",
+  );
+});
+
+test("runtime barrel statically links no test-utils module (#2794)", () => {
+  assert.ok(
+    !barrelSource.includes("test-utils"),
+    "src/importers/index.ts must not reference ./test-utils.js — import @remnic/core/importers/test-utils instead",
+  );
+});

package/src/importers/index.ts

@@ -19,3 +19,8 @@ export {
   type RunImporterResult,
   type RunImportOptions,
 } from "./base.js";
+export {
+  defineFileImporterAdapter,
+  type FileImporterDefinition,
+  type FileImporterParseArgs,
+} from "./base.js";