@remnic/core 9.69.56 → 9.69.58

package/dist/graph-DRkl22KE.d.ts

@@ -1,347 +0,0 @@
-import { GraphConstructionCapabilitySet } from './capabilities.js';
-import './graph-write-lock.js';
-
-interface ActivationPredecessor {
-    prev: string;
-    edgeConfidence: number;
-    graphType: GraphType;
-}
-interface ActivationPathCandidate {
-    hopDepth: number;
-    landingStrength: number;
-    pathKey: string;
-}
-/** Compare path winners: fewer hops, stronger landing, then lexical path order. */
-declare function compareActivationPathCandidates(left: ActivationPathCandidate, right: ActivationPathCandidate): number;
-declare class ActivationPathTracker {
-    readonly predecessors: Map<string, ActivationPredecessor>;
-    private readonly winners;
-    private readonly pathKeys;
-    constructor(seeds: Iterable<string>);
-    consider(seed: string, node: string, neighbor: string, hopDepth: number, landingStrength: number, edgeConfidence: number, graphType: GraphType): string;
-}
-declare function reconstructActivationPath(seed: string, candidate: string, predecessors: Map<string, ActivationPredecessor>, maxSteps: number): ActivationPath | null;
-
-/**
- * Multi-Graph Memory (MAGMA/SYNAPSE-inspired, v8.2)
- *
- * Maintains three typed edge graphs:
- *   entity.jsonl  — memories sharing a named entity (entityRef)
- *   time.jsonl    — consecutive memories in the same thread/session
- *   causal.jsonl  — memories linked by causal language heuristics
- *
- * Stored under `<memoryDir>/state/graphs/`.
- * All writes are fail-open: errors are caught/logged, never thrown.
- */
-
-type GraphType = "entity" | "time" | "causal";
-interface ActivationPath {
-    /** Node ids from the seed (inclusive) to the reached node (inclusive). */
-    nodeIds: string[];
-    /** Edge confidences, parallel to the hops in {@link nodeIds}. */
-    edgeConfidences: number[];
-    /** Graph types, parallel to the hops in {@link nodeIds}. */
-    graphTypes: GraphType[];
-}
-interface GraphEdge {
-    from: string;
-    to: string;
-    type: GraphType;
-    weight: number;
-    label: string;
-    ts: string;
-    confidence?: number;
-    lastReinforcedAt?: string;
-}
-interface GraphConfig {
-    multiGraphMemoryEnabled: boolean;
-    entityGraphEnabled: boolean;
-    timeGraphEnabled: boolean;
-    causalGraphEnabled: boolean;
-    maxGraphTraversalSteps: number;
-    graphActivationDecay: number;
-    maxEntityGraphEdgesPerMemory: number;
-    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;
-    /**
-     * Issue #1904 — incremental GraphIndex edge cache. When true (the default,
-     * and the value when omitted), a single-writer edge append is pushed into the
-     * warm edge cache in place (revalidated by file size for cross-process
-     * coherence) instead of nulling the cache and paying a full 6 MB re-read +
-     * parse on the next traversal. Set false to restore the pre-#1904
-     * null-on-every-write behavior. Optional here (unlike the required
-     * PluginConfig field parseConfig always sets) so GraphConfig can still be
-     * constructed directly with a partial config; only an explicit `false` opts
-     * out, so an omitted field keeps the incremental default.
-     */
-    graphEdgeCacheIncrementalEnabled?: boolean;
-}
-/** 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>;
-
-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 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.
- */
-declare function readAllEdges(memoryDir: string, graphCaps: Pick<GraphConstructionCapabilitySet, "entityGraph" | "timeGraph" | "causalGraph">): Promise<GraphEdge[]>;
-interface GraphHealthFileStats {
-    type: GraphType;
-    filePath: string;
-    exists: boolean;
-    totalLines: number;
-    validEdges: number;
-    corruptLines: number;
-    uniqueNodes: number;
-}
-interface GraphHealthReport {
-    generatedAt: string;
-    enabledTypes: GraphType[];
-    totals: {
-        totalLines: number;
-        validEdges: number;
-        corruptLines: number;
-        uniqueNodes: number;
-    };
-    files: GraphHealthFileStats[];
-    repairGuidance?: string[];
-}
-declare function analyzeGraphHealth(memoryDir: string, options?: {
-    entityGraphEnabled?: boolean;
-    timeGraphEnabled?: boolean;
-    causalGraphEnabled?: boolean;
-    includeRepairGuidance?: boolean;
-}): Promise<GraphHealthReport>;
-/**
- * Detect causal signal phrases in text. Returns the first matched phrase, or null.
- */
-declare function detectCausalPhrase(text: string): string | null;
-declare class GraphIndex {
-    private readonly memoryDir;
-    private readonly cfg;
-    private edgeCache;
-    private static readonly EDGE_CACHE_TTL_MS;
-    constructor(memoryDir: string, cfg: GraphConfig);
-    /** Clear the edge cache so the next spreadingActivation() re-reads from disk.
-     *  Call after any code path that appends edges outside of onMemoryWritten(). */
-    invalidateEdgeCache(): void;
-    private loadEdgesCached;
-    /**
-     * Identity ({ size, mtimeMs, ino }) of each ENABLED graph file (issue #1904).
-     * Missing files (ENOENT) and any stat error map to the all-zero sentinel so
-     * the baseline is fail-open: a later revalidation sees a mismatch (or a peer
-     * creation flipping ino from 0 to non-zero) and forces a full reload rather
-     * than trusting a stale incremental push.
-     */
-    private readEnabledGraphFileMeta;
-    /** True iff both metadata maps carry identical identity for every key. */
-    private graphFileMetaEqual;
-    /**
-     * Re-stat every graph file whose identity the cache just committed and return
-     * false if any has moved since (issue #1904, Codex). Closes the validation→
-     * in-place-push TOCTOU window: a peer process (concurrent CLI / daemon /
-     * decay job) can append between edgeFilesUnchangedExceptOurAppends()'s final
-     * stat and the allEdges.push(...). Without this re-check the cache would be
-     * accepted with identity predating the peer write and miss the peer edge for
-     * the TTL. A residual infinitesimal window (peer writes during this re-stat)
-     * remains and is TTL-bounded.
-     */
-    private edgeCacheIdentityUnchangedSinceCommit;
-    /**
-     * Called after a memory is written to disk.
-     *
-     * Throws when an edge append fails (after logging): the merged-target rewrite
-     * path depends on the rejection to restore the edges `removeNodeEdgesForRewrite`
-     * dropped — swallowing here left that restore dead and the prior edge set
-     * permanently lost (#2330). Fail-open is the CALLER's decision; the create
-     * paths already catch (see persistence-index.buildGraphEdge).
-     *
-     * @param memoryPath - relative path from memoryDir (e.g. "facts/2026-02-22/abc.md")
-     * @param entityRef  - entityRef frontmatter field (if any)
-     * @param content    - full memory text (for causal detection)
-     * @param created    - ISO timestamp of this memory
-     * @param threadId   - current thread ID (for time graph)
-     * @param recentInThread - paths of the N most-recent memories in this thread (for time graph)
-     * @param entitySiblings - paths of other memories that share the same entityRef (for entity graph)
-     */
-    onMemoryWritten(opts: {
-        memoryPath: string;
-        entityRef?: string;
-        content: string;
-        created: string;
-        threadId?: string;
-        recentInThread?: string[];
-        entitySiblings?: string[];
-        causalPredecessor?: string;
-        /**
-         * Optional frozen gate overrides (from GraphConstructionCapabilitySet).
-         * When provided, these take precedence over `this.cfg` so the caller's
-         * operation-scoped snapshot is the single source of truth (#1566).
-         */
-        graphCapsOverride?: {
-            entityGraph: boolean;
-            timeGraph: boolean;
-            causalGraph: boolean;
-            multiGraphMemory: boolean;
-        };
-    }): Promise<GraphEdge[]>;
-    /**
-     * Cross-process coherence check for the incremental edge cache (issue #1904).
-     *
-     * Returns true iff every ENABLED graph file's current identity is explained
-     * ENTIRELY by THIS call's own append — no other process wrote to any graph
-     * file since load. Per file:
-     *   - inode must be unchanged. A local append (`appendFile`) keeps the inode;
-     *     an external atomic temp+rename rewrite (e.g. the edge-decay job) changes
-     *     it, so an inode change — even one that preserves byte length, such as
-     *     decaying confidence 0.9->0.8 — forces a reload (Codex).
-     *   - a file WE appended to (delta > 0): size must equal baseline + our exact
-     *     appended bytes. If it was absent at load (sentinel ino 0), our append
-     *     created it, so we accept size === delta and adopt the new identity.
-     *   - a file we did NOT touch (delta 0): size AND mtime must be unchanged, so
-     *     an in-place equal-length rewrite (mtime bump) or a peer append (size
-     *     bump) both force a reload.
-     * On success it commits the new identity baseline so the next append
-     * revalidates against post-this-write truth. Fail-open: an unreadable file
-     * (non-ENOENT) returns false, forcing a full reload.
-     */
-    private edgeFilesUnchangedExceptOurAppends;
-    /**
-     * 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 × edgeConfidence × decay^hop.
-     *
-     * 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, edgeConfidence, ...} sorted descending, not including seed paths
-     */
-    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;
-        /** Record one shortest seed-to-candidate path in each result. */
-        recordPaths?: boolean;
-        /** Absolute deadline in ms-since-epoch for post-retrieval assembly. */
-        deadlineAtMs?: number;
-    }): 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;
-        activationPath?: ActivationPath | null;
-    }>>;
-}
-/**
- * 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;
-    deadlineAtMs?: number;
-}): void;
-/**
- * Lateral inhibition (Synapse-inspired).
- *
- * For each node, the top-M higher-activation competitors exert inhibition
- * proportional to their activation difference. Output is clamped to [0, ∞).
- *
- * No sigmoid is applied here — downstream `normalizeGraphActivationScore`
- * already applies x/(1+x) soft squash, so adding a sigmoid would double-
- * normalize and cap graph influence at ~50%.
- *
- * Formula: u_hat_i = max(0, u_i - beta * sum_{k in top-M where u_k > u_i}(u_k - u_i))
- *
- * When beta=0 or topM=0, returns original scores unchanged (no-op).
- */
-declare function applyLateralInhibition(scores: Map<string, number>, opts: {
-    beta: number;
-    topM: number;
-}): Map<string, number>;
-
-export { type ActivationPath as A, CAUSAL_PHRASES as C, DEFAULT_GRAPH_TRAVERSAL_CONFIDENCE_FLOOR as D, type GraphType as G, type GraphEdge as a, type GraphHealthReport as b, GraphIndex as c, type ActivationPathCandidate as d, ActivationPathTracker as e, type ActivationPredecessor as f, compareActivationPathCandidates as g, DEFAULT_GRAPH_TRAVERSAL_PAGERANK_ITERATIONS as h, type GraphConfig as i, type GraphHealthFileStats as j, analyzeGraphHealth as k, appendEdge as l, applyLateralInhibition as m, applyPageRankRefinement as n, clampConfidenceFloor as o, clampPageRankIterations as p, detectCausalPhrase as q, reconstructActivationPath as r, ensureGraphsDir as s, graphFilePath as t, graphsDir as u, readAllEdges as v, readEdges as w, readEdgesStrict as x };

