@remnic/core 1.1.12 → 1.1.13

package/src/connectors/live/registry.ts

@@ -0,0 +1,103 @@
+/**
+ * @remnic/core — Live Connectors Registry (issue #683 PR 1/N)
+ *
+ * Pure in-memory registry. No I/O. Concrete connectors register themselves at
+ * orchestrator boot (later PRs); the maintenance scheduler asks the registry
+ * for the active set when running due syncs.
+ */
+
+import { isValidConnectorId, type LiveConnector } from "./framework.js";
+
+/**
+ * Thrown when registering a duplicate id or an id that fails validation.
+ *
+ * Distinct error class so callers can distinguish framework-level mistakes
+ * (which are programmer errors) from connector-runtime failures.
+ */
+export class LiveConnectorRegistryError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "LiveConnectorRegistryError";
+  }
+}
+
+/**
+ * In-memory registry of live connectors. One instance per orchestrator. Not
+ * safe for cross-process sharing — wire each process to its own registry.
+ */
+export class LiveConnectorRegistry {
+  private readonly connectors = new Map<string, LiveConnector>();
+
+  /**
+   * Register a connector. Throws `LiveConnectorRegistryError` if the id is
+   * malformed or already registered.
+   *
+   * Re-registration is rejected (rather than silently overwriting) because
+   * silent overwrites mask plugin loading bugs in development and could let
+   * a malicious extension shadow a built-in connector.
+   */
+  register(connector: LiveConnector): void {
+    if (!connector || typeof connector !== "object") {
+      throw new LiveConnectorRegistryError(
+        "register(): connector must be a non-null object",
+      );
+    }
+    if (!isValidConnectorId(connector.id)) {
+      throw new LiveConnectorRegistryError(
+        `register(): invalid connector id ${JSON.stringify(connector.id)} — must match /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/`,
+      );
+    }
+    if (this.connectors.has(connector.id)) {
+      throw new LiveConnectorRegistryError(
+        `register(): connector id ${JSON.stringify(connector.id)} is already registered`,
+      );
+    }
+    if (typeof connector.displayName !== "string" || connector.displayName.length === 0) {
+      throw new LiveConnectorRegistryError(
+        `register(): connector ${connector.id} missing displayName`,
+      );
+    }
+    if (typeof connector.validateConfig !== "function") {
+      throw new LiveConnectorRegistryError(
+        `register(): connector ${connector.id} missing validateConfig()`,
+      );
+    }
+    if (typeof connector.syncIncremental !== "function") {
+      throw new LiveConnectorRegistryError(
+        `register(): connector ${connector.id} missing syncIncremental()`,
+      );
+    }
+    this.connectors.set(connector.id, connector);
+  }
+
+  /**
+   * Look up a connector by id. Returns `undefined` if not registered.
+   */
+  get(id: string): LiveConnector | undefined {
+    return this.connectors.get(id);
+  }
+
+  /**
+   * Return all registered connectors, sorted by id for stable enumeration.
+   */
+  list(): LiveConnector[] {
+    return Array.from(this.connectors.values()).sort((a, b) => a.id.localeCompare(b.id));
+  }
+
+  /**
+   * Remove a connector. Returns `true` if a connector was removed, `false`
+   * otherwise. The cursor / state file on disk is **not** touched — callers
+   * who want to fully decommission a connector must also delete its state
+   * file via the `state-store` module.
+   */
+  unregister(id: string): boolean {
+    return this.connectors.delete(id);
+  }
+
+  /**
+   * Number of registered connectors. Cheap; safe to call frequently.
+   */
+  size(): number {
+    return this.connectors.size;
+  }
+}

package/src/connectors/live/state-store.ts

