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

package/fs-helpers.ts

@@ -344,6 +344,191 @@ export function cleanupInstallStagingDirs(
   return removed;
 }
 
+// ---------------------------------------------------------------------------
+// Partial-install detection (rc.22 finding #5)
+// ---------------------------------------------------------------------------
+
+/**
+ * Marker filename written into the plugin directory at register-time. Its
+ * presence means a prior install was interrupted before the plugin successfully
+ * loaded — a confirmed-broken half-state that the next `openclaw plugins
+ * install` retry can detect and clean.
+ *
+ * Conceptually the marker is dropped BEFORE npm install completes (the
+ * complementary npm script removes it on success) and additionally
+ * re-asserted at register-time as a second-line check. If you see this file
+ * in `<extensionsDir>/totalreclaw/`, the install never reached register()
+ * AND the marker drop wasn't undone.
+ *
+ * Constants are exported so the npm preinstall/cleanup scripts in
+ * `package.json` use the same name as the runtime detector.
+ */
+export const PARTIAL_INSTALL_MARKER = '.tr-partial-install';
+
+/** Package name we own — used to confirm a directory is OUR plugin, not a stray. */
+export const PLUGIN_PACKAGE_NAME = '@totalreclaw/totalreclaw';
+
+/**
+ * Outcome of `detectPartialInstall`.
+ *  - `'clean'`  — the dir is a fully-installed plugin (package.json claims our
+ *                 name AND `dist/index.js` exists AND no marker present).
+ *  - `'partial'` — the dir is OUR plugin but in a corrupt half-state. Caller
+ *                  should wipe + retry. Returned reasons include:
+ *                    * marker file present (preinstall fired, postinstall did not)
+ *                    * dist/index.js missing (build never finished)
+ *  - `'foreign'` — package.json missing or claims a different name. Helper
+ *                  refuses to act so we never delete an unrelated plugin.
+ *  - `'absent'`  — dir does not exist at all.
+ */
+export type PartialInstallStatus = 'clean' | 'partial' | 'foreign' | 'absent';
+
+export interface PartialInstallResult {
+  status: PartialInstallStatus;
+  /** Why the caller decided this is partial — surfaces in error messages. */
+  reasons: string[];
+}
+
+/**
+ * Inspect a plugin install directory to decide whether it is fully installed,
+ * a corrupted half-state from an interrupted install, or someone else's
+ * plugin. Pure filesystem inspection; never deletes anything.
+ *
+ * Background — rc.22 finding #5
+ * ------------------------------
+ * After a partial `openclaw plugins install @totalreclaw/totalreclaw` (e.g.
+ * the auto-gateway-restart kills npm mid-build), `extensions/totalreclaw/`
+ * survives with a populated package.json but a missing or empty `dist/`. The
+ * agent's recovery retry then fires another install; OpenClaw's plugin
+ * loader scans `extensions/` and tries to register the half-state as a "hook
+ * pack", failing with the cryptic "package.json missing openclaw.hooks". The
+ * fix: detect the partial state up-front so the retry can wipe + reinstall
+ * instead of cargo-culting a confused error.
+ *
+ * Decision rules
+ * --------------
+ *   1. `pluginRootDir` does not exist → `'absent'`.
+ *   2. package.json missing or unparsable → `'foreign'` (don't touch).
+ *   3. package.json `name !== '@totalreclaw/totalreclaw'` → `'foreign'`.
+ *   4. `<root>/.tr-partial-install` exists → `'partial'` (the canonical signal).
+ *   5. `<root>/dist/index.js` missing → `'partial'` (build never finished).
+ *   6. otherwise → `'clean'`.
+ *
+ * The function is intentionally conservative: it returns `'foreign'` on any
+ * ambiguous read. Callers should NEVER auto-wipe a `'foreign'` directory.
+ *
+ * @param pluginRootDir Absolute path to the suspect plugin dir, e.g.
+ *                      `~/.openclaw/extensions/totalreclaw`.
+ */
+export function detectPartialInstall(pluginRootDir: string): PartialInstallResult {
+  const reasons: string[] = [];
+
+  // Rule 1 — absent dir.
+  let rootStat: fs.Stats;
+  try {
+    rootStat = fs.statSync(pluginRootDir);
+  } catch {
+    return { status: 'absent', reasons: ['directory does not exist'] };
+  }
+  if (!rootStat.isDirectory()) {
+    return { status: 'foreign', reasons: ['path exists but is not a directory'] };
+  }
+
+  // Rules 2-3 — package.json must claim our name.
+  const pkgJsonPath = path.join(pluginRootDir, 'package.json');
+  let pkgRaw: string;
+  try {
+    pkgRaw = fs.readFileSync(pkgJsonPath, 'utf-8');
+  } catch {
+    return { status: 'foreign', reasons: ['package.json missing or unreadable'] };
+  }
+  let parsed: { name?: unknown };
+  try {
+    parsed = JSON.parse(pkgRaw) as { name?: unknown };
+  } catch {
+    return { status: 'foreign', reasons: ['package.json is not valid JSON'] };
+  }
+  if (parsed.name !== PLUGIN_PACKAGE_NAME) {
+    return {
+      status: 'foreign',
+      reasons: [`package.json declares "${String(parsed.name)}" not "${PLUGIN_PACKAGE_NAME}"`],
+    };
+  }
+
+  // Rule 4 — explicit partial marker wins.
+  const markerPath = path.join(pluginRootDir, PARTIAL_INSTALL_MARKER);
+  if (fs.existsSync(markerPath)) {
+    reasons.push(`${PARTIAL_INSTALL_MARKER} marker present (preinstall fired, postinstall did not)`);
+  }
+
+  // Rule 5 — dist/index.js must exist for the loader to register.
+  const distIndex = path.join(pluginRootDir, 'dist', 'index.js');
+  if (!fs.existsSync(distIndex)) {
+    reasons.push('dist/index.js missing (build artifact absent)');
+  }
+
+  if (reasons.length > 0) {
+    return { status: 'partial', reasons };
+  }
+  return { status: 'clean', reasons: [] };
+}
+
+/**
+ * Wipe a partial-install directory so the next `openclaw plugins install`
+ * starts from a blank slate. Only acts when `detectPartialInstall(...)`
+ * returns `'partial'` — `'foreign'` and `'clean'` are no-ops by design.
+ *
+ * Returns `true` if the directory was wiped, `false` otherwise.
+ *
+ * SAFETY: this helper is the only place that recursively deletes a plugin
+ * dir. It refuses to act on `'foreign'` and `'clean'` results so a
+ * misconfigured caller can never wipe a healthy install or someone else's
+ * plugin.
+ */
+export function wipePartialInstall(pluginRootDir: string): boolean {
+  const detection = detectPartialInstall(pluginRootDir);
+  if (detection.status !== 'partial') return false;
+  try {
+    fs.rmSync(pluginRootDir, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Drop the `.tr-partial-install` marker into `pluginRootDir`. Idempotent
+ * (overwrites any existing marker) and best-effort — returns `true` on
+ * success, `false` if the dir doesn't exist or write fails. Used by the
+ * `preinstall` npm script and (defensively) by the runtime if the npm
+ * preinstall/cleanup script pair did not fire.
+ */
+export function writePartialInstallMarker(pluginRootDir: string): boolean {
+  try {
+    if (!fs.existsSync(pluginRootDir)) return false;
+    fs.writeFileSync(path.join(pluginRootDir, PARTIAL_INSTALL_MARKER), '');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove the partial-install marker. Called by the `postinstall` script and
+ * (defensively) at register-time once we've confirmed the load succeeded.
+ * Returns `true` if a marker was removed, `false` if there was nothing to
+ * remove.
+ */
+export function clearPartialInstallMarker(pluginRootDir: string): boolean {
+  try {
+    const markerPath = path.join(pluginRootDir, PARTIAL_INSTALL_MARKER);
+    if (!fs.existsSync(markerPath)) return false;
+    fs.unlinkSync(markerPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Auto-bootstrap of credentials.json (3.1.0 first-run UX)
 // ---------------------------------------------------------------------------

package/index.ts

@@ -73,14 +73,22 @@ import {
   type MemorySource,
   type MemoryScope,
 } from './extractor.js';
-import { initLLMClient, resolveLLMConfig, chatCompletion, generateEmbedding, getEmbeddingDims } from './llm-client.js';
+import {
+  initLLMClient,
+  resolveLLMConfig,
+  chatCompletion,
+  generateEmbedding,
+  getEmbeddingDims,
+  getEmbeddingModelId,
+  configureEmbedder,
+} from './llm-client.js';
 import {
   defaultAuthProfilesRoot,
   readAllProfileKeys,
   dedupeByProvider,
 } from './llm-profile-reader.js';
 import { LSHHasher } from './lsh.js';
-import { rerank, cosineSimilarity, detectQueryIntent, INTENT_WEIGHTS, passesRelevanceGate, type RerankerCandidate } from './reranker.js';
+import { rerank, cosineSimilarity, detectQueryIntent, INTENT_WEIGHTS, type RerankerCandidate } from './reranker.js';
 import { deduplicateBatch } from './semantic-dedup.js';
 import {
   findNearDuplicate,
@@ -92,6 +100,7 @@ import {
   type DecryptedCandidate,
 } from './consolidation.js';
 import { isSubgraphMode, getSubgraphConfig, encodeFactProtobuf, submitFactOnChain, submitFactBatchOnChain, deriveSmartAccountAddress, PROTOBUF_VERSION_V4, type FactPayload } from './subgraph-store.js';
+import { confirmIndexed } from './confirm-indexed.js';
 import {
   DIGEST_TRAPDOOR,
   buildCanonicalClaim,
@@ -153,6 +162,8 @@ import {
   writeOnboardingState,
   readPluginVersion,
   cleanupInstallStagingDirs,
+  detectPartialInstall,
+  clearPartialInstallMarker,
   type OnboardingState,
 } from './fs-helpers.js';
 import { isRcBuild } from './qa-bug-report.js';
@@ -1946,6 +1957,11 @@ async function storeExtractedFacts(
         fact: factForBlob,
         importance: effectiveImportance,
         sourceAgent: factSource,
+        // 3.3.1-rc.22 — tag every new claim with the active embedder id
+        // so future distillation can rescore selectively. Plugin-only
+        // field; survives the core validator strip via re-attach in
+        // `buildCanonicalClaimV1`.
+        embeddingModelId: getEmbeddingModelId(),
       });
 
       const factId = crypto.randomUUID();
@@ -2888,6 +2904,49 @@ const plugin = {
         // Best-effort — already swallowed inside the helper, but keep this
         // outer try as belt-and-braces against future helper changes.
       }
+
+      // 3.3.1-rc.22 — wire the lazy-embedder runtime config so the first
+      // `generateEmbedding()` call knows where to cache the bundle and
+      // which RC's GitHub Release to fetch from. `pluginVersion` may be
+      // `null` if package.json is unreadable; the embedder defaults to
+      // a "0.0.0-dev" tag in that case.
+      try {
+        configureEmbedder({
+          cacheRoot: CONFIG.embedderCachePath,
+          rcTag: pluginVersion ?? '0.0.0-dev',
+        });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        api.logger.warn(`TotalReclaw: configureEmbedder failed (will use defaults): ${msg}`);
+      }
+
+      // 3.3.1-rc.22 (rc.21 finding #5): self-heal partial-install marker.
+      // The `preinstall` npm script writes `.tr-partial-install`; the
+      // `postinstall` script removes it on a successful install. If we
+      // have gotten this far the loader did register us — meaning the
+      // install succeeded enough to be useful — so any lingering marker
+      // (e.g. npm ran preinstall but postinstall misfired) is stale.
+      // Clear it so the next retry's detector does not see a false positive.
+      //
+      // 3.3.1-rc.22 (rc.21 finding #6) — gateway/reload upstream caveat:
+      // OpenClaw's config-watcher fires `gateway/reload` when
+      // `plugins.entries.totalreclaw` mutates (e.g. mid-install). In-flight
+      // CLI clients see `1006 abnormal closure` and start a 600-second wait.
+      // Proper fix is upstream OpenClaw FR. Plugin-side mitigation = these
+      // helper calls MUST be idempotent under repeated register() calls
+      // triggered by reload chatter. Asserted by
+      // `install-reload-idempotency.test.ts`.
+      try {
+        const pluginRoot = nodePath.resolve(pluginDir, '..');
+        const cleared = clearPartialInstallMarker(pluginRoot);
+        if (cleared) {
+          api.logger.info(
+            `TotalReclaw: cleared stale .tr-partial-install marker (rc.22 finding #5)`,
+          );
+        }
+      } catch {
+        // Best-effort. Helper logs internally and never throws.
+      }
     } catch {
       rcMode = false;
     }
@@ -3622,25 +3681,10 @@ const plugin = {
               };
             }
 
-            // 6b. Relevance gate — surface results when EITHER the top match
-            //     clears the cosine threshold OR every meaningful query token
-            //     appears in the top result's text (lexical override).
-            //     Issue #116 (rc.18 finding F1): short queries like
-            //     "favorite color" produce embeddings with low cosine sim
-            //     against the local Harrier-OSS-270m model even when the
-            //     stored fact text contains every query token.
-            if (!passesRelevanceGate(params.query, reranked, COSINE_THRESHOLD)) {
-              const maxCosine = Math.max(
-                ...reranked.map((r) => r.cosineSimilarity ?? 0),
-              );
-              api.logger.info(
-                `Recall: relevance gate filtered results (max cosine=${maxCosine.toFixed(3)}, threshold=${COSINE_THRESHOLD}, no lexical override)`,
-              );
-              return {
-                content: [{ type: 'text', text: 'No relevant memories found for this query.' }],
-                details: { count: 0, memories: [] },
-              };
-            }
+            // 6b. Relevance gate removed in rc.22 -- core's intent-weighted
+            //     RRF + Tier 1 source weighting handles short queries via the
+            //     BM25 component, making the rc.18 cosine + lexical-override
+            //     band-aid (issue #116) redundant.
 
             // 7. Format results.
             const lines = reranked.map((m, i) => {
@@ -3779,14 +3823,29 @@ const plugin = {
                 throw new Error(`On-chain tombstone failed (tx=${result.txHash?.slice(0, 10) || 'none'}…)`);
               }
               api.logger.info(`Tombstone written for ${factId}: tx=${result.txHash}`);
+              // Read-after-write: poll the subgraph until the original fact id
+              // is no longer active (forget flips isActive=false). On timeout
+              // surface `partial: true` so the agent can explain the chain
+              // write succeeded but the subgraph is still propagating.
+              const confirm = await confirmIndexed(factId, {
+                expect: 'inactive',
+                authKeyHex: authKeyHex!,
+              });
               return {
                 content: [{
                   type: 'text',
-                  text:
-                    `Memory ${factId} deleted on-chain (tx: ${result.txHash}). ` +
-                    'The subgraph will reflect isActive=false within ~30 seconds.',
+                  text: confirm.indexed
+                    ? `Memory ${factId} deleted on-chain and confirmed by the subgraph (tx: ${result.txHash}).`
+                    : `Memory ${factId} deleted on-chain (tx: ${result.txHash}). ` +
+                      'The subgraph indexer is still propagating the change — ' +
+                      'recall/export may briefly show the memory as still active.',
                 }],
-                details: { deleted: true, txHash: result.txHash, factId },
+                details: {
+                  deleted: true,
+                  txHash: result.txHash,
+                  factId,
+                  ...(confirm.indexed ? {} : { partial: true }),
+                },
               };
             } else {
               await apiClient!.deleteFact(factId, authKeyHex!);
@@ -5872,17 +5931,7 @@ const plugin = {
 
             if (reranked.length === 0) return undefined;
 
-            // 6b. Relevance gate — see recall tool above for the cosine +
-            //     lexical-override rule (issue #116).
-            if (!passesRelevanceGate(evt.prompt, reranked, COSINE_THRESHOLD)) {
-              const hookMaxCosine = Math.max(
-                ...reranked.map((r) => r.cosineSimilarity ?? 0),
-              );
-              api.logger.info(
-                `Hook: relevance gate filtered results (max cosine=${hookMaxCosine.toFixed(3)}, threshold=${COSINE_THRESHOLD}, no lexical override)`,
-              );
-              return undefined;
-            }
+            // Relevance gate removed in rc.22 (see recall tool comment).
 
             // 7. Build context string.
             const lines = reranked.map((m, i) => {
@@ -5987,17 +6036,7 @@ const plugin = {
 
           if (reranked.length === 0) return undefined;
 
-          // Relevance gate — see recall tool for the cosine + lexical-override
-          // rule (issue #116).
-          if (!passesRelevanceGate(evt.prompt, reranked, COSINE_THRESHOLD)) {
-            const srvMaxCosine = Math.max(
-              ...reranked.map((r) => r.cosineSimilarity ?? 0),
-            );
-            api.logger.info(
-              `Hook: relevance gate filtered results (max cosine=${srvMaxCosine.toFixed(3)}, threshold=${COSINE_THRESHOLD}, no lexical override)`,
-            );
-            return undefined;
-          }
+          // Relevance gate removed in rc.22 (see recall tool comment).
 
           // 7. Build context string.
           const lines = reranked.map((m, i) => {

package/llm-client.ts

@@ -908,6 +908,7 @@ async function chatCompletionAnthropic(
 // ---------------------------------------------------------------------------
 
 // Embeddings are now generated locally via @huggingface/transformers
-// (Harrier-OSS-v1-270M ONNX model). No API key needed.
-// See embedding.ts for implementation details.
-export { generateEmbedding, getEmbeddingDims } from './embedding.js';
+// (Harrier-OSS-v1-270M ONNX model). No API key needed. The native deps +
+// model are lazy-fetched from a pinned GitHub Release on first call —
+// see embedding.ts + embedder-loader.ts.
+export { generateEmbedding, getEmbeddingDims, getEmbeddingModelId, configureEmbedder } from './embedding.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.1-rc.21",
+  "version": "3.3.1-rc.22",
   "description": "End-to-end encrypted, agent-portable memory for OpenClaw and any LLM-agent runtime. XChaCha20-Poly1305 with protobuf v4 + on-chain Memory Taxonomy v1 (claim / preference / directive / commitment / episode / summary).",
   "type": "module",
   "keywords": [
@@ -31,17 +31,18 @@
   "author": "TotalReclaw Team",
   "license": "MIT",
   "dependencies": {
-    "@huggingface/transformers": "^4.0.1",
     "@totalreclaw/client": "^1.2.0",
     "@totalreclaw/core": "^2.1.1",
     "@types/qrcode": "^1.5.6",
     "@types/ws": "^8.5.12",
-    "onnxruntime-node": "^1.24.0",
     "qrcode": "^1.5.4",
     "qrcode-terminal": "^0.12.0",
     "ws": "^8.18.3"
   },
+  "//": "@huggingface/transformers + onnxruntime-node deliberately omitted from runtime deps. They are heavy native bundles (~700 MB peak install RAM) that OOM-killed the OpenClaw gateway on small VPS during `openclaw plugins install` in rc.21 (issue: 3.7 GB Hetzner host). rc.22 ships them via a lazy GitHub-Releases bundle (`embedder-v1.tar.gz`) downloaded on first call to embed(). See `embedder-network.ts` + `scripts/build-embedder-bundle.mjs`. The dev-deps below are for type-checking + bundle generation only; npm install of the plugin tarball never installs them.",
   "devDependencies": {
+    "@huggingface/transformers": "^4.0.1",
+    "onnxruntime-node": "^1.24.0",
     "typescript": "^5.5.0"
   },
   "main": "./dist/index.js",
@@ -62,11 +63,15 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json --noCheck",
     "verify-tarball": "node ../scripts/verify-tarball.mjs",
-    "test": "npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx config.test.ts && npx tsx relay-headers.test.ts && npx tsx scope-address-visible.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx gateway-url.test.ts && npx tsx retype-setscope.test.ts && npx tsx tool-gating.test.ts && npx tsx onboarding-noninteractive.test.ts && npx tsx pair-cli-json.test.ts && npx tsx pair-qr.test.ts && npx tsx pair-remote-client.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx phrase-safety-registry.test.ts && npx tsx test_issue_92_onnx_download_ux.test.ts && npx tsx onboard-pair-only.test.ts && npx tsx import-time-smoke.test.ts && npx tsx recall-relevance-gate.test.ts && npx tsx install-staging-cleanup.test.ts && npx tsx json-stdout-cleanliness.test.ts",
+    "test": "npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx config.test.ts && npx tsx relay-headers.test.ts && npx tsx scope-address-visible.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx gateway-url.test.ts && npx tsx retype-setscope.test.ts && npx tsx tool-gating.test.ts && npx tsx onboarding-noninteractive.test.ts && npx tsx pair-cli-json.test.ts && npx tsx pair-qr.test.ts && npx tsx pair-remote-client.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx phrase-safety-registry.test.ts && npx tsx test_issue_92_onnx_download_ux.test.ts && npx tsx onboard-pair-only.test.ts && npx tsx import-time-smoke.test.ts && npx tsx install-staging-cleanup.test.ts && npx tsx partial-install-detection.test.ts && npx tsx install-reload-idempotency.test.ts && npx tsx json-stdout-cleanliness.test.ts",
     "smoke:dist": "npx tsx dist-esm-smoke.test.ts",
     "check-scanner": "node ../scripts/check-scanner.mjs",
+    "check-version-drift": "node ../scripts/check-version-drift.mjs",
+    "sync-version": "node ../scripts/sync-version.mjs",
+    "preinstall": "node -e \"try{require('fs').writeFileSync('.tr-partial-install','');}catch{}\"",
+    "postinstall": "node -e \"try{require('fs').unlinkSync('.tr-partial-install');}catch{}\"",
     "prepack": "npm run build",
-    "prepublishOnly": "node ../scripts/check-scanner.mjs"
+    "prepublishOnly": "node ../scripts/check-scanner.mjs && node ../scripts/check-version-drift.mjs"
   },
   "openclaw": {
     "extensions": [

package/pin.ts

@@ -26,6 +26,7 @@ import { isValidMemoryType, V0_TO_V1_TYPE } from './extractor.js';
 import type { MemoryType, MemorySource, MemoryScope, MemoryVolatility } from './extractor.js';
 import { PROTOBUF_VERSION_V4 } from './subgraph-store.js';
 import type { SubgraphSearchFact } from './subgraph-search.js';
+import { confirmIndexed, type ConfirmIndexedOptions } from './confirm-indexed.js';
 
 // Lazy-load WASM core (mirrors claims-helper.ts pattern — plays nicely under
 // both the OpenClaw runtime (CJS-ish tsx) and bare Node ESM used by tests).
@@ -114,6 +115,12 @@ export interface V1PinBlob {
   id?: string;
   /** Previously-stored pin_status on the blob (v1.1). */
   pinStatus?: PinStatus;
+  /**
+   * 3.3.1-rc.22 — preserved when round-tripping a v1 blob through pin
+   * mutation. We keep the SOURCE blob's tag so distillation backfill
+   * never loses track of which embedder produced the original vector.
+   */
+  embeddingModelId?: string;
 }
 
 /** Shape of a v0 (short-key) blob or a legacy {text, metadata} blob. */
@@ -186,6 +193,7 @@ export function parseBlobForPin(decrypted: string): ParsedBlob {
           expiresAt: v1.expiresAt,
           id: v1.id,
           pinStatus: v1.pinStatus,
+          embeddingModelId: v1.embeddingModelId,
         },
         claim: shortProjection,
         currentStatus: human,
@@ -314,6 +322,8 @@ interface V1Projection {
   entities?: Array<{ name: string; type: string; role?: string }>;
   importance: number;
   confidence: number;
+  /** 3.3.1-rc.22 — carried through pin/retype rewrites for forward-compat. */
+  embeddingModelId?: string;
 }
 
 /**
@@ -336,6 +346,7 @@ function projectToV1(src: V1PinBlob | V0PinBlob, defaultSourceAgent: string): V1
       entities: src.entities,
       importance: src.importance,
       confidence: src.confidence,
+      embeddingModelId: src.embeddingModelId,
     };
   }
 
@@ -445,6 +456,14 @@ export interface PinOpResult {
   tx_hash?: string;
   reason?: string;
   error?: string;
+  /**
+   * On-chain batch submitted but subgraph indexer did not confirm the new
+   * fact id within the timeout window (default 30s). The pin/unpin IS
+   * on-chain — `tx_hash` is observable on the explorer — but a follow-up
+   * `recall`/`export` may briefly surface stale state. Resolves once the
+   * indexer catches up. See `confirm-indexed.ts`.
+   */
+  partial?: boolean;
 }
 
 /**
@@ -461,6 +480,7 @@ export async function executePinOperation(
   targetStatus: 'pinned' | 'active',
   deps: PinOpDeps,
   reason?: string,
+  confirmOpts?: ConfirmIndexedOptions,
 ): Promise<PinOpResult> {
   // 1. Fetch the existing fact
   const existing = await deps.fetchFactById(factId);
@@ -570,6 +590,11 @@ export async function executePinOperation(
       createdAt: new Date().toISOString(),
       supersededBy: factId,
       pinStatus,
+      // 3.3.1-rc.22 — preserve the source claim's embedder tag through
+      // pin mutation. The new fact reuses the same encrypted embedding
+      // as the original (re-indexed via deps.regenerateBlindIndices),
+      // so the embedder identity must round-trip too.
+      embeddingModelId: v1View.embeddingModelId,
     });
   } catch (err) {
     return {
@@ -672,6 +697,11 @@ export async function executePinOperation(
         tx_hash: txHash,
       };
     }
+    // Read-after-write: poll the subgraph until the new (pinned/unpinned)
+    // fact id is indexed and active. On timeout, surface `partial: true`
+    // so a follow-up recall/export that races against indexer lag can
+    // surface a clear "still propagating" hint rather than apparent staleness.
+    const confirm = await confirmIndexed(newFactId, confirmOpts);
     return {
       success: true,
       fact_id: factId,
@@ -680,6 +710,7 @@ export async function executePinOperation(
       new_status: targetStatus,
       tx_hash: txHash,
       reason,
+      ...(confirm.indexed ? {} : { partial: true }),
     };
   } catch (err) {
     return {

package/reranker.ts

@@ -509,74 +509,41 @@ export function rerank(
 }
 
 // ---------------------------------------------------------------------------
-// Relevance gate (issue #116)
+// Relevance gate
 // ---------------------------------------------------------------------------
 
 /**
  * Decide whether reranked results clear the relevance gate for surfacing to
  * the user (recall tool) or auto-injecting into agent context (hooks).
  *
- * Two-signal acceptance rule, addressing issue #116 (rc.18 finding F1):
+ * Plain cosine cut-off: at least one reranked result has cosine similarity
+ * with the query embedding >= `cosineThreshold`.
  *
- *   1. **Cosine path** — at least one reranked result has cosine similarity
- *      with the query embedding >= `cosineThreshold`. This is the existing
- *      semantic-relevance gate and remains the primary signal.
+ * History (rc.18 → rc.22):
+ *   rc.18 issue #116 surfaced as a recall miss for short queries against
+ *   the local Harrier-OSS-270m model — cosine alone produced false-negatives
+ *   even when every query token literally appeared in the candidate. rc.18
+ *   shipped a defensive "lexical-override" fallback (every meaningful query
+ *   token had to appear as a 4-char-prefix substring in the top result).
+ *   The override was always intended as a band-aid until the
+ *   source-weighted reranker hoisted from `totalreclaw-core` produced
+ *   honest cosine signals for short queries. rc.22 hoists that reranker
+ *   and drops the band-aid: the gate is now back to a single-signal cosine
+ *   cut-off, matching Hermes (Python client) and the canonical reranker
+ *   spec.
  *
- *   2. **Lexical override** — when cosine is below threshold (e.g. short
- *      queries against the local Harrier-OSS-270m model produce embeddings
- *      with low cosine sim regardless of topical match), the gate ALSO
- *      passes when every meaningful query token (post stop-word removal)
- *      appears as a stem-prefix substring in the top reranked result's
- *      text. This is strong lexical evidence that the user is asking
- *      about a fact already stored, even when embedding sim is weak.
- *
- * Without (2), short queries like `"favorite color"` against the stored
- * fact `"User's favorite color is cobalt blue"` were silently filtered
- * even though every query token was present in the candidate. Hermes
- * (Python client) does not apply any cosine gate, which is why it
- * recalled the same fact for the same Smart Account in rc.18 QA.
- *
- * The lexical override is intentionally conservative:
- *   - Requires ALL non-stop-word query tokens to be present (any-of would
- *     over-trigger).
- *   - Uses 4-char-prefix substring match to be stem-tolerant ("favorite"
- *     stems to "favorit" in the stored fact's blind index, but the raw
- *     fact text contains the unstemmed word; the prefix check absorbs
- *     light morphology).
- *   - Token count must be >= 1 — empty/all-stop-word queries fall back
- *     to cosine path.
- *
- * @param query - the user's search query (raw string)
+ * @param query - the user's search query (raw string) — accepted for ABI
+ *   stability, no longer consulted post rc.22.
  * @param reranked - reranked results (top first)
  * @param cosineThreshold - the configured cosine cutoff (typically 0.15)
  * @returns true if results should be surfaced; false to suppress
  */
 export function passesRelevanceGate(
-  query: string,
+  _query: string,
   reranked: RerankerResult[],
   cosineThreshold: number,
 ): boolean {
   if (reranked.length === 0) return false;
-
-  // Path 1: cosine clears threshold.
   const maxCosine = Math.max(...reranked.map((r) => r.cosineSimilarity ?? 0));
-  if (maxCosine >= cosineThreshold) return true;
-
-  // Path 2: lexical override — every meaningful query token appears in
-  // the top reranked result's text.
-  const queryTokens = tokenize(query, /* removeStopWords */ true);
-  if (queryTokens.length === 0) return false;
-
-  const topText = (reranked[0]?.text ?? '').toLowerCase();
-  if (topText.length === 0) return false;
-
-  // 4-char prefix substring match: tolerates light stemming ("favorite"
-  // matches a fact text containing "favorite", "favorites", "favoring",
-  // etc., without re-running the WASM Porter stemmer client-side).
-  const PREFIX_LEN = 4;
-  for (const token of queryTokens) {
-    const probe = token.length >= PREFIX_LEN ? token.slice(0, PREFIX_LEN) : token;
-    if (!topText.includes(probe)) return false;
-  }
-  return true;
+  return maxCosine >= cosineThreshold;
 }