@theowlops/boombot 0.0.0-stage → 1.1.1

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

@@ -0,0 +1,23 @@
+/**
+ * @boombot/core — FTS5 full-text memory search for BoomBot.
+ *
+ * Public surface:
+ * - store:     `MemoryStore` (SQLite + FTS5, trigger-synced index)
+ * - search:    scoped, injection-safe full-text search with BM25 ranking
+ * - recall:    bounded immutable snapshots for turns
+ * - lifecycle: revoke (tombstone) / forget (hard delete) with audit
+ * - indexer:   batched rebuild + integrity verification
+ */
+export { MAX_TEXT_BYTES, MAX_QUERY_CHARS, MAX_QUERY_TERMS, MAX_SEARCH_LIMIT, MAX_SCOPE_ID_CHARS, MAX_SNIPPET_TOKENS, GLOBAL_SCOPE, type MemoryScopeKind, type MemoryScope, type MemoryProvenance, type MemoryRecord, type MemoryAuthorization, type MatchMode, type SearchOptions, type SearchHit, type RecallOptions, type MemorySnapshot, type RevokeInput, type ForgetInput, type MemoryAuditEntry, } from './types.js';
+export { MemoryFtsError, type MemoryFtsErrorCode } from './errors.js';
+export { MemoryStore, SCHEMA_VERSION, type CreateRecordInput, type RedactedMemoryRecord, } from './store.js';
+export { search, searchForPrincipal, extractTerms, buildSafeMatchQuery, DEFAULT_HIGHLIGHT_START, DEFAULT_HIGHLIGHT_END, type PrincipalSearchOptions, } from './search.js';
+export { recallMemory } from './recall.js';
+export { revokeMemory, forgetMemory } from './lifecycle.js';
+export { rebuildIndex, verifyIndex, type RebuildStats, type IndexHealth } from './indexer.js';
+export { SqliteFtsMemoryProvider, principalScope, sessionScope, type MemoryProvider, type MemoryEntryInput, type ScoredHit, type SqliteFtsMemoryProviderOptions, } from './provider.js';
+export { TtlMemoryCurator, CurationJob, type MemoryCurator, type CurationPolicy, type CurationReport, type CurationDecision, type CurationJobOptions, } from './curation.js';
+export * from './vector-index.js';
+export * from './hybrid-search.js';
+export { ScopeResolver, conversationScope, groupScope, type ScopeContext, } from './scope-resolver.js';
+export { CONSOLIDATION_STATE_ID, CONSOLIDATION_ACTOR_ID, ConsolidationJob, buildExtractionPrompt, parseExtractedFacts, runConsolidation, DEFAULT_CONSOLIDATION_BUDGET, ConsolidationBudgetTracker, type ConsolidationJobOptions, type ConsolidationLlm, type ConsolidationReport, type ConsolidationBudget, type ConversationSource, type EndedConversation, type RunConsolidationDeps, type WatermarkStore, type BudgetStopReason, type BudgetUsage, } from './consolidation/index.js';

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

@@ -0,0 +1,23 @@
+/**
+ * @boombot/core — FTS5 full-text memory search for BoomBot.
+ *
+ * Public surface:
+ * - store:     `MemoryStore` (SQLite + FTS5, trigger-synced index)
+ * - search:    scoped, injection-safe full-text search with BM25 ranking
+ * - recall:    bounded immutable snapshots for turns
+ * - lifecycle: revoke (tombstone) / forget (hard delete) with audit
+ * - indexer:   batched rebuild + integrity verification
+ */
+export { MAX_TEXT_BYTES, MAX_QUERY_CHARS, MAX_QUERY_TERMS, MAX_SEARCH_LIMIT, MAX_SCOPE_ID_CHARS, MAX_SNIPPET_TOKENS, GLOBAL_SCOPE, } from './types.js';
+export { MemoryFtsError } from './errors.js';
+export { MemoryStore, SCHEMA_VERSION, } from './store.js';
+export { search, searchForPrincipal, extractTerms, buildSafeMatchQuery, DEFAULT_HIGHLIGHT_START, DEFAULT_HIGHLIGHT_END, } from './search.js';
+export { recallMemory } from './recall.js';
+export { revokeMemory, forgetMemory } from './lifecycle.js';
+export { rebuildIndex, verifyIndex } from './indexer.js';
+export { SqliteFtsMemoryProvider, principalScope, sessionScope, } from './provider.js';
+export { TtlMemoryCurator, CurationJob, } from './curation.js';
+export * from './vector-index.js';
+export * from './hybrid-search.js';
+export { ScopeResolver, conversationScope, groupScope, } from './scope-resolver.js';
+export { CONSOLIDATION_STATE_ID, CONSOLIDATION_ACTOR_ID, ConsolidationJob, buildExtractionPrompt, parseExtractedFacts, runConsolidation, DEFAULT_CONSOLIDATION_BUDGET, ConsolidationBudgetTracker, } from './consolidation/index.js';

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

