hippo-memory 1.69.0 → 1.71.0

package/dist/sharing/share.js

@@ -0,0 +1,226 @@
+// Sharing local memories to the global store: transfer scoring, share, peers and auto-share.
+import { BadRequestError, NotFoundError } from '../core/api-errors.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { generateId, COMPACTION_MEMORY_TAG } from '../core/memory.js';
+import { AGENT_MEMORY_SOURCE_PREFIX, AGENT_MEMORY_TAGS } from '../core/agent-memory-tools.js';
+import { writeEntry } from '../store/entry-writes.js';
+import { loadAllEntries, readEntry } from '../store/entry-reads.js';
+import { tallySources } from '../store/candidates.js';
+import { isPersonalScope } from '../store/recall-scope.js';
+import { fallbackOrigin } from '../core/project-identity.js';
+import { detectSecret } from '../util/secret-detect.js';
+import { isQuarantineScope } from '../trust/quarantine.js';
+import { RejectedValueError } from '../store/rejection.js';
+import { embedMemory, embedAll } from '../store/embeddings/index.js';
+import { duplicateKey, storedTextKeys } from '../util/same-text.js';
+import { isReusable } from '../core/memory-quality.js';
+import { log } from '../util/log.js';
+import { getGlobalRoot, initGlobal } from './global-store.js';
+import { logEmbedAllFailure } from './search-both.js';
+/** Tags that indicate project-specific memories (poor transfer candidates) */
+const PROJECT_SPECIFIC_TAGS = new Set([
+    'file-path', 'config', 'deploy', 'cron', 'url', 'auth',
+    'field-names', 'column-names', 'api-key', 'endpoint',
+]);
+/** Tags that indicate transferable memories (good transfer candidates) */
+const TRANSFERABLE_TAGS = new Set([
+    'error', 'platform', 'windows', 'encoding', 'python', 'shell',
+    'powershell', 'quant', 'backtest', 'pattern', 'rule', 'gotcha',
+    'sub-agent', 'review', 'best-practice',
+]);
+/** Tags whose rows only a hand-run share or promote may copy to the global store; derived rows inherit them. */
+export const NEVER_AUTO_SHARE_TAGS = new Set([
+    'git-learned',
+    'session-digest',
+    ...AGENT_MEMORY_TAGS,
+]);
+export function neverAutoShareTags(sources) {
+    return [...NEVER_AUTO_SHARE_TAGS].filter((tag) => sources.some((s) => s.tags.includes(tag)));
+}
+/** Tags whose rows sleep keeps as written: never merged, never sent to LLM extraction. Conflict detection keeps its own list. */
+export const NO_MERGE_TAGS = new Set([
+    'extracted',
+    'session-digest',
+    COMPACTION_MEMORY_TAG,
+    ...AGENT_MEMORY_TAGS,
+]);
+/** Estimate how well a memory would transfer to other projects.
+ *  Returns 0..1 where >0.5 = good candidate for sharing. */
+export function transferScore(entry) {
+    let score = 0.5; // neutral default
+    // Boost for transferable tags
+    const transferableCount = entry.tags.filter((t) => TRANSFERABLE_TAGS.has(t)).length;
+    score += transferableCount * 0.1;
+    // Penalize for project-specific tags
+    const specificCount = entry.tags.filter((t) => PROJECT_SPECIFIC_TAGS.has(t)).length;
+    score -= specificCount * 0.15;
+    // High-retrieval memories are more likely to be universally useful
+    if (entry.retrieval_count >= 3)
+        score += 0.1;
+    // Pinned memories are important to their owner
+    if (entry.pinned)
+        score += 0.1;
+    // Error-tagged memories often encode universal lessons
+    if (entry.emotional_valence === 'negative' || entry.emotional_valence === 'critical')
+        score += 0.05;
+    return Math.min(1, Math.max(0, score));
+}
+/** Share a memory to the global store with attribution (source enriched with project path and timestamp).
+ *  Returns the new entry, or null if the transfer score is too low. */
+export function shareMemory(localRoot, id, options = {}) {
+    // tenantId is optional for single-tenant callers (autoShare passes only `{ force: true }`); MCP/REST hosts MUST pass it so tenant A cannot share
+    // tenant B's memory to global (readEntry returns null on a cross-tenant lookup).
+    const entry = readEntry(localRoot, id, options.tenantId);
+    if (!entry)
+        throw new NotFoundError(`Memory not found: ${id}`);
+    assertShareable(entry, id);
+    const score = transferScore(entry);
+    if (score < 0.3 && !options.force)
+        return null;
+    initGlobal();
+    const globalRoot = getGlobalRoot();
+    // The label keeps the folder name for a user-global row; a NULL row gets `shared::`, which originFromSource reads as no project.
+    const fallbackName = path.basename(path.resolve(localRoot, '..'));
+    const originName = entry.origin_project ?? fallbackOrigin(localRoot);
+    const label = originName === '' ? fallbackName : (originName ?? '');
+    const globalEntry = {
+        ...entry,
+        id: generateId('g'),
+        source: `shared:${label}:${new Date().toISOString()}`,
+        origin_project: originName,
+    };
+    writeEntry(globalRoot, globalEntry);
+    // Embed here unless the caller opts out: autoShare sets skipEmbed to batch one embedAll(), since embedMemory rewrites the whole index per call.
+    if (!options.skipEmbed) {
+        void embedMemory(globalRoot, globalEntry);
+    }
+    return globalEntry;
+}
+function assertShareable(entry, id) {
+    // Secret veto: secrets never reach the global store, even with --force; throw loudly, since a silent null reads as "low transfer score" and invites retries.
+    const secret = detectSecret(entry);
+    if (secret.flagged) {
+        throw new BadRequestError(`Refusing to share ${id} to the global store: content matches secret material (${secret.reason}). ` +
+            `Secrets stay in their owning project's store.`);
+    }
+    // A quarantined row is unreviewed input, not a lesson; sharing it would spread poison globally.
+    if (isQuarantineScope(entry.scope)) {
+        throw new BadRequestError(`Refusing to share ${id}: it is quarantined pending review. Approve it first via 'hippo quarantine approve ${id}'.`);
+    }
+    if (isPersonalScope(entry.scope ?? null)) {
+        throw new BadRequestError(`Refusing to share ${id}: it is a personal memory and stays with its owner on this server.`);
+    }
+}
+/** List all projects that contributed memories to the global store, parsed from 'shared:<project>:' or 'promoted:<path>' sources.
+ *  `tenantId` filters to one tenant; undefined is host-wide (legacy callers: CLI standalone, dashboard). */
+export function listPeers(globalRoot, tenantId) {
+    const root = globalRoot ?? getGlobalRoot();
+    if (!fs.existsSync(root))
+        return [];
+    // Tenant-scoped by default when tenantId provided. Host-wide when
+    // undefined (preserves back-compat).
+    const tallies = tallySources(root, tenantId).sort((a, b) => (a.first < b.first ? -1 : a.first > b.first ? 1 : 0));
+    const peerMap = new Map();
+    for (const tally of tallies) {
+        let project = 'unknown';
+        if (tally.source.startsWith('shared:')) {
+            const parts = tally.source.split(':');
+            project = parts[1] || 'unknown';
+        }
+        else if (tally.source.startsWith('promoted:')) {
+            const promotedPath = tally.source.slice('promoted:'.length);
+            project = path.basename(path.resolve(promotedPath, '..'));
+        }
+        else if (tally.source === 'cli-global') {
+            project = 'global-cli';
+        }
+        const existing = peerMap.get(project);
+        if (!existing) {
+            peerMap.set(project, { count: tally.count, latest: tally.latest });
+        }
+        else {
+            existing.count += tally.count;
+            if (tally.latest > existing.latest)
+                existing.latest = tally.latest;
+        }
+    }
+    return Array.from(peerMap.entries())
+        .map(([project, data]) => ({ project, ...data }))
+        .sort((a, b) => b.count - a.count);
+}
+function isAutoShareCandidate(entry, globalContentSet, minScore, stats) {
+    // shareMemory refuses quarantined and personal rows; filtering here keeps sleep from aborting on one.
+    if (isQuarantineScope(entry.scope ?? null) || isPersonalScope(entry.scope ?? null) || !isReusable(entry))
+        return false;
+    // Before the score: these rows describe one project only, and a git seed's 'error' tag clears the bar.
+    if (entry.tags.some((t) => NEVER_AUTO_SHARE_TAGS.has(t)) || entry.source.startsWith(AGENT_MEMORY_SOURCE_PREFIX)) {
+        if (stats)
+            stats.neverAutoShareSkipped = (stats.neverAutoShareSkipped ?? 0) + 1;
+        return false;
+    }
+    const score = transferScore(entry);
+    if (score < minScore)
+        return false;
+    // Skip if already shared (same text apart from spacing)
+    if (globalContentSet.has(duplicateKey(entry.content)))
+        return false;
+    // Secret veto, checked LAST so the stats counter only counts rows it withheld (a row failing the score or dedupe gate was never going to share).
+    // shareMemory would throw here; filtering keeps the sleep pipeline fail-safe.
+    if (detectSecret(entry).flagged) {
+        if (stats)
+            stats.secretSkipped++;
+        return false;
+    }
+    return true;
+}
+// Rejection containment: shareMemory -> writeEntry can throw RejectedValueError against the GLOBAL store tombstones and abort the autoShare sleep phase.
+// Catch per item like syncGlobalToLocal; writeEntry already audits reject_refusal before rethrowing, so count and continue.
+function shareCandidates(localRoot, candidates, stats) {
+    const shared = [];
+    let rejectedSkipped = 0;
+    for (const entry of candidates) {
+        try {
+            // skipEmbed: batching invariant, this is a batch producer, so it embeds
+            // once via embedAll() below rather than once per row inside shareMemory.
+            const result = shareMemory(localRoot, entry.id, { force: true, skipEmbed: true });
+            if (result)
+                shared.push(result);
+        }
+        catch (err) {
+            if (err instanceof RejectedValueError) {
+                rejectedSkipped++;
+                if (stats)
+                    stats.rejectedSkipped = (stats.rejectedSkipped ?? 0) + 1;
+                continue;
+            }
+            throw err;
+        }
+    }
+    if (rejectedSkipped > 0) {
+        log.warn(`autoShare: skipped ${rejectedSkipped} candidate(s) refused by the global store's rejection tombstone`);
+    }
+    return shared;
+}
+/** Auto-share local memories with high transfer scores, not already global and without a NEVER_AUTO_SHARE_TAGS tag; `options.tenantId` scopes the LOCAL read.
+ *  `options.stats` is an opt-in out-param: `secretSkipped` counts shares the secret veto prevented, `rejectedSkipped` rejection refusals (0 under `dryRun`). */
+export function autoShare(localRoot, options = {}) {
+    const { minScore = 0.6, dryRun = false } = options;
+    const localEntries = loadAllEntries(localRoot, options.tenantId);
+    initGlobal();
+    const globalRoot = getGlobalRoot();
+    // Host-wide read. The global store IS the union across all tenants;
+    // per-tenant filtering on the global root would defeat the purpose.
+    const globalEntries = loadAllEntries(globalRoot);
+    // Build set of global content hashes to avoid duplicates
+    const globalContentSet = storedTextKeys(globalEntries);
+    const candidates = localEntries.filter((entry) => isAutoShareCandidate(entry, globalContentSet, minScore, options.stats));
+    if (dryRun)
+        return candidates;
+    const shared = shareCandidates(localRoot, candidates, options.stats);
+    if (shared.length > 0) {
+        void embedAll(globalRoot).catch((err) => logEmbedAllFailure('autoShare', err));
+    }
+    return shared;
+}
+//# sourceMappingURL=share.js.map

