@psiclawops/hypermem 0.6.2 → 0.8.0

package/dist/content-hash.d.ts

@@ -0,0 +1,43 @@
+/**
+ * hypermem Content Hash
+ *
+ * Content-addressed hashing for fact/knowledge deduplication.
+ * Uses BLAKE3 (via @noble/hashes) for fast, collision-resistant fingerprints.
+ *
+ * Dedup semantics are per-agent: the same content stored by two different
+ * agents is intentional and should not be merged. Check with:
+ *   WHERE content_hash = ? AND agent_id = ?
+ */
+import type { DatabaseSync } from 'node:sqlite';
+/**
+ * Compute a BLAKE3 content hash for deduplication.
+ * Returns a 64-character hex string (32 bytes).
+ *
+ * Normalization: collapses whitespace, trims, lowercases
+ * before hashing. This catches trivial reformatting differences
+ * that shouldn't create duplicate facts.
+ */
+export declare function contentHash(text: string): string;
+/**
+ * SQL migration statements for adding content_hash columns and indexes.
+ *
+ * Use non-unique indexes — different agents may legitimately store identical
+ * facts. Dedup check is always scoped per agent:
+ *   WHERE content_hash = ? AND agent_id = ?
+ */
+export declare const SCHEMA_MIGRATIONS: {
+    addFactsContentHash: string;
+    addKnowledgeContentHash: string;
+    indexFactsContentHash: string;
+    indexKnowledgeContentHash: string;
+};
+/**
+ * Backfill content_hash for existing rows that have NULL hashes.
+ * Meant to run once after schema migration.
+ * Returns count of rows updated.
+ *
+ * Defensive: returns 0 if the content_hash column does not exist on the
+ * target table (e.g. migration hasn't run yet or table is missing).
+ */
+export declare function backfillContentHashes(db: DatabaseSync, table: 'facts' | 'knowledge'): number;
+//# sourceMappingURL=content-hash.d.ts.map

package/dist/content-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-hash.d.ts","sourceRoot":"","sources":["../src/content-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB;;;;;CAK7B,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,OAAO,GAAG,WAAW,GAC3B,MAAM,CAgCR"}

package/dist/content-hash.js

@@ -0,0 +1,75 @@
+/**
+ * hypermem Content Hash
+ *
+ * Content-addressed hashing for fact/knowledge deduplication.
+ * Uses BLAKE3 (via @noble/hashes) for fast, collision-resistant fingerprints.
+ *
+ * Dedup semantics are per-agent: the same content stored by two different
+ * agents is intentional and should not be merged. Check with:
+ *   WHERE content_hash = ? AND agent_id = ?
+ */
+import { blake3 } from '@noble/hashes/blake3.js';
+/**
+ * Compute a BLAKE3 content hash for deduplication.
+ * Returns a 64-character hex string (32 bytes).
+ *
+ * Normalization: collapses whitespace, trims, lowercases
+ * before hashing. This catches trivial reformatting differences
+ * that shouldn't create duplicate facts.
+ */
+export function contentHash(text) {
+    const normalized = text.toLowerCase().replace(/\s+/g, ' ').trim();
+    const bytes = new TextEncoder().encode(normalized);
+    return Buffer.from(blake3(bytes)).toString('hex');
+}
+/**
+ * SQL migration statements for adding content_hash columns and indexes.
+ *
+ * Use non-unique indexes — different agents may legitimately store identical
+ * facts. Dedup check is always scoped per agent:
+ *   WHERE content_hash = ? AND agent_id = ?
+ */
+export const SCHEMA_MIGRATIONS = {
+    addFactsContentHash: `ALTER TABLE facts ADD COLUMN content_hash TEXT`,
+    addKnowledgeContentHash: `ALTER TABLE knowledge ADD COLUMN content_hash TEXT`,
+    indexFactsContentHash: `CREATE INDEX IF NOT EXISTS idx_facts_content_hash ON facts(content_hash)`,
+    indexKnowledgeContentHash: `CREATE INDEX IF NOT EXISTS idx_knowledge_content_hash ON knowledge(content_hash)`,
+};
+/**
+ * Backfill content_hash for existing rows that have NULL hashes.
+ * Meant to run once after schema migration.
+ * Returns count of rows updated.
+ *
+ * Defensive: returns 0 if the content_hash column does not exist on the
+ * target table (e.g. migration hasn't run yet or table is missing).
+ */
+export function backfillContentHashes(db, table) {
+    // Defensive: verify the column exists before querying it.
+    const pragmaRows = db
+        .prepare(`PRAGMA table_info(${table})`)
+        .all();
+    const hasColumn = pragmaRows.some((r) => r['name'] === 'content_hash');
+    if (!hasColumn)
+        return 0;
+    const rows = db
+        .prepare(`SELECT id, content FROM ${table} WHERE content_hash IS NULL`)
+        .all();
+    if (rows.length === 0)
+        return 0;
+    const update = db.prepare(`UPDATE ${table} SET content_hash = ? WHERE id = ?`);
+    // Single transaction for the entire batch — much faster than autocommit per row.
+    // Node 22 DatabaseSync does not have .transaction(); use manual BEGIN/COMMIT.
+    db.exec('BEGIN');
+    try {
+        for (const row of rows) {
+            update.run(contentHash(row.content), row.id);
+        }
+        db.exec('COMMIT');
+    }
+    catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+    }
+    return rows.length;
+}
+//# sourceMappingURL=content-hash.js.map

