@remnic/core 9.69.27 → 9.69.29

package/dist/who-knows-cli.js

@@ -4,26 +4,26 @@ import {
   renderWhoKnows,
   renderWhoKnowsJson,
   renderWhoKnowsText
-} from "./chunk-U6N5IBVY.js";
-import "./chunk-2EKJDQZB.js";
-import "./chunk-XSGUMQQQ.js";
+} from "./chunk-NWWXSJX5.js";
+import "./chunk-EZZV7OQL.js";
+import "./chunk-GVG3JYBI.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-46WM6JX2.js";
 import "./chunk-D5F7TKMH.js";
-import "./chunk-2Z4GS5E6.js";
-import "./chunk-6CVNSDCZ.js";
-import "./chunk-BD7JTBYP.js";
-import "./chunk-OB3XMWX5.js";
-import "./chunk-CYEPCZN5.js";
-import "./chunk-TNSCIPBQ.js";
+import "./chunk-FHQSPTPZ.js";
+import "./chunk-7VJXIDOC.js";
 import "./chunk-YQNNHLCG.js";
-import "./chunk-4O6WRBGE.js";
 import "./chunk-6KTXE6A3.js";
+import "./chunk-PSPABFN2.js";
+import "./chunk-MKWKYHXJ.js";
+import "./chunk-CYEPCZN5.js";
+import "./chunk-ZNJSBIP4.js";
 import "./chunk-GUMZC2BO.js";
-import "./chunk-227UFSEQ.js";
-import "./chunk-ET356KSB.js";
+import "./chunk-4O6WRBGE.js";
+import "./chunk-LEPOP46W.js";
 import "./chunk-72A4L5JJ.js";
 import "./chunk-A7Q43EUZ.js";
+import "./chunk-ET356KSB.js";
 import "./chunk-S2V7RUCL.js";
 import "./chunk-SO7SV523.js";
 import "./chunk-SCU65EZI.js";
@@ -31,11 +31,11 @@ import "./chunk-MRPOZBJC.js";
 import "./chunk-S2HLHAZ4.js";
 import "./chunk-DM2T26WE.js";
 import "./chunk-LDXUBPMO.js";
-import "./chunk-XSTNGNJP.js";
+import "./chunk-DCJ3YFIC.js";
 import "./chunk-AAD2ZS6P.js";
 import "./chunk-H272ZPQ3.js";
-import "./chunk-YXZG5TVN.js";
 import "./chunk-3ONXXHQO.js";
+import "./chunk-YXZG5TVN.js";
 import "./chunk-5GINB5LC.js";
 import "./chunk-3WU7XOFN.js";
 import "./chunk-G7D6GZ5J.js";
@@ -45,21 +45,21 @@ import "./chunk-RBOJCG4T.js";
 import "./chunk-R7QY5ZVB.js";
 import "./chunk-5WITETWU.js";
 import "./chunk-6CIAGZ6X.js";
-import "./chunk-CEH2AFXG.js";
+import "./chunk-DBQWVT2H.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";
 import "./chunk-42JKGUFJ.js";
-import "./chunk-JALOAKSZ.js";
-import "./chunk-QIEUU4UK.js";
+import "./chunk-TLPZ6MKZ.js";
+import "./chunk-I55KAVET.js";
 import "./chunk-L2EXJQJP.js";
 import "./chunk-45GF7Y3V.js";
 import "./chunk-RGMVMVMF.js";
 import "./chunk-N7RWREIQ.js";
-import "./chunk-NXH34IPL.js";
+import "./chunk-353KGBKY.js";
 import "./chunk-ZIKENA2C.js";
 import "./chunk-VYCOJKSX.js";
 import "./chunk-6Q3ZTEF6.js";
@@ -90,8 +90,8 @@ import "./chunk-P7FMDTKL.js";
 import "./chunk-VUFL7X3H.js";
 import "./chunk-JUOZ62Y7.js";
 import "./chunk-O75CRYGF.js";
