hippo-memory 1.63.2 → 1.64.0

package/dist/prompt-hook.d.ts

@@ -0,0 +1,65 @@
+import { type Context, type ContextResult, type ContextResultEntry } from './api.js';
+import { type openHippoDb } from './db.js';
+import type { DeliveryRecorder } from './delivery-recorder.js';
+import { type JsonValue } from './json.js';
+import type { MemoryEntry } from './memory.js';
+import { type PilotArm } from './pilot-arm.js';
+/** With `db`, writes on the token ledger's handle (same store); without it, opens its own. A second flush is a no-op. */
+export declare function flushDeliveryRecorder(rec: DeliveryRecorder | null, db?: ReturnType<typeof openHippoDb>): void;
+/** What one render needs once api.getContext has answered. */
+export interface ContextView {
+    readonly hippoRoot: string;
+    readonly tenantId: string;
+    readonly ledgerSessionId: string | undefined;
+    readonly payloadSessionId: string | undefined;
+    readonly pinnedOnly: boolean;
+    readonly framing: string;
+    readonly rec: DeliveryRecorder | null;
+    readonly result: ContextResult;
+    /** Ledger rows stay in `hippoRoot`, never the global store; see promptHookContext. */
+    readonly sharedStore?: boolean;
+    /** The static block's hash the caller says it printed last. Undefined keeps the ledger-only skip rule;
+     *  a string or null also needs that hash to match, because the ledger counts blocks a caller that prints elsewhere may never have shown. */
+    readonly printedHash?: string | null;
+}
+export declare function hasContextData(result: ContextResult): boolean;
+export type RenderItem = {
+    entry: MemoryEntry;
+    score: number;
+    tokens: number;
+    isGlobal: boolean;
+};
+export declare function toRenderItems(entries: ContextResultEntry[]): RenderItem[];
+/** The hook format's stdout, '' when nothing is sent: a skippable static block (snapshot, handoff, events, pins, recent-N) and a never-skipped recall block. */
+export declare function additionalContextOutput(view: ContextView): string;
+/** The project a hook caller runs in: its id, the folder name its older rows carry, and any other names it resolves to. */
+export interface CallerProject {
+    readonly name: string;
+    readonly legacyName: string;
+    readonly aliases?: readonly string[];
+}
+interface PromptHookRequest {
+    readonly sessionId: string;
+    readonly project: CallerProject;
+    readonly payload?: Readonly<Record<string, JsonValue>>;
+    /** The staticHash of the last reply whose stdout the caller printed in this session; absent, the block is always sent. */
+    readonly printedHash?: string;
+}
+interface PromptHookOpts {
+    /** The store serves many people, so the caller is not its owner: no global store, no user-global recent rows,
+     *  task state only for the caller's own owner and project, and no ledger rows outside this store. */
+    readonly sharedStore?: true;
+}
+/** The caps on a hook caller's session id and project names, so a caller other than an HTTP route is bounded too. */
+export declare function assertCallerIds(sessionId: string, project: CallerProject): void;
+/** The text `hippo context --pinned-only --include-recent 5 --format additional-context` prints for this session, read on `ctx`'s store for the caller's project, leaving out an unchanged static block only when `printedHash` matches it.
+ *  `arm` is the raw ledger arm (`hippo` or `holdout`), null at rate 0; a holdout session gets an empty stdout. `staticHash` is the hash to echo back: null with no static block, for a sub-agent or a holdout.
+ *  Scope detection (HIPPO_SCOPE and skill env vars) and delivery-ledger events are CLI-only.
+ *  Throws BadRequestError past the input caps, and on a shared store for a project assertCallerProject refuses, before any arm is booked. */
+export declare function promptHookContext(ctx: Context, req: PromptHookRequest, opts?: PromptHookOpts): Promise<{
+    arm: PilotArm | null;
+    stdout: string;
+    staticHash: string | null;
+}>;
+export {};
+//# sourceMappingURL=prompt-hook.d.ts.map

package/dist/prompt-hook.js

