hippo-memory 1.61.0 → 1.62.0

package/dist/dag.js

@@ -87,17 +87,14 @@ export async function generateDagSummary(label, factContents, opts) {
         return null;
     }
 }
-export async function buildDag(hippoRoot, facts, opts) {
-    const result = { candidateClusters: 0, summariesCreated: 0, factsLinked: 0, rejected: 0 };
-    const baseHalfLifeDays = loadConfig(hippoRoot).defaultHalfLifeDays;
-    const unparented = facts.filter((f) => f.dag_level === 1 && !f.dag_parent_id && f.tags.includes('extracted'));
-    // Hardening follow-up (mirrors consolidate.ts's mergeCandidatesByTenant,
-    // T1): partition unparented facts by tenantId BEFORE clustering so a
-    // cluster can never mix facts from different tenants into one
-    // LLM-synthesized summary. Map preserves insertion order, so
-    // single-tenant stores (every row 'default') get exactly one partition
-    // and iterate in the same order as before this fix — byte-identical
-    // behavior there.
+// Hardening follow-up (mirrors consolidate.ts's mergeCandidatesByTenant,
+// T1): partition unparented facts by tenantId BEFORE clustering so a
+// cluster can never mix facts from different tenants into one
+// LLM-synthesized summary. Map preserves insertion order, so
+// single-tenant stores (every row 'default') get exactly one partition
+// and iterate in the same order as before this fix — byte-identical
+// behavior there.
+function partitionFactsByTenant(unparented) {
     const unparentedByTenant = new Map();
     for (const fact of unparented) {
         const key = derivationPartitionKey(fact.tenantId, fact.scope, fact.origin_project);
@@ -107,79 +104,149 @@ export async function buildDag(hippoRoot, facts, opts) {
         else
             unparentedByTenant.set(key, [fact]);
     }
-    for (const [, tenantFacts] of unparentedByTenant) {
-        const factTenant = tenantFacts[0].tenantId;
-        const factScope = derivationScope(tenantFacts[0].scope);
+    return unparentedByTenant;
+}
+/** The L2 summary entry for one cluster, landing in the facts' own tenant and scope. */
+function createClusterSummaryEntry(summary, cluster, home) {
+    const memberCreatedAts = cluster.members.map((m) => m.created).sort();
+    // Every member of `cluster` shares home.tenantId by construction (the
+    // tenant partition above), so the summary lands in the same tenant
+    // as the facts it summarizes instead of always 'default'
+    // (memory.ts:535 defaults tenantId when the option is omitted).
+    const summaryEntry = createMemory(summary, {
+        layer: Layer.Semantic,
+        tags: [...cluster.entityTags, ...neverAutoShareTags(cluster.members), 'dag-summary'],
+        confidence: 'inferred',
+        dag_level: 2,
+        tenantId: home.tenantId,
+        scope: home.scope,
+        baseHalfLifeDays: home.baseHalfLifeDays,
+    });
+    summaryEntry.origin_project = home.originProject;
+    // Schema v25: cache descendant_count + earliest/latest_at on the summary
+    // row so DAG-aware recall (docs/plans/2026-05-05-dag-recall.md Task 2)
+    // can reason about scope without walking the children.
+    summaryEntry.descendant_count = cluster.members.length;
+    summaryEntry.earliest_at = memberCreatedAts[0];
+    summaryEntry.latest_at = memberCreatedAts[memberCreatedAts.length - 1];
+    return summaryEntry;
+}
+/** Summarize one eligible cluster, write the summary, then re-parent its members under it. */
+async function summarizeCluster(hippoRoot, cluster, home, opts, result) {
+    const summary = await generateDagSummary(cluster.label, cluster.members.map((m) => m.content), opts);
+    if (!summary)
+        return;
+    const summaryEntry = createClusterSummaryEntry(summary, cluster, home);
+    // AT1 (plan §3 containment): a refused LLM-synthesized summary skips
+    // ONLY this cluster — the sleep cycle continues to the next one. The
+    // member re-parenting writes below never run for a skipped cluster
+    // (there is no summary id to parent them under).
+    //
+    // The tombstone check itself is tenant-scoped for free: writeEntry ->
+    // writeEntryDbOnly -> upsertEntryRow calls
+    // checkRejectionGuard(db, entry.tenantId ?? 'default', ...)
+    // (store/entry-writes.ts), reading tenantId off the entry being written. Now
+    // that summaryEntry carries home.tenantId instead of the implicit
+    // 'default', the guard consults that tenant's tombstones — no
+    // separate check needed here (unlike consolidate.ts's merge pass,
+    // which pre-checks via findRejectedValue because it writes through
+    // batchWriteAndDelete's bypassRejectionGuard path instead of
+    // writeEntry).
+    try {
+        writeEntry(hippoRoot, summaryEntry);
+    }
+    catch (err) {
+        if (err instanceof RejectedValueError) {
+            result.rejected++;
+            log.warn(`buildDag: cluster "${cluster.label}" skipped: summary matches a rejected value`);
+            return;
+        }
+        throw err;
+    }
+    result.summariesCreated++;
+    for (const member of cluster.members) {
+        const updated = { ...member, dag_parent_id: summaryEntry.id };
+        writeEntry(hippoRoot, updated);
+        result.factsLinked++;
+    }
+    // v0.30 / E3 — cancel the cascade of dirty-marks fired by member
+    // writeEntry calls (E2 hook on writeEntryDbOnly in store/entry-writes.ts).
+    // The summary we just built IS fresh, no rebuild needed. Without this,
+    // E3 in the SAME sleep cycle would re-rebuild every new summary
+    // (2x LLM cost). plan-eng-r1 HIGH must-fix.
+    clearSummaryDirtyAfterBuild(hippoRoot, summaryEntry.id, summaryEntry.tenantId, 'buildDag');
+}
+export async function buildDag(hippoRoot, facts, opts) {
+    const result = { candidateClusters: 0, summariesCreated: 0, factsLinked: 0, rejected: 0 };
+    const baseHalfLifeDays = loadConfig(hippoRoot).defaultHalfLifeDays;
+    const unparented = facts.filter((f) => f.dag_level === 1 && !f.dag_parent_id && f.tags.includes('extracted'));
+    for (const [, tenantFacts] of partitionFactsByTenant(unparented)) {
+        const home = {
+            tenantId: tenantFacts[0].tenantId,
+            scope: derivationScope(tenantFacts[0].scope),
+            originProject: tenantFacts[0].origin_project,
+            baseHalfLifeDays,
+        };
         const clusters = clusterFacts(tenantFacts);
         const eligibleClusters = clusters.filter((c) => c.members.length >= 3);
         result.candidateClusters += eligibleClusters.length;
         for (const cluster of eligibleClusters) {
-            const summary = await generateDagSummary(cluster.label, cluster.members.map((m) => m.content), opts);
-            if (!summary)
-                continue;
-            const memberCreatedAts = cluster.members.map((m) => m.created).sort();
-            // Every member of `cluster` shares factTenant by construction (the
-            // tenant partition above), so the summary lands in the same tenant
-            // as the facts it summarizes instead of always 'default'
-            // (memory.ts:535 defaults tenantId when the option is omitted).
-            const summaryEntry = createMemory(summary, {
-                layer: Layer.Semantic,
-                tags: [...cluster.entityTags, ...neverAutoShareTags(cluster.members), 'dag-summary'],
-                confidence: 'inferred',
-                dag_level: 2,
-                tenantId: factTenant,
-                scope: factScope,
-                baseHalfLifeDays,
-            });
-            summaryEntry.origin_project = tenantFacts[0].origin_project;
-            // Schema v25: cache descendant_count + earliest/latest_at on the summary
-            // row so DAG-aware recall (docs/plans/2026-05-05-dag-recall.md Task 2)
-            // can reason about scope without walking the children.
-            summaryEntry.descendant_count = cluster.members.length;
-            summaryEntry.earliest_at = memberCreatedAts[0];
-            summaryEntry.latest_at = memberCreatedAts[memberCreatedAts.length - 1];
-            // AT1 (plan §3 containment): a refused LLM-synthesized summary skips
-            // ONLY this cluster — the sleep cycle continues to the next one. The
-            // member re-parenting writes below never run for a skipped cluster
-            // (there is no summary id to parent them under).
-            //
-            // The tombstone check itself is tenant-scoped for free: writeEntry ->
-            // writeEntryDbOnly -> upsertEntryRow calls
-            // checkRejectionGuard(db, entry.tenantId ?? 'default', ...)
-            // (store/entry-writes.ts), reading tenantId off the entry being written. Now
-            // that summaryEntry carries factTenant instead of the implicit
-            // 'default', the guard consults that tenant's tombstones — no
-            // separate check needed here (unlike consolidate.ts's merge pass,
-            // which pre-checks via findRejectedValue because it writes through
-            // batchWriteAndDelete's bypassRejectionGuard path instead of
-            // writeEntry).
-            try {
-                writeEntry(hippoRoot, summaryEntry);
-            }
-            catch (err) {
-                if (err instanceof RejectedValueError) {
-                    result.rejected++;
-                    log.warn(`buildDag: cluster "${cluster.label}" skipped: summary matches a rejected value`);
-                    continue;
-                }
-                throw err;
-            }
-            result.summariesCreated++;
-            for (const member of cluster.members) {
-                const updated = { ...member, dag_parent_id: summaryEntry.id };
-                writeEntry(hippoRoot, updated);
-                result.factsLinked++;
-            }
-            // v0.30 / E3 — cancel the cascade of dirty-marks fired by member
-            // writeEntry calls (E2 hook on writeEntryDbOnly in store/entry-writes.ts).
-            // The summary we just built IS fresh, no rebuild needed. Without this,
-            // E3 in the SAME sleep cycle would re-rebuild every new summary
-            // (2x LLM cost). plan-eng-r1 HIGH must-fix.
-            clearSummaryDirtyAfterBuild(hippoRoot, summaryEntry.id, summaryEntry.tenantId, 'buildDag');
+            await summarizeCluster(hippoRoot, cluster, home, opts, result);
         }
     }
     return result;
 }
+/** Regenerate one dirty summary from its children and tally the outcome; throws reach the caller's isolation. */
+async function rebuildOneSummary(hippoRoot, summary, opts, result) {
+    const children = loadChildrenOfSummary(hippoRoot, summary.id, summary.tenantId);
+    if (children.length === 0) {
+        // Zero-child case: clear dirty + zero counts, no LLM call, no rebuild_count bump.
+        const { changed } = applyRebuildResult(hippoRoot, summary, {
+            content: summary.content,
+            descendant_count: 0,
+            earliest_at: null,
+            latest_at: null,
+            bumpRebuildCount: false,
+            zeroChildren: true,
+            actor: 'sleep',
+        });
+        if (changed)
+            result.zeroChildSkipped++;
+        // changed=false → race lost / row vanished; silently skip. `refused`
+        // is always false here — applyRebuildResult only checks the
+        // tombstone when bumpRebuildCount is true (store/summaries.ts).
+        return;
+    }
+    // Derive label from summary's existing entity tags (mirrors clusterFacts)
+    const entityTags = summary.tags.filter((t) => t.startsWith('speaker:') || t.startsWith('topic:'));
+    const label = entityTags.length > 0
+        ? entityTags.map((t) => t.split(':')[1]).join(': ')
+        : summary.content.slice(0, 40);
+    const newContent = await generateDagSummary(label, children.map((c) => c.content), opts);
+    if (!newContent) {
+        // LLM null / fetch error → leave dirty for next cycle
+        result.failed++;
+        return;
+    }
+    const childCreatedAts = children.map((c) => c.created).sort();
+    const { changed, refused } = applyRebuildResult(hippoRoot, summary, {
+        content: newContent,
+        descendant_count: children.length,
+        earliest_at: childCreatedAts[0],
+        latest_at: childCreatedAts[childCreatedAts.length - 1],
+        bumpRebuildCount: true,
+        zeroChildren: false,
+        actor: 'sleep',
+    });
+    if (refused) {
+        result.refused++;
+    }
+    else if (changed) {
+        result.rebuilt++;
+    }
+    // changed=false (refused also false) → race lost; not failure, not
+    // success, silently skip
+}
 /**
  * v0.30 / E3 — sleep-cycle phase that drains the dirty L2 summary queue.
  * Thin orchestrator; the heavy lifting lives in store.ts (load + apply)
@@ -221,54 +288,7 @@ export async function rebuildDirtySummaries(hippoRoot, opts) {
             await new Promise((resolve) => setImmediate(resolve));
         }
         try {
-            const children = loadChildrenOfSummary(hippoRoot, summary.id, summary.tenantId);
-            if (children.length === 0) {
-                // Zero-child case: clear dirty + zero counts, no LLM call, no rebuild_count bump.
-                const { changed } = applyRebuildResult(hippoRoot, summary, {
-                    content: summary.content,
-                    descendant_count: 0,
-                    earliest_at: null,
-                    latest_at: null,
-                    bumpRebuildCount: false,
-                    zeroChildren: true,
-                    actor: 'sleep',
-                });
-                if (changed)
-                    result.zeroChildSkipped++;
-                // changed=false → race lost / row vanished; silently skip. `refused`
-                // is always false here — applyRebuildResult only checks the
-                // tombstone when bumpRebuildCount is true (store/summaries.ts).
-                continue;
-            }
-            // Derive label from summary's existing entity tags (mirrors clusterFacts)
-            const entityTags = summary.tags.filter((t) => t.startsWith('speaker:') || t.startsWith('topic:'));
-            const label = entityTags.length > 0
-                ? entityTags.map((t) => t.split(':')[1]).join(': ')
-                : summary.content.slice(0, 40);
-            const newContent = await generateDagSummary(label, children.map((c) => c.content), opts);
-            if (!newContent) {
-                // LLM null / fetch error → leave dirty for next cycle
-                result.failed++;
-                continue;
-            }
-            const childCreatedAts = children.map((c) => c.created).sort();
-            const { changed, refused } = applyRebuildResult(hippoRoot, summary, {
-                content: newContent,
-                descendant_count: children.length,
-                earliest_at: childCreatedAts[0],
-                latest_at: childCreatedAts[childCreatedAts.length - 1],
-                bumpRebuildCount: true,
-                zeroChildren: false,
-                actor: 'sleep',
-            });
-            if (refused) {
-                result.refused++;
-            }
-            else if (changed) {
-                result.rebuilt++;
-            }
-            // changed=false (refused also false) → race lost; not failure, not
-            // success, silently skip
+            await rebuildOneSummary(hippoRoot, summary, opts, result);
         }
         catch (err) {
             // Per-summary failure isolation — one throw doesn't abort the queue.
@@ -281,6 +301,76 @@ export async function rebuildDirtySummaries(hippoRoot, opts) {
     }
     return result;
 }
+// independent-review HIGH #1 fold: cluster ONLY within-tenant.
+// clusterFacts has no tenant awareness; without this partition step a
+// multi-tenant host could form a cluster spanning tenants and produce
+// a single L3 with tenantId='default' that doesn't belong to either
+// child tenant. Fix: bucket by tenantId, run clusterFacts per-tenant,
+// pass tenantId to createMemory.
+function partitionL2sByTenant(unparented) {
+    const byTenant = new Map();
+    for (const l2 of unparented) {
+        const tid = l2.tenantId ?? 'default';
+        const key = derivationPartitionKey(tid, l2.scope, l2.origin_project);
+        const list = byTenant.get(key) ?? [];
+        list.push(l2);
+        byTenant.set(key, list);
+    }
+    return byTenant;
+}
+/** The L3 profile entry for one cluster of L2 summaries. */
+function createProfileEntry(summary, cluster, home) {
+    const memberCreatedAts = cluster.members.map((m) => m.created).sort();
+    const nowIso = new Date().toISOString();
+    const profileEntry = createMemory(summary, {
+        layer: Layer.Semantic,
+        tags: [...cluster.entityTags, ...neverAutoShareTags(cluster.members), 'dag-entity-profile'],
+        confidence: 'inferred',
+        dag_level: 3,
+        tenantId: home.tenantId, // HIGH #1 fold: thread tenant explicitly
+        scope: home.scope,
+        baseHalfLifeDays: home.baseHalfLifeDays,
+    });
+    profileEntry.origin_project = home.originProject;
+    profileEntry.descendant_count = cluster.members.length;
+    profileEntry.earliest_at = memberCreatedAts[0];
+    profileEntry.latest_at = memberCreatedAts[memberCreatedAts.length - 1];
+    profileEntry.dag_level_3_built_at = nowIso;
+    return profileEntry;
+}
+/** Profile one eligible cluster of L2s, write it, then re-link the L2s under it. */
+async function profileCluster(hippoRoot, cluster, home, opts, result) {
+    const summary = await generateDagSummary(cluster.label, cluster.members.map((m) => m.content), opts);
+    if (!summary) {
+        result.failed++;
+        return;
+    }
+    const profileEntry = createProfileEntry(summary, cluster, home);
+    // AT1 (plan §3 containment): per-cluster catch — skip this cluster,
+    // count, log once. The member re-linking writes below never run for a
+    // skipped cluster (mirrors buildDag above).
+    try {
+        writeEntry(hippoRoot, profileEntry);
+    }
+    catch (err) {
+        if (err instanceof RejectedValueError) {
+            result.rejected++;
+            log.warn(`buildEntityProfiles: cluster "${cluster.label}" skipped: profile matches a rejected value`);
+            return;
+        }
+        throw err;
+    }
+    result.profilesCreated++;
+    for (const member of cluster.members) {
+        const updated = { ...member, dag_parent_id: profileEntry.id };
+        writeEntry(hippoRoot, updated);
+        result.l2sLinked++;
+    }
+    // E3 born-dirty cancellation, same dance as buildDag L161-168 but for
+    // L3. Pass source='buildEntityProfiles-clean' to distinguish in audit.
+    // Args: (root, id, tenantId, actor, source).
+    clearSummaryDirtyAfterBuild(hippoRoot, profileEntry.id, home.tenantId, 'buildEntityProfiles', 'buildEntityProfiles-clean');
+}
 /**
  * v0.30 / E5 — build L3 entity profiles by clustering L2 summaries with
  * shared entity tags. Threshold 2+ L2s per entity. Mirrors buildDag L1->L2
@@ -303,72 +393,18 @@ export async function buildEntityProfiles(hippoRoot, l2Summaries, opts) {
     const baseHalfLifeDays = loadConfig(hippoRoot).defaultHalfLifeDays;
     // Only L2 with no L3 parent yet (avoid re-clustering already-profiled L2s).
     const unparented = l2Summaries.filter((s) => s.dag_level === 2 && !s.dag_parent_id);
-    // independent-review HIGH #1 fold: cluster ONLY within-tenant.
-    // clusterFacts has no tenant awareness; without this partition step a
-    // multi-tenant host could form a cluster spanning tenants and produce
-    // a single L3 with tenantId='default' that doesn't belong to either
-    // child tenant. Fix: bucket by tenantId, run clusterFacts per-tenant,
-    // pass tenantId to createMemory.
-    const byTenant = new Map();
-    for (const l2 of unparented) {
-        const tid = l2.tenantId ?? 'default';
-        const key = derivationPartitionKey(tid, l2.scope, l2.origin_project);
-        const list = byTenant.get(key) ?? [];
-        list.push(l2);
-        byTenant.set(key, list);
-    }
-    for (const [, tenantL2s] of byTenant) {
-        const tenantId = tenantL2s[0].tenantId ?? 'default';
-        const scope = derivationScope(tenantL2s[0].scope);
+    for (const [, tenantL2s] of partitionL2sByTenant(unparented)) {
+        const home = {
+            tenantId: tenantL2s[0].tenantId ?? 'default',
+            scope: derivationScope(tenantL2s[0].scope),
+            originProject: tenantL2s[0].origin_project,
+            baseHalfLifeDays,
+        };
         const clusters = clusterFacts(tenantL2s);
         const eligible = clusters.filter((c) => c.members.length >= 2);
         result.candidateClusters += eligible.length;
         for (const cluster of eligible) {
-            const summary = await generateDagSummary(cluster.label, cluster.members.map((m) => m.content), opts);
-            if (!summary) {
-                result.failed++;
-                continue;
-            }
-            const memberCreatedAts = cluster.members.map((m) => m.created).sort();
-            const nowIso = new Date().toISOString();
-            const profileEntry = createMemory(summary, {
-                layer: Layer.Semantic,
-                tags: [...cluster.entityTags, ...neverAutoShareTags(cluster.members), 'dag-entity-profile'],
-                confidence: 'inferred',
-                dag_level: 3,
-                tenantId, // HIGH #1 fold: thread tenant explicitly
-                scope,
-                baseHalfLifeDays,
-            });
-            profileEntry.origin_project = tenantL2s[0].origin_project;
-            profileEntry.descendant_count = cluster.members.length;
-            profileEntry.earliest_at = memberCreatedAts[0];
-            profileEntry.latest_at = memberCreatedAts[memberCreatedAts.length - 1];
-            profileEntry.dag_level_3_built_at = nowIso;
-            // AT1 (plan §3 containment): per-cluster catch — skip this cluster,
-            // count, log once. The member re-linking writes below never run for a
-            // skipped cluster (mirrors buildDag above).
-            try {
-                writeEntry(hippoRoot, profileEntry);
-            }
-            catch (err) {
-                if (err instanceof RejectedValueError) {
-                    result.rejected++;
-                    log.warn(`buildEntityProfiles: cluster "${cluster.label}" skipped: profile matches a rejected value`);
-                    continue;
-                }
-                throw err;
-            }
-            result.profilesCreated++;
-            for (const member of cluster.members) {
-                const updated = { ...member, dag_parent_id: profileEntry.id };
-                writeEntry(hippoRoot, updated);
-                result.l2sLinked++;
-            }
-            // E3 born-dirty cancellation, same dance as buildDag L161-168 but for
-            // L3. Pass source='buildEntityProfiles-clean' to distinguish in audit.
-            // Args: (root, id, tenantId, actor, source).
-            clearSummaryDirtyAfterBuild(hippoRoot, profileEntry.id, tenantId, 'buildEntityProfiles', 'buildEntityProfiles-clean');
+            await profileCluster(hippoRoot, cluster, home, opts, result);
         }
     }
     return result;

package/dist/decisions.js

@@ -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. codex review 2026-05-28 (P1).
+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 BadRequestError(`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,88 +168,14 @@ 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