@remnic/core 1.0.3 → 1.1.1

package/dist/recall-explain-renderer.d.ts

@@ -0,0 +1,49 @@
+import { LastRecallSnapshot } from './recall-state.js';
+import { RecallTierExplain } from './types.js';
+import { RecallXraySnapshot } from './recall-xray.js';
+
+/**
+ * Renderers for RecallTierExplain (issue #518).
+ *
+ * Pure functions that format a `LastRecallSnapshot` and its
+ * optional `tierExplain` field for human text and machine JSON
+ * consumption.  CLI / HTTP / MCP surfaces consume these — they do
+ * not format explain output themselves, so rendering is tested in
+ * one place.
+ */
+
+/**
+ * `text` and `json` are the original formats (backwards-compatible
+ * since issue #518).  `markdown` was added in issue #570 PR 7 and
+ * delegates to the shared X-ray renderer so the three observability
+ * surfaces stay in lock-step (CLAUDE.md rule 22).
+ */
+type RecallExplainFormat = "text" | "json" | "markdown";
+interface RecallExplainJsonPayload {
+    hasExplain: boolean;
+    snapshotFound: boolean;
+    sessionKey: string | null;
+    recordedAt: string | null;
+    namespace: string | null;
+    memoryIds: string[];
+    source: string | null;
+    sourcesUsed: string[] | null;
+    latencyMs: number | null;
+    tierExplain: RecallTierExplain | null;
+}
+declare function toRecallExplainJson(snapshot: LastRecallSnapshot | null): RecallExplainJsonPayload;
+/**
+ * Render the shared "--- tier explain ---" text block used by both the
+ * recall-explain surface and the Recall X-ray surface.  Callers provide
+ * the normalized `RecallTierExplain` (or `null` for the
+ * not-populated/disabled case) so the block stays character-for-character
+ * identical across surfaces (CLAUDE.md rule 22).  The returned strings do
+ * NOT include leading blank lines or headers — callers own that framing.
+ */
+declare function renderTierExplainTextLines(tierExplain: RecallTierExplain | null): string[];
+declare function toRecallExplainText(snapshot: LastRecallSnapshot | null): string;
+declare function toRecallXraySnapshotFromLegacy(snapshot: LastRecallSnapshot | null): RecallXraySnapshot | null;
+declare function renderRecallExplain(snapshot: LastRecallSnapshot | null, format: RecallExplainFormat): string;
+declare function parseRecallExplainFormat(value: unknown): RecallExplainFormat;
+
+export { type RecallExplainFormat, type RecallExplainJsonPayload, parseRecallExplainFormat, renderRecallExplain, renderTierExplainTextLines, toRecallExplainJson, toRecallExplainText, toRecallXraySnapshotFromLegacy };

package/dist/recall-explain-renderer.js

@@ -0,0 +1,18 @@
+import {
+  parseRecallExplainFormat,
+  renderRecallExplain,
+  renderTierExplainTextLines,
+  toRecallExplainJson,
+  toRecallExplainText,
+  toRecallXraySnapshotFromLegacy
+} from "./chunk-ZAIM4TUE.js";
+import "./chunk-SOBJ6NEY.js";
+export {
+  parseRecallExplainFormat,
+  renderRecallExplain,
+  renderTierExplainTextLines,
+  toRecallExplainJson,
+  toRecallExplainText,
+  toRecallXraySnapshotFromLegacy
+};
+//# sourceMappingURL=recall-explain-renderer.js.map

