@remnic/core 1.0.3 → 1.1.1

package/dist/direct-answer-wiring.d.ts

@@ -0,0 +1,77 @@
+import { MemoryFile, PluginConfig } from './types.js';
+import { TrustZoneName } from './trust-zones.js';
+import { T as Taxonomy } from './types-DJhqDJUV.js';
+import { DirectAnswerResult } from './direct-answer.js';
+
+/**
+ * Direct-answer wiring (issue #518 slice 3).
+ *
+ * Binds the pure eligibility decision (`direct-answer.ts`) to the data
+ * sources needed to build candidates: storage, trust-zones, taxonomy,
+ * and importance scoring.  Kept as a separate module so that:
+ *
+ * - The eligibility layer stays pure and unit-testable without stores.
+ * - Each caller injects its own source accessors.  The orchestrator
+ *   binding is a follow-on slice; tests here use mock sources.
+ * - The wiring is safe to ship alone — nothing calls `tryDirectAnswer`
+ *   yet, so enabling this module's presence does not change recall
+ *   behavior.  The next slice adds exactly one call site before QMD.
+ *
+ * Short-circuit contract:
+ *
+ * - When `config.recallDirectAnswerEnabled === false`, the function
+ *   returns the eligibility verdict with reason `"disabled"` without
+ *   touching any source accessor.  This is the documented default.
+ * - When enabled, the wiring cheaply drops non-trusted-zone memories
+ *   and ineligible taxonomy buckets before computing importance, so
+ *   the eligibility module sees a pre-filtered candidate set.  The
+ *   eligibility module still performs the same checks itself — this
+ *   module is purely an I/O and prefiltering layer.
+ */
+
+/**
+ * Caller-provided accessors for candidate sourcing.  Decouples the
+ * wiring from any specific storage / trust-zone / importance backend.
+ */
+interface DirectAnswerSources {
+    /**
+     * List memories eligible to be considered for direct-answer.
+     * Callers are expected to return only active, non-superseded memories
+     * in the requested namespace; the wiring will cheaply re-filter on
+     * trust zone and taxonomy bucket and hand the rest to the eligibility
+     * module, which applies the full gate ladder.
+     */
+    listCandidateMemories(options: {
+        namespace: string;
+        abortSignal?: AbortSignal;
+    }): Promise<MemoryFile[]>;
+    /**
+     * Resolve the trust-zone record for a memory.  Returns `null` when
+     * the memory has no trust-zone record (treated as not trusted).
+     */
+    trustZoneFor(memoryId: string): Promise<TrustZoneName | null>;
+    /**
+     * Resolve a calibrated importance score in [0, 1] for a memory.
+     */
+    importanceFor(memory: MemoryFile): number;
+    /**
+     * Taxonomy used to classify memories into direct-answer buckets.
+     */
+    taxonomy: Taxonomy;
+}
+interface DirectAnswerWiringInput {
+    query: string;
+    namespace: string;
+    config: Pick<PluginConfig, "recallDirectAnswerEnabled" | "recallDirectAnswerTokenOverlapFloor" | "recallDirectAnswerImportanceFloor" | "recallDirectAnswerAmbiguityMargin" | "recallDirectAnswerEligibleTaxonomyBuckets">;
+    sources: DirectAnswerSources;
+    queryEntityRefs?: string[];
+    abortSignal?: AbortSignal;
+}
+/**
+ * Attempt direct-answer resolution.  Returns the eligibility verdict
+ * produced by `isDirectAnswerEligible` with candidates materialized
+ * from the caller-supplied sources.
+ */
+declare function tryDirectAnswer(input: DirectAnswerWiringInput): Promise<DirectAnswerResult>;
+
+export { type DirectAnswerSources, type DirectAnswerWiringInput, tryDirectAnswer };

package/dist/direct-answer-wiring.js

