@remnic/core 1.0.2 → 1.1.0

package/dist/recall-mmr.js

@@ -0,0 +1,17 @@
+import {
+  DEFAULT_LAMBDA,
+  DEFAULT_TOP_N,
+  applyMmrToCandidates,
+  normalizeTokens,
+  reorderRecallResultsWithMmr,
+  summarizeMmrDiversity
+} from "./chunk-YDBIWGNI.js";
+export {
+  DEFAULT_LAMBDA,
+  DEFAULT_TOP_N,
+  applyMmrToCandidates,
+  normalizeTokens,
+  reorderRecallResultsWithMmr,
+  summarizeMmrDiversity
+};
+//# sourceMappingURL=recall-mmr.js.map

package/dist/recall-mmr.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/recall-qos.js

@@ -1,8 +1,8 @@
 import {
   createRecallSectionMetricRecorder,
   formatRecallSectionMetric
-} from "./chunk-L5RPWGFK.js";
-import "./chunk-KWBU5S5U.js";
+} from "./chunk-7DHTMOND.js";
+import "./chunk-2ODBA7MQ.js";
 export {
   createRecallSectionMetricRecorder,
   formatRecallSectionMetric

package/dist/recall-state.d.ts

@@ -1,4 +1,4 @@
-import { RecallPlanMode, IdentityInjectionMode } from './types.js';
+import { RecallPlanMode, IdentityInjectionMode, RecallTierExplain } from './types.js';
 
 interface LastRecallBudgetSummary {
     requestedTopK?: number;
@@ -32,6 +32,15 @@ interface LastRecallSnapshot {
     identityInjectionMode?: IdentityInjectionMode | "none";
     identityInjectedChars?: number;
     identityInjectionTruncated?: boolean;
+    /**
+     * Optional tier-level explanation of how recall was served
+     * (issue #518).  Populated by orchestrator call sites that can
+     * identify a concrete tier; surfaces expose the block via
+     * `engram query --explain`, the `?explain=1` HTTP flag, and the
+     * `remnic_recall_explain` MCP tool.  Orthogonal to the existing
+     * graph-path `recallExplain` operation.
+     */
+    tierExplain?: RecallTierExplain;
 }
 interface GraphRecallExpandedEntry {
     path: string;
@@ -99,7 +108,25 @@ declare class LastRecallStore {
             injectedChars: number;
             truncated: boolean;
         };
+        /**
+         * Per-tier explain annotation (issue #518).  When supplied, the
+         * snapshot carries it so downstream surfaces (CLI / HTTP / MCP)
+         * can render which retrieval tier served the query.
+         */
+        tierExplain?: RecallTierExplain;
     }): Promise<void>;
+    /**
+     * Attach a RecallTierExplain block to the existing snapshot for a
+     * session without rewriting the entire snapshot.  Used by the
+     * post-recall direct-answer annotation path (issue #518 slice 3c):
+     * recallInternal records the snapshot first, then the orchestrator
+     * fires the direct-answer tier in observation mode and annotates
+     * the stored snapshot with whichever tier served the query.
+     *
+     * No-op when no snapshot exists for the given session; callers do
+     * not need to guard on existence.
+     */
+    annotateTierExplain(sessionKey: string, tierExplain: RecallTierExplain): Promise<void>;
 }
 declare class TierMigrationStatusStore {
     private readonly statePath;

package/dist/recall-state.js

@@ -2,8 +2,8 @@ import {
   LastRecallStore,
   TierMigrationStatusStore,
   clampGraphRecallExpandedEntries
-} from "./chunk-HG2NKWR2.js";
-import "./chunk-KWBU5S5U.js";
+} from "./chunk-47UU5PU2.js";
+import "./chunk-2ODBA7MQ.js";
 export {
   LastRecallStore,
   TierMigrationStatusStore,

package/dist/relevance.js

@@ -1,7 +1,7 @@
 import {
   RelevanceStore
-} from "./chunk-BRK4ODMI.js";
-import "./chunk-KWBU5S5U.js";
+} from "./chunk-5NPGSAVB.js";
+import "./chunk-2ODBA7MQ.js";
 export {
   RelevanceStore
 };

package/dist/resolution-QBTDHTG7.js

