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

package/dist/config.js

@@ -0,0 +1,280 @@
+/**
+ * Plugin configuration — centralized env var reads.
+ * This file ONLY reads process.env. No network calls, no I/O.
+ * Other modules import config values from here.
+ *
+ * OpenClaw's security scanner flags files that contain BOTH process.env reads
+ * AND network calls. By centralizing all env reads here, no other file needs
+ * to touch process.env directly.
+ *
+ * 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_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`).
+ *
+ * Tuning knobs (cosine threshold, min importance, cache TTL, etc.) are now
+ * delivered via the relay billing response. Env-var fallbacks are kept only
+ * for self-hosted deployments where the server may not surface those values.
+ */
+import path from 'node:path';
+const home = process.env.HOME ?? '/home/node';
+/**
+ * Removed env vars — warn once per process if still set so operators know
+ * their config is a no-op. The removal list matches `docs/guides/env-vars-reference.md`.
+ */
+const REMOVED_ENV_VARS = [
+    'TOTALRECLAW_CHAIN_ID',
+    'TOTALRECLAW_EMBEDDING_MODEL',
+    'TOTALRECLAW_STORE_DEDUP',
+    'TOTALRECLAW_LLM_MODEL',
+    // 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',
+];
+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.`);
+}
+// Emit the warning once at import time. Safe because this module is loaded
+// exactly once per process.
+warnRemovedEnvVars();
+/** Runtime override for recovery phrase (set by hot-reload after setup). */
+let _recoveryPhraseOverride = null;
+export function setRecoveryPhraseOverride(phrase) {
+    _recoveryPhraseOverride = phrase;
+}
+export function getRecoveryPhrase() {
+    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() {
+    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
+ * (Gnosis mainnet). The relay routes Pro writes to Gnosis, so Pro-tier
+ * UserOps MUST be signed against chain 100 — otherwise the bundler rejects
+ * the signature with AA23.
+ *
+ * See index.ts: after the billing lookup completes, call
+ * `setChainIdOverride(100)` for Pro users. Free users can leave the
+ * override unset.
+ */
+let _chainIdOverride = null;
+export function setChainIdOverride(chainId) {
+    _chainIdOverride = chainId;
+}
+/** Reset the chain override — used by tests. */
+export function __resetChainIdOverrideForTests() {
+    _chainIdOverride = null;
+}
+export const CONFIG = {
+    // Core — recoveryPhrase reads from override first, then env var.
+    // Use getRecoveryPhrase() for dynamic access; this property is for
+    // backward-compat with code that reads CONFIG.recoveryPhrase at init time.
+    get recoveryPhrase() {
+        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() {
+        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'),
+    // 3.2.0 onboarding state file — separate from credentials.json so it
+    // never contains secrets. Loaded on every plugin init + on every
+    // before_tool_call gate check.
+    onboardingStatePath: process.env.TOTALRECLAW_STATE_PATH || path.join(home, '.totalreclaw', 'state.json'),
+    // 3.3.0 QR-pairing session store. Separate file from both credentials.json
+    // and state.json so the session-store module does not have to touch either
+    // (keeps scanner surface isolated). Contains ephemeral x25519 secret keys
+    // 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';
+    })(),
+    // 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
+    // completes. Self-hosted users can still point at a custom DataEdge via
+    // TOTALRECLAW_DATA_EDGE_ADDRESS / TOTALRECLAW_ENTRYPOINT_ADDRESS /
+    // TOTALRECLAW_RPC_URL (undocumented; internal knobs).
+    //
+    // Reads the runtime override set by the billing auto-detect in index.ts.
+    // Falls back to 84532 (free tier / pre-billing-lookup). Must be a getter,
+    // not a literal — a literal would freeze all Pro-tier UserOps to the
+    // wrong chainId and AA23 at the bundler.
+    get chainId() {
+        return _chainIdOverride ?? 84532;
+    },
+    dataEdgeAddress: process.env.TOTALRECLAW_DATA_EDGE_ADDRESS || '',
+    entryPointAddress: process.env.TOTALRECLAW_ENTRYPOINT_ADDRESS || '',
+    rpcUrl: process.env.TOTALRECLAW_RPC_URL || '',
+    // Tuning knobs — default values used only as local fallback for
+    // self-hosted mode. Managed-service clients override these from the relay
+    // billing response via `resolveTuning(...)`.
+    // See: docs/specs/totalreclaw/client-consistency.md
+    cosineThreshold: parseFloat(process.env.TOTALRECLAW_COSINE_THRESHOLD ?? '0.15'),
+    extractInterval: parseInt(process.env.TOTALRECLAW_EXTRACT_INTERVAL ?? process.env.TOTALRECLAW_EXTRACT_EVERY_TURNS ?? '3', 10),
+    relevanceThreshold: parseFloat(process.env.TOTALRECLAW_RELEVANCE_THRESHOLD ?? '0.3'),
+    semanticSkipThreshold: parseFloat(process.env.TOTALRECLAW_SEMANTIC_SKIP_THRESHOLD ?? '0.85'),
+    cacheTtlMs: parseInt(process.env.TOTALRECLAW_CACHE_TTL_MS ?? String(5 * 60 * 1000), 10),
+    minImportance: Math.max(1, Math.min(10, Number(process.env.TOTALRECLAW_MIN_IMPORTANCE) || 6)),
+    trapdoorBatchSize: parseInt(process.env.TOTALRECLAW_TRAPDOOR_BATCH_SIZE ?? '5', 10),
+    pageSize: parseInt(process.env.TOTALRECLAW_SUBGRAPH_PAGE_SIZE ?? '1000', 10),
+    // Store-time dedup is always ON. TOTALRECLAW_STORE_DEDUP was removed in v1.
+    storeDedupEnabled: true,
+    // LLM provider API keys (read once, passed to llm-client). Model selection
+    // is entirely automatic via `deriveCheapModel(provider)` — the
+    // TOTALRECLAW_LLM_MODEL override was removed in v1.
+    llmApiKeys: {
+        zai: process.env.ZAI_API_KEY || '',
+        anthropic: process.env.ANTHROPIC_API_KEY || '',
+        openai: process.env.OPENAI_API_KEY || '',
+        gemini: process.env.GEMINI_API_KEY || '',
+        google: process.env.GOOGLE_API_KEY || '',
+        mistral: process.env.MISTRAL_API_KEY || '',
+        groq: process.env.GROQ_API_KEY || '',
+        deepseek: process.env.DEEPSEEK_API_KEY || '',
+        openrouter: process.env.OPENROUTER_API_KEY || '',
+        xai: process.env.XAI_API_KEY || '',
+        together: process.env.TOGETHER_API_KEY || '',
+        cerebras: process.env.CEREBRAS_API_KEY || '',
+    },
+    // 3.3.1-rc.3: zai base-URL override. Read via a getter so tests can
+    // mutate `process.env.ZAI_BASE_URL` between calls — the value is NOT
+    // frozen at module load. Default is the coding endpoint; the rc.3
+    // auto-fallback flips to the standard endpoint on an "Insufficient
+    // balance" 429.
+    get zaiBaseUrl() {
+        const override = process.env.ZAI_BASE_URL;
+        if (override && override.trim())
+            return override.trim().replace(/\/+$/, '');
+        return 'https://api.z.ai/api/coding/paas/v4';
+    },
+    // 3.3.1-rc.3: retry budget for chatCompletion. Default 60s covers
+    // multi-minute upstream outages. Read as a plain value (not getter)
+    // so tests that patch env need to reload the module — but the default
+    // suffices for production.
+    llmRetryBudgetMs: (() => {
+        const raw = process.env.TOTALRECLAW_LLM_RETRY_BUDGET_MS;
+        const parsed = raw ? parseInt(raw, 10) : NaN;
+        return Number.isFinite(parsed) && parsed > 0 ? parsed : 60_000;
+    })(),
+    // 3.3.1-rc.3: GitHub personal-access token used by the RC-gated
+    // `totalreclaw_report_qa_bug` tool. `TOTALRECLAW_QA_GITHUB_TOKEN` is
+    // the dedicated variable; `GITHUB_TOKEN` is a fallback for CI-style
+    // setups where the same token is shared across tools. Read via getter
+    // so operators can set the var after the process starts (e.g. via a
+    // dotenv reload) and the next tool call picks it up.
+    get qaGithubToken() {
+        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() {
+        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() {
+        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'),
+};
+/**
+ * Merge a billing-response tuning block with the local fallback values.
+ *
+ * Use this at the call-site that needs a threshold, passing the features
+ * blob from the billing cache. No I/O here — callers read the cache once
+ * and hand the features in.
+ */
+export function resolveTuning(features) {
+    return {
+        cosineThreshold: features?.cosine_threshold ?? CONFIG.cosineThreshold,
+        relevanceThreshold: features?.relevance_threshold ?? CONFIG.relevanceThreshold,
+        semanticSkipThreshold: features?.semantic_skip_threshold ?? CONFIG.semanticSkipThreshold,
+        minImportance: features?.min_importance ?? CONFIG.minImportance,
+        cacheTtlMs: features?.cache_ttl_ms ?? CONFIG.cacheTtlMs,
+        trapdoorBatchSize: features?.trapdoor_batch_size ?? CONFIG.trapdoorBatchSize,
+        pageSize: features?.subgraph_page_size ?? CONFIG.pageSize,
+    };
+}
+// Exposed for tests that want to assert the removed-var warning behaviour.
+export const __internal = {
+    REMOVED_ENV_VARS,
+    warnRemovedEnvVars,
+};

package/dist/consolidation.js

@@ -0,0 +1,258 @@
+/**
+ * TotalReclaw Plugin - Memory Consolidation & Near-Duplicate Detection
+ *
+ * Provides cross-session / cross-vault deduplication of stored facts using
+ * cosine similarity on their embeddings. Unlike semantic-dedup.ts (which
+ * handles within-batch dedup at threshold 0.9), this module handles:
+ *
+ *   1. Store-time dedup — before writing a new fact, check whether a
+ *      near-duplicate already exists in the vault (findNearDuplicate).
+ *   2. Supersede logic — when a near-duplicate is found, decide whether
+ *      the new fact should replace or be skipped (shouldSupersede).
+ *   3. Bulk consolidation — cluster all facts in the vault and identify
+ *      groups of near-duplicates for cleanup (clusterFacts).
+ *
+ * Delegates core computation to `@totalreclaw/core` Rust WASM module where
+ * bindings are available. `shouldSupersede` uses the core directly.
+ * `findNearDuplicate` and `clusterFacts` use the core's `findBestNearDuplicate`
+ * and `clusterFacts` WASM functions when available, falling back to local
+ * implementations that use WASM-backed `cosineSimilarity`.
+ *
+ * Threshold helpers remain local (they read process.env).
+ */
+import { createRequire } from 'node:module';
+import { cosineSimilarity } from './reranker.js';
+// ---------------------------------------------------------------------------
+// Lazy-load WASM core (mirrors claims-helper.ts / contradiction-sync.ts
+// pattern — plays nicely under both the OpenClaw runtime (CJS-ish tsx) and
+// bare Node ESM used by tests).
+// ---------------------------------------------------------------------------
+const requireWasm = createRequire(import.meta.url);
+let _wasm = null;
+function getWasm() {
+    if (!_wasm)
+        _wasm = requireWasm('@totalreclaw/core');
+    return _wasm;
+}
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+/**
+ * Get the cosine similarity threshold for store-time dedup.
+ *
+ * Configurable via TOTALRECLAW_STORE_DEDUP_THRESHOLD env var.
+ * Must be a number in [0, 1]. Falls back to 0.85 if invalid or unset.
+ */
+export function getStoreDedupThreshold() {
+    const envVal = process.env.TOTALRECLAW_STORE_DEDUP_THRESHOLD;
+    if (envVal !== undefined) {
+        const parsed = parseFloat(envVal);
+        if (!isNaN(parsed) && parsed >= 0 && parsed <= 1)
+            return parsed;
+    }
+    return 0.85;
+}
+/**
+ * Get the cosine similarity threshold for bulk consolidation clustering.
+ *
+ * Configurable via TOTALRECLAW_CONSOLIDATION_THRESHOLD env var.
+ * Must be a number in [0, 1]. Falls back to 0.88 if invalid or unset.
+ */
+export function getConsolidationThreshold() {
+    const envVal = process.env.TOTALRECLAW_CONSOLIDATION_THRESHOLD;
+    if (envVal !== undefined) {
+        const parsed = parseFloat(envVal);
+        if (!isNaN(parsed) && parsed >= 0 && parsed <= 1)
+            return parsed;
+    }
+    return 0.88;
+}
+/** Maximum candidates to compare against during store-time dedup. */
+export const STORE_DEDUP_MAX_CANDIDATES = 200;
+// ---------------------------------------------------------------------------
+// Store-time dedup
+// ---------------------------------------------------------------------------
+/**
+ * Find the best near-duplicate match for a new fact among existing candidates.
+ *
+ * Compares the new fact's embedding against all candidates using cosine
+ * similarity. Returns the candidate with the highest similarity above the
+ * threshold, or null if no match is found.
+ *
+ * Candidates without embeddings are skipped (fail-safe).
+ *
+ * @param newFactEmbedding - Embedding vector for the new fact
+ * @param candidates       - Existing facts to compare against
+ * @param threshold        - Cosine similarity threshold (e.g. 0.85)
+ * @returns                - Best match above threshold, or null
+ */
+export function findNearDuplicate(newFactEmbedding, candidates, threshold) {
+    const wasm = getWasm();
+    // Use core's findBestNearDuplicate if available (added in core >=1.5.0;
+    // guaranteed present in core >=2.0.0 which this plugin depends on).
+    if (typeof wasm.findBestNearDuplicate === 'function') {
+        const existing = candidates
+            .filter((c) => c.embedding && c.embedding.length > 0)
+            .map((c) => ({ id: c.id, embedding: c.embedding }));
+        if (existing.length === 0)
+            return null;
+        const resultJs = wasm.findBestNearDuplicate(JSON.stringify(newFactEmbedding), JSON.stringify(existing), threshold);
+        if (resultJs == null)
+            return null;
+        const result = typeof resultJs === 'string' ? JSON.parse(resultJs) : resultJs;
+        const matched = candidates.find((c) => c.id === result.fact_id);
+        if (!matched)
+            return null;
+        return { existingFact: matched, similarity: result.similarity };
+    }
+    // Fallback: local loop using WASM-backed cosineSimilarity. Defensive only
+    // — core >=2.0.0 always exposes findBestNearDuplicate.
+    let bestMatch = null;
+    for (const candidate of candidates) {
+        if (!candidate.embedding || candidate.embedding.length === 0)
+            continue;
+        const similarity = cosineSimilarity(newFactEmbedding, candidate.embedding);
+        if (similarity >= threshold) {
+            if (!bestMatch || similarity > bestMatch.similarity) {
+                bestMatch = { existingFact: candidate, similarity };
+            }
+        }
+    }
+    return bestMatch;
+}
+// ---------------------------------------------------------------------------
+// Supersede logic
+// ---------------------------------------------------------------------------
+/**
+ * Decide whether a new fact should supersede an existing near-duplicate.
+ *
+ * - Higher importance wins.
+ * - Equal importance: new fact supersedes (newer is preferred).
+ *
+ * Delegates to `@totalreclaw/core` WASM `shouldSupersede`.
+ *
+ * @param newImportance - Importance score of the new fact
+ * @param existingFact  - The existing near-duplicate candidate
+ * @returns             - 'supersede' if new fact should replace, 'skip' otherwise
+ */
+export function shouldSupersede(newImportance, existingFact) {
+    const wasm = getWasm();
+    return wasm.shouldSupersede(newImportance, existingFact.importance) ? 'supersede' : 'skip';
+}
+// ---------------------------------------------------------------------------
+// Bulk consolidation
+// ---------------------------------------------------------------------------
+/**
+ * Cluster facts by semantic similarity using greedy single-pass clustering.
+ *
+ * Delegates to `@totalreclaw/core` WASM `clusterFacts` which performs the
+ * same greedy single-pass algorithm and representative selection. The WASM
+ * function returns ID-only clusters; this wrapper maps IDs back to full
+ * `DecryptedCandidate` objects for callers.
+ *
+ * Only returns clusters that have duplicates (i.e. more than one member).
+ * Facts without embeddings are not clustered.
+ *
+ * @param facts     - All facts to cluster
+ * @param threshold - Cosine similarity threshold (e.g. 0.88)
+ * @returns         - Clusters with duplicates (representative + duplicates)
+ */
+export function clusterFacts(facts, threshold) {
+    const wasm = getWasm();
+    // Use core's clusterFacts if available (added in core >=1.5.0;
+    // guaranteed present in core >=2.0.0 which this plugin depends on).
+    if (typeof wasm.clusterFacts === 'function') {
+        // Build ConsolidationCandidate JSON for WASM (snake_case fields).
+        const wasmCandidates = facts
+            .filter((f) => f.embedding && f.embedding.length > 0)
+            .map((f) => ({
+            id: f.id,
+            text: f.text,
+            embedding: f.embedding,
+            importance: f.importance,
+            decay_score: f.decayScore,
+            created_at: f.createdAt,
+            version: f.version,
+        }));
+        if (wasmCandidates.length === 0)
+            return [];
+        const resultJs = wasm.clusterFacts(JSON.stringify(wasmCandidates), threshold);
+        // WASM returns a JSON string: [{ representative: string, duplicates: string[] }]
+        const wasmClusters = typeof resultJs === 'string' ? JSON.parse(resultJs) : resultJs;
+        // Build a lookup map for fast ID -> DecryptedCandidate resolution.
+        const byId = new Map();
+        for (const f of facts)
+            byId.set(f.id, f);
+        // Map ID-only clusters back to full DecryptedCandidate objects.
+        // Filter out singleton clusters (no duplicates) to match the pre-WASM
+        // plugin contract — callers rely on `clusters.length === 0` when nothing
+        // duplicates anything.
+        const result = [];
+        for (const wc of wasmClusters) {
+            const rep = byId.get(wc.representative);
+            if (!rep)
+                continue;
+            const dups = wc.duplicates
+                .map((id) => byId.get(id))
+                .filter((d) => d !== undefined);
+            if (dups.length > 0) {
+                result.push({ representative: rep, duplicates: dups });
+            }
+        }
+        return result;
+    }
+    // Fallback: local greedy single-pass clustering using WASM-backed
+    // cosineSimilarity. Defensive only — core >=2.0.0 always exposes clusterFacts.
+    const clusters = [];
+    for (const fact of facts) {
+        if (!fact.embedding || fact.embedding.length === 0)
+            continue;
+        let assigned = false;
+        for (const cluster of clusters) {
+            const seed = cluster.members[0];
+            if (!seed.embedding)
+                continue;
+            const similarity = cosineSimilarity(fact.embedding, seed.embedding);
+            if (similarity >= threshold) {
+                cluster.members.push(fact);
+                assigned = true;
+                break;
+            }
+        }
+        if (!assigned) {
+            clusters.push({ members: [fact] });
+        }
+    }
+    const result = [];
+    for (const cluster of clusters) {
+        if (cluster.members.length < 2)
+            continue;
+        const representative = pickRepresentative(cluster.members);
+        const duplicates = cluster.members.filter((m) => m !== representative);
+        result.push({ representative, duplicates });
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Local helpers (used only in fallback paths)
+// ---------------------------------------------------------------------------
+/**
+ * Pick the best representative from a group of near-duplicate facts.
+ *
+ * Tiebreak order:
+ *   1. Highest decayScore
+ *   2. Most recent (highest createdAt)
+ *   3. Longest text
+ */
+function pickRepresentative(facts) {
+    let best = facts[0];
+    for (let i = 1; i < facts.length; i++) {
+        const f = facts[i];
+        if (f.decayScore > best.decayScore ||
+            (f.decayScore === best.decayScore && f.createdAt > best.createdAt) ||
+            (f.decayScore === best.decayScore && f.createdAt === best.createdAt && f.text.length > best.text.length)) {
+            best = f;
+        }
+    }
+    return best;
+}