@remnic/core 1.1.0 → 1.1.2

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

@@ -32,6 +32,13 @@ 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
@@ -126,7 +133,11 @@ declare class LastRecallStore {
      * 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>;
+    annotateTierExplain(sessionKey: string, tierExplain: RecallTierExplain, expected?: {
+        writeNonce?: string;
+        traceId?: string;
+        recordedAt?: string;
+    }): Promise<void>;
 }
 declare class TierMigrationStatusStore {
     private readonly statePath;

package/dist/recall-state.js

@@ -2,7 +2,7 @@ import {
   LastRecallStore,
   TierMigrationStatusStore,
   clampGraphRecallExpandedEntries
-} from "./chunk-47UU5PU2.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/resolve-provider-secret.d.ts

@@ -40,6 +40,10 @@ type GetRuntimeAuthForModelFn = (params: {
     mode?: string;
     profileId?: string;
 } | null>;
+declare function findExecutableOnPath(executableName: string, access: (path: string, mode?: number) => void, stat: (path: string) => {
+    isFile(): boolean;
+}, executableMode: number): string | undefined;
+declare const __findExecutableOnPathForTest: typeof findExecutableOnPath;
 /**
  * Resolve a provider API key from various OpenClaw formats.
  *
@@ -64,4 +68,4 @@ declare function getGatewayRuntimeAuthForModel(): Promise<GetRuntimeAuthForModel
 declare function clearSecretCache(): void;
 declare function __setGatewayResolverForTest(resolver: ResolveApiKeyFn | null): void;
 
-export { type GetRuntimeAuthForModelFn, __setGatewayResolverForTest, clearSecretCache, getGatewayRuntimeAuthForModel, resolveProviderApiKey };
+export { type GetRuntimeAuthForModelFn, __findExecutableOnPathForTest, __setGatewayResolverForTest, clearSecretCache, getGatewayRuntimeAuthForModel, resolveProviderApiKey };

package/dist/resolve-provider-secret.js

@@ -1,12 +1,14 @@
 import {
+  __findExecutableOnPathForTest,
   __setGatewayResolverForTest,
   clearSecretCache,
   getGatewayRuntimeAuthForModel,
   resolveProviderApiKey
-} from "./chunk-XZ2TIKGC.js";
+} from "./chunk-Y7R2XJ5Q.js";
 import "./chunk-MARWOCVP.js";
 import "./chunk-2ODBA7MQ.js";
 export {
+  __findExecutableOnPathForTest,
   __setGatewayResolverForTest,
   clearSecretCache,
   getGatewayRuntimeAuthForModel,

package/dist/resume-bundles.js

@@ -4,20 +4,20 @@ import {
   recordResumeBundle,
   resolveResumeBundleDir,
   validateResumeBundle
-} from "./chunk-6LX5ORAS.js";
+} from "./chunk-TMYO7B5P.js";
 import "./chunk-CULXMQJH.js";
 import "./chunk-E6K4NIEU.js";
 import "./chunk-YRMVARQP.js";
 import "./chunk-LOBRX7VD.js";
-import "./chunk-FYIYMQ5N.js";
-import "./chunk-MBJHSA7F.js";
+import "./chunk-BECYBZLX.js";
 import "./chunk-Z5LAYHGJ.js";
-import "./chunk-MARWOCVP.js";
+import "./chunk-FYIYMQ5N.js";
 import "./chunk-DT5TVLJE.js";
-import "./chunk-DGXUHMOV.js";
-import "./chunk-LPSF4OQH.js";
 import "./chunk-4DJQYKMN.js";
+import "./chunk-MARWOCVP.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)

package/dist/retrieval-tiers.d.ts

@@ -0,0 +1,17 @@
+import { RetrievalTier } from './types.js';
+
+/**
+ * Retrieval tier ladder (issue #518).
+ *
+ * Explicit tier ordering so callers can reason about precedence without
+ * inspecting retrieval.ts internals.  The tier names are the same strings
+ * used in `RecallTierExplain.tier` and in profiling spans.
+ *
+ * The ladder is codified here as a read-only array; consumers that need
+ * "is this a valid tier?" use `RETRIEVAL_TIERS.includes(value)`.
+ */
+
+declare const RETRIEVAL_TIERS: readonly RetrievalTier[];
+declare function isRetrievalTier(value: unknown): value is RetrievalTier;
+
+export { RETRIEVAL_TIERS, isRetrievalTier };

package/dist/retrieval-tiers.js

@@ -0,0 +1,9 @@
+import {
+  RETRIEVAL_TIERS,
+  isRetrievalTier
+} from "./chunk-SOBJ6NEY.js";
+export {
+  RETRIEVAL_TIERS,
+  isRetrievalTier
+};
+//# sourceMappingURL=retrieval-tiers.js.map

package/dist/retrieval-tiers.js.map

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