@remnic/core 1.1.0 → 1.1.1

package/dist/extraction-judge-training.d.ts

@@ -0,0 +1,85 @@
+import { JudgeVerdictKind } from './extraction-judge.js';
+import './types.js';
+import './local-llm.js';
+import './model-registry.js';
+import './fallback-llm.js';
+
+/**
+ * Extraction Judge Training Data Shim (issue #562, PR 4).
+ *
+ * Opt-in collector for `(candidate_text, verdict_kind, reason,
+ * ground_truth_label?)` tuples. Rows are appended to JSONL files under
+ * `~/.remnic/judge-training/<YYYY-MM-DD>.jsonl` so operators can ship the
+ * data into a future GRPO training pipeline without exfiltrating live
+ * memory content through the regular observation ledger.
+ *
+ * Gating:
+ *   - Off by default. Must be explicitly enabled via
+ *     `collectJudgeTrainingPairs: true` in plugin config.
+ *   - The ground-truth label is always optional — labels are added out-of-
+ *     band once reviewers disambiguate the candidate's fate.
+ *
+ * Privacy: the row carries only what the judge already sees — the
+ * candidate text and its metadata. It does NOT carry session keys,
+ * principal IDs, or any user identifiers. The file lives in the user's
+ * home directory rather than the shared memory directory so it is never
+ * committed, sync'd, or bundled into exports.
+ */
+
+/**
+ * Persisted training row. Intentionally minimal: just the signal needed
+ * to train a judge replacement policy. Schema version is tagged so future
+ * readers can migrate older rows.
+ */
+interface JudgeTrainingPair {
+    version: 1;
+    ts: string;
+    candidateText: string;
+    candidateCategory: string;
+    candidateConfidence?: number;
+    verdictKind: JudgeVerdictKind;
+    reason: string;
+    /**
+     * Number of prior deferrals when the verdict was resolved. `0` for the
+     * first resolution; only set when known (defer pathway).
+     */
+    priorDeferrals?: number;
+    /**
+     * Optional human-applied ground-truth label. Added after the fact by a
+     * reviewer / labelling script; not present on fresh rows.
+     */
+    groundTruthLabel?: JudgeVerdictKind;
+}
+interface JudgeTrainingOptions {
+    enabled: boolean;
+    /**
+     * Override for the output directory. Defaults to
+     * `~/.remnic/judge-training`. Tests pass a temp path here.
+     */
+    directory?: string;
+}
+declare function resolveTrainingDir(options: JudgeTrainingOptions): string;
+declare function trainingFilePathFor(directory: string, iso: string): string;
+/**
+ * Append a single training row. Fails open — write errors are logged at
+ * debug level and swallowed, same policy as the telemetry emitter.
+ * No-op when `options.enabled` is false.
+ */
+declare function recordJudgeTrainingPair(row: JudgeTrainingPair, options: JudgeTrainingOptions): Promise<void>;
+/**
+ * Read all training rows from the configured directory. Returns an empty
+ * array when the directory is missing. Malformed lines are skipped and
+ * counted in the returned `malformed` tally.
+ */
+declare function readJudgeTrainingPairs(options: Pick<JudgeTrainingOptions, "directory">): Promise<{
+    rows: JudgeTrainingPair[];
+    malformed: number;
+}>;
+/**
+ * Structural validator matching the persisted schema. Forward-compat: an
+ * unknown `verdictKind` string is treated as malformed (strict training
+ * signal — we do not want to admit unlabelled gibberish into a trainer).
+ */
+declare function isValidTrainingPair(value: unknown): value is JudgeTrainingPair;
+
+export { type JudgeTrainingOptions, type JudgeTrainingPair, isValidTrainingPair, readJudgeTrainingPairs, recordJudgeTrainingPair, resolveTrainingDir, trainingFilePathFor };

package/dist/extraction-judge-training.js

