hippo-memory 2.0.0 → 2.1.0

package/dist/consolidate/dedupe.js

@@ -1,15 +1,22 @@
-/** 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. */
+/**
+ * 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 '../core/recall-scope.js';
 import { duplicateKey } from '../util/same-text.js';
-/** Quantization step for strength-tie comparisons: the 0.01 epsilon applied by rounding instead of an 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 strength to an integer bucket so ties are a true equivalence relation (equal iff same multiple of `STRENGTH_TIE_EPSILON`).
+/**
+ * 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;
@@ -28,7 +35,8 @@ function survivorOrder(a, b) {
         return retrievalDiff;
     return compareEntryIdentity(a, b);
 }
-// Tenant partition: group by tenantId before sorting so a duplicate pair never forms across tenants; Map keeps insertion order,
+// 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();
@@ -73,33 +81,36 @@ function partitionPairs(tenantEntries, removed, backing) {
     }
     return [...groups.values()].flatMap((group) => group.pairs);
 }
-/** The rows loadCurrentDistilledEntries selects, picked from a whole-store read. */
+/** The rows currentDistilledEntries 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).
+/**
+ * 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 = {}) {
+export function deduplicateStore(store, 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.
-    const entries = options.loaded?.entries.filter(isCurrentDistilled) ?? loadCurrentDistilledEntries(hippoRoot);
+    const entries = options.loaded?.entries.filter(isCurrentDistilled) ?? store.currentDistilledEntries();
     const entriesByTenant = entriesByPartition(entries);
-    // Shared across tenant groups: ids are globally unique UUIDs, so `removed` cannot collide across tenants and deleteEntry deletes by primary key 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 = options.loaded?.backing ?? memoriesBackingObjects(hippoRoot);
+    const backing = options.loaded?.backing ?? store.objectBackedIds();
     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.
         tenantEntries.sort(survivorOrder);
         pairs.push(...partitionPairs(tenantEntries, removed, backing));
     }
-    const done = dryRun ? pairs : deletePairs(hippoRoot, pairs, options.actor);
+    const done = dryRun ? pairs : deletePairs(store, 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) {
+function deletePairs(store, pairs, actor) {
     const targets = pairs.map((p) => ({ id: p.removed, reason: `dedup: duplicate of ${p.kept}` }));
-    const gone = deleteEntriesOneByOne(hippoRoot, targets, { actor, automatic: true });
+    const gone = store.deleteOneByOne(targets, { actor, automatic: true });
     return pairs.filter((_, i) => gone[i]);
 }
 //# sourceMappingURL=dedupe.js.map

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

@@ -3,6 +3,9 @@ import type { DormantMove } from '../store/dormant.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] per queued op on a child whose DAG parent the run removes: the parent-dirty mark otherwise lands after the parent is gone. */
+/**
+ * [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,7 +42,10 @@ function unionFind(units) {
     }
     return find;
 }
-/** [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. */
+/**
+ * [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) {

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

@@ -1,8 +1,11 @@
-/** 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. */
+/**
+ * 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 };
+import type { Consolidation } from '../store/port.js';
 /** What {@link migrateDefaultHalfLife} did, or would do under `dryRun`. */
 export interface HalfLifeMigrationResult {
     from: number;
@@ -22,13 +25,20 @@ type HalfLifeFields = Pick<MemoryEntry, 'half_life_days' | 'tags' | 'schema_fit'
 export declare function halfLifeRecallBonus(entry: HalfLifeFields, written: number): number | null;
 /** The entries to rescale from `from` to `to`, as copies that keep their recall bonus. Pure. */
 export declare function planHalfLifeMigration(entries: readonly MemoryEntry[], from: number, to: number): MemoryEntry[];
-/** Memories of decisions, incidents and other objects still on the flat 90 days, as copies on `to` that keep their recall bonus. Pure. */
+/**
+ * Memories of decisions, incidents and other objects still on the flat 90 days, as copies on `to` that keep their
+ * recall bonus. Pure.
+ */
 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, 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?: {
+export declare function storeHalfLifeBase(store: Consolidation): number;
+/**
+ * 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(store: Consolidation, to: number, opts?: {
     dryRun?: boolean;
     actor?: string;
 }): HalfLifeMigrationResult;
+export {};
 //# sourceMappingURL=half-life-migration.d.ts.map

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

@@ -1,10 +1,19 @@
-/** 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';
-const TYPED_SOURCES = new Set(['decision', 'incident', 'process', 'policy', 'skill', 'project_brief', 'customer_note']);
-export { HALF_LIFE_BASE_META_KEY, LEGACY_TYPED_HALF_LIFE };
+/**
+ * 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, LEGACY_TYPED_HALF_LIFE } from '../core/memory.js';
+const TYPED_SOURCES = new Set([
+    'decision',
+    'incident',
+    'process',
+    'policy',
+    'skill',
+    'project_brief',
+    'customer_note',
+]);
 /** Recall bonus over `written`, the half-life `entry` got at write, or null when off it; each recall added 2 days. */
 export function halfLifeRecallBonus(entry, written) {
     if (entry.superseded_by || entry.tags.includes('invalidated') || entry.tags.includes('superseded'))
@@ -22,7 +31,10 @@ export function planHalfLifeMigration(entries, from, to) {
         return bonus === null ? [] : [{ ...e, half_life_days: deriveHalfLife(to, e) + bonus }];
     });
 }
-/** Memories of decisions, incidents and other objects still on the flat 90 days, as copies on `to` that keep their recall bonus. Pure. */
+/**
+ * Memories of decisions, incidents and other objects still on the flat 90 days, as copies on `to` that keep their
+ * recall bonus. Pure.
+ */
 export function planTypedHalfLifeMigration(entries, to) {
     return entries.flatMap((e) => {
         const bonus = TYPED_SOURCES.has(e.source) ? halfLifeRecallBonus(e, LEGACY_TYPED_HALF_LIFE) : null;
@@ -31,13 +43,16 @@ export function planTypedHalfLifeMigration(entries, to) {
     });
 }
 /** The base this store's memories are on. */
-export function storeHalfLifeBase(hippoRoot) {
-    return recordedHalfLifeBase(hippoRoot);
+export function storeHalfLifeBase(store) {
+    return store.halfLifeBase();
 }
-/** 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 = {}) {
+/**
+ * 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(store, to, opts = {}) {
     const dryRun = opts.dryRun ?? false;
-    const { from, outcome } = moveHalfLives(hippoRoot, to, { dryRun, actor: opts.actor ?? 'system' }, (rows) => {
+    const { from, outcome } = store.moveHalfLives(to, { dryRun, actor: opts.actor ?? 'system' }, (rows) => {
         const { basePlan, typedPlan } = planMoves(rows, to);
         const plan = [...basePlan, ...typedPlan];
         return {
@@ -51,7 +66,15 @@ export function migrateDefaultHalfLife(hippoRoot, to, opts = {}) {
         };
     });
     const moved = outcome ?? { rescaled: 0, typed: 0, kept: 0, halfLives: new Map() };
-    return { from, to, rescaled: moved.rescaled, typed: moved.typed, kept: moved.kept, dryRun, halfLives: moved.halfLives };
+    return {
+        from,
+        to,
+        rescaled: moved.rescaled,
+        typed: moved.typed,
+        kept: moved.kept,
+        dryRun,
+        halfLives: moved.halfLives,
+    };
 }
 /** The base move and the move of object memories, planned from one read of the store. Pure. */
 function planMoves(rows, to) {
@@ -59,13 +82,20 @@ function planMoves(rows, to) {
     const objects = objectMemoryIds(rows.objectRows);
     const losers = conflictLosers(rows.conflictAudits, rows.resolvedConflicts);
     const copies = new Set(all.flatMap((e) => (e.superseded_by ? [e.superseded_by] : [])));
-    // Provenance before shape: an object's memory came from its writer, a supersede copy from the base (it keeps the source). Shape decides the rest.
-    const objectWritten = (e) => objects.all.has(e.id) || (!copies.has(e.id) && TYPED_SOURCES.has(e.source) && halfLifeRecallBonus(e, LEGACY_TYPED_HALF_LIFE) !== null);
-    const typedPlan = typedPending ? planTypedHalfLifeMigration(all.filter((e) => objectWritten(e) && !objects.retired.has(e.id) && !losers.has(e.id)), to) : [];
+    // Provenance before shape: an object's memory came from its writer, a supersede copy from the base (it keeps the
+    // source). Shape decides the rest.
+    const objectWritten = (e) => objects.all.has(e.id) ||
+        (!copies.has(e.id) && TYPED_SOURCES.has(e.source) && halfLifeRecallBonus(e, LEGACY_TYPED_HALF_LIFE) !== null);
+    const typedPlan = typedPending
+        ? planTypedHalfLifeMigration(all.filter((e) => objectWritten(e) && !objects.retired.has(e.id) && !losers.has(e.id)), to)
+        : [];
     const basePlan = planHalfLifeMigration(typedPending ? all.filter((e) => !objectWritten(e)) : all, rows.from, to);
     return { basePlan, typedPlan };
 }
-/** Memories behind every object, and those behind a superseded or closed one. Retiring an object leaves its memory untouched, so only its table knows. */
+/**
+ * Memories behind every object, and those behind a superseded or closed one. Retiring an object leaves its memory
+ * untouched, so only its table knows.
+ */
 function objectMemoryIds(objectRows) {
     const all = new Set();
     const retired = new Set();

package/dist/consolidate/llm-passes.js

@@ -23,6 +23,7 @@ function sleepLlm(run, fetcher) {
     const llmOpts = { apiKey, model: config.extraction.model, fetcher };
     return { apiKey, llmError, llmOpts };
 }
+const dagStore = (run) => ({ hippoRoot: run.hippoRoot, consolidation: run.store });
 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));
@@ -42,7 +43,10 @@ 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). */
+/**
+ * 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');
@@ -66,7 +70,8 @@ async function extractionPass(run, llm, batch) {
         }
         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`);
+            report(`stopped after a failure that will not clear on retry; ${skipped} of ${batch.length} candidates skipped, and ` +
+                `the DAG passes with them`);
             break;
         }
     }
@@ -80,7 +85,7 @@ async function dagBuildPass(run, { apiKey, llmError, llmOpts }) {
         return;
     try {
         const { buildDag } = await import('./dag.js');
-        const dagResult = await buildDag(run.hippoRoot, extractedFacts, { ...llmOpts, onError: llmError('dag') });
+        const dagResult = await buildDag(dagStore(run), extractedFacts, { ...llmOpts, onError: llmError('dag') });
         run.result.dagCandidateClusters = dagResult.candidateClusters;
         run.result.dagSummariesCreated = dagResult.summariesCreated;
         if (dagResult.summariesCreated > 0) {
@@ -92,7 +97,8 @@ async function dagBuildPass(run, { apiKey, llmError, llmOpts }) {
         log.warn('consolidate dag threw', errorFields(err));
     }
 }
-// 1.8. DAG summary rebuild: drain the summary_dirty queue set by child-write hooks; same apiKey/dryRun gate as buildDag.
+// 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;
@@ -101,13 +107,20 @@ async function dagRebuildPass(run, { llmError, llmOpts }) {
         const rawCap = envDagRebuildCap();
         // Hard ceiling so a misconfigured env can't burn unbounded LLM cost.
         const cap = rawCap !== undefined ? Math.min(rawCap, 1000) : 20;
-        const rebuildResult = await rebuildDirtySummaries(run.hippoRoot, { ...llmOpts, onError: llmError('dag rebuild'), cap });
+        const rebuildResult = await rebuildDirtySummaries(run.store, {
+            ...llmOpts,
+            onError: llmError('dag rebuild'),
+            cap,
+        });
         result.summariesRebuilt = rebuildResult.rebuilt;
         result.summariesRebuildFailed = rebuildResult.failed;
         result.summariesZeroChildSkipped = rebuildResult.zeroChildSkipped;
         result.summariesRebuildRefused = rebuildResult.refused;
         result.summariesRebuildCapped = rebuildResult.capped;
-        if (rebuildResult.rebuilt > 0 || rebuildResult.zeroChildSkipped > 0 || rebuildResult.failed > 0 || rebuildResult.refused > 0) {
+        if (rebuildResult.rebuilt > 0 ||
+            rebuildResult.zeroChildSkipped > 0 ||
+            rebuildResult.failed > 0 ||
+            rebuildResult.refused > 0) {
             const parts = [];
             if (rebuildResult.rebuilt > 0)
                 parts.push(`${rebuildResult.rebuilt} rebuilt`);
@@ -127,15 +140,18 @@ async function dagRebuildPass(run, { llmError, llmOpts }) {
         log.warn('consolidate dag rebuild threw', errorFields(err));
     }
 }
-// 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.
+// 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).
+// Reads the stored L2s, 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');
-        const { loadAllL2Summaries } = await import('../store/summaries.js');
-        const l2Summaries = loadAllL2Summaries(run.hippoRoot);
+        const l2Summaries = run.store.unprofiledTopicSummaries();
         if (l2Summaries.length >= 2) {
-            const profileResult = await buildEntityProfiles(run.hippoRoot, l2Summaries, { ...llmOpts, onError: llmError('dag profiles') });
+            const profileResult = await buildEntityProfiles(dagStore(run), l2Summaries, {
+                ...llmOpts,
+                onError: llmError('dag profiles'),
+            });
             run.result.entityProfilesCreated = profileResult.profilesCreated;
             if (profileResult.profilesCreated > 0) {
                 run.result.details.push(`  🌲 DAG L3: ${profileResult.profilesCreated} entity profiles, ${profileResult.l2sLinked} L2s linked`);

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

@@ -1,5 +1,9 @@
-/** 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. */
+/**
+ * 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,5 +1,9 @@
-/** 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. */
+/**
+ * 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,5 +1,9 @@
-/** 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. */
+/**
+ * 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>;
@@ -13,14 +17,25 @@ export interface MvFeatureVector {
     outcome_ratio: number;
     content_length: number;
 }
-/** 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. */
+/**
+ * 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 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. */
+/**
+ * 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 basis both rescueSet and the consolidate audit-row metadata read. */
+/**
+ * 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;
@@ -31,7 +46,9 @@ export interface MvRankInfo {
     /** ceil(RESCUE_BUDGET * totalNonPinned) — the rescue cutoff; rank <= keepN rescues. */
     keepN: number;
 }
-/** Group non-pinned entries by tenantId, score and rank each group independently, and return rank context for every non-pinned entry;
+/**
+ * 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 {
@@ -39,7 +56,10 @@ export interface RescueSetOptions {
     readonly digest?: string;
     readonly precomputedRanks?: Map<string, MvRankInfo>;
 }
-/** 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. */
+/**
+ * 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

package/dist/consolidate/memory-value.js

@@ -1,5 +1,9 @@
-/** 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. */
+/**
+ * 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 { DEFAULT_TENANT_ID } from '../util/env.js';
 import { strengthAblation } from '../core/ablation.js';
 import { calculateStrength } from '../core/memory.js';
@@ -20,11 +24,17 @@ export const MV_FEATURE_NAMES = [
 /** The keep-budget operating point (the only point with measured
  *  evidence): a code constant tied to that evidence, not user-tunable. */
 const RESCUE_BUDGET = 0.3;
-/** Per-tenant floor on the non-pinned candidate set: below it ranks are noise, and keepN=ceil(0.3*N) would rescue a 1-entry tenant's entry every sleep forever.
+/**
+ * Per-tenant floor on the non-pinned candidate set: below it ranks are noise, and keepN=ceil(0.3*N) would rescue a
+ * 1-entry tenant's entry every sleep forever.
  * A code constant tied to that reasoning, not user-tunable (like RESCUE_BUDGET). */
 const MIN_RESCUE_GROUP = 10;
-/** 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. */
+/**
+ * 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 function computeMvFeatures(entry, now) {
     const ageDays = (now.getTime() - Date.parse(entry.created)) / DAY_MS;
     const pos = entry.outcome_positive ?? 0;
@@ -32,7 +42,8 @@ export function computeMvFeatures(entry, now) {
     return {
         age_days: ageDays,
         half_life_days: entry.half_life_days,
-        strength: calculateStrength(entry, now, { ablation: strengthAblation() }), // clock-basis, never the production decay basis — see doc comment above
+        // clock-basis, never the production decay basis — see doc comment above
+        strength: calculateStrength(entry, now, { ablation: strengthAblation() }),
         retrieval_count: entry.retrieval_count,
         outcome_positive: pos,
         outcome_negative: neg,
@@ -40,7 +51,9 @@ export function computeMvFeatures(entry, now) {
         content_length: entry.content.length,
     };
 }
-/** Throws on a malformed weight constant (wrong dims, non-finite weight, missing digest): flag-on with a broken constant must throw, never act as flag-off.
+/**
+ * Throws on a malformed weight constant (wrong dims, non-finite weight, missing digest): flag-on with a broken constant
+ * must throw, never act as flag-off.
  * Parameterized (default: the frozen singleton) so the throw paths are unit-testable. */
 function isFiniteWeightValue(value) {
     return typeof value === 'number' && Number.isFinite(value);
@@ -57,11 +70,16 @@ export function validateWeights(weights = MEMORY_VALUE_WEIGHTS, digest = SOURCE_
         }
     }
     if (!isNonEmptyDigestString(digest)) {
-        throw new Error('memory-value: weights constant is malformed — SOURCE_ARTIFACT_SHA256 digest missing (src/consolidate/memory-value-weights.ts)');
+        throw new Error('memory-value: weights constant is malformed — SOURCE_ARTIFACT_SHA256 digest missing ' +
+            '(src/consolidate/memory-value-weights.ts)');
     }
 }
