@totalreclaw/totalreclaw 3.3.1-rc.21 → 3.3.1-rc.22

package/CHANGELOG.md

@@ -493,7 +493,8 @@ See: `plans/2026-04-22-plugin-3.3.1-provider-agnostic-llm.md` (internal).
     - `--json` — emits a structured payload (requires `--non-interactive`).
     - `--mode <generate|restore>` — skip the menu prompt.
     - `--phrase <12-or-24>` — required for `--mode restore`; `-` reads stdin.
-    - `--emit-phrase` — opt-in path that includes the plaintext phrase in the
+    - `--emit-phrase` — historic opt-in flag (do not invoke via agent shell:
+      forbidden by the phrase-safety rule); included plaintext phrase in the
       JSON payload. Default omits the phrase; the agent should direct the
       user to read `~/.totalreclaw/credentials.json` in their terminal.
 

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
 description: "Install + set up TotalReclaw encrypted memory for OpenClaw, then use totalreclaw_remember / totalreclaw_recall. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', or any remember / recall request."
-version: 3.3.1-rc.11
+version: 3.3.1-rc.22
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz

package/claims-helper.ts

@@ -96,6 +96,14 @@ export interface BuildClaimInput {
   sourceAgent: string;
   /** Creation timestamp. Defaults to now. */
   extractedAt?: string;
+  /**
+   * 3.3.1-rc.22 — optional embedding-model id stamped on the claim for
+   * forward-compat. Defaults to omitted (callers that already know the
+   * active embedder pass it in; legacy paths leave it unset). The field
+   * is plugin-scoped — it survives the core validator's strip pass via
+   * the same re-attach path used for `schema_version` / `volatility`.
+   */
+  embeddingModelId?: string;
 }
 
 /**
@@ -112,7 +120,7 @@ export interface BuildClaimInput {
  * payload (see `subgraph-store.ts::encodeFactProtobuf`).
  */
 export function buildCanonicalClaim(input: BuildClaimInput): string {
-  const { fact, importance, extractedAt } = input;
+  const { fact, importance, extractedAt, embeddingModelId } = input;
 
   // Defensive: ensure fact.source is always populated before v1 validation.
   // `applyProvenanceFilterLax` should have set this upstream; this is the
@@ -125,6 +133,7 @@ export function buildCanonicalClaim(input: BuildClaimInput): string {
     fact: factWithSource,
     importance,
     createdAt: extractedAt,
+    embeddingModelId,
   });
 }
 
@@ -173,6 +182,14 @@ export interface BuildClaimV1Input {
    * when provided.
    */
   pinStatus?: PinStatus;
+  /**
+   * 3.3.1-rc.22 — optional embedding-model id stamped on the claim for
+   * distillation forward-compat. Survives the core validator strip pass
+   * via the same re-attach path used for `schema_version` / `volatility`.
+   * When omitted the field is not emitted (legacy claims remain untagged
+   * and are read back as "unspecified").
+   */
+  embeddingModelId?: string;
 }
 
 /**
@@ -257,6 +274,13 @@ export function buildCanonicalClaimV1(input: BuildClaimV1Input): string {
   if (fact.volatility && (VALID_MEMORY_VOLATILITIES as readonly string[]).includes(fact.volatility)) {
     canonical.volatility = fact.volatility;
   }
+  // 3.3.1-rc.22 — forward-compat embedder marker. Plugin-only field;
+  // survives the core validator via re-attach. Future distillation
+  // detects this on read to re-embed selectively without forcing a
+  // vault-wide rebuild.
+  if (typeof input.embeddingModelId === 'string' && input.embeddingModelId.length > 0) {
+    canonical.embedding_model_id = input.embeddingModelId;
+  }
 
   return JSON.stringify(canonical);
 }
@@ -313,6 +337,11 @@ export interface BuildV1ClaimBlobInput {
    * non-pin write.
    */
   pinStatus?: PinStatus;
+  /**
+   * 3.3.1-rc.22 — optional embedding-model id stamped on the claim for
+   * distillation forward-compat. See `BuildClaimV1Input.embeddingModelId`.
+   */
+  embeddingModelId?: string;
 }
 
 /**
@@ -374,6 +403,10 @@ export function buildV1ClaimBlob(input: BuildV1ClaimBlobInput): string {
   if (input.volatility && (VALID_MEMORY_VOLATILITIES as readonly string[]).includes(input.volatility)) {
     canonical.volatility = input.volatility;
   }
+  // 3.3.1-rc.22 — see `buildCanonicalClaimV1` comment.
+  if (typeof input.embeddingModelId === 'string' && input.embeddingModelId.length > 0) {
+    canonical.embedding_model_id = input.embeddingModelId;
+  }
   return JSON.stringify(canonical);
 }
 
@@ -431,6 +464,13 @@ export interface V1BlobReadResult {
    * when the writer explicitly omitted the field (treated as `"unpinned"`).
    */
   pinStatus?: PinStatus;
