@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/node_modules/@boombot/core/memory/scope-resolver.js

@@ -0,0 +1,60 @@
+import { principalScope } from './provider.js';
+import { GLOBAL_SCOPE } from './types.js';
+export function conversationScope(channel, chatId) {
+    return { kind: 'conversation', id: `${channel}:${chatId}` };
+}
+export function groupScope(groupName) {
+    return { kind: 'group', id: groupName };
+}
+export class ScopeResolver {
+    /**
+     * Resolve scopes visible to this turn:
+     * - Global scope (public facts)
+     * - Principal scope (the local agent)
+     * - Sender scope (if user authenticated)
+     * - Group scope (if group assigned)
+     * - Conversation scope (channel + chatId)
+     */
+    resolveReadableScopes(ctx, principalId) {
+        const scopes = [GLOBAL_SCOPE, principalScope(principalId)];
+        if (ctx.senderId) {
+            scopes.push(principalScope(ctx.senderId));
+        }
+        if (ctx.group) {
+            scopes.push(groupScope(ctx.group));
+        }
+        if (ctx.channel && ctx.chatId) {
+            scopes.push(conversationScope(ctx.channel, ctx.chatId));
+        }
+        else if (ctx.channel) {
+            scopes.push(principalScope(`channel:${ctx.channel}`));
+        }
+        return Object.freeze(scopes);
+    }
+    /**
+     * Determine target scope for writing a new memory note.
+     * Default rule: narrowest scope first (conversation > group > sender > channel).
+     * Global scope is strictly reserved for operators.
+     */
+    resolveWritableScope(ctx, requestedScope) {
+        if (requestedScope?.kind === 'global') {
+            if (ctx.isOperator === true) {
+                return GLOBAL_SCOPE;
+            }
+            // Non-operator requesting global is demoted to narrowest scope
+        }
+        if (ctx.channel && ctx.chatId) {
+            return conversationScope(ctx.channel, ctx.chatId);
+        }
+        if (ctx.group) {
+            return groupScope(ctx.group);
+        }
+        if (ctx.senderId) {
+            return principalScope(ctx.senderId);
+        }
+        if (ctx.channel) {
+            return principalScope(`channel:${ctx.channel}`);
+        }
+        return GLOBAL_SCOPE;
+    }
+}

package/dist/node_modules/@boombot/core/memory/search.d.ts

@@ -0,0 +1,37 @@
+import { type MemoryStore } from './store.js';
+import { type MatchMode, type SearchHit, type SearchOptions } from './types.js';
+/** Default snippet markers: visible, and NOT html (no XSS vector). */
+export declare const DEFAULT_HIGHLIGHT_START = "\u27E8";
+export declare const DEFAULT_HIGHLIGHT_END = "\u27E9";
+/**
+ * Reduce raw input to safe search terms. Throws on empty / overlong input.
+ * This is the single choke point between user input and the FTS engine.
+ */
+export declare function extractTerms(rawQuery: string): string[];
+/**
+ * Build a safe FTS5 MATCH expression from sanitized terms.
+ * Each term becomes a quoted prefix phrase: `"term"*`.
+ * Terms are guaranteed `[\p{L}\p{N}]+`, so no quoting/escaping is needed and
+ * no FTS5 syntax can be smuggled in.
+ */
+export declare function buildSafeMatchQuery(rawQuery: string, match?: MatchMode): string;
+export interface PrincipalSearchOptions {
+    query: string;
+    limit?: number;
+    match?: MatchMode;
+    highlightStart?: string;
+    highlightEnd?: string;
+}
+/**
+ * Convenience wrapper that composes the only scopes a principal may ever
+ * see: their own principal scope plus the shared global scope. Hosts should
+ * prefer this (or `recallMemory` with a derived `MemoryAuthorization`) over
+ * hand-rolling scope lists.
+ */
+export declare function searchForPrincipal(store: MemoryStore, principalId: string, options: PrincipalSearchOptions): SearchHit[];
+/**
+ * Full-text search restricted to the given authorized scopes.
+ * Ranking: FTS5 bm25 (lower = more relevant), tie-broken by
+ * created_at DESC, id ASC — deterministic for identical committed state.
+ */
+export declare function search(store: MemoryStore, options: SearchOptions): SearchHit[];