@@ -0,0 +1,47 @@
+import type { MemoryStore } from './store.js';
+export interface RebuildStats {
+    indexed: number;
+    batches: number;
+    elapsedMs: number;
+}
+export interface IndexHealth {
+    liveRows: number;
+    indexedRows: number;
+    /** True when every live row is indexed and no dead row is indexed. */
+    ok: boolean;
+    /** Row ids present in the index but missing/dead in memory_records. */
+    orphaned: number;
+}
+/**
+ * Rebuild the FTS index from scratch in batches.
+ *
+ * SECURITY FIX (non-atomic rebuild, low): the old code ran
+ * `DELETE FROM memory_fts` up front, then re-inserted in batches — a
+ * concurrent reader querying mid-rebuild saw an EMPTY index (availability
+ * hole: searches silently returned nothing until the rebuild finished).
+ *
+ * The rebuild now happens in two phases:
+ *  1. SHADOW BUILD — live rows are indexed into `memory_fts_shadow` in
+ *     batches, yielding to the event loop between batches. The live
+ *     `memory_fts` table is untouched, so readers keep seeing the old
+ *     (complete) index throughout.
+ *  2. ATOMIC MERGE — a single transaction merges the shadow into the live
+ *     index and drops the shadow table. Readers see the old index, then
+ *     the new one — never an empty one.
+ *
+ * Merge semantics (concurrent-write safety): `INSERT OR IGNORE` keeps rows
+ * the sync triggers wrote to the live index DURING the build — those are
+ * fresher than the shadow snapshot (e.g. a text update that landed
+ * mid-build). The `EXISTS (live row)` guard excludes rows tombstoned or
+ * hard-deleted during the build, so revocation is never resurrected by the
+ * merge.
+ *
+ * Residual note: a row whose INDEX TEXT was corrupt before the rebuild AND
+ * which is concurrently updated mid-build keeps the trigger-written (fresh)
+ * text — correct. A corrupt index entry for a row that is NOT touched during
+ * the build is repaired from the shadow — correct. There is no case where
+ * the merge makes the index worse than the pre-rebuild state.
+ */
+export declare function rebuildIndex(store: MemoryStore, batchSize?: number): Promise<RebuildStats>;
+/** Compare live rows vs indexed rows; report orphans. */
+export declare function verifyIndex(store: MemoryStore): IndexHealth;

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

