hippo-memory 1.70.0 → 1.72.0

package/dist/consolidate/dedupe.js

@@ -1,66 +1,22 @@
-/**
- * Store-level deduplication. Scans for memories with the same text apart
- * from spacing, keeps the stronger copy (by strength + retrieval count),
- * removes the rest.
- *
- * Extracted from cli.ts in Episode A (v1.11.3) so `api.sleep` can dedupe
- * during the consolidation pipeline without violating the cli -> api
- * dependency direction. `cmdDedup` in cli.ts continues to import and use
- * this function unchanged.
- *
- * Survivor selection is a total order as of v1.26.3
- * (docs/plans/2026-07-16-dedupe-survivor-determinism.md): strength bucket
- * desc -> retrieval_count desc -> compareEntryIdentity (content asc ->
- * layer rank -> tags -> source -> id asc; the metadata keys arrived in
- * v1.38.1, docs/plans/2026-09-04-dedupe-survivor-metadata.md). Previously
- * the strength/retrieval-count comparator could tie exactly with no terminal
- * key, so the survivor fell to load order (arrival-order-dependent); see
- * `strengthBucket` below for the bucket encoding. As of the tenant-partition
- * fix (docs/plans/2026-08-15-dedupe-tenant-partition.md) the order is scoped
- * WITHIN each tenant group; cross-tenant pairs are never compared. Raw and
- * superseded rows are not candidates at all (v1.38.1).
- */
+/** Store-level dedup: same text apart from spacing, keeping the stronger copy; split out so `api.sleep` can dedupe without cli -> api imports.
+ * Survivor order is total and tenant-scoped: strength bucket, retrieval_count, then compareEntryIdentity; raw and superseded rows are not candidates. */
 import { textOverlap } from '../util/tokenize.js';
 import { loadCurrentDistilledEntries } from '../store/entry-reads.js';
 import { deleteEntriesOneByOne, memoriesBackingObjects } from '../store/delete-and-batch.js';
 import { compareEntryIdentity } from '../core/compare.js';
 import { canAutoDelete } from '../core/memory.js';
-import { derivationPartitionKey } from '../store/recall-scope.js';
+import { derivationPartitionKey } from '../core/recall-scope.js';
 import { duplicateKey } from '../util/same-text.js';
-/** Quantization step for strength-tie comparisons. The historical 0.01
- *  epsilon (see `strengthBucket` below) applied via rounding instead of a
- *  raw abs-diff threshold, so the tiebreak is transitive. */
+/** Quantization step for strength-tie comparisons: the 0.01 epsilon applied by rounding instead of an abs-diff threshold, so the tiebreak is transitive. */
 const STRENGTH_TIE_EPSILON = 0.01;
-/**
- * Quantize a strength value into an integer "bucket" for tie comparison.
- *
- * Encodes the historical 0.01 epsilon transitively: two strengths compare
- * equal here iff they round to the same multiple of `STRENGTH_TIE_EPSILON`,
- * which (unlike a raw `Math.abs(a - b) > epsilon` check) is a genuine
- * equivalence relation — no more "A ties B, B ties C, but A beats C"
- * (see the file-level history note above).
- *
- * Non-finite input (`NaN`, `+/-Infinity`) maps to bucket `0` rather than
- * propagating: a NaN bucket would make the sort comparator return NaN,
- * silently reintroducing the non-total-order class this fix exists to kill.
- * (`null`/`undefined` already default to strength `0` via `?? 0`, same as
- * before this change.)
- *
- * Bucket-edge nuance: two strengths straddling a bucket edge (e.g. 0.0049 vs
- * 0.0051) now compare as different, where the old raw-epsilon check called
- * them tied. The flip always favors the not-weaker entry, and the OLD
- * behavior at such pairs was itself order/engine-dependent (the defect this
- * fix exists to kill) — so there is no stable prior behavior being broken.
- */
+/** Quantize strength to an integer bucket so ties are a true equivalence relation (equal iff same multiple of `STRENGTH_TIE_EPSILON`).
+ * Non-finite input maps to 0: a NaN bucket would make the comparator return NaN and break the total order. */
 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.
