@remnic/core 9.65.1 → 9.65.3

package/dist/index-CexDrJzC.d.ts

@@ -0,0 +1,284 @@
+import { S as StorageManager } from './storage-BIDzuKIn.js';
+import { w as MemoryStatus, P as PluginConfig, y as MemoryCategory } from './types-BxAcOl5Q.js';
+import { a as SemanticDedupLookup } from './semantic-BalR6EXU.js';
+import { LocalLlmClient } from './local-llm.js';
+import { FallbackLlmClient } from './fallback-llm.js';
+
+/**
+ * Contradiction Scan — pair generator + scan driver (issue #520).
+ *
+ * Nightly cron that pairs semantically-similar active memories within
+ * the same namespace, sends candidate pairs to the LLM-as-judge
+ * contradiction classifier, and drops contradicting pairs into a
+ * review queue for user resolution.
+ *
+ * Pair generation (cheap pre-filter):
+ *   1. Find candidate peers via embedding cosine >= similarityFloor.
+ *   2. Restrict to pairs sharing at least one entityRef OR overlapping
+ *      topic tokens >= topicOverlapFloor.
+ *   3. Skip pairs already judged independent/both-valid within cooldown.
+ *   4. Cap per-run work at maxPairsPerRun.
+ */
+
+/** The set of statuses that represent "live" memories eligible for scanning. */
+declare const ACTIVE_STATUSES: Set<MemoryStatus>;
+interface ScanResult {
+    /** Total active memories scanned. */
+    scanned: number;
+    /** Candidate pairs generated by the pre-filter. */
+    candidates: number;
+    /** Pairs sent to judge. */
+    judged: number;
+    /** Pairs written to review queue. */
+    queued: number;
+    /** Pairs skipped due to cooldown. */
+    cooledDown: number;
+    /** Total wall-clock time in ms. */
+    elapsedMs: number;
+}
+interface ScanStorageResolution {
+    storage: StorageManager;
+    namespace?: string;
+}
+interface ScanDependencies {
+    storage: StorageManager;
+    config: PluginConfig;
+    memoryDir: string;
+    /** Pre-built embedding lookup. When provided, used as-is for Strategy 3. */
+    embeddingLookup?: SemanticDedupLookup;
+    /**
+     * Factory to build a namespace-scoped embedding lookup.
+     * When provided, takes precedence over `embeddingLookup`.
+     * The scan driver passes its own `storage` so the lookup queries the correct index.
+     */
+    embeddingLookupFactory?: (storage: StorageManager) => SemanticDedupLookup | undefined;
+    /** Resolver for namespace-scoped storage. Required for scans when namespaces are enabled. */
+    storageForNamespace?: (namespace: string | undefined) => StorageManager | ScanStorageResolution | Promise<StorageManager | ScanStorageResolution>;
+    localLlm: LocalLlmClient | null;
+    fallbackLlm: FallbackLlmClient | null;
+    namespace?: string;
+}
+/**
+ * Run a contradiction scan over the memory corpus.
+ *
+ * This is the entry point called by the nightly cron and by the CLI.
+ */
+declare function runContradictionScan(deps: ScanDependencies): Promise<ScanResult>;
+
+/**
+ * Contradiction Judge — LLM-as-judge for semantic contradiction detection (issue #520).
+ *
+ * Pairs semantically-similar memories and classifies their relationship.
+ * Reuses the extraction-judge adapter pattern but with a contradiction-specific
+ * prompt and verdict taxonomy.
+ *
+ * Design constraints:
+ *   - Default verdict on any failure is "needs-user" (rule 48: least-privileged default).
+ *   - Never auto-resolve; all verdicts enter the review queue.
+ *   - Content-hash caching avoids redundant LLM calls across runs.
+ */
+
+type ContradictionVerdict = "contradicts" | "independent" | "duplicates" | "needs-user";
+interface ContradictionJudgeInput {
+    /** Memory ID of the first fact. */
+    memoryIdA: string;
+    /** Memory ID of the second fact. */
+    memoryIdB: string;
+    /** Content text of the first fact. */
+    textA: string;
+    /** Content text of the second fact. */
+    textB: string;
+    /** Category of the first fact (optional context). */
+    categoryA?: string;
+    /** Category of the second fact (optional context). */
+    categoryB?: string;
+}
+interface ContradictionJudgeResult {
+    /** Memory IDs of the pair. */
+    memoryIdA: string;
+    memoryIdB: string;
+    /** Verdict from the judge. */
+    verdict: ContradictionVerdict;
+    /** Human-readable rationale. */
+    rationale: string;
+    /** Confidence in [0, 1]. */
+    confidence: number;
+}
+interface ContradictionJudgeBatchResult {
+    /** Results keyed by pair key ("idA:idB"). */
+    results: Map<string, ContradictionJudgeResult>;
+    /** Number served from cache. */
+    cached: number;
+    /** Number produced by LLM call. */
+    judged: number;
+    /** Total wall-clock time in ms. */
+    elapsed: number;
+}
+declare function createVerdictCache(): Map<string, ContradictionJudgeResult>;
+declare function clearVerdictCache(): void;
+declare function verdictCacheSize(): number;
+/**
+ * Judge a batch of memory pairs for contradiction.
+ *
+ * Uses content-hash caching to skip pairs already judged in a prior run.
+ * On any LLM failure, all unresolved pairs default to "needs-user".
+ */
+declare function judgeContradictionPairs(pairs: ContradictionJudgeInput[], config: PluginConfig, localLlm: LocalLlmClient | null, fallbackLlm: FallbackLlmClient | null, cache?: Map<string, ContradictionJudgeResult>): Promise<ContradictionJudgeBatchResult>;
+
+/**
+ * Contradiction Review Queue — storage for detected contradiction pairs (issue #520).
+ *
+ * Stores candidate pairs as JSON files under `memoryDir/.review/contradictions/`.
+ * Pair IDs are deterministic (sha256 of sorted memory IDs plus namespace when scoped) so reruns are idempotent.
+ *
+ * Lifecycle:
+ *   - `contradicts` → awaiting user review
+ *   - `duplicates` → auto-flagged for dedup (still needs user approval)
+ *   - `independent` / `both-valid` → dormant with cooldown
+ */
+
+/**
+ * Resolution verbs. The first five are contradiction-pair verbs; the last
+ * three resolve a `kind: "preference-drift"` item (issue #2371). Verb validity
+ * is per-kind — `executeResolution` rejects a cross-kind verb — but the stored
+ * union is shared so one review queue, one `review_resolve` surface, and one
+ * resolution record serve both item kinds.
+ */
+type ResolutionVerb = "keep-a" | "keep-b" | "merge" | "both-valid" | "needs-more-context" | "keep" | "supersede" | "archive";
+/** Review-item kind. Absent on every pair written before issue #2371. */
+type ReviewItemKind = "contradiction" | "preference-drift";
+interface ContradictionPair {
+    /** Deterministic pair ID: sha256(sorted(memoryIdA, memoryIdB) plus namespace when scoped). */
+    pairId: string;
+    /** Memory IDs (sorted). */
+    memoryIds: [string, string];
+    /**
+     * Item kind (issue #2371). Absent on every pair written before drift
+     * detection existed, which reads as `"contradiction"`. A
+     * `"preference-drift"` item pairs the aging preference (first id) with the
+     * recent evidence that pointed away from it (second id).
+     */
+    kind?: ReviewItemKind;
+    /** Judge verdict. */
+    verdict: ContradictionVerdict;
+    /** Judge rationale. */
+    rationale: string;
+    /** Judge confidence in [0, 1]. */
+    confidence: number;
+    /** ISO timestamp when detected. */
+    detectedAt: string;
+    /** ISO timestamp when last reviewed by user. */
+    lastReviewedAt?: string;
+    /** Resolution verb applied by user. */
+    resolution?: ResolutionVerb;
+    /** ISO timestamp until which a non-terminal deferral remains hidden from review. */
+    deferredUntil?: string;
+    /** Content hashes captured for each referenced memory when this pair was judged. */
+    memoryContentHashes?: Record<string, string>;
+    /** Namespace scope. */
+    namespace?: string;
+}
+interface ContradictionListResult {
+    pairs: ContradictionPair[];
+    total: number;
+    durationMs: number;
+}
+type ContradictionFilter = ContradictionVerdict | "all" | "unresolved";
+interface WritePairOptions {
+    /** Cooldown used by scan callers to preserve still-dormant reviewed pairs. */
+    cooldownDays?: number;
+}
+declare function computePairId(memoryIdA: string, memoryIdB: string, namespace?: string): string;
+/**
+ * Write a contradiction pair to the review queue.
+ * Idempotent: if the pair already exists with a higher or equal confidence,
+ * the existing entry is preserved.
+ */
+declare function writePair(memoryDir: string, pair: Omit<ContradictionPair, "pairId"> & {
+    memoryIds: [string, string];
+}, options?: WritePairOptions): ContradictionPair;
+/**
+ * Write multiple pairs, deduplicating inputs first (rule 49).
+ */
+declare function writePairs(memoryDir: string, pairs: Array<Omit<ContradictionPair, "pairId"> & {
+    memoryIds: [string, string];
+}>, options?: WritePairOptions): ContradictionPair[];
+/**
+ * Read a single pair by ID. Returns null if not found.
+ */
+declare function readPair(memoryDir: string, pairId: string): ContradictionPair | null;
+/**
+ * List pairs in the review queue, optionally filtered by verdict.
+ */
+declare function listPairs(memoryDir: string, options?: {
+    filter?: ContradictionFilter;
+    namespace?: string;
+    includeUnscopedForNamespace?: boolean;
+    limit?: number;
+}): ContradictionListResult;
+/**
+ * Check if a pair is within its cooldown window.
+ * Returns true if the pair should be SKIPPED (still cooling down).
+ */
+declare function isCoolingDown(pair: ContradictionPair, cooldownDays: number): boolean;
+/**
+ * Mark a pair as reviewed (sets lastReviewedAt and, for terminal verbs, resolution).
+ */
+declare function resolvePair(memoryDir: string, pairId: string, verb: ResolutionVerb): ContradictionPair | null;
+
+/**
+ * Resolution Verbs — executes user-chosen resolution actions on contradiction pairs (issue #520).
+ *
+ * All resolution paths delegate to StorageManager.supersedeMemory. Do not
+ * reimplement supersession logic here (rule 22: deduplicate resolution).
+ */
+
+interface ResolutionResult {
+    pairId: string;
+    verb: ResolutionVerb;
+    /** Memory IDs affected by the resolution. */
+    affectedIds: string[];
+    /** Human-readable status. */
+    message: string;
+}
+interface ExecuteResolutionOptions {
+    /** Existing merged memory to supersede both source memories to. */
+    mergedMemoryId?: string;
+    /** Content for a new merged memory. Required for merge when mergedMemoryId is omitted. */
+    mergedContent?: string;
+    /** Category for a newly created merged memory. Defaults to the shared source category, or fact. */
+    mergedCategory?: MemoryCategory;
+    /** Resolve storage for the pair namespace, or the default namespace for legacy unscoped pairs. */
+    storageForNamespace?: (namespace: string | undefined) => StorageManager | Promise<StorageManager>;
+    /**
+     * Best-effort hook invoked after a contradiction resolution leaves a durable
+     * mutation in the namespace's memory files (issue #1499 sweep, NH1dX / NH3X3).
+     * Every mutating verb — `merge` (creates a new memory and supersedes both
+     * sources), `keep-a`, and `keep-b` (supersede the losing source + rewrite
+     * frontmatter) — writes directly to the pair's (possibly DYNAMIC) namespace
+     * storage, bypassing the extraction write path that records catalog writes. So
+     * without this the namespace's `lastWriteAt` stays stale and QMD maintenance /
+     * `writtenSince` can skip a namespace whose only post-write mutation is
+     * resolving a contradiction. It fires after the resolution commits, or after a
+     * failed resolution/rollback path when durable memory changes are still left on
+     * disk. If a failure rolls back cleanly, this is never called, so the catalog
+     * never records a write that did not survive (rule #25). Non-mutating verbs
+     * (`both-valid`, `needs-more-context`) never trigger it. Callers wire this to
+     * `Orchestrator.recordCatalogWrite(namespace, storageDir)`. Must be
+     * failure-tolerant: it is fire-and-forget and must never affect resolution.
+     */
+    onMergedMemoryWritten?: (namespace: string | undefined, storageDir: string) => void;
+}
+declare function isValidResolutionVerb(value: string): value is ResolutionVerb;
+/**
+ * Execute a resolution verb on a contradiction pair.
+ *
+ * - `keep-a`: Supersede B, keep A active.
+ * - `keep-b`: Supersede A, keep B active.
+ * - `merge`: Create or verify a real merged memory, then supersede both inputs.
+ * - `both-valid`: Mark pair as reviewed; no memories are superseded.
+ * - `needs-more-context`: Defer; no action, short cooldown.
+ */
+declare function executeResolution(memoryDir: string, storage: StorageManager, pairId: string, verb: ResolutionVerb, options?: ExecuteResolutionOptions): Promise<ResolutionResult>;
+
+export { ACTIVE_STATUSES as A, type ContradictionPair as C, type ResolutionResult as R, type ScanStorageResolution as S, type ContradictionFilter as a, type ContradictionJudgeBatchResult as b, type ContradictionJudgeInput as c, type ContradictionJudgeResult as d, type ContradictionListResult as e, type ContradictionVerdict as f, type ResolutionVerb as g, type ScanDependencies as h, type ScanResult as i, computePairId as j, executeResolution as k, isCoolingDown as l, isValidResolutionVerb as m, judgeContradictionPairs as n, listPairs as o, resolvePair as p, runContradictionScan as q, readPair as r, writePairs as s, clearVerdictCache as t, createVerdictCache as u, verdictCacheSize as v, writePair as w };