@@ -0,0 +1,10 @@
+import {
+  tryDirectAnswer
+} from "./chunk-6AUUAZEX.js";
+import "./chunk-Y4FHOFJ2.js";
+import "./chunk-PVGDJXVK.js";
+import "./chunk-DT5TVLJE.js";
+export {
+  tryDirectAnswer
+};
+//# sourceMappingURL=direct-answer-wiring.js.map

package/dist/direct-answer-wiring.js.map

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

package/dist/direct-answer.d.ts

@@ -0,0 +1,106 @@
+import { MemoryFile } from './types.js';
+import { TrustZoneName } from './trust-zones.js';
+
+/**
+ * Direct-answer retrieval tier eligibility (issue #518 slice 2).
+ *
+ * This module is a pure decision layer.  It takes a query, a set of
+ * caller-resolved candidates (each already decorated with trust-zone,
+ * taxonomy-bucket, and importance information), and the direct-answer
+ * config, then returns an eligibility verdict.
+ *
+ * Keeping the module pure means:
+ *
+ * - Tests do not need a trust-zones store, taxonomy resolver, or importance
+ *   scorer on disk.
+ * - Slice 3 (retrieval.ts wiring) is responsible for resolving those signals
+ *   before calling in; the wiring layer decides where candidates come from
+ *   (entity index, token prefilter, etc.).  This module only decides
+ *   whether the surfaced candidates add up to a confident direct answer.
+ *
+ * Not wired into retrieval yet — see slice 3.
+ */
+
+/**
+ * Caller-supplied candidate.
+ *
+ * `trustZone`, `taxonomyBucket`, and `importanceScore` are resolved outside
+ * this module because each comes from a different subsystem.  Passing them
+ * as inputs keeps the function deterministic and easy to unit-test.
+ *
+ * `matchScore` is optional; if omitted, candidates are ranked by
+ * token-overlap ratio.  Callers that already computed a better ranking
+ * score (e.g. BM25, vector similarity) can supply it to drive the
+ * ambiguity check.
+ */
+interface DirectAnswerCandidate {
+    memory: MemoryFile;
+    trustZone: TrustZoneName | null;
+    taxonomyBucket: string | null;
+    importanceScore: number;
+    matchScore?: number;
+}
+interface DirectAnswerConfig {
+    enabled: boolean;
+    tokenOverlapFloor: number;
+    importanceFloor: number;
+    ambiguityMargin: number;
+    eligibleTaxonomyBuckets: string[];
+}
+interface DirectAnswerInput {
+    query: string;
+    candidates: DirectAnswerCandidate[];
+    config: DirectAnswerConfig;
+    /**
+     * Optional entity-ref hints resolved from the query upstream.  When
+     * supplied, a candidate with a set `entityRef` must match one of these
+     * (case-insensitive) to remain eligible.  Candidates without an
+     * `entityRef` are allowed through regardless.
+     */
+    queryEntityRefs?: string[];
+}
+type DirectAnswerReason = "disabled" | "empty-query" | "no-candidates" | "no-eligible-candidates" | "below-token-overlap-floor" | "ambiguous" | "eligible";
+interface DirectAnswerResult {
+    eligible: boolean;
+    reason: DirectAnswerReason;
+    /** Winning candidate when eligible. */
+    winner?: DirectAnswerCandidate;
+    /** Computed token-overlap ratio (0..1) of the winner. */
+    tokenOverlap?: number;
+    /**
+     * Human-readable summary suitable for
+     * `RecallTierExplain.tierReason`.
+     */
+    narrative: string;
+    /**
+     * Filter labels that eliminated at least one candidate along the way.
+     * Populated regardless of eligibility so the caller can surface the
+     * narrowing steps in `RecallTierExplain.filteredBy`.
+     */
+    filteredBy: string[];
+}
+/** Filter labels — exported so callers and tests can match them structurally. */
+declare const FILTER_LABELS: {
+    readonly nonActiveStatus: "non-active-status";
+    readonly notTrustedZone: "not-trusted-zone";
+    readonly ineligibleTaxonomyBucket: "ineligible-taxonomy-bucket";
+    readonly belowImportanceFloor: "below-importance-floor";
+    readonly entityRefMismatch: "entity-ref-mismatch";
+    readonly belowTokenOverlapFloor: "below-token-overlap-floor";
+};
+/**
+ * Determine whether a query can be served by the direct-answer tier.
+ *
+ * Decision ladder, in order:
+ *
+ *   1. config.enabled === false → "disabled"
+ *   2. empty query tokens → "empty-query"
+ *   3. empty candidates → "no-candidates"
+ *   4. hard filters drop all candidates → "no-eligible-candidates"
+ *   5. token-overlap floor drops all → "below-token-overlap-floor"
+ *   6. top two candidates within ambiguityMargin → "ambiguous"
+ *   7. otherwise → "eligible"
+ */
+declare function isDirectAnswerEligible(input: DirectAnswerInput): DirectAnswerResult;
+
+export { type DirectAnswerCandidate, type DirectAnswerConfig, type DirectAnswerInput, type DirectAnswerReason, type DirectAnswerResult, FILTER_LABELS, isDirectAnswerEligible };