@@ -0,0 +1,16 @@
+import {
+  isValidTrainingPair,
+  readJudgeTrainingPairs,
+  recordJudgeTrainingPair,
+  resolveTrainingDir,
+  trainingFilePathFor
+} from "./chunk-DF3RVK3X.js";
+import "./chunk-2ODBA7MQ.js";
+export {
+  isValidTrainingPair,
+  readJudgeTrainingPairs,
+  recordJudgeTrainingPair,
+  resolveTrainingDir,
+  trainingFilePathFor
+};
+//# sourceMappingURL=extraction-judge-training.js.map

package/dist/extraction-judge-training.js.map

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

package/dist/extraction-judge.d.ts

@@ -26,10 +26,87 @@ interface JudgeCandidate {
     /** Local importance level, set by caller before judging. */
     importanceLevel?: ImportanceLevel;
 }
+/**
+ * Verdict kinds (issue #562, PR 1).
+ *
+ * - `"accept"`: fact is durable, persist it.
+ * - `"reject"`: fact is not durable, drop it.
+ * - `"defer"`: fact is ambiguous; push it back into the buffer for another
+ *   pass with fresh context. Inspired by MemReader (arxiv 2604.07877).
+ *
+ * PR 1 only introduces the type. No emit path produces `"defer"` yet — the
+ * defer-capable prompt, buffer re-routing, telemetry, and GRPO data
+ * collection are landing in PRs 2, 3, and 4 respectively.
+ */
+type JudgeVerdictKind = "accept" | "reject" | "defer";
+/**
+ * Judge verdict shape.
+ *
+ * Back-compat note: `kind` is optional. Verdicts serialized before PR 1
+ * (both in-memory cache entries and any persisted caches) only carry
+ * `{ durable, reason }`. Downstream consumers must either read `durable`
+ * directly, or use {@link getVerdictKind} / {@link isDurableVerdict} which
+ * gracefully fall back to the boolean when `kind` is missing, and ignore
+ * unknown future `kind` values rather than crashing.
+ */
 interface JudgeVerdict {
+    /**
+     * True iff the fact should be persisted. For `"defer"` verdicts this is
+     * `false` — a deferred fact is not (yet) persisted, so callers that only
+     * look at `durable` will treat defer as "skip this turn", which matches
+     * the pre-PR-1 fail-closed behavior for non-accepted verdicts.
+     */
     durable: boolean;
     reason: string;
+    /**
+     * Optional explicit verdict kind. Added in PR 1 of issue #562. Legacy
+     * verdicts (including cache entries produced before this field existed)
+     * do not set `kind`; use {@link getVerdictKind} to read this safely.
+     */
+    kind?: JudgeVerdictKind;
 }
