hippo-memory 1.71.0 → 1.72.0

package/dist/core/memory-audit.js

@@ -0,0 +1,54 @@
+// The memory-quality audit rules: pure functions of a row, so any store can be audited by them.
+import { canAutoDelete } from './memory.js';
+import { automaticDefect, hasNoSpecificity, isFragment, isReleaseCommitNoise, substantiveWordCount, } from './memory-quality.js';
+export function auditMemory(entry, backsObject = false) {
+    const issue = classifyMemory(entry);
+    // Error means "auto-remove"; a pinned, raw, kept-for-good or object-backing row is never auto-removed, so it can only warn.
+    if (issue?.severity === 'error' && (!canAutoDelete(entry) || backsObject)) {
+        const why = entry.pinned ? 'pinned' : entry.kind === 'raw' ? 'raw' : backsObject ? 'backs an object' : 'keep rule';
+        return { ...issue, severity: 'warning', reason: `${issue.reason} (${why}, kept)` };
+    }
+    return issue;
+}
+function classifyMemory(entry) {
+    const content = entry.content.trim();
+    if (content.length < 3) {
+        return { memoryId: entry.id, content, severity: 'error', reason: 'too short (< 3 chars)' };
+    }
+    if (content.length < 10) {
+        return { memoryId: entry.id, content, severity: 'error', reason: 'too short (< 10 chars)' };
+    }
+    if (isReleaseCommitNoise(content)) {
+        return { memoryId: entry.id, content, severity: 'error', reason: 'release/commit noise, not a useful memory' };
+    }
+    if (isFragment(content)) {
+        return { memoryId: entry.id, content, severity: 'warning', reason: 'sentence fragment — lacks context' };
+    }
+    const substantive = substantiveWordCount(content);
+    if (substantive < 2) {
+        return { memoryId: entry.id, content, severity: 'warning', reason: `only ${substantive} substantive word(s) — too vague` };
+    }
+    if (content.length < 40 && hasNoSpecificity(content)) {
+        return { memoryId: entry.id, content, severity: 'warning', reason: 'no specific details (names, paths, numbers, code)' };
+    }
+    const reason = automaticDefect(entry);
+    if (reason !== null) {
+        return { memoryId: entry.id, content, severity: 'warning', reason: `automatic memory defect: ${reason}` };
+    }
+    return null;
+}
+/** `backing`: ids of memories that back an object (store.memoriesBackingObjects). */
+export function auditMemories(entries, backing) {
+    const issues = [];
+    for (const entry of entries) {
+        const issue = auditMemory(entry, backing.has(entry.id));
+        if (issue)
+            issues.push(issue);
+    }
+    return {
+        total: entries.length,
+        issues,
+        clean: entries.length - issues.length,
+    };
+}
+//# sourceMappingURL=memory-audit.js.map

package/dist/core/memory.d.ts

@@ -1,4 +1,5 @@
 /** Core data model for Hippo memory entries, based on the strength formula from PLAN.md. */