package/dist/context-store.d.ts

@@ -63,6 +63,60 @@ export declare function updateContextHead(db: DatabaseSync, contextId: number, m
  * Idempotent — no-op if already archived.
  */
 export declare function archiveContext(db: DatabaseSync, contextId: number): void;
+/**
+ * Get any context by id, regardless of status.
+ * Returns null if not found.
+ *
+ * @boundary INSPECTION ONLY — not a mining entry point.
+ * @policy See specs/DAG_HELPER_POLICY.md for helper classifications.
+ * Do not use this function to retrieve messages for active composition or
+ * historical mining. Use getArchivedContext + mineArchivedContext for archived
+ * mining, and getActiveContext for composition-path access.
+ */
+export declare function getContextById(db: DatabaseSync, contextId: number): Context | null;
+/**
+ * Get all archived or forked contexts for an agent.
+ * Optionally filter by sessionKey and/or limit.
+ * Returns in reverse-chronological order (most recently updated first).
+ *
+ * @policy See specs/DAG_HELPER_POLICY.md. This is the operator-safe
+ * archived-context enumeration path.
+ */
+export declare function getArchivedContexts(db: DatabaseSync, agentId: string, opts?: {
+    sessionKey?: string;
+    limit?: number;
+}): Context[];
+/**
+ * Get an archived or forked context by id.
+ * Returns null if the context does not exist OR if it is active.
+ *
+ * @policy See specs/DAG_HELPER_POLICY.md. This is the operator-safe
+ * single-context lookup path.
+ */
+export declare function getArchivedContext(db: DatabaseSync, contextId: number): Context | null;
+/**
+ * Walk the parent_context_id chain upward from the given context.
+ * Returns contexts in leaf-to-root order (starting context first).
+ * Includes the starting context itself.
+ * Caps traversal depth at 100 to avoid corrupt loops.
+ *
+ * @boundary STATUS-CROSSING BY DESIGN — this function traverses across
+ * active, archived, and forked contexts without filtering by status.
+ * @policy See specs/DAG_HELPER_POLICY.md for the call-site filtering rule.
+ * If you need only archived/forked contexts in the lineage chain, filter
+ * the returned array at the call site (e.g. `.filter(c => c.status !== 'active')`).
+ */
+export declare function getContextLineage(db: DatabaseSync, contextId: number): Context[];
+/**
+ * Get direct fork children of a context (contexts with parent_context_id = parentContextId).
+ * Returns in ascending creation order.
+ *
+ * @boundary STATUS-CROSSING BY DESIGN — returns children regardless of their status
+ * (may include active, archived, or forked children).
+ * @policy See specs/DAG_HELPER_POLICY.md for the call-site filtering rule.
+ * Filter at the call site if archived-only results are needed.
+ */
+export declare function getForkChildren(db: DatabaseSync, parentContextId: number): Context[];
 /**
  * Rotate a session's active context: archive the current active context
  * and create a new one, optionally linking back via parent_context_id.

package/dist/context-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-store.d.ts","sourceRoot":"","sources":["../src/context-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAyBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAmC1D;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,GAAG,IAAI,CAShB;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,OAAO,CAwBT;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,IAAI,CAeN;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,CAMN;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,OAAO,CA2BT"}
+{"version":3,"file":"context-store.d.ts","sourceRoot":"","sources":["../src/context-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAyBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAmC1D;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,GAAG,IAAI,CAShB;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,OAAO,CAwBT;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,IAAI,CAeN;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,CAMN;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,GAAG,IAAI,CAOhB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IACL,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACA,OAAO,EAAE,CAkBX;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,GAAG,IAAI,CAOhB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,EAAE,CAqBX;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,YAAY,EAChB,eAAe,EAAE,MAAM,GACtB,OAAO,EAAE,CAMX;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,OAAO,CA2BT"}

package/dist/context-store.js

@@ -141,6 +141,108 @@ export function archiveContext(db, contextId) {
     const now = nowIso();
     db.prepare(`UPDATE contexts SET status = 'archived', updated_at = ? WHERE id = ? AND status != 'archived'`).run(now, contextId);
 }
+/**
+ * Get any context by id, regardless of status.
+ * Returns null if not found.
+ *
+ * @boundary INSPECTION ONLY — not a mining entry point.
+ * @policy See specs/DAG_HELPER_POLICY.md for helper classifications.
+ * Do not use this function to retrieve messages for active composition or
+ * historical mining. Use getArchivedContext + mineArchivedContext for archived
+ * mining, and getActiveContext for composition-path access.
+ */
+export function getContextById(db, contextId) {
+    const row = db
+        .prepare('SELECT * FROM contexts WHERE id = ?')
+        .get(contextId);
+    if (!row)
+        return null;
+    return parseContextRow(row);
+}
+/**
+ * Get all archived or forked contexts for an agent.
+ * Optionally filter by sessionKey and/or limit.
+ * Returns in reverse-chronological order (most recently updated first).
+ *
+ * @policy See specs/DAG_HELPER_POLICY.md. This is the operator-safe
+ * archived-context enumeration path.
+ */
+export function getArchivedContexts(db, agentId, opts) {
+    let sql = "SELECT * FROM contexts WHERE agent_id = ? AND status IN ('archived', 'forked')";
+    const params = [agentId];
+    if (opts?.sessionKey) {
+        sql += ' AND session_key = ?';
+        params.push(opts.sessionKey);
+    }
+    sql += ' ORDER BY updated_at DESC';
+    if (opts?.limit) {
+        sql += ' LIMIT ?';
+        params.push(opts.limit);
+    }
+    const rows = db.prepare(sql).all(...params);
+    return rows.map(parseContextRow);
+}
+/**
+ * Get an archived or forked context by id.
+ * Returns null if the context does not exist OR if it is active.
+ *
+ * @policy See specs/DAG_HELPER_POLICY.md. This is the operator-safe
+ * single-context lookup path.
+ */
+export function getArchivedContext(db, contextId) {
+    const row = db
+        .prepare("SELECT * FROM contexts WHERE id = ? AND status IN ('archived', 'forked')")
+        .get(contextId);
+    if (!row)
+        return null;
+    return parseContextRow(row);
+}
+/**
+ * Walk the parent_context_id chain upward from the given context.
+ * Returns contexts in leaf-to-root order (starting context first).
+ * Includes the starting context itself.
+ * Caps traversal depth at 100 to avoid corrupt loops.
+ *
+ * @boundary STATUS-CROSSING BY DESIGN — this function traverses across
+ * active, archived, and forked contexts without filtering by status.
+ * @policy See specs/DAG_HELPER_POLICY.md for the call-site filtering rule.
+ * If you need only archived/forked contexts in the lineage chain, filter
+ * the returned array at the call site (e.g. `.filter(c => c.status !== 'active')`).
+ */
+export function getContextLineage(db, contextId) {
+    const lineage = [];
+    const visited = new Set();
+    let currentId = contextId;
+    while (currentId !== null && lineage.length < 100) {
+        if (visited.has(currentId))
+            break; // loop guard
+        visited.add(currentId);
+        const row = db
+            .prepare('SELECT * FROM contexts WHERE id = ?')
+            .get(currentId);
+        if (!row)
+            break;
+        const ctx = parseContextRow(row);
+        lineage.push(ctx);
+        currentId = ctx.parentContextId;
+    }
+    return lineage;
+}
+/**
+ * Get direct fork children of a context (contexts with parent_context_id = parentContextId).
+ * Returns in ascending creation order.
+ *
+ * @boundary STATUS-CROSSING BY DESIGN — returns children regardless of their status
+ * (may include active, archived, or forked children).
+ * @policy See specs/DAG_HELPER_POLICY.md for the call-site filtering rule.
+ * Filter at the call site if archived-only results are needed.
+ */
+export function getForkChildren(db, parentContextId) {
+    const rows = db
+        .prepare('SELECT * FROM contexts WHERE parent_context_id = ? ORDER BY created_at ASC')
+        .all(parentContextId);
+    return rows.map(parseContextRow);
+}
 /**
  * Rotate a session's active context: archive the current active context
  * and create a new one, optionally linking back via parent_context_id.

package/dist/contradiction-audit-store.d.ts

@@ -0,0 +1,54 @@
+/**
+ * hypermem Contradiction Audit Store
+ *
+ * Lightweight audit trail for contradiction detections during background indexing.
+ * Records when the indexer identifies a new fact candidate that contradicts an
+ * existing stored fact, without auto-resolving (autoResolve: false path).
+ *
+ * Stored in library.db under the contradiction_audits table (created on demand).
+ * Used for observability and future contradiction resolution tooling.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { ContradictionCandidate } from './contradiction-detector.js';
+export interface ContradictionAuditEntry {
+    id: number;
+    agentId: string;
+    newContent: string;
+    newDomain: string | null;
+    existingFactId: number;
+    existingContent: string;
+    similarityScore: number;
+    contradictionScore: number;
+    reason: string;
+    sourceRef: string | null;
+    createdAt: string;
+}
+export declare class ContradictionAuditStore {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    private ensureTable;
+    /**
+     * Record a detected contradiction between a new fact candidate and an existing fact.
+     *
+     * @param agentId     - Agent whose fact was being indexed
+     * @param newFact     - The incoming fact candidate (not yet stored)
+     * @param candidate   - The contradiction candidate from ContradictionDetector
+     * @param opts        - Optional metadata (sourceRef = "msg:<id>" etc.)
+     */
+    recordFactAudit(agentId: string, newFact: {
+        content: string;
+        domain?: string | null;
+    }, candidate: ContradictionCandidate, opts?: {
+        sourceRef?: string;
+        status?: string;
+    }): void;
+    /**
+     * Fetch recent audit entries for an agent (most recent first).
+     */
+    getRecentAudits(agentId: string, limit?: number): ContradictionAuditEntry[];
+    /**
+     * Count unresolved audits for an agent.
+     */
+    countAudits(agentId: string): number;
+}
+//# sourceMappingURL=contradiction-audit-store.d.ts.map

