@totalreclaw/totalreclaw 3.0.7-rc.1 → 3.1.0-rc.2

package/claims-helper.ts

@@ -142,6 +142,16 @@ export function buildCanonicalClaim(input: BuildClaimInput): string {
 
 export const V1_SCHEMA_VERSION = '1.0' as const;
 
+/**
+ * v1.1 pin state — `"pinned"` = user explicitly pinned (immune to
+ * auto-supersede); `"unpinned"` (or absence) = standard behavior.
+ *
+ * Surface of the `pin_status` field added in spec v1.1 (2026-04-19). Writers
+ * that understand v1.1 emit this field on the pin path; readers at 1.0 / 1.1
+ * that see it MUST honor `"pinned"` as immunity from auto-supersede.
+ */
+export type PinStatus = 'pinned' | 'unpinned';
+
 export interface BuildClaimV1Input {
   /** The extracted fact in v1 shape. Must have `type` as a MemoryTypeV1 token. */
   fact: ExtractedFact;
@@ -156,6 +166,13 @@ export interface BuildClaimV1Input {
   /** Stable claim ID. Defaults to crypto.randomUUID() at the call site; keep the
    *  same ID for both the blob and the on-chain fact id. */
   id?: string;
+  /**
+   * v1.1 pin state. When `"pinned"`, the claim is immune to auto-supersede.
+   * Omitted or `"unpinned"` both mean unpinned (field is additive — absence
+   * equivalent to `"unpinned"` on the wire). Surfaced in the final JSON only
+   * when provided.
+   */
+  pinStatus?: PinStatus;
 }
 
 /**
@@ -226,6 +243,10 @@ export function buildCanonicalClaimV1(input: BuildClaimV1Input): string {
   }
   if (expiresAt) corePayload.expires_at = expiresAt;
   if (supersededBy) corePayload.superseded_by = supersededBy;
+  // v1.1 pin_status — additive field; only emitted when the caller opts in.
+  if (input.pinStatus === 'pinned' || input.pinStatus === 'unpinned') {
+    corePayload.pin_status = input.pinStatus;
+  }
 
   // Validate through core — throws on invalid type / source / missing id.
   const validated = getWasm().validateMemoryClaimV1(JSON.stringify(corePayload)) as string;
@@ -240,6 +261,122 @@ export function buildCanonicalClaimV1(input: BuildClaimV1Input): string {
   return JSON.stringify(canonical);
 }
 
+// ---------------------------------------------------------------------------
+// buildV1ClaimBlob — lightweight v1 blob builder for pin / retype / set_scope
+//
+// Unlike buildCanonicalClaimV1 (which consumes a full ExtractedFact), this
+// helper takes raw primitives and is the right entry point when synthesizing
+// a new blob from a previously-decrypted one — e.g. the pin path rewrites the
+// blob with an updated pin_status field and everything else preserved.
+//
+// The output is a v1.1 JSON payload with schema_version "1.0" (v1.1 is
+// additive; on-wire schema_version is unchanged per spec). The outer protobuf
+// wrapper MUST be written at version 4 — see `subgraph-store.ts`.
+// ---------------------------------------------------------------------------
+
+export interface BuildV1ClaimBlobInput {
+  /** Human-readable fact text (5-512 UTF-8 chars). */
+  text: string;
+  /** v1 memory type. Must be one of the 6 canonical values. */
+  type: MemoryType;
+  /** Provenance per spec §provenance-filter. */
+  source: MemorySource;
+  /** Optional stable UUID; defaults to randomUUID(). */
+  id?: string;
+  /** Optional creation timestamp (ISO 8601 UTC); defaults to now. */
+  createdAt?: string;
+  /** Optional scope (defaults to omitted → "unspecified"). */
+  scope?: MemoryScope;
+  /** Optional volatility (defaults to omitted → "updatable"). */
+  volatility?: MemoryVolatility;
+  /** Optional reasoning clause for decision-style claims. */
+  reasoning?: string;
+  /** Optional structured entities. */
+  entities?: ExtractedEntity[];
+  /** Optional expiration timestamp. */
+  expiresAt?: string;
+  /** Optional importance (1-10, advisory). */
+  importance?: number;
+  /** Optional confidence (0-1). */
+  confidence?: number;
+  /** Optional superseded-by chain pointer. */
+  supersededBy?: string;
+  /**
+   * Optional v1.1 pin state.
+   *
+   * - `"pinned"` → user explicitly pinned; the claim MUST NOT be auto-superseded.
+   * - `"unpinned"` → explicit unpin (resets a previous pin).
+   * - Undefined/omitted → field not emitted; receivers treat as unpinned.
+   *
+   * Callers are free to pass `"unpinned"` to create an explicit un-pin
+   * supersede event, or to pass `undefined` to leave the field absent on a
+   * non-pin write.
+   */
+  pinStatus?: PinStatus;
+}
+
+/**
+ * Build a v1.1 canonical claim JSON string, validated through the core
+ * `validateMemoryClaimV1` WASM export.
+ *
+ * Output is UTF-8 JSON ready for encryption as the inner blob of a
+ * protobuf-v4 fact (outer `version = 4`). Field ordering follows the core
+ * validator, so the result is byte-identical to what MCP's equivalent helper
+ * produces for the same inputs (cross-client parity).
+ *
+ * Throws on malformed input (missing required field, invalid enum value).
+ */
+export function buildV1ClaimBlob(input: BuildV1ClaimBlobInput): string {
+  if (!(VALID_MEMORY_SOURCES as readonly string[]).includes(input.source)) {
+    throw new Error(`buildV1ClaimBlob: invalid source "${input.source}"`);
+  }
+  if (!isValidMemoryType(input.type)) {
+    throw new Error(`buildV1ClaimBlob: invalid type "${input.type}"`);
+  }
+
+  const corePayload: Record<string, unknown> = {
+    id: input.id ?? crypto.randomUUID(),
+    text: input.text,
+    type: input.type,
+    source: input.source,
+    created_at: input.createdAt ?? new Date().toISOString(),
+  };
+
+  if (input.scope && (VALID_MEMORY_SCOPES as readonly string[]).includes(input.scope)) {
+    corePayload.scope = input.scope;
+  }
+  if (input.reasoning && input.reasoning.length > 0) {
+    corePayload.reasoning = input.reasoning.slice(0, 256);
+  }
+  if (input.entities && input.entities.length > 0) {
+    corePayload.entities = input.entities.slice(0, 8).map((e) => {
+      const entity: Record<string, unknown> = { name: e.name, type: e.type };
+      if (e.role) entity.role = e.role;
+      return entity;
+    });
+  }
+  if (typeof input.importance === 'number') {
+    corePayload.importance = Math.max(1, Math.min(10, Math.round(input.importance)));
+  }
+  if (typeof input.confidence === 'number') {
+    corePayload.confidence = Math.max(0, Math.min(1, input.confidence));
+  }
+  if (input.expiresAt) corePayload.expires_at = input.expiresAt;
+  if (input.supersededBy) corePayload.superseded_by = input.supersededBy;
+  if (input.pinStatus === 'pinned' || input.pinStatus === 'unpinned') {
+    corePayload.pin_status = input.pinStatus;
+  }
+
+  // Validate via core — throws on invalid shape.
+  const validated = getWasm().validateMemoryClaimV1(JSON.stringify(corePayload)) as string;
+  const canonical = JSON.parse(validated) as Record<string, unknown>;
+  canonical.schema_version = V1_SCHEMA_VERSION;
+  if (input.volatility && (VALID_MEMORY_VOLATILITIES as readonly string[]).includes(input.volatility)) {
+    canonical.volatility = input.volatility;
+  }
+  return JSON.stringify(canonical);
+}
+
 /**
  * Normalize any type token (v0 or v1) to a v1 type. Uses the v0→v1 mapping
  * for legacy tokens; passes through when already v1.
@@ -289,6 +426,11 @@ export interface V1BlobReadResult {
   expiresAt?: string;
   supersededBy?: string;
   id?: string;
+  /**
+   * v1.1 pin state. Absent when the blob was written by a v1.0 client or
+   * when the writer explicitly omitted the field (treated as `"unpinned"`).
+   */
+  pinStatus?: PinStatus;
 }
 
 export function readV1Blob(decrypted: string): V1BlobReadResult | null {
@@ -349,6 +491,12 @@ export function readV1Blob(decrypted: string): V1BlobReadResult | null {
     if (typeof obj.expires_at === 'string') result.expiresAt = obj.expires_at;
     if (typeof obj.superseded_by === 'string') result.supersededBy = obj.superseded_by;
     if (typeof obj.id === 'string') result.id = obj.id;
+    if (typeof obj.pin_status === 'string') {
+      const ps = obj.pin_status;
+      if (ps === 'pinned' || ps === 'unpinned') {
+        result.pinStatus = ps;
+      }
+    }
 
     return result;
   } catch {
@@ -484,6 +632,9 @@ export function readClaimFromBlob(decryptedJson: string): BlobReadResult {
           scope: typeof obj.scope === 'string' ? obj.scope : 'unspecified',
           volatility: typeof obj.volatility === 'string' ? obj.volatility : 'updatable',
           reasoning: typeof obj.reasoning === 'string' ? obj.reasoning : undefined,
+          // v1.1: surface pin_status verbatim for downstream (recall display +
+          // export). Absent ⇒ undefined (receivers treat as "unpinned").
+          pin_status: typeof obj.pin_status === 'string' ? obj.pin_status : undefined,
           importance: importance / 10,
           created_at: typeof obj.created_at === 'string' ? obj.created_at : '',
           schema_version: obj.schema_version,

package/digest-sync.ts

@@ -73,6 +73,44 @@ export interface CompileDigestCoreInput {
   logger: DigestLogger;
 }
 
+// ---------------------------------------------------------------------------
+// Stub / tombstone blob detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Is this subgraph-stored blob a supersede tombstone or other non-content
+ * stub? The 3.0.7-rc.1 QA found that 7 of 25 facts on the QA wallet had
+ * `encryptedBlob == "0x00"` — a 1-byte stub written as a supersede
+ * tombstone. The digest pipeline attempted to decrypt these unconditionally
+ * and produced 5 `Digest: decrypt failed … Encrypted data too short`
+ * warnings per QA window.
+ *
+ * We deliberately ONLY short-circuit shapes that cannot plausibly contain
+ * a real XChaCha20-Poly1305 payload — a valid ciphertext must be at
+ * least 40 bytes (24B nonce + 16B tag). We stay conservative about
+ * "short-but-non-stub" blobs: if someone's wire format changes and we
+ * see a 30-byte blob, that's a legitimate decrypt-failure case worth
+ * logging as a WARN, not silently skipping. So the check is:
+ *
+ *   - Empty string                        → stub
+ *   - Just the `0x` / `0X` prefix         → stub
+ *   - All-zero hex (e.g. "0x00", "00")    → stub (explicit tombstone)
+ *
+ * Anything else falls through to the decrypt attempt.
+ *
+ * Called from both `loadLatestDigest` (digest read path) and
+ * `fetchAllActiveClaims` (digest recompile path).
+ */
+export function isStubBlob(hex: string): boolean {
+  if (typeof hex !== 'string') return true;
+  const stripped = (hex.startsWith('0x') || hex.startsWith('0X')) ? hex.slice(2) : hex;
+  if (stripped.length === 0) return true;
+  // All-zero hex is the explicit tombstone shape the relay emits
+  // when marking a fact superseded (seen as "0x00" on the QA wallet,
+  // but any "00...00" of any length is semantically the same).
+  return /^0+$/i.test(stripped);
+}
+
 // ---------------------------------------------------------------------------
 // Recompile-in-progress guard (in-memory, per-process)
 // ---------------------------------------------------------------------------
@@ -217,16 +255,30 @@ export async function loadLatestDigest(
   }
   if (!results || results.length === 0) return null;
 
-  // Pick the highest createdAt (client-generated Unix seconds). Fall back to
-  // timestamp (block time) when createdAt is missing.
+  // Pick the highest createdAt (client-generated Unix seconds) among rows
+  // with a real (non-stub) blob. Stub blobs are supersede tombstones —
+  // see `isStubBlob` above; attempting to decrypt one produces a noisy
+  // `Digest: decrypt failed … Encrypted data too short` WARN. We filter
+  // them out pre-ranking so we prefer a slightly-older real digest over
+  // a newer tombstone. If EVERY candidate is a stub, return null quietly.
   let best: { id: string; encryptedBlob: string; createdAt: number } | null = null;
+  let stubCount = 0;
   for (const r of results) {
+    if (isStubBlob(r.encryptedBlob)) {
+      stubCount++;
+      continue;
+    }
     const createdAt = parseInt(r.createdAt ?? r.timestamp ?? '0', 10) || 0;
     if (!best || createdAt > best.createdAt) {
       best = { id: r.id, encryptedBlob: r.encryptedBlob, createdAt };
     }
   }
-  if (!best) return null;
+  if (!best) {
+    if (stubCount > 0) {
+      logger.info(`Digest: all ${stubCount} candidates were tombstone stubs — no digest available`);
+    }
+    return null;
+  }
 
   try {
     const decrypted = deps.decryptFromHex(best.encryptedBlob, encryptionKey);
@@ -349,6 +401,11 @@ export async function fetchAllActiveClaims(
   const claimsOut: unknown[] = [];
   for (const row of rows) {
     if (row.isActive === false) continue;
+    // Stub / tombstone blobs (encryptedBlob == "0x00") will always fail
+    // decrypt with `Encrypted data too short`. Skip pre-decrypt so we
+    // don't spin up a WASM call path per stub — the QA wallet had 7 of
+    // 25 facts as stubs, so this matters for recompile cost too.
+    if (isStubBlob(row.encryptedBlob)) continue;
     try {
       const decrypted = deps.decryptFromHex(row.encryptedBlob, encryptionKey);
       const canonicalJson = getWasm().parseClaimOrLegacy(decrypted);