@@ -0,0 +1,138 @@
+/**
+ * Index maintenance: batched rebuild and integrity verification.
+ *
+ * Normal writes stay in sync via SQLite triggers (see store.ts). Rebuild is
+ * for recovery paths the spec calls out: restart reconciliation, migration
+ * repair, and checksum-verified reindex tooling. Batches yield to the event
+ * loop between transactions so a large rebuild does not block the host.
+ */
+import { randomUUID } from 'node:crypto';
+const DEFAULT_BATCH_SIZE = 500;
+/** Yield control so a long rebuild never starves the event loop. */
+function yieldToLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
+/**
+ * Rebuild the FTS index from scratch in batches.
+ *
+ * SECURITY FIX (non-atomic rebuild, low): the old code ran
+ * `DELETE FROM memory_fts` up front, then re-inserted in batches — a
+ * concurrent reader querying mid-rebuild saw an EMPTY index (availability
+ * hole: searches silently returned nothing until the rebuild finished).
+ *
+ * The rebuild now happens in two phases:
+ *  1. SHADOW BUILD — live rows are indexed into `memory_fts_shadow` in
+ *     batches, yielding to the event loop between batches. The live
+ *     `memory_fts` table is untouched, so readers keep seeing the old
+ *     (complete) index throughout.
+ *  2. ATOMIC MERGE — a single transaction merges the shadow into the live
+ *     index and drops the shadow table. Readers see the old index, then
+ *     the new one — never an empty one.
+ *
+ * Merge semantics (concurrent-write safety): `INSERT OR IGNORE` keeps rows
+ * the sync triggers wrote to the live index DURING the build — those are
+ * fresher than the shadow snapshot (e.g. a text update that landed
+ * mid-build). The `EXISTS (live row)` guard excludes rows tombstoned or
+ * hard-deleted during the build, so revocation is never resurrected by the
+ * merge.
+ *
+ * Residual note: a row whose INDEX TEXT was corrupt before the rebuild AND
+ * which is concurrently updated mid-build keeps the trigger-written (fresh)
+ * text — correct. A corrupt index entry for a row that is NOT touched during
+ * the build is repaired from the shadow — correct. There is no case where
+ * the merge makes the index worse than the pre-rebuild state.
+ */
+export async function rebuildIndex(store, batchSize = DEFAULT_BATCH_SIZE) {
+    const started = Date.now();
+    const db = store.raw();
+    let indexed = 0;
+    let batches = 0;
+    // Phase 1 — shadow build. A leftover shadow from a crashed rebuild is
+    // discarded first; the finally-cleanup below covers crashes mid-build.
+    db.exec('DROP TABLE IF EXISTS memory_fts_shadow');
+    db.exec(`CREATE VIRTUAL TABLE memory_fts_shadow USING fts5(
+       text,
+       memory_id UNINDEXED,
+       tokenize = 'unicode61'
+     )`);
+    try {
+        let lastRowid = 0;
+        for (;;) {
+            const rows = db
+                .prepare(`SELECT rowid AS rowid, text, id FROM memory_records
+           WHERE rowid > ? AND tombstoned_at IS NULL AND deleted_at IS NULL
+           ORDER BY rowid ASC LIMIT ?`)
+                .all(lastRowid, batchSize);
+            if (rows.length === 0)
+                break;
+            const insert = db.prepare(`INSERT INTO memory_fts_shadow (rowid, text, memory_id) VALUES (?, ?, ?)`);
+            db.exec('BEGIN IMMEDIATE');
+            try {
+                for (const row of rows)
+                    insert.run(row.rowid, row.text, row.id);
+                db.exec('COMMIT');
+            }
+            catch (error) {
+                db.exec('ROLLBACK');
+                throw error;
+            }
+            indexed += rows.length;
+            batches += 1;
+            const lastRow = rows[rows.length - 1];
+            if (lastRow === undefined) {
+                throw new Error('indexer invariant violated: non-empty batch has no last row');
+            }
+            lastRowid = lastRow.rowid;
+            await yieldToLoop();
+        }
+        // Phase 2 — atomic merge into the live index.
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            db.exec(`INSERT OR IGNORE INTO memory_fts (rowid, text, memory_id)
+         SELECT s.rowid, s.text, s.memory_id
+         FROM memory_fts_shadow AS s
+         WHERE EXISTS (
+           SELECT 1 FROM memory_records AS m
+           WHERE m.rowid = s.rowid
+             AND m.tombstoned_at IS NULL
+             AND m.deleted_at IS NULL
+         )`);
+            db.exec('DROP TABLE memory_fts_shadow');
+            db.exec('COMMIT');
+        }
+        catch (error) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch {
+                // ignore rollback failure; the original error is what matters
+            }
+            throw error;
+        }
+    }
+    catch (error) {
+        // Best-effort cleanup so a failed rebuild never leaves the shadow table
+        // (and its storage) behind.
+        try {
+            db.exec('DROP TABLE IF EXISTS memory_fts_shadow');
+        }
+        catch {
+            // ignore
+        }
+        throw error;
+    }
+    store.insertAudit(randomUUID(), '*', 'reindex', 'system', new Date().toISOString(), `indexed=${indexed}`);
+    return { indexed, batches, elapsedMs: Date.now() - started };
+}
+/** Compare live rows vs indexed rows; report orphans. */
+export function verifyIndex(store) {
+    const db = store.raw();
+    const live = db.prepare(`SELECT COUNT(*) AS c FROM memory_records WHERE tombstoned_at IS NULL AND deleted_at IS NULL`).get().c;
+    const indexed = db.prepare(`SELECT COUNT(*) AS c FROM memory_fts`).get().c;
+    const orphaned = db
+        .prepare(`SELECT COUNT(*) AS c FROM memory_fts AS f
+         LEFT JOIN memory_records AS m ON m.rowid = f.rowid
+         WHERE m.rowid IS NULL OR m.tombstoned_at IS NOT NULL OR m.deleted_at IS NOT NULL`)
+        .get().c;
+    return { liveRows: live, indexedRows: indexed, ok: live === indexed && orphaned === 0, orphaned };
+}

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