package/dist/node_modules/@boombot/core/memory/search.js

@@ -0,0 +1,158 @@
+/**
+ * Scoped full-text search over the FTS5 index.
+ *
+ * SECURITY MODEL
+ * --------------
+ * 1. The raw user query NEVER reaches `MATCH`. `extractTerms()` reduces input
+ *    to unicode letter/number tokens; `buildSafeMatchQuery()` re-assembles a
+ *    phrase/prefix query from those tokens only. FTS5 metacharacters (`*`,
+ *    `"`, `:`, `OR`/`AND`/`NOT`/`NEAR`, column filters like `text:`, braces)
+ *    cannot survive tokenization, so injection is neutralized by construction.
+ * 2. Every query carries an explicit, host-authorized scope list. Results are
+ *    restricted to the union of those scopes — a principal can never observe
+ *    another principal's records, even with a matching query.
+ * 3. Tombstoned rows are excluded twice: the sync triggers keep them out of
+ *    the FTS index, and the query predicate filters them again (defense in
+ *    depth against a corrupt/manual index rebuild).
+ * 4. Resource bounds: query length, term count, and result limit are capped.
+ * 5. TIMING EXISTENCE ORACLE (low, ACCEPTED RISK — documented, not fixed):
+ *    SQLite evaluates the FTS5 MATCH (posting-list traversal over the whole
+ *    index) BEFORE the scope predicate. A term matching an OUT-OF-SCOPE
+ *    record therefore costs slightly more (~28µs measured on 2k records)
+ *    than a term matching nothing, so a caller with direct search access, a
+ *    high-resolution clock, and thousands of samples can distinguish "term
+ *    exists somewhere out of scope" from "term exists nowhere".
+ *    Why not fixed structurally:
+ *    - A "two-phase" query (scope-restricted rowid set first, then MATCH
+ *      constrained to it) does NOT remove the signal: the FTS engine still
+ *      traverses the posting list for the term before the rowid filter
+ *      applies, so the per-match FTS work — the source of the delta — is
+ *      unchanged. It only adds a second query's worth of noise.
+ *    - Constant-time FTS is not achievable: match cost inherently depends on
+ *      posting-list length.
+ *    - Snippet/bm25 are already computed ONLY for rows passing the scope
+ *      predicate (WHERE filters before SELECT evaluation), so the residual
+ *      delta is FTS-internals only.
+ *    Exploitability remains LOW: single-shot measurements are
+ *    indistinguishable (asserted by test); only statistical sampling over
+ *    thousands of interleaved queries leaks existence (never content), and
+ *    only to a caller the host already granted direct search access.
+ */
+import {} from 'node:sqlite';
+import { validationError } from './errors.js';
+import { validateScope } from './store.js';
+import { GLOBAL_SCOPE, MAX_QUERY_CHARS, MAX_QUERY_TERMS, MAX_SEARCH_LIMIT, MAX_SNIPPET_TOKENS, } from './types.js';
+/** Default snippet markers: visible, and NOT html (no XSS vector). */
+export const DEFAULT_HIGHLIGHT_START = '\u27e8'; // ⟨
+export const DEFAULT_HIGHLIGHT_END = '\u27e9'; // ⟩
+const SNIPPET_ELLIPSIS = '\u2026'; // …
+/** Unicode letters/numbers only — every FTS5 metacharacter is dropped. */
+const TERM_PATTERN = /[\p{L}\p{N}]+/gu;
+/**
+ * Reduce raw input to safe search terms. Throws on empty / overlong input.
+ * This is the single choke point between user input and the FTS engine.
+ */
+export function extractTerms(rawQuery) {
+    if (typeof rawQuery !== 'string')
+        throw validationError('query must be a string');
+    const trimmed = rawQuery.trim();
+    if (trimmed.length === 0)
+        throw validationError('query must not be empty');
+    if (trimmed.length > MAX_QUERY_CHARS) {
+        throw validationError(`query exceeds ${MAX_QUERY_CHARS} characters`);
+    }
+    const terms = trimmed.match(TERM_PATTERN) ?? [];
+    if (terms.length === 0) {
+        throw validationError('query contains no searchable terms');
+    }
+    if (terms.length > MAX_QUERY_TERMS) {
+        throw validationError(`query exceeds ${MAX_QUERY_TERMS} terms`);
+    }
+    return terms;
+}
+/**
+ * Build a safe FTS5 MATCH expression from sanitized terms.
+ * Each term becomes a quoted prefix phrase: `"term"*`.
+ * Terms are guaranteed `[\p{L}\p{N}]+`, so no quoting/escaping is needed and
+ * no FTS5 syntax can be smuggled in.
+ */
+export function buildSafeMatchQuery(rawQuery, match = 'any') {
+    const terms = extractTerms(rawQuery);
+    const joiner = match === 'all' ? ' AND ' : ' OR ';
+    return terms.map((t) => `"${t}"*`).join(joiner);
+}
+/**
+ * Convenience wrapper that composes the only scopes a principal may ever
+ * see: their own principal scope plus the shared global scope. Hosts should
+ * prefer this (or `recallMemory` with a derived `MemoryAuthorization`) over
+ * hand-rolling scope lists.
+ */
+export function searchForPrincipal(store, principalId, options) {
+    if (typeof principalId !== 'string' || principalId.length === 0) {
+        throw validationError('principalId is required');
+    }
+    return search(store, {
+        query: options.query,
+        scopes: [
+            { kind: 'principal', id: principalId },
+            GLOBAL_SCOPE,
+        ],
+        limit: options.limit,
+        match: options.match,
+        highlightStart: options.highlightStart,
+        highlightEnd: options.highlightEnd,
+    });
+}
+/**
+ * Full-text search restricted to the given authorized scopes.
+ * Ranking: FTS5 bm25 (lower = more relevant), tie-broken by
+ * created_at DESC, id ASC — deterministic for identical committed state.
+ */
+export function search(store, options) {
+    if (options.scopes.length === 0)
+        throw validationError('at least one scope is required');
+    for (const scope of options.scopes)
+        validateScope(scope);
+    const matchQuery = buildSafeMatchQuery(options.query, options.match ?? 'any');
+    const limit = Math.min(Math.max(Math.floor(options.limit ?? 20), 1), MAX_SEARCH_LIMIT);
+    const hlStart = options.highlightStart ?? DEFAULT_HIGHLIGHT_START;
+    const hlEnd = options.highlightEnd ?? DEFAULT_HIGHLIGHT_END;
+    if (hlStart.length > 16 || hlEnd.length > 16) {
+        throw validationError('highlight markers must be at most 16 chars');
+    }
+    const scopeClauses = [];
+    // Placeholder order in the SQL below: snippet markers, MATCH, scopes, LIMIT.
+    const params = [hlStart, hlEnd, matchQuery];
+    for (const scope of options.scopes) {
+        scopeClauses.push('(m.scope_kind = ? AND m.scope_id = ?)');
+        params.push(scope.kind, scope.id);
+    }
+    params.push(limit);
+    const rows = store
+        .raw()
+        .prepare(
+    // NOTE: the FTS5 table is referenced by its real name everywhere —
+    // this SQLite build does not resolve an alias inside MATCH/bm25/snippet.
+    `SELECT m.id, m.scope_kind, m.scope_id, m.text, m.provenance_json,
+              m.created_at, bm25(memory_fts) AS rank,
+              snippet(memory_fts, 0, ?, ?, '${SNIPPET_ELLIPSIS}', ${MAX_SNIPPET_TOKENS}) AS snippet
+       FROM memory_fts
+       JOIN memory_records AS m ON m.rowid = memory_fts.rowid
+       WHERE memory_fts MATCH ?
+         AND (${scopeClauses.join(' OR ')})
+         AND m.tombstoned_at IS NULL
+         AND m.deleted_at IS NULL
+       ORDER BY rank ASC, m.created_at DESC, m.id ASC
+       LIMIT ?`)
+        .all(...params);
+    return rows.map((row) => {
+        const record = {
+            id: row.id,
+            scope: { kind: row.scope_kind, id: row.scope_id },
+            text: row.text,
+            provenance: JSON.parse(row.provenance_json),
+            createdAt: row.created_at,
+        };
+        return { record, score: row.rank, snippet: row.snippet };
+    });
+}