-import "./chunk-EYIEWJNI.js";
-import "./chunk-JUC24CTX.js";
+import "./chunk-6KH5NLQS.js";
+import "./chunk-P2QRMMVQ.js";
 import "./chunk-2Z24E5W2.js";
 import "./chunk-BTTPKDIL.js";
 import "./chunk-FF4KLI5W.js";

package/dist/who-knows.d.ts

@@ -1,4 +1,4 @@
-export { bA as WHO_KNOWS_AUTHORSHIP_BONUS, bB as WHO_KNOWS_DEFAULT_LIMIT, bC as WHO_KNOWS_MAX_EVIDENCE, bD as WHO_KNOWS_MAX_LIMIT, bE as WHO_KNOWS_MCP_TOOLS, bF as WhoKnowsEntity, bG as WhoKnowsEvidence, bH as WhoKnowsHit, bI as WhoKnowsHttpOutcome, W as WhoKnowsResult, bJ as WhoKnowsStorage, bT as computeWhoKnows, bZ as handleWhoKnowsHttpQuery, c2 as loadWhoKnowsEntities, c9 as tokenizeTopic, ca as validateWhoKnowsInput } from './access-service-DWdY9Mlk.js';
+export { bA as WHO_KNOWS_AUTHORSHIP_BONUS, bB as WHO_KNOWS_DEFAULT_LIMIT, bC as WHO_KNOWS_MAX_EVIDENCE, bD as WHO_KNOWS_MAX_LIMIT, bE as WHO_KNOWS_MCP_TOOLS, bF as WhoKnowsEntity, bG as WhoKnowsEvidence, bH as WhoKnowsHit, bI as WhoKnowsHttpOutcome, W as WhoKnowsResult, bJ as WhoKnowsStorage, bT as computeWhoKnows, bZ as handleWhoKnowsHttpQuery, c2 as loadWhoKnowsEntities, c9 as tokenizeTopic, ca as validateWhoKnowsInput } from './access-service-Cv8Rizo0.js';
 import './types-YY-eKKU7.js';
 import './orchestrator-DgyvFfPR.js';
 import './recall-state.js';

package/dist/who-knows.js

@@ -9,25 +9,25 @@ import {
   loadWhoKnowsEntities,
   tokenizeTopic,
   validateWhoKnowsInput
-} from "./chunk-2EKJDQZB.js";
-import "./chunk-XSGUMQQQ.js";
+} from "./chunk-EZZV7OQL.js";
+import "./chunk-GVG3JYBI.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-46WM6JX2.js";
 import "./chunk-D5F7TKMH.js";
-import "./chunk-2Z4GS5E6.js";
-import "./chunk-6CVNSDCZ.js";
-import "./chunk-BD7JTBYP.js";
-import "./chunk-OB3XMWX5.js";
-import "./chunk-CYEPCZN5.js";
-import "./chunk-TNSCIPBQ.js";
+import "./chunk-FHQSPTPZ.js";
+import "./chunk-7VJXIDOC.js";
 import "./chunk-YQNNHLCG.js";
-import "./chunk-4O6WRBGE.js";
 import "./chunk-6KTXE6A3.js";
+import "./chunk-PSPABFN2.js";
+import "./chunk-MKWKYHXJ.js";
+import "./chunk-CYEPCZN5.js";
+import "./chunk-ZNJSBIP4.js";
 import "./chunk-GUMZC2BO.js";
-import "./chunk-227UFSEQ.js";
-import "./chunk-ET356KSB.js";
+import "./chunk-4O6WRBGE.js";
+import "./chunk-LEPOP46W.js";
 import "./chunk-72A4L5JJ.js";
 import "./chunk-A7Q43EUZ.js";
+import "./chunk-ET356KSB.js";
 import "./chunk-S2V7RUCL.js";
 import "./chunk-SO7SV523.js";
 import "./chunk-SCU65EZI.js";
@@ -35,11 +35,11 @@ import "./chunk-MRPOZBJC.js";
 import "./chunk-S2HLHAZ4.js";
 import "./chunk-DM2T26WE.js";
 import "./chunk-LDXUBPMO.js";
-import "./chunk-XSTNGNJP.js";
+import "./chunk-DCJ3YFIC.js";
 import "./chunk-AAD2ZS6P.js";
 import "./chunk-H272ZPQ3.js";
