hippo-memory 1.71.0 → 1.72.0

package/dist/consolidate/memory-value.js

@@ -1,6 +1,7 @@
 /** 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';
 import { compareEntryIdentity } from '../core/compare.js';
 import { MEMORY_VALUE_WEIGHTS, SOURCE_ARTIFACT_SHA256 } from './memory-value-weights.js';
@@ -31,7 +32,7 @@ export function computeMvFeatures(entry, now) {
     return {
         age_days: ageDays,
         half_life_days: entry.half_life_days,
-        strength: calculateStrength(entry, now), // clock-basis, never decayOpts — see doc comment above
+        strength: calculateStrength(entry, now, { ablation: strengthAblation() }), // clock-basis, never the production decay basis — see doc comment above
         retrieval_count: entry.retrieval_count,
         outcome_positive: pos,
         outcome_negative: neg,

package/dist/consolidate/merge.js

@@ -3,10 +3,10 @@ import { tokenize } from '../util/tokenize.js';
 import { jaccardMinShared, overlapPartners } from './overlap-index.js';
 import { compareEntryIdentity } from '../core/compare.js';
 import { duplicateKey, mergedText } from '../util/same-text.js';
-import { successorAfterRetirement } from './merged-row.js';
+import { successorAfterRetirement } from '../core/merged-row.js';
 import { rejectionDigest } from '../store/rejection.js';
 import { reportAuditWriteFailure } from '../store/audit.js';
-import { derivationScope, derivationPartitionKey } from '../store/recall-scope.js';
+import { derivationScope, derivationPartitionKey } from '../core/recall-scope.js';
 import { jaccardSets } from './conflicts.js';
 import { keptAsWritten } from './run.js';
 import { isReusable } from '../core/memory-quality.js';

package/dist/consolidate/physics-pass.d.ts

@@ -1,3 +1,8 @@
+import { type PhysicsParticle } from '../core/physics.js';
+import type { MemoryEntry } from '../core/memory.js';
 import type { SleepRun } from './run.js';
-export declare function physicsPass(run: SleepRun): void;
+export declare function physicsPass(run: SleepRun, maxParticles?: number): void;
+/** Every stored particle in load order up to the cap; past it, the most recently recalled survivors (memory id breaks ties),
+ * then particles with no survivor. */
+export declare function particlesToSimulate(stored: PhysicsParticle[], entries: ReadonlyMap<string, MemoryEntry>, max?: number): PhysicsParticle[];
 //# sourceMappingURL=physics-pass.d.ts.map

package/dist/consolidate/physics-pass.js

@@ -3,8 +3,10 @@ import { loadStoredParticles, saveStoredParticles } from '../store/vector-index.
 import { simulate } from '../core/physics.js';
 import { errorMessage } from '../util/log.js';
 const STATS_DECIMALS = 4;
+// Every substep is all-pairs, so one sleep moves at most this many particles; the rest keep their stored state until they are recalled.
+const SLEEP_PHYSICS_MAX_PARTICLES = 1000;
 // 2. Physics simulation pass