@@ -0,0 +1,399 @@
+/**
+ * @remnic/core — Live Connectors State Store (issue #683 PR 1/N)
+ *
+ * Persists per-connector cursor + sync metadata to
+ *   `<memoryDir>/state/connectors/<id>.json`
+ *
+ * Reasons this lives next to memory data, not in user config:
+ *   - cursors are *operational* state that should travel with the memory
+ *     directory when a user moves it across machines;
+ *   - it keeps memory + ingest provenance co-located so tooling that backs up
+ *     the memory directory captures cursor state too.
+ *
+ * Atomic-write contract (CLAUDE.md gotcha #54):
+ *   - We NEVER `rmSync(target)` before `renameSync(tmp, target)`.
+ *   - Writes go to a sibling tmp file and `rename()` swaps it in.
+ *   - On error, the tmp file is best-effort cleaned up; the previous good
+ *     state file is left untouched.
+ *
+ * Privacy: cursors are opaque connector-defined strings. We do not log them
+ * and do not surface them through user-visible APIs. Document content NEVER
+ * touches this module.
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+import { expandTildePath } from "../../utils/path.js";
+
+import {
+  isValidConnectorId,
+  type ConnectorCursor,
+} from "./framework.js";
+
+/**
+ * Status of the most recent sync attempt for a connector.
+ *
+ * `"never"` is distinct from `"success"` so callers can detect
+ * "registered but never run" without inspecting timestamps. Per CLAUDE.md
+ * gotcha #34, we deliberately distinguish empty/unknown from failure states.
+ */
+export type ConnectorSyncStatus = "success" | "error" | "never";
+
+/**
+ * Persisted per-connector state.
+ *
+ * Stored as pretty-printed JSON for human inspection — the file is small
+ * (one record per connector) and operators may need to debug stuck cursors
+ * by hand.
+ */
+export interface ConnectorState {
+  /** Connector id. Matches the filename stem. */
+  readonly id: string;
+  /** Last persisted cursor, or `null` if the connector has never synced. */
+  readonly cursor: ConnectorCursor | null;
+  /** ISO 8601 timestamp of the last completed sync attempt, or `null`. */
+  readonly lastSyncAt: string | null;
+  /** Status of the last completed sync attempt. */
+  readonly lastSyncStatus: ConnectorSyncStatus;
+  /** Optional error message from the last failed sync. Truncated to 1 KB. */
+  readonly lastSyncError?: string;
+  /** Cumulative count of documents successfully imported across all syncs. */
+  readonly totalDocsImported: number;
+  /** ISO 8601 timestamp of when this state record was last written. */
+  readonly updatedAt: string;
+}
+
+const STATE_DIR_NAME = "state";
+const CONNECTORS_DIR_NAME = "connectors";
+const MAX_ERROR_LENGTH = 1024;
+const VALID_SYNC_STATUSES: ReadonlySet<ConnectorSyncStatus> = new Set([
+  "success",
+  "error",
+  "never",
+]);
+
+/**
+ * Internal error thrown when a state file's JSON is unparseable or its shape
+ * doesn't match `ConnectorState`. Used by `listConnectorStates` to distinguish
+ * "skip this corrupt file" cases from genuine I/O failures (`EACCES`, `EIO`)
+ * that the caller must see.
+ */
+class ConnectorStateCorruptionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ConnectorStateCorruptionError";
+  }
+}
+
+/**
+ * Resolve `<memoryDir>/state/connectors/`, expanding `~` per CLAUDE.md #17.
+ */
+function resolveConnectorsDir(memoryDir: string): string {
+  if (typeof memoryDir !== "string" || memoryDir.length === 0) {
+    throw new TypeError("memoryDir must be a non-empty string");
+  }
+  return path.join(expandTildePath(memoryDir), STATE_DIR_NAME, CONNECTORS_DIR_NAME);
+}
+
+/**
+ * Resolve the state file path for a single connector. Throws on invalid id
+ * to prevent path traversal via crafted ids.
+ */
+function resolveConnectorStatePath(memoryDir: string, id: string): string {
+  if (!isValidConnectorId(id)) {
+    throw new TypeError(
+      `invalid connector id ${JSON.stringify(id)} — must match /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/`,
+    );
+  }
+  return path.join(resolveConnectorsDir(memoryDir), `${id}.json`);
+}
+
+/**
+ * Type guard for parsed state records. Validates the on-disk shape so a
+ * corrupted/edited file produces a clear error rather than crashing later.
+ *
+ * Per CLAUDE.md gotcha #18, JSON.parse('null') yields `null` which would
+ * pass a naive truthy check. We explicitly require an object.
+ */
+function isConnectorStateShape(value: unknown): value is ConnectorState {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  if (typeof v.id !== "string") return false;
+  if (typeof v.lastSyncStatus !== "string") return false;
+  if (!["success", "error", "never"].includes(v.lastSyncStatus)) return false;
+  // totalDocsImported is a cumulative count — fractional values would corrupt
+  // metrics on later increments. Mirror the boundary check in writeConnectorState.
+  if (typeof v.totalDocsImported !== "number" || !Number.isInteger(v.totalDocsImported)) return false;
+  if (v.totalDocsImported < 0) return false;
+  if (typeof v.updatedAt !== "string") return false;
+  if (v.lastSyncAt !== null && typeof v.lastSyncAt !== "string") return false;
+  if (v.cursor !== null) {
+    if (typeof v.cursor !== "object" || v.cursor === null) return false;
+    const c = v.cursor as Record<string, unknown>;
+    if (typeof c.kind !== "string" || typeof c.value !== "string" || typeof c.updatedAt !== "string") {
+      return false;
+    }
+  }
+  if (v.lastSyncError !== undefined && typeof v.lastSyncError !== "string") return false;
+  return true;
+}
+
+/**
+ * Reject any path component along `<memoryDir>/state/connectors/<id>.json`
+ * that is a symlink. Without this guard, a symlink in any of those
+ * components would let `fs.readFile` escape the memory root and consume an
+ * arbitrary outside file as cursor state — silently poisoning sync state and
+ * violating the project-wide rule against symlink traversal.
+ *
+ * `lstat` is used (not `stat`) so we observe the link itself rather than its
+ * target. Missing components are tolerated — the caller's `readFile` /
+ * `mkdir` will surface ENOENT in its normal way.
+ *
+ * (PR #724 review.)
+ */
+async function assertNoSymlinkOnPath(memoryDir: string, filePath: string): Promise<void> {
+  const expandedRoot = expandTildePath(memoryDir);
+  // Normalize so `..` segments can't bypass the prefix check below.
+  const root = path.resolve(expandedRoot);
+  const target = path.resolve(filePath);
+  const rel = path.relative(root, target);
+  // path.relative() yields a "../..." prefix when target escapes root.
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new Error(
+      `connector state path ${target} escapes memory root ${root}`,
+    );
+  }
+  // Walk every component from root to target (inclusive) and lstat each.
+  const segments = rel.length === 0 ? [] : rel.split(path.sep);
+  let current = root;
+  const componentsToCheck = [current];
+  for (const seg of segments) {
+    current = path.join(current, seg);
+    componentsToCheck.push(current);
+  }
+  for (const component of componentsToCheck) {
+    let stat: import("node:fs").Stats;
+    try {
+      stat = await fs.lstat(component);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        // Not yet created — that's fine; caller's readFile/mkdir handles it.
+        continue;
+      }
+      throw err;
+    }
+    if (stat.isSymbolicLink()) {
+      throw new Error(
+        `connector state path component ${component} is a symlink; refusing to follow`,
+      );
+    }
+  }
+}
+
+/**
+ * Read the persisted state for a single connector.
+ *
+ * Returns `null` if the file does not exist (ENOENT). Throws on any other
+ * I/O error or on shape mismatch — operators should see corruption loudly.
+ *
+ * Rejects symlinks anywhere on the path so a planted symlink can't redirect
+ * reads outside the memory root. (PR #724 review.)
+ */
+export async function readConnectorState(
+  memoryDir: string,
+  id: string,
+): Promise<ConnectorState | null> {
+  const filePath = resolveConnectorStatePath(memoryDir, id);
+  await assertNoSymlinkOnPath(memoryDir, filePath);
+  let raw: string;
+  try {
+    raw = await fs.readFile(filePath, "utf-8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new ConnectorStateCorruptionError(
+      `connector state at ${filePath} is not valid JSON: ${(err as Error).message}`,
+    );
+  }
+  if (!isConnectorStateShape(parsed)) {
+    throw new ConnectorStateCorruptionError(
+      `connector state at ${filePath} does not match ConnectorState shape`,
+    );
+  }
+  if (parsed.id !== id) {
+    throw new ConnectorStateCorruptionError(
+      `connector state at ${filePath} has mismatched id ${JSON.stringify(parsed.id)}; expected ${JSON.stringify(id)}`,
+    );
+  }
+  return parsed;
+}
+
+/**
+ * Write state atomically: create-tmp + rename. Never destroys the previous
+ * file before the new one is in place — see CLAUDE.md gotcha #54.
+ *
+ * We accept `Omit<ConnectorState, "updatedAt">` and stamp `updatedAt`
+ * ourselves so callers can't accidentally persist a stale timestamp.
+ */
+export async function writeConnectorState(
+  memoryDir: string,
+  id: string,
+  state: Omit<ConnectorState, "updatedAt">,
+): Promise<ConnectorState> {
+  if (!isValidConnectorId(id)) {
+    throw new TypeError(
+      `invalid connector id ${JSON.stringify(id)} — must match /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/`,
+    );
+  }
+  if (state.id !== id) {
+    throw new Error(
+      `writeConnectorState(): state.id ${JSON.stringify(state.id)} does not match id argument ${JSON.stringify(id)}`,
+    );
+  }
+  // Full boundary validation. Persisting an out-of-shape record would brick
+  // the connector's cursor file: subsequent `readConnectorState` calls would
+  // throw `ConnectorStateCorruptionError` until manual repair. JS callers
+  // bypassing TS types must be rejected here, not later. (PR #724 review.)
+  if (!VALID_SYNC_STATUSES.has(state.lastSyncStatus as ConnectorSyncStatus)) {
+    throw new Error(
+      `writeConnectorState(): lastSyncStatus must be one of ${[...VALID_SYNC_STATUSES].join(", ")}, got ${JSON.stringify(state.lastSyncStatus)}`,
+    );
+  }
+  if (state.lastSyncAt !== null && typeof state.lastSyncAt !== "string") {
+    throw new Error(
+      `writeConnectorState(): lastSyncAt must be a string or null, got ${typeof state.lastSyncAt}`,
+    );
+  }
+  if (state.cursor !== null) {
+    if (typeof state.cursor !== "object") {
+      throw new Error(`writeConnectorState(): cursor must be an object or null`);
+    }
+    if (
+      typeof state.cursor.kind !== "string" ||
+      typeof state.cursor.value !== "string" ||
+      typeof state.cursor.updatedAt !== "string"
+    ) {
+      throw new Error(
+        `writeConnectorState(): cursor must have string kind, value, and updatedAt`,
+      );
+    }
+  }
+  if (
+    typeof state.totalDocsImported !== "number" ||
+    !Number.isInteger(state.totalDocsImported) ||
+    state.totalDocsImported < 0
+  ) {
+    throw new Error(
+      `writeConnectorState(): totalDocsImported must be a non-negative integer`,
+    );
+  }
+  if (state.lastSyncError !== undefined && typeof state.lastSyncError !== "string") {
+    throw new Error(`writeConnectorState(): lastSyncError must be a string when provided`);
+  }
+  const truncatedError =
+    state.lastSyncError !== undefined && state.lastSyncError.length > MAX_ERROR_LENGTH
+      ? state.lastSyncError.slice(0, MAX_ERROR_LENGTH)
+      : state.lastSyncError;
+
+  const finalState: ConnectorState = {
+    id: state.id,
+    cursor: state.cursor,
+    lastSyncAt: state.lastSyncAt,
+    lastSyncStatus: state.lastSyncStatus,
+    ...(truncatedError !== undefined ? { lastSyncError: truncatedError } : {}),
+    totalDocsImported: state.totalDocsImported,
+    updatedAt: new Date().toISOString(),
+  };
+
+  const dir = resolveConnectorsDir(memoryDir);
+  const targetPath = path.join(dir, `${id}.json`);
+  // Reject planted symlinks before mkdir/write so a redirected target can't
+  // overwrite an arbitrary file outside the memory root. (PR #724 review.)
+  await assertNoSymlinkOnPath(memoryDir, targetPath);
+  await fs.mkdir(dir, { recursive: true });
+  const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+  const body = `${JSON.stringify(finalState, null, 2)}\n`;
+  try {
+    await fs.writeFile(tmpPath, body, { encoding: "utf-8", mode: 0o600 });
+    await fs.rename(tmpPath, targetPath);
+  } catch (err) {
+    // Best-effort cleanup of the tmp file. Never touch `targetPath` — the
+    // previous good state must remain readable on failure.
+    try {
+      await fs.unlink(tmpPath);
+    } catch {
+      // ignore
+    }
+    throw err;
+  }
+  return finalState;
+}
+
+/**
+ * Enumerate every persisted connector state. Returns an empty array when
+ * the directory does not exist yet (clean install, no syncs ever run).
+ *
+ * Files that do not match the `<id>.json` naming rule are skipped — this
+ * keeps stray editor backups (`.json~`, `.swp`) from breaking enumeration.
+ *
+ * Corruption (unparseable JSON, shape mismatch, id mismatch) is also
+ * skipped so one bad file doesn't take down the listing. Operators
+ * inspecting `state/connectors/` can still see the offending file by hand.
+ *
+ * **Genuine I/O failures (`EACCES`, `EIO`, etc.) are NOT swallowed** —
+ * silently returning an incomplete state set would make active connectors
+ * appear missing and trigger duplicate ingestion on the next scheduler tick.
+ * (PR #724 review.)
+ */
+export async function listConnectorStates(memoryDir: string): Promise<ConnectorState[]> {
+  const dir = resolveConnectorsDir(memoryDir);
+  // Refuse to enumerate through a symlinked state directory — a planted
+  // symlink at <memoryDir>/state or <memoryDir>/state/connectors would
+  // otherwise let reads escape the memory root. (PR #724 review.)
+  await assertNoSymlinkOnPath(memoryDir, dir);
+  let entries: string[];
+  try {
+    entries = await fs.readdir(dir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw err;
+  }
+  const out: ConnectorState[] = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(".json")) continue;
+    const id = entry.slice(0, -".json".length);
+    if (!isValidConnectorId(id)) continue;
+    try {
+      const state = await readConnectorState(memoryDir, id);
+      if (state !== null) out.push(state);
+    } catch (err) {
+      if (err instanceof ConnectorStateCorruptionError) {
+        // Skip corrupt files; preserve availability of the rest.
+        continue;
+      }
+      // Anything else (EACCES, EIO, ENOTDIR, ...) is a real operational
+      // failure. Fail loudly so the scheduler / CLI can surface it.
+      throw err;
+    }
+  }
+  out.sort((a, b) => a.id.localeCompare(b.id));
+  return out;
+}
+
+/**
+ * Test-only helper: resolve where a given connector's state lives. Exported
+ * so tests can assert the on-disk layout without duplicating the path math.
+ * Not part of the stable public API.
+ *
+ * @internal
+ */
+export function _connectorStatePathForTest(memoryDir: string, id: string): string {
+  return resolveConnectorStatePath(memoryDir, id);
+}

