hippo-memory 2.0.0 → 2.1.0

package/dist/core/recall-scope.js

@@ -1,11 +1,21 @@
-/** 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`). */
+/**
+ * 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 './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). */
+/**
+ * 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'];
-/** @internal Runtime guard against blanking a load-bearing literal array; `as const` arrays widen via `readonly T[]` at the call site, so the empty case
+/**
+ * @internal Runtime guard against blanking a load-bearing literal array; `as const` arrays widen via `readonly T[]` at
+ * the call site, so the empty case
  * is reachable and testable. */
 export function assertNonEmpty(arr, name) {
     if (arr.length === 0) {
@@ -13,8 +23,12 @@ export function assertNonEmpty(arr, name) {
     }
 }
 assertNonEmpty(RECALL_DEFAULT_DENY_SCOPES, 'RECALL_DEFAULT_DENY_SCOPES');
-/** Source-agnostic private-scope detector: private means `<lowercase-source>:private:<rest>` (`slack:private:Cabc`; not `slack:public:x`, null, '',
- * 'private:foo'). The single source of truth for api.recall, the MCP server, the CLI and search-both.ts, so connector work cannot drift. */
+/**
+ * Source-agnostic private-scope detector: private means `<lowercase-source>:private:<rest>` (`slack:private:Cabc`; not
+ * `slack:public:x`, null, '',
+ * 'private:foo'). The single source of truth for api.recall, the MCP server, the CLI and search-both.ts, so connector
+ * work cannot drift.
+ */
 export const PRIVATE_SCOPE_RE = /^[a-z][a-z0-9_-]*:private:/;
 function isScopeString(value) {
     return typeof value === 'string';
@@ -56,15 +70,21 @@ export function ownScopeTouches(ownScope, scope) {
     return !isPersonalScope(scope) || scope === ownScope;
 }
 /** 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. */
+ * otherwise `<source>:private:*` and `RECALL_DEFAULT_DENY_SCOPES` buckets are denied, while null, public scopes and the
+ * caller's `ownScope` pass.
+ */
 export function passesScopeFilterForRecall(scope, requested, ownScope) {
     if (requested !== undefined && requested !== '') {
         return scope === requested;
     }
     return !isRestrictedScope(scope) || (ownScope != null && scope === 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. */
+/**
+ * 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) {
     if (requested !== undefined && requested !== '' && !isPersonalScope(requested) && scope === requested) {
         return true;
@@ -80,14 +100,20 @@ export class ScopeForbiddenError extends ForbiddenError {
         this.scope = scope;
     }
 }
-/** True for scopes default-deny hides (`<source>:private:*` and the quarantine buckets); naming one explicitly unlocks it, so naming one needs
+/**
+ * True for scopes default-deny hides (`<source>:private:*` and the quarantine buckets); naming one explicitly unlocks
+ * it, so naming one needs
  * authorization. */
 export function isRestrictedScope(scope) {
     if (!isScopeString(scope))
         return false;
-    // SAFETY: RECALL_DEFAULT_DENY_SCOPES is a readonly tuple of string literals; widening the array lets .includes() take any scope.
-    // `:private:` anywhere, any case, matches the SQL default-deny in src/store/search-rows.ts so JS never admits what SQL hides.
-    return isPrivateScope(scope) || /:private:/i.test(scope) || RECALL_DEFAULT_DENY_SCOPES.includes(scope);
+    // SAFETY: RECALL_DEFAULT_DENY_SCOPES is a readonly tuple of string literals; widening the array lets .includes() take
+    // any scope.
+    // `:private:` anywhere, any case, matches the SQL default-deny in src/store/search-rows.ts so JS never admits what
+    // SQL hides.
+    return (isPrivateScope(scope) ||
+        /:private:/i.test(scope) ||
+        RECALL_DEFAULT_DENY_SCOPES.includes(scope));
 }
 /** Personal rows answer to their owner alone: role, key grants and resolver scopes never
  * open one. Else admin reads all; a member needs an exact grant on a restricted scope. */
@@ -132,7 +158,8 @@ export function commonDerivationScope(scopes) {
 /** Map-partition key for consolidate/dag/dedup producers: tenant + derivation scope + origin project,
  *  so a derived row never blends two restricted scopes, a mixed pair, or two projects. */
 export function derivationPartitionKey(tenantId, scope, origin) {
-    const project = origin === undefined ? '\u0002' : origin ?? '\u0001'; // unstamped, unknown and named never share a bucket
+    // unstamped, unknown and named never share a bucket
+    const project = origin === undefined ? '\u0002' : (origin ?? '\u0001');
     return `${tenantId}\u0000${derivationScope(scope) ?? ''}\u0000${project}`;
 }
 //# sourceMappingURL=recall-scope.js.map

package/dist/core/rejection-digest.d.ts

@@ -0,0 +1,7 @@
+/** Normalize content for rejection digests: NFC, lowercase, collapse whitespace runs, trim. No punctuation stripping:
+ * over-normalizing causes false refusals, worse than misses. */
+export declare function normalizeValueForRejection(content: string): string;
+/** Full 64-char sha256 hex of the normalized content: a tombstone key needs collision resistance, not the 16-char
+ * redaction hash used for query hashing. */
+export declare function rejectionDigest(content: string): string;
+//# sourceMappingURL=rejection-digest.d.ts.map

package/dist/core/rejection-digest.js

@@ -0,0 +1,13 @@
+// Tombstone keys are a pure hash of the normalized value, so the domain computes them without reaching the store.
+import { createHash } from 'node:crypto';
+/** Normalize content for rejection digests: NFC, lowercase, collapse whitespace runs, trim. No punctuation stripping:
+ * over-normalizing causes false refusals, worse than misses. */
+export function normalizeValueForRejection(content) {
+    return content.normalize('NFC').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+/** Full 64-char sha256 hex of the normalized content: a tombstone key needs collision resistance, not the 16-char
+ * redaction hash used for query hashing. */
+export function rejectionDigest(content) {
+    return createHash('sha256').update(normalizeValueForRejection(content)).digest('hex');
+}
+//# sourceMappingURL=rejection-digest.js.map

package/dist/core/salience.d.ts

@@ -1,4 +1,6 @@
-/** Salience gate: decides at memory creation whether content is stored at full strength, starts weakened, or is skipped. */
+/**
+ * Salience gate: decides at memory creation whether content is stored at full strength, starts weakened, or is skipped.
+ */
 import type { MemoryEntry } from './memory.js';
 export type SalienceDecision = 'store' | 'skip' | 'start_weak';
 export interface SalienceResult {

package/dist/core/salience.js

@@ -1,4 +1,6 @@
-/** Salience gate: decides at memory creation whether content is stored at full strength, starts weakened, or is skipped. */
+/**
+ * Salience gate: decides at memory creation whether content is stored at full strength, starts weakened, or is skipped.
+ */
 import { textOverlap } from '../util/tokenize.js';
 import { duplicateKey, heldTextKeys } from '../util/same-text.js';
 // Each store or skip reason carries a score; a novel memory adds bonuses for structure and length.
@@ -10,6 +12,9 @@ const NOVEL_ERROR_SCORE = 0.9;
 const NOVEL_BASE_SCORE = 0.5;
 const STRUCTURED_TAGS_BONUS = 0.15;
 const LENGTH_BONUS = 0.1;
+// A novel memory earns LENGTH_BONUS past each of these lengths in characters.
+const LONG_CONTENT_CHARS = 100;
+const VERY_LONG_CONTENT_CHARS = 300;
 const DEFAULTS = {
     recentWindow: 20,
     overlapThreshold: 0.6,
@@ -35,7 +40,8 @@ export function computeSalience(content, tags, recentMemories, options = {}) {
             if (recentErrors >= opts.maxRepeatErrors) {
                 return {
                     decision: 'start_weak',
-                    reason: `repeat_error (${recentErrors} recent errors, overlap ${(duplicateMatch.overlap * 100).toFixed(0)}% with ${duplicateMatch.matchId})`,
+                    reason: `repeat_error (${recentErrors} recent errors, overlap ` +
+                        `${(duplicateMatch.overlap * 100).toFixed(0)}% with ${duplicateMatch.matchId})`,
                     score: REPEAT_ERROR_SCORE,
                 };
             }
@@ -66,9 +72,9 @@ function scoreNovel(trimmed, tags) {
     let score = NOVEL_BASE_SCORE;
     if (hasStructuredTags)
         score += STRUCTURED_TAGS_BONUS;
-    if (trimmed.length > 100)
+    if (trimmed.length > LONG_CONTENT_CHARS)
         score += LENGTH_BONUS;
-    if (trimmed.length > 300)
+    if (trimmed.length > VERY_LONG_CONTENT_CHARS)
         score += LENGTH_BONUS;
     return { decision: 'store', reason: 'novel', score: Math.min(score, 1.0) };
 }

package/dist/core/search-types.d.ts

@@ -1,7 +1,17 @@
 import type { MemoryEntry } from './memory.js';
 export declare const DEFAULT_RECALL_BUDGET = 4000;
 export declare const DEFAULT_LOCAL_BUMP = 1.2;
-/** One score mutation applied after candidate generation; allocated only under `recall --why` or `RecallOpts.explain`. */
+export declare const DEFAULT_MMR_LAMBDA = 0.7;
+export declare const CONFLICT_PEER_MULTIPLIER = 0.3;
+export declare const VALUE_MULT_SLOPE = 0.3;
+export declare const VALUE_MULT_MIN = 0.7;
+export declare const VALUE_MULT_MAX = 1.3;
+export declare const UTILITY_LENGTH_PENALTY_CAP = 0.3;
+export declare const UTILITY_LENGTH_TOKENS = 10000;
+export declare const SALIENCE_MIN_MULTIPLIER = 0.5;
+/**
+ * One score mutation applied after candidate generation; allocated only under `recall --why` or `RecallOpts.explain`.
+ */
 export interface RerankStep {
     /** One of: interference, value, utility, reranker, goal-boost, retrieval-count-downweight. */
     stage: string;
@@ -63,7 +73,10 @@ export interface ScoreBreakdown {
     scopeBoost: number;
     /** Extra multiplier applied post-hybrid (e.g. 1.2x for local hits in a local+global merge); 1.0 otherwise. */
     sourceBump: number;
-    /** Immediate outcome nudge, 1 + 0.15*tanh((pos - neg) / 2) clipped to [0.85, 1.15]; separate from the slow strength path. */
+    /**
+     * Immediate outcome nudge, 1 + 0.15*tanh((pos - neg) / 2) clipped to [0.85, 1.15]; separate from the slow strength
+     * path.
+     */
     outcomeBoost: number;
     /** CHURN_STALE_RANK_MULTIPLIER if tagged 'churn-stale', else 1.0. */
     churnStaleMultiplier: number;

package/dist/core/search-types.js

@@ -1,4 +1,15 @@
 export const DEFAULT_RECALL_BUDGET = 4000;
 // Local memories outrank global ones by this factor; getContext applies it as a 1/x global discount.
 export const DEFAULT_LOCAL_BUMP = 1.2;
+// The relevance side of the MMR relevance-versus-diversity trade; config and hybrid recall both default to it.
+export const DEFAULT_MMR_LAMBDA = 0.7;
+// A recorded conflict peer in the same result list is cut to this share of its score.
+export const CONFLICT_PEER_MULTIPLIER = 0.3;
+// The value-aware clamp is wider than the always-on outcome nudge, so outcome history can decide the order.
+export const VALUE_MULT_SLOPE = 0.3;
+export const VALUE_MULT_MIN = 0.7;
+export const VALUE_MULT_MAX = 1.3;
+export const UTILITY_LENGTH_PENALTY_CAP = 0.3;
+export const UTILITY_LENGTH_TOKENS = 10000;
+export const SALIENCE_MIN_MULTIPLIER = 0.5;
 //# sourceMappingURL=search-types.js.map

package/dist/dashboard/dashboard-actions.js

@@ -5,6 +5,7 @@ import { RawAppendOnlyError } from '../core/raw-append-only.js';
 import { listTouchableConflicts, resolveConflict } from '../store/conflicts.js';
 import { readEntry } from '../store/entry-reads.js';
 import { writeEntry } from '../store/entry-writes.js';
+import { sqliteStore } from '../store/sqlite/store.js';
 import { ParamError, parseMemoryId } from './dashboard-params.js';
 import { isLiveMemory } from './dashboard-snapshot.js';
 const ACTOR = 'dashboard';
@@ -33,7 +34,12 @@ export async function markWrong(hippoRoot, tenantId, rawId) {
     const id = parseMemoryId(rawId);
     if (liveEntry(hippoRoot, tenantId, id) === null)
         return notFound();
-    const ctx = { hippoRoot, tenantId, actor: api.adminActor(ACTOR) };
+    const ctx = {
+        hippoRoot,
+        tenantId,
+        actor: api.adminActor(ACTOR),
+        store: sqliteStore(hippoRoot),
+    };
     // outcome() answers `applied: 0` for a missing or other-tenant id instead of throwing.
     if ((await api.outcome(ctx, [id], false)).applied === 0)
         return notFound();
@@ -45,7 +51,12 @@ export async function forgetMemory(hippoRoot, tenantId, rawId) {
     const id = parseMemoryId(rawId);
     if (liveEntry(hippoRoot, tenantId, id) === null)
         return notFound();
-    const ctx = { hippoRoot, tenantId, actor: api.adminActor(ACTOR) };
+    const ctx = {
+        hippoRoot,
+        tenantId,
+        actor: api.adminActor(ACTOR),
+        store: sqliteStore(hippoRoot),
+    };
     try {
         const done = await api.forget(ctx, id);
         return { status: 200, body: done, changed: true };

package/dist/dashboard/dashboard-snapshot.d.ts

@@ -129,8 +129,8 @@ export interface SnapshotService {
     invalidate(): void;
     /** Id of the most recent build, which is what a client holding the last response still has. */
     currentId(): number;
-    /** Ids with a vector as of the last build (a direct read before any build), so a detail read never rescans the vector table. */
-    embeddedIds(): ReadonlySet<string> | null;
+    /** Whether a row of the last build's tenant had a vector at that build (a point read before any build), so a detail read never scans vectors. */
+    isEmbedded(id: string): boolean;
     close(): void;
 }
 /** Holds one read-only connection for its commit signal (`PRAGMA data_version`) and the

package/dist/dashboard/dashboard-snapshot.js

@@ -260,7 +260,7 @@ class SnapshotCacheService {
         this.lastId += 1;
         highestIssuedId = Math.max(highestIssuedId, this.lastId);
         // After loadDashboardRows, whose writable open has run any pending migration and legacy embeddings.json import.
-        this.lastEmbeddedIds = this.connection.embeddedIds();
+        this.lastEmbeddedIds = this.connection.embeddedIds(tenantId);
         return buildSnapshot({
             id: this.lastId,
             tenantId,
@@ -292,11 +292,11 @@ class SnapshotCacheService {
     currentId() {
         return this.lastId;
     }
-    embeddedIds() {
+    isEmbedded(id) {
         if (this.lastEmbeddedIds !== undefined)
-            return this.lastEmbeddedIds;
+            return this.lastEmbeddedIds?.has(id) ?? false;
         this.connection.dataVersion();
-        return this.connection.embeddedIds();
+        return this.connection.hasVector(id);
     }
     close() {
         this.connection.close();

package/dist/dashboard/dashboard.js

@@ -19,6 +19,7 @@ import { installSignalHandlers } from '../util/crash-handlers.js';
 import { DEFAULT_SHUTDOWN_DRAIN_MS, drainAndClose, setKeepAliveTimeouts, shutdownBoundMs } from '../server/lifecycle.js';
 import { printError } from '../cli/output.js';
 import { PACKAGE_ROOT } from '../core/package-root.js';
+import { DAY_MS } from '../util/time.js';
 const MIME_TYPES = {
     '.html': 'text/html; charset=utf-8',
     '.js': 'application/javascript; charset=utf-8',
@@ -132,7 +133,7 @@ function handleRead(ctx, segments) {
         if (entry === null || !isLiveMemory(entry))
             return sendOrNotFound(res, null);
         const snapshotId = snapshots.get(tenantId, fresh).id;
-        const embedded = snapshots.embeddedIds()?.has(entry.id) ?? false;
+        const embedded = snapshots.isEmbedded(entry.id);
         return sendOrNotFound(res, buildMemoryDetail(hippoRoot, tenantId, entry, { snapshotId, nowMs: ctx.now(), embedded }));
     }
     if (head === 'search' && segments.length === 2) {
@@ -184,7 +185,7 @@ async function handlePost(ctx, segments) {
         snapshots.invalidate();
     if (result.entry) {
         // The write is committed, so a rebuild failure must not turn it into a 500: the next read rebuilds.
-        const embedded = snapshots.embeddedIds()?.has(result.entry.id) ?? false;
+        const embedded = snapshots.isEmbedded(result.entry.id);
         const detail = buildMemoryDetail(hippoRoot, tenantId, result.entry, { snapshotId: snapshots.currentId(), nowMs: ctx.now(), embedded });
         jsonResponse(res, detail, result.status);
     }
@@ -279,13 +280,15 @@ function leaveTokenUrl(req, res, url) {
     res.end(`<!doctype html>\n<html lang="en"><head><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${target}"><title>Hippo Dashboard</title></head><body></body></html>`);
     return true;
 }
+// A browser that restores its session keeps a cookie with no Max-Age for good; no Secure, since this server speaks plain HTTP on loopback only.
+const DASHBOARD_COOKIE_MAX_AGE_S = DAY_MS / 1000;
 /** True when the request may proceed; false when this already answered it (redirect off the token URL, or 401). */
 function admitDashboardRequest(req, res, url, access) {
     const { token, port } = access;
     // Cookies ignore the port, so the name carries it: two dashboards on one host keep separate tokens.
     const cookieName = `hippo_dashboard_${req.socket.localPort ?? port}`;
     if (sameToken(url.searchParams.get('token') ?? undefined, token)) {
-        res.setHeader('Set-Cookie', `${cookieName}=${token}; HttpOnly; SameSite=Strict; Path=/`);
+        res.setHeader('Set-Cookie', `${cookieName}=${token}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${DASHBOARD_COOKIE_MAX_AGE_S}`);
         if (leaveTokenUrl(req, res, url))
             return false;
     }

package/dist/db/backup.js

@@ -1,6 +1,6 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { log } from '../util/log.js';
+import { log, errorFields } from '../util/log.js';
 /** Copies the database before a repair writes, so the audit ids plus this file are the way back. */
 export function backupStore(db, hippoRoot, label, now = new Date()) {
     const dir = path.join(hippoRoot, 'backups');
@@ -21,7 +21,7 @@ export function withBackup(db, hippoRoot, label, transaction) {
             fs.rmSync(backup, { force: true });
         }
         catch (cleanupError) {
-            log.warn(`Could not delete the unused backup ${backup}: ${String(cleanupError)}`);
+            log.warn(`Could not delete the unused backup ${backup}: ${String(cleanupError)}`, errorFields(cleanupError));
         }
         throw err;
     }

package/dist/db/busy.d.ts

@@ -8,18 +8,25 @@ export interface WriteScopeOptions {
     readonly busyWaitMs?: number;
 }
 /** 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. */
+ * A deferred scope that reads first cannot wait out another writer, while BEGIN IMMEDIATE waits the open's
+ * busy_timeout.
+ */
 export declare function withWriteScope<T>(db: DatabaseSyncLike, name: string, fn: () => T, opts?: WriteScopeOptions): T;
 /** Runs the reads in `fn` against one snapshot, so two statements cannot straddle another process's write. */
 export declare function withReadSnapshot<T>(db: DatabaseSyncLike, fn: () => T): T;
-/** Runs `fn` and undoes every write it made, throw or not: a dry run that reports what a real run would do. Takes no write lock up front. */
+/**
+ * Runs `fn` and undoes every write it made, throw or not: a dry run that reports what a real run would do. Takes no
+ * write lock up front.
+ */
 export declare function withTrialScope<T>(db: DatabaseSyncLike, name: string, fn: () => T): T;
 /** What `withWriteScopeOr` hands its callback's `rollback(value)`; a class so no stored value can pass for one. */
 declare class RolledBack<V> {
     readonly value: V;
     constructor(value: V);
 }
-/** `withWriteScope` for a write that can refuse: a callback that returns `rollback(value)` gets the scope's writes undone
+/**
+ * `withWriteScope` for a write that can refuse: a callback that returns `rollback(value)` gets the scope's writes
+ * undone
  *  and `value` back, with no throw. Any other return commits. */
 export declare function withWriteScopeOr<T, R>(db: DatabaseSyncLike, name: string, fn: (rollback: <V>(value: V) => RolledBack<V>) => T | RolledBack<R>): T | R;
 export {};

package/dist/db/busy.js

@@ -8,7 +8,8 @@ export function isSqliteBusy(cause) {
 }
 /** 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
+// 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 = DEFAULT_BUSY_WAIT_MS) {
     const deadline = Date.now() + timeoutMs;
@@ -25,6 +26,14 @@ export function execWithBusyRetry(db, sql, timeoutMs = DEFAULT_BUSY_WAIT_MS) {
         }
     }
 }
+// SQLite cannot bind a savepoint name as a parameter, so the name is spliced into the SQL and must be a bare
+// identifier.
+const SAVEPOINT_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertSavepointName(name) {
+    if (!SAVEPOINT_NAME_RE.test(name)) {
+        throw new Error(`invalid savepoint name ${JSON.stringify(name)}: use letters, digits and _ only`);
+    }
+}
 function undoScope(db, top, name) {
     if (top) {
         db.exec('ROLLBACK');
@@ -34,7 +43,10 @@ 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. */
+/**
+ * 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;
@@ -46,8 +58,11 @@ function undoAfterFailure(db, top, name) {
     }
 }
 /** 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. */
+ * 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) {
+    assertSavepointName(name);
     const top = db.isTransaction === false;
     if (top && opts)
         execWithBusyRetry(db, 'BEGIN IMMEDIATE', opts.busyWaitMs);
@@ -84,8 +99,12 @@ export function withReadSnapshot(db, fn) {
     db.exec('COMMIT');
     return result;
 }
-/** Runs `fn` and undoes every write it made, throw or not: a dry run that reports what a real run would do. Takes no write lock up front. */
+/**
+ * Runs `fn` and undoes every write it made, throw or not: a dry run that reports what a real run would do. Takes no
+ * write lock up front.
+ */
 export function withTrialScope(db, name, fn) {
+    assertSavepointName(name);
     const top = db.isTransaction === false;
     db.exec(top ? 'BEGIN' : `SAVEPOINT ${name}`);
     let result;
@@ -106,9 +125,12 @@ class RolledBack {
         this.value = value;
     }
 }
-/** `withWriteScope` for a write that can refuse: a callback that returns `rollback(value)` gets the scope's writes undone
+/**
+ * `withWriteScope` for a write that can refuse: a callback that returns `rollback(value)` gets the scope's writes
+ * undone
  *  and `value` back, with no throw. Any other return commits. */
 export function withWriteScopeOr(db, name, fn) {
+    assertSavepointName(name);
     const top = db.isTransaction === false;
     db.exec(top ? 'BEGIN IMMEDIATE' : `SAVEPOINT ${name}`);
     try {

package/dist/db/connect.d.ts

@@ -3,12 +3,19 @@ import { type OpenFacts } from './migrate.js';
 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;
-/** A connection with what its own open's probe read; facts go stale with the next statement, so a handle made by an earlier call carries null. */
+/**
+ * A connection with what its own open's probe read; facts go stale with the next statement, so a handle made by an
+ * earlier call carries null.
+ */
 export interface OpenedDb {
     readonly db: DatabaseSyncLike;
     readonly facts: OpenFacts | null;
 }
-/** 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.
- *  Outside any request scope (CLI start-up, timers) this is the only handle there is; openHippoDb reuses the scope's when one exists. */
+/**
+ * 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.
+ * Outside any request scope (CLI start-up, timers) this is the only handle there is; openHippoDb reuses the scope's
+ * when one exists.
+ */
 export declare function connectWithFacts(hippoRoot: string, busyWaitMs?: number): OpenedDb;
 //# sourceMappingURL=connect.d.ts.map

package/dist/db/connect.js

@@ -37,7 +37,8 @@ function createStoreFilesOwnerOnly(hippoRoot) {
             throw err;
     }
 }
-// The archive only grows and its ids never repeat, so an unchanged top id means no row this process has not swept; a failed sweep stays due.
+// The archive only grows and its ids never repeat, so an unchanged top id means no row this process has not swept; a
+// failed sweep stays due.
 function sweepArchivedMirrorsIfDue(hippoRoot, db, probedTop) {
     const top = probedTop ?? archiveTop(db);
     const key = storeKey(hippoRoot);
@@ -51,8 +52,12 @@ function archiveTop(db) {
     const row = db.prepare('SELECT MAX(id) AS top FROM raw_archive').get();
     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.
- *  Outside any request scope (CLI start-up, timers) this is the only handle there is; openHippoDb reuses the scope's when one exists. */
+/**
+ * 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.
+ * Outside any request scope (CLI start-up, timers) this is the only handle there is; openHippoDb reuses the scope's
+ * when one exists.
+ */
 export function connectWithFacts(hippoRoot, busyWaitMs = DEFAULT_BUSY_WAIT_MS) {
     createStoreFilesOwnerOnly(hippoRoot);
     const db = new DatabaseSync(getHippoDbPath(hippoRoot));

package/dist/db/continuity.d.ts

@@ -2,7 +2,7 @@ import type { DatabaseSyncLike } from './sqlite.js';
 export declare const MEMORY_QUARANTINE_DDL = "\n    CREATE TABLE IF NOT EXISTS memory_quarantine (\n      tenant_id      TEXT NOT NULL DEFAULT 'default',\n      memory_id      TEXT NOT NULL,\n      original_scope TEXT,\n      reason         TEXT NOT NULL,\n      status         TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','approved','rejected')),\n      quarantined_at TEXT NOT NULL,\n      decided_at     TEXT,\n      decided_by     TEXT,\n      PRIMARY KEY (tenant_id, memory_id)\n    ) WITHOUT ROWID;\n    CREATE INDEX IF NOT EXISTS idx_memory_quarantine_status\n      ON memory_quarantine(tenant_id, status, quarantined_at DESC);\n";
 export declare const SESSION_OWNERS_DDL = "\n    CREATE TABLE IF NOT EXISTS session_owners (\n      tenant_id TEXT NOT NULL,\n      session_id TEXT NOT NULL,\n      owner_subject TEXT NOT NULL,\n      created_at TEXT NOT NULL,\n      PRIMARY KEY (tenant_id, session_id)\n    )\n  ";
 export declare function ensureContinuityTables(db: DatabaseSyncLike): void;
-export declare const MEMORIES_FTS_DDL = "CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(id UNINDEXED, content, tags)";
+export declare const MEMORIES_FTS_DDL: string;
 /** Names of every table and index a `CREATE ... IF NOT EXISTS` in `ddl` makes. */
 export declare function createdObjectNames(ddl: string): string[];
 /** Every object runMigrations re-asserts on a stamped store; the open fast path requires all of them. */

package/dist/db/continuity.js

@@ -149,35 +149,51 @@ const CONTINUITY_INDEX_DDL = [
     `CREATE INDEX IF NOT EXISTS idx_task_snapshots_status_updated ON task_snapshots(status, updated_at DESC, id DESC)`,
     `CREATE INDEX IF NOT EXISTS idx_task_snapshots_tenant_status ON task_snapshots(tenant_id, status, updated_at DESC)`,
     `CREATE INDEX IF NOT EXISTS idx_task_snapshots_tenant_scope ON task_snapshots(tenant_id, scope, status)`,
-    `CREATE INDEX IF NOT EXISTS idx_session_events_session_created ON session_events(session_id, created_at DESC, id DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_events_session_created ON session_events(session_id, created_at DESC, id ` +
+        `DESC)`,
     `CREATE INDEX IF NOT EXISTS idx_session_events_task_created ON session_events(task, created_at DESC, id DESC)`,
-    `CREATE INDEX IF NOT EXISTS idx_session_events_tenant_session ON session_events(tenant_id, session_id, created_at DESC, id DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_events_tenant_session ON session_events(tenant_id, session_id, created_at ` +
+        `DESC, id DESC)`,
     `CREATE INDEX IF NOT EXISTS idx_session_handoffs_session ON session_handoffs(session_id, created_at DESC)`,
-    `CREATE INDEX IF NOT EXISTS idx_session_handoffs_tenant_session ON session_handoffs(tenant_id, session_id, created_at DESC)`,
-    `CREATE INDEX IF NOT EXISTS idx_session_handoffs_tenant_outcome ON session_handoffs(tenant_id, outcome, created_at DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_handoffs_tenant_session ON session_handoffs(tenant_id, session_id, ` +
+        `created_at DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_handoffs_tenant_outcome ON session_handoffs(tenant_id, outcome, created_at ` +
+        `DESC)`,
     `CREATE INDEX IF NOT EXISTS idx_cards_tenant_status ON cards(tenant_id, status, updated_at DESC)`,
     `CREATE INDEX IF NOT EXISTS idx_card_deps_tenant_child ON card_deps(tenant_id, child)`,
     `CREATE INDEX IF NOT EXISTS idx_card_deps_tenant_parent ON card_deps(tenant_id, parent)`,
     `CREATE INDEX IF NOT EXISTS idx_card_runs_tenant_card ON card_runs(tenant_id, card, started DESC)`,
     `CREATE INDEX IF NOT EXISTS idx_card_comments_tenant_card ON card_comments(tenant_id, card_id, created_at DESC)`,
-    `CREATE INDEX IF NOT EXISTS idx_session_handoffs_tenant_card ON session_handoffs(tenant_id, card_id, created_at DESC)`,
-    `CREATE INDEX IF NOT EXISTS idx_task_snapshots_owner ON task_snapshots(tenant_id, owner_subject, origin_project, status, updated_at DESC)`,
-    `CREATE INDEX IF NOT EXISTS idx_session_handoffs_owner ON session_handoffs(tenant_id, owner_subject, origin_project, created_at DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_handoffs_tenant_card ON session_handoffs(tenant_id, card_id, created_at ` +
+        `DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_task_snapshots_owner ON task_snapshots(tenant_id, owner_subject, origin_project, ` +
+        `status, updated_at DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_handoffs_owner ON session_handoffs(tenant_id, owner_subject, ` +
+        `origin_project, created_at DESC)`,
 ];
 // A client retry carries the same request id, so a repeat finds the earlier row instead of writing again.
 const REQUEST_INDEX_DDL = {
-    compactions: `CREATE UNIQUE INDEX IF NOT EXISTS idx_compactions_request ON compactions(tenant_id, request_id) WHERE request_id IS NOT NULL`,
-    failure_log: `CREATE UNIQUE INDEX IF NOT EXISTS idx_failure_log_request ON failure_log(tenant_id, request_id) WHERE request_id IS NOT NULL`,
+    compactions: `CREATE UNIQUE INDEX IF NOT EXISTS idx_compactions_request ON compactions(tenant_id, request_id) ` +
+        `WHERE request_id IS NOT NULL`,
+    failure_log: `CREATE UNIQUE INDEX IF NOT EXISTS idx_failure_log_request ON failure_log(tenant_id, request_id) ` +
+        `WHERE request_id IS NOT NULL`,
 };
 // Lives with the other re-asserted DDL so the required-object list below derives from one place.
-export const MEMORIES_FTS_DDL = `CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(id UNINDEXED, content, tags)`;
+export const MEMORIES_FTS_DDL = `CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts ` +
+    `USING fts5(id UNINDEXED, content, tags)`;
 const CREATED_NAME = /CREATE\s+(?:VIRTUAL\s+|UNIQUE\s+)?(?:TABLE|INDEX)\s+IF\s+NOT\s+EXISTS\s+(\w+)/gi;
 /** Names of every table and index a `CREATE ... IF NOT EXISTS` in `ddl` makes. */
 export function createdObjectNames(ddl) {
     return [...ddl.matchAll(CREATED_NAME)].map((m) => m[1]);
 }
 /** Every object runMigrations re-asserts on a stamped store; the open fast path requires all of them. */
-export const REQUIRED_SCHEMA_OBJECTS = Object.freeze([META_TABLE_DDL, ...CONTINUITY_TABLE_DDL, ...CONTINUITY_INDEX_DDL, ...Object.values(REQUEST_INDEX_DDL), MEMORIES_FTS_DDL].flatMap(createdObjectNames));
+export const REQUIRED_SCHEMA_OBJECTS = Object.freeze([
+    META_TABLE_DDL,
+    ...CONTINUITY_TABLE_DDL,
+    ...CONTINUITY_INDEX_DDL,
+    ...Object.values(REQUEST_INDEX_DDL),
+    MEMORIES_FTS_DDL,
+].flatMap(createdObjectNames));
 // After the loop: tenant_id (v16) and scope (v23) do not exist yet on a genuine old store.
 export function ensureContinuityIndexes(db) {
     for (const ddl of CONTINUITY_INDEX_DDL)

package/dist/db/meta.d.ts

@@ -9,7 +9,10 @@ export declare function pragmaDataVersion(db: DatabaseSyncLike): number;
 export declare function setSchemaVersion(db: DatabaseSyncLike, version: number): void;
 export declare function getMeta(db: DatabaseSyncLike, key: string, fallback?: string): string;
 export declare function setMeta(db: DatabaseSyncLike, key: string, value: string): void;
-/** Raise min_compatible_binary to `version`; never lowers it, since an older floor would let back in a binary a newer write already shut out. */
+/**
+ * Raise min_compatible_binary to `version`; never lowers it, since an older floor would let back in a binary a newer
+ * write already shut out.
+ */
 export declare function raiseMinBinary(db: DatabaseSyncLike, version: string): void;
 export declare function isFtsAvailable(db: DatabaseSyncLike): boolean;
 //# sourceMappingURL=meta.d.ts.map

package/dist/db/meta.js

@@ -41,7 +41,10 @@ export function getMeta(db, key, fallback = '') {
 export function setMeta(db, key, value) {
     db.prepare(`INSERT INTO meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value`).run(key, value);
 }
-/** Raise min_compatible_binary to `version`; never lowers it, since an older floor would let back in a binary a newer write already shut out. */
+/**
+ * Raise min_compatible_binary to `version`; never lowers it, since an older floor would let back in a binary a newer
+ * write already shut out.
+ */
 export function raiseMinBinary(db, version) {
     const existing = getMeta(db, 'min_compatible_binary');
     if (!existing || compareSemver(version, existing) > 0)