@totalreclaw/totalreclaw 3.3.1-rc.9 → 3.3.1

package/config.ts

@@ -9,8 +9,15 @@
  *
  * v1 env var cleanup — see `docs/guides/env-vars-reference.md`.
  * Removed user-facing vars: TOTALRECLAW_CHAIN_ID, TOTALRECLAW_EMBEDDING_MODEL,
- * TOTALRECLAW_STORE_DEDUP, TOTALRECLAW_LLM_MODEL, TOTALRECLAW_SESSION_ID,
- * TOTALRECLAW_TAXONOMY_VERSION.
+ * TOTALRECLAW_STORE_DEDUP, TOTALRECLAW_LLM_MODEL, TOTALRECLAW_TAXONOMY_VERSION.
+ *
+ * NOTE: ``TOTALRECLAW_SESSION_ID`` was in the removed list during the v1
+ * cleanup and silently rejected with a warning. That broke Axiom log tracing
+ * for QA — the qa-totalreclaw skill prescribes setting the var so relay logs
+ * are searchable by ``X-TotalReclaw-Session``. Restored as a SUPPORTED
+ * variable: read here, forwarded as the ``X-TotalReclaw-Session`` header on
+ * every outbound relay call. Mirrors the Python-side fix
+ * (`python/src/totalreclaw/agent/state.py`, v2.0.2). See internal#127.
  * Removed legacy gates: TOTALRECLAW_CLAIM_FORMAT, TOTALRECLAW_DIGEST_MODE,
  * TOTALRECLAW_AUTO_RESOLVE_MODE (the last one moved to an internal debug
  * module; see `contradiction-sync.ts`).
@@ -33,18 +40,27 @@ const REMOVED_ENV_VARS = [
   'TOTALRECLAW_EMBEDDING_MODEL',
   'TOTALRECLAW_STORE_DEDUP',
   'TOTALRECLAW_LLM_MODEL',
-  'TOTALRECLAW_SESSION_ID',
+  // NOTE: TOTALRECLAW_SESSION_ID was here before; restored as SUPPORTED
+  // (forwarded as X-TotalReclaw-Session header). Do NOT add it back to this
+  // list — see file header + internal#127.
   'TOTALRECLAW_TAXONOMY_VERSION',
   'TOTALRECLAW_CLAIM_FORMAT',
   'TOTALRECLAW_DIGEST_MODE',
 ] as const;
 
+// Migration guide URL — kept as a constant so the regression test can assert
+// the exact link text in the warning. Pointing at GitHub raw-blob is more
+// useful than the relative repo path: operators copying the warning out of
+// stderr usually do not have the repo cloned. rc.22 finding #4.
+export const ENV_VARS_REFERENCE_URL =
+  'https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/env-vars-reference.md';
+
 function warnRemovedEnvVars(warn: (msg: string) => void = console.warn): void {
   const set = REMOVED_ENV_VARS.filter((name) => process.env[name] !== undefined);
   if (set.length === 0) return;
   warn(
     `TotalReclaw: ignoring removed env var(s): ${set.join(', ')}. ` +
-      `See docs/guides/env-vars-reference.md for the v1 env var surface.`,
+      `Migration guide: ${ENV_VARS_REFERENCE_URL}`,
   );
 }
 
@@ -63,6 +79,27 @@ export function getRecoveryPhrase(): string {
   return _recoveryPhraseOverride ?? process.env.TOTALRECLAW_RECOVERY_PHRASE ?? '';
 }
 