package/dist/{ambient-store.d.ts → store/ambient.d.ts}

@@ -1,4 +1,4 @@
-import { type AmbientTallies } from './ambient.js';
+import { type AmbientTallies } from '../core/ambient.js';
 /** The rows an ambient summary describes: a context read's envelope, origin partition and tag secret veto. */
 export interface AmbientStoreFilter {
     exactScope?: string;
@@ -13,4 +13,4 @@ export interface AmbientStoreFilter {
 /** Whole-store ambient tallies in one aggregate pass, no row loaded. Content-pattern secrets and session-local
  *  rows (own compaction items, a printed handoff's digest) still count: only injection drops them. */
 export declare function loadAmbientTallies(hippoRoot: string, tenantId: string, filter: AmbientStoreFilter): AmbientTallies;
-//# sourceMappingURL=ambient-store.d.ts.map
+//# sourceMappingURL=ambient.d.ts.map

package/dist/{ambient-store.js → store/ambient.js}

@@ -1,12 +1,11 @@
-import { closeHippoDb } from './db.js';
-import { strengthSql } from './memory.js';
+import { strengthSql } from './rule-sql.js';
 import { scopeAdmitSql } from './recall-scope.js';
-import { SECRET_TAGS } from './secret-detect.js';
-import { openStore } from './store/open.js';
-import { originInSql } from './project-identity.js';
-import { isErrorTagged } from './ambient.js';
-// A malformed or non-array JSON list reads as empty, as parseJsonArray does, instead of failing json_each.
-const jsonList = (column) => `(CASE WHEN json_valid(${column}) AND json_type(${column}) = 'array' THEN ${column} ELSE '[]' END)`;
+import { SECRET_TAGS } from '../util/secret-detect.js';
+import { onHandle, openStore } from './open.js';
+import { jsonList } from './candidates.js';
+import { originInSql } from '../core/project-identity.js';
+import { isErrorTagged } from '../core/ambient.js';
+import { DAY_MS } from '../util/time.js';
 // SHORTCUT: mirrors loadContextCandidates' WHERE (request-path snapshots pin the match); share it once store.ts is split.
 function contextRowsWhere(tenantId, filter) {
     const where = ['tenant_id = ?', `COALESCE(superseded_by, '') = ''`, `COALESCE(kind, '') != 'archived'`];
@@ -40,9 +39,8 @@ function secretTaggedSql() {
 export function loadAmbientTallies(hippoRoot, tenantId, filter) {
     const { where, params } = contextRowsWhere(tenantId, filter);
     const secret = secretTaggedSql();
-    const sevenDaysAgo = new Date(filter.now.getTime() - 7 * 86400000).toISOString();
-    const db = openStore(hippoRoot);
-    try {
+    const sevenDaysAgo = new Date(filter.now.getTime() - 7 * DAY_MS).toISOString();
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: one aggregate row whose columns are the aliases named below. Tag lists come back as one JSON array of
         // arrays and are counted in JS, which maps items through String() as parseJsonArray does.
         const row = db.prepare(`SELECT
@@ -84,9 +82,6 @@ export function loadAmbientTallies(hippoRoot, tenantId, filter) {
             maxDagLevel: Number(row.maxDagLevel),
             tagCounts,
         };
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-//# sourceMappingURL=ambient-store.js.map
+//# sourceMappingURL=ambient.js.map

package/dist/store/audit-event.d.ts

@@ -1,19 +1,17 @@
-import { openHippoDb } from '../db.js';
-import { type AuditOp } from '../audit.js';
-import { RejectedValueError } from '../rejection.js';
-import type { JsonValue } from '../json.js';
-/**
- * Emit an audit event for a mutation against `db`. Wrapped so a broken audit
- * log can never crash the surrounding mutation — the SQLite store is still the
- * source of truth and audit failures are diagnosable from the missing rows.
- */
-export declare function audit(db: ReturnType<typeof openHippoDb>, op: AuditOp, targetId?: string, metadata?: Record<string, JsonValue>, actor?: string, tenantId?: string): void;
-/**
- * Refusal audit for the rejected-value guard. Written by the
- * transaction OWNER post-rollback — writeEntry's catch (no outer tx exists
- * there, so this lands in a fresh implicit transaction) and commitSupersede's
- * catch (after its own ROLLBACK) — never inside a scope the caller's own
- * rollback could claw back. Best-effort `audit()` semantics: never throws.
- */
+import { openHippoDb } from '../db/index.js';
+import { type AuditOp } from './audit.js';
+import { RejectedValueError } from './rejection.js';
+import type { JsonValue } from '../util/json.js';
+export interface AuditOptions {
+    readonly targetId?: string;
+    readonly metadata?: Record<string, JsonValue>;
+    readonly actor?: string;
+    readonly tenantId?: string;
+}
+/** Emit an audit event for a mutation. Never throws: the SQLite store stays the source of truth,
+ * and a failed audit write shows up as missing rows. */
+export declare function audit(db: ReturnType<typeof openHippoDb>, op: AuditOp, options?: AuditOptions): void;
+/** Refusal audit for the rejected-value guard, written by the transaction owner after rollback so the caller's own rollback cannot claw it back.
+ * Best-effort like `audit()`: never throws. */
 export declare function auditRejectionRefusal(db: ReturnType<typeof openHippoDb>, err: RejectedValueError, actor: string): void;
 //# sourceMappingURL=audit-event.d.ts.map

package/dist/store/audit-event.js

@@ -1,11 +1,9 @@
-import { resolveTenantId } from '../tenant.js';
-import { appendAuditEvent, reportAuditWriteFailure } from '../audit.js';
-/**
- * Emit an audit event for a mutation against `db`. Wrapped so a broken audit
- * log can never crash the surrounding mutation — the SQLite store is still the
- * source of truth and audit failures are diagnosable from the missing rows.
- */
-export function audit(db, op, targetId, metadata, actor = 'cli', tenantId) {
+import { resolveTenantId } from './tenant.js';
+import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
+/** Emit an audit event for a mutation. Never throws: the SQLite store stays the source of truth,
+ * and a failed audit write shows up as missing rows. */
+export function audit(db, op, options = {}) {
+    const { targetId, metadata, actor = 'cli', tenantId } = options;
     try {
         appendAuditEvent(db, {
             tenantId: tenantId ?? resolveTenantId({}),
@@ -20,14 +18,9 @@ export function audit(db, op, targetId, metadata, actor = 'cli', tenantId) {
         reportAuditWriteFailure(op, String(error), targetId);
     }
 }
-/**
- * Refusal audit for the rejected-value guard. Written by the
- * transaction OWNER post-rollback — writeEntry's catch (no outer tx exists
- * there, so this lands in a fresh implicit transaction) and commitSupersede's
- * catch (after its own ROLLBACK) — never inside a scope the caller's own
- * rollback could claw back. Best-effort `audit()` semantics: never throws.
- */
+/** Refusal audit for the rejected-value guard, written by the transaction owner after rollback so the caller's own rollback cannot claw it back.
+ * Best-effort like `audit()`: never throws. */
 export function auditRejectionRefusal(db, err, actor) {
-    audit(db, 'reject_refusal', err.entryId, { digest: err.digest, reason: err.reason }, actor, err.tenantId);
+    audit(db, 'reject_refusal', { targetId: err.entryId, metadata: { digest: err.digest, reason: err.reason }, actor, tenantId: err.tenantId });
 }
 //# sourceMappingURL=audit-event.js.map

package/dist/{audit.d.ts → store/audit.d.ts}

@@ -1,7 +1,7 @@
-import { type MemoryEntry } from './memory.js';
-import type { DatabaseSyncLike } from './db.js';
+import { type MemoryEntry } from '../core/memory.js';
+import { type DatabaseSyncLike } from '../db/index.js';
 import type { JsonObject } from './working-memory.js';
-import { type KeysetPosition } from './keyset.js';
+import { type KeysetPosition } from '../util/keyset.js';
 export type AuditSeverity = 'warning' | 'error';
 export interface AuditIssue {
     memoryId: string;
@@ -32,10 +32,14 @@ export type AuditQueryFields = {
 };
 export declare function auditQueryFields(query: string): AuditQueryFields;
 export declare function appendAuditEvent(db: DatabaseSyncLike, opts: AppendAuditOpts): void;
+/** One audit row in the store under `hippoRoot`, as its own write. */
+export declare function recordAuditEvent(hippoRoot: string, event: AppendAuditOpts): void;
 /** For callers that keep a mutation when its audit row fails: the failure is logged and counted, never silent. */
 export declare function reportAuditWriteFailure(op: AuditOp, reason: string, targetId?: string | null): void;
 /** Audit rows this process failed to write; the loopback `/health` body reports it. */
 export declare function auditWriteFailureCount(): number;
+/** Adds the failures a store worker counted on its own thread, so the process reports one number. */
+export declare function addAuditWriteFailures(count: number): void;
 export interface QueryAuditOpts {
     tenantId: string;
     op?: AuditOp;
@@ -62,10 +66,27 @@ export interface ListAuditAfterOpts {
     /** Omit for every tenant (deployment-wide export). */
     tenantId?: string;
 }
-/**
- * Cursor read: events with id > afterId, ascending by id. Ids are AUTOINCREMENT
- * and never reused, but deletes (retention prune) leave gaps, so resume from
- * the last id returned, never from a count.
- */
+/** Cursor read: events with id > afterId, ascending. Retention prune leaves gaps in the ids,
+ * so resume from the last id returned, never from a count. */
 export declare function listAuditEventsAfter(db: DatabaseSyncLike, opts: ListAuditAfterOpts): AuditEvent[];
+/** Latest time each target got a good outcome, from the audit rows, read on a handle of its own; unlike queryAuditEvents it has no row cap. */
+export declare function confirmedOutcomeTimes(hippoRoot: string, tenantId: string): Map<string, string>;
+/** An audit row that did not land, with what its write threw. */
+export interface FailedAuditEvent {
+    event: AppendAuditOpts;
+    error: unknown;
+}
+/** Appends each event as its own write on one handle, so a row that fails drops only itself. Returns the rows that failed, for the caller to report. */
+export declare function recordAuditEventsRowByRow(hippoRoot: string, events: readonly AppendAuditOpts[]): FailedAuditEvent[];
+export interface AuditPrune {
+    tenantId: string;
+    /** ISO time; rows with `ts` before it go. */
+    cutoff: string;
+    actor: string;
+    olderThanDays: number;
+    /** Count the rows and delete nothing. */
+    dryRun: boolean;
+}
+/** Deletes a tenant's audit rows older than the cutoff and records the prune in the same write scope, so neither lands alone; returns the row count. */
+export declare function pruneAuditRows(hippoRoot: string, prune: AuditPrune): number;
 //# sourceMappingURL=audit.d.ts.map

package/dist/{audit.js → store/audit.js}

@@ -1,8 +1,10 @@
 import { createHash } from 'node:crypto';
-import { canAutoDelete } from './memory.js';
-import { log } from './log.js';
-import { keysetAfter } from './keyset.js';
-import { automaticDefect, hasNoSpecificity, isFragment, isReleaseCommitNoise, substantiveWordCount, } from './memory-quality.js';
+import { canAutoDelete } from '../core/memory.js';
+import { closeHippoDb, openHippoDb, withWriteScope } from '../db/index.js';
+import { log } from '../util/log.js';
+import { keysetAfter } from '../util/keyset.js';
+import { warnDamagedColumn } from '../util/stored-json.js';
+import { automaticDefect, hasNoSpecificity, isFragment, isReleaseCommitNoise, substantiveWordCount, } from '../core/memory-quality.js';
 export function auditMemory(entry, backsObject = false) {
     const issue = classifyMemory(entry);
     // Error means "auto-remove"; a pinned, raw, kept-for-good or object-backing row is never auto-removed, so it can only warn.
@@ -53,9 +55,6 @@ export function auditMemories(entries, backing) {
         clean: entries.length - issues.length,
     };
 }
-// ---------------------------------------------------------------------------
-// Audit log primitives (append-only mutation trail)
-// ---------------------------------------------------------------------------
 // The one list of audit ops: the AuditOp type, `hippo audit list --op` and GET /v1/audit?op= all read it.
 export const AUDIT_OPS = [
     'remember',
@@ -136,6 +135,16 @@ export function auditQueryFields(query) {
 export function appendAuditEvent(db, opts) {
     db.prepare(`INSERT INTO audit_log (ts, tenant_id, actor, op, target_id, metadata_json) VALUES (?, ?, ?, ?, ?, ?)`).run(new Date().toISOString(), opts.tenantId, opts.actor, opts.op, opts.targetId ?? null, JSON.stringify(opts.metadata ?? {}, bigintSafeReplacer));
 }
+/** One audit row in the store under `hippoRoot`, as its own write. */
+export function recordAuditEvent(hippoRoot, event) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        appendAuditEvent(db, event);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 let auditWriteFailures = 0;
 /** For callers that keep a mutation when its audit row fails: the failure is logged and counted, never silent. */
 export function reportAuditWriteFailure(op, reason, targetId) {
@@ -146,6 +155,10 @@ export function reportAuditWriteFailure(op, reason, targetId) {
 export function auditWriteFailureCount() {
     return auditWriteFailures;
 }
+/** Adds the failures a store worker counted on its own thread, so the process reports one number. */
+export function addAuditWriteFailures(count) {
+    auditWriteFailures += count;
+}
 export function queryAuditEvents(db, opts) {
     const where = ['tenant_id = ?'];
     const params = [opts.tenantId];
@@ -166,11 +179,8 @@ export function queryAuditEvents(db, opts) {
         .all(...params, ...after.params, limit);
     return rows.map(rowToAuditEvent);
 }
-/**
- * Cursor read: events with id > afterId, ascending by id. Ids are AUTOINCREMENT
- * and never reused, but deletes (retention prune) leave gaps, so resume from
- * the last id returned, never from a count.
- */
+/** Cursor read: events with id > afterId, ascending. Retention prune leaves gaps in the ids,
+ * so resume from the last id returned, never from a count. */
 export function listAuditEventsAfter(db, opts) {
     if (!Number.isInteger(opts.afterId) || opts.afterId < 0) {
         throw new RangeError('afterId must be a non-negative integer');
@@ -191,6 +201,37 @@ export function listAuditEventsAfter(db, opts) {
         .all(...params, limit);
     return rows.map(rowToAuditEvent);
 }
+/** How many of a tenant's audit rows are older than `cutoff`. */
+function countAuditBefore(db, tenantId, cutoff) {
+    // SAFETY: row comes from `SELECT COUNT(*) AS c`; COUNT(*) always yields exactly one row with a
+    // numeric `c` column (number or bigint depending on the node:sqlite driver's integer handling).
+    const row = db
+        .prepare(`SELECT COUNT(*) AS c FROM audit_log WHERE tenant_id = ? AND ts < ?`)
+        .get(tenantId, cutoff);
+    return Number(row.c);
+}
+/** Deletes a tenant's audit rows older than `cutoff`; returns how many went. */
+function deleteAuditBefore(db, tenantId, cutoff) {
+    const result = db
+        .prepare(`DELETE FROM audit_log WHERE tenant_id = ? AND ts < ?`)
+        .run(tenantId, cutoff);
+    return Number(result.changes ?? 0);
+}
+/** Latest time each target got a good outcome, from the audit rows, read on a handle of its own; unlike queryAuditEvents it has no row cap. */
+export function confirmedOutcomeTimes(hippoRoot, tenantId) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        // SAFETY: the SELECT list is exactly target_id and ts; no other shape reaches this cast.
+        const rows = db.prepare(`SELECT target_id, MAX(ts) AS ts FROM audit_log
+         WHERE tenant_id = ? AND op = 'outcome' AND target_id IS NOT NULL
+           AND json_extract(metadata_json, '$.good') = 1
+         GROUP BY target_id`).all(tenantId);
+        return new Map(rows.map((r) => [r.target_id, r.ts]));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 const AUDIT_COLUMNS = 'id, ts, tenant_id, actor, op, target_id, metadata_json';
 function rowToAuditEvent(r) {
     return {
@@ -202,21 +243,57 @@ function rowToAuditEvent(r) {
         // typed AuditOp at the INSERT call site, so every stored value is a valid AuditOp.
         op: r.op,
         targetId: r.target_id,
-        metadata: safeJsonParse(r.metadata_json),
+        metadata: safeJsonParse(r.metadata_json, r.id),
     };
 }
-function safeJsonParse(raw) {
+function safeJsonParse(raw, id) {
     try {
         const v = JSON.parse(raw);
-        // SAFETY: JSON.parse only ever returns a plain object, array, string, number,
-        // boolean, or null; `v instanceof Object` is true for exactly the first two
-        // (both are valid JsonObject shapes for our purposes), matching the prior
-        // `typeof v === 'object' && v !== null` check without using typeof.
+        // SAFETY: JSON.parse returns only an object, array or primitive; `instanceof Object` is true for the first two,
+        // both valid JsonObject shapes here.
         return v instanceof Object ? v : {};
     }
     catch {
         // Malformed metadata reads as empty so the audit row itself stays listable.
+        warnDamagedColumn({ table: 'audit_log', id, column: 'metadata_json' }, 'not valid JSON');
         return {};
     }
 }
+/** Appends each event as its own write on one handle, so a row that fails drops only itself. Returns the rows that failed, for the caller to report. */
+export function recordAuditEventsRowByRow(hippoRoot, events) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        const failed = [];
+        for (const event of events) {
+            try {
+                appendAuditEvent(db, event);
+            }
+            catch (error) {
+                failed.push({ event, error });
+            }
+        }
+        return failed;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Deletes a tenant's audit rows older than the cutoff and records the prune in the same write scope, so neither lands alone; returns the row count. */
+export function pruneAuditRows(hippoRoot, prune) {
+    const { tenantId, cutoff, actor, olderThanDays } = prune;
+    const db = openHippoDb(hippoRoot);
+    try {
+        if (prune.dryRun)
+            return countAuditBefore(db, tenantId, cutoff);
+        return withWriteScope(db, 'audit_prune', () => {
+            const count = deleteAuditBefore(db, tenantId, cutoff);
+            // Written after the delete with ts = now, so the cutoff just applied cannot take it.
+            appendAuditEvent(db, { tenantId, actor, op: 'audit_prune', metadata: { cutoff, count, dryRun: false, olderThanDays } });
+            return count;
+        });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 //# sourceMappingURL=audit.js.map