@@ -0,0 +1,12 @@
+import { type MemoryStore } from './store.js';
+import type { ForgetInput, MemoryRecord, RevokeInput } from './types.js';
+/**
+ * Tombstone a record. Idempotent: revoking twice returns the record with the
+ * original tombstone timestamp and records an audit entry.
+ */
+export declare function revokeMemory(store: MemoryStore, input: RevokeInput): MemoryRecord;
+/**
+ * Hard-delete a record. The FTS entry is purged by trigger; audit keeps
+ * metadata only (no content). Idempotent.
+ */
+export declare function forgetMemory(store: MemoryStore, input: ForgetInput): void;

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

@@ -0,0 +1,66 @@
+/**
+ * Record lifecycle: revocation (tombstone) and forget (hard delete).
+ *
+ * - Revoke: sets `tombstoned_at`. The sync trigger immediately drops the row
+ *   from the FTS index, so the next search cannot return it, while the row
+ *   itself survives as the audit trail (per spec: revocation is visible to
+ *   authorized inspection, derived indexes are invalidated).
+ * - Forget: physically deletes the row (trigger purges the FTS entry). The
+ *   audit log keeps action/actor/timestamp WITHOUT content.
+ *
+ * Both operations are idempotent and scope-checked: the caller must name the
+ * exact scope the record lives in, otherwise the operation fails — this
+ * prevents a principal from revoking another principal's records by id.
+ */
+import { randomUUID } from 'node:crypto';
+import { forbiddenError, notFoundError } from './errors.js';
+import { validateScope } from './store.js';
+function loadInScope(store, id, scope) {
+    validateScope(scope);
+    const record = store.getForAudit(id, { forAudit: true });
+    if (record === undefined || record.scope.kind !== scope.kind || record.scope.id !== scope.id) {
+        // Same error whether the id is unknown or lives in another scope:
+        // existence must not leak across scope boundaries.
+        throw notFoundError(id);
+    }
+    return record;
+}
+function checkActor(actorId) {
+    if (typeof actorId !== 'string' || actorId.length === 0 || actorId.length > 256) {
+        throw forbiddenError('actorId is required');
+    }
+}
+/**
+ * Tombstone a record. Idempotent: revoking twice returns the record with the
+ * original tombstone timestamp and records an audit entry.
+ */
+export function revokeMemory(store, input) {
+    checkActor(input.actorId);
+    const record = loadInScope(store, input.id, input.scope);
+    const now = new Date().toISOString();
+    if (record.tombstonedAt === undefined) {
+        store.markTombstoned(input.id, now);
+        record.tombstonedAt = now;
+    }
+    store.insertAudit(randomUUID(), input.id, 'revoke', input.actorId, now, input.reason.slice(0, 500));
+    const refreshed = store.getForAudit(input.id, { forAudit: true });
+    if (refreshed === undefined)
+        throw notFoundError(input.id);
+    return refreshed;
+}
+/**
+ * Hard-delete a record. The FTS entry is purged by trigger; audit keeps
+ * metadata only (no content). Idempotent.
+ */
+export function forgetMemory(store, input) {
+    checkActor(input.actorId);
+    const record = store.getForAudit(input.id, { forAudit: true });
+    if (record === undefined)
+        return; // idempotent: already gone
+    if (record.scope.kind !== input.scope.kind || record.scope.id !== input.scope.id) {
+        throw notFoundError(input.id);
+    }
+    const now = new Date().toISOString();
+    store.hardDelete(input.id);
+    store.insertAudit(randomUUID(), input.id, 'forget', input.actorId, now, input.reason.slice(0, 500));
+}

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