package/dist/recall-explain-renderer.js.map

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

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,22 @@ interface LastRecallSnapshot {
     identityInjectionMode?: IdentityInjectionMode | "none";
     identityInjectedChars?: number;
     identityInjectionTruncated?: boolean;
+    /**
+     * Collision-safe write nonce.  Random UUID set on every `record()`
+     * call so the observation-mode direct-answer hook can detect stale
+     * snapshots and avoid annotating a snapshot that a subsequent recall
+     * already replaced (issue #518).
+     */
+    writeNonce?: string;
+    /**
+     * 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,6 +115,28 @@ 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, expected?: {
+        writeNonce?: string;
+        traceId?: string;
+        recordedAt?: string;
     }): Promise<void>;
 }
 declare class TierMigrationStatusStore {

package/dist/recall-state.js

@@ -2,7 +2,7 @@ import {
   LastRecallStore,
   TierMigrationStatusStore,
   clampGraphRecallExpandedEntries
-} from "./chunk-S4LX5EBI.js";
+} from "./chunk-VBVG2M5G.js";
 import "./chunk-2ODBA7MQ.js";
 export {
   LastRecallStore,

package/dist/recall-xray-cli.d.ts

@@ -0,0 +1,40 @@
+import { RecallXrayFormat } from './recall-xray-renderer.js';
+import './recall-xray.js';
+import './types.js';
+
+/**
+ * Input-validation helpers for the `remnic xray` CLI command (issue
+ * #570, PR 3).
+ *
+ * Pulled out of `cli.ts` so the validation paths can be unit-tested in
+ * isolation — the full CLI handler is hard to exercise without booting
+ * an orchestrator.  CLAUDE.md rules 14 + 51 require that `--format`,
+ * `--budget`, `--namespace`, and `--out` reject missing-value /
+ * unknown / non-positive arguments with a listed-options error, rather
+ * than silently defaulting.
+ */
+
+interface ParsedXrayCliOptions {
+    format: RecallXrayFormat;
+    /** Positive integer override, or undefined when not specified. */
+    budget?: number;
+    /** Trimmed namespace, or undefined when not specified. */
+    namespace?: string;
+    /** Trimmed, tilde-unexpanded output path, or undefined when stdout. */
+    outPath?: string;
+}
+/**
+ * Validate and coerce `--budget <chars>`.  Must be a positive integer;
+ * throws a listed-options error otherwise.
+ */
+declare function parseXrayBudgetFlag(value: unknown): number | undefined;
+/**
+ * Parse and validate the full option bag for `remnic xray`.  Extracted
+ * so the CLI handler in `cli.ts` can stay thin and the validation can
+ * be unit-tested without booting an orchestrator.
+ */
+declare function parseXrayCliOptions(rawQuery: unknown, options: Record<string, unknown>): {
+    query: string;
+} & ParsedXrayCliOptions;
+
+export { type ParsedXrayCliOptions, parseXrayBudgetFlag, parseXrayCliOptions };

package/dist/recall-xray-cli.js

@@ -0,0 +1,11 @@
+import {
+  parseXrayBudgetFlag,
+  parseXrayCliOptions
+} from "./chunk-PVPWZSSI.js";
+import "./chunk-ZAIM4TUE.js";
+import "./chunk-SOBJ6NEY.js";
+export {
+  parseXrayBudgetFlag,
+  parseXrayCliOptions
+};
+//# sourceMappingURL=recall-xray-cli.js.map

package/dist/recall-xray-cli.js.map

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

package/dist/recall-xray-renderer.d.ts

@@ -0,0 +1,44 @@
+import { RecallXraySnapshot } from './recall-xray.js';
+import './types.js';
+
+/**
+ * Unified Recall X-ray renderer (issue #570, PR 2).
+ *
+ * Pure functions that format a `RecallXraySnapshot` for human text,
+ * GitHub-flavored markdown, and machine JSON consumption.  CLI / HTTP
+ * / MCP surfaces all call into this module — they do NOT format X-ray
+ * output themselves, so rendering is tested in one place (CLAUDE.md
+ * rule 22).
+ *
+ * Scope for PR 2 (this slice):
+ *   - Pure rendering.  No IO, no transport, no capture.
+ *   - `renderXray(snapshot, format)` with format ∈
+ *     `{"json", "text", "markdown"}`.
+ *   - `parseXrayFormat(value)` — input validator that rejects unknown
+ *     formats with a listed-options error (CLAUDE.md rule 51).
+ *   - Golden-file-style tests in `recall-xray-renderer.test.ts`.
+ */
+
+type RecallXrayFormat = "json" | "text" | "markdown";
+declare const RECALL_XRAY_FORMATS: readonly RecallXrayFormat[];
+/**
+ * Validate and coerce a user-provided `--format` / `format` argument to
+ * `RecallXrayFormat`.  Unknown values throw an error listing valid
+ * options (CLAUDE.md rule 51).  `undefined`/`null` defaults to `"text"`.
+ */
+declare function parseXrayFormat(value: unknown): RecallXrayFormat;
+/**
+ * Top-level dispatcher.  CLI / HTTP / MCP callers should always route
+ * through this function so the three formats stay in lock-step.
+ */
+declare function renderXray(snapshot: RecallXraySnapshot | null, format: RecallXrayFormat): string;
+/**
+ * Deterministic JSON encoding of an X-ray snapshot.  Returns a stable
+ * v1 envelope when the snapshot is absent so consumers can pattern-match
+ * on `snapshotFound` rather than distinguishing `null` vs `{}`.
+ */
+declare function renderXrayJson(snapshot: RecallXraySnapshot | null): string;
+declare function renderXrayText(snapshot: RecallXraySnapshot | null): string;
+declare function renderXrayMarkdown(snapshot: RecallXraySnapshot | null): string;
+
+export { RECALL_XRAY_FORMATS, type RecallXrayFormat, parseXrayFormat, renderXray, renderXrayJson, renderXrayMarkdown, renderXrayText };

package/dist/recall-xray-renderer.js

@@ -0,0 +1,18 @@
+import {
+  RECALL_XRAY_FORMATS,
+  parseXrayFormat,
+  renderXray,
+  renderXrayJson,
+  renderXrayMarkdown,
+  renderXrayText
+} from "./chunk-ZAIM4TUE.js";
+import "./chunk-SOBJ6NEY.js";
+export {
+  RECALL_XRAY_FORMATS,
+  parseXrayFormat,
+  renderXray,
+  renderXrayJson,
+  renderXrayMarkdown,
+  renderXrayText
+};
+//# sourceMappingURL=recall-xray-renderer.js.map

package/dist/recall-xray-renderer.js.map

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

package/dist/recall-xray.d.ts

@@ -0,0 +1,179 @@
+import { RecallTierExplain } from './types.js';
+
+/**
+ * Recall X-ray snapshot schema (issue #570, PR 1).
+ *
+ * The X-ray surface is the unified, per-result attribution document that
+ * merges the tier that served each memory, its score decomposition, any
+ * graph path, an audit entry id, and the exact filter/eligibility ladder
+ * that either admitted or rejected each candidate.  This file defines the
+ * schema and an in-memory builder + builder-state helper.
+ *
+ * Scope for PR 1 (this slice):
+ *   - Types only + pure builder functions (no IO, no rendering).
+ *   - Orchestrator plumbing captures a snapshot when the caller passes
+ *     `xrayCapture: true`.  No behavior change when the flag is absent.
+ *   - NO new public surfaces here — CLI/HTTP/MCP land in later slices.
+ *
+ * The shared renderer lands in PR 2 at `recall-xray-renderer.ts`.  Do not
+ * fork formatting logic into other surfaces; extend the renderer.
+ */
+
+/**
+ * Which retrieval source produced a given result.  This is the X-ray
+ * tier ladder called out in issue #570 and is *distinct* from the
+ * `RetrievalTier` enum (which describes issue #518's tier-explain
+ * block).  Keeping the sets separate lets the two observability
+ * surfaces evolve without conflating their vocabularies:
+ *
+ *   - `RetrievalTier`     — direct-answer eligibility ladder.
+ *   - `RecallXrayServedBy` — which source materialized each result.
+ */
+type RecallXrayServedBy = "direct-answer" | "hybrid" | "graph" | "recent-scan" | "procedural" | "review-context";
+declare const RECALL_XRAY_SERVED_BY_VALUES: readonly RecallXrayServedBy[];
+declare function isRecallXrayServedBy(value: unknown): value is RecallXrayServedBy;
+/**
+ * Score decomposition for a single X-ray result.
+ *
+ * All fields are optional because different tiers populate different
+ * terms: `hybrid` reports vector + bm25 + mmr penalty, `direct-answer`
+ * reports importance + tier prior, etc.  The only guaranteed field is
+ * `final`, which is the post-combination score used for ordering.
+ */
+interface RecallXrayScoreDecomposition {
+    vector?: number;
+    bm25?: number;
+    importance?: number;
+    mmrPenalty?: number;
+    tierPrior?: number;
+    final: number;
+}
+/**
+ * Per-result breakdown inside an X-ray snapshot.
+ */
+interface RecallXrayResult {
+    memoryId: string;
+    path: string;
+    servedBy: RecallXrayServedBy;
+    scoreDecomposition: RecallXrayScoreDecomposition;
+    graphPath?: string[];
+    auditEntryId?: string;
+    /** Human-readable list of filters the candidate *passed*. */
+    admittedBy: string[];
+    /**
+     * First filter that *would have* rejected the candidate, or undefined
+     * when the candidate was admitted without a rejection trace.  When
+     * present, `admittedBy` may still contain filters the candidate passed
+     * before the rejecting gate; consumers should render both.
+     */
+    rejectedBy?: string;
+}
+/**
+ * Trace entry for a filter the orchestrator evaluated during recall.
+ * Captures the name of the filter, how many candidates it saw, and how
+ * many it let through.  Used by X-ray consumers to render the filter
+ * ladder above the per-result breakdown.
+ */
+interface RecallFilterTrace {
+    name: string;
+    considered: number;
+    admitted: number;
+    /** Optional human-readable reason for any rejections. */
+    reason?: string;
+}
+/**
+ * The unified X-ray snapshot.  CLI, HTTP, and MCP surfaces all render
+ * this same shape through the shared renderer (CLAUDE.md rule 22).
+ */
+interface RecallXraySnapshot {
+    /** Stable v1 tag so downstream consumers can version-gate their parsers. */
+    schemaVersion: "1";
+    query: string;
+    /** UUID minted per capture; unique across snapshots within a process. */
+    snapshotId: string;
+    /** Epoch milliseconds the snapshot was captured. */
+    capturedAt: number;
+    /**
+     * Tier-explain block from issue #518, carried verbatim when present.
+     * `null` means direct-answer tier did not run (disabled, or another
+     * tier served the query).
+     */
+    tierExplain: RecallTierExplain | null;
+    results: RecallXrayResult[];
+    filters: RecallFilterTrace[];
+    /**
+     * Character budget accounting for the final assembled recall payload.
+     * `used` is the rendered-context length; `chars` is the cap.  Both are
+     * non-negative integers in `[0, 2**31)`.
+     */
+    budget: {
+        chars: number;
+        used: number;
+    };
+    /** Optional session-scope fields carried for downstream filtering. */
+    sessionKey?: string;
+    namespace?: string;
+    traceId?: string;
+}
+interface BuildXraySnapshotInput {
+    query: string;
+    tierExplain?: RecallTierExplain | null;
+    results?: RecallXrayResult[];
+    filters?: RecallFilterTrace[];
+    budget?: {
+        chars?: number;
+        used?: number;
+    };
+    sessionKey?: string;
+    namespace?: string;
+    traceId?: string;
+    /** Optional injected timestamp for deterministic tests. */
+    now?: () => number;
+    /** Optional injected id generator for deterministic tests. */
+    snapshotIdGenerator?: () => string;
+}
+/**
+ * Build a `RecallXraySnapshot` from explicit input fields.  Pure
+ * function; safe to call from anywhere.  All array/object inputs are
+ * shallow-copied so caller mutation after build cannot tear the
+ * returned snapshot.
+ */
+declare function buildXraySnapshot(input: BuildXraySnapshotInput): RecallXraySnapshot;
+/**
+ * Mutable builder used by the orchestrator to accumulate X-ray fields
+ * as recall progresses.  Call `build()` to get the finalized
+ * immutable-ish snapshot.  All inputs are validated at insert time so
+ * a malformed entry cannot poison the snapshot later.
+ */
+declare class RecallXrayBuilder {
+    private readonly query;
+    private readonly sessionKey;
+    private namespace;
+    private traceId;
+    private tierExplain;
+    private readonly results;
+    private readonly filters;
+    private budgetChars;
+    private budgetUsed;
+    constructor(opts: {
+        query: string;
+        sessionKey?: string;
+        namespace?: string;
+        traceId?: string;
+    });
+    setNamespace(namespace: string | undefined): void;
+    setTraceId(traceId: string | undefined): void;
+    setTierExplain(tierExplain: RecallTierExplain | null | undefined): void;
+    setBudget(budget: {
+        chars?: number;
+        used?: number;
+    }): void;
+    recordResult(result: RecallXrayResult): void;
+    recordFilter(filter: RecallFilterTrace): void;
+    build(opts?: {
+        now?: () => number;
+        snapshotIdGenerator?: () => string;
+    }): RecallXraySnapshot;
+}
+
+export { type BuildXraySnapshotInput, RECALL_XRAY_SERVED_BY_VALUES, type RecallFilterTrace, RecallXrayBuilder, type RecallXrayResult, type RecallXrayScoreDecomposition, type RecallXrayServedBy, type RecallXraySnapshot, buildXraySnapshot, isRecallXrayServedBy };

package/dist/recall-xray.js

@@ -0,0 +1,13 @@
+import {
+  RECALL_XRAY_SERVED_BY_VALUES,
+  RecallXrayBuilder,
+  buildXraySnapshot,
+  isRecallXrayServedBy
+} from "./chunk-KVBLZUKV.js";
+export {
+  RECALL_XRAY_SERVED_BY_VALUES,
+  RecallXrayBuilder,
+  buildXraySnapshot,
+  isRecallXrayServedBy
+};
+//# sourceMappingURL=recall-xray.js.map

package/dist/recall-xray.js.map

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

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-KEG4GNGI.js";
+} from "./chunk-XZ2TIKGC.js";
 import "./chunk-MARWOCVP.js";
 import "./chunk-2ODBA7MQ.js";
 export {
+  __setGatewayResolverForTest,
   clearSecretCache,
   getGatewayRuntimeAuthForModel,
   resolveProviderApiKey

package/dist/resume-bundles.js

@@ -4,20 +4,20 @@ import {
   recordResumeBundle,
   resolveResumeBundleDir,
   validateResumeBundle
-} from "./chunk-AYPYCLR7.js";
+} from "./chunk-KUB6JU6H.js";
 import "./chunk-CULXMQJH.js";
 import "./chunk-E6K4NIEU.js";
-import "./chunk-LOBRX7VD.js";
 import "./chunk-YRMVARQP.js";
-import "./chunk-FYIYMQ5N.js";
-import "./chunk-OJFGVJS6.js";
+import "./chunk-LOBRX7VD.js";
+import "./chunk-BK2EFTE2.js";
 import "./chunk-Z5LAYHGJ.js";
+import "./chunk-FYIYMQ5N.js";
 import "./chunk-MARWOCVP.js";
 import "./chunk-DT5TVLJE.js";
-import "./chunk-DGXUHMOV.js";
-import "./chunk-LPSF4OQH.js";
 import "./chunk-4DJQYKMN.js";
 import "./chunk-2ODBA7MQ.js";
+import "./chunk-DGXUHMOV.js";
+import "./chunk-LPSF4OQH.js";
 export {
   buildResumeBundleFromState,
   getResumeBundleStatus,

package/dist/retrieval-agents.d.ts

@@ -1,6 +1,6 @@
 import { QmdSearchResult } from './types.js';
 import { QmdClient } from './qmd.js';
-import './port-C1GZFv8h.js';
+import './port-BADbLZU5.js';
 
 /**
  * Parallel Specialized Retrieval (v9.1 — ASMR-inspired)