hippo-memory 1.59.0 → 1.61.0

package/dist/store/summaries.d.ts

@@ -0,0 +1,94 @@
+import type { MemoryEntry } from '../memory.js';
+/**
+ * Load summaries flagged dirty for the given tenant. Sorted by latest_at
+ * DESC (NULLS LAST) so E3's rebuild cap (HIPPO_DAG_REBUILD_CAP, default 20)
+ * takes the most-recently-changed summaries first.
+ *
+ * Returns full MemoryEntry shape via MEMORY_SELECT_COLUMNS + rowToEntry
+ * (v28 fields are part of the standard read path).
+ */
+export declare function loadDirtySummaries(hippoRoot: string, tenantId: string): MemoryEntry[];
+/**
+ * Mark a summary as dirty. Idempotent (re-marking dirty is a no-op + no
+ * second audit row). Tenant-scoped to prevent cross-tenant writes via
+ * parent-lookup. Called by E2 from invalidation.ts / writeEntry /
+ * forgetMemory / archiveRawMemory whenever a child is invalidated,
+ * superseded, forgotten, or archived.
+ *
+ * Quietly no-ops if the target row doesn't exist or isn't a level-2
+ * summary (E5 will widen the dag_level guard to IN (2, 3) when level-3
+ * build path lands). Emits a 'summary_marked_dirty' audit row on actual
+ * state transitions (0 -> 1) via the audit() helper, which try/catches
+ * for missing audit_log (the v27 self-heal scenario).
+ */
+export declare function markSummaryDirty(hippoRoot: string, summaryId: string, tenantId: string, actor?: string): void;
+/**
+ * v0.30 / E5 — host-wide loader for L2 topic summaries without an L3 parent.
+ * Used by consolidate phase 1.9 (buildEntityProfiles) to cluster L2s into
+ * L3 entity profiles. Mirrors loadAllDirtySummaries pattern (E3): SQL-level
+ * filter is cheaper than reusing in-memory `survivors` (which doesn't
+ * contain L2s freshly created by phase 1.7 buildDag).
+ *
+ * Returns entries with tenantId attached so per-cluster writes stay
+ * tenant-scoped via summary.tenantId.
+ */
+export declare function loadAllL2Summaries(hippoRoot: string): MemoryEntry[];
+/**
+ * v0.30 / E3 — host-wide variant of loadDirtySummaries. Iterates all tenants
+ * in one query so consolidate.ts (host-wide per L106-109) does not need a
+ * per-tenant loop. Each returned MemoryEntry carries its own tenantId (via
+ * rowToEntry), so per-summary children + rebuild UPDATE stay tenant-scoped.
+ *
+ * Sort: latest_at DESC NULLS LAST, id ASC — same as per-tenant variant so
+ * HIPPO_DAG_REBUILD_CAP takes most-recently-changed summaries first.
+ */
+export declare function loadAllDirtySummaries(hippoRoot: string): MemoryEntry[];
+/**
+ * v0.30 / E3 — load live children of a DAG summary. Used by
+ * rebuildDirtySummaries to regenerate content from the CURRENT child set
+ * (not the children at create-time). Skips archived. Tenant-scoped
+ * (defence in depth — dag_parent_id is unique-ish but tenant guard is
+ * cheap). created column is TEXT NOT NULL since db.ts schema v1.
+ */
+export declare function loadChildrenOfSummary(hippoRoot: string, summaryId: string, tenantId: string): MemoryEntry[];
+/**
+ * v0.30 / E3 — patch applied by applyRebuildResult. Two-branch shape
+ * (bumpRebuildCount false for zero-child case, true for normal rebuild).
+ */
+export interface RebuildPatch {
+    content: string;
+    descendant_count: number;
+    earliest_at: string | null;
+    latest_at: string | null;
+    bumpRebuildCount: boolean;
+    zeroChildren: boolean;
+    actor: string;
+}
+/**
+ * v0.30 / E3 — apply a rebuild result to a dirty summary. Atomic: one
+ * prepared UPDATE statement plus syncFtsRow inside one SAVEPOINT.
+ * WHERE includes `AND summary_dirty = 1` so concurrent sleep's race-loser
+ * becomes a no-op (no rebuild_count bump, no audit row).
+ *
+ * Returns `{ changed, refused }`. `changed` is true when this call's UPDATE
+ * (content or metadata-only) affected a row; false on race-loss / unknown id
+ * / archived / wrong dag_level. `refused` is true only when a tombstone hit
+ * suppressed the content write AND the metadata UPDATE still landed — see
+ * the return-semantics comment below for the full contract.
+ */
+export declare function applyRebuildResult(hippoRoot: string, summary: MemoryEntry, patch: RebuildPatch): {
+    changed: boolean;
+    refused: boolean;
+};
+/**
+ * v0.30 / E3 — clear summary_dirty on a freshly-built summary. Called by
+ * buildDag immediately after the child-link loop finishes. Without this,
+ * each member's writeEntry call fires markSummaryDirtyInTx on the just-
+ * created parent (E2 hook at store.ts:1214), and the same sleep cycle's
+ * E3 rebuild phase would re-rebuild every new summary (2x LLM cost).
+ *
+ * Idempotent: no-op + no audit if summary isn't dirty. Audit
+ * source='buildDag-clean' distinguishes from E3-rebuild source.
+ */
+export declare function clearSummaryDirtyAfterBuild(hippoRoot: string, summaryId: string, tenantId: string, actor?: string, source?: string): void;
+//# sourceMappingURL=summaries.d.ts.map