package/dist/node_modules/@boombot/core/memory/store.d.ts

@@ -0,0 +1,60 @@
+import { DatabaseSync } from 'node:sqlite';
+import { type MemoryAuditEntry, type MemoryProvenance, type MemoryRecord, type MemoryScope } from './types.js';
+export declare const SCHEMA_VERSION = 1;
+export declare function validateScope(scope: MemoryScope): void;
+export declare function validateText(text: string): void;
+/** Redacted view: the full record minus its text (safe for non-audit code paths). */
+export interface RedactedMemoryRecord extends Omit<MemoryRecord, 'text'> {
+    readonly text: '[REDACTED]';
+}
+export interface CreateRecordInput {
+    id?: string;
+    scope: MemoryScope;
+    text: string;
+    provenance: MemoryProvenance;
+    createdAt?: string;
+    actorId: string;
+}
+export declare class MemoryStore {
+    private readonly db;
+    private closed;
+    private constructor();
+    /** Open (or create) a store. Runs the schema migration exactly once. */
+    static open(path: string): MemoryStore;
+    /** Direct access for the sibling modules (search/indexer/lifecycle). */
+    pin(recordId: string, scope: MemoryScope): void;
+    unpin(recordId: string, scope: MemoryScope): void;
+    isPinned(recordId: string, scope: MemoryScope): boolean;
+    raw(): DatabaseSync;
+    close(): void;
+    private assertOpen;
+    /** Insert a record and index it. Idempotent on duplicate id → CONFLICT. */
+    create(input: CreateRecordInput): MemoryRecord;
+    /**
+     * Privileged read by id, INCLUDING tombstoned rows (audit visibility).
+     *
+     * SECURITY FIX (tombstone bypass via privileged API, low): the old
+     * `get(id)` returned tombstoned rows WITH full text and was NOT
+     * scope-checked — any host code path that reached it could trivially
+     * bypass revocation (`get(revokedId).text`). The rename forces every
+     * caller to acknowledge the privilege, and the text is stripped unless
+     * the caller explicitly passes `{ forAudit: true }` (the audit
+     * capability). NEVER expose this to principals or plugins.
+     */
+    getForAudit(id: string, options: {
+        forAudit: true;
+    }): MemoryRecord | undefined;
+    getForAudit(id: string, options?: {
+        forAudit?: false;
+    }): RedactedMemoryRecord | undefined;
+    /** Raw row update used by lifecycle (tombstone). Bypasses FTS only via trigger. */
+    markTombstoned(id: string, at: string): void;
+    /** Physical removal; the AFTER DELETE trigger purges the FTS entry. */
+    hardDelete(id: string): void;
+    insertAudit(auditId: string, memoryId: string, action: MemoryAuditEntry['action'], actorId: string, at: string, detail: string): void;
+    auditFor(memoryId: string): MemoryAuditEntry[];
+    /** Number of live (indexable) rows. */
+    countLive(): number;
+    /** Number of rows currently in the FTS index. */
+    countIndexed(): number;
+}