+  /**
+   * 3.3.1-rc.22 — embedder identity tag. Absent on claims written by
+   * older plugin versions. Forward-compat marker; consumers MAY use it
+   * to decide whether a claim's stored embedding matches the active
+   * embedder before letting cosine similarity make a relevance call.
+   */
+  embeddingModelId?: string;
 }
 
 export function readV1Blob(decrypted: string): V1BlobReadResult | null {
@@ -497,6 +537,12 @@ export function readV1Blob(decrypted: string): V1BlobReadResult | null {
         result.pinStatus = ps;
       }
     }
+    // 3.3.1-rc.22 — pull the embedder identity tag through. Plugin-only
+    // field added by `buildCanonicalClaimV1` / `buildV1ClaimBlob` after
+    // core validation.
+    if (typeof obj.embedding_model_id === 'string' && obj.embedding_model_id.length > 0) {
+      result.embeddingModelId = obj.embedding_model_id;
+    }
 
     return result;
   } catch {

package/config.ts

@@ -48,12 +48,19 @@ const REMOVED_ENV_VARS = [
   '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}`,
   );
 }
 
@@ -276,6 +283,20 @@ export const CONFIG = {
   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/dist/claims-helper.js

@@ -71,7 +71,7 @@ export function mapTypeToCategory(type) {
  * payload (see `subgraph-store.ts::encodeFactProtobuf`).
  */
 export function buildCanonicalClaim(input) {
-    const { fact, importance, extractedAt } = input;
+    const { fact, importance, extractedAt, embeddingModelId } = input;
     // Defensive: ensure fact.source is always populated before v1 validation.
     // `applyProvenanceFilterLax` should have set this upstream; this is the
     // belt-and-suspenders fallback for explicit tool paths / legacy callers.
@@ -82,6 +82,7 @@ export function buildCanonicalClaim(input) {
         fact: factWithSource,
         importance,
         createdAt: extractedAt,
+        embeddingModelId,
     });
 }
 // ---------------------------------------------------------------------------
@@ -173,6 +174,13 @@ export function buildCanonicalClaimV1(input) {
     if (fact.volatility && VALID_MEMORY_VOLATILITIES.includes(fact.volatility)) {
         canonical.volatility = fact.volatility;
     }
+    // 3.3.1-rc.22 — forward-compat embedder marker. Plugin-only field;
+    // survives the core validator via re-attach. Future distillation
+    // detects this on read to re-embed selectively without forcing a
+    // vault-wide rebuild.
+    if (typeof input.embeddingModelId === 'string' && input.embeddingModelId.length > 0) {
+        canonical.embedding_model_id = input.embeddingModelId;
+    }
     return JSON.stringify(canonical);
 }
 /**
@@ -234,6 +242,10 @@ export function buildV1ClaimBlob(input) {
     if (input.volatility && VALID_MEMORY_VOLATILITIES.includes(input.volatility)) {
         canonical.volatility = input.volatility;
     }
+    // 3.3.1-rc.22 — see `buildCanonicalClaimV1` comment.
+    if (typeof input.embeddingModelId === 'string' && input.embeddingModelId.length > 0) {
+        canonical.embedding_model_id = input.embeddingModelId;
+    }
     return JSON.stringify(canonical);
 }
 /**
@@ -321,6 +333,12 @@ export function readV1Blob(decrypted) {
                 result.pinStatus = ps;
             }
         }
+        // 3.3.1-rc.22 — pull the embedder identity tag through. Plugin-only
+        // field added by `buildCanonicalClaimV1` / `buildV1ClaimBlob` after
+        // core validation.
+        if (typeof obj.embedding_model_id === 'string' && obj.embedding_model_id.length > 0) {
+            result.embeddingModelId = obj.embedding_model_id;
+        }
         return result;
     }
     catch {

package/dist/config.js

@@ -44,12 +44,17 @@ const REMOVED_ENV_VARS = [
     'TOTALRECLAW_CLAIM_FORMAT',
     'TOTALRECLAW_DIGEST_MODE',
 ];
+// 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 = console.warn) {
     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}`);
 }
 // Emit the warning once at import time. Safe because this module is loaded
 // exactly once per process.
@@ -254,6 +259,18 @@ export const CONFIG = {
     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 || '',
 };
 /**
  * Merge a billing-response tuning block with the local fallback values.

package/dist/confirm-indexed.js

@@ -0,0 +1,127 @@
+/**
+ * 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';
+const requireWasm = createRequire(import.meta.url);
+let _wasm = null;
+function getWasm() {
+    if (!_wasm)
+        _wasm = requireWasm('@totalreclaw/core');
+    return _wasm;
+}
+/**
+ * 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, options = {}) {
+    // 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;
+    let query;
+    let pollIntervalMs;
+    let timeoutMs;
+    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 = {
+        '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;
+    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,
+    };
+}