@@ -0,0 +1,84 @@
+import { type MemoryProvenance, type MemoryRecord, type MemoryScope } from './types.js';
+/** Input for `MemoryProvider.save` — the host supplies scope + content. */
+export interface MemoryEntryInput {
+    id?: string;
+    scope: MemoryScope;
+    text: string;
+    provenance: Omit<MemoryProvenance, 'at'> & {
+        at?: string;
+    };
+    createdAt?: string;
+}
+/** A ranked search result. `score` is provider-specific (lower = better). */
+export interface ScoredHit {
+    record: MemoryRecord;
+    /** Provider-specific relevance score. Lower = more relevant. */
+    score: number;
+    /** Excerpt with highlight markers around matched terms. */
+    snippet: string;
+}
+/**
+ * The memory storage port. Builtin (FTS) and external (vector/remote)
+ * implementations share this surface; callers never depend on SQLite.
+ *
+ * All methods are synchronous for the builtin provider. External providers
+ * that need I/O should wrap this interface with an async facade at the
+ * host layer rather than forcing async onto every caller.
+ */
+export interface MemoryProvider {
+    /** 'builtin' = shipped with BoomBot; 'external' = host-provided. */
+    readonly kind: 'builtin' | 'external';
+    /** Persist a memory entry. Returns the stored record. */
+    save(entry: MemoryEntryInput): MemoryRecord;
+    /** Full-text / semantic search. Returns at most `limit` hits (default 20). */
+    search(query: string, limit?: number): ScoredHit[];
+    /** Hard-delete a record (audit keeps metadata only). Optional. */
+    delete?(id: string, scope: MemoryScope): void;
+    /** Tombstone a record: removed from search, kept for audit. Optional. */
+    archive?(id: string, scope: MemoryScope, reason?: string): void;
+    /** Protect a record from curation. Optional. */
+    pin?(id: string, scope: MemoryScope): void;
+    /** Remove curation protection. Optional. */
+    unpin?(id: string, scope: MemoryScope): void;
+    /** Whether a record is currently pinned. Optional. */
+    isPinned?(id: string, scope: MemoryScope): boolean;
+    /** List recent live records in a scope (newest first). Optional. */
+    list?(scope: MemoryScope, limit?: number): MemoryRecord[];
+    /** Release resources (close DB, flush buffers). Optional. */
+    close?(): void;
+}
+export interface SqliteFtsMemoryProviderOptions {
+    /** SQLite path, or ':memory:'. Default ':memory:'. */
+    path?: string;
+    /** Principal this provider serves. Never taken from user input. */
+    principalId: string;
+}
+/**
+ * Builtin `MemoryProvider` backed by the ported SQLite FTS5 store
+ * (`MemoryStore`). Scoped search = the principal's own scope + the shared
+ * global scope; scope isolation and tombstone semantics are inherited
+ * unchanged from the tested store/search/lifecycle modules.
+ */
+export declare class SqliteFtsMemoryProvider implements MemoryProvider {
+    readonly kind: "builtin";
+    private readonly store;
+    private readonly principalId;
+    private closed;
+    constructor(options: SqliteFtsMemoryProviderOptions);
+    private assertOpen;
+    save(entry: MemoryEntryInput): MemoryRecord;
+    search(query: string, limit?: number): ScoredHit[];
+    delete(id: string, scope: MemoryScope): void;
+    archive(id: string, scope: MemoryScope, reason?: string): void;
+    pin(id: string, scope: MemoryScope): void;
+    unpin(id: string, scope: MemoryScope): void;
+    isPinned(id: string, scope: MemoryScope): boolean;
+    list(scope: MemoryScope, limit?: number): MemoryRecord[];
+    close(): void;
+    /** The shared global scope — visible to every principal. */
+    static globalScope(): MemoryScope;
+}
+/** Build a principal-private scope id. The id must come from auth, not input. */
+export declare function principalScope(principalId: string): MemoryScope;
+/** Build a session-private scope id. */
+export declare function sessionScope(sessionId: string): MemoryScope;

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