package/dist/contradiction-audit-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contradiction-audit-store.d.ts","sourceRoot":"","sources":["../src/contradiction-audit-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAE1E,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,uBAAuB;IACtB,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAI7C,OAAO,CAAC,WAAW;IAiCnB;;;;;;;OAOG;IACH,eAAe,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EACpD,SAAS,EAAE,sBAAsB,EACjC,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7C,IAAI;IAqBP;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,uBAAuB,EAAE;IAYvE;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAMrC"}

package/dist/contradiction-audit-store.js

@@ -0,0 +1,88 @@
+/**
+ * hypermem Contradiction Audit Store
+ *
+ * Lightweight audit trail for contradiction detections during background indexing.
+ * Records when the indexer identifies a new fact candidate that contradicts an
+ * existing stored fact, without auto-resolving (autoResolve: false path).
+ *
+ * Stored in library.db under the contradiction_audits table (created on demand).
+ * Used for observability and future contradiction resolution tooling.
+ */
+export class ContradictionAuditStore {
+    db;
+    constructor(db) {
+        this.db = db;
+        this.ensureTable();
+    }
+    ensureTable() {
+        // Synced with library-schema.ts v19 shape so in-memory test DBs match production.
+        // In real usage, setupLibraryDb() runs first and this CREATE TABLE is a no-op.
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS contradiction_audits (
+        id                   INTEGER PRIMARY KEY AUTOINCREMENT,
+        agent_id             TEXT NOT NULL,
+        entity_type          TEXT NOT NULL CHECK(entity_type IN ('fact')),
+        new_content          TEXT NOT NULL,
+        new_domain           TEXT,
+        existing_fact_id     INTEGER NOT NULL,
+        existing_content     TEXT NOT NULL,
+        similarity_score     REAL NOT NULL DEFAULT 0,
+        contradiction_score  REAL NOT NULL DEFAULT 0,
+        reason               TEXT NOT NULL,
+        detector             TEXT NOT NULL DEFAULT 'heuristic_v1',
+        suggested_resolution TEXT NOT NULL DEFAULT 'review',
+        source_ref           TEXT,
+        status               TEXT NOT NULL DEFAULT 'pending'
+          CHECK(status IN ('pending', 'accepted', 'dismissed', 'auto-superseded', 'auto-invalidated')),
+        resolution_notes     TEXT,
+        created_at           TEXT NOT NULL DEFAULT (datetime('now')),
+        resolved_at          TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_contradiction_audits_agent_status
+        ON contradiction_audits (agent_id, status, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_contradiction_audits_existing_fact
+        ON contradiction_audits (existing_fact_id, status);
+      CREATE INDEX IF NOT EXISTS idx_contradiction_audits_agent
+        ON contradiction_audits (agent_id, created_at DESC);
+    `);
+    }
+    /**
+     * Record a detected contradiction between a new fact candidate and an existing fact.
+     *
+     * @param agentId     - Agent whose fact was being indexed
+     * @param newFact     - The incoming fact candidate (not yet stored)
+     * @param candidate   - The contradiction candidate from ContradictionDetector
+     * @param opts        - Optional metadata (sourceRef = "msg:<id>" etc.)
+     */
+    recordFactAudit(agentId, newFact, candidate, opts) {
+        const status = opts?.status ?? 'pending';
+        this.db.prepare(`
+      INSERT INTO contradiction_audits
+        (agent_id, entity_type, new_content, new_domain, existing_fact_id, existing_content,
+         similarity_score, contradiction_score, reason, source_ref, status, created_at)
+      VALUES (?, 'fact', ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+    `).run(agentId, newFact.content, newFact.domain ?? null, candidate.existingFactId, candidate.existingContent, candidate.similarityScore, candidate.contradictionScore, candidate.reason, opts?.sourceRef ?? null, status);
+    }
+    /**
+     * Fetch recent audit entries for an agent (most recent first).
+     */
+    getRecentAudits(agentId, limit = 20) {
+        return this.db.prepare(`
+      SELECT
+        id, agent_id, new_content, new_domain, existing_fact_id, existing_content,
+        similarity_score, contradiction_score, reason, source_ref, created_at
+      FROM contradiction_audits
+      WHERE agent_id = ?
+      ORDER BY created_at DESC
+      LIMIT ?
+    `).all(agentId, limit);
+    }
+    /**
+     * Count unresolved audits for an agent.
+     */
+    countAudits(agentId) {
+        const row = this.db.prepare('SELECT COUNT(*) as cnt FROM contradiction_audits WHERE agent_id = ?').get(agentId);
+        return row?.cnt ?? 0;
+    }
+}
+//# sourceMappingURL=contradiction-audit-store.js.map

package/dist/contradiction-detector.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Contradiction Detector — heuristic-based contradiction detection for the fact store.
+ *
+ * Detects when a newly ingested fact contradicts existing active facts using
+ * vector similarity (when available) and FTS candidate retrieval, scored by
+ * pattern-based heuristics (negation, numeric conflict, state conflict, temporal).
+ *
+ * No LLM calls — v1 is purely heuristic. LLM-enhanced scoring is a future item.
+ */
+import type { FactStore } from './fact-store.js';
+import type { VectorStore } from './vector-store.js';
+export interface ContradictionCandidate {
+    existingFactId: number;
+    existingContent: string;
+    similarityScore: number;
+    contradictionScore: number;
+    reason: string;
+}
+export interface ContradictionResult {
+    contradictions: ContradictionCandidate[];
+    autoResolved: boolean;
+    resolvedCount: number;
+}
+export interface ContradictionDetectorConfig {
+    /** Minimum similarity to consider as candidate. Default: 0.6 */
+    minSimilarity?: number;
+    /** Minimum contradiction score for auto-resolution. Default: 0.85 */
+    autoResolveThreshold?: number;
+    /** Max candidates to evaluate per ingest. Default: 10 */
+    maxCandidates?: number;
+    /** Enable auto-resolution. Default: true */
+    autoResolve?: boolean;
+}
+export declare class ContradictionDetector {
+    private readonly factStore;
+    private readonly vectorStore?;
+    private readonly config;
+    constructor(factStore: FactStore, vectorStore?: VectorStore | undefined, config?: ContradictionDetectorConfig);
+    /**
+     * On fact ingest, check if the new fact contradicts existing active facts.
+     * Uses vector similarity (when available) + FTS to find candidates, then
+     * scores each candidate with heuristic contradiction checks.
+     */
+    detectOnIngest(agentId: string, newFact: {
+        content: string;
+        domain?: string;
+    }): Promise<ContradictionResult>;
+    /**
+     * Resolve a detected contradiction between an existing fact and a new fact.
+     */
+    resolveContradiction(oldFactId: number, newFactId: number, resolution: 'supersede' | 'keep-both' | 'reject-new'): void;
+    /**
+     * Auto-resolve high-confidence contradictions: newer supersedes older.
+     * Only resolves candidates above the autoResolveThreshold.
+     *
+     * @param agentId - The agent whose facts are being resolved (for audit trail)
+     * @param candidates - Scored contradiction candidates from detectOnIngest
+     * @returns Count of auto-resolved contradictions
+     */
+    autoResolve(_agentId: string, candidates: ContradictionCandidate[]): Promise<number>;
+    /**
+     * Find candidate facts that might contradict the new fact.
+     * Uses vector search (if available) and FTS, deduplicates, and returns
+     * up to maxCandidates results above minSimilarity.
+     */
+    private findCandidates;
+    /**
+     * Score a candidate fact against the new fact content for contradiction.
+     * Returns a ContradictionCandidate if any heuristic fires, null otherwise.
+     */
+    private scoreContradiction;
+    /**
+     * Compute Jaccard-like token overlap between two texts.
+     * Returns 0-1 where 1 means identical token sets.
+     */
+    private tokenOverlapSimilarity;
+}
+//# sourceMappingURL=contradiction-detector.d.ts.map

package/dist/contradiction-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contradiction-detector.d.ts","sourceRoot":"","sources":["../src/contradiction-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,mBAAmB,CAAC;AAIzE,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,sBAAsB,EAAE,CAAC;IACzC,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,2BAA2B;IAC1C,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAkKD,qBAAa,qBAAqB;IAI9B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAJ/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;gBAG5C,SAAS,EAAE,SAAS,EACpB,WAAW,CAAC,EAAE,WAAW,YAAA,EAC1C,MAAM,CAAC,EAAE,2BAA2B;IAKtC;;;;OAIG;IACG,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5C,OAAO,CAAC,mBAAmB,CAAC;IAuB/B;;OAEG;IACH,oBAAoB,CAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,WAAW,GAAG,WAAW,GAAG,YAAY,GACnD,IAAI;IAcP;;;;;;;OAOG;IACG,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,sBAAsB,EAAE,GACnC,OAAO,CAAC,MAAM,CAAC;IAoBlB;;;;OAIG;YACW,cAAc;IA0E5B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IA0D1B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;CAa/B"}