-import "./chunk-YXZG5TVN.js";
 import "./chunk-3ONXXHQO.js";
+import "./chunk-YXZG5TVN.js";
 import "./chunk-5GINB5LC.js";
 import "./chunk-3WU7XOFN.js";
 import "./chunk-G7D6GZ5J.js";
@@ -49,21 +49,21 @@ import "./chunk-RBOJCG4T.js";
 import "./chunk-R7QY5ZVB.js";
 import "./chunk-5WITETWU.js";
 import "./chunk-6CIAGZ6X.js";
-import "./chunk-CEH2AFXG.js";
+import "./chunk-DBQWVT2H.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";
 import "./chunk-42JKGUFJ.js";
-import "./chunk-JALOAKSZ.js";
-import "./chunk-QIEUU4UK.js";
+import "./chunk-TLPZ6MKZ.js";
+import "./chunk-I55KAVET.js";
 import "./chunk-L2EXJQJP.js";
 import "./chunk-45GF7Y3V.js";
 import "./chunk-RGMVMVMF.js";
 import "./chunk-N7RWREIQ.js";
-import "./chunk-NXH34IPL.js";
+import "./chunk-353KGBKY.js";
 import "./chunk-ZIKENA2C.js";
 import "./chunk-VYCOJKSX.js";
 import "./chunk-6Q3ZTEF6.js";
@@ -94,8 +94,8 @@ import "./chunk-P7FMDTKL.js";
 import "./chunk-VUFL7X3H.js";
 import "./chunk-JUOZ62Y7.js";
 import "./chunk-O75CRYGF.js";
-import "./chunk-EYIEWJNI.js";
-import "./chunk-JUC24CTX.js";
+import "./chunk-6KH5NLQS.js";
+import "./chunk-P2QRMMVQ.js";
 import "./chunk-2Z24E5W2.js";
 import "./chunk-BTTPKDIL.js";
 import "./chunk-FF4KLI5W.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.69.27",
+  "version": "9.69.29",
   "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.27"
