@psiclawops/hypermem 0.7.0 → 0.8.1

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-resolution-policy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * hypermem Contradiction Resolution Policy
+ *
+ * Defines thresholds and flags that control how the background indexer acts
+ * on detected contradictions during fact ingest.
+ *
+ * Tiers (by contradictionScore):
+ *   >= autoSupersedeThreshold  → mark old fact superseded, remove stale vector
+ *   >= autoInvalidateThreshold → mark old fact invalid (no supersede linkage)
+ *   below autoInvalidateThreshold → log-only (pending review)
+ */
+export interface ContradictionResolutionPolicy {
+    /** Score threshold at or above which the old fact is auto-superseded by the new one. Default: 0.80 */
+    autoSupersedeThreshold: number;
+    /** Score threshold at or above which the old fact is auto-invalidated. Default: 0.60 */
+    autoInvalidateThreshold: number;
+    /** When true, always write an audit row regardless of tier. Default: true */
+    alwaysAudit: boolean;
+}
+export declare const DEFAULT_CONTRADICTION_POLICY: ContradictionResolutionPolicy;
+//# sourceMappingURL=contradiction-resolution-policy.d.ts.map

package/dist/contradiction-resolution-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contradiction-resolution-policy.d.ts","sourceRoot":"","sources":["../src/contradiction-resolution-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,6BAA6B;IAC5C,sGAAsG;IACtG,sBAAsB,EAAE,MAAM,CAAC;IAC/B,wFAAwF;IACxF,uBAAuB,EAAE,MAAM,CAAC;IAChC,6EAA6E;IAC7E,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,eAAO,MAAM,4BAA4B,EAAE,6BAI1C,CAAC"}

package/dist/contradiction-resolution-policy.js

@@ -0,0 +1,17 @@
+/**
+ * hypermem Contradiction Resolution Policy
+ *
+ * Defines thresholds and flags that control how the background indexer acts
+ * on detected contradictions during fact ingest.
+ *
+ * Tiers (by contradictionScore):
+ *   >= autoSupersedeThreshold  → mark old fact superseded, remove stale vector
+ *   >= autoInvalidateThreshold → mark old fact invalid (no supersede linkage)
+ *   below autoInvalidateThreshold → log-only (pending review)
+ */
+export const DEFAULT_CONTRADICTION_POLICY = {
+    autoSupersedeThreshold: 0.80,
+    autoInvalidateThreshold: 0.60,
+    alwaysAudit: true,
+};
+//# sourceMappingURL=contradiction-resolution-policy.js.map

package/dist/degradation.d.ts

