hippo-memory 1.61.0 → 1.63.0

package/dist/decisions.js

@@ -1,5 +1,5 @@
 /**
- * E2 decision first-class object (docs/plans/2026-05-28-e2-decision-object.md).
+ * Decision first-class object.
  *
  * `hippo decide` used to write only a tagged memory (tags ['decision'], source
  * 'decision') with a 90-day half-life, so an in-force decision decayed out of
@@ -16,7 +16,7 @@
  * Tenant scoping: every helper requires tenantId. BEFORE INSERT/UPDATE triggers
  * enforce decisions.tenant_id == the referenced memory's tenant_id, and a
  * superseded_by same-tenant trigger makes cross-tenant supersession
- * unrepresentable. Mirrors the v0.31 predictions pattern (src/predictions.ts).
+ * unrepresentable. Mirrors the predictions pattern (src/predictions.ts).
  *
  * Dual-write atomicity: `saveDecision` writes the memory + decisions row (and,
  * when superseding, the old row's UPDATE) inside writeEntry's SAVEPOINT
@@ -60,6 +60,97 @@ const DECISION_COLS = `
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
+/** The legacy `hippo decide` memory mirror for a decision. */
+function buildDecisionMemory(hippoRoot, tenantId, opts) {
+    const content = opts.context
+        ? `${opts.decisionText}\n\nContext: ${opts.context}`
+        : opts.decisionText;
+    const tags = ['decision', ...(opts.extraTags ?? [])];
+    return createMemory(content, {
+        tags,
+        layer: Layer.Semantic,
+        confidence: 'verified',
+        source: 'decision',
+        baseHalfLifeDays: objectHalfLifeDays(hippoRoot),
+        tenantId,
+    });
+}
+// Preflight the supersede target BEFORE inserting the new row. The new
+// row's autoincrement id could otherwise collide with a non-existent
+// supersedesDecisionId (e.g. superseding id 1 on an empty store, where the
+// INSERT below would itself become id 1), making the row supersede itself.
+// Validating first means the new row is never a candidate for its own
+// supersede UPDATE.
+function preflightDecisionSupersede(db, tenantId, supersedesId) {
+    // SAFETY: row shape matches the single `status` column named in the SELECT below.
+    const pred = db.prepare(`SELECT status FROM decisions WHERE id = ? AND tenant_id = ?`).get(supersedesId, tenantId);
+    if (!pred) {
+        throw new NotFoundError(`saveDecision: decision ${supersedesId} to supersede not found for tenant ${tenantId}`);
+    }
+    if (pred.status !== 'active') {
+        throw new ConflictError(`saveDecision: decision ${supersedesId} is not active (status='${pred.status}'); only active decisions can be superseded.`);
+    }
+}
+function insertDecisionRow(db, memoryId, tenantId, opts, now) {
+    const result = db.prepare(`
+    INSERT INTO decisions(
+      memory_id, tenant_id, decision_text, context,
+      status, superseded_by, superseded_at, closed_at, created_at
+    ) VALUES (?, ?, ?, ?, 'active', NULL, NULL, NULL, ?)
+  `).run(memoryId, tenantId, opts.decisionText, opts.context ?? null, now);
+    return Number(result.lastInsertRowid ?? 0);
+}
+// Supersede the (preflight-validated) prior active decision in the SAME
+// SAVEPOINT, atomic with the new row. The `id != decisionId` exclusion is
+// defense-in-depth against the self-match described above; combined with
+// the preflight, a 0-change here is unreachable in the single-writer txn.
+function supersedeDecisionRow(db, tenantId, actor, supersedesId, decisionId, now) {
+    const sup = db.prepare(`
+    UPDATE decisions
+    SET status = 'superseded', superseded_by = ?, superseded_at = ?
+    WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
+  `).run(decisionId, now, supersedesId, tenantId, decisionId);
+    if (sup.changes === 0) {
+        throw new ConflictError(`saveDecision: decision ${supersedesId} could not be superseded (no longer active or self-reference).`);
+    }
+    appendAuditEvent(db, {
+        tenantId,
+        actor,
+        op: 'decision_supersede',
+        targetId: String(supersedesId),
+        metadata: {
+            decision_id: supersedesId,
+            superseded_by: decisionId,
+        },
+    });
+}
+/** The afterWrite body: preflight, INSERT, supersede, reload, create audit, all in one SAVEPOINT. */
+function writeDecisionRow(db, memoryId, tenantId, opts, actor, now) {
+    if (opts.supersedesDecisionId !== undefined) {
+        preflightDecisionSupersede(db, tenantId, opts.supersedesDecisionId);
+    }
+    const decisionId = insertDecisionRow(db, memoryId, tenantId, opts, now);
+    if (opts.supersedesDecisionId !== undefined) {
+        supersedeDecisionRow(db, tenantId, actor, opts.supersedesDecisionId, decisionId, now);
+    }
+    // SAFETY: row's shape matches the columns named in DECISION_COLS above.
+    const row = db.prepare(`SELECT ${DECISION_COLS} FROM decisions WHERE id = ?`)
+        .get(decisionId);
+    if (!row)
+        throw new Error('saveDecision: failed to reload saved decision row');
+    // GDPR-light metadata: id + flag only, no decision_text.
+    appendAuditEvent(db, {
+        tenantId,
+        actor,
+        op: 'decision_create',
+        targetId: String(decisionId),
+        metadata: {
+            decision_id: decisionId,
+            has_context: opts.context !== undefined && opts.context !== null && opts.context !== '',
+        },
+    });
+    return row;
+}
 /**
  * Create a decision. Writes the memory mirror + the decisions row atomically
  * inside writeEntry's SAVEPOINT 'write_entry'. When supersedesDecisionId is
@@ -77,92 +168,18 @@ export function saveDecision(hippoRoot, tenantId, opts, actor = 'cli') {
     if (!opts.decisionText)
         throw new BadRequestError('saveDecision: decisionText is required');
     const now = new Date().toISOString();
-    const content = opts.context
-        ? `${opts.decisionText}\n\nContext: ${opts.context}`
-        : opts.decisionText;
-    const tags = ['decision', ...(opts.extraTags ?? [])];
-    const mem = createMemory(content, {
-        tags,
-        layer: Layer.Semantic,
-        confidence: 'verified',
-        source: 'decision',
-        baseHalfLifeDays: objectHalfLifeDays(hippoRoot),
-        tenantId,
-    });
+    const mem = buildDecisionMemory(hippoRoot, tenantId, opts);
     // Populated inside afterWrite so the INSERT, the supersede UPDATE, and the
     // memory write all share one SAVEPOINT.
     let savedRow;
     writeEntry(hippoRoot, mem, {
         actor,
         afterWrite: (db, memoryId) => {
-            // Preflight the supersede target BEFORE inserting the new row. The new
-            // row's autoincrement id could otherwise collide with a non-existent
-            // supersedesDecisionId (e.g. superseding id 1 on an empty store, where the
-            // INSERT below would itself become id 1), making the row supersede itself.
-            // Validating first means the new row is never a candidate for its own
-            // supersede UPDATE. codex review 2026-05-28 (P1).
-            if (opts.supersedesDecisionId !== undefined) {
-                // SAFETY: row shape matches the single `status` column named in the SELECT below.
-                const pred = db.prepare(`SELECT status FROM decisions WHERE id = ? AND tenant_id = ?`).get(opts.supersedesDecisionId, tenantId);
-                if (!pred) {
-                    throw new NotFoundError(`saveDecision: decision ${opts.supersedesDecisionId} to supersede not found for tenant ${tenantId}`);
-                }
-                if (pred.status !== 'active') {
-                    throw new ConflictError(`saveDecision: decision ${opts.supersedesDecisionId} is not active (status='${pred.status}'); only active decisions can be superseded.`);
-                }
-            }
-            const result = db.prepare(`
-        INSERT INTO decisions(
-          memory_id, tenant_id, decision_text, context,
-          status, superseded_by, superseded_at, closed_at, created_at
-        ) VALUES (?, ?, ?, ?, 'active', NULL, NULL, NULL, ?)
-      `).run(memoryId, tenantId, opts.decisionText, opts.context ?? null, now);
-            const decisionId = Number(result.lastInsertRowid ?? 0);
-            // Supersede the (preflight-validated) prior active decision in the SAME
-            // SAVEPOINT, atomic with the new row. The `id != decisionId` exclusion is
-            // defense-in-depth against the self-match described above; combined with
-            // the preflight, a 0-change here is unreachable in the single-writer txn.
-            if (opts.supersedesDecisionId !== undefined) {
-                const sup = db.prepare(`
-          UPDATE decisions
-          SET status = 'superseded', superseded_by = ?, superseded_at = ?
-          WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
-        `).run(decisionId, now, opts.supersedesDecisionId, tenantId, decisionId);
-                if (sup.changes === 0) {
-                    throw new BadRequestError(`saveDecision: decision ${opts.supersedesDecisionId} could not be superseded (no longer active or self-reference).`);
-                }
-                appendAuditEvent(db, {
-                    tenantId,
-                    actor,
-                    op: 'decision_supersede',
-                    targetId: String(opts.supersedesDecisionId),
-                    metadata: {
-                        decision_id: opts.supersedesDecisionId,
-                        superseded_by: decisionId,
-                    },
-                });
-            }
-            // SAFETY: row's shape matches the columns named in DECISION_COLS above.
-            const row = db.prepare(`SELECT ${DECISION_COLS} FROM decisions WHERE id = ?`)
-                .get(decisionId);
-            if (!row)
-                throw new Error('saveDecision: failed to reload saved decision row');
-            savedRow = row;
-            // GDPR-light metadata: id + flag only, no decision_text.
-            appendAuditEvent(db, {
-                tenantId,
-                actor,
-                op: 'decision_create',
-                targetId: String(decisionId),
-                metadata: {
-                    decision_id: decisionId,
-                    has_context: opts.context !== undefined && opts.context !== null && opts.context !== '',
-                },
-            });
+            savedRow = writeDecisionRow(db, memoryId, tenantId, opts, actor, now);
         },
         // Post-commit hook: mark the tenant's graph dirty AFTER the DB row commits
         // but BEFORE the markdown mirrors are written, so a mirror-write failure can
-        // never leave a committed save unflagged (codex). markGraphDirty is fail-soft.
+        // never leave a committed save unflagged. markGraphDirty is fail-soft.
         afterCommit: () => markGraphDirty(hippoRoot, tenantId, mem.id),
     });
     if (!savedRow) {
@@ -215,7 +232,7 @@ export function closeDecision(hippoRoot, tenantId, id, actor = 'cli') {
             // Closing removes the object from the graph. Remove its rows DIRECTLY (deterministic),
             // not only via an enqueued rebuild whose queue item is lost if the mirror is later
             // forgotten (the queue row cascade-deletes with the memory), which would leave the closed
-            // object stale and could block that forget (codex P1). Still enqueue when a mirror exists
+            // object stale and could block that forget. Still enqueue when a mirror exists
             // so a concurrent rebuild re-derives consistently (harmless if it also runs).
             removeGraphEntitiesForObject(hippoRoot, tenantId, 'decision', closed.id);
             if (closed.memoryId) {

package/dist/dedupe.js

@@ -22,7 +22,9 @@
  */
 import { textOverlap } from './tokenize.js';
 import { loadAllEntries } from './store/entry-reads.js';