+/**
+ * Resolve a verdict's effective kind.
+ *
+ * - If `kind` is explicitly set to one of the known values, return it.
+ * - If `kind` is absent, infer from `durable` (back-compat with pre-PR-1
+ *   cache entries and emit paths that have not been updated yet).
+ * - If `kind` is set to an unrecognised value (forward-compat, e.g. a
+ *   future cache entry loaded by an older build), fall back to `durable`
+ *   so we never crash on unknown strings.
+ */
+declare function getVerdictKind(verdict: JudgeVerdict): JudgeVerdictKind;
+/**
+ * Type guard: returns `true` only for verdicts that should be persisted.
+ * Treats both `"reject"` and `"defer"` as "not durable" — defer means the
+ * caller should re-evaluate later, not write now.
+ */
+declare function isDurableVerdict(verdict: JudgeVerdict): boolean;
+/**
+ * Validate a cache entry loaded from persistence / another process.
+ *
+ * Strict: accepts legacy `{ durable, reason }` entries and new entries
+ * whose `kind` is one of the three known `JudgeVerdictKind` values.
+ * Rejects structurally wrong types and unknown `kind` strings so the
+ * type-guard narrowing is sound — callers that receive
+ * `value is JudgeVerdict` can safely treat `kind` as the declared
+ * union.
+ *
+ * Forward-compat is handled by {@link normalizeCachedVerdict}, which
+ * drops unknown `kind` strings before validation so a newer build's
+ * cache entry still loads instead of being rejected.
+ */
+declare function isValidCachedVerdict(value: unknown): value is JudgeVerdict;
+/**
+ * Forward-compatible cache-entry loader.
+ *
+ * Drops unknown `kind` strings to `undefined` (so `getVerdictKind` can
+ * fall back to `durable`), then validates structurally. Non-string
+ * `kind` values are still treated as structural violations and rejected.
+ * Returns the sanitised verdict, or `null` when the entry is structurally
+ * unusable.
+ */
+declare function normalizeCachedVerdict(value: unknown): JudgeVerdict | null;
 interface JudgeBatchResult {
     verdicts: Map<number, JudgeVerdict>;
     /** Number of verdicts served from cache. */
@@ -38,6 +115,45 @@ interface JudgeBatchResult {
     judged: number;
     /** Total wall-clock time in milliseconds. */
     elapsed: number;
+    /**
+     * Number of verdicts in this batch that resolved to `"defer"` (issue #562,
+     * PR 2). Callers can use this to decide whether to retain buffer turns for
+     * the next extraction pass.
+     */
+    deferred: number;
+    /**
+     * Number of defers that were forcibly converted to `"reject"` because the
+     * same candidate text had already been deferred at least
+     * `extractionJudgeMaxDeferrals` times. Rolled out of `deferred` — a
+     * candidate counted here is *not* also in `deferred`.
+     */
+    deferredCappedToReject: number;
+}
+/**
+ * Per-verdict observation emitted by `judgeFactDurability` when an
+ * `onVerdict` callback is supplied (issue #562, PR 3). Used to wire the
+ * observation ledger / telemetry stream without coupling the judge module
+ * directly to filesystem I/O. One event is emitted for every resolved
+ * verdict, including auto-approved and cache-hit paths.
+ */
+interface JudgeVerdictObservation {
+    verdict: JudgeVerdict;
+    /** The original `JudgeCandidate` passed in (same reference). */
+    candidate: JudgeCandidate;
+    /** SHA-256 of `text\0category`, same key the cache/deferCounter use. */
+    contentHash: string;
+    /** Verdict resolution path. Useful for debugging + dashboards. */
+    source: "auto-approve" | "cache" | "llm" | "llm-cap-rejected" | "fail-open";
+    /**
+     * How many times this candidate had already been deferred before this
+     * verdict resolved. 0 when the candidate had never been deferred.
+     */
+    priorDeferrals: number;
+    /**
+     * Milliseconds from batch start to now. Shared across verdicts emitted in
+     * the same batch.
+     */
+    elapsedMs: number;
 }
 /**
  * Deterministic gate for extracted `procedure` memories: ≥2 steps with non-empty
@@ -55,12 +171,18 @@ declare function validateProcedureExtraction(input: {
  * checked against an in-memory content-hash cache, and sent to the LLM
  * for verdict.
  */
-declare function judgeFactDurability(candidates: JudgeCandidate[], config: PluginConfig, localLlm: LocalLlmClient | null, fallbackLlm: FallbackLlmClient | null, cache?: Map<string, JudgeVerdict>): Promise<JudgeBatchResult>;
+declare function judgeFactDurability(candidates: JudgeCandidate[], config: PluginConfig, localLlm: LocalLlmClient | null, fallbackLlm: FallbackLlmClient | null, cache?: Map<string, JudgeVerdict>, deferCounts?: Map<string, number>, onVerdict?: (observation: JudgeVerdictObservation) => void): Promise<JudgeBatchResult>;
 /** Clear the in-memory default verdict cache. Primarily for tests. */
 declare function clearVerdictCache(): void;
 /** Return the current default verdict cache size. Primarily for tests. */
 declare function verdictCacheSize(): number;
 /** Create a new per-instance verdict cache. Orchestrators should hold one. */
 declare function createVerdictCache(): Map<string, JudgeVerdict>;
+/**
+ * Create a new per-instance defer-counter map. Orchestrators should hold one
+ * alongside their verdict cache so defer counts survive across extraction
+ * passes within a single orchestrator but do not leak across orchestrators.
+ */
+declare function createDeferCountMap(): Map<string, number>;
 
-export { type JudgeBatchResult, type JudgeCandidate, type JudgeVerdict, clearVerdictCache, createVerdictCache, judgeFactDurability, validateProcedureExtraction, verdictCacheSize };
+export { type JudgeBatchResult, type JudgeCandidate, type JudgeVerdict, type JudgeVerdictKind, type JudgeVerdictObservation, clearVerdictCache, createDeferCountMap, createVerdictCache, getVerdictKind, isDurableVerdict, isValidCachedVerdict, judgeFactDurability, normalizeCachedVerdict, validateProcedureExtraction, verdictCacheSize };

package/dist/extraction-judge.js

@@ -1,17 +1,27 @@
 import {
   clearVerdictCache,
+  createDeferCountMap,
   createVerdictCache,
+  getVerdictKind,
+  isDurableVerdict,
+  isValidCachedVerdict,
   judgeFactDurability,
+  normalizeCachedVerdict,
   validateProcedureExtraction,
   verdictCacheSize
-} from "./chunk-LAYN4LDC.js";
+} from "./chunk-C4SQJZAF.js";
 import "./chunk-UZB5KHKX.js";
 import "./chunk-QDW3E4RD.js";
 import "./chunk-2ODBA7MQ.js";
 export {
   clearVerdictCache,
+  createDeferCountMap,
   createVerdictCache,
+  getVerdictKind,
+  isDurableVerdict,
+  isValidCachedVerdict,
   judgeFactDurability,
+  normalizeCachedVerdict,
   validateProcedureExtraction,
   verdictCacheSize
 };