@@ -0,0 +1,117 @@
+/**
+ * @boombot/core — `MemoryProvider` abstraction.
+ *
+ * Lesson from Hermes/OpenClaw analysis (#6): the memory store must be an
+ * interface from day one so the builtin FTS implementation can be swapped
+ * for an external provider (vector DB, remote service) without touching the
+ * agent loop or the curator. Curation is deliberately NOT part of this
+ * interface — see `curation.ts`.
+ */
+import { forgetMemory, revokeMemory } from './lifecycle.js';
+import { searchForPrincipal } from './search.js';
+import { MemoryStore } from './store.js';
+import { GLOBAL_SCOPE, } from './types.js';
+/**
+ * Builtin `MemoryProvider` backed by the ported SQLite FTS5 store
+ * (`MemoryStore`). Scoped search = the principal's own scope + the shared
+ * global scope; scope isolation and tombstone semantics are inherited
+ * unchanged from the tested store/search/lifecycle modules.
+ */
+export class SqliteFtsMemoryProvider {
+    kind = 'builtin';
+    store;
+    principalId;
+    closed = false;
+    constructor(options) {
+        if (typeof options.principalId !== 'string' || options.principalId.length === 0) {
+            throw new Error('SqliteFtsMemoryProvider: principalId is required');
+        }
+        this.principalId = options.principalId;
+        this.store = MemoryStore.open(options.path ?? ':memory:');
+    }
+    assertOpen() {
+        if (this.closed)
+            throw new Error('SqliteFtsMemoryProvider: provider is closed');
+    }
+    save(entry) {
+        this.assertOpen();
+        return this.store.create({
+            id: entry.id,
+            scope: entry.scope,
+            text: entry.text,
+            provenance: {
+                source: entry.provenance.source,
+                reference: entry.provenance.reference,
+                actorId: entry.provenance.actorId,
+                at: entry.provenance.at ?? new Date().toISOString(),
+            },
+            createdAt: entry.createdAt,
+            actorId: entry.provenance.actorId,
+        });
+    }
+    search(query, limit = 20) {
+        this.assertOpen();
+        return searchForPrincipal(this.store, this.principalId, { query, limit }).map((hit) => ({
+            record: hit.record,
+            score: hit.score,
+            snippet: hit.snippet,
+        }));
+    }
+    delete(id, scope) {
+        this.assertOpen();
+        forgetMemory(this.store, { id, scope, actorId: this.principalId, reason: 'provider.delete' });
+        this.store.unpin(id, scope);
+    }
+    archive(id, scope, reason = 'curated') {
+        this.assertOpen();
+        revokeMemory(this.store, { id, scope, actorId: this.principalId, reason });
+    }
+    pin(id, scope) {
+        this.assertOpen();
+        this.store.pin(id, scope);
+    }
+    unpin(id, scope) {
+        this.assertOpen();
+        this.store.unpin(id, scope);
+    }
+    isPinned(id, scope) {
+        return this.store.isPinned(id, scope);
+    }
+    list(scope, limit = 100) {
+        this.assertOpen();
+        const rows = this.store
+            .raw()
+            .prepare(`SELECT id, scope_kind, scope_id, text, provenance_json, created_at
+         FROM memory_records
+         WHERE scope_kind = ? AND scope_id = ?
+           AND tombstoned_at IS NULL AND deleted_at IS NULL
+         ORDER BY created_at DESC, id ASC
+         LIMIT ?`)
+            .all(scope.kind, scope.id, limit);
+        return rows.map((row) => ({
+            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,
+        }));
+    }
+    close() {
+        if (!this.closed) {
+            this.closed = true;
+            this.store.close();
+        }
+    }
+    /** The shared global scope — visible to every principal. */
+    static globalScope() {
+        return GLOBAL_SCOPE;
+    }
+}
+/** Build a principal-private scope id. The id must come from auth, not input. */
+export function principalScope(principalId) {
+    return { kind: 'principal', id: principalId };
+}
+/** Build a session-private scope id. */
+export function sessionScope(sessionId) {
+    return { kind: 'session', id: sessionId };
+}

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

@@ -0,0 +1,7 @@
+import { type MemoryStore } from './store.js';
+import { type MemorySnapshot, type RecallOptions } from './types.js';
+/**
+ * Recall memory into an immutable, bounded snapshot.
+ * Without a query, returns the latest records per scope (created_at DESC).
+ */
+export declare function recallMemory(store: MemoryStore, options: RecallOptions): MemorySnapshot;

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