@@ -0,0 +1,213 @@
+// The per-prompt hook's block and ledger rows, rendered here for `hippo context` and for promptHookContext (a remote hook route's call).
+// promptHookContext keeps the server-side copy of the CLI's getContext flags (cli/context.ts); the CLI parity case in tests/prompt-hook-context.test.ts is all that ties the two.
+import { getContext } from './api.js';
+import { BadRequestError } from './api-errors.js';
+import { isSharedStore, loadConfig } from './config.js';
+import { contextBlockLines, contextCost, crossProjectLines, handoffText, sessionTrailText, settleTokens, snapshotText } from './context-render.js';
+import { isSqliteBusy, noteStoreBusy } from './db.js';
+import { MAX_ID_LEN } from './http-util.js';
+import { isJsonString } from './json.js';
+import { withLedgerDb } from './ledger-db.js';
+import { sessionPilotArm } from './pilot-arm.js';
+import { assertCallerProject, MAX_PROJECT_ALIASES } from './project-identity.js';
+import { writeDeliveryEventAtRoot, writeDeliveryEventOnHandle } from './recall-trace.js';
+import { blockHash, estimateTokens, isSubagentPayload, lastSentState, recordTokenUse, shouldSkipUnchanged } from './token-ledger.js';
+/** With `db`, writes on the token ledger's handle (same store); without it, opens its own. A second flush is a no-op. */
+export function flushDeliveryRecorder(rec, db) {
+    if (rec === null)
+        return;
+    try {
+        rec.flush((input) => (db ? writeDeliveryEventOnHandle(db, input) : writeDeliveryEventAtRoot(rec.root, input)));
+    }
+    catch (error) {
+        // The hook's one-line stderr contract pins this exact text, so it bypasses the leveled logger.
+        console.error(`[hippo] delivery ledger write failed:${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+const NOTHING_RENDERED = Object.freeze({ stdout: '', staticHash: null });
+export function hasContextData(result) {
+    return Boolean(result.entries.length > 0 ||
+        result.activeSnapshot ||
+        result.sessionHandoff ||
+        (result.recentEvents && result.recentEvents.length > 0));
+}
+export function toRenderItems(entries) {
+    return entries.map((r) => ({ entry: r.entry, score: r.score, tokens: r.tokens, isGlobal: r.isGlobal ?? false }));
+}
+/** The hook format's stdout, '' when nothing is sent: a skippable static block (snapshot, handoff, events, pins, recent-N) and a never-skipped recall block. */
+export function additionalContextOutput(view) {
+    return renderAdditionalContext(view).stdout;
+}
+function renderAdditionalContext(view) {
+    const { result, rec, framing } = view;
+    const staticEntries = result.entries.filter((r) => r.category !== 'cross-project' && !r.promptRecall);
+    const staticCrossEntries = result.entries.filter((r) => r.category === 'cross-project' && !r.promptRecall);
+    const staticItems = toRenderItems(staticEntries);
+    const recallItems = toRenderItems(result.entries.filter((r) => r.promptRecall));
+    const staticBlock = settleTokens((t) => [
+        ...(result.activeSnapshot ? [snapshotText(result.activeSnapshot)] : []),
+        ...(result.sessionHandoff ? [handoffText(result.sessionHandoff)] : []),
+        ...(result.recentEvents && result.recentEvents.length > 0 ? [sessionTrailText(result.recentEvents)] : []),
+        // No live strength percentage, so an unchanged set of memories renders byte-identically turn after turn.
+        ...(staticItems.length > 0 ? contextBlockLines(staticItems, t, framing, { showStrength: false }) : []),
+        ...crossProjectLines(staticCrossEntries),
+    ].join('\n'));
+    const recallBlock = recallItems.length > 0
+        ? settleTokens((t) => contextBlockLines(recallItems, t, framing, { showStrength: false, heading: 'Prompt-Relevant Memory' }).join('\n'))
+        : '';
+    if (!staticBlock.trim() && !recallBlock.trim()) {
+        rec?.delivered({ state: 'empty' });
+        return NOTHING_RENDERED;
+    }
+    const surface = view.pinnedOnly ? 'hook' : 'context';
+    const sendStatic = staticBlock.trim().length > 0 && !skipUnchangedStatic(view, surface, staticBlock, recallBlock, staticItems.length);
+    const finalStatic = sendStatic ? staticBlock : '';
+    const additionalContext = finalStatic && recallBlock
+        ? `${finalStatic}\n\n${recallBlock}`
+        : finalStatic || recallBlock;
+    const staticReused = !sendStatic && staticBlock.trim().length > 0;
+    if (!additionalContext.trim()) {
+        rec?.delivered({ state: 'reused', staticHash: blockHash(staticBlock), staticReused });
+        return NOTHING_RENDERED;
+    }
+    const stdout = JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'UserPromptSubmit',
+            additionalContext,
+        },
+    });
+    rec?.delivered({
+        state: staticReused ? 'reused-recall-sent' : 'sent',
+        staticHash: staticBlock.trim() ? blockHash(staticBlock) : null,
+        recallHash: recallBlock ? blockHash(recallBlock) : null,
+        emittedText: additionalContext,
+        staticReused,
+    });
+    if (finalStatic || recallBlock) {
+        recordAdditionalContextRows(view, surface, { text: finalStatic, items: staticItems.length }, { text: recallBlock, items: recallItems.length });
+    }
+    return { stdout, staticHash: finalStatic ? blockHash(finalStatic) : null };
+}
+/** True, after booking the skip row, when the hook may omit a static block this session already holds. */
+function skipUnchangedStatic(view, surface, staticBlock, recallBlock, staticCount) {
+    const { hippoRoot, payloadSessionId, rec } = view;
+    const ledgerOpts = { sharedStore: view.sharedStore };
+    if (!view.pinnedOnly || payloadSessionId === undefined)
+        return false;
+    const injectCfg = loadConfig(hippoRoot).pinnedInject;
+    if (injectCfg.skipUnchanged === false)
+        return false;
+    const refreshTurns = Number.isFinite(injectCfg.refreshTurns) && injectCfg.refreshTurns >= 0
+        ? injectCfg.refreshTurns
+        : 10;
+    // Hashed on the static text alone so an unchanged pin set still skips while recall varies.
+    const staticHash = blockHash(staticBlock);
+    // Before the ledger read, so a caller that did not print this block books no skip row.
+    if (view.printedHash !== undefined && view.printedHash !== staticHash)
+        return false;
+    const last = withLedgerDb(hippoRoot, (db) => lastSentState(db, view.tenantId, payloadSessionId, surface), ledgerOpts);
+    if (!shouldSkipUnchanged(last ?? null, staticHash, refreshTurns))
+        return false;
+    withLedgerDb(hippoRoot, (db) => {
+        recordTokenUse(db, {
+            tenantId: view.tenantId, sessionId: payloadSessionId, surface, event: 'skip',
+            items: staticCount, tokens: estimateTokens(staticBlock), hash: staticHash,
+        });
+        if (recallBlock.trim())
+            return;
+        rec?.delivered({ state: 'reused', staticHash, staticReused: true });
+        flushDeliveryRecorder(rec, db);
+    }, ledgerOpts);
+    return true;
+}
+/** One connection for both rows; each insert in its own try so one failing doesn't skip the other. */
+function recordAdditionalContextRows(view, surface, staticPart, recallPart) {
+    withLedgerDb(view.hippoRoot, (db) => {
+        if (staticPart.text) {
+            try {
+                recordTokenUse(db, {
+                    tenantId: view.tenantId, sessionId: view.ledgerSessionId, surface, event: 'inject',
+                    items: staticPart.items, tokens: estimateTokens(staticPart.text), hash: blockHash(staticPart.text),
+                });
+                // Best-effort row: only a busy store is actionable, and a ledger failure must not break the hook.
+            }
+            catch (error) {
+                if (isSqliteBusy(error))
+                    noteStoreBusy('token ledger row skipped');
+            }
+        }
+        if (recallPart.text) {
+            try {
+                recordTokenUse(db, {
+                    tenantId: view.tenantId, sessionId: view.ledgerSessionId, surface: 'hook_recall', event: 'inject',
+                    items: recallPart.items, tokens: estimateTokens(recallPart.text), hash: blockHash(recallPart.text),
+                });
+                // Same best-effort rule as the inject row above.
+            }
+            catch (error) {
+                if (isSqliteBusy(error))
+                    noteStoreBusy('token ledger row skipped');
+            }
+        }
+        flushDeliveryRecorder(view.rec, db);
+    }, { sharedStore: view.sharedStore });
+}
+// The flags HIPPO_PINNED_INJECT_COMMAND gives the local hook; the CLI parity test fails if the two drift.
+const HOOK_INCLUDE_RECENT = 5;
+const HOOK_BUDGET = 1500;
+const HOOK_FRAMING = 'observe';
+// blockHash's shape (token-ledger.ts).
+const BLOCK_HASH_RE = /^[0-9a-f]{16}$/;
+/** The caps on a hook caller's session id and project names, so a caller other than an HTTP route is bounded too. */
+export function assertCallerIds(sessionId, project) {
+    const { name, legacyName, aliases = [] } = project;
+    if (aliases.length > MAX_PROJECT_ALIASES)
+        throw new BadRequestError(`project aliases: at most ${MAX_PROJECT_ALIASES}`);
+    if ([sessionId, name, legacyName, ...aliases].some((v) => v.length > MAX_ID_LEN)) {
+        throw new BadRequestError(`session id and project names: at most ${MAX_ID_LEN} characters each`);
+    }
+}
+function assertPromptHookRequest(req) {
+    assertCallerIds(req.sessionId, req.project);
+    if (req.printedHash !== undefined && !BLOCK_HASH_RE.test(req.printedHash)) {
+        throw new BadRequestError('printed hash: 16 lowercase hex characters');
+    }
+}
+/** The text `hippo context --pinned-only --include-recent 5 --format additional-context` prints for this session, read on `ctx`'s store for the caller's project, leaving out an unchanged static block only when `printedHash` matches it.
+ *  `arm` is the raw ledger arm (`hippo` or `holdout`), null at rate 0; a holdout session gets an empty stdout. `staticHash` is the hash to echo back: null with no static block, for a sub-agent or a holdout.
+ *  Scope detection (HIPPO_SCOPE and skill env vars) and delivery-ledger events are CLI-only.
+ *  Throws BadRequestError past the input caps, and on a shared store for a project assertCallerProject refuses, before any arm is booked. */
+export async function promptHookContext(ctx, req, opts = {}) {
+    assertPromptHookRequest(req);
+    const { sessionId, payload } = req;
+    const { sharedStore } = opts;
+    if (sharedStore || isSharedStore(ctx.hippoRoot))
+        assertCallerProject(req.project);
+    // The test the local hook runs on its stdin, so a sub-agent books no arm and no session rows here either.
+    const subagent = payload !== undefined && isSubagentPayload(JSON.stringify(payload));
+    const ledgerSessionId = subagent ? undefined : sessionId;
+    const arm = sessionPilotArm(ctx.hippoRoot, ctx.tenantId, sessionId, !subagent, { sharedStore, ownTenantOnly: true });
+    if (arm === 'holdout')
+        return { arm, ...NOTHING_RENDERED };
+    const prompt = payload?.prompt;
+    const result = await getContext(ctx, {
+        budget: HOOK_BUDGET,
+        pinnedOnly: true,
+        includeRecent: HOOK_INCLUDE_RECENT,
+        // The project comes from the caller, never from where the store sits or the daemon's cwd.
+        currentProject: req.project,
+        currentSessionId: sessionId,
+        prompt: isJsonString(prompt) ? prompt : undefined,
+        cost: contextCost('additional-context', HOOK_FRAMING),
+        sharedStore,
+    });
+    const rendered = hasContextData(result)
+        ? renderAdditionalContext({
+            hippoRoot: ctx.hippoRoot, tenantId: ctx.tenantId, ledgerSessionId, payloadSessionId: ledgerSessionId,
+            pinnedOnly: true, framing: HOOK_FRAMING, rec: null, result, sharedStore, printedHash: req.printedHash ?? null,
+        })
+        : NOTHING_RENDERED;
+    // A sub-agent's output is not the session's, so its caller must not record it as printed.
+    return { arm, stdout: rendered.stdout, staticHash: subagent ? null : rendered.staticHash };
+}
+//# sourceMappingURL=prompt-hook.js.map

package/dist/prompt-recall.js

@@ -1,6 +1,6 @@
 /** Recall gated on the hook prompt, not the five newest memories (pure, no I/O). */
 import { tokenize } from './tokenize.js';
-import { STOP_WORDS } from './audit.js';
+import { STOP_WORDS } from './memory-quality.js';
 // Latency bound, not tuned: fixed in the prereg regardless of gate config.
 export const PROMPT_RECALL_MAX_CHARS = 4000;
 /** Distinct content tokens: longer than 2 chars, not a stop word. */

package/dist/quality-repair.d.ts

@@ -0,0 +1,27 @@
+/** One automatic row with a defect. `set-aside` moves to dormant storage on apply, `review` is listed only, `protected` is kept. */
+export interface QualityRepairIssue {
+    readonly id: string;
+    readonly reason: string;
+    readonly disposition: 'set-aside' | 'review' | 'protected';
+    readonly protection?: string;
+}
+/** One tenant's plan; `supported` is false, with `blockers` naming each gap, when the schema cannot be changed safely. */
+export interface QualityRepairResult {
+    readonly root: string;
+    readonly schema: number;
+    readonly supported: boolean;
+    readonly blockers: readonly string[];
+    readonly total: number;
+    readonly issues: readonly QualityRepairIssue[];
+    readonly appliedIds: readonly string[];
+    readonly backup: string | null;
+    readonly warnings: readonly string[];
+}
+/** Preview by default; apply backs the database up, then moves certain defects to dormant storage, without running migrations. */
+export declare function repairAutomaticMemories(root: string, opts: {
+    tenantId: string;
+    apply?: boolean;
+}): QualityRepairResult;
+/** Applies the repair once per store, so stores that predate the quality gate are cleaned on upgrade with no command; null once done. */
+export declare function repairQualityOnce(root: string, tenantId: string): QualityRepairResult | null;
+//# sourceMappingURL=quality-repair.d.ts.map

package/dist/quality-repair.js

@@ -0,0 +1,220 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { appendAuditEvent } from './audit.js';
+import { withBackup } from './db/backup.js';
+import { DatabaseSync } from './db/sqlite.js';
+import { getMeta, setMeta } from './db/meta.js';
+import { tableColumns } from './db/tables.js';
+import { assertBinaryCompatible } from './db/migrate.js';
+import { insertDormantRow, listDormantSnapshots } from './dormant.js';
+import { calculateStrength, canAutoDelete } from './memory.js';
+import { assessAutomaticMemory, BUNDLE_HEADER, isAutomaticEntry, isCertainReason } from './memory-quality.js';
+import { heldTexts } from './same-text.js';
+import { deleteEntryCore, MEMORY_BACKED_TABLES, memoriesBackingObjectsOn } from './store/delete-and-batch.js';
+import { selectAllEntries } from './store/entry-reads.js';
+import { MEMORY_SELECT_COLUMNS, parseJsonArray } from './store/rows.js';
+import { purgeMirrorBestEffort } from './store/mirrors.js';
+const REQUIRED_COLUMNS = {
+    memories: MEMORY_SELECT_COLUMNS.split(',').map((s) => s.trim()),
+    meta: ['key', 'value'],
+    dormant_memories: ['tenant_id', 'id', 'content', 'entry_json', 'reason', 'strength', 'dormant_at'],
+    audit_log: ['ts', 'tenant_id', 'actor', 'op', 'target_id', 'metadata_json'],
+    ...Object.fromEntries(MEMORY_BACKED_TABLES.map((table) => [table, ['memory_id']])),
+};
+function capabilityBlockers(db) {
+    const blockers = [];
+    for (const [table, required] of Object.entries(REQUIRED_COLUMNS)) {
+        const columns = tableColumns(db, table);
+        if (columns.size === 0)
+            blockers.push(`missing table: ${table}`);
+        else
+            for (const column of required)
+                if (!columns.has(column))
+                    blockers.push(`missing column: ${table}.${column}`);
+    }
+    if (blockers.some((blocker) => blocker === 'missing table: meta' || blocker.startsWith('missing column: meta.')))
+        return blockers;
+    assertBinaryCompatible(db);
+    if (getMeta(db, 'fts5_available', '0') === '1') {
+        const columns = tableColumns(db, 'memories_fts');
+        for (const column of ['id', 'content', 'tags']) {
+            if (!columns.has(column))
+                blockers.push(`missing column: memories_fts.${column}`);
+        }
+    }
+    return blockers;
+}
+function protection(entry, backing) {
+    if (entry.pinned)
+        return 'pinned';
+    if (entry.kind === 'raw')
+        return 'raw receipt';
+    if (!canAutoDelete(entry))
+        return 'trusted imported note';
+    if (backing.has(entry.id))
+        return 'backs an object';
+    return undefined;
+}
+function structured(entry) {
+    return entry.trace_outcome !== null || entry.tags.includes('session-digest') || entry.source === 'auto-promote';
+}
+/** A parent that is gone says nothing about who wrote it, so it counts as a person's. */
+function fromAutomaticParents(entry, rows) {
+    return entry.parents.length > 0 && entry.parents.every((id) => {
+        const parent = rows.get(id);
+        return parent !== undefined && isAutomaticEntry(parent);
+    });
+}
+function contentIssue(entry, rows) {
+    if (structured(entry) || !isAutomaticEntry(entry))
+        return null;
+    // Only a bundle header marks parts; a refined row keeps its lead line, so it is judged whole.
+    if (!BUNDLE_HEADER.test(entry.content)) {
+        const { reason } = assessAutomaticMemory(entry.content);
+        return reason === null ? null : { reason, disposition: isCertainReason(reason) ? 'set-aside' : 'review' };
+    }
+    const texts = heldTexts({ ...entry, source: 'consolidation' });
+    if (texts.length === 0)
+        return { reason: 'derived bundle has no safely parsed constituents', disposition: 'review' };
+    const reasons = texts.map((text) => assessAutomaticMemory(text).reason).filter((reason) => reason !== null);
+    if (reasons.length === 0)
+        return null;
+    const certain = reasons.length === texts.length && reasons.every(isCertainReason) && fromAutomaticParents(entry, rows);
+    return { reason: `derived constituents: ${[...new Set(reasons)].join('; ')}`, disposition: certain ? 'set-aside' : 'review' };
+}
+function planRows(db, tenantId) {
+    const all = selectAllEntries(db, tenantId);
+    const rows = new Map(listDormantSnapshots(db, tenantId).map((snapshot) => [snapshot.entry.id, snapshot.entry]));
+    for (const entry of all)
+        rows.set(entry.id, entry);
+    const entries = all.filter((entry) => !entry.superseded_by && entry.kind !== 'archived');
+    const backing = memoriesBackingObjectsOn(db);
+    const issues = [];
+    for (const entry of entries) {
+        const issue = contentIssue(entry, rows);
+        if (issue === null)
+            continue;
+        const kept = protection(entry, backing);
+        issues.push(kept === undefined ? { id: entry.id, ...issue } : { id: entry.id, ...issue, disposition: 'protected', protection: kept });
+    }
+    return { total: entries.length, issues };
+}
+function unsupportedPreview(db, tenantId) {
+    const columns = tableColumns(db, 'memories');
+    if (!columns.has('id') || !columns.has('content'))
+        return { total: 0, issues: [] };
+    const tenant = columns.has('tenant_id') ? ' WHERE tenant_id = ?' : '';
+    const column = (name, fallback) => (columns.has(name) ? name : `${fallback} AS ${name}`);
+    const statement = db.prepare(`SELECT id, content, ${column('source', "''")}, ${column('confidence', 'NULL')}, ${column('extracted_from', 'NULL')}, ${column('dag_level', '0')}, ${column('tags_json', "'[]'")} FROM memories${tenant}`);
+    // SAFETY: the SELECT names every Row field, each a literal fallback when its column is missing.
+    const rows = (tenant ? statement.all(tenantId) : statement.all());
+    const issues = rows.flatMap((row) => {
+        const provenance = { ...row, source: row.source ?? '', confidence: row.confidence ?? 'observed', dag_level: row.dag_level ?? 0, tags: parseJsonArray(row.tags_json) };
+        if (!isAutomaticEntry(provenance))
+            return [];
+        const { reason } = assessAutomaticMemory(row.content);
+        return reason === null ? [] : [{ id: row.id, reason, disposition: 'review', protection: 'unsupported schema; no changes permitted' }];
+    });
+    return { total: rows.length, issues };
+}
+function initialResult(db, root, tenantId) {
+    const blockers = capabilityBlockers(db);
+    // SAFETY: PRAGMA user_version returns one row with one integer column.
+    const schema = db.prepare('PRAGMA user_version').get().user_version;
+    const plan = blockers.length > 0 ? unsupportedPreview(db, tenantId) : planRows(db, tenantId);
+    return {
+        root, schema, supported: blockers.length === 0, blockers,
+        total: plan.total,
+        issues: plan.issues, appliedIds: [], backup: null, warnings: [],
+    };
+}
+// No rejection record, as in project repair: the writers refuse these defects themselves, and a record would also refuse a person's copy.
+function setAsideIssue(db, entry, reason, now, backup) {
+    const actor = 'quality-repair';
+    if (deleteEntryCore(db, entry.id, { actor, automatic: true, suppressForgetAudit: true }) === null)
+        return false;
+    insertDormantRow(db, { entry, strength: calculateStrength(entry, now), reason: 'quality-repair', dormantAt: now.toISOString() });
+    if (getMeta(db, 'fts5_available', '0') === '1' && db.prepare('SELECT id FROM memories_fts WHERE id = ?').get(entry.id)) {
+        throw new Error(`Quality repair could not remove the full-text row for ${entry.id}`);
+    }
+    appendAuditEvent(db, { tenantId: entry.tenantId, actor, op: 'quality_repair', targetId: entry.id, metadata: { reason, backup } });
+    return true;
+}
+function applyPlan(db, root, tenantId, backup, doneKey) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const result = initialResult(db, root, tenantId);
+        if (!result.supported)
+            throw new Error(`Quality repair capability changed: ${result.blockers.join('; ')}`);
+        const entries = new Map(selectAllEntries(db, tenantId).map((entry) => [entry.id, entry]));
+        const appliedIds = [];
+        const warnings = [];
+        const now = new Date();
+        for (const issue of result.issues) {
+            if (issue.disposition !== 'set-aside')
+                continue;
+            if (setAsideIssue(db, entries.get(issue.id), issue.reason, now, backup))
+                appliedIds.push(issue.id);
+            else
+                warnings.push(`Kept ${issue.id}: the store's delete guard protects it.`);
+        }
+        if (doneKey)
+            setMeta(db, doneKey, '1');
+        db.exec('COMMIT');
+        return { ...result, appliedIds, backup, warnings };
+    }
+    catch (error) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch { /* preserve the mutation error */ }
+        throw error;
+    }
+}
+function repairOn(db, root, opts) {
+    db.exec('BEGIN');
+    const initial = initialResult(db, root, opts.tenantId);
+    db.exec('ROLLBACK');
+    if (!opts.apply || !initial.supported || !initial.issues.some((issue) => issue.disposition === 'set-aside'))
+        return initial;
+    db.exec('PRAGMA foreign_keys = ON');
+    const result = withBackup(db, root, 'before-quality-repair', (backup) => applyPlan(db, root, opts.tenantId, backup, opts.doneKey));
+    const warnings = [...result.warnings];
+    for (const id of result.appliedIds) {
+        if (!purgeMirrorBestEffort(root, id, false, 'quality repair'))
+            warnings.push(`Mirror cleanup failed for ${id}; remove its stale mirror before rebuilding the index.`);
+    }
+    return { ...result, warnings };
+}
+function openForRepair(root, readOnly, fn) {
+    const file = path.join(root, 'hippo.db');
+    if (!fs.existsSync(file))
+        throw new Error(`No existing Hippo database at ${file}`);
+    const db = new DatabaseSync(file, { readOnly });
+    try {
+        db.exec('PRAGMA busy_timeout = 5000');
+        return fn(db);
+    }
+    finally {
+        db.close();
+    }
+}
+/** Preview by default; apply backs the database up, then moves certain defects to dormant storage, without running migrations. */
+export function repairAutomaticMemories(root, opts) {
+    return openForRepair(root, !opts.apply, (db) => repairOn(db, root, opts));
+}
+const AUTO_REPAIR_META_KEY = 'quality_repair_auto';
+/** Applies the repair once per store, so stores that predate the quality gate are cleaned on upgrade with no command; null once done. */
+export function repairQualityOnce(root, tenantId) {
+    return openForRepair(root, false, (db) => {
+        if (getMeta(db, AUTO_REPAIR_META_KEY) === '1')
+            return null;
+        // The apply commits the flag with the moves, so a lock taken between them cannot hide what moved.
+        const result = repairOn(db, root, { tenantId, apply: true, doneKey: AUTO_REPAIR_META_KEY });
+        // An unsupported schema changed nothing, so the next run tries again once a migration has run.
+        if (result.supported && result.backup === null)
+            setMeta(db, AUTO_REPAIR_META_KEY, '1');
+        return result;
+    });
+}
+//# sourceMappingURL=quality-repair.js.map

