@remnic/core 1.1.2 → 1.1.4

package/dist/graph-events.js

@@ -0,0 +1,14 @@
+import {
+  destroyGraphEventBus,
+  emitGraphEvent,
+  getGraphEventBus,
+  subscribeGraphEvents
+} from "./chunk-WIICJPET.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  destroyGraphEventBus,
+  emitGraphEvent,
+  getGraphEventBus,
+  subscribeGraphEvents
+};
+//# sourceMappingURL=graph-events.js.map

package/dist/graph-events.js.map

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

package/dist/graph-recall.js

@@ -2,6 +2,7 @@ import {
   runGraphRecall
 } from "./chunk-DGVM5SFL.js";
 import "./chunk-64NJRYU2.js";
+import "./chunk-PZ5AY32C.js";
 export {
   runGraphRecall
 };

package/dist/graph-retrieval.js

@@ -8,6 +8,7 @@ import {
   isNodeType,
   queryGraph
 } from "./chunk-64NJRYU2.js";
+import "./chunk-PZ5AY32C.js";
 export {
   DEFAULT_PPR_DAMPING,
   DEFAULT_PPR_ITERATIONS,

package/dist/graph-snapshot.d.ts

@@ -0,0 +1,112 @@
+import { GraphType } from './graph.js';
+
+/**
+ * Graph snapshot — read-only view of the multi-graph memory adjacency
+ * (issue #691 PR 2/5).
+ *
+ * Composes the JSONL edge store from `graph.ts` with optional node-metadata
+ * loading so HTTP / MCP / future CLI surfaces can return a consistent
+ * `{ nodes, edges, generatedAt }` shape suitable for the admin pane scaffold
+ * shipped in PR 1/5.
+ *
+ * All inputs are validated and clamped at this layer so the access surface
+ * (which is responsible for HTTP/MCP-flavored errors) can keep the wiring
+ * thin.  The module is pure async I/O — no global state, no caches.
+ */
+
+/** Default `limit` when the caller omits it. */
+declare const GRAPH_SNAPSHOT_DEFAULT_LIMIT = 500;
+/** Hard upper bound on `limit` to keep responses sized for the admin pane. */
+declare const GRAPH_SNAPSHOT_MAX_LIMIT = 5000;
+/** Categories accepted by the `categories` filter; matches `MemoryFile.frontmatter.category`. */
+type GraphSnapshotCategory = string;
+interface GraphSnapshotNode {
+    /** Stable identifier — relative memory path (matches `GraphEdge.from` / `to`). */
+    id: string;
+    /** Short human label.  Falls back to the basename when no metadata is available. */
+    label: string;
+    /** Memory category (e.g. `fact`, `decision`, `entity`).  `"unknown"` when metadata is missing. */
+    kind: string;
+    /** Aggregate edge confidence touching this node, used for sizing in the admin pane. */
+    score: number;
+    /** Most recent edge timestamp (ISO) touching this node — best-effort recency signal. */
+    lastUpdated: string | null;
+}
+interface GraphSnapshotEdge {
+    source: string;
+    target: string;
+    kind: GraphType;
+    /** Edge confidence in [0, 1]; legacy edges without confidence return 1.0. */
+    confidence: number;
+}
+interface GraphSnapshotResponse {
+    nodes: GraphSnapshotNode[];
+    edges: GraphSnapshotEdge[];
+    generatedAt: string;
+}
+interface GraphSnapshotRequest {
+    /** Max number of edges to include (after filtering).  Default 500, max 5000. */
+    limit?: number;
+    /** Inclusive lower bound on edge `ts` (ISO string).  Edges older than this are dropped. */
+    since?: string;
+    /** When set, restrict the snapshot to the focus node and its direct neighbors. */
+    focusNodeId?: string;
+    /**
+     * Optional category allow-list.  Edges are kept only when both endpoints
+     * resolve to nodes whose category falls in this set; nodes are kept only
+     * when their category matches.  When omitted, no category filter is applied.
+     */
+    categories?: GraphSnapshotCategory[];
+}
+/**
+ * Loader contract: given a relative memory path, return `{ category, label,
+ * updated }` or `null` when the memory cannot be resolved.  Implementations
+ * typically wrap `StorageManager.readMemoryByPath`; the snapshot module stays
+ * agnostic so tests can pass a synchronous in-memory map.
+ */
+type GraphSnapshotNodeLoader = (relPath: string) => Promise<GraphSnapshotNodeMetadata | null>;
+interface GraphSnapshotNodeMetadata {
+    /** Memory category, e.g. `fact` / `decision` / `entity`. */
+    category: string;
+    /** Display label — usually the memory id or the entity name. */
+    label: string;
+    /** ISO `updated` timestamp from frontmatter, when available. */
+    updated?: string;
+}
+/**
+ * Coerce a caller-supplied limit into the `[1, GRAPH_SNAPSHOT_MAX_LIMIT]` range.
+ *
+ * - `undefined` / `null` → `GRAPH_SNAPSHOT_DEFAULT_LIMIT`.
+ * - non-finite or non-integer → throws `Error` (callers translate to 400).
+ * - `<= 0` → throws.
+ * - `> GRAPH_SNAPSHOT_MAX_LIMIT` → clamped to the max (no error — admin
+ *   panel callers send liberal limits).
+ */
+declare function normalizeGraphSnapshotLimit(raw: unknown): number;
+/**
+ * Validate and parse an ISO timestamp into a millisecond epoch.  Throws
+ * when the input cannot be parsed; callers translate to a 400.  `undefined`
+ * input yields `undefined`.
+ */
+declare function parseGraphSnapshotSince(raw: string | undefined): number | undefined;
+/**
+ * Build a `GraphSnapshotResponse` from the raw edge JSONL on disk plus an
+ * optional node-metadata loader.
+ *
+ * The function is split into pure subroutines so HTTP / MCP / tests can
+ * exercise the same logic without spinning up a full `StorageManager`.
+ */
+declare function buildGraphSnapshot(opts: {
+    memoryDir: string;
+    graphConfig: {
+        entityGraphEnabled: boolean;
+        timeGraphEnabled: boolean;
+        causalGraphEnabled: boolean;
+    };
+    request: GraphSnapshotRequest;
+    loadNode: GraphSnapshotNodeLoader;
+    /** Override clock for deterministic tests. */
+    now?: () => Date;
+}): Promise<GraphSnapshotResponse>;
+
+export { GRAPH_SNAPSHOT_DEFAULT_LIMIT, GRAPH_SNAPSHOT_MAX_LIMIT, type GraphSnapshotCategory, type GraphSnapshotEdge, type GraphSnapshotNode, type GraphSnapshotNodeLoader, type GraphSnapshotNodeMetadata, type GraphSnapshotRequest, type GraphSnapshotResponse, buildGraphSnapshot, normalizeGraphSnapshotLimit, parseGraphSnapshotSince };

package/dist/graph-snapshot.js

@@ -0,0 +1,19 @@
+import {
+  GRAPH_SNAPSHOT_DEFAULT_LIMIT,
+  GRAPH_SNAPSHOT_MAX_LIMIT,
+  buildGraphSnapshot,
+  normalizeGraphSnapshotLimit,
+  parseGraphSnapshotSince
+} from "./chunk-PCUKNJAZ.js";
+import "./chunk-RK2Y4XOM.js";
+import "./chunk-2LSZVONP.js";
+import "./chunk-WIICJPET.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  GRAPH_SNAPSHOT_DEFAULT_LIMIT,
+  GRAPH_SNAPSHOT_MAX_LIMIT,
+  buildGraphSnapshot,
+  normalizeGraphSnapshotLimit,
+  parseGraphSnapshotSince
+};
+//# sourceMappingURL=graph-snapshot.js.map