+import { type StrengthAblation } from './ablation.js';
 export declare const DEFAULT_SCHEMA_FIT = 0.5;
 export declare const FALLBACK_HALF_LIFE_DAYS = 7;
 export declare enum Layer {
@@ -10,7 +11,8 @@ export declare enum Layer {
 export type EmotionalValence = 'neutral' | 'positive' | 'negative' | 'critical';
 export type ConfidenceLevel = 'verified' | 'observed' | 'inferred' | 'stale';
 export type TraceOutcome = 'success' | 'failure' | 'partial' | null;
-export type MemoryKind = 'raw' | 'distilled' | 'superseded' | 'archived';
+export declare const MEMORY_KINDS: readonly ["raw", "distilled", "superseded", "archived"];
+export type MemoryKind = (typeof MEMORY_KINDS)[number];
 export interface MemoryEntry {
     id: string;
     created: string;
@@ -75,14 +77,14 @@ export declare function _resetLossAversionRatioCacheForTests(): void;
 /** Scales only the `negative` multiplier; `critical` stays unscaled so the knob moves just the losses-vs-gains claim. */
 export declare function applyLossAversionRatio(valence: EmotionalValence, baseMultiplier: number): number;
 /** 1 + REWARD_SLOPE * (pos - neg) / (pos + neg + 1), in (0.5, 1.5), 1.0 with no outcomes; it scales the effective half-life. */
-export declare function calculateRewardFactor(entry: Pick<MemoryEntry, 'outcome_positive' | 'outcome_negative'>): number;
+export declare function calculateRewardFactor(entry: Pick<MemoryEntry, 'outcome_positive' | 'outcome_negative'>, ablation?: StrengthAblation): number;
 /** Bad marks alone never push a memory under sleep's 0.05 retire line; supersede is the hard correction. */
 export declare const MAX_WRONG_HALVINGS = 3;
 export declare const DECAY_BASE = 0.5;
 export declare const REWARD_SLOPE = 0.5;
 export declare const RETRIEVAL_BOOST_SLOPE = 0.1;
 /** Bad outcome marks past good ones, floored at zero; each halves strength and stops recall strengthening, so a correction outranks pinning. */
-export declare function netWrong(entry: Pick<MemoryEntry, 'outcome_positive' | 'outcome_negative'>): number;
+export declare function netWrong(entry: Pick<MemoryEntry, 'outcome_positive' | 'outcome_negative'>, ablation?: StrengthAblation): number;
 /** What calculateStrength reads, so a caller can score a row without loading its text. */
 export type StrengthInputs = Pick<MemoryEntry, 'pinned' | 'created' | 'last_retrieved' | 'half_life_days' | 'retrieval_count' | 'emotional_valence' | 'outcome_positive' | 'outcome_negative'>;
 /** Decay basis: clock = wall time, session = per sleep cycle (intermittent agents), adaptive = half-life scaled by session frequency. */
@@ -92,6 +94,8 @@ export interface DecayOptions {
     avgSessionIntervalDays?: number;
     /** Total sleep cycles completed. Used by consolidation tracking. */
     sleepCount?: number;
+    /** EVAL-ONLY switches resolved once at the entry layer (`strengthAblation()`); absent means production scoring. */
+    ablation?: StrengthAblation;
 }
 /** Strength at `now` = decay * retrieval boost * emotional multiplier, clamped to [0, 1]; the basis modes are on DecayOptions.
  *  Pinned memories skip time decay, but being marked wrong still fades them (netWrong). */
@@ -167,6 +171,8 @@ export declare function createSuccessor(old: MemoryEntry, content: string, opts:
 /** How well new content fits existing knowledge, 0..1: above 0.7 consolidates faster, below 0.3 is novel and decays faster if unused.
  *  Tags shared with existing memories count by rarity (a rare shared tag fits more), plus content-token overlap. */
 export declare function computeSchemaFit(content: string, tags: string[], existingEntries: MemoryEntry[]): number;
+/** What schema fit reads from `entries`, built once for a caller that scores many contents against the same rows. */
+export declare function schemaFitSourceOf(entries: readonly MemoryEntry[]): SchemaFitSource;
 /** What schema fit reads from a set of memories, so a store can answer without loading its rows. */
 export interface SchemaFitSource {
     readonly rows: number;
@@ -179,5 +185,5 @@ export interface SchemaFitSource {
 export declare function schemaFitFrom(content: string, tags: readonly string[], source: SchemaFitSource): number;
 /** Returns copies with the retrieval count, clock and half-life updated; the caller persists them.
  *  Under HIPPO_ABLATE_RECALL_BOOST (eval-only) the entries come back unchanged, not empty, since callers derive last_retrieval_ids from them. */
-export declare function markRetrieved(entries: MemoryEntry[], now?: Date): MemoryEntry[];
+export declare function markRetrieved(entries: MemoryEntry[], now?: Date, options?: Pick<DecayOptions, 'ablation'>): MemoryEntry[];
 //# sourceMappingURL=memory.d.ts.map

package/dist/core/memory.js

@@ -2,7 +2,7 @@
 import { DEFAULT_TENANT_ID, envLossAversionRatio } from '../util/env.js';
 import { BadRequestError } from './api-errors.js';
 import { randomUUID } from 'crypto';
-import { isDecayAblated, isOutcomeSlowAblated, isRecallBoostAblated, evalNow, } from './ablation.js';
+import { evalNow, NO_STRENGTH_ABLATION } from './ablation.js';
 import { AGENT_MEMORY_TOOLS, toolSourcePrefix } from './agent-memory-tools.js';
 import { isJsonString } from '../util/json.js';
 import { DAY_MS } from '../util/time.js';
@@ -16,6 +16,7 @@ export var Layer;
     Layer["Semantic"] = "semantic";
     Layer["Trace"] = "trace";
 })(Layer || (Layer = {}));
+export const MEMORY_KINDS = ['raw', 'distilled', 'superseded', 'archived'];
 /** Tag on a memory whose named file/symbol/script changed after it was stored. */
 export const CHURN_STALE_TAG = 'churn-stale';
 // Losses weigh ~2x gains (Lovallo-Kahneman), so negative is 2.0; HIPPO_LOSS_AVERSION_RATIO scales it per process.
@@ -57,9 +58,9 @@ export function applyLossAversionRatio(valence, baseMultiplier) {
     return baseMultiplier * getLossAversionRatio();
 }
 /** 1 + REWARD_SLOPE * (pos - neg) / (pos + neg + 1), in (0.5, 1.5), 1.0 with no outcomes; it scales the effective half-life. */
-export function calculateRewardFactor(entry) {
+export function calculateRewardFactor(entry, ablation = NO_STRENGTH_ABLATION) {
     // EVAL-ONLY ablation (see ablation.ts): the slow outcome channel.
-    if (isOutcomeSlowAblated())
+    if (ablation.outcomeSlow)
         return 1.0;
     const pos = entry.outcome_positive ?? 0;
     const neg = entry.outcome_negative ?? 0;
@@ -75,8 +76,8 @@ export const DECAY_BASE = 0.5;
 export const REWARD_SLOPE = 0.5;
 export const RETRIEVAL_BOOST_SLOPE = 0.1;
 /** Bad outcome marks past good ones, floored at zero; each halves strength and stops recall strengthening, so a correction outranks pinning. */
-export function netWrong(entry) {
-    if (isOutcomeSlowAblated() || isDecayAblated())
+export function netWrong(entry, ablation = NO_STRENGTH_ABLATION) {
+    if (ablation.outcomeSlow || ablation.decay)
         return 0;
     return Math.max(0, (entry.outcome_negative ?? 0) - (entry.outcome_positive ?? 0));
 }
@@ -85,22 +86,23 @@ export function netWrong(entry) {
 export function calculateStrength(entry, 
 // evalNow() is the real clock unless HIPPO_FAKE_NOW is set (eval-only); an explicit `now` wins.
 now = evalNow(), options = {}) {
+    const ablation = options.ablation ?? NO_STRENGTH_ABLATION;
     // Being marked wrong outranks every shield: pinning, error tags, heavy recall.
-    const wrongPenalty = Math.pow(DECAY_BASE, Math.min(netWrong(entry), MAX_WRONG_HALVINGS));
+    const wrongPenalty = Math.pow(DECAY_BASE, Math.min(netWrong(entry, ablation), MAX_WRONG_HALVINGS));
     if (entry.pinned)
         return wrongPenalty;
     // EVAL-ONLY ablation (see ablation.ts): anchor decay at creation so clock resets from earlier unflagged runs cannot leak in.
-    const lastRetrieved = new Date(isRecallBoostAblated() ? entry.created : entry.last_retrieved);
+    const lastRetrieved = new Date(ablation.recallBoost ? entry.created : entry.last_retrieved);
     const daysSince = (now.getTime() - lastRetrieved.getTime()) / DAY_MS;
-    const rewardFactor = calculateRewardFactor(entry);
+    const rewardFactor = calculateRewardFactor(entry, ablation);
     const effectiveHalfLife = entry.half_life_days * rewardFactor;
     // Guard: zero half-life causes 0/0 = NaN in the exponent
     if (effectiveHalfLife <= 0)
         return 0.0;
     const decayExponent = decayExponentFor(options, daysSince, effectiveHalfLife);
     // EVAL-ONLY ablation (see ablation.ts): decay := 1, so the [0,1] clamp below caps the boost at baseline.
-    const decay = isDecayAblated() ? 1.0 : Math.pow(DECAY_BASE, decayExponent);
-    const retrievalBoost = retrievalBoostFor(entry);
+    const decay = ablation.decay ? 1.0 : Math.pow(DECAY_BASE, decayExponent);
+    const retrievalBoost = retrievalBoostFor(entry, ablation);
     const baseMultiplier = EMOTIONAL_MULTIPLIERS[entry.emotional_valence] ?? 1.0;
     const emotionalMultiplier = applyLossAversionRatio(entry.emotional_valence, baseMultiplier);
     const raw = decay * retrievalBoost * emotionalMultiplier;
@@ -127,8 +129,8 @@ function decayExponentFor(options, daysSince, halfLifeDays) {
     return daysSince / effectiveHalfLife;
 }
 // EVAL-ONLY ablation (see ablation.ts) neutralizes the read side too, so counts written before the flag cannot leak in.
-function retrievalBoostFor(entry) {
-    return isRecallBoostAblated() || netWrong(entry) > 0
+function retrievalBoostFor(entry, ablation) {
+    return ablation.recallBoost || netWrong(entry, ablation) > 0
         ? 1.0
         : 1 + RETRIEVAL_BOOST_SLOPE * Math.log2(entry.retrieval_count + 1);
 }
@@ -296,13 +298,17 @@ export function createSuccessor(old, content, opts) {
 /** How well new content fits existing knowledge, 0..1: above 0.7 consolidates faster, below 0.3 is novel and decays faster if unused.
  *  Tags shared with existing memories count by rarity (a rare shared tag fits more), plus content-token overlap. */
 export function computeSchemaFit(content, tags, existingEntries) {
+    return schemaFitFrom(content, tags, schemaFitSourceOf(existingEntries));
+}
+/** What schema fit reads from `entries`, built once for a caller that scores many contents against the same rows. */
+export function schemaFitSourceOf(entries) {
     const tagCounts = new Map();
-    for (const entry of existingEntries) {
+    for (const entry of entries) {
         for (const tag of entry.tags) {
             tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
         }
     }
-    return schemaFitFrom(content, tags, { rows: existingEntries.length, tagCounts, contents: existingEntries.map((e) => e.content) });
+    return { rows: entries.length, tagCounts, contents: entries.map((e) => e.content) };
 }
 function significantTokens(text) {
     return new Set(text.toLowerCase().replace(/[^\w\s]/g, ' ').split(/\s+/).filter((t) => t.length > 3));
@@ -358,13 +364,14 @@ function inferValence(tags) {
 }
 /** Returns copies with the retrieval count, clock and half-life updated; the caller persists them.
  *  Under HIPPO_ABLATE_RECALL_BOOST (eval-only) the entries come back unchanged, not empty, since callers derive last_retrieval_ids from them. */
-export function markRetrieved(entries, now = evalNow()) {
-    if (isRecallBoostAblated())
+export function markRetrieved(entries, now = evalNow(), options = {}) {
+    const ablation = options.ablation ?? NO_STRENGTH_ABLATION;
+    if (ablation.recallBoost)
         return entries;
     return entries.map((e) => {
         if (e.superseded_by)
             return e;
-        const wrong = netWrong(e) > 0;
+        const wrong = netWrong(e, ablation) > 0;
         // Confidence stays untouched: it is an epistemic tier, not a recency signal.
         const updated = {
             ...e,
@@ -373,7 +380,7 @@ export function markRetrieved(entries, now = evalNow()) {
             last_retrieved: wrong ? e.last_retrieved : now.toISOString(),
             half_life_days: wrong ? e.half_life_days : e.half_life_days + RETRIEVAL_HALF_LIFE_GAIN_DAYS,
         };
-        updated.strength = calculateStrength(updated, now);
+        updated.strength = calculateStrength(updated, now, { ablation });
         return updated;
     });
 }

package/dist/{consolidate → core}/merged-row.d.ts

@@ -1,4 +1,4 @@
-import { type MemoryEntry } from '../core/memory.js';
+import { type MemoryEntry } from './memory.js';
 /** The row that replaces a merged row once its retired texts leave: undefined when it holds none, null when nothing else is left. */
 export declare function mergedSuccessor(row: MemoryEntry, retired: (text: string) => boolean, retiredIds: ReadonlySet<string>): MemoryEntry | null | undefined;
 /** Sleep's check on a merged row: drops texts whose source was superseded since the merge, or that a rejection now covers. */

package/dist/{consolidate → core}/merged-row.js

@@ -1,7 +1,7 @@
 // A sleep-merged row copies its sources' texts, so retiring a text (reject, or superseding its source) must reach the row too.
 // SHORTCUT: reject rewrites merged rows at once, live and dormant; supersede and `resolve
 // --reject-loser` wait for the next sleep's check, which sees a dormant row only once restored.
-import { generateId } from '../core/memory.js';
+import { generateId } from './memory.js';
 import { duplicateKey, heldTexts, mergedText } from '../util/same-text.js';
 /** The row that replaces a merged row once its retired texts leave: undefined when it holds none, null when nothing else is left. */
 export function mergedSuccessor(row, retired, retiredIds) {

package/dist/core/physics.js

@@ -1,6 +1,7 @@
 /** Memory-as-Physics engine: pure math (forces, Velocity Verlet integration, physics-based scoring, cluster amplification), no I/O.
  * Memories are particles on the unit hypersphere in embedding space (384-dim); query gravity, attraction, conflict repulsion and drag act on them,
  * and nearby high-scoring memories amplify each other. */
+import { cosineOf } from './cosine.js';
 import { isRecallBoostAblated } from './ablation.js';
 import { FALLBACK_HALF_LIFE_DAYS } from './memory.js';
 import { comparePhysicsResultsBy } from './compare.js';
@@ -48,17 +49,6 @@ export function vecClampMagnitude(v, maxMag) {
         return v;
     return vecScale(v, maxMag / mag);
 }
-/** Cosine similarity between two vectors. */
-function cosine(a, b) {
-    if (a.length === 0 || b.length === 0 || a.length !== b.length)
-        return 0;
-    const dot = vecDot(a, b);
-    const na = vecNorm(a);
-    const nb = vecNorm(b);
-    if (na < 1e-10 || nb < 1e-10)
-        return 0;
-    return Math.min(1, Math.max(-1, dot / (na * nb)));
-}
 const CHARGE_MAP = {
     neutral: 0,
     positive: 0.3,
@@ -79,7 +69,7 @@ export function computeTemperature(ageDays, temperatureDecay) {
 }
 /** Query gravity (retrieval-time, virtual: does not move the particle): scalar ranking magnitude F = G_Q * mass * max(0, cosine(pos, query))^2. */
 export function queryGravityMagnitude(particle, queryEmbedding, G_query) {
-    const cos = cosine(particle.position, queryEmbedding);
+    const cos = cosineOf(particle.position, queryEmbedding);
     return G_query * particle.mass * Math.pow(Math.max(0, cos), 2);
 }
 /** Momentum bonus in [0, 1]: how aligned the particle's velocity is with the query direction. */
@@ -96,7 +86,7 @@ export function velocityAlignmentBonus(particle, queryEmbedding) {
 /** Attraction force on particle i from j (consolidation-time): G_M m_i m_j max(0, cosine)^3, directed along (pos_j - pos_i) projected tangent to the unit
  * sphere at pos_i (positions are re-normalized to the sphere after integration). Adds into `out` (a fresh zero vector by default) using `diff` as scratch. */
 export function attractionForce(pi, pj, G_memory, out = vecZero(pi.position.length), diff = vecZero(pi.position.length)) {
-    const cos = cosine(pi.position, pj.position);
+    const cos = cosineOf(pi.position, pj.position);
     if (cos <= 0)
         return out;
     const magnitude = G_memory * pi.mass * pj.mass * Math.pow(cos, 3);
@@ -113,7 +103,7 @@ export function attractionForce(pi, pj, G_memory, out = vecZero(pi.position.leng
 }
 /** Conflict repulsion on i away from j (consolidation-time): K_R * m_i * m_j / max(0.01, cosine_distance)^2, where cosine_distance = 1 - cosine_similarity. */
 export function repulsionForce(pi, pj, K_repulsion) {
-    const cos = cosine(pi.position, pj.position);
+    const cos = cosineOf(pi.position, pj.position);
     const dist = Math.max(0.01, 1 - cos);
     const magnitude = K_repulsion * pi.mass * pj.mass / (dist * dist);
     // Direction: away from j
@@ -237,7 +227,7 @@ export function computeSystemEnergy(particles, G_memory) {
     }
     for (let i = 0; i < particles.length; i++) {
         for (let j = i + 1; j < particles.length; j++) {
-            const cos = cosine(particles[i].position, particles[j].position);
+            const cos = cosineOf(particles[i].position, particles[j].position);
             potential -= G_memory * particles[i].mass * particles[j].mass * Math.max(0, cos);
         }
     }
@@ -292,7 +282,7 @@ function applyClusterAmplification(results, particles, config) {
             const pj = particleMap.get(top[j].memoryId);
             if (!pj)
                 continue;
-            const proximity = cosine(pi.position, pj.position);
+            const proximity = cosineOf(pi.position, pj.position);
             if (proximity > config.cluster_threshold) {
                 clusterSignal += top[j].baseScore * proximity;
             }

package/dist/core/prediction.d.ts

@@ -0,0 +1,3 @@
+export type ClosureState = 'open' | 'closed' | 'closed-unknown';
+export declare const VALID_CLOSURE_STATES: ReadonlySet<ClosureState>;
+//# sourceMappingURL=prediction.d.ts.map

package/dist/core/prediction.js

@@ -0,0 +1,6 @@
+export const VALID_CLOSURE_STATES = new Set([
+    'open',
+    'closed',
+    'closed-unknown',
+]);
+//# sourceMappingURL=prediction.js.map

package/dist/core/project-identity.d.ts

@@ -27,6 +27,9 @@ export declare function resolveProjectIdentity(cwd?: string, opts?: ResolveProje
 /** Nearest ancestor `.hippo` below home and the temp root (never projects; on Windows the temp root sits inside home).
  *  Everything is realpath'd so a symlinked temp root or cwd still matches its bound. */
 export declare function findHippoStoreDir(cwd?: string, opts?: ResolveProjectIdentityOpts): string | null;
+/** Nearest ancestor store like git; the strict join is the fallback so `hippo init` still creates `<cwd>/.hippo`. */
+export declare function getHippoRoot(cwd?: string, opts?: ResolveProjectIdentityOpts): string;
+export declare function isInitialized(hippoRoot: string): boolean;
 /** A reader's project: a bare name, or an identity whose own rows may also carry its legacy folder name. */
 export type ProjectRef = string | Pick<ProjectIdentity, 'name' | 'legacyName' | 'aliases'>;
 /** The id a reader's new rows are stamped with; '' outside a project. */

package/dist/core/project-identity.js

@@ -4,7 +4,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { BadRequestError } from './api-errors.js';
 import { isSharedStore, loadConfig } from './config.js';
-import { MAX_ID_LEN } from '../util/http-util.js';
+import { MAX_ID_LEN } from '../util/limits.js';
 import { errorMessage, log } from '../util/log.js';
 import { originRemoteId, projectFileId } from './project-remote.js';
 import { realpathOrResolve } from '../util/real-path.js';
@@ -154,6 +154,15 @@ export function findHippoStoreDir(cwd, opts) {
     const { hippoRoot } = walkProjectMarkers(start, home, stops);
     return hippoRoot === null ? null : path.join(hippoRoot, '.hippo');
 }
+/** Nearest ancestor store like git; the strict join is the fallback so `hippo init` still creates `<cwd>/.hippo`. */
+export function getHippoRoot(cwd = process.cwd(), opts) {
+    return findHippoStoreDir(cwd, opts) ?? path.join(realpathOrResolve(cwd), '.hippo');
+}
+export function isInitialized(hippoRoot) {
+    // autoInstallHooks / setupDailySchedule can create a bare .hippo with no hippo.db; counting
+    // that as initialized makes `hippo init` skip initStore, so only hippo.db counts.
+    return fs.existsSync(path.join(hippoRoot, 'hippo.db'));
+}
 function isBareName(project) {
     return typeof project === 'string';
 }

package/dist/{store → core}/recall-scope.d.ts

@@ -1,6 +1,6 @@
 /** Recall-side scope predicates, in a leaf module so search-both.ts can apply the same default-deny rule to searchBothHybrid's candidate loads without an
  * import cycle. src/api/index.ts imports these and re-exports them for back-compat (`api.isPrivateScope`, tests importing `passesScopeFilterForRecall`). */
-import { ForbiddenError } from '../core/api-errors.js';
+import { ForbiddenError } from './api-errors.js';
 /** Literal scopes excluded from recall by default-deny when the caller passes no `scope`; read by the SQL clause in `loadSearchRows` and by
  * `passesScopeFilterForRecall`. Invariant: never empty, or quarantine scopes would pass both paths silently (the module-load assertion below pins this). */
 export declare const RECALL_DEFAULT_DENY_SCOPES: readonly ["unknown:legacy"];
@@ -31,15 +31,6 @@ export declare function ownScopeTouches(ownScope: string | null, scope: string |
 /** JS half of the recall default-deny rule (SQL half: `loadSearchRows`). A non-empty `requested` needs an exact match;
  * otherwise `<source>:private:*` and `RECALL_DEFAULT_DENY_SCOPES` buckets are denied, while null, public scopes and the caller's `ownScope` pass. */
 export declare function passesScopeFilterForRecall(scope: string | null, requested: string | undefined, ownScope?: string | null): boolean;
-export interface SqlFragment {
-    sql: string;
-    params: string[];
-}
-/** SQL twin of the no-request arm of passesScopeFilterForRecall; `ownScope` is bound and compared with `=`, so `%` or `_` in an owner match nothing extra. */
-export declare function scopeAdmitSql(col: '' | 'm.', ownScope?: string | null): SqlFragment;
-/** SQL twin of canTouchScope, which is also canReadScope for an admin: every row but
- * another person's personal one. LIKE folds ASCII case as isPersonalScope's /i does. */
-export declare function touchableScopeSql(col: '' | 'm.', ownScope?: string | null): SqlFragment;
 /** CLI `--scope` variant: an explicit `--scope X` UNLOCKS scope X on top of the default-admitted set rather than narrowing to X (api.recall keeps 'exact').
  * Includes private/quarantine scopes (owner access); a named personal scope never unlocks: the CLI has no caller identity. */
 export declare function passesCliRecallScopeFilter(scope: string | null, requested: string | undefined): boolean;

package/dist/{store → core}/recall-scope.js

@@ -1,7 +1,7 @@
 /** Recall-side scope predicates, in a leaf module so search-both.ts can apply the same default-deny rule to searchBothHybrid's candidate loads without an
  * import cycle. src/api/index.ts imports these and re-exports them for back-compat (`api.isPrivateScope`, tests importing `passesScopeFilterForRecall`). */
-import { BadRequestError, ForbiddenError } from '../core/api-errors.js';
-import { MAX_ID_LEN } from '../util/http-util.js';
+import { BadRequestError, ForbiddenError } from './api-errors.js';
+import { MAX_ID_LEN } from '../util/limits.js';
 /** Literal scopes excluded from recall by default-deny when the caller passes no `scope`; read by the SQL clause in `loadSearchRows` and by
  * `passesScopeFilterForRecall`. Invariant: never empty, or quarantine scopes would pass both paths silently (the module-load assertion below pins this). */
 export const RECALL_DEFAULT_DENY_SCOPES = ['unknown:legacy'];
@@ -63,23 +63,6 @@ export function passesScopeFilterForRecall(scope, requested, ownScope) {
     }
     return !isRestrictedScope(scope) || (ownScope != null && scope === ownScope);
 }
-/** SQL twin of the no-request arm of passesScopeFilterForRecall; `ownScope` is bound and compared with `=`, so `%` or `_` in an owner match nothing extra. */
-export function scopeAdmitSql(col, ownScope) {
-    const placeholders = RECALL_DEFAULT_DENY_SCOPES.map(() => '?').join(', ');
-    const admitted = `${col}scope IS NULL OR (${col}scope NOT IN (${placeholders}) AND ${col}scope NOT LIKE '%:private:%')`;
-    if (ownScope == null)
-        return { sql: `(${admitted})`, params: [...RECALL_DEFAULT_DENY_SCOPES] };
-    // The own arm sits inside the outer parentheses so a caller's `AND ${sql}` cannot split it off.
-    return { sql: `(${admitted} OR ${col}scope = ?)`, params: [...RECALL_DEFAULT_DENY_SCOPES, ownScope] };
-}
-/** SQL twin of canTouchScope, which is also canReadScope for an admin: every row but
- * another person's personal one. LIKE folds ASCII case as isPersonalScope's /i does. */
-export function touchableScopeSql(col, ownScope) {
-    const notPersonal = `${col}scope IS NULL OR ${col}scope NOT LIKE '${PERSONAL_SCOPE_PREFIX}%'`;
-    if (ownScope == null)
-        return { sql: `(${notPersonal})`, params: [] };
-    return { sql: `(${notPersonal} OR ${col}scope = ?)`, params: [ownScope] };
-}
 /** CLI `--scope` variant: an explicit `--scope X` UNLOCKS scope X on top of the default-admitted set rather than narrowing to X (api.recall keeps 'exact').
  * Includes private/quarantine scopes (owner access); a named personal scope never unlocks: the CLI has no caller identity. */
 export function passesCliRecallScopeFilter(scope, requested) {

package/dist/db/busy.d.ts

@@ -1,12 +1,7 @@
 import type { DatabaseSyncLike } from './sqlite.js';
 export declare function isSqliteBusy(cause: unknown): boolean;
-export declare const STORE_BUSY_MESSAGE = "store busy (another hippo process holds the write lock); retry shortly";
-/** A store behind the port throws this when its lock wait runs out, so the server answers 503 as it does for a busy hippo.db. */
-export declare class StoreBusyError extends Error {
-    constructor(message?: string, options?: ErrorOptions);
-}
-/** A held lock in any store: SQLite's busy codes or a port's StoreBusyError. */
-export declare function isStoreBusy<E>(error: E): boolean;
+/** The lock wait of an open that names none: its busy_timeout and every explicit wait below. */
+export declare const DEFAULT_BUSY_WAIT_MS = 5000;
 export declare function execWithBusyRetry(db: DatabaseSyncLike, sql: string, timeoutMs?: number): void;
 /** Waits for the lock past busy_timeout when given; ignored inside a caller's transaction, which already holds it. */
 export interface WriteScopeOptions {

package/dist/db/busy.js

@@ -1,3 +1,4 @@
+import { errorFields, errorMessage, log } from '../util/log.js';
 function carriesErrcode(cause) {
     return typeof cause === 'object' && cause !== null && 'errcode' in cause;
 }
@@ -5,21 +6,11 @@ export function isSqliteBusy(cause) {
     const code = carriesErrcode(cause) ? cause.errcode : undefined;
     return code === 5 || code === 6 || code === 517;
 }
-export const STORE_BUSY_MESSAGE = 'store busy (another hippo process holds the write lock); retry shortly';
-/** A store behind the port throws this when its lock wait runs out, so the server answers 503 as it does for a busy hippo.db. */
-export class StoreBusyError extends Error {
-    constructor(message = STORE_BUSY_MESSAGE, options) {
-        super(message, options);
-        this.name = 'StoreBusyError';
-    }
-}
-/** A held lock in any store: SQLite's busy codes or a port's StoreBusyError. */
-export function isStoreBusy(error) {
-    return error instanceof StoreBusyError || isSqliteBusy(error);
-}
+/** The lock wait of an open that names none: its busy_timeout and every explicit wait below. */
+export const DEFAULT_BUSY_WAIT_MS = 5000;
 // busy_timeout covers neither contended statement here: SQLite skips the busy handler for `PRAGMA journal_mode` and for a write
 // that upgrades a deferred read snapshot, so both need an explicit wait.
-export function execWithBusyRetry(db, sql, timeoutMs = 30000) {
+export function execWithBusyRetry(db, sql, timeoutMs = DEFAULT_BUSY_WAIT_MS) {
     const deadline = Date.now() + timeoutMs;
     const idle = new Int32Array(new SharedArrayBuffer(4));
     for (;;) {
@@ -43,6 +34,17 @@ function undoScope(db, top, name) {
         db.exec(`RELEASE SAVEPOINT ${name}`);
     }
 }
+/** Undo after a failure without letting a failed undo replace the caller's error; an idle handle means SQLite already unwound the scope. */
+function undoAfterFailure(db, top, name) {
+    if (db.isTransaction === false)
+        return;
+    try {
+        undoScope(db, top, name);
+    }
+    catch (undoError) {
+        log.error(`rollback of write scope ${name} failed: ${errorMessage(undoError)}`, errorFields(undoError));
+    }
+}
 /** Runs `fn` as one write: BEGIN IMMEDIATE on an idle handle, else SAVEPOINT `name` inside the caller's transaction.
  *  A deferred scope that reads first cannot wait out another writer, while BEGIN IMMEDIATE waits the open's busy_timeout. */
 export function withWriteScope(db, name, fn, opts) {
@@ -57,10 +59,7 @@ export function withWriteScope(db, name, fn, opts) {
         return result;
     }
     catch (error) {
-        try {
-            undoScope(db, top, name);
-        }
-        catch { /* already rolled back; keep the original error */ }
+        undoAfterFailure(db, top, name);
         throw error;
     }
 }
@@ -77,7 +76,9 @@ export function withReadSnapshot(db, fn) {
         try {
             db.exec('COMMIT');
         }
-        catch { /* snapshot already gone; keep the original error */ }
+        catch (endError) {
+            log.error(`ending read snapshot failed: ${errorMessage(endError)}`, errorFields(endError));
+        }
         throw error;
     }
     db.exec('COMMIT');
@@ -92,10 +93,7 @@ export function withTrialScope(db, name, fn) {
         result = fn();
     }
     catch (error) {
-        try {
-            undoScope(db, top, name);
-        }
-        catch { /* already rolled back; keep the original error */ }
+        undoAfterFailure(db, top, name);
         throw error;
     }
     undoScope(db, top, name);
@@ -123,10 +121,7 @@ export function withWriteScopeOr(db, name, fn) {
         return result;
     }
     catch (error) {
-        try {
-            undoScope(db, top, name);
-        }
-        catch { /* already rolled back; keep the original error */ }
+        undoAfterFailure(db, top, name);
         throw error;
     }
 }

package/dist/db/connect.d.ts

@@ -1,6 +1,5 @@
 import { type DatabaseSyncLike } from './sqlite.js';
 import { type OpenFacts } from './migrate.js';
-export declare const DEFAULT_BUSY_WAIT_MS = 5000;
 export declare function getHippoDbPath(hippoRoot: string): string;
 /** Runs `step` on this store unless it already ran to the end in this process; a throw leaves it due. */
 export declare function oncePerStore(hippoRoot: string, name: string, step: () => void): void;

package/dist/db/connect.js

@@ -3,10 +3,9 @@ import * as path from 'path';
 import { cleanupArchivedMirrors } from './raw-archive-mirror-cleanup.js';
 import { errorFields, errorMessage, log } from '../util/log.js';
 import { DatabaseSync } from './sqlite.js';
-import { execWithBusyRetry } from './busy.js';
+import { DEFAULT_BUSY_WAIT_MS, execWithBusyRetry } from './busy.js';
 import { runMigrations } from './migrate.js';
 import { autoCheckpointPages } from './wal-checkpointer.js';
-export const DEFAULT_BUSY_WAIT_MS = 5000;
 export function getHippoDbPath(hippoRoot) {
     return path.join(hippoRoot, 'hippo.db');
 }
@@ -53,11 +52,11 @@ function archiveTop(db) {
     return Number(row?.top ?? 0);
 }
 /** A new connection with the store's pragmas and migrations applied and the mirror cleanup run when it is due; the caller owns and closes it. */
-export function connectWithFacts(hippoRoot, busyWaitMs) {
+export function connectWithFacts(hippoRoot, busyWaitMs = DEFAULT_BUSY_WAIT_MS) {
     createStoreFilesOwnerOnly(hippoRoot);
     const db = new DatabaseSync(getHippoDbPath(hippoRoot));
     try {
-        db.exec(`PRAGMA busy_timeout = ${busyWaitMs ?? DEFAULT_BUSY_WAIT_MS}`);
+        db.exec(`PRAGMA busy_timeout = ${busyWaitMs}`);
         execWithBusyRetry(db, 'PRAGMA journal_mode = WAL', busyWaitMs);
         db.exec('PRAGMA synchronous = NORMAL');
         db.exec(`PRAGMA wal_autocheckpoint = ${autoCheckpointPages(getHippoDbPath(hippoRoot))}`);
@@ -76,8 +75,8 @@ export function connectWithFacts(hippoRoot, busyWaitMs) {
         try {
             db.close();
         }
-        catch {
-            // Best effort only.
+        catch (closeErr) {
+            log.error(`openHippoDb: closing the handle after a failed open failed: ${errorMessage(closeErr)}`, errorFields(closeErr));
         }
         throw error;
     }

package/dist/db/index.d.ts

@@ -1,9 +1,9 @@
 export type { DatabaseSyncLike } from './sqlite.js';
-export { isSqliteBusy, isStoreBusy, StoreBusyError, STORE_BUSY_MESSAGE, execWithBusyRetry, withReadSnapshot, withTrialScope, withWriteScope, withWriteScopeOr } from './busy.js';
+export { isSqliteBusy, execWithBusyRetry, withReadSnapshot, withTrialScope, withWriteScope, withWriteScopeOr } from './busy.js';
 export { getSchemaVersion, getMeta, setMeta, isFtsAvailable } from './meta.js';
-export { countTableRows, pruneConsolidationRuns } from './tables.js';
+export { countTableRows, pruneConsolidationRuns, CONSOLIDATION_RUNS_KEPT } from './tables.js';
 export { getCurrentSchemaVersion, IncompatibleBinaryError, ftsRowCounts, repairFtsDrift } from './migrate.js';
-export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, scopedBusyWait, withSqliteBlocked, withSqliteAllowed, withSqliteOffLoop, outsideSqliteOffLoop, rethrowIfSqliteBlocked, OTHER_STORE_MARKER, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './open.js';
+export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, scopedBusyWait, withSqliteBlocked, withSqliteAllowed, withSqliteOffLoop, outsideSqliteOffLoop, OTHER_STORE_MARKER, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './open.js';
 export { RequestStores, runWithRequestStores, currentRequestStores, outsideRequestStores } from './request-stores.js';
 export { OtherStoreFolderError, SqliteBlockedError } from '../util/sqlite-blocked.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/db/index.js

@@ -1,8 +1,8 @@
-export { isSqliteBusy, isStoreBusy, StoreBusyError, STORE_BUSY_MESSAGE, execWithBusyRetry, withReadSnapshot, withTrialScope, withWriteScope, withWriteScopeOr } from './busy.js';
+export { isSqliteBusy, execWithBusyRetry, withReadSnapshot, withTrialScope, withWriteScope, withWriteScopeOr } from './busy.js';
 export { getSchemaVersion, getMeta, setMeta, isFtsAvailable } from './meta.js';
-export { countTableRows, pruneConsolidationRuns } from './tables.js';
+export { countTableRows, pruneConsolidationRuns, CONSOLIDATION_RUNS_KEPT } from './tables.js';
 export { getCurrentSchemaVersion, IncompatibleBinaryError, ftsRowCounts, repairFtsDrift } from './migrate.js';
-export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, scopedBusyWait, withSqliteBlocked, withSqliteAllowed, withSqliteOffLoop, outsideSqliteOffLoop, rethrowIfSqliteBlocked, OTHER_STORE_MARKER, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './open.js';
+export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, scopedBusyWait, withSqliteBlocked, withSqliteAllowed, withSqliteOffLoop, outsideSqliteOffLoop, OTHER_STORE_MARKER, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './open.js';
 export { RequestStores, runWithRequestStores, currentRequestStores, outsideRequestStores } from './request-stores.js';
 export { OtherStoreFolderError, SqliteBlockedError } from '../util/sqlite-blocked.js';
 //# sourceMappingURL=index.js.map

package/dist/db/migrations/index.d.ts

@@ -1,5 +1,5 @@
 import type { Migration } from './types.js';
-export declare const CURRENT_SCHEMA_VERSION = 54;
+export declare const CURRENT_SCHEMA_VERSION = 55;
 /** Every schema migration in version order; runMigrations applies each one above the stored version. */
 export declare const MIGRATIONS: Migration[];
 //# sourceMappingURL=index.d.ts.map