package/dist/rate-limit.d.ts

@@ -12,6 +12,7 @@ export interface RateLimiter {
      * for deterministic tests.
      */
     check(key: string, now?: number): boolean;
+    readonly retryAfterSec: number;
 }
 export interface RateLimiterOpts {
     /** Sustained refill rate in tokens per second. */

package/dist/rate-limit.js

@@ -34,10 +34,10 @@ export function createRateLimiter(opts) {
                 bucket = { tokens: burst, last: now };
             }
             else {
-                // Refill for elapsed time, capped at burst.
-                const refill = ((now - existing.last) / 1000) * ratePerSec;
+                // A clock stepped back refills nothing, and keeping the later time stops the step forward again refilling that span twice.
+                const refill = (Math.max(0, now - existing.last) / 1000) * ratePerSec;
                 existing.tokens = Math.min(burst, existing.tokens + refill);
-                existing.last = now;
+                existing.last = Math.max(existing.last, now);
                 bucket = existing;
                 // Drop the old slot so the re-insert below puts the key last in Map
                 // iteration order — Map order then tracks least-recently-used.
@@ -55,6 +55,8 @@ export function createRateLimiter(opts) {
             buckets.set(key, bucket);
             return allowed;
         },
+        // A refused bucket holds under one token and refills at ratePerSec, so one token is back within this.
+        retryAfterSec: Math.max(1, Math.ceil(1 / ratePerSec)),
     };
 }
 //# sourceMappingURL=rate-limit.js.map