@@ -0,0 +1,111 @@
+/**
+ * Bounded recall — the BoomBot "bounded snapshot" philosophy.
+ *
+ * The agent runtime never holds the repository or a mutable memory object;
+ * the session owner converts authorized recall into an immutable, bounded
+ * snapshot before a turn. This module enforces the bounds:
+ * - maxResults:   at most N records enter the snapshot;
+ * - maxCharsPerHit: each excerpt is truncated to a fixed width;
+ * - maxTotalChars:  the whole snapshot stays within a byte/char budget.
+ *
+ * `truncated` tells the caller budget pressure existed, so the session owner
+ * can emit the degraded-but-visible diagnostic the spec requires instead of
+ * silently dropping context.
+ */
+import {} from 'node:sqlite';
+import { validationError } from './errors.js';
+import { search } from './search.js';
+import { validateScope } from './store.js';
+import {} from './types.js';
+const DEFAULT_MAX_RESULTS = 10;
+const DEFAULT_MAX_CHARS_PER_HIT = 500;
+const DEFAULT_MAX_TOTAL_CHARS = 4000;
+function truncateTo(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return text.slice(0, Math.max(0, maxChars - 1)) + '…';
+}
+function authorizedScopes(auth) {
+    if (auth.readableScopes.length === 0) {
+        throw validationError('authorization carries no readable scopes');
+    }
+    for (const scope of auth.readableScopes)
+        validateScope(scope);
+    return auth.readableScopes;
+}
+/**
+ * Recall memory into an immutable, bounded snapshot.
+ * Without a query, returns the latest records per scope (created_at DESC).
+ */
+export function recallMemory(store, options) {
+    const scopes = authorizedScopes(options.authorization);
+    const maxResults = Math.min(Math.max(Math.floor(options.maxResults ?? DEFAULT_MAX_RESULTS), 1), 200);
+    const maxCharsPerHit = Math.min(Math.max(Math.floor(options.maxCharsPerHit ?? DEFAULT_MAX_CHARS_PER_HIT), 16), 8192);
+    const maxTotalChars = Math.min(Math.max(Math.floor(options.maxTotalChars ?? DEFAULT_MAX_TOTAL_CHARS), 64), 65536);
+    const evaluatedAt = new Date().toISOString();
+    let hits;
+    if (options.query !== undefined) {
+        // Over-fetch slightly so per-hit truncation still leaves maxResults.
+        hits = search(store, {
+            query: options.query,
+            scopes,
+            limit: maxResults,
+            match: options.match ?? 'any',
+        });
+    }
+    else {
+        hits = latestPerScope(store, scopes, maxResults);
+    }
+    const bounded = [];
+    let totalChars = 0;
+    let truncated = false;
+    for (const hit of hits) {
+        if (bounded.length >= maxResults) {
+            truncated = true;
+            break;
+        }
+        const excerpt = truncateTo(hit.snippet, maxCharsPerHit);
+        if (totalChars + excerpt.length > maxTotalChars) {
+            truncated = true;
+            break;
+        }
+        totalChars += excerpt.length;
+        bounded.push({ record: hit.record, score: hit.score, snippet: excerpt });
+    }
+    return Object.freeze({
+        evaluatedAt,
+        hits: Object.freeze(bounded),
+        truncated,
+        totalChars,
+    });
+}
+/** Latest-first scoped listing for recall without a query. */
+function latestPerScope(store, scopes, limit) {
+    const clauses = [];
+    const params = [];
+    for (const scope of scopes) {
+        clauses.push('(scope_kind = ? AND scope_id = ?)');
+        params.push(scope.kind, scope.id);
+    }
+    params.push(limit);
+    const rows = store
+        .raw()
+        .prepare(`SELECT id, scope_kind, scope_id, text, provenance_json, created_at
+       FROM memory_records
+       WHERE (${clauses.join(' OR ')})
+         AND tombstoned_at IS NULL AND deleted_at IS NULL
+       ORDER BY created_at DESC, id ASC
+       LIMIT ?`)
+        .all(...params);
+    return rows.map((row) => ({
+        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,
+        },
+        score: 0,
+        snippet: row.text,
+    }));
+}

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

@@ -0,0 +1,27 @@
+import { type MemoryScope } from './types.js';
+export interface ScopeContext {
+    readonly channel?: string;
+    readonly chatId?: string;
+    readonly senderId?: string;
+    readonly group?: string;
+    readonly isOperator?: boolean;
+}
+export declare function conversationScope(channel: string, chatId: string): MemoryScope;
+export declare function groupScope(groupName: string): MemoryScope;
+export declare 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: ScopeContext, principalId: string): readonly MemoryScope[];
+    /**
+     * 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: ScopeContext, requestedScope?: MemoryScope): MemoryScope;
+}