@@ -0,0 +1,100 @@
+import {
+  readPair,
+  resolvePair
+} from "./chunk-YNB73F22.js";
+import {
+  log
+} from "./chunk-2ODBA7MQ.js";
+
+// src/contradiction/resolution.ts
+var VALID_VERBS = ["keep-a", "keep-b", "merge", "both-valid", "needs-more-context"];
+function isValidResolutionVerb(value) {
+  return VALID_VERBS.includes(value);
+}
+async function executeResolution(memoryDir, storage, pairId, verb) {
+  const pair = readPair(memoryDir, pairId);
+  if (!pair) {
+    return { pairId, verb, affectedIds: [], message: `Pair ${pairId} not found` };
+  }
+  if (pair.resolution) {
+    return { pairId, verb, affectedIds: [], message: `Pair already resolved with verb "${pair.resolution}"` };
+  }
+  const [idA, idB] = pair.memoryIds;
+  const affectedIds = [];
+  let message = "";
+  let supersedeFailed = false;
+  switch (verb) {
+    case "keep-a": {
+      const ok = await supersedeSafe(storage, idB, idA, "contradiction-resolution:keep-a");
+      if (ok) {
+        affectedIds.push(idB);
+        message = `Kept ${idA}, superseded ${idB}`;
+      } else {
+        supersedeFailed = true;
+        message = `Supersede failed for ${idB}; not resolving`;
+      }
+      break;
+    }
+    case "keep-b": {
+      const ok = await supersedeSafe(storage, idA, idB, "contradiction-resolution:keep-b");
+      if (ok) {
+        affectedIds.push(idA);
+        message = `Kept ${idB}, superseded ${idA}`;
+      } else {
+        supersedeFailed = true;
+        message = `Supersede failed for ${idA}; not resolving`;
+      }
+      break;
+    }
+    case "merge": {
+      const mergedId = `merged-${pairId}`;
+      const okA = await supersedeSafe(storage, idA, mergedId, "contradiction-resolution:merge");
+      const okB = await supersedeSafe(storage, idB, mergedId, "contradiction-resolution:merge");
+      if (okA) affectedIds.push(idA);
+      if (okB) affectedIds.push(idB);
+      if (!okA || !okB) {
+        supersedeFailed = true;
+        message = `Merge incomplete: ${affectedIds.length}/2 superseded; not resolving to allow retry`;
+      } else {
+        message = `Both memories superseded by merged ${mergedId}`;
+      }
+      break;
+    }
+    case "both-valid": {
+      message = "Pair marked as both-valid; cooldown applied";
+      break;
+    }
+    case "needs-more-context": {
+      message = "Deferred; no action taken, short cooldown applied";
+      break;
+    }
+  }
+  if (!supersedeFailed) {
+    resolvePair(memoryDir, pairId, verb);
+  }
+  log.info("[contradiction-resolution] pair=%s verb=%s affected=%d", pairId, verb, affectedIds.length);
+  return { pairId, verb, affectedIds, message };
+}
+async function supersedeSafe(storage, oldId, newId, reason) {
+  try {
+    const result = await storage.supersedeMemory(oldId, newId, reason);
+    if (result === false) {
+      log.warn("[contradiction-resolution] supersede returned false for %s \u2192 %s", oldId, newId);
+      return false;
+    }
+    return true;
+  } catch (err) {
+    log.warn(
+      "[contradiction-resolution] supersede failed %s \u2192 %s: %s",
+      oldId,
+      newId,
+      err instanceof Error ? err.message : err
+    );
+    return false;
+  }
+}
+export {
+  executeResolution,
+  isValidResolutionVerb
+};
+//# sourceMappingURL=resolution-QBTDHTG7.js.map