package/dist/extraction.js

@@ -1,18 +1,19 @@
 import {
   ExtractionEngine
-} from "./chunk-3SV6CQHO.js";
-import "./chunk-UEYA6UC7.js";
+} from "./chunk-S3EEFKNY.js";
+import "./chunk-NZLQTHS5.js";
+import "./chunk-54V4BZWP.js";
 import "./chunk-NBNN5GOB.js";
 import "./chunk-FEMOX5AD.js";
 import "./chunk-JL2PU6AI.js";
-import "./chunk-GZCUW5IC.js";
 import "./chunk-VEWZZM3H.js";
+import "./chunk-GZCUW5IC.js";
 import "./chunk-LK6SGL53.js";
 import "./chunk-EJI5XIBB.js";
-import "./chunk-44ICJRF3.js";
+import "./chunk-3GXCSUXR.js";
 import "./chunk-XZ2TIKGC.js";
-import "./chunk-Y27UJK6V.js";
 import "./chunk-ODWDQNRE.js";
+import "./chunk-Y27UJK6V.js";
 import "./chunk-UZB5KHKX.js";
 import "./chunk-MARWOCVP.js";
 import "./chunk-EEQLFRUM.js";

package/dist/fallback-llm.js

@@ -1,9 +1,9 @@
 import {
   FallbackLlmClient
-} from "./chunk-44ICJRF3.js";
+} from "./chunk-3GXCSUXR.js";
 import "./chunk-XZ2TIKGC.js";
-import "./chunk-Y27UJK6V.js";
 import "./chunk-ODWDQNRE.js";
+import "./chunk-Y27UJK6V.js";
 import "./chunk-UZB5KHKX.js";
 import "./chunk-MARWOCVP.js";
 import "./chunk-2ODBA7MQ.js";

package/dist/graph-recall.d.ts