+// finiteCount hardens the retrieval leg like strengthBucket: a NaN would break the total order.
+// Unreachable via the schema (non-nullable INTEGER column); kept for symmetry.
 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) {
@@ -72,12 +28,8 @@ function survivorOrder(a, b) {
         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.
+// Tenant partition: group by tenantId before sorting so a duplicate pair never forms across tenants; Map keeps insertion order,
+// so a single-tenant store gets one group and the same result as a global pass.
 function entriesByPartition(entries) {
     const entriesByTenant = new Map();
     for (const entry of entries) {
@@ -121,28 +73,20 @@ function partitionPairs(tenantEntries, removed, backing) {
     }
     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,
- * path, name), AND the same tenant: the scan is partitioned by
- * tenantId, so byte-identical content in two tenants is never a duplicate
- * pair (the tenant boundary is an isolation boundary; cross-tenant removal
- * was the v1.32.0 known-issue data-loss bug).
- * Keeps the one with higher strength (or more retrievals if tied). `threshold` is accepted for old callers and ignored.
- */
+/** The rows loadCurrentDistilledEntries selects, picked from a whole-store read. */
+const isCurrentDistilled = (e) => (e.kind ?? 'distilled') === 'distilled' && !e.superseded_by;
+/** Remove the weaker copy of same-text (apart from spacing) memories within one tenant; cross-tenant pairs are never duplicates (isolation boundary).
+ * Higher strength wins, then more retrievals; `threshold` is accepted for old callers and ignored. */
 export function deduplicateStore(hippoRoot, options = {}) {
     const dryRun = options.dryRun ?? false;
     // 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 = loadCurrentDistilledEntries(hippoRoot);
+    // trigger would abort sleep mid-loop) and superseded rows are history.
+    const entries = options.loaded?.entries.filter(isCurrentDistilled) ?? loadCurrentDistilledEntries(hippoRoot);
     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
-    // primary-key id alone.
+    // Shared across tenant groups: ids are globally unique UUIDs, so `removed` cannot collide across tenants and deleteEntry deletes by primary key alone.
     const removed = new Set();
     const pairs = [];
-    const backing = memoriesBackingObjects(hippoRoot);
+    const backing = options.loaded?.backing ?? memoriesBackingObjects(hippoRoot);
     for (const tenantEntries of entriesByTenant.values()) {
         // 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.

package/dist/consolidate/flush-units.d.ts

@@ -1,9 +1,8 @@
 import type { MemoryEntry } from '../core/memory.js';
 import type { DormantMove } from '../store/dormant.js';
-import type { FlushComponent } from '../store/delete-and-batch.js';
+import type { FlushComponent, LoadedRows } from '../store/delete-and-batch.js';
 /** Components that share no id, ordered by each one's first op across writes, then deletes, then dormant moves. */
 export declare function groupFlush(writes: readonly MemoryEntry[], deletes: readonly string[], dormant: readonly DormantMove[], units: readonly (readonly string[])[]): FlushComponent[];
-/** [child, parent] for each queued op on a child whose DAG parent the run removes: a child's change marks the parent
- *  dirty, and one transaction always applied that mark after the parent was gone, so it audited nothing. */
-export declare function familyUnits(writes: readonly MemoryEntry[], deletes: readonly string[], dormant: readonly DormantMove[], snapshot: ReadonlyMap<string, MemoryEntry>): string[][];
+/** [child, parent] per queued op on a child whose DAG parent the run removes: the parent-dirty mark otherwise lands after the parent is gone. */
+export declare function familyUnits(writes: readonly MemoryEntry[], deletes: readonly string[], dormant: readonly DormantMove[], snapshot: LoadedRows): string[][];
 //# sourceMappingURL=flush-units.d.ts.map

package/dist/consolidate/flush-units.js

@@ -42,9 +42,9 @@ function unionFind(units) {
     }
     return find;
 }
-/** [child, parent] for each queued op on a child whose DAG parent the run removes: a child's change marks the parent
- *  dirty, and one transaction always applied that mark after the parent was gone, so it audited nothing. */
-// SHORTCUT: a removed parent and all its changed children commit as one component, so one hold can pass holdMs by a family's size; split by child if a family grows large.
+/** [child, parent] per queued op on a child whose DAG parent the run removes: the parent-dirty mark otherwise lands after the parent is gone. */
+// SHORTCUT: a removed parent and all its changed children commit as one component, so
+// one hold can pass holdMs by a family's size; split by child if a family grows large.
 export function familyUnits(writes, deletes, dormant, snapshot) {
     const removing = new Set([...deletes, ...dormant.map((m) => m.entry.id)]);
     const units = [];

package/dist/consolidate/half-life-migration.d.ts

@@ -1,24 +1,5 @@
-/**
- * Moving a store's memories to a new default half-life.
- *
- * Each memory stores its own `half_life_days`, set at write from the
- * default base and a few write-time multipliers (`deriveHalfLife`). Changing
- * the default therefore reaches only new memories; without this migration a
- * store would mix old-base and new-base memories, a state the decay
- * evaluation never tested. The rule, declared before any run:
- *
- * - only a memory still on the old base is rescaled: its half-life is
- *   `deriveHalfLife(from, entry)` plus its recall bonus. A memory hippo shortened since
- *   (invalidated, superseded, a merge source, marked bad) or one with its own
- *   fixed half-life (decisions, incidents, customer notes) keeps its value;
- * - every rescale is written to the audit log with the ids, so it can be
- *   undone, and the store records the base it is on (`meta`), so the
- *   migration runs once.
- *
- * `hippo sleep` runs it before its decay pass, from the base the store is on
- * (7 days when never recorded) to the configured `defaultHalfLifeDays`. Once per store it also
- * moves memories of live decisions, incidents and other objects off the flat 90 days they used to get.
- */
+/** Moves a store's memories to a new default half-life: only memories still on the old base are rescaled (`deriveHalfLife(from, entry)` plus recall bonus).
+ * Memories hippo shortened since, or with their own fixed half-life, keep theirs; rescales are audit-logged and `meta` records the base, so it runs once. */
 import { type MemoryEntry } from '../core/memory.js';
 import { HALF_LIFE_BASE_META_KEY, LEGACY_TYPED_HALF_LIFE } from '../store/open.js';
 export { HALF_LIFE_BASE_META_KEY, LEGACY_TYPED_HALF_LIFE };
@@ -45,11 +26,7 @@ export declare function planHalfLifeMigration(entries: readonly MemoryEntry[], f
 export declare function planTypedHalfLifeMigration(entries: readonly MemoryEntry[], to: number): MemoryEntry[];
 /** The base this store's memories are on. */
 export declare function storeHalfLifeBase(hippoRoot: string): number;
-/**
- * Move the store's memories from the base they are on, and those of objects from
- * the old flat 90 days, to `to`, once. Under `dryRun` nothing is written, the recorded
- * base included.
- */
+/** Move the store's memories, and those of objects on the old flat 90 days, from their recorded base to `to`, once; `dryRun` writes nothing. */
 export declare function migrateDefaultHalfLife(hippoRoot: string, to: number, opts?: {
     dryRun?: boolean;
     actor?: string;

package/dist/consolidate/half-life-migration.js

@@ -1,24 +1,5 @@
-/**
- * Moving a store's memories to a new default half-life.
- *
- * Each memory stores its own `half_life_days`, set at write from the
- * default base and a few write-time multipliers (`deriveHalfLife`). Changing
- * the default therefore reaches only new memories; without this migration a
- * store would mix old-base and new-base memories, a state the decay
- * evaluation never tested. The rule, declared before any run:
- *
- * - only a memory still on the old base is rescaled: its half-life is
- *   `deriveHalfLife(from, entry)` plus its recall bonus. A memory hippo shortened since
- *   (invalidated, superseded, a merge source, marked bad) or one with its own
- *   fixed half-life (decisions, incidents, customer notes) keeps its value;
- * - every rescale is written to the audit log with the ids, so it can be
- *   undone, and the store records the base it is on (`meta`), so the
- *   migration runs once.
- *
- * `hippo sleep` runs it before its decay pass, from the base the store is on
- * (7 days when never recorded) to the configured `defaultHalfLifeDays`. Once per store it also
- * moves memories of live decisions, incidents and other objects off the flat 90 days they used to get.
- */
+/** Moves a store's memories to a new default half-life: only memories still on the old base are rescaled (`deriveHalfLife(from, entry)` plus recall bonus).
+ * Memories hippo shortened since, or with their own fixed half-life, keep theirs; rescales are audit-logged and `meta` records the base, so it runs once. */
 import { deriveHalfLife } from '../core/memory.js';
 import { HALF_LIFE_BASE_META_KEY, LEGACY_TYPED_HALF_LIFE } from '../store/open.js';
 import { moveHalfLives, recordedHalfLifeBase } from '../store/half-life.js';
@@ -53,11 +34,7 @@ export function planTypedHalfLifeMigration(entries, to) {
 export function storeHalfLifeBase(hippoRoot) {
     return recordedHalfLifeBase(hippoRoot);
 }
-/**
- * Move the store's memories from the base they are on, and those of objects from
- * the old flat 90 days, to `to`, once. Under `dryRun` nothing is written, the recorded
- * base included.
- */
+/** Move the store's memories, and those of objects on the old flat 90 days, from their recorded base to `to`, once; `dryRun` writes nothing. */
 export function migrateDefaultHalfLife(hippoRoot, to, opts = {}) {
     const dryRun = opts.dryRun ?? false;
     const { from, outcome } = moveHalfLives(hippoRoot, to, { dryRun, actor: opts.actor ?? 'system' }, (rows) => {
@@ -65,7 +42,12 @@ export function migrateDefaultHalfLife(hippoRoot, to, opts = {}) {
         const plan = [...basePlan, ...typedPlan];
         return {
             moves: [{ from: rows.from, to, entries: basePlan }, { from: LEGACY_TYPED_HALF_LIFE, to, entries: typedPlan }],
-            outcome: { rescaled: basePlan.length, typed: typedPlan.length, kept: rows.all.length - plan.length, halfLives: new Map(plan.map((e) => [e.id, e.half_life_days])) },
+            outcome: {
+                rescaled: basePlan.length,
+                typed: typedPlan.length,
+                kept: rows.all.length - plan.length,
+                halfLives: new Map(plan.map((e) => [e.id, e.half_life_days]))
+            },
         };
     });
     const moved = outcome ?? { rescaled: 0, typed: 0, kept: 0, halfLives: new Map() };
@@ -94,7 +76,8 @@ function objectMemoryIds(objectRows) {
     }
     return { all, retired };
 }
-/** Memories that lost a conflict, which resolveConflict halved untagged. A resolved conflict with no audit row (resolved before resolves were audited, or found stale) names no winner, so both sides count. */
+/** Memories that lost a conflict, which resolveConflict halved untagged. A resolved conflict with no audit
+ * row (resolved before resolves were audited, or found stale) names no winner, so both sides count. */
 function conflictLosers(audited, resolved) {
     const losers = new Set(audited.map((a) => a.loserId));
     const named = new Set(audited.map((a) => a.conflictId));

package/dist/consolidate/llm-passes.js

@@ -1,8 +1,11 @@
 import { envAnthropicApiKey, envDagRebuildCap } from '../util/env.js';
 import { Layer } from '../core/memory.js';
-import { log } from '../util/log.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { keptAsWritten } from './run.js';
 import { isReusable } from '../core/memory-quality.js';
+import { isPermanentFailure } from '../util/anthropic-messages.js';
+// Bounds the LLM calls one sleep spends on extraction.
+const EXTRACTION_BATCH_LIMIT = 20;
 /** The key, model options and once-per-line error reporter every LLM phase shares. */
 function sleepLlm(run, fetcher) {
     const { config, result } = run;
@@ -21,30 +24,17 @@ function sleepLlm(run, fetcher) {
     return { apiKey, llmError, llmOpts };
 }
 export async function llmPasses(run, fetcher) {
-    // -------------------------------------------------------------------------
     // 1.6. Batch extraction — extract facts from episodic memories missing them
-    // -------------------------------------------------------------------------
     const extractedFromIds = new Set(run.survivors.filter((e) => e.extracted_from).map((e) => e.extracted_from));
     const extractionCandidates = run.survivors.filter((e) => e.layer === Layer.Episodic && !e.superseded_by && !extractedFromIds.has(e.id) && !keptAsWritten(e)
         && e.trace_outcome === null && e.source !== 'auto-promote' && isReusable(e));
     run.result.extractionCandidates = extractionCandidates.length;
     const llm = sleepLlm(run, fetcher);
     if (llm.apiKey && extractionCandidates.length > 0 && !run.dryRun) {
-        const { extractFacts, storeExtractedFacts } = await import('../learn/extract.js');
-        const batchLimit = 20;
-        let extractedCount = 0;
-        for (const candidate of extractionCandidates.slice(0, batchLimit)) {
-            try {
-                const facts = await extractFacts(candidate.content, { ...llm.llmOpts, onError: llm.llmError('extraction') });
-                if (facts.length > 0) {
-                    extractedCount += storeExtractedFacts(run.hippoRoot, candidate, facts).length;
-                }
-            }
-            catch (err) {
-                llm.llmError('extraction')(String(err));
-            }
-        }
-        run.result.extracted = extractedCount;
+        const stopped = await extractionPass(run, llm, extractionCandidates.slice(0, EXTRACTION_BATCH_LIMIT));
+        // The DAG passes call the same API with the same key and model, so they would fail the same way.
+        if (stopped)
+            return;
     }
     await dagBuildPass(run, llm);
     if (llm.apiKey && !run.dryRun) {
@@ -52,9 +42,38 @@ export async function llmPasses(run, fetcher) {
         await entityProfilePass(run, llm);
     }
 }
-// -------------------------------------------------------------------------
+/** Extracts facts from each candidate; true when it stopped on a failure every later call would repeat (bad key, no credit, unknown model). */
+async function extractionPass(run, llm, batch) {
+    const { extractFacts, storeExtractedFacts } = await import('../learn/extract.js');
+    const report = llm.llmError('extraction');
+    let extractedCount = 0;
+    let stopped = false;
+    const onError = (msg, failure) => {
+        report(msg);
+        if (failure && isPermanentFailure(failure))
+            stopped = true;
+    };
+    for (const [index, candidate] of batch.entries()) {
+        try {
+            const facts = await extractFacts(candidate.content, { ...llm.llmOpts, onError });
+            if (facts.length > 0) {
+                extractedCount += storeExtractedFacts(run.hippoRoot, candidate, facts).length;
+            }
+        }
+        catch (err) {
+            report(errorMessage(err));
+            log.warn('consolidate extraction threw', errorFields(err));
+        }
+        if (stopped) {
+            const skipped = batch.length - index - 1;
+            report(`stopped after a failure that will not clear on retry; ${skipped} of ${batch.length} candidates skipped, and the DAG passes with them`);
+            break;
+        }
+    }
+    run.result.extracted = extractedCount;
+    return stopped;
+}
 // 1.7. DAG summarization — cluster extracted facts and generate summaries
-// -------------------------------------------------------------------------
 async function dagBuildPass(run, { apiKey, llmError, llmOpts }) {
     const extractedFacts = run.survivors.filter((e) => e.tags.includes('extracted') && e.dag_level === 1 && !e.superseded_by && isReusable(e));
     if (!(apiKey && extractedFacts.length >= 3 && !run.dryRun))
@@ -69,17 +88,12 @@ async function dagBuildPass(run, { apiKey, llmError, llmOpts }) {
         }
     }
     catch (err) {
-        llmError('dag')(String(err));
+        llmError('dag')(errorMessage(err));
+        log.warn('consolidate dag threw', errorFields(err));
     }
 }
-// -------------------------------------------------------------------------
-// 1.8. DAG summary rebuild — drain dirty queue from the child-write hooks
-// -------------------------------------------------------------------------
-// Consumer of the summary_dirty flag. Walks dirty L2 summaries, regenerates
-// each via generateDagSummary, atomically refreshes content + 6 metadata
-// columns + clears summary_dirty (with FTS sync). Same apiKey/dryRun gate
-// as buildDag above. Cap HIPPO_DAG_REBUILD_CAP (default 20, hard ceiling
-// 1000) prevents runaway LLM cost.
+// 1.8. DAG summary rebuild: drain the summary_dirty queue set by child-write hooks; same apiKey/dryRun gate as buildDag.
+// Cap HIPPO_DAG_REBUILD_CAP (default 20, hard ceiling 1000) prevents runaway LLM cost.
 async function dagRebuildPass(run, { llmError, llmOpts }) {
     const { result } = run;
     try {
@@ -109,18 +123,12 @@ async function dagRebuildPass(run, { llmError, llmOpts }) {
         }
     }
     catch (err) {
-        llmError('dag rebuild')(String(err));
+        llmError('dag rebuild')(errorMessage(err));
+        log.warn('consolidate dag rebuild threw', errorFields(err));
     }
 }
-// -------------------------------------------------------------------------
-// 1.9. DAG entity profiles — cluster L2 topic summaries into L3 profiles
-// -------------------------------------------------------------------------
-// Aggregate per-entity L2 summaries (e.g. all the speaker:Alice
-// topic summaries) into a single L3 entity profile. Runs even when phase
-// 1.7 buildDag was skipped (re-clusters existing L2s every sleep).
-//
-// Uses loadAllL2Summaries (not `survivors`) because phase 1.7 wrote new
-// L2s directly via writeEntry without pushing back into survivors.
+// 1.9. DAG entity profiles: cluster L2 summaries into per-entity L3 profiles; runs even when 1.7 was skipped (re-clusters existing L2s every sleep).
+// Uses loadAllL2Summaries, not `survivors`: phase 1.7 wrote new L2s via writeEntry without pushing them into survivors.
 async function entityProfilePass(run, { llmError, llmOpts }) {
     try {
         const { buildEntityProfiles } = await import('./dag.js');
@@ -135,7 +143,8 @@ async function entityProfilePass(run, { llmError, llmOpts }) {
         }
     }
     catch (err) {
-        llmError('dag profiles')(String(err));
+        llmError('dag profiles')(errorMessage(err));
+        log.warn('consolidate dag profiles threw', errorFields(err));
     }
 }
 //# sourceMappingURL=llm-passes.js.map

package/dist/consolidate/memory-value-weights.d.ts

@@ -1,16 +1,5 @@
-/**
- * Frozen learned memory-value weight vector.
- *
- * GENERATED FROM the frozen artifact
- * (benchmarks/memory-value/weights-learned.json +
- * benchmarks/memory-value/weights-learned.meta.json). NEVER EDIT BY HAND —
- * tests/memory-value-wiring.test.ts's weights-sync test asserts this constant
- * equals the committed JSON artifact (value equality + digest match), so
- * drift between the artifact and this file fails CI.
- *
- * CAVEAT: usage-feature signs reflect an anti-oracle simulation, NOT real usage
- * value. Never read this as production ranking advice.
- */
+/** Frozen learned memory-value weight vector, GENERATED from benchmarks/memory-value/weights-learned.json; never edit by hand (a sync test fails CI on drift).
+ * CAVEAT: usage-feature signs come from an anti-oracle simulation, not real usage value; never read this as production ranking advice. */
 /** The 8 live feature dims the fitter optimized over (FIT_DIMS). */
 export declare const MEMORY_VALUE_WEIGHTS: Readonly<Record<string, number>>;
 /** sha256 of benchmarks/memory-value/weights-learned.json at freeze time

package/dist/consolidate/memory-value-weights.js

@@ -1,16 +1,5 @@
-/**
- * Frozen learned memory-value weight vector.
- *
- * GENERATED FROM the frozen artifact
- * (benchmarks/memory-value/weights-learned.json +
- * benchmarks/memory-value/weights-learned.meta.json). NEVER EDIT BY HAND —
- * tests/memory-value-wiring.test.ts's weights-sync test asserts this constant
- * equals the committed JSON artifact (value equality + digest match), so
- * drift between the artifact and this file fails CI.
- *
- * CAVEAT: usage-feature signs reflect an anti-oracle simulation, NOT real usage
- * value. Never read this as production ranking advice.
- */
+/** Frozen learned memory-value weight vector, GENERATED from benchmarks/memory-value/weights-learned.json; never edit by hand (a sync test fails CI on drift).
+ * CAVEAT: usage-feature signs come from an anti-oracle simulation, not real usage value; never read this as production ranking advice. */
 /** The 8 live feature dims the fitter optimized over (FIT_DIMS). */
 export const MEMORY_VALUE_WEIGHTS = Object.freeze({
     age_days: -0.3245577821391783,

package/dist/consolidate/memory-value.d.ts

@@ -1,23 +1,5 @@
-/**
- * Learned memory-value scorer, wired into the sleep decay pass as a
- * rescue-only veto.
- *
- * computeMvFeatures mirrors benchmarks/memory-value/extract.mjs's
- * computeFeatures for the 8 live dims the fitter optimized over
- * (FIT_DIMS) — the only dims MEMORY_VALUE_WEIGHTS carries a weight for.
- * Any future edit to either side must keep them byte-equivalent; the parity
- * test in tests/memory-value-wiring.test.ts enforces this.
- *
- * scoreEntries mirrors benchmarks/memory-value/evaluate.mjs's per-store
- * min-max normalization + weighted scorer (no additional orientation
- * multiply — the frozen weights already encode sign/orientation).
- *
- * rescueSet implements rescue-only semantics: a condemned entry is
- * rescued iff its learned score ranks in the top 30% (RESCUE_BUDGET, the
- * measured keep-budget operating point) of its own tenant's non-pinned
- * candidate set. Deletes(flag-on) subset Deletes(flag-off) by construction — this
- * function can only ever shrink the condemned set, never grow it.
- */
+/** Learned memory-value scorer, a rescue-only veto in the sleep decay pass (it can only shrink the condemned set); mirrors benchmarks/memory-value/*.mjs.
+ * rescueSet rescues a condemned entry iff it ranks in the top 30% (RESCUE_BUDGET) of its tenant's non-pinned set; memory-value-wiring.test.ts guards parity. */
 import { type MemoryEntry } from '../core/memory.js';
 /** The 8 live feature dims (FIT_DIMS) — canonical order for iteration. */
 export declare const MV_FEATURE_NAMES: ReadonlyArray<keyof MvFeatureVector>;
@@ -31,44 +13,14 @@ export interface MvFeatureVector {
     outcome_ratio: number;
     content_length: number;
 }
-/**
- * Blind v1 feature dict for one MemoryEntry, restricted to the 8 dims the
- * frozen weights carry (mirrors extract.mjs's computeFeatures).
- *
- * CRITICAL: `strength` is CLOCK-BASIS `calculateStrength(entry, now)` with
- * NO DecayOptions — that is how the frozen weights' training features were
- * computed (extract.mjs never passes decayOpts). Passing the production
- * decay basis (config.decayBasis via consolidate.ts's decayOpts) into this
- * feature would silently break parity with the frozen weight vector. This
- * is an intentional divergence from the condemnation TRIGGER in
- * consolidate.ts, which keeps using decayOpts as today — only the rescue
- * FEATURE is clock-basis.
- */
+/** Blind v1 feature dict for one entry, restricted to the 8 dims the frozen weights carry. `strength` is CLOCK-BASIS `calculateStrength(entry, now)` with no
+ * DecayOptions, as in the weights' training; passing the production decay basis would silently break parity with the frozen weights. */
 export declare function computeMvFeatures(entry: MemoryEntry, now: Date): MvFeatureVector;
 export declare function validateWeights(weights?: Readonly<Record<string, number>>, digest?: string): void;
-/**
- * Min-max normalize each of the 8 features over the given entry set
- * (constant feature -> 0, matching evaluate.mjs), then score = dot(weights,
- * normalized). The normalization context is exactly the entries passed in —
- * callers control the bounded scope (per-tenant, non-pinned).
- *
- * `weights` defaults to the real frozen singleton; parameterized (like
- * validateWeights) so callers/tests can score against an explicit vector
- * without touching the module singleton.
- *
- * Non-finite features: Date.parse on a malformed `created`
- * string yields NaN, and NaN would silently corrupt every OTHER entry's
- * min-max in the same group. An entry with ANY non-finite computed feature
- * is excluded from the normalization context entirely (its raw values never
- * touch min/max) and always scores -Infinity — the lowest possible score, so
- * it sorts to the bottom of its tenant deterministically and (via rescueSet's
- * explicit finite-score guard below) can never be rescued. Conservative
- * direction: deletes(flag-on) subset deletes(flag-off) still holds.
- */
+/** Min-max normalize the 8 features over the given entries (constant -> 0), then score = dot(weights, normalized); callers set the scope.
+ * An entry with any non-finite feature (NaN from a malformed `created`) is excluded from normalization and scores -Infinity, so it can never be rescued. */
 export declare function scoreEntries(entries: MemoryEntry[], now: Date, weights?: Readonly<Record<string, number>>): Map<string, number>;
-/** Per-entry rank context within its tenant's non-pinned candidate set —
- *  the score-rank basis both rescueSet's rescue decision and consolidate.ts's
- *  audit-row metadata read from. */
+/** Per-entry rank context within its tenant's non-pinned candidate set: the basis both rescueSet and the consolidate audit-row metadata read. */
 export interface MvRankInfo {
     tenantId: string;
     score: number;
@@ -79,40 +31,15 @@ export interface MvRankInfo {
     /** ceil(RESCUE_BUDGET * totalNonPinned) — the rescue cutoff; rank <= keepN rescues. */
     keepN: number;
 }
-/**
- * Groups non-pinned entries by tenantId, scores + ranks each tenant's
- * group independently, and returns per-entry rank context for every
- * non-pinned entry (not just condemned ones) — the shared basis for both
- * rescueSet's rescue decision and consolidate.ts's audit-row rank context,
- * so the two never compute the ranking differently.
- *
- * `weights`/`digest` default to the real frozen singleton — parameterized
- * (like validateWeights/scoreEntries) purely for direct unit-testability of
- * the fail-loud path, never overridden by production callers.
- */
+/** Group non-pinned entries by tenantId, score and rank each group independently, and return rank context for every non-pinned entry;
+ * rescueSet and the consolidate audit rows share it so they never compute the ranking differently. */
 export declare function rankNonPinnedByTenant(entries: MemoryEntry[], now: Date, weights?: Readonly<Record<string, number>>, digest?: string): Map<string, MvRankInfo>;
 export interface RescueSetOptions {
     readonly weights?: Readonly<Record<string, number>>;
     readonly digest?: string;
     readonly precomputedRanks?: Map<string, MvRankInfo>;
 }
-/**
- * Rescue decision: a condemned entry is rescued iff it ranks in the top
- * 30% of its tenant's non-pinned candidate set by learned score. Returns the
- * subset of condemnedIds that are rescued — the caller filters commits
- * (rescued -> survivors) and threads the same set into detectConflicts.
- *
- * `weights`/`digest` default to the real frozen singleton; production
- * callers (consolidate.ts) never pass overrides — the params exist purely so
- * "flag on + a broken constant throws" is directly testable end-to-end
- * through this function without mutating the frozen module singleton.
- *
- * `precomputedRanks`: when the caller has already
- * computed the per-tenant ranking (e.g. consolidate.ts needs it separately
- * for detail/audit rank context), pass it here to skip the internal
- * rankNonPinnedByTenant call — the whole-store ranking pass then runs
- * exactly once per sleep instead of twice. Omitted (the default), rescueSet
- * computes it internally as before — existing callers/tests are unaffected.
- */
+/** Rescue decision: the subset of condemnedIds ranking in the top 30% of their tenant's non-pinned set by learned score.
+ * Pass `precomputedRanks` to skip the internal ranking so the whole-store pass runs once per sleep; `weights`/`digest` overrides exist for tests only. */
 export declare function rescueSet(entries: MemoryEntry[], condemnedIds: Set<string>, now: Date, options?: RescueSetOptions): Set<string>;
 //# sourceMappingURL=memory-value.d.ts.map