hippo-memory 1.68.0 → 1.70.0

package/dist/store/port.js

@@ -0,0 +1,17 @@
+import { StoreNotPortedError } from '../util/sqlite-blocked.js';
+/** Tells a refusal from the row a write answered; no row carries a `refused` key. */
+export function isObjectRefusal(written) {
+    return 'refused' in written;
+}
+export function hasGroup(store, group) {
+    return group === 'base' || store[group] !== undefined;
+}
+/** The group's methods; a store without them throws StoreNotPortedError, which answers 501 as any unported path does. */
+export function requireGroup(store, group) {
+    const groups = store;
+    const methods = groups[group];
+    if (methods === undefined)
+        throw new StoreNotPortedError(store.kind, group);
+    return methods;
+}
+//# sourceMappingURL=port.js.map

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

@@ -22,7 +22,9 @@
  * The planning-fallacy detector reads `loadPredictionsByClass` and computes
  * per-class base rates from (estimate_value, actual_value) at query time.
  */
-import { type KeysetPosition } from '../keyset.js';
+import { type MemoryEntry } from '../core/memory.js';
+import { type KeysetPosition } from '../util/keyset.js';
+import type { PredictionSave } from './port.js';
 export type ClosureState = 'open' | 'closed' | 'closed-unknown';
 export declare const VALID_CLOSURE_STATES: ReadonlySet<ClosureState>;
 export interface Prediction {
@@ -72,6 +74,10 @@ export interface ListPredictionsOpts {
  * structured store used by the planning-fallacy detector.
  */
 export declare function savePrediction(hippoRoot: string, tenantId: string, opts: SavePredictionOpts, actor?: string): Prediction;
+/** The memory row that mirrors a claim into recall, built here alone so every store keeps the same row for it. */
+export declare function predictionMirror(tenantId: string, claim: SavePredictionOpts, baseHalfLifeDays: number): MemoryEntry;
+/** The store port's save on hippo.db: the mirror goes in as the port's writeEntry has it, tenant check included, and its predictions row shares that write scope, so neither lands alone. */
+export declare function writePrediction(hippoRoot: string, tenantId: string, save: PredictionSave, actor: string): Prediction;
 /**
  * Close an existing open prediction. Updates the predictions row only;
  * the memory mirror is NOT mutated in v1 (predictions table is canonical).
@@ -106,6 +112,11 @@ export interface PredictionBaserate {
      *  Empty when nClosed = 0. */
     summary: string;
 }
+/** One closed prediction as the baserate reads it: both values set. */
+export interface BaserateRow {
+    estimate_value: number;
+    actual_value: number;
+}
 /**
  * Compute base-rate stats for closed predictions in a class for the
  * planning-fallacy detector: Lovallo-Kahneman (2003) inside-vs-outside view.
@@ -120,9 +131,11 @@ export declare function computePredictionBaserate(hippoRoot: string, tenantId: s
 /** False skips the predict_baserate audit so that channel only records deliberate
  *  baserate calls, not every recall the planning-fallacy orchestrator inspects. */
 emitAudit?: boolean): PredictionBaserate;
+/** A class's stats over its closed rows, summed in the order given. Every store computes them here, so no two can disagree on the arithmetic. */
+export declare function predictionBaserateOf(classTag: string, rows: readonly BaserateRow[]): PredictionBaserate;
 export declare function loadOpenPredictions(hippoRoot: string, tenantId: string, opts?: {
     classTag?: string;
     limit?: number;
     after?: KeysetPosition;
 }): Prediction[];
-//# sourceMappingURL=store.d.ts.map
+//# sourceMappingURL=predictions.d.ts.map

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

@@ -22,14 +22,15 @@
  * The planning-fallacy detector reads `loadPredictionsByClass` and computes
  * per-class base rates from (estimate_value, actual_value) at query time.
  */