@@ -0,0 +1,100 @@
+import { MemoryEdgeSource, RemnicGraph } from './graph-retrieval.js';
+
+/**
+ * Graph-based retrieval integration (issue #559 PR 4 of 5).
+ *
+ * Pure helper that composes `extractGraphEdges` (PR 2) and `queryGraph`
+ * (PR 3) into a single retrieval surface. Operators opt in via the
+ * `recallGraphEnabled` config flag; until the `retrieval-graph` bench in
+ * PR 5 justifies flipping the default, this tier ships disabled.
+ *
+ * Kept as a pure function so the orchestrator can call it with whatever
+ * candidate pool it has (hot cache, recent window, QMD first-pass, etc.)
+ * without forcing a specific storage contract on this module.
+ */
+
+/**
+ * Subset of `PluginConfig` that governs the graph retrieval tier. Kept
+ * as a local interface so this module does not pull in the full
+ * `PluginConfig` import — `orchestrator.ts` can pass the fields directly.
+ */
+interface GraphRecallConfig {
+    /** Master enable flag. When false, `runGraphRecall` is a no-op. */
+    recallGraphEnabled: boolean;
+    /** PPR damping factor (default 0.85). */
+    recallGraphDamping: number;
+    /** PPR power-iteration cap (default 20). */
+    recallGraphIterations: number;
+    /**
+     * Max memories the graph tier returns. `0` disables the tier's
+     * contribution without touching `recallGraphEnabled`.
+     */
+    recallGraphTopK: number;
+}
+/** Per-invocation options for `runGraphRecall`. */
+interface GraphRecallOptions {
+    /**
+     * Candidate memories to build the graph from. Typically the caller's
+     * recall candidate pool (hot cache + QMD first-pass). The extractor
+     * reads only the fields declared on `MemoryEdgeSource` — callers can
+     * safely pass richer memory objects.
+     */
+    memories: readonly MemoryEdgeSource[];
+    /**
+     * Seed memory / entity ids produced by the query-to-graph matcher.
+     * Typically the ids of the top QMD hits plus any entity-exact matches.
+     * If empty, PPR falls back to a uniform distribution over graph nodes.
+     */
+    seedIds: readonly string[];
+    /**
+     * Optional per-seed weights. When provided, PPR starts from the
+     * weighted distribution instead of uniform-over-seeds.
+     */
+    seedWeights?: ReadonlyMap<string, number> | Readonly<Record<string, number>>;
+}
+/** A single result from the graph tier. */
+interface GraphRecallResult {
+    /** Memory id (the `to` of the highest-scoring `memory`-typed node). */
+    id: string;
+    /** PPR score in [0, 1]. Higher is better. */
+    score: number;
+}
+/** The full shape returned by `runGraphRecall`. */
+interface GraphRecallRun {
+    /**
+     * Whether the graph tier actually ran. `false` when `recallGraphEnabled`
+     * is `false` or `recallGraphTopK <= 0` — in both cases `results` is `[]`
+     * and `reason` indicates which gate short-circuited.
+     */
+    ran: boolean;
+    /**
+     * Memory-typed ranked results. Entity / agent nodes are filtered out
+     * because the orchestrator merges this list with memory-typed QMD
+     * results via MMR.
+     */
+    results: GraphRecallResult[];
+    /** The graph that was built (or `null` if the tier did not run). */
+    graph: RemnicGraph | null;
+    /** Debugging tag for tier-explain surfaces. */
+    reason: "ran" | "disabled" | "topk-zero" | "empty-input";
+    /** Number of power-iteration rounds that executed. */
+    iterations: number;
+    /** Whether PPR's L1 delta fell below tolerance before the iter cap. */
+    converged: boolean;
+}
+/**
+ * Pure graph retrieval run.
+ *
+ * 1. Short-circuits to `{ ran: false }` when the feature flag is off,
+ *    `topK <= 0`, or the memory pool is empty. No graph is built, no
+ *    PPR runs — this preserves the zero-cost guarantee for
+ *    `recallGraphEnabled: false` (the default).
+ * 2. Otherwise builds the retrieval graph from the candidate pool via
+ *    `buildGraphFromMemories` (PR 2 extractor).
+ * 3. Runs Personalized PageRank via `queryGraph` (PR 3).
+ * 4. Projects ranked nodes to memory-typed ids only — entity and agent
+ *    nodes never appear in the recall result set.
+ */
+declare function runGraphRecall(config: GraphRecallConfig, options: GraphRecallOptions): GraphRecallRun;
+
+export { type GraphRecallConfig, type GraphRecallOptions, type GraphRecallResult, type GraphRecallRun, runGraphRecall };

package/dist/graph-recall.js

@@ -0,0 +1,8 @@
+import {
+  runGraphRecall
+} from "./chunk-DGVM5SFL.js";
+import "./chunk-64NJRYU2.js";
+export {
+  runGraphRecall
+};
+//# sourceMappingURL=graph-recall.js.map

package/dist/graph-recall.js.map

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