hippo-memory 1.70.0 → 1.71.0

package/dist/store/predictions.js

@@ -1,29 +1,9 @@
-/**
- * Prediction first-class object.
- *
- * Canonical store for ex-ante claims that can be closed against ex-post
- * outcomes. The `predictions` table holds every field (including
- * `claim_text`); a memory row mirrors the claim for recall/inspect surfaces
- * but is NOT the source of truth — ON DELETE SET NULL on memory_id means
- * memory deletion gracefully orphans the prediction without losing data.
- *
- * Tenant scoping: every helper requires tenantId. The schema's BEFORE INSERT
- * + BEFORE UPDATE triggers (`trg_predictions_tenant_match_*`) enforce that
- * `predictions.tenant_id` matches the referenced memory's tenant_id when
- * `memory_id IS NOT NULL`. Cross-tenant references are unrepresentable at
- * the schema level.
- *
- * Dual-write atomicity: `savePrediction` writes the memory + predictions
- * row inside `writeEntry`'s SAVEPOINT 'write_entry' (store/entry-writes.ts). The
- * afterWrite hook (store/entry-writes.ts) runs inside the same SAVEPOINT, so
- * a failure in either step rolls back both. Pattern matches supersede
- * (api.ts:1486) and the Slack/GitHub connectors.
- *
- * The planning-fallacy detector reads `loadPredictionsByClass` and computes
- * per-class base rates from (estimate_value, actual_value) at query time.
- */
+/** First-class prediction: an ex-ante claim closed against an outcome. The `predictions` table is the source of truth; the memory row only mirrors the claim.
+ * Every helper requires tenantId; `trg_predictions_tenant_match_*` triggers enforce the prediction's tenant matches the referenced memory's.
+ * `savePrediction` writes memory and prediction inside `writeEntry`'s SAVEPOINT (via afterWrite), so a failure in either rolls back both. */
 import { BadRequestError, NotFoundError } from '../core/api-errors.js';
-import { openHippoDb, closeHippoDb, withWriteScope } from '../db/index.js';
+import { withWriteScope } from '../db/index.js';
+import { onHandle } from './open.js';
 import { writeEntryAt } from './sqlite/entry-writes-group.js';
 import { assertTenantId } from './tenant.js';
 import { createMemory, Layer } from '../core/memory.js';
@@ -31,6 +11,9 @@ import { appendAuditEvent } from './audit.js';
 import { loadConfig } from '../core/config.js';
 import { keysetAfter } from '../util/keyset.js';
 const DEFAULT_PREDICTION_PAGE_SIZE = 100;
+const SELECT_COLUMNS = `id, memory_id, tenant_id, class_tag, claim_text,
+  estimate_value, estimate_unit, target_date,
+  actual_value, closure_state, closed_at, closure_note, created_at`;
 export const VALID_CLOSURE_STATES = new Set([
     'open',
     'closed',
@@ -55,20 +38,8 @@ function rowToPrediction(row) {
         createdAt: row.created_at,
     };
 }
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Create a new prediction. Writes a memory mirror + a predictions table
- * row atomically inside `writeEntry`'s SAVEPOINT 'write_entry'. On any
- * failure (audit write, predictions INSERT, trigger ABORT), the SAVEPOINT
- * rolls back — neither the memory row nor the predictions row lands.
- *
- * The memory is tagged `['prediction', classTag]` with `source='prediction'`
- * and `kind='distilled'`. It surfaces in `hippo recall` so the agent can
- * see open predictions naturally; the predictions table is the canonical
- * structured store used by the planning-fallacy detector.
- */
+/** Create a prediction: memory mirror and predictions row land atomically inside `writeEntry`'s SAVEPOINT; any failure rolls back both.
+ * The memory (tags `['prediction', classTag]`, kind 'distilled') surfaces in `hippo recall`; the predictions table feeds the planning-fallacy detector. */
 export function savePrediction(hippoRoot, tenantId, opts, actor = 'cli') {
     assertTenantId('savePrediction', tenantId);
     if (!opts.classTag)
@@ -91,7 +62,8 @@ export function predictionMirror(tenantId, claim, baseHalfLifeDays) {
         tenantId,
     });
 }