-import { BadRequestError, NotFoundError } from '../api-errors.js';
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { writeEntry } from '../store/entry-writes.js';
-import { assertTenantId } from '../tenant.js';
-import { createMemory, Layer } from '../memory.js';
-import { appendAuditEvent } from '../audit.js';
-import { loadConfig } from '../config.js';
-import { keysetAfter } from '../keyset.js';
+import { BadRequestError, NotFoundError } from '../core/api-errors.js';
+import { openHippoDb, closeHippoDb, withWriteScope } from '../db/index.js';
+import { writeEntryAt } from './sqlite/entry-writes-group.js';
+import { assertTenantId } from './tenant.js';
+import { createMemory, Layer } from '../core/memory.js';
+import { appendAuditEvent } from './audit.js';
+import { loadConfig } from '../core/config.js';
+import { keysetAfter } from '../util/keyset.js';
+const DEFAULT_PREDICTION_PAGE_SIZE = 100;
 export const VALID_CLOSURE_STATES = new Set([
     'open',
     'closed',
@@ -74,25 +75,31 @@ export function savePrediction(hippoRoot, tenantId, opts, actor = 'cli') {
         throw new BadRequestError('savePrediction: classTag is required');
     if (!opts.claimText)
         throw new BadRequestError('savePrediction: claimText is required');
-    const now = new Date().toISOString();
-    const mem = createMemory(opts.claimText, {
-        tags: ['prediction', opts.classTag],
+    const mirror = predictionMirror(tenantId, opts, loadConfig(hippoRoot).defaultHalfLifeDays);
+    return writePrediction(hippoRoot, tenantId, { ...opts, mirror }, actor);
+}
+/** The memory row that mirrors a claim into recall, built here alone so every store keeps the same row for it. */
+export function predictionMirror(tenantId, claim, baseHalfLifeDays) {
+    return createMemory(claim.claimText, {
+        tags: ['prediction', claim.classTag],
         layer: Layer.Semantic,
         confidence: 'observed',
         source: 'prediction',
         // SAFETY: 'distilled' is a valid MemoryKind literal (see memory.ts).
         kind: 'distilled',
-        baseHalfLifeDays: loadConfig(hippoRoot).defaultHalfLifeDays,
+        baseHalfLifeDays,
         tenantId,
     });
+}
+/** The store port's save on hippo.db: the mirror goes in as the port's writeEntry has it, tenant check included, and its predictions row shares that write scope, so neither lands alone. */
+export function writePrediction(hippoRoot, tenantId, save, actor) {
+    assertTenantId('savePrediction', tenantId);
+    const now = new Date().toISOString();
     // Captured for the return value; populated inside afterWrite hook so the
     // INSERT and the memory write share a SAVEPOINT.
     let savedRow;
-    writeEntry(hippoRoot, mem, {
-        actor,
-        afterWrite: (db, memoryId) => {
-            savedRow = insertPredictionRow(db, memoryId, tenantId, opts, now, actor);
-        },
+    writeEntryAt(hippoRoot, { entry: save.mirror, actor }, (db, memoryId) => {
+        savedRow = insertPredictionRow(db, memoryId, tenantId, save, { now, actor });
     });
     if (!savedRow) {
         // Cannot reach here without the afterWrite throwing first; defensive.
@@ -100,8 +107,8 @@ export function savePrediction(hippoRoot, tenantId, opts, actor = 'cli') {
     }
     return rowToPrediction(savedRow);
 }
-/** Inserts, reloads and audits the predictions row inside writeEntry's SAVEPOINT. */
-function insertPredictionRow(db, memoryId, tenantId, opts, now, actor) {
+function insertPredictionRow(db, memoryId, tenantId, opts, stamp) {
+    const { now, actor } = stamp;
     const result = db.prepare(`
         INSERT INTO predictions(
           memory_id, tenant_id, class_tag, claim_text,
@@ -121,21 +128,24 @@ function insertPredictionRow(db, memoryId, tenantId, opts, now, actor) {
     if (!row) {
         throw new Error('Failed to reload saved prediction row');
     }
+    auditPredictionCreate(db, { tenantId, actor, predictionId }, opts);
+    return row;
+}
+function auditPredictionCreate(db, who, opts) {
     // GDPR-light audit metadata: prediction_id + class_tag + flags only.
     // No claim_text in metadata; the predictions table holds it canonically.
     appendAuditEvent(db, {
-        tenantId,
-        actor,
+        tenantId: who.tenantId,
+        actor: who.actor,
         op: 'predict_create',
-        targetId: String(predictionId),
+        targetId: String(who.predictionId),
         metadata: {
-            prediction_id: predictionId,
+            prediction_id: who.predictionId,
             class_tag: opts.classTag,
             has_estimate: opts.estimateValue !== undefined && opts.estimateValue !== null,
             target_date: opts.targetDate ?? null,
         },
     });
-    return row;
 }
 /**
  * Close an existing open prediction. Updates the predictions row only;
@@ -150,28 +160,16 @@ export function closePrediction(hippoRoot, tenantId, id, opts, actor = 'cli') {
     const now = new Date().toISOString();
     const db = openHippoDb(hippoRoot);
     try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const row = closeOpenPredictionRow(db, tenantId, id, opts, now, actor);
-            db.exec('COMMIT');
-            return rowToPrediction(row);
-        }
-        catch (e) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch {
-                // Ignore rollback failures — the throw below is what matters.
-            }
-            throw e;
-        }
+        const row = withWriteScope(db, 'close_prediction', () => closeOpenPredictionRow(db, tenantId, id, opts, { now, actor }));
+        return rowToPrediction(row);
     }
     finally {
         closeHippoDb(db);
     }
 }
 /** Closes the row, reloads it and audits the close; the caller owns the transaction. */
-function closeOpenPredictionRow(db, tenantId, id, opts, now, actor) {
+function closeOpenPredictionRow(db, tenantId, id, opts, stamp) {
+    const { now, actor } = stamp;
     // closure_state='open' in the WHERE stops a retried close from overwriting
     // actual_value and auditing twice; zero changed rows means not found or already closed.
     const updateResult = db.prepare(`
@@ -237,7 +235,7 @@ export function loadPredictionById(hippoRoot, tenantId, id) {
 }
 export function loadPredictionsByClass(hippoRoot, tenantId, classTag, opts = {}) {
     assertTenantId('loadPredictionsByClass', tenantId);
-    const limit = opts.limit ?? 100;
+    const limit = opts.limit ?? DEFAULT_PREDICTION_PAGE_SIZE;
     const after = keysetAfter('created_at', 'id', opts.after);
     const db = openHippoDb(hippoRoot);
     try {
@@ -290,7 +288,7 @@ export function loadAllPredictions(hippoRoot, tenantId, opts = {}) {
       WHERE tenant_id = ?${after.sql}
       ORDER BY created_at DESC, id DESC
       LIMIT ?
-    `).all(tenantId, ...after.params, opts.limit ?? 100);
+    `).all(tenantId, ...after.params, opts.limit ?? DEFAULT_PREDICTION_PAGE_SIZE);
         return rows.map(rowToPrediction);
     }
     finally {
@@ -316,6 +314,7 @@ emitAudit = true) {
         throw new BadRequestError('computePredictionBaserate: classTag is required');
     const db = openHippoDb(hippoRoot);
     try {
+        // Ordered by id because the float sums differ with row order, and another store must reach the same figures.
         // SAFETY: rows' shape matches the two columns named in the SELECT above.
         const rows = db.prepare(`
       SELECT estimate_value, actual_value
@@ -325,29 +324,12 @@ emitAudit = true) {
         AND closure_state = 'closed'
         AND estimate_value IS NOT NULL
         AND actual_value IS NOT NULL
+      ORDER BY id
     `).all(tenantId, classTag);
-        const nClosed = rows.length;
-        if (nClosed === 0) {
-            // Audit zero-result reads too — agents probing empty classes is
-            // a signal worth recording. Skipped when emitAudit=false: the orchestrator's own
-            // recall_autodebias_hint audit fires only when nClosed > 0, so no signal is lost.
-            if (emitAudit)
-                auditBaserateRead(db, tenantId, actor, classTag, 0);
-            return {
-                classTag,
-                nClosed: 0,
-                nRatioEligible: 0,
-                meanEstimate: null,
-                meanActual: null,
-                meanRatio: null,
-                p50Ratio: null,
-                mae: null,
-                summary: '',
-            };
-        }
-        const baserate = baserateFromRows(classTag, rows);
+        const baserate = predictionBaserateOf(classTag, rows);
+        // An empty class is audited too, since an agent probing one is a signal; the recall path passes false and audits its own hint.
         if (emitAudit)
-            auditBaserateRead(db, tenantId, actor, classTag, nClosed);
+            auditBaserateRead(db, tenantId, actor, classTag, baserate.nClosed);
         return baserate;
     }
     finally {
@@ -363,9 +345,12 @@ function auditBaserateRead(db, tenantId, actor, classTag, nClosed) {
         metadata: { class_tag: classTag, n_closed: nClosed },
     });
 }
-/** Stats over a non-empty set of closed rows. */
-function baserateFromRows(classTag, rows) {
+/** A class's stats over its closed rows, summed in the order given. Every store computes them here, so no two can disagree on the arithmetic. */
+export function predictionBaserateOf(classTag, rows) {
     const nClosed = rows.length;
+    if (nClosed === 0) {
+        return { classTag, nClosed: 0, nRatioEligible: 0, meanEstimate: null, meanActual: null, meanRatio: null, p50Ratio: null, mae: null, summary: '' };
+    }
     const ratioEligible = rows.filter((r) => r.estimate_value > 0);
     const nRatioEligible = ratioEligible.length;
     const meanEstimate = rows.reduce((s, r) => s + r.estimate_value, 0) / nClosed;
@@ -399,7 +384,7 @@ function baserateFromRows(classTag, rows) {
 }
 export function loadOpenPredictions(hippoRoot, tenantId, opts = {}) {
     assertTenantId('loadOpenPredictions', tenantId);
-    const limit = opts.limit ?? 100;
+    const limit = opts.limit ?? DEFAULT_PREDICTION_PAGE_SIZE;
     const after = keysetAfter('created_at', 'id', opts.after);
     const db = openHippoDb(hippoRoot);
     try {
@@ -434,4 +419,4 @@ export function loadOpenPredictions(hippoRoot, tenantId, opts = {}) {
         closeHippoDb(db);
     }
 }
-//# sourceMappingURL=store.js.map
+//# sourceMappingURL=predictions.js.map

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

@@ -1,10 +1,8 @@
-/** Quarantine tier (CD5, AT3): pending/approved/rejected record for a memory `remember` flagged as untrusted. */
-import type { DatabaseSyncLike } from './db.js';
-import { type KeysetPosition } from './keyset.js';
+import { type DatabaseSyncLike } from '../db/index.js';
+import type { QuarantineApproval, QuarantineListQuery, QuarantineRejection, QuarantinedMemory } from './port.js';
 export declare const QUARANTINE_SCOPE_PREFIX = "quarantine:private:";
 /** Scope a quarantined memory is stored under; matches PRIVATE_SCOPE_RE so every default-deny site hides it. */
 export declare function quarantineScopeFor(original: string | null): string;
-export declare function isQuarantineScope(scope: string | null | undefined): boolean;
 export type QuarantineStatus = 'pending' | 'approved' | 'rejected';
 export interface QuarantineRow {
     tenantId: string;
@@ -25,8 +23,10 @@ export interface RecordQuarantineOpts {
 }
 /** Insert the quarantine row + its audit event; caller runs this inside the memory's own write transaction. */
 export declare function recordQuarantine(db: DatabaseSyncLike, opts: RecordQuarantineOpts): void;
-export declare function getQuarantineRow(db: DatabaseSyncLike, tenantId: string, memoryId: string): QuarantineRow | null;
-export declare function listQuarantineRows(db: DatabaseSyncLike, tenantId: string, status?: QuarantineStatus | 'all', limit?: number, afterRow?: KeysetPosition): QuarantineRow[];
-export declare function approveQuarantineRow(db: DatabaseSyncLike, tenantId: string, memoryId: string, decidedBy: string): void;
-export declare function rejectQuarantineRow(db: DatabaseSyncLike, tenantId: string, memoryId: string, decidedBy: string): void;
+/** A page of the tenant's records, each with its memory's content read in the same query batch. */
+export declare function listQuarantinedAt(db: DatabaseSyncLike, tenantId: string, { status, limit, after }: QuarantineListQuery): QuarantinedMemory[];
+/** Puts the memory back under its original scope; the scope guard refuses a row moved since it was quarantined. */
+export declare function approveQuarantinedAt(db: DatabaseSyncLike, tenantId: string, id: string, actor: string): QuarantineApproval;
+/** Marks the record rejected; the memory row is left as stored. */
+export declare function rejectQuarantinedAt(db: DatabaseSyncLike, tenantId: string, id: string, actor: string): QuarantineRejection;
 //# sourceMappingURL=quarantine.d.ts.map

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

@@ -1,14 +1,13 @@
-/** Quarantine tier (CD5, AT3): pending/approved/rejected record for a memory `remember` flagged as untrusted. */
+// The memory_quarantine table: the review queue's rows, and the approve and reject writes with their audit rows.
 import { appendAuditEvent } from './audit.js';
-import { keysetAfter } from './keyset.js';
+import { withWriteScopeOr } from '../db/index.js';
+import { keysetAfter } from '../util/keyset.js';
+import { selectEntriesByIds } from './entry-reads.js';
 export const QUARANTINE_SCOPE_PREFIX = 'quarantine:private:';
 /** Scope a quarantined memory is stored under; matches PRIVATE_SCOPE_RE so every default-deny site hides it. */
 export function quarantineScopeFor(original) {
     return `${QUARANTINE_SCOPE_PREFIX}${original ?? 'unscoped'}`;
 }
-export function isQuarantineScope(scope) {
-    return scope != null && scope.startsWith(QUARANTINE_SCOPE_PREFIX);
-}
 const SELECT_COLUMNS = 'tenant_id, memory_id, original_scope, reason, status, quarantined_at, decided_at, decided_by';
 function fromDbRow(row) {
     return {
@@ -16,31 +15,19 @@ function fromDbRow(row) {
         memoryId: row.memory_id,
         originalScope: row.original_scope,
         reason: row.reason,
-        // SAFETY: this module's own INSERT/UPDATE statements are the only writers of status.
+        // SAFETY: the quarantine INSERT and this module's UPDATE statements are the only writers of status.
         status: row.status,
         quarantinedAt: row.quarantined_at,
         decidedAt: row.decided_at,
         decidedBy: row.decided_by,
     };
 }
-/** Insert the quarantine row + its audit event; caller runs this inside the memory's own write transaction. */
-export function recordQuarantine(db, opts) {
-    db.prepare(`INSERT INTO memory_quarantine (tenant_id, memory_id, original_scope, reason, status, quarantined_at)
-     VALUES (?, ?, ?, ?, 'pending', ?)`).run(opts.tenantId, opts.memoryId, opts.originalScope, opts.reason, new Date().toISOString());
-    appendAuditEvent(db, {
-        tenantId: opts.tenantId,
-        actor: opts.actor,
-        op: 'quarantine',
-        targetId: opts.memoryId,
-        metadata: { reason: opts.reason, originalScope: opts.originalScope },
-    });
-}
-export function getQuarantineRow(db, tenantId, memoryId) {
+function getQuarantineRow(db, tenantId, memoryId) {
     const row = db.prepare(`SELECT ${SELECT_COLUMNS} FROM memory_quarantine WHERE tenant_id = ? AND memory_id = ?`)
         .get(tenantId, memoryId);
     return row ? fromDbRow(row) : null;
 }
-export function listQuarantineRows(db, tenantId, status = 'pending', limit = 100, afterRow) {
+function listQuarantineRows(db, tenantId, status = 'pending', limit = 100, afterRow) {
     // A pending row whose memory was deleted (e.g. Slack message_deleted) is dead; keep its history, drop it from the queue.
     const live = status === 'pending'
         ? ' AND EXISTS (SELECT 1 FROM memories m WHERE m.id = memory_quarantine.memory_id AND m.tenant_id = memory_quarantine.tenant_id)'
@@ -55,12 +42,67 @@ export function listQuarantineRows(db, tenantId, status = 'pending', limit = 100
     // SAFETY: both branches select SELECT_COLUMNS, matching QuarantineDbRow's field set.
     return rows.map(fromDbRow);
 }
-export function approveQuarantineRow(db, tenantId, memoryId, decidedBy) {
+/** Insert the quarantine row + its audit event; caller runs this inside the memory's own write transaction. */
+export function recordQuarantine(db, opts) {
+    db.prepare(`INSERT INTO memory_quarantine (tenant_id, memory_id, original_scope, reason, status, quarantined_at)
+     VALUES (?, ?, ?, ?, 'pending', ?)`).run(opts.tenantId, opts.memoryId, opts.originalScope, opts.reason, new Date().toISOString());
+    appendAuditEvent(db, {
+        tenantId: opts.tenantId,
+        actor: opts.actor,
+        op: 'quarantine',
+        targetId: opts.memoryId,
+        metadata: { reason: opts.reason, originalScope: opts.originalScope },
+    });
+}
+function approveQuarantineRow(db, tenantId, memoryId, decidedBy) {
     db.prepare(`UPDATE memory_quarantine SET status = 'approved', decided_at = ?, decided_by = ? WHERE tenant_id = ? AND memory_id = ?`)
         .run(new Date().toISOString(), decidedBy, tenantId, memoryId);
 }
-export function rejectQuarantineRow(db, tenantId, memoryId, decidedBy) {
+function rejectQuarantineRow(db, tenantId, memoryId, decidedBy) {
     db.prepare(`UPDATE memory_quarantine SET status = 'rejected', decided_at = ?, decided_by = ? WHERE tenant_id = ? AND memory_id = ?`)
         .run(new Date().toISOString(), decidedBy, tenantId, memoryId);
 }
+/** A page of the tenant's records, each with its memory's content read in the same query batch. */
+export function listQuarantinedAt(db, tenantId, { status, limit, after }) {
+    const rows = listQuarantineRows(db, tenantId, status, limit, after);
+    const entries = selectEntriesByIds(db, rows.map((row) => row.memoryId), tenantId);
+    return rows.map((row) => ({ ...row, content: entries.get(row.memoryId)?.content ?? null }));
+}
+/** The pending record, or why a decision on `id` is refused. */
+function pendingOrRefusal(db, tenantId, id) {
+    const row = getQuarantineRow(db, tenantId, id);
+    if (!row)
+        return { outcome: 'not_quarantined' };
+    if (row.status !== 'pending')
+        return { outcome: 'already_decided', status: row.status };
+    return row;
+}
+/** Puts the memory back under its original scope; the scope guard refuses a row moved since it was quarantined. */
+export function approveQuarantinedAt(db, tenantId, id, actor) {
+    return withWriteScopeOr(db, 'quarantine_approve', (rollback) => {
+        const row = pendingOrRefusal(db, tenantId, id);
+        if ('outcome' in row)
+            return rollback(row);
+        const quarantineScope = quarantineScopeFor(row.originalScope);
+        const updated = db
+            .prepare(`UPDATE memories SET scope = ? WHERE id = ? AND tenant_id = ? AND scope = ?`)
+            .run(row.originalScope, id, tenantId, quarantineScope);
+        if (Number(updated.changes ?? 0) !== 1)
+            return rollback({ outcome: 'scope_moved' });
+        approveQuarantineRow(db, tenantId, id, actor);
+        appendAuditEvent(db, { tenantId, actor, op: 'quarantine_approve', targetId: id, metadata: { originalScope: row.originalScope } });
+        return { outcome: 'approved' };
+    });
+}
+/** Marks the record rejected; the memory row is left as stored. */
+export function rejectQuarantinedAt(db, tenantId, id, actor) {
+    return withWriteScopeOr(db, 'quarantine_reject', (rollback) => {
+        const row = pendingOrRefusal(db, tenantId, id);
+        if ('outcome' in row)
+            return rollback(row);
+        rejectQuarantineRow(db, tenantId, id, actor);
+        appendAuditEvent(db, { tenantId, actor, op: 'quarantine_reject', targetId: id, metadata: {} });
+        return { outcome: 'rejected' };
+    });
+}
 //# sourceMappingURL=quarantine.js.map

package/dist/{raw-archive.d.ts → store/raw-archive.d.ts}

@@ -1,4 +1,4 @@
-import type { DatabaseSyncLike } from './db.js';
+import type { DatabaseSyncLike } from '../db/index.js';
 export interface ArchiveOpts {
     reason: string;
     who: string;
@@ -11,6 +11,8 @@ export interface ArchiveOpts {
      */
     afterArchive?: (db: DatabaseSyncLike, archivedMemoryId: string) => void;
 }
+/** Stamps the archived copy of `memoryId` as having its markdown mirror cleaned at `at`. */
+export declare function markMirrorCleaned(db: DatabaseSyncLike, memoryId: string, at: string): void;
 /**
  * The only legitimate path to remove a `kind='raw'` row from `memories`.
  *
@@ -18,7 +20,7 @@ export interface ArchiveOpts {
  * append-only trigger lets the delete through, then deletes the row. All in one
  * write scope, which nests inside an outer transaction (e.g. batchWriteAndDelete).
  *
- * Throws if the row does not exist or is not `kind='raw'`.
+ * Throws if the row does not exist or is not `kind='raw'`. Returns the archived_at it wrote.
  */
-export declare function archiveRawMemory(db: DatabaseSyncLike, id: string, opts: ArchiveOpts): void;
+export declare function archiveRawMemory(db: DatabaseSyncLike, id: string, opts: ArchiveOpts): string;
 //# sourceMappingURL=raw-archive.d.ts.map

package/dist/{raw-archive.js → store/raw-archive.js}

@@ -1,7 +1,11 @@
-import { BadRequestError, NotFoundError } from './api-errors.js';
-import { isFtsAvailable, withWriteScope } from './db.js';
+import { BadRequestError, NotFoundError } from '../core/api-errors.js';
+import { isFtsAvailable, withWriteScope } from '../db/index.js';
 import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
 import { markSummaryDirtyInTx } from './summary-dirty.js';
+/** Stamps the archived copy of `memoryId` as having its markdown mirror cleaned at `at`. */
+export function markMirrorCleaned(db, memoryId, at) {
+    db.prepare(`UPDATE raw_archive SET mirror_cleaned_at = ? WHERE memory_id = ?`).run(at, memoryId);
+}
 function loadRawRow(db, id) {
     // SAFETY: SELECT * FROM memories returns every column of the memories table; only
     // kind, tenant_id, and dag_parent_id are read below, all guaranteed present (possibly
@@ -34,6 +38,7 @@ function moveRowToArchive(db, id, row, opts) {
     // Archived text must be unsearchable at commit, so a failed purge fails (and rolls back) the whole archive.
     if (isFtsAvailable(db))
         db.prepare(`DELETE FROM memories_fts WHERE id = ?`).run(id);
+    return archivedAt;
 }
 // Emit the archive_raw audit event inside the SAVEPOINT so the audit row is
 // committed atomically with the row deletion. Use the row's own tenant_id
@@ -62,14 +67,14 @@ function auditArchive(db, id, row, opts) {
  * append-only trigger lets the delete through, then deletes the row. All in one
  * write scope, which nests inside an outer transaction (e.g. batchWriteAndDelete).
  *
- * Throws if the row does not exist or is not `kind='raw'`.
+ * Throws if the row does not exist or is not `kind='raw'`. Returns the archived_at it wrote.
  */
 export function archiveRawMemory(db, id, opts) {
     const row = loadRawRow(db, id);
     // A SAVEPOINT when already inside a transaction (e.g. batchWriteAndDelete), so a throw here
     // rolls back only this archive.
-    withWriteScope(db, 'archive_raw', () => {
-        moveRowToArchive(db, id, row, opts);
+    return withWriteScope(db, 'archive_raw', () => {
+        const archivedAt = moveRowToArchive(db, id, row, opts);
         auditArchive(db, id, row, opts);
         // Archiving a child under a level-2 summary marks the parent dirty, inside the
         // SAVEPOINT so the dirty-mark commits atomically with the archive.
@@ -84,6 +89,7 @@ export function archiveRawMemory(db, id, opts) {
         if (opts.afterArchive) {
             opts.afterArchive(db, id);
         }
+        return archivedAt;
     });
 }
 //# sourceMappingURL=raw-archive.js.map

package/dist/{recall-scope.d.ts → store/recall-scope.d.ts}

@@ -5,11 +5,11 @@
  * these for its own call sites AND re-exports them for back-compat
  * (`api.isPrivateScope`, test imports of `passesScopeFilterForRecall`).
  */
-import { ForbiddenError } from './api-errors.js';
+import { ForbiddenError } from '../core/api-errors.js';
 /**
  * Literal scopes excluded from recall by default-deny when the
  * caller passes no `scope`. The SQL clause in `loadSearchRows` and the JS
- * helper `passesScopeFilterForRecall` (src/api.ts) both read from this
+ * helper `passesScopeFilterForRecall` (src/api/index.ts) both read from this
  * constant. Adding a deny scope is a one-place change.
  *
  * Regex-based denies (e.g. `<source>:private:*`) stay in
@@ -60,6 +60,8 @@ export declare function assertClientScope(scope: string | null | undefined): voi
 export declare function canTouchScope(actor: {
     owner?: string;
 }, scope: string | null): boolean;
+/** canTouchScope for a caller known by its own personal scope, as a store method receives it. */
+export declare function ownScopeTouches(ownScope: string | null, scope: string | null): boolean;
 /**
  * Recall-side scope filter — the canonical JS half of the recall default-deny
  * rule (the SQL half lives in `loadSearchRows` via `loadRecallSearchEntries`).
@@ -68,11 +70,6 @@ export declare function canTouchScope(actor: {
  * - When `requested` is undefined/empty: default-deny on any
  *   `<source>:private:*` scope and on the `RECALL_DEFAULT_DENY_SCOPES`
  *   quarantine buckets. `null` and public scopes pass, and so does `ownScope`, the caller's own personal scope.
- *
- * @internal Exported for test parity with
- * `RECALL_DEFAULT_DENY_SCOPES` (single-source-of-truth verification). NOT part
- * of the public API surface; not re-exported from `src/index.ts`. Subject to
- * change without semver bump.
  */
 export declare function passesScopeFilterForRecall(scope: string | null, requested: string | undefined, ownScope?: string | null): boolean;
 export interface SqlFragment {

package/dist/{recall-scope.js → store/recall-scope.js}

@@ -5,12 +5,12 @@
  * these for its own call sites AND re-exports them for back-compat
  * (`api.isPrivateScope`, test imports of `passesScopeFilterForRecall`).
  */
-import { BadRequestError, ForbiddenError } from './api-errors.js';
-import { MAX_ID_LEN } from './http-util.js';
+import { BadRequestError, ForbiddenError } from '../core/api-errors.js';
+import { MAX_ID_LEN } from '../util/http-util.js';
 /**
  * Literal scopes excluded from recall by default-deny when the
  * caller passes no `scope`. The SQL clause in `loadSearchRows` and the JS
- * helper `passesScopeFilterForRecall` (src/api.ts) both read from this
+ * helper `passesScopeFilterForRecall` (src/api/index.ts) both read from this
  * constant. Adding a deny scope is a one-place change.
  *
  * Regex-based denies (e.g. `<source>:private:*`) stay in
@@ -83,7 +83,11 @@ export function assertClientScope(scope) {
 }
 /** True when `actor` may change or delete a row in `scope`: any non-personal scope, or its own personal one. */
 export function canTouchScope(actor, scope) {
-    return !isPersonalScope(scope) || scope === personalScopeOf(actor);
+    return ownScopeTouches(personalScopeOf(actor), scope);
+}
+/** canTouchScope for a caller known by its own personal scope, as a store method receives it. */
+export function ownScopeTouches(ownScope, scope) {
+    return !isPersonalScope(scope) || scope === ownScope;
 }
 /**
  * Recall-side scope filter — the canonical JS half of the recall default-deny
@@ -93,11 +97,6 @@ export function canTouchScope(actor, scope) {
  * - When `requested` is undefined/empty: default-deny on any
  *   `<source>:private:*` scope and on the `RECALL_DEFAULT_DENY_SCOPES`
  *   quarantine buckets. `null` and public scopes pass, and so does `ownScope`, the caller's own personal scope.
- *
- * @internal Exported for test parity with
- * `RECALL_DEFAULT_DENY_SCOPES` (single-source-of-truth verification). NOT part
- * of the public API surface; not re-exported from `src/index.ts`. Subject to
- * change without semver bump.
  */
 export function passesScopeFilterForRecall(scope, requested, ownScope) {
     if (requested !== undefined && requested !== '') {