hippo-memory 1.69.0 → 1.71.0

package/dist/db/migrations/v33.js

@@ -75,21 +75,8 @@ const TRG_POLICIES_SUPERSEDE_TENANT_MATCH_UPDATE = `
 export const v33 = {
     version: 33,
     up: (db) => {
-        // Policy first-class object.
-        // The "bi-temporal-first" object type: a named rule/statement that is in
-        // force over an EFFECTIVE-TIME range (valid_from required, valid_to nullable
-        // = open-ended) and evolves via the v32 processes supersede machinery
-        // (superseded_by self-FK + supersede tenant-match trigger + version +
-        // change_summary). This table = the v32 processes table MINUS `steps`
-        // (a policy has policy_text, not an ordered step list) PLUS the first-class
-        // effective-time columns valid_from/valid_to. Valid-time is the queryable
-        // axis (the as-of query loadPoliciesAsOf); transaction-time is present via
-        // created_at + the supersede chain's superseded_at (time-travel deferred).
-        //
-        // All date inputs are normalized to standard ISO-8601 datetime
-        // (toISOString) at the store boundary before persist/compare, so the
-        // fixed-width values sort lexically and the half-open [valid_from, valid_to)
-        // as-of comparison is correct.
+        // Policy first-class object: a rule in force over an effective-time range (valid_to nullable = open-ended); supersedes like v32 processes.
+        // Dates are ISO-8601 (toISOString) at the store boundary so values sort lexically and the half-open [valid_from, valid_to) as-of comparison is correct.
         if (!tableExists(db, 'policies')) {
             db.exec(POLICIES_TABLE);
             db.exec(IDX_POLICIES_TENANT_STATUS);

package/dist/db/migrations/v34.js

@@ -69,17 +69,8 @@ const TRG_SKILLS_SUPERSEDE_TENANT_MATCH_UPDATE = `
 export const v34 = {
     version: 34,
     up: (db) => {
-        // Skill first-class object.
-        // A skill is a reusable, agent-followable capability: an `instructions` body
-        // + an optional `trigger_text` (when to apply), evolving via the v32
-        // processes supersede machinery (superseded_by self-FK + supersede
-        // tenant-match trigger + version + change_summary). This table = the v32
-        // processes table MINUS `steps` (a skill's content is a single instructions
-        // body) PLUS `instructions` (NOT NULL) and `trigger_text`. "Executable" is
-        // scoped to an agent-followable instruction that EXPORTS into the agent's
-        // in-force rules (AGENTS.md / CLAUDE.md) via exportSkills; literal code
-        // execution is deferred. NOTE: the column is `trigger_text`, NOT `trigger`,
-        // because TRIGGER is a SQLite reserved keyword.
+        // Skill first-class object: `instructions` plus optional `trigger_text`, superseding like v32 processes; exportSkills writes it to AGENTS.md / CLAUDE.md.
+        // The column is `trigger_text`, not `trigger`, because TRIGGER is a SQLite reserved keyword.
         if (!tableExists(db, 'skills')) {
             db.exec(SKILLS_TABLE);
             db.exec(IDX_SKILLS_TENANT_STATUS);

package/dist/db/migrations/v35.js

@@ -72,17 +72,8 @@ const TRG_PROJECT_BRIEFS_SUPERSEDE_TENANT_MATCH_UPDATE = `
 export const v35 = {
     version: 35,
     up: (db) => {
-        // project_brief first-class object. A project_brief is the
-        // living, repo-scoped summary of a repository's state: a `summary` body
-        // scoped to a `repo`, evolving via the v34 skills supersede machinery
-        // (superseded_by self-FK + supersede tenant-match trigger + version +
-        // change_summary). This table = the v34 skills table with
-        // skill_name/trigger_text replaced by `repo` (the repo-scoping dimension)
-        // PLUS `summary` (the brief body). The distinguishing op (refreshBrief, in
-        // src/project-briefs.ts) auto-assembles the summary from the repo's receipts
-        // (memory rows tagged path:<repo>); it needs no schema support beyond `repo`.
-        // All column names were checked against SQLite reserved words:
-        // repo/summary/version/status/etc. are non-reserved.
+        // project_brief first-class object: repo-scoped `summary` superseding like v34 skills; refreshBrief (objects/project-briefs.ts) builds it from receipts.
+        // The schema needs only `repo`; column names were checked against SQLite reserved words.
         if (!tableExists(db, 'project_briefs')) {
             db.exec(PROJECT_BRIEFS_TABLE);
             db.exec(IDX_PROJECT_BRIEFS_TENANT_STATUS);

package/dist/db/migrations/v36.js

@@ -72,17 +72,8 @@ const TRG_CUSTOMER_NOTES_SUPERSEDE_TENANT_MATCH_UPDATE = `
 export const v36 = {
     version: 36,
     up: (db) => {
-        // customer_note first-class object. A customer_note is a
-        // discrete note recorded against an account/customer entity, evolving via the
-        // v35 project_briefs supersede machinery (superseded_by self-FK + supersede
-        // tenant-match trigger + version + change_summary). This table = the v35
-        // project_briefs table with repo/summary replaced by `customer` (the
-        // entity-scoping dimension; a free-form account/customer id - the entities
-        // table is unbuilt, so a FK is deferred) PLUS `note` (the note body).
-        // MANY notes per customer (each its own supersede chain), unlike the
-        // one-summary-per-repo project_brief. All column names checked against SQLite
-        // reserved words: customer/note/
-        // version/status/etc. are non-reserved.
+        // customer_note first-class object: a note on a customer, superseding like v35 project_briefs; `customer` is a free-form id (no FK: no entities table).
+        // Many notes per customer, each its own supersede chain. Column names were checked against SQLite reserved words.
         if (!tableExists(db, 'customer_notes')) {
             db.exec(CUSTOMER_NOTES_TABLE);
             db.exec(IDX_CUSTOMER_NOTES_TENANT_STATUS);

package/dist/db/migrations/v37.js

@@ -41,9 +41,8 @@ const GRAPH_EXTRACTION_QUEUE_TABLE = `
             FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE
           )
         `;
-// entities guard: source_kind must equal the FK'd memory's actual kind (so a
-// raw memory or a lying source_kind both ABORT), and tenant must match. Both
-// INSERT and UPDATE (UPDATE fires when memory_id/source_kind/tenant_id change).
+// entities guard: source_kind must equal the FK'd memory's actual kind (raw or a lying source_kind ABORTs) and tenant must match,
+// on INSERT and on UPDATE (when memory_id/source_kind/tenant_id change).
 const TRG_ENTITIES_CONSOLIDATED_ONLY_INSERT = `
           CREATE TRIGGER IF NOT EXISTS trg_entities_consolidated_only_insert
           BEFORE INSERT ON entities
@@ -139,16 +138,8 @@ const TRG_GRAPH_QUEUE_CONSOLIDATED_ONLY_UPDATE = `
             END;
           END
         `;
-// Reverse guard: the graph-table triggers
-// only fire on writes to the GRAPH tables. They do NOT fire when an
-// already-indexed memory is later mutated. So 'UPDATE memories SET kind=raw'
-// (or a tenant change) on a memory the graph references would silently leave
-// entity/relation/queue rows pointing at a raw / cross-tenant memory while
-// their source_kind stays 'distilled' - bypassing the central 'graph never
-// indexes raw' invariant after insertion. This trigger closes that direction:
-// a memory cannot be reclassified to raw, nor moved cross-tenant, WHILE the
-// graph references it (rebuild/remove the graph rows first). Cheap: the EXISTS
-// checks are only evaluated when kind actually becomes raw or tenant changes.
+// Reverse guard: graph triggers fire only on graph-table writes, so reclassifying an indexed memory to raw (or tenant) would break the no-raw invariant.
+// Block both while the graph references the memory; the EXISTS checks run only when kind becomes raw or tenant changes.
 const TRG_MEMORIES_GRAPH_REFERENCED_GUARD = `
           CREATE TRIGGER IF NOT EXISTS trg_memories_graph_referenced_guard
           BEFORE UPDATE ON memories
@@ -162,13 +153,8 @@ const TRG_MEMORIES_GRAPH_REFERENCED_GUARD = `
             SELECT RAISE(ABORT, 'cannot change the kind or tenant of a memory while the graph references it (E3.3 graph-on-consolidated guard); a graph-referenced memory is immutable in kind/tenant - rebuild/remove the graph rows first, or rebuild them after supersession');
           END
         `;
-// Second reverse guard: an entity that is
-// a relation endpoint cannot be moved cross-tenant. The entity UPDATE trigger
-// validates the entity against its source memory, but an existing relation
-// pointing at the entity is NOT re-validated, so a raw 'UPDATE entities SET
-// tenant_id=?, memory_id=?' to another tenant would leave a tenant-A relation
-// pointing at a tenant-B entity. Block the tenant move while the entity is
-// referenced by any relation (rebuild the relations first).
+// Second reverse guard: the entity UPDATE trigger does not re-validate existing relations, so a cross-tenant entity move would leave a tenant-A relation
+// pointing at a tenant-B entity. Block the tenant move while any relation references the entity.
 const TRG_ENTITIES_NO_TENANT_MOVE_WHEN_REFERENCED = `
           CREATE TRIGGER IF NOT EXISTS trg_entities_no_tenant_move_when_referenced
           BEFORE UPDATE ON entities
@@ -181,19 +167,8 @@ const TRG_ENTITIES_NO_TENANT_MOVE_WHEN_REFERENCED = `
 export const v37 = {
     version: 37,
     up: (db) => {
-        // Graph-on-consolidated guard.
-        // The graph layer (entities + relations) sits ON TOP OF consolidated state and
-        // must NEVER index the raw layer. The substrate: entities + relations +
-        // graph_extraction_queue, each FK-ing to memories and guarded so they can only
-        // reference CONSOLIDATED memories (kind IN ('distilled','superseded')), never
-        // kind='raw'. New tables -> real CHECK constraints (unlike the ALTER'd memories,
-        // whose kind CHECK lives in triggers). The kind/source MATCH (source_kind ==
-        // the FK'd memory's actual kind) cannot be a CHECK (CHECK can't subquery), so it
-        // is a BEFORE INSERT *and* BEFORE UPDATE trigger (the subquery-capable pattern
-        // from the v30 decisions / predictions tenant-match triggers). Both INSERT and
-        // UPDATE are guarded: an INSERT-only guard is bypassable via a raw SQL UPDATE
-        // that moves a row onto a raw memory. All column
-        // names checked vs SQL reserved words: rel_type avoids REFERENCES.
+        // Graph-on-consolidated guard: entities, relations and graph_extraction_queue may reference only consolidated memories (distilled|superseded), never raw.
+        // The kind match needs a subquery, so it is a BEFORE INSERT and UPDATE trigger (INSERT-only is bypassable). rel_type avoids the reserved word REFERENCES.
         if (!tableExists(db, 'entities')) {
             db.exec(ENTITIES_TABLE);
             db.exec(`CREATE INDEX IF NOT EXISTS idx_entities_tenant ON entities(tenant_id)`);

package/dist/db/migrations/v38.js

@@ -33,12 +33,8 @@ const RELATIONS_TABLE = `
           FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE SET NULL
         )
       `;
-// entities guard (dual-provenance): at least one valid provenance, no raw.
-//  - all-null  -> ABORT.
-//  - memory path (memory_id NOT NULL): source_kind == the FK'd memory's kind
-//    (raw / lying source_kind ABORT) AND tenant-match.
-//  - object path (memory_id NULL): the (type,id) points at an EXISTING same-tenant
-//    object row whose status is active|superseded (explicit 4-way CASE per table).
+// entities guard (dual-provenance): at least one valid provenance, no raw. Memory path: source_kind must equal the FK'd memory's kind, plus tenant-match.
+// Object path (memory_id NULL): (type,id) must point at an existing same-tenant object with status active|superseded (4-way CASE per table); all-null aborts.
 const TRG_ENTITIES_CONSOLIDATED_ONLY_INSERT = `
         CREATE TRIGGER IF NOT EXISTS trg_entities_consolidated_only_insert
         BEFORE INSERT ON entities
@@ -201,10 +197,7 @@ const TRG_RELATIONS_CONSOLIDATED_ONLY_UPDATE = `
           END;
         END
       `;
-// Recreated VERBATIM from v37 (logic unchanged): an entity that is a relation
-// endpoint cannot be moved cross-tenant while referenced. trg_memories_graph_referenced_guard
-// (on memories) and trg_graph_queue_* (on graph_extraction_queue) are NOT recreated
-// here: those tables are not dropped by v38, so the triggers survive.
+// Recreated verbatim from v37 (relation endpoints cannot move cross-tenant). The memories and graph queue triggers survive: those tables are not dropped.
 const TRG_ENTITIES_NO_TENANT_MOVE_WHEN_REFERENCED = `
         CREATE TRIGGER IF NOT EXISTS trg_entities_no_tenant_move_when_referenced
         BEFORE UPDATE ON entities
@@ -217,34 +210,8 @@ const TRG_ENTITIES_NO_TENANT_MOVE_WHEN_REFERENCED = `
 export const v38 = {
     version: 38,
     up: (db) => {
-        // Object provenance: anchor graph entity/relation provenance to the authoritative
-        // first-class object (decision/policy/customer-note/project-brief) instead of the
-        // decaying memory mirror. An in-force object must STAY in the graph after its mirror memory is forgotten or
-        // consolidation-pruned. The graph is a PURE DERIVED CACHE (clearGraph + rebuild on
-        // every `graph extract` / `sleep`), so v38 DROPs+recreates entities/relations (no
-        // data copy) and the next extract repopulates. graph_extraction_queue is untouched.
-        //
-        // Two provenance paths, "at least one, no raw":
-        //  - memory path (memory_id NOT NULL): source_kind must equal the FK'd memory's live
-        //    kind and that kind is distilled|superseded (raw still ABORTs) + tenant-match.
-        //  - object path (memory_id NULL): source_object_type/id must reference an EXISTING
-        //    same-tenant object row whose status is active|superseded (not closed). Such objects
-        //    are consolidated BY CONSTRUCTION, so the no-raw invariant still holds.
-        //  - all-null is rejected.
-        //
-        // memory_id is now NULLABLE with ON DELETE SET NULL (was NOT NULL / CASCADE), so a
-        // mirror forget/consolidate nulls the recall pointer without dropping the row. NOTE
-        // (empirically verified, contradicts the SQLite docs): node:sqlite DOES fire the
-        // BEFORE UPDATE guard from the FK SET NULL action even with recursive_triggers OFF.
-        // So the *_consolidated_only_UPDATE triggers deliberately OMIT the all-null ABORT
-        // (kept on INSERT) - otherwise a mirror delete of a memory-only row would be blocked.
-        // See the per-trigger comments below. A SET NULL leaves source_kind at its old value
-        // by design (the object path is distilled-by-construction; source_kind is only
-        // re-checked when memory_id NOT NULL).
-        // source_object_id is a SOFT (type,id) pointer (no hard FK) the rebuild re-validates,
-        // so a legitimate object hard-delete is never blocked; a `closed` object row drops at next
-        // extract. SQLite cannot parametrize a table name in a trigger, so the object-path
-        // validation is an explicit 4-way CASE (one arm per object table).
+        // Anchor graph provenance to the authoritative object, not the decaying mirror memory; the graph is a derived cache, so entities/relations are recreated.
+        // memory_id is NULLABLE ON DELETE SET NULL; node:sqlite fires the BEFORE UPDATE guard on that SET NULL, so the UPDATE triggers omit the all-null ABORT.
         recreateGraphTables(db);
         createGraphGuards(db);
     },

package/dist/db/migrations/v39.js

@@ -1,30 +1,22 @@
 import * as os from 'os';
 import * as path from 'path';
-import { deriveOriginProject, originFromSource, isGlobalStoreRoot } from '../../project-identity.js';
+import { deriveOriginProject, originFromSource, isGlobalStoreRoot } from '../../core/project-identity.js';
 import { raiseMinBinary } from '../meta.js';
 import { tableHasColumn } from '../tables.js';
 export const v39 = {
     version: 39,
     up: (db, ctx) => {
-        // Memory scope isolation.
-        // origin_project: '<name>' = owned by that project, '' = user-global,
+        // Memory scope isolation. origin_project: '<name>' = owned by that project, '' = user-global,
         // NULL = legacy/unknown (ambient context treats NULL as deny).
         if (!tableHasColumn(db, 'memories', 'origin_project')) {
             db.exec(`ALTER TABLE memories ADD COLUMN origin_project TEXT`);
         }
-        // Backfill on store-location evidence only (no path-tag guessing):
-        // 1. Rows shared from a project carry source 'shared:<project>:<ts>' -
-        //    take <project>; a share whose <project> is the home dir basename
-        //    maps to '' (user-global).
-        // 2. Every other row was written into THIS store, so it takes the
-        //    store's own origin: `<project>/.hippo` -> '<project>', the
-        //    home/global store -> '' (user-global).
-        // Rows stay NULL only when no hippoRoot was provided.
+        // Backfill from store location only (no path-tag guessing): 'shared:<project>:<ts>' rows take <project> (home-dir basename maps to '' user-global);
+        // every other row takes this store's origin (`<project>/.hippo` -> '<project>', global store -> ''). Rows stay NULL only when no hippoRoot was provided.
         const hippoRoot = ctx?.hippoRoot;
         if (hippoRoot) {
-            // Provenance-source evidence first (shared:<project>: / promoted:<localRoot>,
-            // parsed by the same helper the markdown-import stamp uses), then the
-            // store's own location for everything else.
+            // Provenance-source evidence first (shared:<project>: / promoted:<localRoot>, parsed by the markdown-import stamp's helper),
+            // then the store's own location for everything else.
             const homeName = path.basename(os.homedir()).toLowerCase();
             // SAFETY: sourcedRows' shape matches the two columns (id, source)
             // named in the SELECT above.
@@ -36,18 +28,15 @@ export const v39 = {
                     continue;
                 setOrigin.run(origin, row.id);
             }
-            // The global root itself is ALWAYS user-global (''), regardless of
-            // what surrounds it on disk - a HIPPO_HOME inside a dotfiles git
-            // repo must not stamp the whole corpus with that repo's name.
+            // The global root itself is always user-global (''), whatever surrounds it on disk: a HIPPO_HOME inside a dotfiles git repo
+            // must not stamp the whole corpus with that repo's name.
             const storeOrigin = isGlobalStoreRoot(hippoRoot)
                 ? ''
                 : deriveOriginProject(path.dirname(hippoRoot));
             db.prepare(`UPDATE memories SET origin_project = ? WHERE origin_project IS NULL`).run(storeOrigin);
         }
-        // Rollback-safety guard (v24 precedent): a pre-isolation binary opening
-        // this DB would ignore origin_project and the secret veto and resume
-        // injecting cross-project rows. 1.24.0 is the first version with the
-        // isolation behavior. Forward-only - never lower an existing minimum.
+        // Rollback-safety guard: a pre-isolation binary would ignore origin_project and the secret veto and resume injecting cross-project rows.
+        // 1.24.0 is the first version with isolation; forward-only, never lower an existing minimum.
         raiseMinBinary(db, '1.24.0');
     },
 };

package/dist/db/migrations/v40.js

@@ -1,16 +1,4 @@
-export const v40 = {
-    version: 40,
-    up: (db) => {
-        // Retrieval-trace persistence.
-        // Follows the v18 goal_recall_log style: one parent trace row per
-        // recall, a WITHOUT ROWID child table for the ranked results, and a
-        // separate append-only outcomes table so audit_log pruning can never
-        // erase training data.
-        //
-        // No min_compatible_binary bump, on purpose: an old binary ignores these tables and
-        // recordTraceOutcome re-validates trace ids, so its stale writes are skipped; a bump
-        // would lock old binaries out of the whole store for an observability feature.
-        db.exec(`
+const RECALL_TRACES_SCHEMA_SQL = `
         CREATE TABLE IF NOT EXISTS recall_traces (
           id INTEGER PRIMARY KEY AUTOINCREMENT,
           ts TEXT NOT NULL,
@@ -56,7 +44,13 @@ export const v40 = {
           memory_ids_json TEXT NOT NULL      -- ids actually credited by this outcome event
         );
         CREATE INDEX IF NOT EXISTS idx_recall_trace_outcomes_trace ON recall_trace_outcomes(trace_id);
-      `);
+      `;
+export const v40 = {
+    version: 40,
+    up: (db) => {
+        // Retrieval-trace persistence: one trace row per recall, a WITHOUT ROWID results table, append-only outcomes (audit_log pruning must not erase them).
+        // No min_compatible_binary bump on purpose: old binaries ignore these tables and recordTraceOutcome re-validates trace ids; a bump would lock them out.
+        db.exec(RECALL_TRACES_SCHEMA_SQL);
     },
 };
 //# sourceMappingURL=v40.js.map

package/dist/db/migrations/v41.js

@@ -1,30 +1,8 @@
 export const v41 = {
     version: 41,
     up: (db) => {
-        // Rejected-value tombstone.
-        // Additive table, template = v40 above. A human who rejects a fact gets
-        // a durable say: the write-path guard in upsertEntryRow refuses any
-        // write that would re-introduce a value whose normalized digest
-        // matches a row here.
-        //
-        // No raw content and no preview stored. Follows the raw_archive
-        // redaction precedent (raw-archive.ts payload is {redacted:true, ...}):
-        // a rejected value may itself be a secret or PII ("never store my key
-        // again") — persisting it in the tombstone would defeat the point. The
-        // human sees the content at reject time (CLI echoes it); afterwards
-        // `reason` is the human-readable identity.
-        //
-        // No FK on source_memory_id (v40 precedent above: tombstone outlives
-        // the row it was sourced from) — provenance only.
-        //
-        // Reserved-word check on column names:
-        // tenant/digest/reason/rejected/source/normalized/chars are non-reserved.
-        //
-        // No min_compatible_binary bump, a deliberate tradeoff: an old binary sharing a synced store
-        // writes WITHOUT the guard until upgraded; documented in
-        // MEMORY_ENVELOPE.md rather than hard-locking every old binary out of
-        // the store, which is disproportionate for the dominant single-user
-        // single-binary deployment.
+        // Rejected-value tombstone: upsertEntryRow refuses writes matching a row's digest. No raw content stored (may be secret); no FK: it outlives its row.
+        // No min_compatible_binary bump, a deliberate tradeoff: an old binary writes without the guard until upgraded (see MEMORY_ENVELOPE.md).
         db.exec(`
         CREATE TABLE IF NOT EXISTS rejected_values (
           tenant_id  TEXT NOT NULL,

package/dist/db/migrations/v43.js

@@ -1,8 +1,4 @@
-export const v43 = {
-    version: 43,
-    up: (db) => {
-        // W2a work-queue cards (trajectories/01M2D5VSYJFK4YXQ0RG2NGCPYJ/plan.md). Additive only, v41 precedent.
-        db.exec(`
+const CARDS_SCHEMA_SQL = `
         CREATE TABLE IF NOT EXISTS cards (
           id TEXT PRIMARY KEY,
           title TEXT NOT NULL,
@@ -61,7 +57,12 @@ export const v43 = {
 
         CREATE INDEX IF NOT EXISTS idx_session_handoffs_tenant_card
           ON session_handoffs(tenant_id, card_id, created_at DESC);
-      `);
+      `;
+export const v43 = {
+    version: 43,
+    up: (db) => {
+        // W2a work-queue cards. Additive only, v41 precedent.
+        db.exec(CARDS_SCHEMA_SQL);
     },
 };
 //# sourceMappingURL=v43.js.map

package/dist/db/migrations/v44.js

@@ -1,14 +1,8 @@
 export const v44 = {
     version: 44,
     up: (db) => {
-        // Dormant memories (src/dormant.ts): with `dormant.enabled`, the sleep
-        // decay pass moves a faded memory here instead of deleting it. The row
-        // leaves `memories` in the same transaction, so recall, context and
-        // every sleep pass stop seeing it; entry_json is the full MemoryEntry
-        // snapshot `hippo dormant restore` writes back. No FK to memories (the
-        // memories row is gone by design). Additive only, v41 precedent: no
-        // min_compatible_binary bump. An older binary ignores the table and
-        // keeps deleting faded memories as it always did.
+        // Dormant memories (src/store/dormant.ts): with `dormant.enabled`, sleep moves a faded memory here; `hippo dormant restore` writes entry_json back.
+        // No FK to memories (the row is gone by design). Additive only: no min_compatible_binary bump, an older binary ignores the table and keeps deleting.
         db.exec(`
         CREATE TABLE IF NOT EXISTS dormant_memories (
           tenant_id  TEXT NOT NULL DEFAULT 'default',

package/dist/db/migrations/v45.js

@@ -1,13 +1,8 @@
 export const v45 = {
     version: 45,
     up: (db) => {
-        // Token ledger (src/token-ledger.ts): one row per block of
-        // memory text hippo hands an agent (hook, CLI, MCP, HTTP). `event` is 'inject'
-        // (sent), 'skip' (unchanged since the session's last inject, not sent), 'reset'
-        // (compaction dropped earlier injections, so the next one must be sent) or
-        // 'reread' (re-read by later calls, booked at session end per call day). block_hash
-        // lets the per-prompt hook skip an unchanged block. Rows older than the retention
-        // window are pruned on write. Additive only: no min_compatible_binary bump.
+        // Token ledger (src/store/token-ledger.ts): one row per block of memory text handed to an agent; `event` is inject, skip, reset (compaction) or reread.
+        // block_hash lets the per-prompt hook skip an unchanged block; rows past retention are pruned on write. Additive: no min_compatible_binary bump.
         db.exec(`
         CREATE TABLE IF NOT EXISTS token_ledger (
           id         INTEGER PRIMARY KEY AUTOINCREMENT,

package/dist/db/migrations/v46.js

@@ -1,7 +1,7 @@
 export const v46 = {
     version: 46,
     up: (db) => {
-        // Failure log (src/failure-log.ts): hashes only, since failure text can carry paths and secrets.
+        // Failure log (src/store/failure-log.ts): hashes only, since failure text can carry paths and secrets.
         // Additive only: no min_compatible_binary bump.
         db.exec(`
         CREATE TABLE IF NOT EXISTS failure_log (

package/dist/db/migrations/v47.js

@@ -1,9 +1,8 @@
 export const v47 = {
     version: 47,
     up: (db) => {
-        // Scope grants (src/auth.ts): a member key reads a
-        // restricted scope only by an explicit row here. Additive only: no
-        // min_compatible_binary bump.
+        // Scope grants (src/store/auth.ts): a member key reads a restricted scope only by an explicit row here.
+        // Additive only: no min_compatible_binary bump.
         db.exec(`
         CREATE TABLE IF NOT EXISTS api_key_scope_grants (
           key_id     TEXT NOT NULL,

package/dist/db/migrations/v48.js

@@ -2,7 +2,7 @@ import { MEMORY_QUARANTINE_DDL } from '../continuity.js';
 export const v48 = {
     version: 48,
     up: (db) => {
-        // Quarantine (src/quarantine.ts): a poisoned or suspect memory sits here pending
+        // Quarantine (src/trust/quarantine.ts): a poisoned or suspect memory sits here pending
         // admin review instead of being hidden with no record. Additive only: no min_compatible_binary bump.
         db.exec(MEMORY_QUARANTINE_DDL);
     },

package/dist/db/migrations/v49.js

@@ -1,7 +1,7 @@
 export const v49 = {
     version: 49,
     up: (db) => {
-        // Compaction record (src/compaction-record.ts): one row per Claude Code compaction, written before it (started)
+        // Compaction record (src/capture/compaction-record.ts): one row per Claude Code compaction, written before it (started)
         // and after it (summarised, done). Not a memory row. Additive only: no min_compatible_binary bump.
         db.exec(`
         CREATE TABLE IF NOT EXISTS compactions (

package/dist/db/migrations/v50.js

@@ -1,9 +1,4 @@
-export const v50 = {
-    version: 50,
-    up: (db) => {
-        // Per-turn delivery events (src/recall-trace.ts). Additive only: no min_compatible_binary bump; rollback drops both tables
-        // and sets schema_version back to 49. No CHECK on enum columns since SQLite cannot alter one; delivery-recorder.ts unions are the allowlist.
-        db.exec(`
+const DELIVERY_EVENTS_SCHEMA_SQL = `
         CREATE TABLE IF NOT EXISTS delivery_events (
           id                INTEGER PRIMARY KEY AUTOINCREMENT,
           ts                TEXT NOT NULL,
@@ -61,7 +56,13 @@ export const v50 = {
           tokens       INTEGER,
           PRIMARY KEY (event_id, memory_id)
         ) WITHOUT ROWID;
-      `);
+      `;
+export const v50 = {
+    version: 50,
+    up: (db) => {
+        // Per-turn delivery events (src/store/recall-trace.ts). Additive only: no min_compatible_binary bump; rollback drops both tables
+        // and sets schema_version back to 49. No CHECK on enum columns since SQLite cannot alter one; delivery-recorder.ts unions are the allowlist.
+        db.exec(DELIVERY_EVENTS_SCHEMA_SQL);
     },
 };
 //# sourceMappingURL=v50.js.map

package/dist/db/migrations/v51.js

@@ -1,7 +1,7 @@
 export const v51 = {
     version: 51,
     up: (db) => {
-        // Both indexes serve loadAmbientCandidates (src/store.ts); their WHERE text must match its SQL for the planner to pick them.
+        // Both indexes serve loadAmbientCandidates (src/store/candidates.ts); their WHERE text must match its SQL for the planner to pick them.
         // The drift index stays empty on a healthy store, so the drift probe is one index seek instead of a tenant scan. Additive only.
         db.exec(`
         CREATE INDEX IF NOT EXISTS idx_memories_pinned

package/dist/db/migrations/v52.js

@@ -1,4 +1,4 @@
-import { MEMORY_VECTORS_DDL } from '../../vector-store.js';
+import { MEMORY_VECTORS_DDL } from '../vector-store.js';
 export const v52 = {
     version: 52,
     // Vectors move out of embeddings.json so hybrid search reads only the rows it ranks. Additive only; the JSON import runs after COMMIT.

package/dist/db/open.d.ts

@@ -1,5 +1,5 @@
 import { type DatabaseSyncLike } from './sqlite.js';
-import { getHippoDbPath } from './connect.js';
+import { getHippoDbPath, type OpenedDb } from './connect.js';
 export { getHippoDbPath };
 /** Lock wait for hook commands: under the 5 s prompt-hook budget even after a few skipped writes, and far above a normal write's hold. */
 export declare const HOOK_DB_WAIT_MS = 1000;
@@ -20,6 +20,10 @@ export declare function scopedBusyWait(): number | undefined;
 export declare function withSqliteBlocked<T>(storeKind: string, fn: () => T): T;
 /** Runs `fn` with hippo.db opens allowed again, for a store whose own methods are backed by hippo.db, or a copy that reads the old hippo.db. */
 export declare function withSqliteAllowed<T>(fn: () => T): T;
+/** Runs `fn` so that a hippo.db open on this thread throws, across awaits; a block of another store, when one is open, already refuses and stays as it is. */
+export declare function withSqliteOffLoop<T>(fn: () => T): T;
+/** Leaves withSqliteOffLoop's block and nothing else: another store's block and the folder marker still refuse, which withSqliteAllowed would waive. */
+export declare function outsideSqliteOffLoop<T>(fn: () => T): T;
 /** First line of a best-effort catch around a hippo.db open: an unported path must fail closed, not fall back silently. */
 export declare function rethrowIfSqliteBlocked<E>(err: E): void;
 /** store init --db, store copy --db and serve --db write this file in the hippo root; its text is the store kind. */
@@ -30,7 +34,13 @@ export declare function assertSqliteAllowed(hippoRoot: string): void;
 export declare function openHippoDb(hippoRoot: string, opts?: {
     busyWaitMs?: number;
 }): DatabaseSyncLike;
+/** openHippoDb, with what the open's probe read when this call made the connection. */
+export declare function openHippoDbWithFacts(hippoRoot: string, opts?: {
+    busyWaitMs?: number;
+}): OpenedDb;
 /** Open an existing store without changing it: no mkdir, WAL switch, migration or mirror cleanup. Throws when hippo.db is missing. */
 export declare function openHippoDbReadOnly(hippoRoot: string): DatabaseSyncLike;
+/** Runs `fn` on an existing hippo.db opened without migrations, for a repair of a store whose schema is behind; closes it after. */
+export declare function withUnmigratedDb<T>(hippoRoot: string, readOnly: boolean, fn: (db: DatabaseSyncLike) => T): T;
 export declare function closeHippoDb(db: DatabaseSyncLike): void;
 //# sourceMappingURL=open.d.ts.map

package/dist/db/open.js

@@ -1,13 +1,13 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { errorMessage, log } from '../log.js';
+import { errorMessage, log } from '../util/log.js';
 import { DatabaseSync } from './sqlite.js';
 import { tableExists } from './tables.js';
 import { assertBinaryCompatible } from './migrate.js';
-import { connectHippoDb, getHippoDbPath } from './connect.js';
+import { connectWithFacts, DEFAULT_BUSY_WAIT_MS, getHippoDbPath } from './connect.js';
 import { currentRequestStores, isScopedHandle, runWithRequestStores } from './request-stores.js';
-import { OtherStoreFolderError, SqliteBlockedError } from './sqlite-blocked.js';
+import { OtherStoreFolderError, SqliteBlockedError } from '../util/sqlite-blocked.js';
 export { getHippoDbPath };
 /** Lock wait for hook commands: under the 5 s prompt-hook budget even after a few skipped writes, and far above a normal write's hold. */
 export const HOOK_DB_WAIT_MS = 1000;
@@ -38,6 +38,17 @@ export function withSqliteBlocked(storeKind, fn) {
 export function withSqliteAllowed(fn) {
     return sqliteBlockedBy.exit(() => markerWaived.run(true, fn));
 }
+// Not a store kind: the block of a route whose SQLite work belongs on a worker thread, under the hippo.db store itself.
+const OFF_LOOP = 'sqlite (off the event loop)';
+const OFF_LOOP_MESSAGE = 'hippo.db was opened on the server thread by a route whose SQLite work runs on a worker thread';
+/** Runs `fn` so that a hippo.db open on this thread throws, across awaits; a block of another store, when one is open, already refuses and stays as it is. */
+export function withSqliteOffLoop(fn) {
+    return sqliteBlockedBy.getStore() === undefined ? sqliteBlockedBy.run(OFF_LOOP, fn) : fn();
+}
+/** Leaves withSqliteOffLoop's block and nothing else: another store's block and the folder marker still refuse, which withSqliteAllowed would waive. */
+export function outsideSqliteOffLoop(fn) {
+    return sqliteBlockedBy.getStore() === OFF_LOOP ? sqliteBlockedBy.exit(fn) : fn();
+}
 /** First line of a best-effort catch around a hippo.db open: an unported path must fail closed, not fall back silently. */
 export function rethrowIfSqliteBlocked(err) {
     if (err instanceof SqliteBlockedError)
@@ -59,6 +70,8 @@ function markerKind(marker) {
 /** Throws where hippo.db must not open; checked on every open, not cached, since the marker can appear while a process runs. */
 export function assertSqliteAllowed(hippoRoot) {
     const storeKind = sqliteBlockedBy.getStore();
+    if (storeKind === OFF_LOOP)
+        throw new SqliteBlockedError('sqlite', OFF_LOOP_MESSAGE);
     if (storeKind !== undefined)
         throw new SqliteBlockedError(storeKind);
     if (markerWaived.getStore())
@@ -69,9 +82,13 @@ export function assertSqliteAllowed(hippoRoot) {
 }
 /** `busyWaitMs` shortens every lock wait of this open, for a hook that must finish inside its own timeout. */
 export function openHippoDb(hippoRoot, opts) {
+    return openHippoDbWithFacts(hippoRoot, opts).db;
+}
+/** openHippoDb, with what the open's probe read when this call made the connection. */
+export function openHippoDbWithFacts(hippoRoot, opts) {
     assertSqliteAllowed(hippoRoot);
     const stores = currentRequestStores();
-    return stores ? stores.get(hippoRoot, opts) : connectHippoDb(hippoRoot, opts?.busyWaitMs);
+    return stores ? stores.getWithFacts(hippoRoot, opts) : connectWithFacts(hippoRoot, opts?.busyWaitMs);
 }
 /** Open an existing store without changing it: no mkdir, WAL switch, migration or mirror cleanup. Throws when hippo.db is missing. */
 export function openHippoDbReadOnly(hippoRoot) {
@@ -93,6 +110,22 @@ export function openHippoDbReadOnly(hippoRoot) {
         throw error;
     }
 }
+/** Runs `fn` on an existing hippo.db opened without migrations, for a repair of a store whose schema is behind; closes it after. */
+export function withUnmigratedDb(hippoRoot, readOnly, fn) {
+    // Skips openHippoDb, so it takes the same refusal itself.
+    assertSqliteAllowed(hippoRoot);
+    const file = getHippoDbPath(hippoRoot);
+    if (!existsSync(file))
+        throw new Error(`No existing Hippo database at ${file}`);
+    const db = new DatabaseSync(file, { readOnly });
+    try {
+        db.exec(`PRAGMA busy_timeout = ${DEFAULT_BUSY_WAIT_MS}`);
+        return fn(db);
+    }
+    finally {
+        db.close();
+    }
+}
 export function closeHippoDb(db) {
     if (isScopedHandle(db))
         return;