@remnic/core 1.1.0 → 1.1.1

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/resume-bundles.js

@@ -4,20 +4,20 @@ import {
   recordResumeBundle,
   resolveResumeBundleDir,
   validateResumeBundle
-} from "./chunk-6LX5ORAS.js";
+} from "./chunk-KUB6JU6H.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-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)

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":[]}