@@ -0,0 +1,102 @@
+/**
+ * HyperMem Canonical Degradation Contracts, Phase C0.2
+ *
+ * Defines the typed surfaces, reason enum, and format builders for degraded
+ * prompt-visible outputs. These shapes stay in volatile context and should not
+ * cross the stable-prefix boundary.
+ */
+/**
+ * Closed set of reasons for any degradation decision.
+ * Use these values in telemetry and tests instead of ad-hoc strings.
+ */
+export type DegradationReason = 'gradient_t2_prose' | 'gradient_t3_stub' | 'eviction_oversize' | 'eviction_turn0_trim' | 'wave_guard_pressure_high' | 'wave_guard_pressure_elevated' | 'budget_cluster_drop' | 'artifact_oversize' | 'artifact_fetch_hint' | 'replay_cold_redis' | 'replay_stabilizing' | 'replay_exited' | 'pressure_mismatch' | 'unknown';
+/** All valid DegradationReason values as a readonly array. */
+export declare const DEGRADATION_REASONS: readonly ["gradient_t2_prose", "gradient_t3_stub", "eviction_oversize", "eviction_turn0_trim", "wave_guard_pressure_high", "wave_guard_pressure_elevated", "budget_cluster_drop", "artifact_oversize", "artifact_fetch_hint", "replay_cold_redis", "replay_stabilizing", "replay_exited", "pressure_mismatch", "unknown"];
+/** Field-length caps for canonical degraded strings. */
+export declare const DEGRADATION_LIMITS: {
+    readonly toolName: 64;
+    readonly toolId: 64;
+    readonly reason: 48;
+    readonly toolSummary: 120;
+    readonly toolArtifactId: 64;
+    readonly artifactId: 64;
+    readonly artifactPath: 160;
+    readonly artifactFetchHint: 80;
+    readonly replayState: 32;
+    readonly replaySummary: 120;
+};
+export declare function isDegradationReason(value: string): value is DegradationReason;
+/**
+ * Canonical shape for a degraded tool call/result pair.
+ *
+ * Prompt-visible format:
+ *   [tool:<name> id=<id> status=ejected reason=<reason> summary=<stub>]
+ *
+ * Optional artifact pointer (Phase 1 of tool_artifacts):
+ *   [tool:<name> id=<id> status=ejected reason=<reason> artifact=<artifactId> summary=<stub>]
+ *
+ * The `artifact=` field is backwards-compatible and optional. When present, it
+ * lets the compositor rehydrate the full tool result payload from the
+ * tool_artifacts table without needing to rewrite the transcript.
+ */
+export interface ToolChainStub {
+    name: string;
+    id: string;
+    status: 'ejected';
+    reason: DegradationReason;
+    summary: string;
+    /** Optional durable pointer into the tool_artifacts table. */
+    artifactId?: string;
+}
+export declare function formatToolChainStub(stub: ToolChainStub): string;
+export declare function parseToolChainStub(text: string): ToolChainStub | null;
+export declare function isToolChainStub(text: string): boolean;
+/**
+ * Canonical shape for a degraded oversized artifact replaced by a pointer.
+ *
+ * Prompt-visible format:
+ *   [artifact:<id> path=<path> size=<tokens> status=degraded fetch=<hint>]
+ */
+export interface ArtifactRef {
+    id: string;
+    path: string;
+    sizeTokens: number;
+    status: 'degraded';
+    reason: DegradationReason;
+    fetchHint: string;
+}
+export declare function formatArtifactRef(ref: ArtifactRef): string;
+export declare function parseArtifactRef(text: string): ArtifactRef | null;
+export declare function isArtifactRef(text: string): boolean;
+/**
+ * State of the replay recovery window.
+ */
+export type ReplayState = 'entering' | 'stabilizing' | 'exited';
+export declare function isReplayState(value: string): value is ReplayState;
+/**
+ * Canonical shape for a replay recovery mode marker.
+ *
+ * Prompt-visible format:
+ *   [replay state=<state> status=bounded reason=<reason> summary=<stub>]
+ */
+export interface ReplayMarker {
+    state: ReplayState;
+    status: 'bounded';
+    reason: DegradationReason;
+    summary: string;
+}
+export declare function formatReplayMarker(marker: ReplayMarker): string;
+export declare function parseReplayMarker(text: string): ReplayMarker | null;
+export declare function isReplayMarker(text: string): boolean;
+export declare function isDegradedContent(text: string): boolean;
+export interface DegradationEvent {
+    event: 'degradation';
+    ts: string;
+    agentId: string;
+    sessionKey: string;
+    degradationClass: 'tool_chain' | 'artifact' | 'replay';
+    reason: DegradationReason;
+    tokensSaved: number;
+    emittedText: string;
+}
+//# sourceMappingURL=degradation.d.ts.map

package/dist/degradation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"degradation.d.ts","sourceRoot":"","sources":["../src/degradation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB,mBAAmB,GACnB,kBAAkB,GAClB,mBAAmB,GACnB,qBAAqB,GACrB,0BAA0B,GAC1B,8BAA8B,GAC9B,qBAAqB,GACrB,mBAAmB,GACnB,qBAAqB,GACrB,mBAAmB,GACnB,oBAAoB,GACpB,eAAe,GACf,mBAAmB,GACnB,SAAS,CAAC;AAEd,8DAA8D;AAC9D,eAAO,MAAM,mBAAmB,2TAeiB,CAAC;AAElD,wDAAwD;AACxD,eAAO,MAAM,kBAAkB;;;;;;;;;;;CAWrB,CAAC;AAiBX,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,iBAAiB,CAE7E;AAID;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAKD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAS/D;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAQrE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAID;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAM1D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAajE;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAID;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,aAAa,GAAG,QAAQ,CAAC;AAEhE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,WAAW,CAEjE;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAK/D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAWnE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAID,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAID,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,aAAa,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,YAAY,GAAG,UAAU,GAAG,QAAQ,CAAC;IACvD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB"}