package/dist/resolution-QBTDHTG7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contradiction/resolution.ts"],"sourcesContent":["/**\n * Resolution Verbs — executes user-chosen resolution actions on contradiction pairs (issue #520).\n *\n * All resolution paths delegate to StorageManager.supersedeMemory. Do not\n * reimplement supersession logic here (rule 22: deduplicate resolution).\n */\n\nimport type { StorageManager } from \"../storage.js\";\nimport type { ResolutionVerb } from \"./contradiction-review.js\";\nimport { resolvePair, readPair } from \"./contradiction-review.js\";\nimport { log } from \"../logger.js\";\n\nexport interface ResolutionResult {\n  pairId: string;\n  verb: ResolutionVerb;\n  /** Memory IDs affected by the resolution. */\n  affectedIds: string[];\n  /** Human-readable status. */\n  message: string;\n}\n\nconst VALID_VERBS: ResolutionVerb[] = [\"keep-a\", \"keep-b\", \"merge\", \"both-valid\", \"needs-more-context\"];\n\nexport function isValidResolutionVerb(value: string): value is ResolutionVerb {\n  return VALID_VERBS.includes(value as ResolutionVerb);\n}\n\n/**\n * Execute a resolution verb on a contradiction pair.\n *\n * - `keep-a`: Supersede B, keep A active.\n * - `keep-b`: Supersede A, keep B active.\n * - `merge`: Mark both as superseded by a synthetic merged ID.\n * - `both-valid`: Mark pair as reviewed; no memories are superseded.\n * - `needs-more-context`: Defer; no action, short cooldown.\n */\nexport async function executeResolution(\n  memoryDir: string,\n  storage: StorageManager,\n  pairId: string,\n  verb: ResolutionVerb,\n): Promise<ResolutionResult> {\n  const pair = readPair(memoryDir, pairId);\n  if (!pair) {\n    return { pairId, verb, affectedIds: [], message: `Pair ${pairId} not found` };\n  }\n\n  if (pair.resolution) {\n    return { pairId, verb, affectedIds: [], message: `Pair already resolved with verb \"${pair.resolution}\"` };\n  }\n\n  const [idA, idB] = pair.memoryIds;\n  const affectedIds: string[] = [];\n  let message = \"\";\n  let supersedeFailed = false;\n\n  switch (verb) {\n    case \"keep-a\": {\n      const ok = await supersedeSafe(storage, idB, idA, \"contradiction-resolution:keep-a\");\n      if (ok) { affectedIds.push(idB); message = `Kept ${idA}, superseded ${idB}`; }\n      else { supersedeFailed = true; message = `Supersede failed for ${idB}; not resolving`; }\n      break;\n    }\n    case \"keep-b\": {\n      const ok = await supersedeSafe(storage, idA, idB, \"contradiction-resolution:keep-b\");\n      if (ok) { affectedIds.push(idA); message = `Kept ${idB}, superseded ${idA}`; }\n      else { supersedeFailed = true; message = `Supersede failed for ${idA}; not resolving`; }\n      break;\n    }\n    case \"merge\": {\n      const mergedId = `merged-${pairId}`;\n      const okA = await supersedeSafe(storage, idA, mergedId, \"contradiction-resolution:merge\");\n      const okB = await supersedeSafe(storage, idB, mergedId, \"contradiction-resolution:merge\");\n      if (okA) affectedIds.push(idA);\n      if (okB) affectedIds.push(idB);\n      if (!okA || !okB) {\n        supersedeFailed = true;\n        message = `Merge incomplete: ${affectedIds.length}/2 superseded; not resolving to allow retry`;\n      } else {\n        message = `Both memories superseded by merged ${mergedId}`;\n      }\n      break;\n    }\n    case \"both-valid\": {\n      message = \"Pair marked as both-valid; cooldown applied\";\n      break;\n    }\n    case \"needs-more-context\": {\n      message = \"Deferred; no action taken, short cooldown applied\";\n      break;\n    }\n  }\n\n  if (!supersedeFailed) {\n    resolvePair(memoryDir, pairId, verb);\n  }\n  log.info(\"[contradiction-resolution] pair=%s verb=%s affected=%d\", pairId, verb, affectedIds.length);\n  return { pairId, verb, affectedIds, message };\n}\n\nasync function supersedeSafe(\n  storage: StorageManager,\n  oldId: string,\n  newId: string,\n  reason: string,\n): Promise<boolean> {\n  try {\n    const result = await storage.supersedeMemory(oldId, newId, reason);\n    if (result === false) {\n      log.warn(\"[contradiction-resolution] supersede returned false for %s → %s\", oldId, newId);\n      return false;\n    }\n    return true;\n  } catch (err) {\n    log.warn(\n      \"[contradiction-resolution] supersede failed %s → %s: %s\",\n      oldId,\n      newId,\n      err instanceof Error ? err.message : err,\n    );\n    return false;\n  }\n}\n"],"mappings":";;;;;;;;;AAqBA,IAAM,cAAgC,CAAC,UAAU,UAAU,SAAS,cAAc,oBAAoB;AAE/F,SAAS,sBAAsB,OAAwC;AAC5E,SAAO,YAAY,SAAS,KAAuB;AACrD;AAWA,eAAsB,kBACpB,WACA,SACA,QACA,MAC2B;AAC3B,QAAM,OAAO,SAAS,WAAW,MAAM;AACvC,MAAI,CAAC,MAAM;AACT,WAAO,EAAE,QAAQ,MAAM,aAAa,CAAC,GAAG,SAAS,QAAQ,MAAM,aAAa;AAAA,EAC9E;AAEA,MAAI,KAAK,YAAY;AACnB,WAAO,EAAE,QAAQ,MAAM,aAAa,CAAC,GAAG,SAAS,oCAAoC,KAAK,UAAU,IAAI;AAAA,EAC1G;AAEA,QAAM,CAAC,KAAK,GAAG,IAAI,KAAK;AACxB,QAAM,cAAwB,CAAC;AAC/B,MAAI,UAAU;AACd,MAAI,kBAAkB;AAEtB,UAAQ,MAAM;AAAA,IACZ,KAAK,UAAU;AACb,YAAM,KAAK,MAAM,cAAc,SAAS,KAAK,KAAK,iCAAiC;AACnF,UAAI,IAAI;AAAE,oBAAY,KAAK,GAAG;AAAG,kBAAU,QAAQ,GAAG,gBAAgB,GAAG;AAAA,MAAI,OACxE;AAAE,0BAAkB;AAAM,kBAAU,wBAAwB,GAAG;AAAA,MAAmB;AACvF;AAAA,IACF;AAAA,IACA,KAAK,UAAU;AACb,YAAM,KAAK,MAAM,cAAc,SAAS,KAAK,KAAK,iCAAiC;AACnF,UAAI,IAAI;AAAE,oBAAY,KAAK,GAAG;AAAG,kBAAU,QAAQ,GAAG,gBAAgB,GAAG;AAAA,MAAI,OACxE;AAAE,0BAAkB;AAAM,kBAAU,wBAAwB,GAAG;AAAA,MAAmB;AACvF;AAAA,IACF;AAAA,IACA,KAAK,SAAS;AACZ,YAAM,WAAW,UAAU,MAAM;AACjC,YAAM,MAAM,MAAM,cAAc,SAAS,KAAK,UAAU,gCAAgC;AACxF,YAAM,MAAM,MAAM,cAAc,SAAS,KAAK,UAAU,gCAAgC;AACxF,UAAI,IAAK,aAAY,KAAK,GAAG;AAC7B,UAAI,IAAK,aAAY,KAAK,GAAG;AAC7B,UAAI,CAAC,OAAO,CAAC,KAAK;AAChB,0BAAkB;AAClB,kBAAU,qBAAqB,YAAY,MAAM;AAAA,MACnD,OAAO;AACL,kBAAU,sCAAsC,QAAQ;AAAA,MAC1D;AACA;AAAA,IACF;AAAA,IACA,KAAK,cAAc;AACjB,gBAAU;AACV;AAAA,IACF;AAAA,IACA,KAAK,sBAAsB;AACzB,gBAAU;AACV;AAAA,IACF;AAAA,EACF;AAEA,MAAI,CAAC,iBAAiB;AACpB,gBAAY,WAAW,QAAQ,IAAI;AAAA,EACrC;AACA,MAAI,KAAK,0DAA0D,QAAQ,MAAM,YAAY,MAAM;AACnG,SAAO,EAAE,QAAQ,MAAM,aAAa,QAAQ;AAC9C;AAEA,eAAe,cACb,SACA,OACA,OACA,QACkB;AAClB,MAAI;AACF,UAAM,SAAS,MAAM,QAAQ,gBAAgB,OAAO,OAAO,MAAM;AACjE,QAAI,WAAW,OAAO;AACpB,UAAI,KAAK,wEAAmE,OAAO,KAAK;AACxF,aAAO;AAAA,IACT;AACA,WAAO;AAAA,EACT,SAAS,KAAK;AACZ,QAAI;AAAA,MACF;AAAA,MACA;AAAA,MACA;AAAA,MACA,eAAe,QAAQ,IAAI,UAAU;AAAA,IACvC;AACA,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/resolve-provider-secret.d.ts