package/dist/node_modules/@boombot/core/memory/store.js

@@ -0,0 +1,289 @@
+/**
+ * SQLite store for memory records + FTS5 index.
+ *
+ * Schema is intentionally aligned with the repo's `memory_records` table
+ * (migration 2 in `src/storage/migrations.ts`) so this module can later land
+ * as migration 7: same `memory_records` shape, plus a `memory_fts` virtual
+ * table kept in sync by triggers. Triggers only index rows where
+ * `tombstoned_at IS NULL AND deleted_at IS NULL`, so revocation immediately
+ * removes a record from search while the row (audit trail) survives.
+ *
+ * Only `node:sqlite` (Node >= 22) is used. The database handle is
+ * synchronous; callers must not run it on a latency-sensitive event loop —
+ * the BoomBot spec requires recall to stay off the Gateway event loop.
+ */
+import { randomUUID } from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+import { MemoryFtsError, validationError } from './errors.js';
+import { MAX_SCOPE_ID_CHARS, MAX_TEXT_BYTES, } from './types.js';
+export const SCHEMA_VERSION = 1;
+const DDL = `
+CREATE TABLE memory_records (
+  id TEXT PRIMARY KEY,
+  scope_kind TEXT NOT NULL CHECK (scope_kind IN ('principal', 'session', 'global', 'conversation', 'group')),
+  scope_id TEXT NOT NULL,
+  text TEXT NOT NULL,
+  provenance_json TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  tombstoned_at TEXT,
+  deleted_at TEXT
+);
+
+CREATE INDEX memory_records_scope_order
+  ON memory_records (scope_kind, scope_id, created_at DESC, id ASC);
+
+CREATE VIRTUAL TABLE memory_fts USING fts5(
+  text,
+  memory_id UNINDEXED,
+  tokenize = 'unicode61'
+);
+
+-- Keep the FTS index in sync. Only live rows are indexed; tombstoned or
+-- soft-deleted rows are removed from the index but kept in memory_records
+-- as the audit trail.
+CREATE TRIGGER memory_fts_after_insert AFTER INSERT ON memory_records
+WHEN NEW.tombstoned_at IS NULL AND NEW.deleted_at IS NULL
+BEGIN
+  INSERT INTO memory_fts (rowid, text, memory_id)
+  VALUES (NEW.rowid, NEW.text, NEW.id);
+END;
+
+CREATE TRIGGER memory_fts_after_delete AFTER DELETE ON memory_records
+BEGIN
+  DELETE FROM memory_fts WHERE rowid = OLD.rowid;
+END;
+
+CREATE TRIGGER memory_fts_after_update_delete AFTER UPDATE ON memory_records
+BEGIN
+  DELETE FROM memory_fts WHERE rowid = OLD.rowid;
+END;
+
+CREATE TRIGGER memory_fts_after_update_insert AFTER UPDATE ON memory_records
+WHEN NEW.tombstoned_at IS NULL AND NEW.deleted_at IS NULL
+BEGIN
+  INSERT INTO memory_fts (rowid, text, memory_id)
+  VALUES (NEW.rowid, NEW.text, NEW.id);
+END;
+
+CREATE TABLE memory_audit (
+  audit_id TEXT PRIMARY KEY,
+  memory_id TEXT NOT NULL,
+  action TEXT NOT NULL CHECK (action IN ('create', 'revoke', 'forget', 'reindex')),
+  actor_id TEXT NOT NULL,
+  at TEXT NOT NULL,
+  detail TEXT NOT NULL
+);
+
+CREATE INDEX memory_audit_record ON memory_audit (memory_id, at DESC);
+`;
+const SCOPE_KINDS = ['principal', 'session', 'global', 'conversation', 'group'];
+export function validateScope(scope) {
+    if (!SCOPE_KINDS.includes(scope.kind)) {
+        throw validationError(`invalid scope kind '${String(scope.kind)}'`);
+    }
+    if (typeof scope.id !== 'string' || scope.id.length === 0) {
+        throw validationError('scope id must be a non-empty string');
+    }
+    if (scope.id.length > MAX_SCOPE_ID_CHARS) {
+        throw validationError(`scope id exceeds ${MAX_SCOPE_ID_CHARS} chars`);
+    }
+}
+export function validateText(text) {
+    if (typeof text !== 'string' || text.length === 0) {
+        throw validationError('memory text must be a non-empty string');
+    }
+    if (Buffer.byteLength(text, 'utf8') > MAX_TEXT_BYTES) {
+        throw validationError(`memory text exceeds ${MAX_TEXT_BYTES} bytes`);
+    }
+}
+function rowToRecord(row) {
+    const record = {
+        id: row.id,
+        scope: { kind: row.scope_kind, id: row.scope_id },
+        text: row.text,
+        provenance: JSON.parse(row.provenance_json),
+        createdAt: row.created_at,
+    };
+    if (row.tombstoned_at !== null)
+        record.tombstonedAt = row.tombstoned_at;
+    return record;
+}
+export class MemoryStore {
+    db;
+    closed = false;
+    constructor(db) {
+        this.db = db;
+    }
+    /** Open (or create) a store. Runs the schema migration exactly once. */
+    static open(path) {
+        const db = new DatabaseSync(path);
+        try {
+            db.exec('PRAGMA journal_mode = WAL;');
+            db.exec(`CREATE TABLE IF NOT EXISTS memory_pins (
+           record_id TEXT NOT NULL,
+           scope_kind TEXT NOT NULL,
+           scope_id TEXT NOT NULL,
+           pinned_at TEXT NOT NULL,
+           PRIMARY KEY (record_id, scope_kind, scope_id)
+         )`);
+            db.exec(`CREATE TABLE IF NOT EXISTS schema_version (
+           version INTEGER PRIMARY KEY,
+           applied_at TEXT NOT NULL
+         )`);
+            const row = db
+                .prepare(`SELECT version AS v FROM schema_version ORDER BY version DESC LIMIT 1`)
+                .get();
+            if (row === undefined) {
+                db.exec(DDL);
+                db.prepare(`INSERT INTO schema_version (version, applied_at) VALUES (?, ?)`).run(SCHEMA_VERSION, new Date().toISOString());
+            }
+            else if (row.v > SCHEMA_VERSION) {
+                throw new MemoryFtsError('MEMORY_FTS_STORAGE', `memory database schema version ${row.v} is newer than supported ${SCHEMA_VERSION}`);
+            }
+            // Guard against a half-applied schema (e.g. crash mid-DDL on first open).
+            const fts = db
+                .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'memory_fts'`)
+                .get();
+            if (fts === undefined) {
+                throw new MemoryFtsError('MEMORY_FTS_STORAGE', 'memory_fts virtual table is missing');
+            }
+            return new MemoryStore(db);
+        }
+        catch (error) {
+            db.close();
+            throw error;
+        }
+    }
+    /** Direct access for the sibling modules (search/indexer/lifecycle). */
+    pin(recordId, scope) {
+        this.assertOpen();
+        validateScope(scope);
+        this.db
+            .prepare(`INSERT OR REPLACE INTO memory_pins (record_id, scope_kind, scope_id, pinned_at) VALUES (?, ?, ?, ?)`)
+            .run(recordId, scope.kind, scope.id, new Date().toISOString());
+    }
+    unpin(recordId, scope) {
+        this.assertOpen();
+        validateScope(scope);
+        this.db
+            .prepare(`DELETE FROM memory_pins WHERE record_id = ? AND scope_kind = ? AND scope_id = ?`)
+            .run(recordId, scope.kind, scope.id);
+    }
+    isPinned(recordId, scope) {
+        this.assertOpen();
+        validateScope(scope);
+        const row = this.db
+            .prepare(`SELECT 1 FROM memory_pins WHERE record_id = ? AND scope_kind = ? AND scope_id = ? LIMIT 1`)
+            .get(recordId, scope.kind, scope.id);
+        return row !== undefined;
+    }
+    raw() {
+        this.assertOpen();
+        return this.db;
+    }
+    close() {
+        if (!this.closed) {
+            this.closed = true;
+            this.db.close();
+        }
+    }
+    assertOpen() {
+        if (this.closed)
+            throw new MemoryFtsError('MEMORY_FTS_STORAGE', 'memory store is closed');
+    }
+    /** Insert a record and index it. Idempotent on duplicate id → CONFLICT. */
+    create(input) {
+        this.assertOpen();
+        validateScope(input.scope);
+        validateText(input.text);
+        const id = input.id ?? randomUUID();
+        if (id.length === 0 || id.length > 256)
+            throw validationError('invalid record id');
+        const createdAt = input.createdAt ?? new Date().toISOString();
+        const provenance = {
+            source: input.provenance.source,
+            reference: input.provenance.reference,
+            actorId: input.provenance.actorId,
+            at: input.provenance.at,
+        };
+        try {
+            this.db
+                .prepare(`INSERT INTO memory_records
+             (id, scope_kind, scope_id, text, provenance_json, created_at)
+           VALUES (?, ?, ?, ?, ?, ?)`)
+                .run(id, input.scope.kind, input.scope.id, input.text, JSON.stringify(provenance), createdAt);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('UNIQUE constraint failed')) {
+                throw new MemoryFtsError('MEMORY_FTS_CONFLICT', `memory record '${id}' already exists`);
+            }
+            throw error;
+        }
+        this.insertAudit(randomUUID(), id, 'create', input.actorId, new Date().toISOString(), 'created');
+        const row = this.db
+            .prepare(`SELECT * FROM memory_records WHERE id = ?`)
+            .get(id);
+        if (row === undefined)
+            throw new MemoryFtsError('MEMORY_FTS_STORAGE', 'record vanished after insert');
+        return rowToRecord(row);
+    }
+    getForAudit(id, options) {
+        this.assertOpen();
+        const row = this.db.prepare(`SELECT * FROM memory_records WHERE id = ?`).get(id);
+        if (row === undefined)
+            return undefined;
+        const record = rowToRecord(row);
+        if (options?.forAudit === true)
+            return record;
+        const redacted = { ...record, text: '[REDACTED]' };
+        return redacted;
+    }
+    /** Raw row update used by lifecycle (tombstone). Bypasses FTS only via trigger. */
+    markTombstoned(id, at) {
+        this.assertOpen();
+        this.db
+            .prepare(`UPDATE memory_records SET tombstoned_at = ? WHERE id = ? AND tombstoned_at IS NULL`)
+            .run(at, id);
+    }
+    /** Physical removal; the AFTER DELETE trigger purges the FTS entry. */
+    hardDelete(id) {
+        this.assertOpen();
+        this.db.prepare(`DELETE FROM memory_records WHERE id = ?`).run(id);
+        this.db.prepare(`DELETE FROM memory_pins WHERE record_id = ?`).run(id);
+    }
+    insertAudit(auditId, memoryId, action, actorId, at, detail) {
+        this.assertOpen();
+        this.db
+            .prepare(`INSERT INTO memory_audit (audit_id, memory_id, action, actor_id, at, detail)
+         VALUES (?, ?, ?, ?, ?, ?)`)
+            .run(auditId, memoryId, action, actorId, at, detail);
+    }
+    auditFor(memoryId) {
+        this.assertOpen();
+        return this.db
+            .prepare(`SELECT audit_id, memory_id, action, actor_id, at, detail
+           FROM memory_audit WHERE memory_id = ? ORDER BY at ASC`)
+            .all(memoryId).map((r) => ({
+            auditId: r.audit_id,
+            memoryId: r.memory_id,
+            action: r.action,
+            actorId: r.actor_id,
+            at: r.at,
+            detail: r.detail,
+        }));
+    }
+    /** Number of live (indexable) rows. */
+    countLive() {
+        this.assertOpen();
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS c FROM memory_records WHERE tombstoned_at IS NULL`)
+            .get();
+        return row.c;
+    }
+    /** Number of rows currently in the FTS index. */
+    countIndexed() {
+        this.assertOpen();
+        const row = this.db.prepare(`SELECT COUNT(*) AS c FROM memory_fts`).get();
+        return row.c;
+    }
+}