-/** The store port's save on hippo.db: the mirror goes in as the port's writeEntry has it, tenant check included, and its predictions row shares that write scope, so neither lands alone. */
+/** The store port's save on hippo.db: the mirror goes in as the port's writeEntry has it, tenant
+ * check included, and its predictions row shares that write scope, so neither lands alone. */
 export function writePrediction(hippoRoot, tenantId, save, actor) {
     assertTenantId('savePrediction', tenantId);
     const now = new Date().toISOString();
@@ -120,9 +92,7 @@ function insertPredictionRow(db, memoryId, tenantId, opts, stamp) {
     const predictionId = Number(result.lastInsertRowid ?? 0);
     // SAFETY: row's shape matches the columns named in the SELECT above.
     const row = db.prepare(`
-        SELECT id, memory_id, tenant_id, class_tag, claim_text,
-               estimate_value, estimate_unit, target_date,
-               actual_value, closure_state, closed_at, closure_note, created_at
+        SELECT ${SELECT_COLUMNS}
         FROM predictions WHERE id = ?
       `).get(predictionId);
     if (!row) {
@@ -147,25 +117,18 @@ function auditPredictionCreate(db, who, opts) {
         },
     });
 }
-/**
- * Close an existing open prediction. Updates the predictions row only;
- * the memory mirror is NOT mutated in v1 (predictions table is canonical).
- * Accuracy is computed from (estimateValue, actualValue) at query time.
- */
+/** Close an open prediction. Updates the predictions row only; the memory mirror is not mutated (the predictions table is the source of truth).
+ * Accuracy is computed from (estimateValue, actualValue) at query time. */
 export function closePrediction(hippoRoot, tenantId, id, opts, actor = 'cli') {
     assertTenantId('closePrediction', tenantId);
     if (!VALID_CLOSURE_STATES.has(opts.closureState)) {
         throw new BadRequestError(`closePrediction: closureState must be one of ${Array.from(VALID_CLOSURE_STATES).join('|')}; got ${opts.closureState}`);
     }
     const now = new Date().toISOString();
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const row = withWriteScope(db, 'close_prediction', () => closeOpenPredictionRow(db, tenantId, id, opts, { now, actor }));
         return rowToPrediction(row);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 /** Closes the row, reloads it and audits the close; the caller owns the transaction. */
 function closeOpenPredictionRow(db, tenantId, id, opts, stamp) {
@@ -181,9 +144,7 @@ function closeOpenPredictionRow(db, tenantId, id, opts, stamp) {
         throwCloseMiss(db, tenantId, id);
     // SAFETY: row's shape matches the columns named in the SELECT above.
     const row = db.prepare(`
-        SELECT id, memory_id, tenant_id, class_tag, claim_text,
-               estimate_value, estimate_unit, target_date,
-               actual_value, closure_state, closed_at, closure_note, created_at
+        SELECT ${SELECT_COLUMNS}
         FROM predictions WHERE id = ? AND tenant_id = ?
       `).get(id, tenantId);
     if (!row) {
@@ -203,10 +164,8 @@ function closeOpenPredictionRow(db, tenantId, id, opts, stamp) {
     return row;
 }
 function throwCloseMiss(db, tenantId, id) {
-    // Distinguish "not found" from "already closed" so callers (CLI, HTTP)
-    // can surface the right error to the user.
-    // SAFETY: row shape matches the single `closure_state` column named
-    // in the SELECT above.
+    // Distinguish 'not found' from 'already closed' so callers (CLI, HTTP) surface the right error.
+    // SAFETY: row shape matches the single `closure_state` column named in the SELECT above.
     const existing = db.prepare(`
           SELECT closure_state FROM predictions WHERE id = ? AND tenant_id = ?
         `).get(id, tenantId);
@@ -218,27 +177,20 @@ function throwCloseMiss(db, tenantId, id) {
 }
 export function loadPredictionById(hippoRoot, tenantId, id) {
     assertTenantId('loadPredictionById', tenantId);
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: row's shape matches the columns named in the SELECT above.
         const row = db.prepare(`
-      SELECT id, memory_id, tenant_id, class_tag, claim_text,
-             estimate_value, estimate_unit, target_date,
-             actual_value, closure_state, closed_at, closure_note, created_at
+      SELECT ${SELECT_COLUMNS}
       FROM predictions WHERE id = ? AND tenant_id = ?
     `).get(id, tenantId);
         return row ? rowToPrediction(row) : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 export function loadPredictionsByClass(hippoRoot, tenantId, classTag, opts = {}) {
     assertTenantId('loadPredictionsByClass', tenantId);
     const limit = opts.limit ?? DEFAULT_PREDICTION_PAGE_SIZE;
     const after = keysetAfter('created_at', 'id', opts.after);
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         let rows;
         if (opts.closureState) {
             if (!VALID_CLOSURE_STATES.has(opts.closureState)) {
@@ -246,9 +198,7 @@ export function loadPredictionsByClass(hippoRoot, tenantId, classTag, opts = {})
             }
             // SAFETY: rows' shape matches the columns named in the SELECT above.
             rows = db.prepare(`
-        SELECT id, memory_id, tenant_id, class_tag, claim_text,
-               estimate_value, estimate_unit, target_date,
-               actual_value, closure_state, closed_at, closure_note, created_at
+        SELECT ${SELECT_COLUMNS}
         FROM predictions
         WHERE tenant_id = ? AND class_tag = ? AND closure_state = ?${after.sql}
         ORDER BY created_at DESC, id DESC
@@ -258,9 +208,7 @@ export function loadPredictionsByClass(hippoRoot, tenantId, classTag, opts = {})
         else {
             // SAFETY: rows' shape matches the columns named in the SELECT above.
             rows = db.prepare(`
-        SELECT id, memory_id, tenant_id, class_tag, claim_text,
-               estimate_value, estimate_unit, target_date,
-               actual_value, closure_state, closed_at, closure_note, created_at
+        SELECT ${SELECT_COLUMNS}
         FROM predictions
         WHERE tenant_id = ? AND class_tag = ?${after.sql}
         ORDER BY created_at DESC, id DESC
@@ -268,43 +216,26 @@ export function loadPredictionsByClass(hippoRoot, tenantId, classTag, opts = {})
       `).all(tenantId, classTag, ...after.params, limit);
         }
         return rows.map(rowToPrediction);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 /** Every prediction in the tenant, open and closed, across all classes: the `status=all` list without a class. */
 export function loadAllPredictions(hippoRoot, tenantId, opts = {}) {
     assertTenantId('loadAllPredictions', tenantId);
     const after = keysetAfter('created_at', 'id', opts.after);
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: rows' shape matches the columns named in the SELECT.
         const rows = db.prepare(`
-      SELECT id, memory_id, tenant_id, class_tag, claim_text,
-             estimate_value, estimate_unit, target_date,
-             actual_value, closure_state, closed_at, closure_note, created_at
+      SELECT ${SELECT_COLUMNS}
       FROM predictions
       WHERE tenant_id = ?${after.sql}
       ORDER BY created_at DESC, id DESC
       LIMIT ?
     `).all(tenantId, ...after.params, opts.limit ?? DEFAULT_PREDICTION_PAGE_SIZE);
         return rows.map(rowToPrediction);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
-/**
- * Compute base-rate stats for closed predictions in a class for the
- * planning-fallacy detector: Lovallo-Kahneman (2003) inside-vs-outside view.
- *
- * Filter: closure_state='closed' AND estimate_value IS NOT NULL AND
- * actual_value IS NOT NULL. Excludes closed-unknown (no actual to
- * compare against) and open (not yet resolved).
- *
- * Audit-emit is built in here, not at the 3 call sites, so callers cannot drift.
- */
+/** Base-rate stats for closed predictions in a class (Lovallo-Kahneman inside-vs-outside view): closure_state='closed' with estimate and actual non-null;
+ * closed-unknown and open are excluded. Audit-emit is built in here, not at the 3 call sites, so callers cannot drift. */
 export function computePredictionBaserate(hippoRoot, tenantId, classTag, actor = 'cli', 
 /** False skips the predict_baserate audit so that channel only records deliberate
  *  baserate calls, not every recall the planning-fallacy orchestrator inspects. */
@@ -312,8 +243,7 @@ emitAudit = true) {
     assertTenantId('computePredictionBaserate', tenantId);
     if (!classTag)
         throw new BadRequestError('computePredictionBaserate: classTag is required');
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // Ordered by id because the float sums differ with row order, and another store must reach the same figures.
         // SAFETY: rows' shape matches the two columns named in the SELECT above.
         const rows = db.prepare(`
@@ -331,10 +261,7 @@ emitAudit = true) {
         if (emitAudit)
             auditBaserateRead(db, tenantId, actor, classTag, baserate.nClosed);
         return baserate;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 function auditBaserateRead(db, tenantId, actor, classTag, nClosed) {
     appendAuditEvent(db, {
@@ -386,15 +313,12 @@ export function loadOpenPredictions(hippoRoot, tenantId, opts = {}) {
     assertTenantId('loadOpenPredictions', tenantId);
     const limit = opts.limit ?? DEFAULT_PREDICTION_PAGE_SIZE;
     const after = keysetAfter('created_at', 'id', opts.after);
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         let rows;
         if (opts.classTag) {
             // SAFETY: rows' shape matches the columns named in the SELECT above.
             rows = db.prepare(`
-        SELECT id, memory_id, tenant_id, class_tag, claim_text,
-               estimate_value, estimate_unit, target_date,
-               actual_value, closure_state, closed_at, closure_note, created_at
+        SELECT ${SELECT_COLUMNS}
         FROM predictions
         WHERE tenant_id = ? AND class_tag = ? AND closure_state = 'open'${after.sql}
         ORDER BY created_at DESC, id DESC
@@ -404,9 +328,7 @@ export function loadOpenPredictions(hippoRoot, tenantId, opts = {}) {
         else {
             // SAFETY: rows' shape matches the columns named in the SELECT above.
             rows = db.prepare(`
-        SELECT id, memory_id, tenant_id, class_tag, claim_text,
-               estimate_value, estimate_unit, target_date,
-               actual_value, closure_state, closed_at, closure_note, created_at
+        SELECT ${SELECT_COLUMNS}
         FROM predictions
         WHERE tenant_id = ? AND closure_state = 'open'${after.sql}
         ORDER BY created_at DESC, id DESC
@@ -414,9 +336,6 @@ export function loadOpenPredictions(hippoRoot, tenantId, opts = {}) {
       `).all(tenantId, ...after.params, limit);
         }
         return rows.map(rowToPrediction);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 //# sourceMappingURL=predictions.js.map

package/dist/{cli → store}/quality-repair.js

@@ -1,22 +1,19 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { appendAuditEvent } from '../store/audit.js';
+import { appendAuditEvent } from './audit.js';
 import { withBackup } from '../db/backup.js';
 import { withTrialScope, withWriteScope } from '../db/busy.js';
-import { assertSqliteAllowed } from '../db/open.js';
-import { DatabaseSync } from '../db/sqlite.js';
+import { withUnmigratedDb } from '../db/open.js';
 import { getMeta, pragmaUserVersion, setMeta } from '../db/meta.js';
 import { tableColumns } from '../db/tables.js';
 import { assertBinaryCompatible } from '../db/migrate.js';
-import { insertDormantRow, listDormantSnapshots } from '../store/dormant.js';
+import { insertDormantRow, listDormantSnapshots } from './dormant.js';
 import { calculateStrength, canAutoDelete } from '../core/memory.js';
 import { assessAutomaticMemory, BUNDLE_HEADER, isAutomaticEntry, isCertainReason } from '../core/memory-quality.js';
 import { heldTexts } from '../util/same-text.js';
-import { deleteEntryCore, MEMORY_BACKED_TABLES, memoriesBackingObjectsOn } from '../store/delete-and-batch.js';
-import { selectAllEntries, selectPreviewRows } from '../store/entry-reads.js';
-import { ftsRowExists } from '../store/entry-row.js';
-import { MEMORY_SELECT_COLUMNS, parseJsonArray } from '../store/rows.js';
-import { purgeMirrorBestEffort } from '../store/mirrors.js';
+import { deleteEntryCore, MEMORY_BACKED_TABLES, memoriesBackingObjectsOn } from './delete-and-batch.js';
+import { selectAllEntries, selectPreviewRows } from './entry-reads.js';
+import { ftsRowExists } from './entry-row.js';
+import { MEMORY_SELECT_COLUMNS, parseJsonArray } from './rows.js';
+import { purgeMirrorBestEffort } from './mirrors.js';
 const REQUIRED_COLUMNS = {
     memories: MEMORY_SELECT_COLUMNS.split(',').map((s) => s.trim()),
     meta: ['key', 'value'],
@@ -108,7 +105,8 @@ function unsupportedPreview(db, tenantId) {
         return { total: 0, issues: [] };
     const rows = selectPreviewRows(db, columns, tenantId);
     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) };
+        const tags = parseJsonArray(row.tags_json, { table: 'memories', id: row.id, column: 'tags_json' });
+        const provenance = { ...row, source: row.source ?? '', confidence: row.confidence ?? 'observed', dag_level: row.dag_level ?? 0, tags };
         if (!isAutomaticEntry(provenance))
             return [];
         const { reason } = assessAutomaticMemory(row.content);
@@ -168,34 +166,20 @@ function repairOn(db, root, opts) {
     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.`);
+        if (purgeMirrorBestEffort(root, id, false, 'quality repair'))
+            continue;
+        warnings.push(`Mirror cleanup failed for ${id}; remove its stale mirror before rebuilding the index.`);
     }
     return { ...result, warnings };
 }
-function openForRepair(root, readOnly, fn) {
-    // Opens without openHippoDb to skip migrations, so it takes the same refusal itself.
-    assertSqliteAllowed(root);
-    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));
+    return withUnmigratedDb(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) => {
+    return withUnmigratedDb(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.

package/dist/store/raw-archive.d.ts

@@ -2,25 +2,13 @@ import type { DatabaseSyncLike } from '../db/index.js';
 export interface ArchiveOpts {
     reason: string;
     who: string;
-    /**
-     * Optional hook invoked inside the same SAVEPOINT as the archive INSERT/DELETE,
-     * after the audit row is appended and before RELEASE. Used by the Slack
-     * deletion connector to mark the deletion event seen atomically — a crash
-     * mid-archive must not leave the deletion event untracked. Throwing rolls
-     * back the entire archive (including the audit row).
-     */
+    /** Hook run inside the archive SAVEPOINT after the audit row and before RELEASE (the Slack deletion connector marks the event seen atomically);
+     * throwing rolls back the whole archive, audit row included. */
     afterArchive?: (db: DatabaseSyncLike, archivedMemoryId: string) => void;
 }
 /** Stamps the archived copy of `memoryId` as having its markdown mirror cleaned at `at`. */
 export declare function markMirrorCleaned(db: DatabaseSyncLike, memoryId: string, at: string): void;
-/**
- * The only legitimate path to remove a `kind='raw'` row from `memories`.
- *
- * 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
- * write scope, which nests inside an outer transaction (e.g. batchWriteAndDelete).
- *
- * Throws if the row does not exist or is not `kind='raw'`. Returns the archived_at it wrote.
- */
+/** The only way to remove a `kind='raw'` row: snapshots it into `raw_archive`, flips `kind` to 'archived' so the append-only trigger allows the delete,
+ * all in one write scope that nests in an outer transaction. Throws if the row is missing or not raw; returns the archived_at. */
 export declare function archiveRawMemory(db: DatabaseSyncLike, id: string, opts: ArchiveOpts): string;
 //# sourceMappingURL=raw-archive.d.ts.map

package/dist/store/raw-archive.js

@@ -1,3 +1,4 @@
+import { DEFAULT_TENANT_ID } from '../util/env.js';
 import { BadRequestError, NotFoundError } from '../core/api-errors.js';
 import { isFtsAvailable, withWriteScope } from '../db/index.js';
 import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
@@ -7,9 +8,8 @@ export function markMirrorCleaned(db, memoryId, at) {
     db.prepare(`UPDATE raw_archive SET mirror_cleaned_at = ? WHERE memory_id = ?`).run(at, memoryId);
 }
 function loadRawRow(db, id) {
-    // SAFETY: SELECT * FROM memories returns every column of the memories table; only
-    // kind, tenant_id, and dag_parent_id are read below, all guaranteed present (possibly
-    // null) by the memories schema.
+    // SAFETY: SELECT * returns every memories column; only kind, tenant_id and dag_parent_id are read below, all guaranteed present (possibly null) by the
+    // schema.
     const row = db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id);
     if (!row)
         throw new NotFoundError(`memory not found: ${id}`);
@@ -19,15 +19,13 @@ function loadRawRow(db, id) {
     return row;
 }
 function moveRowToArchive(db, id, row, opts) {
-    // GDPR: raw_archive stores ONLY metadata, not the original
-    // memory content. The audit_log row appended below carries op='archive_raw'
-    // for the compliance audit trail. True right-to-be-forgotten — the original
-    // content is unrecoverable from raw_archive after this point.
+    // GDPR: raw_archive stores ONLY metadata, never the original content; the archive_raw audit row is the compliance trail,
+    // so the content is unrecoverable from here on.
     const archivedAt = new Date().toISOString();
     const redactedPayload = JSON.stringify({
         redacted: true,
         archived_at: archivedAt,
-        tenant_id: row.tenant_id ?? 'default',
+        tenant_id: row.tenant_id ?? DEFAULT_TENANT_ID,
         kind: row.kind,
         reason: opts.reason,
     });
@@ -40,15 +38,12 @@ function moveRowToArchive(db, id, row, opts) {
         db.prepare(`DELETE FROM memories_fts WHERE id = ?`).run(id);
     return archivedAt;
 }
-// Emit the archive_raw audit event inside the SAVEPOINT so the audit row is
-// committed atomically with the row deletion. Use the row's own tenant_id
-// (fetched above as part of SELECT *), not the env. Archives must be
-// attributed to the tenant that owns the row, not whatever HIPPO_TENANT
-// happens to be set to in the calling shell.
+// Emit the archive_raw audit inside the SAVEPOINT so it commits atomically with the row deletion, attributed to the row's own tenant_id,
+// not whatever HIPPO_TENANT the calling shell has set.
 function auditArchive(db, id, row, opts) {
     try {
         appendAuditEvent(db, {
-            tenantId: String(row.tenant_id ?? 'default'),
+            tenantId: String(row.tenant_id ?? DEFAULT_TENANT_ID),
             actor: opts.who || 'cli',
             op: 'archive_raw',
             targetId: id,
@@ -60,15 +55,8 @@ function auditArchive(db, id, row, opts) {
         reportAuditWriteFailure('archive_raw', String(error), id);
     }
 }
-/**
- * The only legitimate path to remove a `kind='raw'` row from `memories`.
- *
- * 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
- * write scope, which nests inside an outer transaction (e.g. batchWriteAndDelete).
- *
- * Throws if the row does not exist or is not `kind='raw'`. Returns the archived_at it wrote.
- */
+/** The only way to remove a `kind='raw'` row: snapshots it into `raw_archive`, flips `kind` to 'archived' so the append-only trigger allows the delete,
+ * all in one write scope that nests in an outer transaction. Throws if the row is missing or not raw; returns the archived_at. */
 export function archiveRawMemory(db, id, opts) {
     const row = loadRawRow(db, id);
     // A SAVEPOINT when already inside a transaction (e.g. batchWriteAndDelete), so a throw here
@@ -79,13 +67,10 @@ export function archiveRawMemory(db, id, opts) {
         // Archiving a child under a level-2 summary marks the parent dirty, inside the
         // SAVEPOINT so the dirty-mark commits atomically with the archive.
         if (row.dag_parent_id) {
-            markSummaryDirtyInTx(db, String(row.dag_parent_id), String(row.tenant_id ?? 'default'), opts.who || 'cli');
+            markSummaryDirtyInTx(db, String(row.dag_parent_id), String(row.tenant_id ?? DEFAULT_TENANT_ID), opts.who || 'cli');
         }
-        // afterArchive hook: connector-level idempotency markers
-        // (e.g. slack_event_log) must commit atomically with the archive itself.
-        // Throwing here rolls back the entire SAVEPOINT — both the archive and any
-        // hook side effects. The hook runs INSIDE the SAVEPOINT so its writes
-        // share the archive's transactional fate.
+        // afterArchive hook: connector idempotency markers (e.g. slack_event_log) must commit atomically with the archive, so it runs INSIDE the SAVEPOINT;
+        // throwing rolls back both.
         if (opts.afterArchive) {
             opts.afterArchive(db, id);
         }

package/dist/store/recall-scope.d.ts

@@ -1,48 +1,14 @@
-/**
- * Recall-side scope predicates, in a leaf module so shared.ts (which api.ts
- * imports) can apply the same default-deny rule to searchBothHybrid's internal
- * candidate loads without an import cycle. api.ts imports
- * these for its own call sites AND re-exports them for back-compat
- * (`api.isPrivateScope`, test imports of `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 { ForbiddenError } from '../core/api-errors.js';
-/**
- * Literal scopes excluded from recall by default-deny when the
- * caller passes no `scope`. The SQL clause in `loadSearchRows` and the JS
- * helper `passesScopeFilterForRecall` (src/api/index.ts) both read from this
- * constant. Adding a deny scope is a one-place change.
- *
- * Regex-based denies (e.g. `<source>:private:*`) stay in
- * `passesScopeFilterForRecall` as a separate JS step — they don't translate
- * cleanly to SQL.
- *
- * Invariant: never empty. An empty array would silently allow quarantine
- * scopes through both paths (SQL clause omitted, JS check vacuous). The
- * module-load assertion below pins this loudly.
- */
+/** 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"];
-/**
- * @internal Runtime guard against a future maintainer blanking a
- * load-bearing literal array. Extracted from the inline guard so the throw
- * path is directly testable. `as const` arrays widen via `readonly T[]` at
- * the call site so the empty case is reachable at runtime.
- */
+/** @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 declare function assertNonEmpty<T>(arr: readonly T[], name: string): void;
-/**
- * Source-agnostic private-scope detector. A scope string is treated
- * as private when it has the shape `<lowercase-source>:private:<rest>`.
- *
- * Examples that match:
- *   slack:private:Cabc, github:private:owner/repo, jira:private:PROJ-1
- * Examples that DO NOT match:
- *   slack:public:Cgeneral, acme:public:my-private-channel, null, '',
- *   'unknown:legacy', 'private' (alone), 'private:foo' (no source prefix).
- *
- * Used by api.recall, mcp/server.ts (hippo_recall + hippo_context),
- * cli.ts (cmdRecall + cmdExplain + continuity), shared.ts (searchBothHybrid
- * recall mode). Keep these in sync — the export is the single source of
- * truth 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 declare const PRIVATE_SCOPE_RE: RegExp;
 /** True when `scope` matches the `<source>:private:*` shape. */
 export declare function isPrivateScope(scope: string | null | undefined): boolean;
@@ -62,15 +28,8 @@ export declare function canTouchScope(actor: {
 }, scope: string | null): boolean;
 /** canTouchScope for a caller known by its own personal scope, as a store method receives it. */
 export declare function ownScopeTouches(ownScope: string | null, scope: string | null): boolean;
-/**
- * Recall-side scope filter — the canonical JS half of the recall default-deny
- * rule (the SQL half lives in `loadSearchRows` via `loadRecallSearchEntries`).
- *
- * - When `requested` is set and non-empty: exact match required.
- * - When `requested` is undefined/empty: default-deny on any
- *   `<source>:private:*` scope and on the `RECALL_DEFAULT_DENY_SCOPES`
- *   quarantine buckets. `null` and public scopes pass, and so does `ownScope`, the caller's own personal scope.
- */
+/** 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;
@@ -78,39 +37,19 @@ export interface SqlFragment {
 }
 /** 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. */
+/** 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;
-/**
- * The CLI `--scope` variant of the recall filter (JS half of the
- * SQL 'default-deny-or-exact' mode in loadSearchRows).
- *
- * The CLI flag predates the envelope column as a TAG-boost ranking hint
- * (`scope:<v>` tags, HIPPO_SCOPE, detectScope()), so an explicit `--scope X`
- * UNLOCKS envelope scope X in addition to the default-admitted set — it does
- * NOT narrow the result to X (that would return zero rows for every
- * tag-scoped workflow, whose envelope scope is NULL). api.recall keeps the
- * narrowing 'exact' semantics via `passesScopeFilterForRecall`.
- *
- * Note the unlock applies to whatever scope was explicitly named — including
- * a private scope or a quarantine bucket (`--scope unknown:legacy`). That is
- * deliberate owner access, identical in reach to api.recall's exact-match
- * for the same input; only NON-requested private/quarantine scopes stay
- * denied. A named personal scope never unlocks: the CLI has no caller identity to check it against.
- */
+/** 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;
-/**
- * Thrown when a caller requests a scope its role may not read. The HTTP layer
- * maps it to 403.
- */
+/** Thrown when a caller requests a scope its role may not read; the HTTP layer maps it to 403. */
 export declare class ScopeForbiddenError extends ForbiddenError {
     readonly scope: string;
     constructor(scope: string);
 }
-/**
- * True for scopes that default-deny hides: `<source>:private:*` and the
- * quarantine buckets. Naming one explicitly is what unlocks it, so naming one
- * is the act that needs authorization.
- */
+/** True for scopes default-deny hides (`<source>:private:*` and the quarantine buckets); naming one explicitly unlocks it, so naming one needs
+ * authorization. */
 export declare function isRestrictedScope(scope: string | null | undefined): boolean;
 /** The identity a scope check runs against: a role, any scope grants, and the person who owns the key. */
 export interface ScopeActor {
@@ -118,7 +57,8 @@ export interface ScopeActor {
     scopes?: readonly string[];
     owner?: string;
 }
-/** 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. */
+/** 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. */
 export declare function canReadScope(actor: ScopeActor, scope: string): boolean;
 /** Authorize an explicitly requested scope before any read honours it (member scope grants). */
 export declare function assertScopeRequestAllowed(actor: ScopeActor, requested: string | undefined): void;