package/dist/graph-edge-decay-MKIRZ762.js

@@ -1,30 +0,0 @@
-import {
-  DEFAULT_VISIBILITY_THRESHOLD,
-  discoverGraphNamespaceRoots,
-  graphEdgeDecayStatusPath,
-  readGraphEdgeDecayStatus,
-  runGraphEdgeDecayMaintenance,
-  runGraphEdgeDecayMaintenanceAcrossNamespaces
-} from "./chunk-SCXURCVT.js";
-import "./chunk-DGS34QSY.js";
-import "./chunk-5FAGCOZD.js";
-import "./chunk-EUT2WCWS.js";
-import "./chunk-2LSZVONP.js";
-import "./chunk-DEUNUKTD.js";
-import "./chunk-LXY5VVGM.js";
-import "./chunk-GKCXTSFF.js";
-import "./chunk-FFAZ2XFU.js";
-import "./chunk-PCXDUHQH.js";
-import "./chunk-VUFL7X3H.js";
-import "./chunk-KNA3BXXL.js";
-import "./chunk-3WCASNQZ.js";
-import "./chunk-PZ5AY32C.js";
-export {
-  DEFAULT_VISIBILITY_THRESHOLD,
-  discoverGraphNamespaceRoots,
-  graphEdgeDecayStatusPath,
-  readGraphEdgeDecayStatus,
-  runGraphEdgeDecayMaintenance,
-  runGraphEdgeDecayMaintenanceAcrossNamespaces
-};
-//# sourceMappingURL=graph-edge-decay-MKIRZ762.js.map

package/dist/index-B735x-tK.d.ts

@@ -1,284 +0,0 @@
-import { S as StorageManager } from './storage-CMm-3aD3.js';
-import { x as MemoryStatus, P as PluginConfig, u as MemoryCategory } from './types-Du6VdoAg.js';
-import { a as SemanticDedupLookup } from './semantic-BalR6EXU.js';
-import { L as LocalLlmClient } from './local-llm-BkkEK9rn.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 };