-/** 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. */
+/**
+ * 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 function scoreEntries(entries, now, weights = MEMORY_VALUE_WEIGHTS) {
     const raw = new Map();
     for (const e of entries)
@@ -104,7 +122,9 @@ export function scoreEntries(entries, now, weights = MEMORY_VALUE_WEIGHTS) {
     }
     return scores;
 }
-/** Group non-pinned entries by tenantId, score and rank each group independently, and return rank context for every non-pinned entry;
+/**
+ * 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 function rankNonPinnedByTenant(entries, now, weights = MEMORY_VALUE_WEIGHTS, digest = SOURCE_ARTIFACT_SHA256) {
     validateWeights(weights, digest);
@@ -146,8 +166,11 @@ export function rankNonPinnedByTenant(entries, now, weights = MEMORY_VALUE_WEIGH
     }
     return result;
 }
-/** 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. */
+/**
+ * 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 function rescueSet(entries, condemnedIds, now, options = {}) {
     const { weights = MEMORY_VALUE_WEIGHTS, digest = SOURCE_ARTIFACT_SHA256, precomputedRanks } = options;
     validateWeights(weights, digest); // fail loud before any rescue computation

package/dist/consolidate/merge.d.ts

@@ -2,6 +2,9 @@ import { type SleepRun } from './run.js';
 export declare function retireHeldTexts(run: SleepRun): void;
 /** Returns how many clusters were skipped because their merged text matches a rejected value. */
 export declare function mergePass(run: SleepRun): number;
-/** Maps i to each j > i, ascending, whose text overlap with i reaches the merge threshold; every text needs at least one token. */
+/**
+ * Maps i to each j > i, ascending, whose text overlap with i reaches the merge threshold; every text needs at least one
+ * token.
+ */
 export declare function mergePartners(contents: readonly string[]): (i: number) => number[];
 //# sourceMappingURL=merge.d.ts.map