package/dist/raw-archive.d.ts

@@ -16,7 +16,7 @@ export interface ArchiveOpts {
  *
  * Snapshots the full row into `raw_archive`, flips `kind` to `'archived'` so the
  * append-only trigger lets the delete through, then deletes the row. All in one
- * SAVEPOINT so it can be nested inside an outer transaction (e.g. batchWriteAndDelete).
+ * write scope, which nests inside an outer transaction (e.g. batchWriteAndDelete).
  *
  * Throws if the row does not exist or is not `kind='raw'`.
  */

package/dist/raw-archive.js

@@ -1,5 +1,5 @@
 import { BadRequestError, NotFoundError } from './api-errors.js';
-import { isFtsAvailable } from './db.js';
+import { isFtsAvailable, withWriteScope } from './db.js';
 import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
 import { markSummaryDirtyInTx } from './summary-dirty.js';
 function loadRawRow(db, id) {
@@ -60,16 +60,15 @@ function auditArchive(db, id, row, opts) {
  *
  * Snapshots the full row into `raw_archive`, flips `kind` to `'archived'` so the
  * append-only trigger lets the delete through, then deletes the row. All in one
- * SAVEPOINT so it can be nested inside an outer transaction (e.g. batchWriteAndDelete).
+ * write scope, which nests inside an outer transaction (e.g. batchWriteAndDelete).
  *
  * Throws if the row does not exist or is not `kind='raw'`.
  */
 export function archiveRawMemory(db, id, opts) {
     const row = loadRawRow(db, id);
-    // SAVEPOINT (not BEGIN) so this works whether or not we're already inside a
-    // transaction. SQLite refuses BEGIN within a transaction; SAVEPOINT nests safely.
-    db.exec('SAVEPOINT archive_raw');
-    try {
+    // A SAVEPOINT when already inside a transaction (e.g. batchWriteAndDelete), so a throw here
+    // rolls back only this archive.
+    withWriteScope(db, 'archive_raw', () => {
         moveRowToArchive(db, id, row, opts);
         auditArchive(db, id, row, opts);
         // Archiving a child under a level-2 summary marks the parent dirty, inside the
@@ -85,15 +84,6 @@ export function archiveRawMemory(db, id, opts) {
         if (opts.afterArchive) {
             opts.afterArchive(db, id);
         }
-        db.exec('RELEASE SAVEPOINT archive_raw');
-    }
-    catch (e) {
-        try {
-            db.exec('ROLLBACK TO SAVEPOINT archive_raw');
-            db.exec('RELEASE SAVEPOINT archive_raw');
-        }
-        catch { /* savepoint already discarded; keep the original error */ }
-        throw e;
-    }
+    });
 }
 //# sourceMappingURL=raw-archive.js.map