-export function physicsPass(run) {
+export function physicsPass(run, maxParticles = SLEEP_PHYSICS_MAX_PARTICLES) {
     if (run.dryRun)
         return;
     const { config, result } = run;
@@ -12,27 +14,45 @@ export function physicsPass(run) {
         const physicsEnabled = config.physics.enabled === true
             || (config.physics.enabled === 'auto');
         if (physicsEnabled)
-            simulateStoredParticles(run);
+            simulateStoredParticles(run, maxParticles);
     }
     catch (error) {
         result.details.push(`  ⚠️ physics simulation skipped: ${errorMessage(error)}`);
     }
 }
-function simulateStoredParticles(run) {
+function simulateStoredParticles(run, maxParticles) {
     const { result, survivors } = run;
-    const particles = loadStoredParticles(run.hippoRoot);
-    if (particles.length === 0)
+    const stored = loadStoredParticles(run.hippoRoot);
+    if (stored.length === 0)
         return;
     // Build entry lookup for property refresh
     const entryMap = new Map(survivors.map(e => [e.id, e]));
+    const particles = particlesToSimulate(stored, entryMap, maxParticles);
     refreshParticleProperties(particles, entryMap, run.now);
     const stats = simulate(particles, survivorForces(run));
     saveStoredParticles(run.hippoRoot, particles);
     result.physicsSimulated = stats.particleCount;
-    result.details.push(`  ⚛️  physics: ${stats.particleCount} particles, ` +
+    const capped = particles.length < stored.length ? ` (the ${particles.length} most recently recalled of ${stored.length})` : '';
+    result.details.push(`  ⚛️  physics: ${stats.particleCount} particles${capped}, ` +
         `avg vel ${stats.avgVelocityMagnitude.toFixed(STATS_DECIMALS)}, ` +
         `energy ${stats.energy.total.toFixed(STATS_DECIMALS)}`);
 }
+/** Every stored particle in load order up to the cap; past it, the most recently recalled survivors (memory id breaks ties),
+ * then particles with no survivor. */
+export function particlesToSimulate(stored, entries, max = SLEEP_PHYSICS_MAX_PARTICLES) {
+    if (stored.length <= max)
+        return stored;
+    const recalled = (p) => entries.get(p.memoryId)?.last_retrieved ?? '';
+    const ranked = [...stored].sort((a, b) => {
+        const [ra, rb] = [recalled(a), recalled(b)];
+        if (ra !== rb)
+            return ra < rb ? 1 : -1;
+        return a.memoryId < b.memoryId ? -1 : a.memoryId > b.memoryId ? 1 : 0;
+    });
+    const kept = new Set(ranked.slice(0, max));
+    // Load order, not rank order: the force sums run in this order, so a capped run matches an uncapped one over the same set.
+    return stored.filter((p) => kept.has(p));
+}
 function survivorForces(run) {
     // Build conflict pairs from survivors
     const conflictPairs = new Map();

package/dist/consolidate/replay.js

@@ -1,5 +1,6 @@
 /** Replay: during `hippo sleep`, sample N survivors weighted by reward, valence, under-rehearsal and age, then apply the `markRetrieved` strengthening.
  * A lightweight deterministic analog of hippocampal replay, so important memories stay strong without being queried; distinct from decay, physics and merge. */
+import { HOUR_MS } from '../util/time.js';
 import { isOutcomeSlowAblated } from '../core/ablation.js';
 import { resolveConfidence } from '../core/memory.js';
 const VALENCE_WEIGHT = {
@@ -8,6 +9,12 @@ const VALENCE_WEIGHT = {
     negative: 1.5,
     critical: 2.0,
 };
+// Floor keeps every weight positive for sampleForReplay; the rest scale reward and idle boosts.
+const REWARD_FLOOR = 0.1;
+const REWARD_POSITIVE_GAIN = 0.5;
+const REWARD_NET_GAIN = 0.25;
+const IDLE_BOOST_GAIN = 0.1;
+const STRENGTH_FLOOR = 0.1;
 /** Priority score for ranking survivors for replay (higher = more likely sampled); pure in the entry and current time. */
 export function replayPriority(entry, now, outcomeAblated) {
     const pos = entry.outcome_positive ?? 0;
@@ -16,18 +23,18 @@ export function replayPriority(entry, now, outcomeAblated) {
     // The clamp is required because sampleForReplay needs all weights positive.
     const rewardSignal = outcomeAblated
         ? 1.0 // EVAL-ONLY ablation (see ablation.ts): outcome-off also silences replay's reward bias
-        : Math.max(0.1, 1 + pos * 0.5 + (pos - neg) * 0.25);
+        : Math.max(REWARD_FLOOR, 1 + pos * REWARD_POSITIVE_GAIN + (pos - neg) * REWARD_NET_GAIN);
     const valence = VALENCE_WEIGHT[entry.emotional_valence] ?? 1.0;
     // Under-rehearsed memories benefit most from replay.
     const underRehearsed = 1 / (1 + (entry.retrieval_count ?? 0));
     // Idle-time boost: memories that haven't been touched recently need rehearsal more.
     const lastRetrieved = new Date(entry.last_retrieved);
     const deltaMs = now.getTime() - lastRetrieved.getTime();
-    const ageHours = Number.isFinite(deltaMs) ? Math.max(0, deltaMs / 3_600_000) : 0;
-    const idleBoost = 1 + Math.log1p(ageHours) * 0.1;
+    const ageHours = Number.isFinite(deltaMs) ? Math.max(0, deltaMs / HOUR_MS) : 0;
+    const idleBoost = 1 + Math.log1p(ageHours) * IDLE_BOOST_GAIN;
     // Weight by current strength so dead-and-decaying memories don't waste replay slots.
     const rawStrength = Number.isFinite(entry.strength) ? entry.strength : 0;
-    const strengthFloor = Math.max(0.1, rawStrength);
+    const strengthFloor = Math.max(STRENGTH_FLOOR, rawStrength);
     return rewardSignal * valence * underRehearsed * idleBoost * strengthFloor;
 }
 /** Deterministic 32-bit RNG (Mulberry32): same seed, same sequence, so replay is reproducible without a random-number dependency. */

package/dist/consolidate/sleep.js

@@ -1,5 +1,5 @@
 /** Consolidation engine ("Sleep"): decay pass (drop entries below the strength threshold), merge pass (semantic summaries of overlapping episodics), stats. */
-import { evalNow } from '../core/ablation.js';
+import { evalNow, strengthAblation } from '../core/ablation.js';
 import { canAutoDelete } from '../core/memory.js';
 import { loadAllEntriesWithBase } from '../store/entry-reads.js';
 import { commitInChunks, memoriesBackingObjects } from '../store/delete-and-batch.js';
@@ -11,7 +11,7 @@ import { loadConfig } from '../core/config.js';
 import { recordAuditEventsRowByRow, reportAuditWriteFailure } from '../store/audit.js';
 import { lazyTombstoneChecks } from '../store/tombstone-checks.js';
 import { migrateDefaultHalfLife, LEGACY_TYPED_HALF_LIFE } from './half-life-migration.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { WRITE_BUDGET } from '../util/write-budget.js';
 import { decayPass } from './decay.js';
 import { familyUnits, groupFlush } from './flush-units.js';
@@ -68,6 +68,7 @@ function sessionDecayOptions(hippoRoot, config) {
         decayBasis: config.decayBasis,
         avgSessionIntervalDays: sessionCtx.avgSessionIntervalDays,
         sleepCount: sessionCtx.sleepCount,
+        ablation: strengthAblation(),
     };
 }
 /** Every pass between decay and the flush; the tombstone-check handle closes whichever of them throws. */
@@ -96,7 +97,8 @@ function migrateHalfLives(hippoRoot, dryRun, result) {
         result.details.push(`  ⏳ ${dryRun ? 'would move' : 'moved'} ${halfLife.rescaled} memories from the ${halfLife.from}-day to the ${halfLife.to}-day half-life`);
     }
     if (halfLife.typed > 0) {
-        result.details.push(`  ⏳ ${dryRun ? 'would move' : 'moved'} ${halfLife.typed} memories of decisions, incidents and other objects from the ${LEGACY_TYPED_HALF_LIFE}-day to the ${halfLife.to}-day half-life`);
+        result.details.push(`  ⏳ ${dryRun ? 'would move' : 'moved'} ${halfLife.typed} memories of decisions, incidents and other objects ` +
+            `from the ${LEGACY_TYPED_HALF_LIFE}-day to the ${halfLife.to}-day half-life`);
     }
     return halfLife;
 }
@@ -126,7 +128,8 @@ async function expireDormant(run, budget) {
     const cutoff = new Date(run.now.getTime() - config.dormant.retentionDays * DAY_MS).toISOString();
     result.dormantExpired = await expireDormantBefore(run.hippoRoot, cutoff, { dryRun, budget, busyWaitMs: SLEEP_DB_WAIT_MS });
     if (result.dormantExpired > 0) {
-        result.details.push(`  ⌛ ${dryRun ? 'would expire' : 'expired'} ${result.dormantExpired} dormant memor${result.dormantExpired === 1 ? 'y' : 'ies'} older than ${config.dormant.retentionDays} days`);
+        result.details.push(`  ⌛ ${dryRun ? 'would expire' : 'expired'} ${result.dormantExpired} dormant memor${result.dormantExpired === 1 ? 'y' : 'ies'} ` +
+            `older than ${config.dormant.retentionDays} days`);
     }
 }
 // 4. Log run
@@ -175,7 +178,7 @@ function auditRescues(run, { rescuedEntries, rankById }) {
     }
     catch (err) {
         // An audit store that will not open must never crash the mutation it records.
-        log.debug(`mv_rescue audit unavailable: ${errorMessage(err)}`);
+        log.warn(`mv_rescue audit unavailable: ${errorMessage(err)}`, { errorClass: errorFields(err).errorClass });
         result.details.push(`  ⚠️ memory-value: mv_rescue audit unavailable this cycle ` +
             `(${rescuedEntries.length} rescue${rescuedEntries.length === 1 ? '' : 's'} not audited)`);
     }

package/dist/consolidate/traces.js

@@ -1,4 +1,4 @@
-import { isRecallBoostAblated } from '../core/ablation.js';
+import { isRecallBoostAblated, strengthAblation } from '../core/ablation.js';
 import { Layer, createMemory, markRetrieved } from '../core/memory.js';
 import { findPromotableSessions, traceExistsForSession, listSessionEvents } from '../store/sessions.js';
 import { rejectionDigest } from '../store/rejection.js';
@@ -6,7 +6,7 @@ import { sampleForReplay } from './replay.js';
 import { renderTraceContent } from './trace.js';
 import { resolveTenantId } from '../store/tenant.js';
 import { reportAuditWriteFailure } from '../store/audit.js';
-import { commonDerivationScope } from '../store/recall-scope.js';
+import { commonDerivationScope } from '../core/recall-scope.js';
 import { log } from '../util/log.js';
 import { REPLAY_COUNT_DEFAULT } from './run.js';
 import { isJsonString } from '../util/json.js';
@@ -136,7 +136,7 @@ export function replayPass(run) {
     const picked = sampleForReplay(survivors, replayCount, now, seed);
     if (picked.length === 0)
         return;
-    const rehearsed = markRetrieved(picked, now);
+    const rehearsed = markRetrieved(picked, now, { ablation: strengthAblation() });
     const rehearsedById = new Map(rehearsed.map((e) => [e.id, e]));
     // Update survivors in place so downstream passes see rehearsed state.
     for (let i = 0; i < survivors.length; i++) {

package/dist/core/ablation.d.ts

@@ -1,6 +1,16 @@
 /** EVAL-ONLY ablation switches (HIPPO_ABLATE_*, HIPPO_EVAL_RECENCY_DAYS, HIPPO_FAKE_NOW): each cuts ONE mechanism (outcome also replayPriority bias).
  * Not a production surface. Env is read once per process; tests that mutate these vars MUST call _resetAblationCacheForTests() in beforeEach AND afterEach. See
  * docs/ARCHITECTURE.md#srccoreablationts. */
+/** The three switches strength scoring honours, resolved by the entry layer and handed to core in DecayOptions. */
+export interface StrengthAblation {
+    readonly decay: boolean;
+    readonly recallBoost: boolean;
+    readonly outcomeSlow: boolean;
+}
+/** Production scoring: nothing ablated. Core falls back to this, so it never reads the environment. */
+export declare const NO_STRENGTH_ABLATION: StrengthAblation;
+/** The frozen strength switches for this process; entry-layer callers pass them as `DecayOptions.ablation`. */
+export declare function strengthAblation(): StrengthAblation;
 export declare function isDecayAblated(): boolean;
 export declare function isRecallBoostAblated(): boolean;
 export declare function isOutcomeSlowAblated(): boolean;

package/dist/core/ablation.js

@@ -2,7 +2,10 @@
  * Not a production surface. Env is read once per process; tests that mutate these vars MUST call _resetAblationCacheForTests() in beforeEach AND afterEach. See
  * docs/ARCHITECTURE.md#srccoreablationts. */
 import { envAblateDecay, envAblateOutcome, envAblateOutcomeFast, envAblateOutcomeSlow, envAblateRecallBoost, envAblateRecency, envEvalRecencyDays, envFakeNowMs, } from '../util/env.js';
+/** Production scoring: nothing ablated. Core falls back to this, so it never reads the environment. */
+export const NO_STRENGTH_ABLATION = Object.freeze({ decay: false, recallBoost: false, outcomeSlow: false });
 let _cache;
+let _strengthCache;
 function readFlags() {
     if (_cache !== undefined)
         return _cache;
@@ -18,6 +21,14 @@ function readFlags() {
     };
     return _cache;
 }
+/** The frozen strength switches for this process; entry-layer callers pass them as `DecayOptions.ablation`. */
+export function strengthAblation() {
+    if (_strengthCache === undefined) {
+        const f = readFlags();
+        _strengthCache = Object.freeze({ decay: f.decay, recallBoost: f.recallBoost, outcomeSlow: f.outcomeSlow });
+    }
+    return _strengthCache;
+}
 export function isDecayAblated() {
     return readFlags().decay;
 }
@@ -45,5 +56,6 @@ export function evalNow() {
 /** Test-only. See module JSDoc: call in BOTH beforeEach AND afterEach. */
 export function _resetAblationCacheForTests() {
     _cache = undefined;
+    _strengthCache = undefined;
 }
 //# sourceMappingURL=ablation.js.map

package/dist/{sharing/scope.d.ts → core/active-scope.d.ts}

@@ -4,4 +4,4 @@ export declare function detectScope(): string | null;
 /** Compute scope match between a memory's scope tags and the active scope.
  *  Returns: 1 if matching scope, -1 if mismatching scope, 0 if neutral (no scope on either side). */
 export declare function scopeMatch(memoryTags: string[], activeScope: string | null): -1 | 0 | 1;
-//# sourceMappingURL=scope.d.ts.map
+//# sourceMappingURL=active-scope.d.ts.map

package/dist/{sharing/scope.js → core/active-scope.js}

@@ -26,4 +26,4 @@ export function scopeMatch(memoryTags, activeScope) {
         return 1; // match
     return -1; // mismatch
 }
-//# sourceMappingURL=scope.js.map
+//# sourceMappingURL=active-scope.js.map

package/dist/core/ambient.d.ts

@@ -13,6 +13,10 @@ export interface AmbientState {
     dagDepth: number;
     totalMemories: number;
 }
+/** A memory is fresh when created within this window. */
+export declare const AMBIENT_FRESH_WINDOW_MS: number;
+/** A memory counts as high schema fit strictly above this. */
+export declare const HIGH_SCHEMA_FIT_ABOVE = 0.7;
 /** Row counts and sums an AmbientState is derived from; two stores' tallies add with addAmbientTallies. */
 export interface AmbientTallies {
     total: number;

package/dist/core/ambient.js

@@ -1,9 +1,29 @@
 /** Ambient state vector: a compact O(N) summary of the corpus telling the agent "where it is" in knowledge-space without retrieving specific memories. */
-import { evalNow } from './ablation.js';
+import { evalNow, strengthAblation } from './ablation.js';
 import { Layer } from './memory.js';
 import { calculateStrength } from './memory.js';
 import { DAY_MS } from '../util/time.js';
 const STATE_DECIMALS = 3;
+// Cut points renderAmbientSummary uses to turn the state vector into words.
+const SUMMARY_THRESHOLD = {
+    freshHigh: 0.5,
+    freshLow: 0.1,
+    skewHigh: 0.3,
+    skewLow: -0.3,
+    consolidatedHigh: 0.4,
+    consolidatedLow: 0.1,
+    extractionHigh: 0.5,
+    conflictShown: 0.1,
+    dagDepthShown: 2,
+    strengthLow: 0.3,
+    strengthHigh: 0.7,
+    entropyHigh: 0.8,
+    entropyLow: 0.3,
+};
+/** A memory is fresh when created within this window. */
+export const AMBIENT_FRESH_WINDOW_MS = 7 * DAY_MS;
+/** A memory counts as high schema fit strictly above this. */
+export const HIGH_SCHEMA_FIT_ABOVE = 0.7;
 /** The tallies of two disjoint row sets taken together. */
 export function addAmbientTallies(a, b) {
     const tagCounts = new Map(a.tagCounts);
@@ -31,7 +51,7 @@ export function isErrorTagged(tags) {
 /** Tallies over loaded entries; superseded rows count toward the total only, as they always have here. */
 export function tallyAmbientEntries(entries, now) {
     const currentTime = now ?? evalNow(); // honors HIPPO_FAKE_NOW (eval-only)
-    const sevenDaysAgo = currentTime.getTime() - 7 * DAY_MS;
+    const freshAfter = currentTime.getTime() - AMBIENT_FRESH_WINDOW_MS;
     const t = {
         total: entries.length, strengthSum: 0, fresh: 0, negative: 0, highSchemaFit: 0, errors: 0,
         semantic: 0, episodic: 0, conflicts: 0, extracted: 0, maxDagLevel: 0, tagCounts: new Map(),
@@ -41,14 +61,14 @@ export function tallyAmbientEntries(entries, now) {
             continue;
         for (const tag of entry.tags)
             t.tagCounts.set(tag, (t.tagCounts.get(tag) ?? 0) + 1);
-        t.strengthSum += calculateStrength(entry, currentTime);
-        if (new Date(entry.created).getTime() > sevenDaysAgo)
+        t.strengthSum += calculateStrength(entry, currentTime, { ablation: strengthAblation() });
+        if (new Date(entry.created).getTime() > freshAfter)
             t.fresh++;
         if (entry.emotional_valence === 'negative' || entry.emotional_valence === 'critical')
             t.negative++;
         if (isErrorTagged(entry.tags))
             t.errors++;
-        if (entry.schema_fit > 0.7)
+        if (entry.schema_fit > HIGH_SCHEMA_FIT_ABOVE)
             t.highSchemaFit++;
         if (entry.layer === Layer.Semantic)
             t.semantic++;
@@ -116,33 +136,34 @@ function shannonEntropy(counts, total) {
 export function renderAmbientSummary(state) {
     if (state.totalMemories === 0)
         return 'Memory state: empty store, no memories yet.';
+    const T = SUMMARY_THRESHOLD;
     const parts = [];
     parts.push(`${state.totalMemories} memories`);
-    if (state.recencyFreshness > 0.5)
+    if (state.recencyFreshness > T.freshHigh)
         parts.push('mostly fresh (<7d)');
-    else if (state.recencyFreshness < 0.1)
+    else if (state.recencyFreshness < T.freshLow)
         parts.push('mostly aged');
-    if (state.emotionalSkew > 0.3)
+    if (state.emotionalSkew > T.skewHigh)
         parts.push('error-focused');
-    else if (state.emotionalSkew < -0.3)
+    else if (state.emotionalSkew < T.skewLow)
         parts.push('steady operation');
-    if (state.consolidationRatio > 0.4)
+    if (state.consolidationRatio > T.consolidatedHigh)
         parts.push('well-consolidated');
-    else if (state.consolidationRatio < 0.1)
+    else if (state.consolidationRatio < T.consolidatedLow)
         parts.push('mostly episodic');
-    if (state.extractionCoverage > 0.5)
+    if (state.extractionCoverage > T.extractionHigh)
         parts.push('high extraction coverage');
-    if (state.conflictIntensity > 0.1)
+    if (state.conflictIntensity > T.conflictShown)
         parts.push(`${(state.conflictIntensity * 100).toFixed(0)}% conflict rate`);
-    if (state.dagDepth >= 2)
+    if (state.dagDepth >= T.dagDepthShown)
         parts.push(`DAG depth ${state.dagDepth}`);
-    if (state.avgStrength < 0.3)
+    if (state.avgStrength < T.strengthLow)
         parts.push('low avg strength (aging corpus)');
-    else if (state.avgStrength > 0.7)
+    else if (state.avgStrength > T.strengthHigh)
         parts.push('high avg strength');
-    if (state.tagEntropy > 0.8)
+    if (state.tagEntropy > T.entropyHigh)
         parts.push('diverse topics');
-    else if (state.tagEntropy < 0.3)
+    else if (state.tagEntropy < T.entropyLow)
         parts.push('narrow focus');
     return `Memory state: ${parts.join(', ')}.`;
 }

package/dist/core/api-errors.d.ts

@@ -24,4 +24,20 @@ export declare class ConflictError extends ApiError {
     readonly status = 409;
     constructor(message: string);
 }
+/** Thrown by the write-path guard (checkRejectionGuard, via upsertEntryRow) when a write would introduce a tombstoned value; carries what the
+ * transaction-owner catch blocks (writeEntry, api.supersede) need to write the post-rollback `reject_refusal` audit row via `auditRejectionRefusal`. */
+export declare class RejectedValueError extends BadRequestError {
+    readonly digest: string;
+    readonly tenantId: string;
+    readonly entryId: string;
+    readonly reason: string | null;
+    readonly rejectedAt: string;
+    constructor(opts: {
+        digest: string;
+        tenantId: string;
+        entryId: string;
+        reason: string | null;
+        rejectedAt: string;
+    });
+}
 //# sourceMappingURL=api-errors.d.ts.map

package/dist/core/api-errors.js

@@ -1,4 +1,5 @@
 /** Errors whose HTTP status is part of the API contract; the server maps by class, so message text can change freely. */
+import { DIGEST_DISPLAY_CHARS } from '../util/token-text.js';
 /** Base class: an error the caller caused, carrying the status the HTTP layer answers with. */
 export class ApiError extends Error {
 }
@@ -34,4 +35,23 @@ export class ConflictError extends ApiError {
         this.name = 'ConflictError';
     }
 }
+/** Thrown by the write-path guard (checkRejectionGuard, via upsertEntryRow) when a write would introduce a tombstoned value; carries what the
+ * transaction-owner catch blocks (writeEntry, api.supersede) need to write the post-rollback `reject_refusal` audit row via `auditRejectionRefusal`. */
+export class RejectedValueError extends BadRequestError {
+    digest;
+    tenantId;
+    entryId;
+    reason;
+    rejectedAt;
+    constructor(opts) {
+        super(`Memory value refused: matches a rejected value (digest ${opts.digest.slice(0, DIGEST_DISPLAY_CHARS)}..., ` +
+            `reason: ${opts.reason ?? 'none given'}). Run "hippo unreject" to allow it again.`);
+        this.name = 'RejectedValueError';
+        this.digest = opts.digest;
+        this.tenantId = opts.tenantId;
+        this.entryId = opts.entryId;
+        this.reason = opts.reason;
+        this.rejectedAt = opts.rejectedAt;
+    }
+}
 //# sourceMappingURL=api-errors.js.map

package/dist/core/card.js

@@ -1,3 +1,5 @@
+// Work-queue card types: a claimable unit of work, N candidates claim one row, first wins.
+import { HOUR_MS } from '../util/time.js';
 const CARD_STATUSES = ['backlog', 'ready', 'running', 'blocked', 'review', 'done', 'shelved'];
 /** Narrows a raw string, such as a CLI flag value, to a CardStatus. */
 export function isCardStatus(v) {
@@ -15,7 +17,7 @@ export const CARD_TRANSITIONS = {
 };
 // SHORTCUT: one fixed lease for every claim; add a per-claim lease when the W3 dispatcher heartbeats on a timer.
 /** How long a claim or a heartbeat keeps a running card's lease before reclaimExpiredCards may return it to ready. */
-export const CARD_LEASE_MS = 4 * 60 * 60 * 1000;
+export const CARD_LEASE_MS = 4 * HOUR_MS;
 /** Throws on any move CARD_TRANSITIONS does not allow, before a status write touches the row. */
 export function assertCardTransition(from, to) {
     for (const status of from) {

package/dist/core/compaction-timing.d.ts

@@ -0,0 +1,7 @@
+/** PostCompact has 10 s in all (PreCompact 30 s), so a locked store must be given up on early. */
+export declare const COMPACTION_DB_WAIT_MS = 2000;
+/** Long enough that a live hook has finished with its own record. */
+export declare const REPLAY_AFTER_MS: number;
+/** Claude Code deletes transcripts after 30 days, so an older gap can never be filled. */
+export declare const TRANSCRIPT_FILL_WINDOW_MS: number;
+//# sourceMappingURL=compaction-timing.d.ts.map

package/dist/core/compaction-timing.js

@@ -0,0 +1,9 @@
+// Waits and windows shared by the compaction record's SQL (src/store) and the hooks and CLI that schedule it.
+import { DAY_MS, MINUTE_MS } from '../util/time.js';
+/** PostCompact has 10 s in all (PreCompact 30 s), so a locked store must be given up on early. */
+export const COMPACTION_DB_WAIT_MS = 2000;
+/** Long enough that a live hook has finished with its own record. */
+export const REPLAY_AFTER_MS = 10 * MINUTE_MS;
+/** Claude Code deletes transcripts after 30 days, so an older gap can never be filled. */
+export const TRANSCRIPT_FILL_WINDOW_MS = 30 * DAY_MS;
+//# sourceMappingURL=compaction-timing.js.map

package/dist/core/config.d.ts

@@ -20,7 +20,7 @@ export interface HippoConfig {
         model: string;
         hybridWeight: number;
         /** Embedding backend: 'local' (default) = zero-dependency transformers.js; 'openai' | 'voyage' | 'cohere' = opt-in API embedder needing the provider's
-         *  API key in env (OPENAI_API_KEY / VOYAGE_API_KEY / COHERE_API_KEY). See src/store/embeddings/provider.ts. */
+         *  API key in env (OPENAI_API_KEY / VOYAGE_API_KEY / COHERE_API_KEY). See src/embeddings/provider.ts. */
         provider?: 'local' | 'openai' | 'voyage' | 'cohere';
         /** Optional API base-URL override (self-host / proxy). HTTPS only (localhost
          *  may use http). Ignored by the local provider. */

package/dist/core/config.js

@@ -6,7 +6,7 @@ import * as path from 'path';
 import { DEFAULT_PHYSICS_CONFIG, mergePhysicsConfig } from './physics-config.js';
 import { DEFAULT_HALF_LIFE_DAYS } from './memory.js';
 import { DEFAULT_LOCAL_BUMP, DEFAULT_RECALL_BUDGET } from './search-types.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorCode, errorMessage, log } from '../util/log.js';
 import { isJsonObject } from '../util/json.js';
 export const DEFAULT_CONFIG = {
     defaultHalfLifeDays: DEFAULT_HALF_LIFE_DAYS,
@@ -243,7 +243,12 @@ function fileStamp(file) {
         return stat === undefined ? null : `${stat.mtimeMs}:${stat.size}`;
     }
     catch (err) {
-        log.debug(`config: ${file} could not be reached, read as missing: ${errorMessage(err)}`);
+        const code = errorCode(err);
+        const message = `config: ${file} could not be reached, read as missing: ${errorMessage(err)}`;
+        if (code === 'EACCES' || code === 'EPERM')
+            log.warnThenDebug(`config-unreachable:${file}:${code}`, message, { path: file, code });
+        else
+            log.debug(message);
         return null;
     }
 }

package/dist/core/cosine.d.ts

@@ -0,0 +1,3 @@
+/** Cosine over any indexable vectors (a Float32 view scores as its number[] copy); 0 for empty, mismatched or zero-norm input. */
+export declare function cosineOf(a: ArrayLike<number>, b: ArrayLike<number>): number;
+//# sourceMappingURL=cosine.d.ts.map

package/dist/core/cosine.js

@@ -0,0 +1,19 @@
+/** Cosine over any indexable vectors (a Float32 view scores as its number[] copy); 0 for empty, mismatched or zero-norm input. */
+export function cosineOf(a, b) {
+    if (a.length === 0 || b.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    if (denom < 1e-10)
+        return 0;
+    // Clamp to [-1, 1] to handle floating point drift
+    return Math.min(1, Math.max(-1, dot / denom));
+}
+//# sourceMappingURL=cosine.js.map

package/dist/{store → core}/markdown.d.ts

@@ -1,4 +1,4 @@
-import { type MemoryEntry } from '../core/memory.js';
+import { type MemoryEntry } from './memory.js';
 /** Serialize a MemoryEntry to markdown with YAML frontmatter. */
 export declare function serializeEntry(entry: MemoryEntry): string;
 /** Deserialize a markdown file to a MemoryEntry. */

package/dist/{store → core}/markdown.js

@@ -1,6 +1,6 @@
 import { DEFAULT_TENANT_ID } from '../util/env.js';
-import { FALLBACK_HALF_LIFE_DAYS, DEFAULT_SCHEMA_FIT } from '../core/memory.js';
-import { dumpFrontmatter, parseFrontmatter } from './yaml.js';
+import { FALLBACK_HALF_LIFE_DAYS, DEFAULT_SCHEMA_FIT } from './memory.js';
+import { dumpFrontmatter, parseFrontmatter } from '../util/yaml.js';
 /** The fields every mirror file carries; serializeEntry adds the optional ones. */
 function entryFrontmatter(entry) {
     return {

package/dist/core/memory-audit.d.ts

@@ -0,0 +1,17 @@
+import { type MemoryEntry } from './memory.js';
+export type AuditSeverity = 'warning' | 'error';
+export interface AuditIssue {
+    memoryId: string;
+    content: string;
+    severity: AuditSeverity;
+    reason: string;
+}
+export interface AuditResult {
+    total: number;
+    issues: AuditIssue[];
+    clean: number;
+}
+export declare function auditMemory(entry: MemoryEntry, backsObject?: boolean): AuditIssue | null;
+/** `backing`: ids of memories that back an object (store.memoriesBackingObjects). */
+export declare function auditMemories(entries: MemoryEntry[], backing: ReadonlySet<string>): AuditResult;
+//# sourceMappingURL=memory-audit.d.ts.map