@@ -1,3 +1,25 @@
+/**
+ * Resolve a provider API key using OpenClaw's own auth resolution system.
+ *
+ * This module delegates to the gateway's `resolveApiKeyForProvider()` function,
+ * which handles all secret reference formats (SecretRef objects, auth profiles,
+ * "secretref-managed" markers, environment variables, etc.) using the same
+ * codepath the gateway uses for its own agent sessions.
+ *
+ * For plain-text API keys, a fast path returns them directly without
+ * involving the gateway auth system.
+ *
+ * Results are cached per provider for the gateway process lifetime.
+ */
+type ResolveApiKeyFn = (params: {
+    provider: string;
+    cfg?: unknown;
+    agentDir?: string;
+}) => Promise<{
+    apiKey?: string;
+    source?: string;
+    mode?: string;
+} | null>;
 /**
  * Resolve request-ready auth for a model, including provider-owned transforms
  * (e.g., OAuth token exchange, base URL override for openai-codex).
@@ -40,5 +62,6 @@ declare function getGatewayRuntimeAuthForModel(): Promise<GetRuntimeAuthForModel
  * Clear the resolution cache (useful for testing or key rotation).
  */
 declare function clearSecretCache(): void;
+declare function __setGatewayResolverForTest(resolver: ResolveApiKeyFn | null): void;
 