+    "@remnic/coding-graph": "^9.69.29"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/config-discovery.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared config discovery (issue #2796).
+ *
+ * The server and CLI resolve their config through `discoverConfigPath`; the
+ * OpenClaw bridge probes `configPathCandidates` directly. These tests pin the
+ * identity the P1 fix restored: for every home-reference form, both surfaces
+ * must land on the same file.
+ */
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { configPathCandidates, discoverConfigPath } from "./config-discovery.js";
+
+const ORIGINAL_ENV = {
+  HOME: process.env.HOME,
+  REMNIC_CONFIG_PATH: process.env.REMNIC_CONFIG_PATH,
+  ENGRAM_CONFIG_PATH: process.env.ENGRAM_CONFIG_PATH,
+};
+
+function restoreEnv(): void {
+  for (const [key, value] of Object.entries(ORIGINAL_ENV)) {
+    if (value === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+}
+
+test("env config paths expand every home-reference form on both surfaces", async () => {
+  const home = await mkdtemp(path.join(os.tmpdir(), "remnic-discovery-home-"));
+  try {
+    process.env.HOME = home;
+    delete process.env.ENGRAM_CONFIG_PATH;
+    const expected = path.join(home, "opt", "remnic.json");
+    for (const form of ["$HOME/opt/remnic.json", "${HOME}/opt/remnic.json", "~/opt/remnic.json"]) {
+      process.env.REMNIC_CONFIG_PATH = form;
+      // The bridge probes candidates[0]; the server/CLI resolver returns the
+      // explicit path. Same form in, same file out — a daemon the server can
+      // discover is never invisible to the bridge.
+      assert.equal(configPathCandidates()[0], expected, `configPathCandidates: ${form}`);
+      assert.equal(discoverConfigPath().path, expected, `discoverConfigPath: ${form}`);
+      assert.equal(discoverConfigPath().explicit, true, `explicit: ${form}`);
+    }
+  } finally {
+    restoreEnv();
+    await rm(home, { recursive: true, force: true });
+  }
+});
+test("no env override leaves auto-discovery candidates only", () => {
+  try {
+    delete process.env.REMNIC_CONFIG_PATH;
+    delete process.env.ENGRAM_CONFIG_PATH;
+    const candidates = configPathCandidates();
+    assert.equal(candidates[0], path.join(process.cwd(), "remnic.config.json"));
+    assert.ok(!candidates[0].includes("$HOME"));
+  } finally {
+    restoreEnv();
+  }
+});

package/src/config-discovery.ts

@@ -0,0 +1,90 @@
+/**
+ * Shared Remnic config-file discovery (issue #2796).
+ *
+ * One implementation of the candidate order every surface uses: explicit
+ * `--config` path, then `REMNIC_CONFIG_PATH`/`ENGRAM_CONFIG_PATH`, then the
+ * first existing candidate under cwd, then the home default. The standalone
+ * server boots from this order and the CLI resolves `--config`-less commands
+ * through it, so the two can never drift onto different files.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { readCompatEnv, resolveHomeDir } from "./runtime/env.js";
+
+export interface DiscoveredConfigPath {
+  path: string;
+  explicit: boolean;
+  source: string;
+}
+
+/**
+ * Expand a leading home reference — `~`, `~\`, `$HOME`, or `${HOME}` — to the
+ * resolved home directory. Union of the historical server (tilde only) and
+ * CLI (tilde plus `$HOME` forms) behaviors; every other path passes through
+ * unchanged.
+ */
+function expandHomeReference(p: string): string {
+  if (p === "~" || p.startsWith("~/") || p.startsWith("~\\")) {
+    return resolveHomeDir() + p.slice(1);
+  }
+  const home = resolveHomeDir();
+  if (p === "$HOME" || p.startsWith("$HOME/") || p.startsWith("$HOME\\")) {
+    return home + p.slice(5);
+  }
+  if (p === "${HOME}" || p.startsWith("${HOME}/") || p.startsWith("${HOME}\\")) {
+    return home + p.slice(7);
+  }
+  return p;
+}
+
+/**
+ * The ordered candidates every probing surface walks: the expanded
+ * `REMNIC_CONFIG_PATH`/`ENGRAM_CONFIG_PATH` value (if set), then the cwd
+ * files, then the home defaults. The standalone server and the CLI resolve to
+ * the single file `discoverConfigPath` picks; the OpenClaw bridge probes each
+ * candidate's endpoint. One list, so a daemon the server can discover is never
+ * invisible to the bridge.
+ */
+export function configPathCandidates(): string[] {
+  const envPath = readCompatEnv("REMNIC_CONFIG_PATH", "ENGRAM_CONFIG_PATH");
+  return [
+    ...(envPath ? [path.resolve(expandHomeReference(envPath))] : []),
+    ...autoDiscoveryCandidates(),
+  ];
+}
+
+function autoDiscoveryCandidates(): string[] {
+  const homeDir = resolveHomeDir();
+  return [
+    path.join(process.cwd(), "remnic.config.json"),
+    path.join(process.cwd(), "engram.config.json"),
+    path.join(homeDir, ".config", "remnic", "config.json"),
+    path.join(homeDir, ".config", "engram", "config.json"),
+  ];
+}
+
+export function discoverConfigPath(cliPath?: string): DiscoveredConfigPath {
+  if (cliPath) {
+    return { path: path.resolve(expandHomeReference(cliPath)), explicit: true, source: "--config" };
+  }
+
+  const envPath = readCompatEnv("REMNIC_CONFIG_PATH", "ENGRAM_CONFIG_PATH");
+  if (envPath) {
+    return {
+      path: path.resolve(expandHomeReference(envPath)),
+      explicit: true,
+      source: "REMNIC_CONFIG_PATH/ENGRAM_CONFIG_PATH",
+    };
+  }
+
+  const candidates = autoDiscoveryCandidates();
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      return { path: candidate, explicit: false, source: "auto-discovery" };
+    }
+  }
+
+  return { path: candidates[2], explicit: false, source: "auto-discovery" };
+}

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();
+});