@totalreclaw/totalreclaw 3.3.1-rc.9 → 3.3.1

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/qa-bug-report.ts

@@ -18,6 +18,13 @@
  * POST. BIP-39 phrases, API keys, Telegram bot tokens, and bearer tokens
  * in headers all become `<REDACTED>` in the posted issue. Refer to
  * `redactSecrets()` for the exact rule set.
+ *
+ * Target repo safety: the default target is `p-diogo/totalreclaw-internal`.
+ * Operators can override via the `TOTALRECLAW_QA_REPO` env var, but only
+ * to another slug ending in `-internal`. Any other slug — including the
+ * public `p-diogo/totalreclaw` — is rejected with a loud error. rc.13 QA
+ * surfaced a repo-slug drift where QA findings leaked to the public
+ * tracker; rc.14 adds this fail-loud guard.
  */
 
 // ---------------------------------------------------------------------------
@@ -148,7 +155,12 @@ export interface QaBugArgs {
 export interface QaBugDeps {
   /** GitHub personal-access token with `repo` scope. */
   githubToken: string;
-  /** Repo to post to. Defaults to `p-diogo/totalreclaw-internal`. */
+  /**
+   * Repo to post to. Defaults to `resolveQaRepo(null)` → reads
+   * `TOTALRECLAW_QA_REPO` env var and falls back to
+   * `p-diogo/totalreclaw-internal`. Pass a slug (tests only) to
+   * bypass env-var lookup.
+   */
   repo?: string;
   /**
    * Abstract fetch for testing — defaults to global `fetch`. Intentionally
@@ -160,6 +172,76 @@ export interface QaBugDeps {
   logger?: { info: (msg: string) => void; warn: (msg: string) => void };
 }
 
+// ---------------------------------------------------------------------------
+// Target repo guard — fail-loud on any repo that isn't the internal tracker.
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_QA_REPO = 'p-diogo/totalreclaw-internal';
+
+/**
+ * Known-public repo slugs that must never receive QA bug reports. The
+ * structural rule (`endsWith('-internal')`) below should already block
+ * these, but the explicit denylist is a belt-and-braces safety against
+ * a future rename that accidentally drops the `-internal` suffix.
+ */
+export const PUBLIC_REPOS_DENYLIST: ReadonlySet<string> = new Set([
+  'p-diogo/totalreclaw',
+  'p-diogo/totalreclaw-website',
+  'p-diogo/totalreclaw-relay',
+  'p-diogo/totalreclaw-plugin',
+  'p-diogo/totalreclaw-hermes',
+]);
+
+/**
+ * Resolve the target repo for a QA bug filing.
+ *
+ * Precedence: explicit override → `TOTALRECLAW_QA_REPO` env → default.
+ * Throws if the slug is on the public denylist or does not end in
+ * `-internal`. rc.13 QA found agent-filed bug reports leaking to the
+ * public repo; this guard makes any such drift fail loudly rather than
+ * silently leak RC ship-stopper detail.
+ *
+ * `TOTALRECLAW_QA_REPO` is the documented override var. The env-var
+ * read lives in `config.ts` (CONFIG.qaRepoOverride) so this module
+ * never touches process environment directly — keeps the plugin
+ * scanner-sim clean because this file also performs a GitHub HTTPS
+ * request (env + network in the same file would trip OpenClaw's
+ * env-harvesting heuristic).
+ *
+ * Pass the env-resolved slug (or `null`/empty for default) as
+ * `override`. Tests can inject via the second arg.
+ */
+export function resolveQaRepo(
+  override?: string | null,
+  env?: Record<string, string | undefined>,
+): string {
+  // `env` is only for test injection — production callers should
+  // pre-resolve the env value via CONFIG.qaRepoOverride and pass it as
+  // `override`. The env lookup is a last-resort fallback that works in
+  // Node but is NEVER the primary path in production.
+  const envOverride = env ? env.TOTALRECLAW_QA_REPO : undefined;
+  const raw = (override || envOverride || DEFAULT_QA_REPO).trim();
+  if (!raw || !raw.includes('/')) {
+    throw new Error(`invalid QA repo slug '${raw}': expected 'owner/name' format`);
+  }
+  if (PUBLIC_REPOS_DENYLIST.has(raw)) {
+    throw new Error(
+      `refusing to file QA bug to PUBLIC repo '${raw}'. ` +
+        'QA bug reports contain RC ship-stopper detail that must not ' +
+        "leak to public. Set TOTALRECLAW_QA_REPO to a repo ending in " +
+        "'-internal' (e.g. p-diogo/totalreclaw-internal).",
+    );
+  }
+  if (!raw.endsWith('-internal')) {
+    throw new Error(
+      `refusing to file QA bug to repo '${raw}': slug must end in ` +
+        "'-internal' (structural safety rule). Override via " +
+        'TOTALRECLAW_QA_REPO only to another internal fork.',
+    );
+  }
+  return raw;
+}
+
 const VALID_INTEGRATIONS = new Set([
   'plugin',
   'hermes',
@@ -260,7 +342,7 @@ export async function postQaBugIssue(
   if ('error' in validation) throw new Error(`invalid args: ${validation.error}`);
   if (!deps.githubToken) throw new Error('githubToken is required');
 
-  const repo = deps.repo ?? 'p-diogo/totalreclaw-internal';
+  const repo = resolveQaRepo(deps.repo ?? null);
   const url = `https://api.github.com/repos/${repo}/issues`;
 
   const title = `[qa-bug] ${redactSecrets(args.title)}`;

package/relay-headers.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared outbound-header helper for relay calls.
+ *
+ * Centralizes the common `X-TotalReclaw-*` headers so every fetch site
+ * consistently tags requests with:
+ *   - `X-TotalReclaw-Client`  — caller identity (defaults to `openclaw-plugin`).
+ *   - `X-TotalReclaw-Session` — optional QA / observability tag from
+ *     `TOTALRECLAW_SESSION_ID`. Used by Axiom log filters and the
+ *     `qa-totalreclaw` skill to scope log searches per QA run.
+ *
+ * Pure function — no I/O, no network. Reads `getSessionId()` (which reads the
+ * env var via getter so harnesses that flip the env between calls pick up
+ * the new value).
+ *
+ * The session-id env var was accidentally placed in the v1 REMOVED_ENV_VARS
+ * list and silently warned-and-dropped, breaking Axiom traceability for QA
+ * runs (see internal#127). This helper is the canonical re-entry point for
+ * the variable.
+ */
+
+import { getSessionId } from './config.js';
+
+/** Default `X-TotalReclaw-Client` value. */
+export const DEFAULT_CLIENT_ID = 'openclaw-plugin';
+
+/**
+ * Build the standard outbound header set.
+ *
+ * @param overrides - merge-in additional headers (`Authorization`,
+ *   `Content-Type`, etc.); these win over the defaults.
+ * @param clientId - override the `X-TotalReclaw-Client` value.
+ *
+ * Always includes `X-TotalReclaw-Client`. Includes `X-TotalReclaw-Session`
+ * only when `TOTALRECLAW_SESSION_ID` is set + non-empty.
+ */
+export function buildRelayHeaders(
+  overrides: Record<string, string> = {},
+  clientId: string = DEFAULT_CLIENT_ID,
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    'X-TotalReclaw-Client': clientId,
+  };
+  const sessionId = getSessionId();
+  if (sessionId) {
+    headers['X-TotalReclaw-Session'] = sessionId;
+  }
+  // Caller-supplied headers (Authorization, Content-Type, Accept, etc.) take
+  // precedence over the defaults but should generally not stomp the X-* tags.
+  return { ...headers, ...overrides };
+}

package/reranker.ts

@@ -507,3 +507,43 @@ export function rerank(
   // Preserve rrfScore and cosineSimilarity through MMR
   return mmrResults as RerankerResult[];
 }
+
+// ---------------------------------------------------------------------------
+// Relevance gate
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide whether reranked results clear the relevance gate for surfacing to
+ * the user (recall tool) or auto-injecting into agent context (hooks).
+ *
+ * Plain cosine cut-off: at least one reranked result has cosine similarity
+ * with the query embedding >= `cosineThreshold`.
+ *
+ * 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.
+ *
+ * @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,
+  reranked: RerankerResult[],
+  cosineThreshold: number,
+): boolean {
+  if (reranked.length === 0) return false;
+  const maxCosine = Math.max(...reranked.map((r) => r.cosineSimilarity ?? 0));
+  return maxCosine >= cosineThreshold;
+}

package/retype-setscope.ts

@@ -34,6 +34,7 @@ import {
   buildV1ClaimBlob,
   mapTypeToCategory,
   readV1Blob,
+  type PinStatus,
 } from './claims-helper.js';
 import {
   isValidMemoryType,
@@ -48,6 +49,7 @@ import type {
 } 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 pin.ts pattern.
 const requireWasm = createRequire(import.meta.url);
@@ -116,6 +118,15 @@ export interface RetypeSetScopeResult {
   new_scope?: MemoryScope;
   tx_hash?: string;
   error?: string;
+  /**
+   * Set to `true` when the on-chain batch was submitted successfully but the
+   * subgraph indexer did not confirm the new fact id within the timeout
+   * window (default 30s). The mutation IS on-chain — clients can rely on
+   * `tx_hash` for observability — but a follow-up `recall`/`export` may
+   * surface stale state for another few seconds. Resolves once the indexer
+   * catches up. See `confirm-indexed.ts` for the polling implementation.
+   */
+  partial?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -135,6 +146,20 @@ interface NormalizedFact {
   confidence: number;
   createdAt: string;
   expiresAt?: string;
+  /**
+   * v1.1 pin state. Preserved across retype / set_scope so that pinned facts
+   * remain pinned after a metadata edit. Issue #117 surfaced an adjacent gap
+   * where this field was silently dropped on the rewrite path.
+   */
+  pinStatus?: PinStatus;
+  /**
+   * 3.3.1-rc.22 — embedder identity tag. Preserved across retype/set_scope
+   * so the source claim's embedder isn't lost on metadata mutation. The
+   * stored encrypted_embedding is regenerated by `deps.generateIndices`
+   * downstream; the on-claim tag survives the mutation as a forward-compat
+   * marker.
+   */
+  embeddingModelId?: string;
 }
 
 function projectFromDecrypted(decrypted: string): NormalizedFact | null {
@@ -166,6 +191,8 @@ function projectFromDecrypted(decrypted: string): NormalizedFact | null {
         confidence: v1.confidence,
         createdAt: v1.createdAt,
         expiresAt: v1.expiresAt,
+        pinStatus: v1.pinStatus,
+        embeddingModelId: v1.embeddingModelId,
       };
     }
   }
@@ -221,6 +248,7 @@ async function rewriteWithMutation(
   factId: string,
   deps: RetypeSetScopeDeps,
   mutate: (existing: NormalizedFact) => NormalizedFact,
+  confirmOpts?: ConfirmIndexedOptions,
 ): Promise<RetypeSetScopeResult> {
   const existing = await deps.fetchFactById(factId);
   if (!existing) {
@@ -267,6 +295,13 @@ async function rewriteWithMutation(
       confidence: next.confidence,
       createdAt: new Date().toISOString(),
       supersededBy: factId,
+      // Issue #117 follow-up: preserve pin_status so that retype / set_scope
+      // on a pinned fact does NOT silently un-pin it. Without this, a pinned
+      // fact loses its immunity to auto-supersede after any metadata edit.
+      pinStatus: next.pinStatus,
+      // 3.3.1-rc.22 — preserve the source claim's embedder tag through
+      // retype/set_scope rewrites. Distillation forward-compat.
+      embeddingModelId: next.embeddingModelId,
     });
   } catch (err) {
     return {
@@ -337,6 +372,19 @@ async function rewriteWithMutation(
         tx_hash: txHash,
       };
     }
+    // Read-after-write: poll the subgraph until the new fact id is indexed
+    // and active, OR the timeout (default 30s) elapses. On timeout (or if
+    // the WASM bindings are unavailable / subgraph unreachable), surface
+    // `partial: true` so the caller knows the chain write succeeded but the
+    // indexer has not yet caught up. The confirm step is observational —
+    // never fail the whole operation just because confirm step couldn't run.
+    let indexed = false;
+    try {
+      const confirm = await confirmIndexed(newFactId, confirmOpts);
+      indexed = confirm.indexed;
+    } catch {
+      indexed = false;
+    }
     return {
       success: true,
       fact_id: factId,
@@ -346,6 +394,7 @@ async function rewriteWithMutation(
       previous_scope: current.scope,
       new_scope: next.scope,
       tx_hash: txHash,
+      ...(indexed ? {} : { partial: true }),
     };
   } catch (err) {
     return {
@@ -369,6 +418,7 @@ export async function executeRetype(
   factId: string,
   newType: MemoryType,
   deps: RetypeSetScopeDeps,
+  confirmOpts?: ConfirmIndexedOptions,
 ): Promise<RetypeSetScopeResult> {
   if (!isValidMemoryType(newType)) {
     return {
@@ -377,10 +427,15 @@ export async function executeRetype(
       error: `Invalid new type "${newType}". Must be one of: claim, preference, directive, commitment, episode, summary.`,
     };
   }
-  return rewriteWithMutation(factId, deps, (current) => ({
-    ...current,
-    type: newType,
-  }));
+  return rewriteWithMutation(
+    factId,
+    deps,
+    (current) => ({
+      ...current,
+      type: newType,
+    }),
+    confirmOpts,
+  );
 }
 
 /**
@@ -391,6 +446,7 @@ export async function executeSetScope(
   factId: string,
   newScope: MemoryScope,
   deps: RetypeSetScopeDeps,
+  confirmOpts?: ConfirmIndexedOptions,
 ): Promise<RetypeSetScopeResult> {
   if (!(VALID_MEMORY_SCOPES as readonly string[]).includes(newScope)) {
     return {
@@ -399,10 +455,15 @@ export async function executeSetScope(
       error: `Invalid new scope "${newScope}". Must be one of: ${VALID_MEMORY_SCOPES.join(', ')}.`,
     };
   }
-  return rewriteWithMutation(factId, deps, (current) => ({
-    ...current,
-    scope: newScope,
-  }));
+  return rewriteWithMutation(
+    factId,
+    deps,
+    (current) => ({
+      ...current,
+      scope: newScope,
+    }),
+    confirmOpts,
+  );
 }
 
 // ---------------------------------------------------------------------------

package/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "totalreclaw",
-  "version": "1.6.2",
+  "version": "3.3.1-rc.22",
   "description": "End-to-end encrypted memory for AI agents — portable, yours forever. XChaCha20-Poly1305 E2EE: server never sees plaintext.",
   "author": "TotalReclaw Team",
   "license": "MIT",

package/subgraph-search.ts

@@ -22,6 +22,7 @@
 
 import { getSubgraphConfig } from './subgraph-store.js';
 import { CONFIG } from './config.js';
+import { buildRelayHeaders } from './relay-headers.js';
 
 export interface SubgraphSearchFact {
   id: string;
@@ -48,13 +49,13 @@ async function gqlQuery<T>(
   authKeyHex?: string,
 ): Promise<T | null> {
   try {
-    const headers: Record<string, string> = {
+    const overrides: Record<string, string> = {
       'Content-Type': 'application/json',
-      'X-TotalReclaw-Client': 'openclaw-plugin',
     };
     if (authKeyHex) {
-      headers['Authorization'] = `Bearer ${authKeyHex}`;
+      overrides['Authorization'] = `Bearer ${authKeyHex}`;
     }
+    const headers = buildRelayHeaders(overrides);
     const response = await fetch(endpoint, {
       method: 'POST',
       headers,

package/subgraph-store.ts

@@ -10,13 +10,18 @@
  * and chain RPCs. No viem, no permissionless.
  */
 
-// Lazy-load WASM to avoid crash when npm install hasn't finished yet.
+// Lazy-load WASM via createRequire — the shipped bundle is ESM-only and
+// the bare `require` global is undefined there (issue #124). Same pattern
+// as crypto / lsh / claims-helper / consolidation / digest-sync.
+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;
 }
 import { CONFIG } from './config.js';
+import { buildRelayHeaders } from './relay-headers.js';
 
 // ---------------------------------------------------------------------------
 // Pimlico 429 retry helper
@@ -383,12 +388,12 @@ async function submitFactOnChainLocked(
   sender: string,
 ): Promise<{ txHash: string; userOpHash: string; success: boolean }> {
   const bundlerUrl = `${config.relayUrl}/v1/bundler`;
-  const headers: Record<string, string> = {
+  const overrides: Record<string, string> = {
     'Content-Type': 'application/json',
-    'X-TotalReclaw-Client': 'openclaw-plugin',
   };
-  if (config.authKeyHex) headers['Authorization'] = `Bearer ${config.authKeyHex}`;
-  if (config.walletAddress) headers['X-Wallet-Address'] = config.walletAddress;
+  if (config.authKeyHex) overrides['Authorization'] = `Bearer ${config.authKeyHex}`;
+  if (config.walletAddress) overrides['X-Wallet-Address'] = config.walletAddress;
+  const headers = buildRelayHeaders(overrides);
 
   // Helper for JSON-RPC calls to relay bundler (with 429 retry)
   async function rpc(method: string, params: unknown[]): Promise<any> {
@@ -600,12 +605,12 @@ async function submitFactBatchOnChainLocked(
   sender: string,
 ): Promise<{ txHash: string; userOpHash: string; success: boolean; batchSize: number }> {
   const bundlerUrl = `${config.relayUrl}/v1/bundler`;
-  const headers: Record<string, string> = {
+  const overrides: Record<string, string> = {
     'Content-Type': 'application/json',
-    'X-TotalReclaw-Client': 'openclaw-plugin',
   };
-  if (config.authKeyHex) headers['Authorization'] = `Bearer ${config.authKeyHex}`;
-  if (config.walletAddress) headers['X-Wallet-Address'] = config.walletAddress;
+  if (config.authKeyHex) overrides['Authorization'] = `Bearer ${config.authKeyHex}`;
+  if (config.walletAddress) overrides['X-Wallet-Address'] = config.walletAddress;
+  const headers = buildRelayHeaders(overrides);
 
   // Helper for JSON-RPC calls to relay bundler (with 429 retry)
   async function rpc(method: string, params: unknown[]): Promise<any> {