+/**
+ * Read the QA / observability session tag from the environment.
+ *
+ * When set, every outbound relay call adds the ``X-TotalReclaw-Session``
+ * header so relay logs (and Axiom queries) can be filtered by this tag —
+ * this is what the qa-totalreclaw skill relies on to scope log searches per
+ * QA run. When unset, returns ``null`` and the header is omitted.
+ *
+ * Read via getter (not snapshotted) so operators / test harnesses can flip
+ * the var between calls without reloading the module.
+ *
+ * Mirrors the Python-side ``RelayClient._session_id`` resolution priority.
+ * See internal#127 / `docs/guides/env-vars-reference.md`.
+ */
+export function getSessionId(): string | null {
+  const raw = process.env.TOTALRECLAW_SESSION_ID;
+  if (raw === undefined) return null;
+  const trimmed = raw.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
 /**
  * Runtime override for chain ID, set after the relay billing response is
  * read. Free tier stays on 84532 (Base Sepolia); Pro tier flips to 100
@@ -92,6 +129,15 @@ export const CONFIG = {
   get recoveryPhrase(): string {
     return getRecoveryPhrase();
   },
+  /**
+   * Optional QA / observability session tag forwarded to the relay as
+   * ``X-TotalReclaw-Session``. See `getSessionId()` above. Getter form so
+   * tests + harnesses can flip the env between calls. ``null`` when unset
+   * (header omitted).
+   */
+  get sessionId(): string | null {
+    return getSessionId();
+  },
   serverUrl: (process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz').replace(/\/+$/, ''),
   selfHosted: process.env.TOTALRECLAW_SELF_HOSTED === 'true',
   credentialsPath: process.env.TOTALRECLAW_CREDENTIALS_PATH || path.join(home, '.totalreclaw', 'credentials.json'),
@@ -105,6 +151,21 @@ export const CONFIG = {
   // for 15-min TTL windows; 0600 mode.
   pairSessionsPath: process.env.TOTALRECLAW_PAIR_SESSIONS_PATH || path.join(home, '.totalreclaw', 'pair-sessions.json'),
 
+  // 3.3.1-rc.11 — pair-flow transport selector. Mirrors the Python-side
+  // `TOTALRECLAW_PAIR_MODE` env (rc.10). `'relay'` (default) routes
+  // `totalreclaw_pair` through the universal-reachability WebSocket relay at
+  // `TOTALRECLAW_PAIR_RELAY_URL`. `'local'` preserves the rc.4–rc.10 loopback
+  // HTTP flow (the plugin serves `/plugin/totalreclaw/pair/*` via
+  // `pair-http.ts`). Air-gapped / self-hosted users can pin `'local'` here.
+  pairMode: (() => {
+    const v = (process.env.TOTALRECLAW_PAIR_MODE ?? '').trim().toLowerCase();
+    return v === 'local' ? 'local' : 'relay';
+  })() as 'relay' | 'local',
+  // 3.3.1-rc.11 — relay base URL for the WebSocket-brokered pair flow.
+  // `wss://` preferred; `https://` is rewritten in the remote-client.
+  pairRelayUrl: (process.env.TOTALRECLAW_PAIR_RELAY_URL
+    || 'wss://api-staging.totalreclaw.xyz').replace(/\/+$/, ''),
+
   // Chain — chainId is no longer user-configurable. It is auto-detected from
   // the relay billing response (free = Base Sepolia / 84532, Pro = Gnosis /
   // 100). The default here is used only before the first billing lookup
@@ -188,11 +249,54 @@ export const CONFIG = {
     return process.env.TOTALRECLAW_QA_GITHUB_TOKEN || process.env.GITHUB_TOKEN || '';
   },
 
+  // 3.3.1-rc.14: optional target-repo override for the RC-gated QA
+  // bug-report tool. The `qa-bug-report` module enforces a
+  // "slug ends in `-internal`" rule on whatever is resolved here, so
+  // this override is only useful for forks / mirrors of the internal
+  // tracker. Leaving unset uses the production default
+  // (`p-diogo/totalreclaw-internal`). Read via getter so operators can
+  // flip the var at runtime.
+  get qaRepoOverride(): string {
+    return process.env.TOTALRECLAW_QA_REPO || '';
+  },
+
+  // 3.3.1-rc.21 (issue #128): verbose-register flag. When enabled, the
+  // plugin emits opt-in `info`-level breadcrumbs after sensitive
+  // registerTool calls (currently `totalreclaw_pair`) to help ops/QA
+  // grep gateway logs for definitive proof the tool was declared.
+  // Default OFF — the breadcrumb is debug-grade and was bleeding into
+  // `openclaw agent --json` stdout, breaking programmatic parsers.
+  // Enable with either:
+  //   TOTALRECLAW_VERBOSE_REGISTER=1   (specific opt-in)
+  //   TOTALRECLAW_DEBUG=1              (general debug toggle)
+  // Read via getter so flipping the env at runtime takes effect on the
+  // next gateway start without a rebuild.
+  get verboseRegister(): boolean {
+    const specific = (process.env.TOTALRECLAW_VERBOSE_REGISTER ?? '').trim().toLowerCase();
+    if (specific === '1' || specific === 'true' || specific === 'yes') return true;
+    const general = (process.env.TOTALRECLAW_DEBUG ?? '').trim().toLowerCase();
+    return general === '1' || general === 'true' || general === 'yes';
+  },
+
   // Paths
   home,
   billingCachePath: path.join(home, '.totalreclaw', 'billing-cache.json'),
   cachePath: process.env.TOTALRECLAW_CACHE_PATH || path.join(home, '.totalreclaw', 'cache.enc'),
   openclawWorkspace: path.join(home, '.openclaw', 'workspace'),
+
+  // 3.3.1-rc.22 — lazy embedder bundle cache. The embedder
+  // (`@huggingface/transformers` + `onnxruntime-node` + the q4 ONNX
+  // model) is no longer shipped inside the plugin tarball; it is fetched
+  // on first `embed()` call from a versioned GitHub Release and cached
+  // here. Separate path from `cachePath` (encrypted vault cache) so the
+  // two never collide. See `embedder-loader.ts`.
+  embedderCachePath: process.env.TOTALRECLAW_EMBEDDER_CACHE_PATH || path.join(home, '.totalreclaw', 'embedder'),
+
+  // 3.3.1-rc.22 — override the GitHub-Releases URL templates. Only useful
+  // for air-gapped / mirror deployments and self-hosted CI. Empty string
+  // falls back to the static defaults baked into the embedder code path.
+  embedderBundleUrlTemplate: process.env.TOTALRECLAW_EMBEDDER_BUNDLE_URL || '',
+  embedderManifestUrlTemplate: process.env.TOTALRECLAW_EMBEDDER_MANIFEST_URL || '',
 } as const;
 
 // ---------------------------------------------------------------------------

package/confirm-indexed.ts

@@ -0,0 +1,191 @@
+/**
+ * Read-after-write primitive — confirm a fact id has been indexed by the
+ * subgraph after an on-chain mutation (retype / set_scope / pin / unpin /
+ * forget).
+ *
+ * Wraps the pure-compute halves exported by `@totalreclaw/core`
+ * (`wasmConfirmIndexedQuery`, `wasmConfirmIndexedParse`) in a host-side
+ * polling loop. Subgraph indexer lag on Gnosis production runs 5-30s; this
+ * helper polls every `pollIntervalMs` (default 1000ms) up to `timeoutMs`
+ * (default 30000ms).
+ *
+ * Why this exists
+ * ---------------
+ * Pre-fix, mutation tools returned `{success: true}` based on the bundler
+ * ack alone. A user who immediately ran `totalreclaw_export` would see the
+ * pre-mutation state, because the subgraph indexer hadn't yet observed the
+ * L1 inclusion. Confusing UX, root cause of rc.18 finding #117.
+ *
+ * Post-fix, mutation tools call `confirmIndexed(newFactId)` after submitting
+ * the batched UserOp; on success they return normally, on timeout they
+ * return `{success: true, partial: true, ...}` with the chain write
+ * acknowledged but the indexer-level confirmation withheld.
+ *
+ * Mnemonic isolation: this helper never touches the mnemonic, encryption
+ * key, or any decrypted blob. Only reads the public {id, isActive,
+ * blockNumber} of a fact.
+ */
+
+import { createRequire } from 'node:module';
+import { getSubgraphConfig } from './subgraph-store.js';
+import { buildRelayHeaders } from './relay-headers.js';
+
+/**
+ * The four `wasmConfirmIndexed*` exports below ship in `@totalreclaw/core@2.3.x`
+ * (the `confirm` module added in 2.2.x). Older type declarations don't list
+ * them — we use a structural cast so the plugin's `--noCheck` build is
+ * unblocked and runtime resolution is via dynamic require.
+ */
+type ConfirmIndexedCore = typeof import('@totalreclaw/core') & {
+  wasmConfirmIndexedQuery(): string;
+  wasmConfirmIndexedParse(responseJson: string): boolean;
+  wasmConfirmIndexedDefaultPollMs(): number;
+  wasmConfirmIndexedDefaultTimeoutMs(): number;
+};
+
+const requireWasm = createRequire(import.meta.url);
+let _wasm: ConfirmIndexedCore | null = null;
+function getWasm(): ConfirmIndexedCore {
+  if (!_wasm) _wasm = requireWasm('@totalreclaw/core') as unknown as ConfirmIndexedCore;
+  return _wasm!;
+}
+
+/** Result of a confirm-indexed poll loop. */
+export interface ConfirmIndexedResult {
+  /** True if the fact was found and `isActive == true` before the timeout. */
+  indexed: boolean;
+  /** Number of poll attempts before resolution (or timeout). */
+  attempts: number;
+  /** Total wall-clock ms spent polling. */
+  elapsedMs: number;
+  /** Last error message from the GraphQL adapter, if any. */
+  lastError?: string;
+}
+
+export interface ConfirmIndexedOptions {
+  /** Override the default 1s poll interval. */
+  pollIntervalMs?: number;
+  /** Override the default 30s total timeout. */
+  timeoutMs?: number;
+  /** Override `${relayUrl}/v1/subgraph` (test injection point). */
+  subgraphUrl?: string;
+  /** Override the auth-key-hex header (defaults to none). */
+  authKeyHex?: string;
+  /**
+   * Direction of the read-after-write check.
+   *   - `"active"` (default) — wait until fact is found AND `isActive == true`.
+   *     Use after pin/unpin/retype/set_scope (we're confirming the *new* fact
+   *     id has appeared).
+   *   - `"inactive"` — wait until fact either disappears OR `isActive ==
+   *     false`. Use after `forget`, where the *original* fact id is being
+   *     tombstoned and a confirm-indexed wait should resolve once the
+   *     subgraph has flipped it.
+   */
+  expect?: 'active' | 'inactive';
+  /**
+   * Test injection — caller-provided `fetch`-compatible POST. Defaults to
+   * the global `fetch`. Letting tests stub this out avoids a network mock
+   * dependency.
+   */
+  poster?: (url: string, body: string, headers: Record<string, string>) => Promise<{
+    ok: boolean;
+    status: number;
+    text: () => Promise<string>;
+  }>;
+}
+
+/**
+ * Poll the subgraph until the new fact id is indexed-and-active, or the
+ * timeout elapses. Returns a result object describing the outcome — never
+ * throws on indexer-level transient errors; the caller decides whether to
+ * surface a `partial: true` flag based on `result.indexed`.
+ *
+ * The host's submitBatch already returned a tx hash before this is called,
+ * so on `indexed: false` the on-chain write is still acknowledged — just not
+ * yet visible in the read API.
+ */
+export async function confirmIndexed(
+  factId: string,
+  options: ConfirmIndexedOptions = {},
+): Promise<ConfirmIndexedResult> {
+  // WASM bindings may be unavailable (e.g. core@<2.3.0 not yet published).
+  // In that case the chain write has still succeeded — confirm step is
+  // observational only. Return `indexed: false` so callers surface
+  // `partial: true` rather than fail the whole tool invocation.
+  let wasm: ConfirmIndexedCore;
+  let query: string;
+  let pollIntervalMs: number;
+  let timeoutMs: number;
+  try {
+    wasm = getWasm();
+    pollIntervalMs = options.pollIntervalMs ?? Number(wasm.wasmConfirmIndexedDefaultPollMs?.() ?? 1000);
+    timeoutMs = options.timeoutMs ?? Number(wasm.wasmConfirmIndexedDefaultTimeoutMs?.() ?? 30000);
+    query = wasm.wasmConfirmIndexedQuery();
+  } catch (err) {
+    return {
+      indexed: false,
+      attempts: 0,
+      elapsedMs: 0,
+      lastError: `confirm-indexed wasm bindings unavailable: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+  const subgraphUrl =
+    options.subgraphUrl ?? `${getSubgraphConfig().relayUrl}/v1/subgraph`;
+
+  const overrides: Record<string, string> = {
+    'Content-Type': 'application/json',
+  };
+  if (options.authKeyHex) overrides['Authorization'] = `Bearer ${options.authKeyHex}`;
+  const headers = buildRelayHeaders(overrides);
+
+  const body = JSON.stringify({ query, variables: { id: factId } });
+
+  const poster =
+    options.poster ??
+    (async (url, b, h) => {
+      const r = await fetch(url, { method: 'POST', headers: h, body: b });
+      return { ok: r.ok, status: r.status, text: () => r.text() };
+    });
+
+  const expect = options.expect ?? 'active';
+  const start = Date.now();
+  let attempts = 0;
+  let lastError: string | undefined;
+
+  while (Date.now() - start < timeoutMs) {
+    attempts++;
+    try {
+      const r = await poster(subgraphUrl, body, headers);
+      if (r.ok) {
+        const txt = await r.text();
+        try {
+          // wasmConfirmIndexedParse returns `true` when fact is present AND
+          // isActive==true. For `expect: 'inactive'` we invert: a `false`
+          // (fact missing OR present-but-inactive) is the resolution signal.
+          const isActive = wasm.wasmConfirmIndexedParse(txt);
+          const resolved = expect === 'active' ? isActive : !isActive;
+          if (resolved) {
+            return { indexed: true, attempts, elapsedMs: Date.now() - start };
+          }
+        } catch (parseErr) {
+          lastError = parseErr instanceof Error ? parseErr.message : String(parseErr);
+        }
+      } else {
+        lastError = `HTTP ${r.status}`;
+      }
+    } catch (err) {
+      lastError = err instanceof Error ? err.message : String(err);
+    }
+    // Sleep before the next attempt — but only if there's still budget.
+    const remaining = timeoutMs - (Date.now() - start);
+    if (remaining <= 0) break;
+    await new Promise((res) => setTimeout(res, Math.min(pollIntervalMs, remaining)));
+  }
+
+  return {
+    indexed: false,
+    attempts,
+    elapsedMs: Date.now() - start,
+    lastError,
+  };
+}

package/crypto.ts

@@ -15,10 +15,18 @@
  *     -> HKDF-SHA256(seed, salt, "openmemory-dedup-v1",           32) -> dedupKey
  */
 
-// Lazy-load WASM to avoid crash when npm install hasn't finished yet.
+// Lazy-load WASM. Uses createRequire so this module loads cleanly under bare
+// Node ESM — the shipped `dist/index.js` declares `"type":"module"`, where
+// the CJS `require` global is undefined at runtime. Prior to the rc.21 fix
+// this file called bare `require('@totalreclaw/core')` and every consumer
+// died with `require is not defined`. Matches the pattern already used by
+// claims-helper / consolidation / contradiction-sync / digest-sync / pin /
+// retype-setscope. See issue #124.
+import { createRequire } from 'node:module';
+const requireWasm = createRequire(import.meta.url);
 let _wasm: typeof import('@totalreclaw/core') | null = null;
 function getWasm() {
-  if (!_wasm) _wasm = require('@totalreclaw/core');
+  if (!_wasm) _wasm = requireWasm('@totalreclaw/core');
   return _wasm;
 }
 

package/dist/api-client.js

@@ -0,0 +1,226 @@
+/**
+ * TotalReclaw Plugin - HTTP API Client
+ *
+ * Communicates with the TotalReclaw server over JSON/HTTP. Uses Node.js
+ * built-in `fetch` (available since Node 18).
+ *
+ * All authenticated endpoints expect:
+ *   Authorization: Bearer <hex-encoded-auth-key>
+ *
+ * The server hashes the auth key with SHA-256 to look up the user.
+ *
+ * Every outbound request goes through `buildRelayHeaders()` so the
+ * `X-TotalReclaw-Client` tag is set + the optional QA-tracing
+ * `X-TotalReclaw-Session` tag is forwarded when `TOTALRECLAW_SESSION_ID`
+ * is set. See `relay-headers.ts` and internal#127.
+ */
+import { buildRelayHeaders } from './relay-headers.js';
+// ---------------------------------------------------------------------------
+// API Client Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create an API client bound to a specific TotalReclaw server URL.
+ *
+ * All methods are async and throw descriptive errors on non-2xx responses.
+ */
+export function createApiClient(serverUrl) {
+    // Normalise URL -- strip trailing slash.
+    const baseUrl = serverUrl.replace(/\/+$/, '');
+    // ------------------------------------------------------------------
+    // Shared helpers
+    // ------------------------------------------------------------------
+    /**
+     * Throw a descriptive error when the server returns a non-2xx status.
+     */
+    async function assertOk(res, context) {
+        if (res.ok)
+            return;
+        let body;
+        try {
+            body = await res.text();
+        }
+        catch {
+            body = '(could not read response body)';
+        }
+        const hint = res.status === 401
+            ? ' Authentication failed. If using a recovery phrase, check that all 12 words are in the correct order and spelled correctly.'
+            : '';
+        throw new Error(`${context}: HTTP ${res.status} - ${body}${hint}`);
+    }
+    // ------------------------------------------------------------------
+    // Public methods
+    // ------------------------------------------------------------------
+    return {
+        // ---- Registration (unauthenticated) ----
+        /**
+         * Register a new user.
+         *
+         * @param authKeyHash  Hex-encoded SHA-256 of the auth key (64 chars).
+         * @param saltHex      Hex-encoded 32-byte salt (64 chars).
+         * @returns `{ user_id }` on success.
+         */
+        async register(authKeyHash, saltHex) {
+            const res = await fetch(`${baseUrl}/v1/register`, {
+                method: 'POST',
+                headers: buildRelayHeaders({ 'Content-Type': 'application/json' }),
+                body: JSON.stringify({ auth_key_hash: authKeyHash, salt: saltHex }),
+            });
+            await assertOk(res, 'register');
+            const json = (await res.json());
+            if (!json.success && json.error_code !== 'USER_EXISTS') {
+                throw new Error(`register: server returned success=false - ${json.error_code}: ${json.error_message}`);
+            }
+            if (!json.user_id) {
+                throw new Error(`register: server did not return user_id (error_code=${json.error_code})`);
+            }
+            return { user_id: json.user_id };
+        },
+        // ---- Store (authenticated) ----
+        /**
+         * Store one or more encrypted facts.
+         *
+         * @param userId       The authenticated user's ID.
+         * @param facts        Array of `StoreFactPayload` objects.
+         * @param authKeyHex   Hex-encoded raw auth key (64 chars) for Bearer header.
+         */
+        async store(userId, facts, authKeyHex) {
+            const res = await fetch(`${baseUrl}/v1/store`, {
+                method: 'POST',
+                headers: buildRelayHeaders({
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${authKeyHex}`,
+                }),
+                body: JSON.stringify({ user_id: userId, facts }),
+            });
+            await assertOk(res, 'store');
+            const json = (await res.json());
+            if (!json.success) {
+                throw new Error(`store: server returned success=false - ${json.error_code}: ${json.error_message}`);
+            }
+            return {
+                ids: json.ids ?? [],
+                duplicate_ids: json.duplicate_ids,
+            };
+        },
+        // ---- Search (authenticated) ----
+        /**
+         * Search for facts using blind trapdoors.
+         *
+         * @param userId         The authenticated user's ID.
+         * @param trapdoors      SHA-256 hex hashes of query tokens.
+         * @param maxCandidates  Maximum candidates to retrieve.
+         * @param authKeyHex     Hex-encoded raw auth key for Bearer header.
+         * @returns Array of encrypted search candidates.
+         */
+        async search(userId, trapdoors, maxCandidates, authKeyHex) {
+            const res = await fetch(`${baseUrl}/v1/search`, {
+                method: 'POST',
+                headers: buildRelayHeaders({
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${authKeyHex}`,
+                }),
+                body: JSON.stringify({
+                    user_id: userId,
+                    trapdoors,
+                    max_candidates: maxCandidates,
+                }),
+            });
+            await assertOk(res, 'search');
+            const json = (await res.json());
+            if (!json.success) {
+                throw new Error(`search: server returned success=false - ${json.error_code}: ${json.error_message}`);
+            }
+            return json.results ?? [];
+        },
+        // ---- Delete (authenticated) ----
+        /**
+         * Soft-delete a fact by ID.
+         *
+         * @param factId      The fact UUID to delete.
+         * @param authKeyHex  Hex-encoded raw auth key for Bearer header.
+         */
+        async deleteFact(factId, authKeyHex) {
+            const res = await fetch(`${baseUrl}/v1/facts/${encodeURIComponent(factId)}`, {
+                method: 'DELETE',
+                headers: buildRelayHeaders({
+                    Authorization: `Bearer ${authKeyHex}`,
+                }),
+            });
+            await assertOk(res, 'deleteFact');
+            const json = (await res.json());
+            if (!json.success) {
+                throw new Error(`deleteFact: server returned success=false - ${json.error_code}: ${json.error_message}`);
+            }
+        },
+        // ---- Batch Delete (authenticated) ----
+        /**
+         * Batch soft-delete facts by ID list.
+         *
+         * @param factIds     Array of fact UUIDs to delete (max 500).
+         * @param authKeyHex  Hex-encoded raw auth key for Bearer header.
+         * @returns The number of facts that were actually deleted.
+         */
+        async batchDelete(factIds, authKeyHex) {
+            const res = await fetch(`${baseUrl}/v1/facts/batch-delete`, {
+                method: 'POST',
+                headers: buildRelayHeaders({
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${authKeyHex}`,
+                }),
+                body: JSON.stringify({ fact_ids: factIds }),
+            });
+            await assertOk(res, 'batchDelete');
+            const json = (await res.json());
+            if (!json.success) {
+                throw new Error(`batchDelete: server returned success=false - ${json.error_code}: ${json.error_message}`);
+            }
+            return json.deleted_count ?? 0;
+        },
+        // ---- Export (authenticated) ----
+        /**
+         * Export all active facts (paginated).
+         *
+         * @param authKeyHex  Hex-encoded raw auth key for Bearer header.
+         * @param limit       Page size (default 1000, max 5000).
+         * @param cursor      Cursor from previous page (omit for first page).
+         * @returns Page of facts with pagination metadata.
+         */
+        async exportFacts(authKeyHex, limit = 1000, cursor) {
+            const params = new URLSearchParams({ limit: String(limit) });
+            if (cursor)
+                params.set('cursor', cursor);
+            const res = await fetch(`${baseUrl}/v1/export?${params.toString()}`, {
+                method: 'GET',
+                headers: buildRelayHeaders({
+                    Authorization: `Bearer ${authKeyHex}`,
+                }),
+            });
+            await assertOk(res, 'exportFacts');
+            const json = (await res.json());
+            if (!json.success) {
+                throw new Error(`exportFacts: server returned success=false - ${json.error_code}: ${json.error_message}`);
+            }
+            return {
+                facts: json.facts ?? [],
+                cursor: json.cursor,
+                has_more: json.has_more ?? false,
+                total_count: json.total_count,
+            };
+        },
+        // ---- Health (unauthenticated) ----
+        /**
+         * Check server health.
+         *
+         * @returns `true` if the server responds with HTTP 200.
+         */
+        async health() {
+            try {
+                const res = await fetch(`${baseUrl}/health`, { method: 'GET' });
+                return res.status === 200;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}