package/dist/store/summaries.js

@@ -0,0 +1,377 @@
+import { closeHippoDb } from '../db.js';
+import { assertTenantId } from '../tenant.js';
+import { findRejectedValue, rejectionDigest } from '../rejection.js';
+import { log } from '../log.js';
+import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
+import { audit } from './audit-event.js';
+import { syncFtsRow } from './entry-row.js';
+import { openStore } from './open.js';
+// ---------------------------------------------------------------------------
+// v0.30 / E1 of DAG live-coupling — dirty-flag helpers for the existing
+// DAG layer's level-2 summaries.
+//
+// Used by E2 (child-write propagation in invalidation.ts / writeEntry /
+// forgetMemory / archiveRawMemory) to mark a summary dirty when one of its
+// children changes, and by E3's sleep-cycle rebuildDirtySummaries phase to
+// enumerate candidates without scanning every memory row.
+// ---------------------------------------------------------------------------
+/**
+ * Load summaries flagged dirty for the given tenant. Sorted by latest_at
+ * DESC (NULLS LAST) so E3's rebuild cap (HIPPO_DAG_REBUILD_CAP, default 20)
+ * takes the most-recently-changed summaries first.
+ *
+ * Returns full MemoryEntry shape via MEMORY_SELECT_COLUMNS + rowToEntry
+ * (v28 fields are part of the standard read path).
+ */
+export function loadDirtySummaries(hippoRoot, tenantId) {
+    assertTenantId('loadDirtySummaries', tenantId);
+    const db = openStore(hippoRoot);
+    try {
+        // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
+        // MemoryRow's field set.
+        const rows = db.prepare(`
+      SELECT ${MEMORY_SELECT_COLUMNS}
+        FROM memories
+       WHERE summary_dirty = 1
+         AND tenant_id = ?
+         AND kind != 'archived'
+       ORDER BY latest_at DESC NULLS LAST, id ASC
+    `).all(tenantId);
+        return rows.map(rowToEntry);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Mark a summary as dirty. Idempotent (re-marking dirty is a no-op + no
+ * second audit row). Tenant-scoped to prevent cross-tenant writes via
+ * parent-lookup. Called by E2 from invalidation.ts / writeEntry /
+ * forgetMemory / archiveRawMemory whenever a child is invalidated,
+ * superseded, forgotten, or archived.
+ *
+ * Quietly no-ops if the target row doesn't exist or isn't a level-2
+ * summary (E5 will widen the dag_level guard to IN (2, 3) when level-3
+ * build path lands). Emits a 'summary_marked_dirty' audit row on actual
+ * state transitions (0 -> 1) via the audit() helper, which try/catches
+ * for missing audit_log (the v27 self-heal scenario).
+ */
+export function markSummaryDirty(hippoRoot, summaryId, tenantId, actor = 'cli') {
+    assertTenantId('markSummaryDirty', tenantId);
+    const db = openStore(hippoRoot);
+    try {
+        // v0.30 / E5: widened dag_level=2 -> IN (2, 3). RETURNING dag_level reads
+        // actual level in same round trip.
+        // SAFETY: result's shape matches the single `dag_level` column returned
+        // above.
+        const result = db.prepare(`
+      UPDATE memories
+         SET summary_dirty = 1
+       WHERE id = ?
+         AND tenant_id = ?
+         AND dag_level IN (2, 3)
+         AND summary_dirty = 0
+         AND kind != 'archived'
+      RETURNING dag_level
+    `).get(summaryId, tenantId);
+        if (result) {
+            // audit() wraps appendAuditEvent in try/catch (v27 heal scenario).
+            // metadata.source=E1 leaves a breadcrumb so E2-E5 debugging can
+            // distinguish dirty-marks across the arc's wiring layers.
+            audit(db, 'summary_marked_dirty', summaryId, { dag_level: result.dag_level, source: 'E1' }, actor, tenantId);
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+// ---------------------------------------------------------------------------
+// v0.30 / E3 of DAG live-coupling — sleep-cycle rebuild surface.
+//
+// loadAllDirtySummaries / loadChildrenOfSummary / applyRebuildResult /
+// clearSummaryDirtyAfterBuild live HERE (not in dag.ts) because they need
+// module-private MEMORY_SELECT_COLUMNS, MemoryRow, rowToEntry, audit,
+// syncFtsRow, assertTenantId. dag.ts owns only the thin orchestrator
+// rebuildDirtySummaries() that calls into these.
+// ---------------------------------------------------------------------------
+/**
+ * v0.30 / E5 — host-wide loader for L2 topic summaries without an L3 parent.
+ * Used by consolidate phase 1.9 (buildEntityProfiles) to cluster L2s into
+ * L3 entity profiles. Mirrors loadAllDirtySummaries pattern (E3): SQL-level
+ * filter is cheaper than reusing in-memory `survivors` (which doesn't
+ * contain L2s freshly created by phase 1.7 buildDag).
+ *
+ * Returns entries with tenantId attached so per-cluster writes stay
+ * tenant-scoped via summary.tenantId.
+ */
+export function loadAllL2Summaries(hippoRoot) {
+    const db = openStore(hippoRoot);
+    try {
+        // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
+        // MemoryRow's field set.
+        const rows = db.prepare(`
+      SELECT ${MEMORY_SELECT_COLUMNS}
+        FROM memories
+       WHERE dag_level = 2
+         AND dag_parent_id IS NULL
+         AND kind != 'archived'
+         AND superseded_by IS NULL
+       ORDER BY created ASC, id ASC
+    `).all();
+        return rows.map(rowToEntry);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * v0.30 / E3 — host-wide variant of loadDirtySummaries. Iterates all tenants
+ * in one query so consolidate.ts (host-wide per L106-109) does not need a
+ * per-tenant loop. Each returned MemoryEntry carries its own tenantId (via
+ * rowToEntry), so per-summary children + rebuild UPDATE stay tenant-scoped.
+ *
+ * Sort: latest_at DESC NULLS LAST, id ASC — same as per-tenant variant so
+ * HIPPO_DAG_REBUILD_CAP takes most-recently-changed summaries first.
+ */
+export function loadAllDirtySummaries(hippoRoot) {
+    const db = openStore(hippoRoot);
+    try {
+        // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
+        // MemoryRow's field set.
+        const rows = db.prepare(`
+      SELECT ${MEMORY_SELECT_COLUMNS}
+        FROM memories
+       WHERE summary_dirty = 1
+         AND kind != 'archived'
+       ORDER BY latest_at DESC NULLS LAST, id ASC
+    `).all();
+        return rows.map(rowToEntry);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * v0.30 / E3 — load live children of a DAG summary. Used by
+ * rebuildDirtySummaries to regenerate content from the CURRENT child set
+ * (not the children at create-time). Skips archived. Tenant-scoped
+ * (defence in depth — dag_parent_id is unique-ish but tenant guard is
+ * cheap). created column is TEXT NOT NULL since db.ts schema v1.
+ */
+export function loadChildrenOfSummary(hippoRoot, summaryId, tenantId) {
+    assertTenantId('loadChildrenOfSummary', tenantId);
+    const db = openStore(hippoRoot);
+    try {
+        // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
+        // MemoryRow's field set.
+        const rows = db.prepare(`
+      SELECT ${MEMORY_SELECT_COLUMNS}
+        FROM memories
+       WHERE dag_parent_id = ?
+         AND tenant_id = ?
+         AND kind != 'archived'
+         AND superseded_by IS NULL
+       ORDER BY created ASC
+    `).all(summaryId, tenantId);
+        return rows.map(rowToEntry);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * v0.30 / E3 — apply a rebuild result to a dirty summary. Atomic: one
+ * prepared UPDATE statement plus syncFtsRow inside one SAVEPOINT.
+ * WHERE includes `AND summary_dirty = 1` so concurrent sleep's race-loser
+ * becomes a no-op (no rebuild_count bump, no audit row).
+ *
+ * Returns `{ changed, refused }`. `changed` is true when this call's UPDATE
+ * (content or metadata-only) affected a row; false on race-loss / unknown id
+ * / archived / wrong dag_level. `refused` is true only when a tombstone hit
+ * suppressed the content write AND the metadata UPDATE still landed — see
+ * the return-semantics comment below for the full contract.
+ */
+export function applyRebuildResult(hippoRoot, summary, patch) {
+    assertTenantId('applyRebuildResult', summary.tenantId);
+    const db = openStore(hippoRoot);
+    try {
+        db.exec('SAVEPOINT rebuild_summary');
+        try {
+            const outcome = applyRebuildInSavepoint(db, summary, patch);
+            db.exec('RELEASE SAVEPOINT rebuild_summary');
+            return outcome;
+        }
+        catch (e) {
+            try {
+                db.exec('ROLLBACK TO SAVEPOINT rebuild_summary');
+                db.exec('RELEASE SAVEPOINT rebuild_summary');
+            }
+            catch {
+                // Ignore rollback failures — throw below is what matters.
+            }
+            throw e;
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+// ONE prepared UPDATE per branch. Test #8 inspects the SQL string.
+// v0.30 / E5: widened dag_level=2 -> IN (2, 3) on both branches.
+const REBUILD_CONTENT_SQL = `UPDATE memories
+              SET content = ?,
+                  descendant_count = ?,
+                  earliest_at = ?,
+                  latest_at = ?,
+                  last_rebuilt_at = ?,
+                  rebuild_count = COALESCE(rebuild_count, 0) + 1,
+                  summary_dirty = 0
+            WHERE id = ?
+              AND tenant_id = ?
+              AND dag_level IN (2, 3)
+              AND summary_dirty = 1
+              AND kind != 'archived'`;
+const REBUILD_METADATA_SQL = `UPDATE memories
+              SET descendant_count = ?,
+                  earliest_at = ?,
+                  latest_at = ?,
+                  summary_dirty = 0
+            WHERE id = ?
+              AND tenant_id = ?
+              AND dag_level IN (2, 3)
+              AND summary_dirty = 1
+              AND kind != 'archived'`;
+function applyRebuildInSavepoint(db, summary, patch) {
+    const nowIso = new Date().toISOString();
+    // AT1 P1a fix (docs/plans/2026-08-15-at1-rejected-value-tombstone.md):
+    // applyRebuildResult's bumpRebuildCount branch wrote patch.content via
+    // a direct UPDATE, bypassing the rejection guard entirely (the guard
+    // lives in upsertEntryRow's INSERT path, which this function never
+    // calls). A rebuild that regenerates byte-identical content to an
+    // already-rejected value (e.g. deterministic summarization of an
+    // unchanged child set) would silently re-assert it every sleep cycle.
+    // Check BEFORE choosing which UPDATE to run — only the
+    // bumpRebuildCount branch ever writes content, so a miss or a
+    // zero-child call is a no-op here (one indexed point query, guarded
+    // path only).
+    const tombstone = patch.bumpRebuildCount
+        ? findRejectedValue(db, summary.tenantId, rejectionDigest(patch.content))
+        : null;
+    // On a hit: do NOT write the new content. Fall through to the SAME
+    // metadata-only behavior the zero-child branch already has —
+    // descendant_count/earliest_at/latest_at update + summary_dirty
+    // cleared, no content write, no rebuild_count bump. Clearing dirty
+    // (rather than leaving it set) is deliberate: leaving it dirty would
+    // make every following sleep cycle re-attempt and re-refuse the
+    // identical rebuild forever (the DAG-loop this fix closes).
+    const applyContentWrite = patch.bumpRebuildCount && !tombstone;
+    const result = applyContentWrite
+        ? db.prepare(REBUILD_CONTENT_SQL).run(patch.content, patch.descendant_count, patch.earliest_at, patch.latest_at, nowIso, summary.id, summary.tenantId)
+        : db.prepare(REBUILD_METADATA_SQL).run(patch.descendant_count, patch.earliest_at, patch.latest_at, summary.id, summary.tenantId);
+    // Return-value semantics (v0.30/T4 split): `changed` reflects whether
+    // THIS call's UPDATE (content or metadata-only) affected a row — NOT
+    // whether patch.content specifically landed. On a refusal, metadata
+    // still applies, so changed=true even though content did not change.
+    // This preserves the pre-T4 no-infinite-retry choice: the caller
+    // (dag.ts rebuildDirtySummaries) treats changed=false as "race lost,
+    // silently retry next cycle" — returning false on a refusal would
+    // retry the same doomed LLM rebuild forever, so changed=true settles
+    // this cycle (dirty cleared) regardless of refusal.
+    // `refused` is the T4 addition: true only when a tombstone hit AND
+    // the metadata UPDATE landed (changed=true) — a refusal that loses
+    // the race to a concurrent writer reports refused=false too, since
+    // nothing from this call took effect. Before T4, a refusal also
+    // counted toward the caller's `rebuilt` stat because `changed` alone
+    // could not distinguish it; the caller now increments `refused`
+    // instead of `rebuilt` when this is true, so the stat reflects what
+    // happened without changing dirty-clearing or retry behavior.
+    const changed = (result.changes ?? 0) > 0;
+    const refused = Boolean(tombstone) && changed;
+    if (tombstone && changed)
+        auditRefusedRebuild(db, summary, patch, tombstone);
+    if (changed)
+        syncRebuiltSummary(db, summary, patch, applyContentWrite, nowIso);
+    return { changed, refused };
+}
+/** Audit and log a rebuild whose content matched a rejected value; metadata still landed. */
+function auditRefusedRebuild(db, summary, patch, tombstone) {
+    // refused === true here (same condition, narrowed for the tombstone.*
+    // access below). Best-effort refusal audit, written INLINE inside
+    // this still-open SAVEPOINT — nothing here rolls back on a refusal
+    // (the metadata UPDATE above already committed to this savepoint), so the
+    // post-rollback auditRejectionRefusal helper (writeEntry/supersede's
+    // tool) is the wrong one here; a direct audit() call is correct and
+    // commits with the rest of this savepoint.
+    audit(db, 'reject_refusal', summary.id, { digest: tombstone.digest, reason: tombstone.reason }, patch.actor, summary.tenantId);
+    log.warn(`applyRebuildResult: refused rebuild content for ${summary.id} — matches a rejected value ` +
+        `(digest ${tombstone.digest.slice(0, 12)}...); metadata updated, content unchanged`);
+}
+function syncRebuiltSummary(db, summary, patch, applyContentWrite, nowIso) {
+    // FTS sync — bare UPDATE on memories does NOT update memories_fts.
+    // R1 HIGH must-fix from plan-eng-r1. Construct the patched entry in
+    // memory and reuse the existing syncFtsRow helper (delete-then-insert).
+    // earliest_at/latest_at preserve null semantics (R2 must-fix).
+    // AT1: content stays summary.content (unchanged) when the write was
+    // refused — applyContentWrite is false, so patch.content was never
+    // written to the row FTS must mirror.
+    const patchedEntry = {
+        ...summary,
+        content: applyContentWrite ? patch.content : summary.content,
+        descendant_count: patch.descendant_count,
+        earliest_at: patch.earliest_at,
+        latest_at: patch.latest_at,
+        summary_dirty: 0,
+        last_rebuilt_at: applyContentWrite ? nowIso : summary.last_rebuilt_at,
+        rebuild_count: applyContentWrite
+            ? (summary.rebuild_count ?? 0) + 1
+            : summary.rebuild_count,
+    };
+    syncFtsRow(db, patchedEntry);
+    audit(db, 'summary_rebuilt', summary.id, {
+        // v0.30 / E5: read actual level from the summary in scope
+        // (NOT hardcoded 2). L2 -> 2, L3 -> 3.
+        dag_level: summary.dag_level,
+        source: 'E3-rebuild',
+        zero_children: patch.zeroChildren,
+        descendant_count: patch.descendant_count,
+    }, patch.actor, summary.tenantId);
+}
+/**
+ * v0.30 / E3 — clear summary_dirty on a freshly-built summary. Called by
+ * buildDag immediately after the child-link loop finishes. Without this,
+ * each member's writeEntry call fires markSummaryDirtyInTx on the just-
+ * created parent (E2 hook at store.ts:1214), and the same sleep cycle's
+ * E3 rebuild phase would re-rebuild every new summary (2x LLM cost).
+ *
+ * Idempotent: no-op + no audit if summary isn't dirty. Audit
+ * source='buildDag-clean' distinguishes from E3-rebuild source.
+ */
+export function clearSummaryDirtyAfterBuild(hippoRoot, summaryId, tenantId, actor = 'cli', source = 'buildDag-clean') {
+    assertTenantId('clearSummaryDirtyAfterBuild', tenantId);
+    const db = openStore(hippoRoot);
+    try {
+        // v0.30 / E5: widened dag_level=2 -> IN (2, 3). RETURNING dag_level reads
+        // actual level so audit metadata stays accurate without an extra SELECT.
+        // SAFETY: result's shape matches the single `dag_level` column returned
+        // below.
+        const result = db.prepare(`
+      UPDATE memories
+         SET summary_dirty = 0
+       WHERE id = ?
+         AND tenant_id = ?
+         AND dag_level IN (2, 3)
+         AND summary_dirty = 1
+         AND kind != 'archived'
+      RETURNING dag_level
+    `).get(summaryId, tenantId);
+        if (result) {
+            // v0.30 / E5: source param distinguishes buildDag-clean (L2) from
+            // buildEntityProfiles-clean (L3) and any future build path.
+            audit(db, 'summary_marked_clean', summaryId, { dag_level: result.dag_level, source }, actor, tenantId);
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=summaries.js.map

package/dist/store/tenant-lookup.d.ts

@@ -0,0 +1,12 @@
+import type { DatabaseSyncLike } from '../db.js';
+/** The api_keys fields a tenant, revocation or rank check reads. */
+export interface ApiKeyOwner {
+    tenantId: string;
+    revokedAt: string | null;
+    role: string;
+}
+/** The owner row of `keyId`, or undefined when no such key exists. */
+export declare function selectApiKeyOwner(db: DatabaseSyncLike, keyId: string): ApiKeyOwner | undefined;
+/** The tenant that owns memory `id`, or undefined when no such memory exists. */
+export declare function selectMemoryTenant(db: DatabaseSyncLike, id: string): string | undefined;
+//# sourceMappingURL=tenant-lookup.d.ts.map

package/dist/store/tenant-lookup.js

@@ -0,0 +1,16 @@
+// Owner lookups by id: the tenant checks in src/api and the CLI's key-tenant lookup share these queries.
+/** The owner row of `keyId`, or undefined when no such key exists. */
+export function selectApiKeyOwner(db, keyId) {
+    // SAFETY: row's shape matches the three columns named in the SELECT.
+    const row = db
+        .prepare(`SELECT tenant_id, revoked_at, role FROM api_keys WHERE key_id = ?`)
+        .get(keyId);
+    return row && { tenantId: row.tenant_id, revokedAt: row.revoked_at, role: row.role };
+}
+/** The tenant that owns memory `id`, or undefined when no such memory exists. */
+export function selectMemoryTenant(db, id) {
+    // SAFETY: row's shape matches the single tenant_id column named in the SELECT.
+    const row = db.prepare(`SELECT tenant_id FROM memories WHERE id = ?`).get(id);
+    return row?.tenant_id;
+}
+//# sourceMappingURL=tenant-lookup.js.map

package/dist/store-cards.js

@@ -3,7 +3,8 @@ import { closeHippoDb } from './db.js';
 import { rowToSessionHandoff, isHandoffOutcome } from './handoff.js';
 import { CARD_TRANSITIONS, CARD_LEASE_MS } from './card.js';
 import { assertTenantId } from './tenant.js';
-import { openStore, HANDOFF_COLUMNS } from './store.js';
+import { openStore } from './store/open.js';
+import { HANDOFF_COLUMNS } from './store/handoffs.js';
 const CARD_COLUMNS = 'id, title, status, assignee_runtime, repo, contract, budget, lease_until, heartbeat_at, created_at, updated_at, tenant_id, scope';
 function rowToCard(row) {
     return {

package/dist/summary-dirty.d.ts

@@ -0,0 +1,4 @@
+import type { DatabaseSyncLike } from './db.js';
+/** Runs in the caller's transaction so the mark commits or rolls back with the child change; only a 0 to 1 flip is audited. */
+export declare function markSummaryDirtyInTx(db: DatabaseSyncLike, summaryId: string, tenantId: string, actor: string): void;
+//# sourceMappingURL=summary-dirty.d.ts.map

package/dist/summary-dirty.js

@@ -0,0 +1,32 @@
+// Leaf module so store.ts and raw-archive.ts can both mark a parent summary dirty without importing each other.
+import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
+/** Runs in the caller's transaction so the mark commits or rolls back with the child change; only a 0 to 1 flip is audited. */
+export function markSummaryDirtyInTx(db, summaryId, tenantId, actor) {
+    // SAFETY: result's shape matches the single `dag_level` column returned below.
+    const result = db.prepare(`
+    UPDATE memories
+       SET summary_dirty = 1
+     WHERE id = ?
+       AND tenant_id = ?
+       AND dag_level IN (2, 3)
+       AND summary_dirty = 0
+       AND kind != 'archived'
+    RETURNING dag_level
+  `).get(summaryId, tenantId);
+    if (!result)
+        return;
+    try {
+        appendAuditEvent(db, {
+            tenantId,
+            actor,
+            op: 'summary_marked_dirty',
+            targetId: summaryId,
+            metadata: { dag_level: result.dag_level, source: 'E2' },
+        });
+    }
+    catch (error) {
+        // The mark has already succeeded; a broken audit table must not undo it.
+        reportAuditWriteFailure('summary_marked_dirty', String(error), summaryId);
+    }
+}
+//# sourceMappingURL=summary-dirty.js.map

package/dist/support-bundle.js

@@ -1,11 +1,12 @@
 /** `hippo support-bundle`: one redacted JSON snapshot for a support ticket. Read-only (SQLite may leave empty -wal and -shm files); never touches memory content. */
+import { envByName, processEnv } from './env.js';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { pathToFileURL } from 'url';
 import { findHippoStoreDir, isGlobalStoreRoot, realpathOrResolve } from './project-identity.js';
 import { getGlobalRoot } from './shared.js';
-import { isInitialized } from './store.js';
+import { isInitialized } from './store/open.js';
 import { openHippoDbReadOnly, closeHippoDb, getSchemaVersion, getMeta, countTableRows } from './db.js';
 import { runDoctor } from './doctor.js';
 import { loadConfig } from './config.js';
@@ -118,12 +119,12 @@ function buildStores(opts) {
 }
 function listSetEnvNames() {
     const names = new Set();
-    for (const key of Object.keys(process.env)) {
+    for (const key of Object.keys(processEnv())) {
         if (key.startsWith('HIPPO_'))
             names.add(key);
     }
     for (const key of OTHER_ENV_NAMES) {
-        if (process.env[key] !== undefined)
+        if (envByName(key) !== undefined)
             names.add(key);
     }
     return [...names].sort();

package/dist/tenant.js

@@ -1,3 +1,4 @@
+import { envTenant } from './env.js';
 import { validateApiKey } from './auth.js';
 export function resolveTenantId(opts) {
     if (opts.apiKey) {
@@ -11,8 +12,7 @@ export function resolveTenantId(opts) {
     // L1: empty / whitespace-only HIPPO_TENANT must fall through to 'default'.
     // `??` only catches undefined, so HIPPO_TENANT="" leaked through as the
     // literal empty string and broke every downstream tenant filter.
-    const t = process.env.HIPPO_TENANT?.trim();
-    return t ? t : 'default';
+    return envTenant();
 }
 /**
  * Defensive runtime guard for tenant id arguments.

package/dist/token-ledger.js

@@ -161,6 +161,7 @@ function parseHookPayload(stdinText) {
         return isJsonObject(payload) ? payload : null;
     }
     catch {
+        // Malformed is one of the null cases the docblock names.
         return null;
     }
 }

package/dist/tokenize.d.ts

@@ -1,2 +1,4 @@
 export declare function tokenize(text: string): string[];
+/** Jaccard overlap of the two texts' token sets; two empty texts count as identical. */
+export declare function textOverlap(a: string, b: string): number;
 //# sourceMappingURL=tokenize.d.ts.map

package/dist/tokenize.js

@@ -5,4 +5,20 @@ export function tokenize(text) {
         .split(/\s+/)
         .filter((t) => t.length > 1);
 }
+/** Jaccard overlap of the two texts' token sets; two empty texts count as identical. */
+export function textOverlap(a, b) {
+    const setA = new Set(tokenize(a));
+    const setB = new Set(tokenize(b));
+    if (setA.size === 0 && setB.size === 0)
+        return 1;
+    if (setA.size === 0 || setB.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const t of setA) {
+        if (setB.has(t))
+            intersection++;
+    }
+    const union = setA.size + setB.size - intersection;
+    return intersection / union;
+}
 //# sourceMappingURL=tokenize.js.map

package/dist/transcript-tail.d.ts

@@ -0,0 +1,7 @@
+/** Never read the whole transcript: PreCompact fires exactly when it's largest. */
+export declare const PRE_COMPACT_TAIL_BYTES: number;
+/** Cut to `maxChars` UTF-16 units, backing off one unit rather than leave half a surrogate pair in a stored field. */
+export declare function truncateCodePointSafe(text: string, maxChars: number): string;
+/** The last `capBytes` of a JSONL transcript, read at an offset and starting on a whole line so every line parses. */
+export declare function readTranscriptTail(transcriptPath: string, capBytes?: number): string;
+//# sourceMappingURL=transcript-tail.d.ts.map