package/dist/direct-answer.js

@@ -0,0 +1,10 @@
+import {
+  FILTER_LABELS,
+  isDirectAnswerEligible
+} from "./chunk-Y4FHOFJ2.js";
+import "./chunk-DT5TVLJE.js";
+export {
+  FILTER_LABELS,
+  isDirectAnswerEligible
+};
+//# sourceMappingURL=direct-answer.js.map

package/dist/direct-answer.js.map

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

package/dist/{engine-X7X3AAG3.js → engine-F3GOXGE5.js}

@@ -1,22 +1,23 @@
 import {
   CompoundingEngine,
   defaultTierMigrationCycleBudget
-} from "./chunk-JROGC36Y.js";
-import "./chunk-POMSFKTB.js";
-import "./chunk-U2IQTSBY.js";
+} from "./chunk-RGLL5SPU.js";
+import "./chunk-F5VP6YCB.js";
+import "./chunk-LTCGGW2D.js";
 import "./chunk-4KAN3GZ3.js";
-import "./chunk-6ZH4TU6I.js";
 import "./chunk-6PFRXT4K.js";
 import "./chunk-TP4FZJIZ.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-BOUYNNYD.js";
-import "./chunk-QSVPYQPG.js";
 import "./chunk-DM2T26WE.js";
+import "./chunk-QSVPYQPG.js";
 import "./chunk-M62O4P4T.js";
 import "./chunk-4DJQYKMN.js";
+import "./chunk-X6GF3FX2.js";
+import "./chunk-FAAFWE4G.js";
 import "./chunk-2ODBA7MQ.js";
 export {
   CompoundingEngine,
   defaultTierMigrationCycleBudget
 };
-//# sourceMappingURL=engine-X7X3AAG3.js.map
+//# sourceMappingURL=engine-F3GOXGE5.js.map

package/dist/engine-F3GOXGE5.js.map

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

package/dist/entity-retrieval.d.ts

@@ -1,6 +1,7 @@
 import { StorageManager } from './storage.js';
 import { PluginConfig, TranscriptEntry } from './types.js';
 import './page-versioning.js';
+import './consolidation-operator.js';
 import './memory-projection-store-DeSXPh1j.js';
 import 'better-sqlite3';
 

package/dist/entity-retrieval.js

@@ -3,20 +3,21 @@ import {
   entityIndexVersion,
   entityRecentTranscriptLookbackHours,
   readRecentEntityTranscriptEntries
-} from "./chunk-74JR4N5J.js";
+} from "./chunk-FVA6TGI3.js";
 import "./chunk-7SEAZFFB.js";
-import "./chunk-POMSFKTB.js";
-import "./chunk-U2IQTSBY.js";
+import "./chunk-F5VP6YCB.js";
+import "./chunk-LTCGGW2D.js";
 import "./chunk-4KAN3GZ3.js";