-import { deleteEntry, memoriesBackingObjects } from './store/delete-and-batch.js';
+import { deleteEntryOn, memoriesBackingObjects } from './store/delete-and-batch.js';
+import { openStore } from './store/open.js';
+import { closeHippoDb } from './db.js';
 import { compareEntryIdentity } from './compare.js';
 import { canAutoDelete } from './memory.js';
 import { derivationPartitionKey } from './recall-scope.js';
@@ -56,6 +58,71 @@ export function strengthBucket(strength) {
     const s = strength ?? 0;
     return Number.isFinite(s) ? Math.round(s / STRENGTH_TIE_EPSILON) : 0;
 }
+// finiteCount mirrors strengthBucket's non-finite hardening on the
+// retrieval leg: a NaN retrieval_count would make the comparator return
+// NaN and break the total order the same way a NaN bucket would.
+// Unreachable via the schema (non-nullable INTEGER column), so this is
+// symmetry, not a live bug.
+const finiteCount = (n) => Number.isFinite(n ?? 0) ? (n ?? 0) : 0;
+/** The v1.26.3 survivor total order: strength bucket desc, then retrieval_count desc, then compareEntryIdentity. */
+function survivorOrder(a, b) {
+    const bucketDiff = strengthBucket(b.strength) - strengthBucket(a.strength);
+    if (bucketDiff !== 0)
+        return bucketDiff;
+    const retrievalDiff = finiteCount(b.retrieval_count) - finiteCount(a.retrieval_count);
+    if (retrievalDiff !== 0)
+        return retrievalDiff;
+    return compareEntryIdentity(a, b);
+}
+// Tenant partition (mirrors consolidate.ts mergeCandidatesByTenant and
+// dag.ts unparentedByTenant): group by tenantId BEFORE the sort so a
+// duplicate pair can never form across tenants. Map preserves insertion
+// order, so a single-tenant store (every row 'default') gets exactly one
+// group and the sort plus pair loop below run byte-identical to the
+// pre-fix global pass.
+function entriesByPartition(entries) {
+    const entriesByTenant = new Map();
+    for (const entry of entries) {
+        // EI2: also split by restricted scope, else a private copy can delete the readable one.
+        const key = derivationPartitionKey(entry.tenantId, entry.scope, entry.origin_project);
+        const bucket = entriesByTenant.get(key);
+        if (bucket)
+            bucket.push(entry);
+        else
+            entriesByTenant.set(key, [entry]);
+    }
+    return entriesByTenant;
+}
+function dedupPair(kept, dropped) {
+    return {
+        kept: kept.id,
+        keptContent: kept.content,
+        keptLayer: kept.layer,
+        keptStrength: kept.strength ?? 0,
+        removed: dropped.id,
+        removedContent: dropped.content,
+        removedLayer: dropped.layer,
+        removedStrength: dropped.strength ?? 0,
+        similarity: textOverlap(kept.content, dropped.content),
+    };
+}
+/** Pairs within one partition, already in survivor order, grouped by survivor; marks each loser in `removed`. */
+function partitionPairs(tenantEntries, removed, backing) {
+    const groups = new Map();
+    for (const entry of tenantEntries) {
+        const key = duplicateKey(entry.content);
+        const group = groups.get(key);
+        if (!group) {
+            groups.set(key, { survivor: entry, pairs: [] });
+            continue;
+        }
+        if (!canAutoDelete(entry) || backing.has(entry.id))
+            continue;
+        removed.add(entry.id);
+        group.pairs.push(dedupPair(group.survivor, entry));
+    }
+    return [...groups.values()].flatMap((group) => group.pairs);
+}
 /**
  * Scan the store for duplicates and remove the weaker copy: same text apart
  * from spacing, since a near-duplicate can differ in a value (port, version,
@@ -70,28 +137,7 @@ export function deduplicateStore(hippoRoot, options = {}) {
     // Only current distilled rows compete: raw rows are append-only (the delete
     // trigger would abort sleep mid-loop) and superseded rows are history, as in consolidate.ts.
     const entries = loadAllEntries(hippoRoot).filter((e) => e.kind === 'distilled' && !e.superseded_by);
-    // Tenant partition (mirrors consolidate.ts mergeCandidatesByTenant and
-    // dag.ts unparentedByTenant): group by tenantId BEFORE the sort so a
-    // duplicate pair can never form across tenants. Map preserves insertion
-    // order, so a single-tenant store (every row 'default') gets exactly one
-    // group and the sort plus pair loop below run byte-identical to the
-    // pre-fix global pass.
-    const entriesByTenant = new Map();
-    for (const entry of entries) {
-        // EI2: also split by restricted scope, else a private copy can delete the readable one.
-        const key = derivationPartitionKey(entry.tenantId, entry.scope, entry.origin_project);
-        const bucket = entriesByTenant.get(key);
-        if (bucket)
-            bucket.push(entry);
-        else
-            entriesByTenant.set(key, [entry]);
-    }
-    // finiteCount mirrors strengthBucket's non-finite hardening on the
-    // retrieval leg: a NaN retrieval_count would make the comparator return
-    // NaN and break the total order the same way a NaN bucket would.
-    // Unreachable via the schema (non-nullable INTEGER column), so this is
-    // symmetry, not a live bug.
-    const finiteCount = (n) => Number.isFinite(n ?? 0) ? (n ?? 0) : 0;
+    const entriesByTenant = entriesByPartition(entries);
     // Shared across tenant groups: safe because memory ids are globally
     // unique (crypto.randomUUID at creation), so an id in `removed` can never
     // collide with another tenant's row, and deleteEntry below deletes by
@@ -100,45 +146,24 @@ export function deduplicateStore(hippoRoot, options = {}) {
     const pairs = [];
     const backing = memoriesBackingObjects(hippoRoot);
     for (const tenantEntries of entriesByTenant.values()) {
-        // The v1.26.3 survivor total order (see the file-level docstring:
-        // strength bucket desc -> retrieval_count desc -> compareEntryIdentity),
-        // scoped per tenant group: the total order holds within a tenant only,
-        // matching the partition above.
-        tenantEntries.sort((a, b) => {
-            const bucketDiff = strengthBucket(b.strength) - strengthBucket(a.strength);
-            if (bucketDiff !== 0)
-                return bucketDiff;
-            const retrievalDiff = finiteCount(b.retrieval_count) - finiteCount(a.retrieval_count);
-            if (retrievalDiff !== 0)
-                return retrievalDiff;
-            return compareEntryIdentity(a, b);
-        });
-        const texts = tenantEntries.map((e) => duplicateKey(e.content));
-        for (let i = 0; i < tenantEntries.length; i++) {
-            if (removed.has(tenantEntries[i].id))
-                continue;
-            for (let j = i + 1; j < tenantEntries.length; j++) {
-                if (removed.has(tenantEntries[j].id) || !canAutoDelete(tenantEntries[j]) || backing.has(tenantEntries[j].id))
-                    continue;
-                if (texts[j] !== texts[i])
-                    continue;
-                const similarity = textOverlap(tenantEntries[i].content, tenantEntries[j].content);
-                removed.add(tenantEntries[j].id);
-                pairs.push({
-                    kept: tenantEntries[i].id,
-                    keptContent: tenantEntries[i].content,
-                    keptLayer: tenantEntries[i].layer,
-                    keptStrength: tenantEntries[i].strength ?? 0,
-                    removed: tenantEntries[j].id,
-                    removedContent: tenantEntries[j].content,
-                    removedLayer: tenantEntries[j].layer,
-                    removedStrength: tenantEntries[j].strength ?? 0,
-                    similarity,
-                });
-            }
-        }
+        // The survivor total order (see the file-level docstring), scoped per
+        // tenant group: the total order holds within a tenant only, matching the partition above.
+        tenantEntries.sort(survivorOrder);
+        pairs.push(...partitionPairs(tenantEntries, removed, backing));
     }
-    const done = dryRun ? pairs : pairs.filter((p) => deleteEntry(hippoRoot, p.removed, { actor: options.actor, reason: `dedup: duplicate of ${p.kept}`, automatic: true }));
+    const done = dryRun ? pairs : deletePairs(hippoRoot, pairs, options.actor);
     return { removed: done.length, pairs: done };
 }
+/** The pairs whose loser was deleted; one store handle, one transaction per delete. */
+function deletePairs(hippoRoot, pairs, actor) {
+    if (pairs.length === 0)
+        return [];
+    const db = openStore(hippoRoot);
+    try {
+        return pairs.filter((p) => deleteEntryOn(db, hippoRoot, p.removed, { actor, reason: `dedup: duplicate of ${p.kept}`, automatic: true }));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 //# sourceMappingURL=dedupe.js.map