-export { type GetRuntimeAuthForModelFn, clearSecretCache, getGatewayRuntimeAuthForModel, resolveProviderApiKey };
+export { type GetRuntimeAuthForModelFn, __setGatewayResolverForTest, clearSecretCache, getGatewayRuntimeAuthForModel, resolveProviderApiKey };

package/dist/resolve-provider-secret.js

@@ -1,11 +1,13 @@
 import {
+  __setGatewayResolverForTest,
   clearSecretCache,
   getGatewayRuntimeAuthForModel,
   resolveProviderApiKey
-} from "./chunk-M5ZBBBJI.js";
+} from "./chunk-XZ2TIKGC.js";
 import "./chunk-MARWOCVP.js";
-import "./chunk-KWBU5S5U.js";
+import "./chunk-2ODBA7MQ.js";
 export {
+  __setGatewayResolverForTest,
   clearSecretCache,
   getGatewayRuntimeAuthForModel,
   resolveProviderApiKey

package/dist/resume-bundles.js

@@ -4,19 +4,20 @@ import {
   recordResumeBundle,
   resolveResumeBundleDir,
   validateResumeBundle
-} from "./chunk-QANCTXQF.js";
+} from "./chunk-6LX5ORAS.js";
 import "./chunk-CULXMQJH.js";
-import "./chunk-UV2FO7J4.js";
-import "./chunk-LOBRX7VD.js";
+import "./chunk-E6K4NIEU.js";
 import "./chunk-YRMVARQP.js";
+import "./chunk-LOBRX7VD.js";
 import "./chunk-FYIYMQ5N.js";
-import "./chunk-ISY75RLM.js";
+import "./chunk-MBJHSA7F.js";
 import "./chunk-Z5LAYHGJ.js";
 import "./chunk-MARWOCVP.js";
 import "./chunk-DT5TVLJE.js";
-import "./chunk-KWBU5S5U.js";
 import "./chunk-DGXUHMOV.js";
 import "./chunk-LPSF4OQH.js";
+import "./chunk-4DJQYKMN.js";
+import "./chunk-2ODBA7MQ.js";
 export {
   buildResumeBundleFromState,
   getResumeBundleStatus,

package/dist/retrieval-agents.js

@@ -7,9 +7,9 @@ import {
   runDirectAgent,
   runTemporalAgent,
   shouldRunAgent
-} from "./chunk-GPGBSNKM.js";
+} from "./chunk-K4FLSOR5.js";
 import "./chunk-V3RXWQIE.js";
-import "./chunk-KWBU5S5U.js";
+import "./chunk-2ODBA7MQ.js";
 export {
   PARALLEL_AGENT_WEIGHTS,
   augmentWithDirectAndTemporal,

package/dist/retrieval.js

@@ -1,8 +1,8 @@
 import {
   applyRuntimeRetrievalPolicy,
   expandQuery
-} from "./chunk-G3AG3KZN.js";
-import "./chunk-QCCCQT3O.js";
+} from "./chunk-5IZL4DCV.js";
+import "./chunk-TBBDFYXW.js";
 export {
   applyRuntimeRetrievalPolicy,
   expandQuery