-import "./chunk-6ZH4TU6I.js";
 import "./chunk-6PFRXT4K.js";
 import "./chunk-TP4FZJIZ.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-BOUYNNYD.js";
-import "./chunk-QSVPYQPG.js";
 import "./chunk-DM2T26WE.js";
+import "./chunk-QSVPYQPG.js";
 import "./chunk-M62O4P4T.js";
 import "./chunk-4DJQYKMN.js";
+import "./chunk-X6GF3FX2.js";
+import "./chunk-FAAFWE4G.js";
 import "./chunk-2ODBA7MQ.js";
 export {
   buildEntityRecallSection,

package/dist/explicit-capture.d.ts

@@ -1,22 +1,25 @@
-import { O as Orchestrator } from './orchestrator-B9kwlCep.js';
+import { O as Orchestrator } from './orchestrator-CmJ-NTdJ.js';
 import { MemoryCategory, PluginConfig } from './types.js';
 import './buffer.js';
 import './storage.js';
 import './page-versioning.js';
+import './consolidation-operator.js';
 import './memory-projection-store-DeSXPh1j.js';
 import 'better-sqlite3';
-import './port-C1GZFv8h.js';
+import './port-BADbLZU5.js';
 import './transcript.js';
 import './session-integrity.js';
 import './summarizer.js';
 import './model-registry.js';
 import './local-llm.js';
+import './fallback-llm.js';
 import './relevance.js';
 import './negative.js';
 import './recall-state.js';
+import './recall-xray.js';
 import './session-observer-state.js';
 import './embedding-fallback.js';
-import './semantic-consolidation-DrvSYRdB.js';
+import './semantic-consolidation-CxJU6MJk.js';
 import './codex-materialize-CQlLTzke.js';
 import './logger.js';
 import 'zod';

package/dist/explicit-capture.js

@@ -7,8 +7,8 @@ import {
   shouldSkipImplicitExtraction,
   stripInlineExplicitCaptureNotes,
   validateExplicitCaptureInput
-} from "./chunk-QDYXG4CS.js";
-import "./chunk-QNJMBKFK.js";
+} from "./chunk-3FPTCC3Z.js";
+import "./chunk-2LGMW3DJ.js";
 import "./chunk-M62O4P4T.js";
 export {
   hasInlineExplicitCaptureMarkup,

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

@@ -0,0 +1,113 @@
+import { JudgeVerdictKind } from './extraction-judge.js';
+import './types.js';
+import './local-llm.js';
+import './model-registry.js';
+import './fallback-llm.js';
+
+/**
+ * Extraction Judge Telemetry (issue #562, PR 3).
+ *
+ * Appends one structured event per judge verdict to the observation ledger
+ * under a dedicated JSONL file. The ledger is the same directory used by
+ * the turn-count observation writer
+ * (`state/observation-ledger/rebuilt-observations.jsonl`) but judge events
+ * live in their own file so aggregation stays cheap and schemas do not
+ * collide.
+ *
+ * Emit path is best-effort and fail-open: a telemetry write must never
+ * block an extraction run.
+ */
+
+/**
+ * Observation-ledger category for judge verdict events. Callers that
+ * aggregate across event kinds can filter on this constant.
+ */
+declare const EXTRACTION_JUDGE_VERDICT_CATEGORY = "EXTRACTION_JUDGE_VERDICT";
+/**
+ * Structured event written for every judge verdict (including verdicts
+ * served from cache). The `version` field lets future readers upgrade the
+ * schema without breaking older rows.
+ */
+interface JudgeVerdictEvent {
+    version: 1;
+    category: typeof EXTRACTION_JUDGE_VERDICT_CATEGORY;
+    ts: string;
+    verdictKind: JudgeVerdictKind;
+    /** Short free-text reason from the judge / deterministic fallback. */
+    reason: string;
+    /**
+     * How many times this candidate's content hash had already been deferred
+     * before this verdict. 0 for the first defer, 1 for the second, etc.
+     * Not applicable for non-defer kinds — emitted as 0.
+     */
+    deferrals: number;
+    /**
+     * Milliseconds between batch start and batch return (the whole
+     * `judgeFactDurability` call, shared across all verdicts in a single
+     * batch).
+     */
+    elapsedMs: number;
+    /** Candidate metadata for coarse filtering. */
+    candidateCategory: string;
+    confidence?: number;
+    /** SHA-256 of the (text\0category) pair, same as the verdict-cache key. */
+    contentHash: string;
+    /** Whether the verdict came from the in-memory verdict cache. */
+    fromCache: boolean;
+    /**
+     * True when the judge forcibly converted a defer to reject because the
+     * defer cap was reached. Only set on cap-triggered rejects.
+     */
+    deferCapTriggered?: boolean;
+}
+/**
+ * Options to control emit behavior. `enabled` gates all writes; when
+ * false, `recordJudgeVerdict` is a no-op so callers can unconditionally
+ * invoke it.
+ */
+interface JudgeTelemetryOptions {
+    enabled: boolean;
+    memoryDir: string;
+}
+declare function judgeTelemetryPath(memoryDir: string): string;
+/**
+ * Append a single verdict event as a JSONL row. Fails open — if the write
+ * cannot be completed (directory missing, permissions, disk full), the
+ * error is logged at debug level and swallowed so extraction never fails
+ * because of telemetry.
+ */
+declare function recordJudgeVerdict(event: JudgeVerdictEvent, options: JudgeTelemetryOptions): Promise<void>;
+/**
+ * Aggregate statistics over the verdict ledger, optionally restricted to a
+ * time window. Returns zero-count stats when the ledger is missing or
+ * empty — callers do not need to special-case a cold install.
+ */
+interface JudgeVerdictStats {
+    total: number;
+    accept: number;
+    reject: number;
+    defer: number;
+    deferCapTriggered: number;
+    /** Mean elapsed milliseconds across all events in the window. */
+    meanElapsedMs: number;
+    /** Defer rate as `defer / total`, in `[0, 1]`. `0` when total is 0. */
+    deferRate: number;
+    /** First and last event timestamps observed in the window. */
+    firstTs?: string;
+    lastTs?: string;
+    /** Number of rows skipped because they were malformed or wrong shape. */
+    malformed: number;
+}
+/**
+ * Read and aggregate events from the verdict ledger.
+ *
+ * `sinceMs` / `untilMs` bound by `ts` parse — events with unparseable
+ * timestamps are counted toward `malformed`. The upper bound is exclusive
+ * (`ts < untilMs`), per CLAUDE.md gotcha 35.
+ */
+declare function readJudgeVerdictStats(memoryDir: string, opts?: {
+    sinceMs?: number;
+    untilMs?: number;
+}): Promise<JudgeVerdictStats>;
+
+export { EXTRACTION_JUDGE_VERDICT_CATEGORY, type JudgeTelemetryOptions, type JudgeVerdictEvent, type JudgeVerdictStats, judgeTelemetryPath, readJudgeVerdictStats, recordJudgeVerdict };

package/dist/extraction-judge-telemetry.js

@@ -0,0 +1,14 @@
+import {
+  EXTRACTION_JUDGE_VERDICT_CATEGORY,
+  judgeTelemetryPath,
+  readJudgeVerdictStats,
+  recordJudgeVerdict
+} from "./chunk-AJU4PJGY.js";
+import "./chunk-2ODBA7MQ.js";
+export {
+  EXTRACTION_JUDGE_VERDICT_CATEGORY,
+  judgeTelemetryPath,
+  readJudgeVerdictStats,
+  recordJudgeVerdict
+};
+//# sourceMappingURL=extraction-judge-telemetry.js.map

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

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

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