package/dist/graph-snapshot.js.map

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

package/dist/graph.d.ts

@@ -17,6 +17,8 @@ interface GraphEdge {
     weight: number;
     label: string;
     ts: string;
+    confidence?: number;
+    lastReinforcedAt?: string;
 }
 interface GraphConfig {
     multiGraphMemoryEnabled: boolean;
@@ -29,17 +31,57 @@ interface GraphConfig {
     graphLateralInhibitionEnabled: boolean;
     graphLateralInhibitionBeta: number;
     graphLateralInhibitionTopM: number;
+    /**
+     * Issue #681 PR 3/3 — minimum edge confidence required for traversal.
+     * Edges with confidence below this floor are pruned. Legacy edges
+     * (no `confidence` field) are treated as 1.0 and always pass.
+     * Range `[0, 1]`. Default 0.2.
+     */
+    graphTraversalConfidenceFloor: number;
+    /**
+     * Issue #681 PR 3/3 — number of PageRank-style refinement iterations
+     * applied on top of BFS activation. Set to 0 to disable refinement
+     * and return raw BFS scores. Default 8.
+     */
+    graphTraversalPageRankIterations: number;
 }
+/** Default minimum edge confidence required for traversal (issue #681 PR 3/3). */
+declare const DEFAULT_GRAPH_TRAVERSAL_CONFIDENCE_FLOOR = 0.2;
+/** Default PageRank-style refinement iteration count (issue #681 PR 3/3). */
+declare const DEFAULT_GRAPH_TRAVERSAL_PAGERANK_ITERATIONS = 8;
 declare const CAUSAL_PHRASES: string[];
 declare function graphsDir(memoryDir: string): string;
 declare function graphFilePath(memoryDir: string, type: GraphType): string;
 declare function ensureGraphsDir(memoryDir: string): Promise<void>;
+/**
+ * Run `fn` while holding the write lock for the given graph JSONL file.
+ *
+ * The lock is keyed by absolute file path so concurrent writes to
+ * different graph types proceed independently. The chain recovers from
+ * rejection (gotcha #40) so a single I/O failure does not poison all
+ * future writers, but the original error is still surfaced to the
+ * caller of `withGraphWriteLock`.
+ */
+declare function withGraphWriteLock<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
 declare function appendEdge(memoryDir: string, edge: GraphEdge): Promise<void>;
 /**
  * Read all edges of a given type from the JSONL file.
- * Returns [] if the file doesn't exist or is corrupt (fail-open).
+ * Returns [] if the file doesn't exist or any read error occurs (fail-open).
+ *
+ * Production traversal callers (recall/PageRank) depend on this fail-open
+ * posture so a temporarily missing or unreadable graph file never blocks
+ * a recall. Maintenance jobs that need to distinguish ENOENT from real
+ * I/O failures must use {@link readEdgesStrict} instead.
  */
 declare function readEdges(memoryDir: string, type: GraphType): Promise<GraphEdge[]>;
+/**
+ * Same as {@link readEdges} but only swallows `ENOENT`; all other read
+ * errors (`EACCES`, `EIO`, …) are propagated. Used by the graph-edge
+ * decay maintenance job so I/O outages surface as a failed run instead
+ * of being silently reported as "no edges to decay" (issue #729 /
+ * Codex P1, line 120).
+ */
+declare function readEdgesStrict(memoryDir: string, type: GraphType): Promise<GraphEdge[]>;
 /**
  * Read edges from all enabled graph types.
  */
@@ -119,22 +161,78 @@ declare class GraphIndex {
      * Spreading activation BFS (SYNAPSE-inspired).
      *
      * Starting from `seeds`, traverse the combined graph for up to `maxSteps` hops.
-     * Each candidate gets an activation score = edge.weight × decay^hop.
-     * Returns top-N candidate paths sorted by descending activation score.
+     * Each candidate gets an activation score = edge.weight × edgeConfidence × decay^hop.
      *
-     * @param seeds   - initial memory paths to expand from (e.g. QMD top results)
+     * Issue #681 PR 3/3 — confidence-aware traversal:
+     *   - Each edge's `weight` is multiplied by its `confidence` (legacy edges
+     *     missing `confidence` are treated as 1.0, preserving prior behavior).
+     *   - Edges with `confidence < graphTraversalConfidenceFloor` are pruned and
+     *     contribute neither activation nor downstream neighbors.
+     *   - When `graphTraversalPageRankIterations > 0`, an additional PageRank-
+     *     style refinement pass redistributes activation along confidence-weighted
+     *     edges, sharpening the ranking among multi-hop candidates.
+     *   - Per-result provenance includes the highest-confidence edge that landed
+     *     on each candidate, so the X-ray surface can attribute pruning and
+     *     ranking decisions back to specific edges.
+     *
+     * @param seeds    - initial memory paths to expand from (e.g. QMD top results)
      * @param maxSteps - max BFS hops (from config: maxGraphTraversalSteps)
-     * @returns Array of {path, score} sorted descending, not including seed paths
+     * @returns Array of {path, score, edgeConfidence, ...} sorted descending, not including seed paths
      */
-    spreadingActivation(seeds: string[], maxSteps?: number): Promise<Array<{
+    spreadingActivation(seeds: string[], maxSteps?: number, opts?: {
+        /**
+         * Issue #681 — when `true`, bypasses the configured
+         * `graphTraversalConfidenceFloor` and includes low-confidence
+         * edges in traversal.  Equivalent to forcing the floor to `0`.
+         * Default `false` (floor from config is applied).
+         */
+        includeLowConfidence?: boolean;
+    }): Promise<Array<{
         path: string;
         score: number;
         seed: string;
         hopDepth: number;
         decayedWeight: number;
         graphType: "entity" | "time" | "causal";
+        /**
+         * Confidence of the edge that produced this candidate's recorded
+         * provenance (the strongest edge along the chosen entry path).
+         * In `[0, 1]`. Legacy edges without `confidence` surface as 1.0.
+         */
+        edgeConfidence: number;
     }>>;
 }
+/**
+ * Clamp `graphTraversalConfidenceFloor` into the legal range `[0, 1]`.
+ * Non-finite or non-numeric values fall back to the documented default
+ * so misconfiguration cannot silently disable the floor or reject every edge.
+ *
+ * Exported for tests; call sites in `spreadingActivation` use it to make
+ * the contract explicit at every boundary.
+ */
+declare function clampConfidenceFloor(raw: unknown): number;
+/**
+ * Clamp `graphTraversalPageRankIterations` into a non-negative integer.
+ * Negative or non-finite values fall back to 0 (disable refinement) so
+ * misconfiguration cannot stall recall in an unbounded loop.
+ */
+declare function clampPageRankIterations(raw: unknown): number;
+/**
+ * PageRank-style refinement on top of the BFS activation map.
+ *
+ * Each iteration redistributes a fraction of every node's score along
+ * its outgoing edges, scaled by edge confidence. Confidence below
+ * `floor` is filtered out before redistribution, mirroring the BFS
+ * pruning rule. Mutates `scores` in place.
+ *
+ * Exported for tests; in production, call sites pass the same adjacency
+ * map already used by BFS so behavior stays consistent.
+ */
+declare function applyPageRankRefinement(scores: Map<string, number>, adj: Map<string, GraphEdge[]>, opts: {
+    iterations: number;
+    floor: number;
+    damping: number;
+}): void;
 /**
  * Lateral inhibition (Synapse-inspired).
  *
@@ -154,4 +252,4 @@ declare function applyLateralInhibition(scores: Map<string, number>, opts: {
     topM: number;
 }): Map<string, number>;
 
-export { CAUSAL_PHRASES, type GraphConfig, type GraphEdge, type GraphHealthFileStats, type GraphHealthReport, GraphIndex, type GraphType, analyzeGraphHealth, appendEdge, applyLateralInhibition, detectCausalPhrase, ensureGraphsDir, graphFilePath, graphsDir, readAllEdges, readEdges };
+export { CAUSAL_PHRASES, DEFAULT_GRAPH_TRAVERSAL_CONFIDENCE_FLOOR, DEFAULT_GRAPH_TRAVERSAL_PAGERANK_ITERATIONS, type GraphConfig, type GraphEdge, type GraphHealthFileStats, type GraphHealthReport, GraphIndex, type GraphType, analyzeGraphHealth, appendEdge, applyLateralInhibition, applyPageRankRefinement, clampConfidenceFloor, clampPageRankIterations, detectCausalPhrase, ensureGraphsDir, graphFilePath, graphsDir, readAllEdges, readEdges, readEdgesStrict, withGraphWriteLock };

package/dist/graph.js

@@ -1,27 +1,44 @@
 import {
   CAUSAL_PHRASES,
+  DEFAULT_GRAPH_TRAVERSAL_CONFIDENCE_FLOOR,
+  DEFAULT_GRAPH_TRAVERSAL_PAGERANK_ITERATIONS,
   GraphIndex,
   analyzeGraphHealth,
   appendEdge,
   applyLateralInhibition,
+  applyPageRankRefinement,
+  clampConfidenceFloor,
+  clampPageRankIterations,
   detectCausalPhrase,
   ensureGraphsDir,
   graphFilePath,
   graphsDir,
   readAllEdges,
-  readEdges
-} from "./chunk-C2EFFULQ.js";
+  readEdges,
+  readEdgesStrict,
+  withGraphWriteLock
+} from "./chunk-RK2Y4XOM.js";
+import "./chunk-2LSZVONP.js";
+import "./chunk-WIICJPET.js";
+import "./chunk-PZ5AY32C.js";
 export {
   CAUSAL_PHRASES,
+  DEFAULT_GRAPH_TRAVERSAL_CONFIDENCE_FLOOR,
+  DEFAULT_GRAPH_TRAVERSAL_PAGERANK_ITERATIONS,
   GraphIndex,
   analyzeGraphHealth,
   appendEdge,
   applyLateralInhibition,
+  applyPageRankRefinement,
+  clampConfidenceFloor,
+  clampPageRankIterations,
   detectCausalPhrase,
   ensureGraphsDir,
   graphFilePath,
   graphsDir,
   readAllEdges,
-  readEdges
+  readEdges,
+  readEdgesStrict,
+  withGraphWriteLock
 };
 //# sourceMappingURL=graph.js.map

package/dist/harmonic-retrieval.js

@@ -7,6 +7,7 @@ import "./chunk-NGAVDO7E.js";
 import "./chunk-DT5TVLJE.js";
 import "./chunk-DGXUHMOV.js";
 import "./chunk-LPSF4OQH.js";
+import "./chunk-PZ5AY32C.js";
 export {
   searchHarmonicRetrieval
 };

package/dist/himem.js

@@ -1,6 +1,7 @@
 import {
   classifyMemoryKind
 } from "./chunk-YAZNBMNF.js";
+import "./chunk-PZ5AY32C.js";
 export {
   classifyMemoryKind
 };

package/dist/hygiene.js

@@ -2,6 +2,7 @@ import {
   lintWorkspaceFiles,
   rotateMarkdownFileToArchive
 } from "./chunk-DM2T26WE.js";
+import "./chunk-PZ5AY32C.js";
 export {
   lintWorkspaceFiles,
   rotateMarkdownFileToArchive

package/dist/identity-continuity.js

@@ -7,6 +7,7 @@ import {
   serializeContinuityIncident,
   upsertContinuityLoopInMarkdown
 } from "./chunk-QSVPYQPG.js";
+import "./chunk-PZ5AY32C.js";
 export {
   closeContinuityIncidentRecord,
   createContinuityIncidentRecord,

package/dist/importance.js

@@ -4,6 +4,7 @@ import {
   rescoreMemoryImportance,
   scoreImportance
 } from "./chunk-JXS5PDQ7.js";
+import "./chunk-PZ5AY32C.js";
 export {
   importanceLevel,
   isAboveImportanceThreshold,