package/src/connectors/live/transient-errors.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared transient-error classifier for live connectors.
+ *
+ * All three connectors (Drive, Notion, Gmail) need to distinguish transient
+ * errors (re-throw so the pass stops without advancing the cursor — the next
+ * poll retries the same batch) from terminal errors (skip-and-continue — the
+ * resource is gone, inaccessible, or malformed in a non-recoverable way).
+ *
+ * Having three independent copies of this logic caused divergent edge-case
+ * handling (Cursor thread PRRT_kwDORJXyws59sdH4 / #745). This module is the
+ * single source of truth; all three connectors import from here.
+ *
+ * Transient classes:
+ *   - 429  (rate-limit / quota — retry after backoff)
+ *   - 5xx  (backend error — retry)
+ *   - AbortError / cancelled requests
+ *   - Network errors with no HTTP status (ECONNRESET, ETIMEDOUT, ENOTFOUND, EAI_AGAIN, …)
+ *   - Bare `Error` with no metadata (plain network failures)
+ *
+ * Terminal classes (skip-and-continue):
+ *   - 400  (bad request — won't be fixed by retrying)
+ *   - 403  (permission denied)
+ *   - 404  (resource gone or not shared)
+ *   - 410  (gone)
+ *   - Any other 4xx that isn't 429
+ *
+ * Connector-specific status properties are resolved via the `statusProps`
+ * parameter. Connectors attach their own status property name (e.g.
+ * `gmailStatus`, `notionStatus`) so the classifier can resolve it without
+ * knowing the error shape in detail.
+ */
+
+/**
+ * Duck-typed error shape that all three connector error types share.
+ * Callers pass additional connector-specific status property names via
+ * `statusProps`.
+ */
+interface ErrorLike {
+  name?: unknown;
+  code?: unknown;
+  status?: unknown;
+  response?: { status?: unknown } | null;
+  [key: string]: unknown;
+}
+
+/**
+ * Set of Node.js network-layer error codes we treat as transient.
+ * Explicitly enumerated (not a denylist) so unknown codes don't accidentally
+ * get swallowed.
+ */
+const TRANSIENT_NODE_CODES = new Set([
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ECONNABORTED",
+  "ETIMEDOUT",
+  "ESOCKETTIMEDOUT",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "EPIPE",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ENETDOWN",
+  "ERR_NETWORK",
+  "ERR_NETWORK_CHANGED",
+]);
+
+/**
+ * Resolve a numeric HTTP status from any of the documented locations on an
+ * error-shaped object.
+ *
+ * Resolution order:
+ *   1. `statusProps` — connector-specific status properties (e.g. `gmailStatus`, `notionStatus`)
+ *   2. `response.status` — canonical for fetch-compatible / GaxiosError shapes
+ *   3. `status` — top-level for some HTTP client libraries
+ *   4. `code` — numeric (older GaxiosError) or string-numeric ("429" / "503")
+ */
+function resolveHttpStatus(
+  e: ErrorLike,
+  statusProps: readonly string[],
+): number | undefined {
+  // Connector-specific properties first.
+  for (const prop of statusProps) {
+    const v = e[prop];
+    if (typeof v === "number" && Number.isFinite(v)) return v;
+  }
+
+  // response.status (canonical GaxiosError / fetch-compatible).
+  const responseStatus = e.response?.status;
+  if (typeof responseStatus === "number" && Number.isFinite(responseStatus)) {
+    return responseStatus;
+  }
+
+  // Top-level status.
+  if (typeof e.status === "number" && Number.isFinite(e.status)) return e.status;
+
+  // Numeric code.
+  if (typeof e.code === "number" && Number.isFinite(e.code)) return e.code;
+
+  // String-numeric codes ("429" / "503" — older googleapis / older Node HTTP).
+  if (typeof e.code === "string" && /^\d+$/.test(e.code)) {
+    const n = Number(e.code);
+    if (Number.isFinite(n) && n >= 100 && n <= 599) return n;
+  }
+
+  return undefined;
+}
+
+/**
+ * Generic transient-error classifier.
+ *
+ * Returns `true` when `err` looks transient (caller should re-throw without
+ * advancing the cursor so the next poll retries). Returns `false` for terminal
+ * errors (skip-and-continue is safe).
+ *
+ * @param err      - The caught error value.
+ * @param statusProps - Additional property names the caller attaches an HTTP
+ *                  status to (e.g. `["gmailStatus"]`, `["notionStatus"]`).
+ *                  Pass an empty array when only the generic locations are needed.
+ */
+export function isTransientHttpError(
+  err: unknown,
+  statusProps: readonly string[] = [],
+): boolean {
+  if (err === null || typeof err !== "object") return false;
+  const e = err as ErrorLike;
+
+  // AbortError — always transient.
+  if (typeof e.name === "string" && e.name === "AbortError") return true;
+
+  // Resolve HTTP status.
+  const status = resolveHttpStatus(e, statusProps);
+  if (status !== undefined) {
+    if (status === 429) return true;
+    if (status >= 500 && status <= 599) return true;
+    // Any 4xx that isn't 429 is terminal.
+    return false;
+  }
+
+  // Network-layer codes.
+  if (typeof e.code === "string") {
+    if (TRANSIENT_NODE_CODES.has(e.code)) return true;
+    // Unknown string code with no HTTP status: conservative terminal to avoid
+    // looping on a permanent error. Callers can override if needed.
+    return false;
+  }
+
+  // No status, no code — likely a plain `Error` from a fetch-layer network
+  // failure. Treat as transient.
+  return true;
+}