@asaidimu/utils-workspace 2.0.0 → 2.1.1

package/index.d.ts

@@ -1,3 +1,6 @@
+import { QueryFilter, PaginationOptions } from '@asaidimu/query';
+import { IndexDefinition, SchemaDefinition, SchemaChange, DataTransform } from '@asaidimu/anansi';
+
 type UUID = string;
 type Timestamp = string;
 type URI = string;
@@ -29,7 +32,7 @@ type WorkspaceError = {
 };
 interface Settings {
     language: string;
-    defaultRole: string;
+    defaultRole?: string;
     prompt?: string;
 }
 interface Project {
@@ -61,8 +64,7 @@ type ResolvedBlob = {
 };
 /**
  * Full registry entry for a blob. BlobRef is a Pick of this type, so
- * a BlobRecord is always assignable to BlobRef. BlobSummary has been
- * removed — callers that previously used BlobSummary use BlobRecord directly.
+ * a BlobRecord is always assignable to BlobRef.
  */
 interface BlobRecord {
     sha256: SHA256;
@@ -124,11 +126,26 @@ interface Turn {
     role: TurnRole;
     blocks: ContentBlock[];
     timestamp: Timestamp;
+    /**
+     * The name of the role active when this turn was recorded.
+     * Snapshot so history is stable even if the role is later renamed.
+     */
     roleSnapshot?: string;
+    /**
+     * Parent pointer. Null for root turns.
+     * This is plain data stored on the document — the DAG is reconstructed
+     * in memory by TurnTree.buildNodeGraph() at session open time.
+     */
     parent: {
         id: UUID;
         version: number;
     } | null;
+    /**
+     * Partition key. Stored on the Turn document so Collection.filter
+     * can retrieve all turns for a session in a single query.
+     * Not present on Turn objects used purely in memory (e.g. dirty buffer).
+     */
+    sessionId?: UUID;
 }
 interface TurnNode {
     id: UUID;
@@ -145,63 +162,53 @@ interface TurnNode {
     children: Record<number, UUID[]>;
 }
 interface BranchInfo {
-    /** All sibling versions at this level, in insertion order. */
     versions: number[];
-    /** Index of this turn within siblings (0-based). */
     currentIndex: number;
-    /** Convenience: number of siblings (siblings.length). */
     total: number;
-    /** True when there is a branch to the left. */
     hasPrev: boolean;
-    /** True when there is a branch to the right. */
     hasNext: boolean;
 }
-interface RoleSummary {
+interface Role {
     name: string;
     label: string;
     description?: string;
-    preferences: number;
+    persona: string;
+    preferences: UUID[];
 }
-interface PreferenceSummary {
+interface Preference {
     id: UUID;
+    content: string;
     topics: string[];
     timestamp: Timestamp;
-    snippet?: string;
 }
-interface ContextSummary {
+type ContextContent = {
+    kind: 'text';
+    value: string;
+} | {
+    kind: 'json';
+    value: unknown;
+} | {
+    kind: 'blob';
+    sha256: SHA256;
+    mediaType: BlobMediaType;
+    sizeBytes: number;
+    filename?: string;
+} | {
+    kind: 'remote';
+    uri: URI;
+    mediaType?: BlobMediaType;
+};
+interface Context {
     key: string;
     topics: string[];
+    content: ContextContent;
     timestamp: Timestamp;
-    mime?: string;
-    size?: number;
-    preview?: string;
-    source?: string;
     metadata?: Record<string, any>;
 }
-interface TopicIndex {
-    topic: string;
-    contextKeys: string[];
-    preferences: UUID[];
-    metadata?: {
-        created?: Timestamp;
-        updated?: Timestamp;
-        entries?: number;
-    };
-}
-interface Workspace {
-    id: UUID;
-    settings: Settings;
-    project: Project;
-    index: Index;
-}
-interface Index {
-    format: string;
-    roles: Record<string, RoleSummary>;
-    preferences: Record<UUID, PreferenceSummary>;
-    context: Record<string, ContextSummary>;
-    sessions: Record<UUID, SessionMeta>;
-    topics: Record<string, TopicIndex>;
-}
+/**
+ * SessionMeta is stored as a document in the 'session' collection.
+ * The head pointer lives here — no separate session_heads store needed.
+ */
 interface SessionMeta {
     id: UUID;
     label: string;
@@ -218,69 +225,64 @@ interface SessionMeta {
         version: number;
     } | null;
 }
-interface Role {
-    id: UUID;
+interface RoleSummary {
     name: string;
     label: string;
-    persona: string;
     description?: string;
-    preferences: UUID[];
+    /** Number of preference IDs listed on the role. */
+    preferences: number;
 }
-interface Preference {
+interface PreferenceSummary {
     id: UUID;
-    content: string;
     topics: string[];
     timestamp: Timestamp;
+    snippet?: string;
 }
-interface Context {
+interface ContextSummary {
     key: string;
-    content: ContextContent;
     topics: string[];
     timestamp: Timestamp;
+    mime?: string;
+    size?: number;
+    preview?: string;
+    source?: string;
     metadata?: Record<string, any>;
-    remoteIds?: Record<string, string>;
-    refCount?: number;
 }
-type ContextContent = {
-    kind: 'text';
-    value: string;
-} | {
-    kind: 'json';
-    value: object;
-} | {
-    kind: 'blob';
-} & BlobRef | {
-    kind: 'remote';
-    uri: URI;
-    mediaType: BlobMediaType;
-};
-interface Session$1 {
-    id: UUID;
-    label: string;
-    role: string;
-    topics: string[];
+interface TopicIndex {
+    topic: string;
+    contextKeys: string[];
     preferences: UUID[];
-    turns: Turn[];
-    metadata: {
+    metadata?: {
         created?: Timestamp;
         updated?: Timestamp;
+        entries?: number;
     };
 }
+interface Index {
+    roles: Record<string, RoleSummary>;
+    preferences: Record<UUID, PreferenceSummary>;
+    context: Record<string, ContextSummary>;
+    sessions: Record<UUID, SessionMeta>;
+    topics: Record<string, TopicIndex>;
+    blobs: Record<SHA256, BlobRecord>;
+}
+interface Workspace {
+    id: UUID;
+    settings: Settings;
+    project: Project;
+    index: Index;
+}
 interface WorkspaceBundle {
     format: 'aiworkspace/4.0';
     workspace: Workspace;
     roles: Record<string, Role>;
     preferences: Record<UUID, Preference>;
     context: Record<string, Context>;
-    sessions: Record<UUID, Session$1>;
+    sessions: Record<UUID, SessionMeta & {
+        turns: Turn[];
+    }>;
     blobs: Record<SHA256, BlobRecord>;
 }
-interface TranscriptWindow {
-    sessionId: UUID;
-    turns: Turn[];
-    flushedCount: number;
-    hasMore: boolean;
-}
 interface EffectiveSession {
     session: SessionMeta;
     role: Role;
@@ -293,7 +295,6 @@ interface CacheConfig {
     roles?: number;
     preferences?: number;
     context?: number;
-    transcriptWindows?: number;
 }
 interface FlushConfig {
     maxBufferSize: number;
@@ -302,7 +303,6 @@ interface FlushConfig {
 interface ContentStoreConfig {
     cache?: CacheConfig;
     flush?: FlushConfig;
-    transcriptWindowSize?: number;
 }
 interface BaseCommand {
     type: string;
@@ -452,14 +452,16 @@ interface DeleteSession extends BaseCommand {
 }
 interface RegisterBlob extends BaseCommand {
     type: 'blob:register';
-    payload: BlobRecord;
+    payload: {
+        data: Uint8Array;
+        mediaType: BlobMediaType;
+        filename?: string;
+    };
 }
-interface RecordBlobRemoteId extends BaseCommand {
-    type: 'blob:remote_id';
+interface RetainBlob extends BaseCommand {
+    type: 'blob:retain';
     payload: {
         sha256: SHA256;
-        providerId: string;
-        fileId: string;
     };
 }
 interface ReleaseBlob extends BaseCommand {
@@ -468,7 +470,22 @@ interface ReleaseBlob extends BaseCommand {
         sha256: SHA256;
     };
 }
-type Command = CreateWorkspace | AddRole | UpdateRole | DeleteRole | AddPreference | UpdatePreference | DeletePreference | CreateSession | AddContext | UpdateContext | DeleteContext | AddTurn | EditTurn | BranchTurn | DeleteTurn | SwitchRole | AddSessionTopics | OverrideSessionPreferences | ForkSession | DeleteSession | RegisterBlob | RecordBlobRemoteId | ReleaseBlob;
+interface PurgeBlob extends BaseCommand {
+    type: 'blob:purge';
+    payload: {
+        sha256: SHA256;
+    };
+}
+interface RecordBlobRemoteId extends BaseCommand {
+    type: 'blob:record_remote_id';
+    payload: {
+        sha256: SHA256;
+        providerId: string;
+        fileId: string;
+    };
+}
+type BlobCommand = RegisterBlob | RetainBlob | ReleaseBlob | PurgeBlob | RecordBlobRemoteId;
+type Command = CreateWorkspace | AddRole | UpdateRole | DeleteRole | AddPreference | UpdatePreference | DeletePreference | CreateSession | AddContext | UpdateContext | DeleteContext | AddTurn | EditTurn | BranchTurn | DeleteTurn | SwitchRole | AddSessionTopics | OverrideSessionPreferences | ForkSession | DeleteSession | BlobCommand;
 interface TokenBudget {
     total: number;
     estimator?: (text: string) => number;
@@ -486,7 +503,7 @@ interface ContextRelevanceConfig {
     freshnessHalfLifeDays?: number;
 }
 /**
- * BuiltTurn has been removed. Prompt.transcript.turns is now Turn[].
+ * Prompt.transcript.turns is Turn[].
  * Synthetic turns produced by PromptAssembler (summary blocks, truncation
  * notices, referential attachments) carry generated UUIDs and version 0,
  * with parent: null. They are ephemeral — never stored, never patched.
@@ -515,36 +532,448 @@ interface Prompt {
     warnings: string[];
     conflicts: PreferenceConflict[];
 }
+interface TranscriptWindow {
+    sessionId: UUID;
+    turns: Turn[];
+    flushedCount: number;
+    hasMore: boolean;
+}
 
-interface ContentStorage {
-    saveRole(role: Role): Promise<void>;
-    loadRole(name: string): Promise<Role | null>;
-    deleteRole(name: string): Promise<void>;
-    savePreference(preference: Preference): Promise<void>;
-    loadPreference(id: UUID): Promise<Preference | null>;
-    deletePreference(id: UUID): Promise<void>;
-    saveContext(context: Context): Promise<void>;
-    loadContext(key: string): Promise<Context | null>;
-    loadContextBatch(keys: string[]): Promise<Map<string, Context>>;
-    deleteContext(key: string): Promise<void>;
-    saveTurn(sessionId: UUID, turn: Turn): Promise<void>;
-    loadTurn(sessionId: UUID, turnId: UUID, version: number): Promise<Turn | null>;
-    loadAllTurns(sessionId: UUID): Promise<Turn[]>;
-    deleteTurn(sessionId: UUID, turnId: UUID, version: number): Promise<void>;
-    setSessionHead(sessionId: UUID, head: {
-        id: UUID;
-        version: number;
-    } | null): Promise<void>;
-    getSessionHead(sessionId: UUID): Promise<{
-        id: UUID;
-        version: number;
-    } | null>;
-    storeBytes(sha256: SHA256, data: Uint8Array): Promise<void>;
-    loadBytes(sha256: SHA256): Promise<Uint8Array | null>;
-    deleteBytes(sha256: SHA256): Promise<void>;
-    exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
+/**
+ * Buffers write operations across one or more stores and commits them atomically.
+ *
+ * ## How atomicity works
+ *
+ * ### IndexedDB stores (same database)
+ * At commit time, TransactionContext collects the names of every IDB store that
+ * received operations, then opens a **single** `IDBTransaction` spanning all of
+ * them via `ConnectionManager.openTransaction`. Each store's `executeInTransaction`
+ * receives that shared transaction object and performs its writes against it
+ * without opening a new transaction of its own. IDB commits or aborts the
+ * entire multi-store transaction as one unit.
+ *
+ * ### MemoryStore
+ * MemoryStore's `executeInTransaction` receives `null` for the shared transaction.
+ * It applies ops against an internal staging map and returns. If a later
+ * participant fails, TransactionContext calls `rollbackMemory` on each
+ * MemoryStore that already applied its staged ops. MemoryStore restores its
+ * pre-transaction snapshot.
+ *
+ * ### Mixed (IDB + Memory in the same transaction)
+ * All IDB stores are committed first as a single atomic IDB transaction, then
+ * each MemoryStore is committed. If a MemoryStore fails after IDB has already
+ * committed, the IDB side cannot be rolled back — this is an inherent limitation
+ * of mixing two different storage engines. In practice the schema store is
+ * always MemoryStore-or-IDB consistently, so mixed transactions should not arise
+ * in normal usage.
+ */
+declare class TransactionContext {
+    readonly id: string;
+    /**
+     * Flat list of every operation staged so far, in the order they were added.
+     * We keep the store reference alongside the op so commit() can group them.
+     */
+    private staged;
+    private done;
+    constructor();
+    /**
+     * Stages a single write operation against a store.
+     * Does NOT touch the store — no I/O happens until commit().
+     */
+    addOp<T extends Record<string, any>>(store: Store<T>, type: "put" | "delete" | "add", data: any): Promise<void>;
+    /**
+     * Commits all staged operations atomically.
+     *
+     * For IDB stores: opens one shared IDBTransaction across all participating
+     * stores, then dispatches ops to each store's executeInTransaction.
+     * For MemoryStores: dispatches sequentially; rolls back on failure.
+     */
+    commit(): Promise<void>;
+    /**
+     * Discards all staged operations. No I/O has occurred so there is nothing
+     * to undo — we simply clear the buffer.
+     */
+    rollback(): void;
+    /**
+     * Opens ONE IDBTransaction across all participating IDB stores and lets
+     * each store execute its ops against the shared transaction handle.
+     *
+     * We obtain the IDBDatabase from the first store (they all share the same
+     * ConnectionManager / database) and open the transaction ourselves so that
+     * the commit/abort lifecycle belongs entirely to this method.
+     */
+    private commitIDB;
+    /**
+     * Commits MemoryStore groups sequentially.
+     * Maintains a list of stores that have already applied their ops; if any
+     * store throws, all previously-applied stores are rolled back via the
+     * store-level `_rollbackMemory(snapshot)` escape hatch.
+     */
+    private commitMemory;
+    completed(): boolean;
 }
 
+interface CursorCallbackResult<T> {
+    value: T | null;
+    done: boolean;
+    offset?: number;
+}
+/**
+ * Callback function for cursor iteration over store records.
+ *
+ * @template T - The type of records stored.
+ * @param value - The current record value (cloned, not a live reference).
+ * @param key - The key (ID) of the current record.
+ * @param cursor - The underlying cursor object (implementation-specific; may be `null` in memory adapters).
+ * @returns A promise resolving to an object indicating whether iteration should stop,
+ *          and an optional offset to advance.
+ */
+type CursorCallback<T> = (value: T, key: string | number, cursor: any) => Promise<CursorCallbackResult<T>>;
+/**
+ * A generic representation of a key range, replacing the browser-specific IDBKeyRange.
+ */
+interface StoreKeyRange {
+    lower?: any;
+    upper?: any;
+    lowerOpen?: boolean;
+    upperOpen?: boolean;
+}
+/**
+ * A single buffered operation staged inside a TransactionContext.
+ * Kept intentionally minimal — the context only needs to know what to
+ * replay against a store during commit.
+ */
+type BufferedOperation<T> = {
+    type: "add" | "put";
+    data: T | T[];
+} | {
+    type: "delete";
+    data: string | number | (string | number)[];
+};
+/**
+ * Storage adapter interface for a single object store (collection).
+ *
+ * Stores own their indexes. Index lifecycle (create, drop) and index-aware reads
+ * (findByIndex) are part of this contract so that both MemoryStore and IndexedDBStore
+ * implement them natively — MemoryStore via in-memory index maps, IndexedDB via its
+ * native index mechanism.
+ *
+ * @template T - The type of objects stored. Must include the key path property.
+ */
+interface Store<T extends Record<string, any> = Record<string, any>> {
+    /**
+     * Returns the name of this store (the IDB object store / collection name).
+     * Used by TransactionContext to group operations and open a correctly-scoped
+     * multi-store IDB transaction at commit time.
+     */
+    name(): string;
+    /**
+     * Opens the store, ensuring underlying storage structures exist.
+     */
+    open(): Promise<void>;
+    /**
+     * Adds one or more records to the store.
+     * If a record does not have a value for the store's key path, an automatic
+     * key may be assigned. Throws if a record with the same key already exists.
+     */
+    add(data: T | T[]): Promise<string | number | (string | number)[]>;
+    /**
+     * Removes all records from the store without destroying index structures.
+     */
+    clear(): Promise<void>;
+    /**
+     * Returns the total number of records in the store.
+     */
+    count(): Promise<number>;
+    /**
+     * Deletes one or more records by their keys.
+     */
+    delete(id: string | number | (string | number)[]): Promise<void>;
+    /**
+     * Retrieves a single record by its primary key.
+     */
+    getById(id: string | number): Promise<T | undefined>;
+    /**
+     * Retrieves the first record matching an exact index key (point lookup).
+     * Useful for unique indexes — returns the single matching record or undefined.
+     *
+     * @param indexName - The name of the index to query.
+     * @param key - The exact key value to look up.
+     */
+    getByIndex(indexName: string, key: any): Promise<T | undefined>;
+    /**
+     * Retrieves all records from a named index, optionally filtered by a key range.
+     * Use this for range scans over an index (e.g. all records where age >= 18).
+     *
+     * @param indexName - The name of the index to query.
+     * @param keyRange - Optional range to filter results.
+     */
+    getByKeyRange(indexName: string, keyRange?: StoreKeyRange): Promise<T[]>;
+    /**
+     * Retrieves all records from the store without index involvement.
+     */
+    getAll(): Promise<T[]>;
+    /**
+     * Inserts or replaces a record. Validates OCC if a record with the same key exists.
+     */
+    put(data: T): Promise<string | number>;
+    /**
+     * Iterates over records using a cursor, allowing early termination and skipping.
+     *
+     * @param callback - Invoked for each record; return `{ done: true }` to stop,
+     *                   `{ offset: n }` to skip ahead n records.
+     * @param direction - Iteration order.
+     * @param keyRange - Optional range to restrict iteration.
+     */
+    cursor(callback: CursorCallback<T>, direction?: "forward" | "backward", keyRange?: StoreKeyRange): Promise<T | null>;
+    /**
+     * Executes a batch of write operations atomically within this store.
+     * All operations succeed or fail together.
+     *
+     * Used for standalone (single-store) atomic writes. For cross-store atomicity,
+     * use executeInTransaction instead.
+     */
+    batch(operations: Array<{
+        type: "add" | "put";
+        data: T | T[];
+    } | {
+        type: "delete";
+        data: string | number | (string | number)[];
+    }>): Promise<void>;
+    /**
+     * Registers a new index on the store. Idempotent — no-op if the index already exists.
+     * For IndexedDB, this triggers a database version upgrade.
+     * For MemoryStore, this builds the index map from existing records.
+     *
+     * @param definition - The full index definition from the schema.
+     */
+    createIndex(definition: IndexDefinition): Promise<void>;
+    /**
+     * Removes a named index from the store.
+     * For IndexedDB, this triggers a database version upgrade.
+     * For MemoryStore, this drops the in-memory index map.
+     *
+     * @param name - The index name as declared in IndexDefinition.name.
+     */
+    dropIndex(name: string): Promise<void>;
+    /**
+     * Returns all records matching an exact index key.
+     * Unlike getByIndex (which returns only the first match), this returns all matches —
+     * essential for non-unique indexes where multiple records share the same indexed value.
+     *
+     * @param indexName - The name of the index to query.
+     * @param value - The exact value to look up.
+     */
+    findByIndex(indexName: string, value: any): Promise<T[]>;
+    /**
+     * Executes a set of buffered operations as part of a cross-store atomic transaction.
+     *
+     * For IndexedDBStore: `sharedTx` is the single IDBTransaction opened across all
+     * participating stores. Operations are applied directly to `sharedTx.objectStore(name)`
+     * without opening a new transaction — IDB commits or aborts the whole thing atomically.
+     *
+     * For MemoryStore: `sharedTx` is null. The store applies ops against its own staging
+     * area. The caller (TransactionContext) is responsible for coordinating rollback across
+     * all MemoryStores if any participant fails.
+     *
+     * This method must NOT open, commit, or abort any transaction itself.
+     *
+     * @param ops - The buffered operations to apply.
+     * @param sharedTx - The shared IDBTransaction (IndexedDB only), or null (MemoryStore).
+     */
+    executeInTransaction(ops: BufferedOperation<T>[], sharedTx: IDBTransaction | null): Promise<void>;
+}
+interface Collection<T> {
+    /**
+     * Finds a single document matching the query.
+     */
+    find: (query: QueryFilter<T>) => Promise<Document<T> | null>;
+    /**
+     * Lists documents with pagination. Returns an AsyncIterator so consumers can
+     * wrap it in their own iteration protocol (e.g. for-await-of via AsyncIterable).
+     */
+    list: (query: PaginationOptions) => Promise<AsyncIterator<Document<T>[]>>;
+    /**
+     * Filters all documents matching the query.
+     */
+    filter: (query: QueryFilter<T>) => Promise<Document<T>[]>;
+    /**
+     * Creates a new document in the collection.
+     *
+     * When a TransactionContext is provided the initial store.add is buffered into
+     * the transaction rather than written immediately. The document is returned in
+     * its fully initialised in-memory state regardless — callers can use it before
+     * the transaction commits.
+     *
+     * @param initial - The initial data for the document.
+     * @param tx - Optional transaction to buffer the write into.
+     */
+    create: (initial: T, tx?: TransactionContext) => Promise<Document<T>>;
+    /**
+     * Subscribes to collection-level events.
+     */
+    subscribe: (event: CollectionEventType | TelemetryEventType, callback: (event: CollectionEvent<T> | TelemetryEvent) => void) => () => void;
+    /**
+     * Validates data against the collection's schema.
+     */
+    validate(data: Record<string, any>): Promise<{
+        value?: any;
+        issues: Array<{
+            message: string;
+            path: Array<string>;
+        }>;
+    }>;
+    invalidate(): void;
+}
+/**
+ * Event payload for Collection events.
+ */
+type CollectionEventType = "document:create" | "collection:read" | "migration:start" | "migration:end";
+type CollectionEvent<T> = {
+    type: CollectionEventType;
+    document?: T;
+    model?: string;
+    method?: keyof Collection<T>;
+    metadata?: Record<string, unknown>;
+    timestamp: number;
+};
+interface Database {
+    /**
+     * Opens an existing collection by name.
+     */
+    collection: <T>(schemaName: string) => Promise<Collection<T>>;
+    /**
+     * Creates a new collection from a schema definition.
+     */
+    createCollection: <T>(schema: SchemaDefinition) => Promise<Collection<T>>;
+    /**
+     * Deletes a collection and its schema record.
+     */
+    deleteCollection: (schemaName: string) => Promise<boolean>;
+    /**
+     * Updates an existing collection's schema record.
+     */
+    updateCollection: (schema: SchemaDefinition) => Promise<boolean>;
+    /**
+     * Migrates an existing collection's data and schema definition.
+     * Processes data in a streaming fashion to avoid loading the full collection
+     * into memory.
+     */
+    migrateCollection: <T>(name: string, opts: CollectionMigrationOptions, batchSize?: number) => Promise<Collection<T>>;
+    /**
+     * Executes a callback within a TransactionContext.
+     * Writes buffered inside the callback are flushed atomically on commit.
+     * If the callback throws, the buffer is discarded (no writes are flushed).
+     */
+    transaction: (callback: (tx: TransactionContext) => Promise<void>) => Promise<void>;
+    /**
+     * Subscribes to database-level events.
+     */
+    subscribe: (event: DatabaseEventType | "telemetry", callback: (event: DatabaseEvent | TelemetryEvent) => void) => () => void;
+    /**
+     * Releases in-memory references and event bus subscriptions.
+     * Does not delete any persisted data.
+     */
+    close: () => void;
+    clear: () => Promise<void>;
+    /**
+     * Ensures a collection exists; creates it if it doesn't. Idempotent.
+     */
+    ensureCollection: (schema: SchemaDefinition) => Promise<void>;
+    /**
+     * Ensures multiple collections exist; creates any that don't. Idempotent.
+     */
+    setupCollections: (schemas: SchemaDefinition[]) => Promise<void>;
+}
+type CollectionMigrationOptions = {
+    changes: SchemaChange<any>[];
+    description: string;
+    rollback?: SchemaChange<any>[];
+    transform?: string | DataTransform<any, any>;
+};
+type DatabaseEventType = "collection:create" | "collection:delete" | "collection:update" | "collection:read" | "migrate";
+type DatabaseEvent = {
+    type: DatabaseEventType;
+    schema?: SchemaDefinition | Partial<SchemaDefinition>;
+    timestamp: number;
+};
+type Document<T> = {
+    readonly [K in keyof T]: T[K];
+} & {
+    $id?: string;
+    $created?: string | Date;
+    $updated?: string | Date;
+    $version?: number;
+    read: () => Promise<boolean>;
+    save: (tx?: TransactionContext) => Promise<boolean>;
+    update: (props: Partial<T>, tx?: TransactionContext) => Promise<boolean>;
+    delete: (tx?: TransactionContext) => Promise<boolean>;
+    subscribe: (event: DocumentEventType | TelemetryEventType, callback: (event: DocumentEvent<T> | TelemetryEvent) => void) => () => void;
+    state(): T;
+};
+type DocumentEventType = "document:create" | "document:write" | "document:update" | "document:delete" | "document:read";
+type DocumentEvent<T> = {
+    type: DocumentEventType;
+    data?: Partial<T>;
+    timestamp: number;
+};
+type TelemetryEventType = "telemetry";
+type TelemetryEvent = {
+    type: TelemetryEventType;
+    method: string;
+    timestamp: number;
+    source: any;
+    metadata: {
+        args: any[];
+        performance: {
+            durationMs: number;
+        };
+        source: {
+            level: "database" | "collection" | "document";
+            collection?: string;
+            document?: string;
+        };
+        result?: {
+            type: "array" | string;
+            size?: number;
+        };
+        error: {
+            message: string;
+            name: string;
+            stack?: string;
+        } | null;
+    };
+};
+
+interface WorkspaceDatabase {
+    /**
+     * Open the database. Registers core schemas followed by any extension
+     * schemas supplied by the caller (domain plugins).
+     *
+     * Idempotent — safe to call multiple times; subsequent calls are no-ops
+     * if the database is already open.
+     */
+    open(extensionSchemas?: SchemaDefinition[]): Promise<void>;
+    /**
+     * Access a collection by schema name.
+     * Throws if the schema has not been registered.
+     */
+    collection<T>(schemaName: string): Promise<Collection<T>>;
+    /**
+     * Close the database connection.
+     */
+    close(): void;
+}
+declare function createWorkspaceDatabase(db: Database): WorkspaceDatabase;
+declare const COLLECTIONS: {
+    readonly ROLE: "role";
+    readonly PREFERENCE: "preference";
+    readonly CONTEXT: "context";
+    readonly SESSION: "session";
+    readonly TURN: "turn";
+};
+type CollectionName = typeof COLLECTIONS[keyof typeof COLLECTIONS];
+
 /**
  * Utility type for representing partial updates to the state, allowing deep nesting.
  * It makes all properties optional and applies the same transformation recursively
@@ -560,65 +989,14 @@ declare function del<T>(): T;
 declare const merge: <T extends object>(original: T, changes: DeepPartial<T> | symbol) => T;
 declare function ok<T>(value: T): Result<T, never>;
 declare function err<E = WorkspaceError>(error: E): Result<never, E>;
-
-interface IndexedDBConfig {
-    dbName?: string;
-}
-declare class IndexedDBStorage implements ContentStorage {
-    private readonly dbName;
-    private db;
-    constructor(config?: IndexedDBConfig);
-    open(): Promise<void>;
-    private createSchema;
-    close(): void;
-    deleteDatabase(): Promise<void>;
-    private getDB;
-    private readTx;
-    private writeTx;
-    saveRole(role: Role): Promise<void>;
-    loadRole(name: string): Promise<Role | null>;
-    deleteRole(name: string): Promise<void>;
-    savePreference(preference: Preference): Promise<void>;
-    loadPreference(id: UUID): Promise<Preference | null>;
-    deletePreference(id: UUID): Promise<void>;
-    saveContext(context: Context): Promise<void>;
-    loadContext(key: string): Promise<Context | null>;
-    loadContextBatch(keys: string[]): Promise<Map<string, Context>>;
-    deleteContext(key: string): Promise<void>;
-    saveTurn(sessionId: UUID, turn: Turn): Promise<void>;
-    loadTurn(sessionId: UUID, turnId: UUID, version: number): Promise<Turn | null>;
-    loadAllTurns(sessionId: UUID): Promise<Turn[]>;
-    deleteTurn(sessionId: UUID, turnId: UUID, version: number): Promise<void>;
-    setSessionHead(sessionId: UUID, head: {
-        id: UUID;
-        version: number;
-    } | null): Promise<void>;
-    getSessionHead(sessionId: UUID): Promise<{
-        id: UUID;
-        version: number;
-    } | null>;
-    storeBytes(sha256: SHA256, data: Uint8Array): Promise<void>;
-    loadBytes(sha256: SHA256): Promise<Uint8Array | null>;
-    deleteBytes(sha256: SHA256): Promise<void>;
-    exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
-    saveWorkspace(state: Workspace): Promise<void>;
-    loadWorkspace(): Promise<Workspace | null>;
-    exportBundle(): Promise<{
-        roles: Record<string, Role>;
-        preferences: Record<UUID, Preference>;
-        context: Record<string, Context>;
-        transcripts: Record<UUID, Turn[]>;
-        workspace: Workspace | null;
-    }>;
-    importBundle(data: {
-        roles: Record<string, Role>;
-        preferences: Record<UUID, Preference>;
-        context: Record<string, Context>;
-        transcripts: Record<UUID, Turn[]>;
-        workspace?: Workspace;
-    }): Promise<void>;
-    private getAllFromStore;
-}
+declare function omitNullUndefined<T extends Record<string, any>>(obj: T): Partial<T>;
+declare function createSimpleWorkspace({ name, owner, language }: {
+    name: string;
+    language: string;
+    owner: string;
+}): Workspace;
+declare function extractBlobRecord(patch: DeepPartial<Workspace>): BlobRecord | null;
+declare function extractBlobRef(record: BlobRecord): BlobRef;
 
 /**
  * Persistence contract for binary blob content and blob registry records.
@@ -672,19 +1050,26 @@ interface TurnRef {
     version: number;
 }
 declare class TurnTree {
-    private readonly storage;
-    constructor(storage: ContentStorage);
+    private readonly db;
+    constructor(db: WorkspaceDatabase);
+    private turns;
+    private sessions;
+    /**
+     * Compound filter for a specific (sessionId, id, version) tuple.
+     * Uses only declared schema fields — never $id.
+     */
+    private turnFilter;
+    getHead(sessionId: UUID): Promise<TurnRef | null>;
+    setHead(sessionId: UUID, head: TurnRef | null): Promise<void>;
     append(sessionId: UUID, turn: Turn): Promise<Turn>;
-    appendBatch(sessionId: UUID, turns: Turn[]): Promise<void>;
+    appendBatch(sessionId: UUID, turns: Turn[], finalHead: TurnRef | null): Promise<void>;
     replaceVersion(sessionId: UUID, newTurn: Turn): Promise<void>;
     branch(sessionId: UUID, newTurn: Turn): Promise<void>;
+    loadAllTurns(sessionId: UUID): Promise<Turn[]>;
     getActiveChain(sessionId: UUID, dirtyBuffer?: readonly Turn[]): Promise<Turn[]>;
-    countChained(sessionId: UUID, dirtyBuffer?: readonly Turn[]): Promise<number>;
     buildNodeGraph(sessionId: UUID, dirtyBuffer?: readonly Turn[]): Promise<Record<UUID, TurnNode>>;
     deleteSubtree(sessionId: UUID, turnId: UUID, version: number, newHead: TurnRef | null): Promise<void>;
     copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
-    getHead(sessionId: UUID): Promise<TurnRef | null>;
-    setHead(sessionId: UUID, head: TurnRef | null): Promise<void>;
 }
 
 declare function computeSHA256(data: Uint8Array): Promise<SHA256>;
@@ -741,29 +1126,55 @@ declare class BlobStore {
 }
 
 declare class ContentStore {
-    private readonly storage;
-    private readonly tree;
-    private readonly cache;
-    constructor(storage: ContentStorage, config?: ContentStoreConfig);
+    private readonly db;
+    readonly tree: TurnTree;
+    readonly blobs: BlobStore;
+    private readonly roleCache;
+    private readonly preferenceCache;
+    private readonly contextCache;
+    /**
+     * Called after any blob registry change with the sha256 and updated
+     * BlobRecord (null on deletion). Wire this to your state manager to
+     * keep Index.blobs current.
+     *
+     * ContentStore sets this on BlobStore.onRegistryChanged internally.
+     * Consumers set this property to receive the forwarded notifications.
+     */
+    onBlobRegistryChanged?: (sha256: SHA256, record: BlobRecord | null) => void;
+    private constructor();
+    static create(db: WorkspaceDatabase, blobStorage: BlobStorage, config?: ContentStoreConfig): Promise<ContentStore>;
+    private init;
     getTurnTree(): TurnTree;
     getRole(name: string): Promise<Result<Role, WorkspaceError>>;
-    getPreference(id: UUID): Promise<Result<Preference, WorkspaceError>>;
-    getContext(key: string): Promise<Result<Context, WorkspaceError>>;
-    getContextByTopics(indexState: Index, topics: string[]): Promise<Context[]>;
     saveRole(role: Role): Promise<void>;
-    savePreference(preference: Preference): Promise<void>;
-    saveContext(context: Context): Promise<void>;
     deleteRole(name: string): Promise<void>;
+    getPreference(id: UUID): Promise<Result<Preference, WorkspaceError>>;
+    savePreference(preference: Preference): Promise<void>;
     deletePreference(id: UUID): Promise<void>;
+    getContext(key: string): Promise<Result<Context, WorkspaceError>>;
+    saveContext(context: Context): Promise<void>;
     deleteContext(key: string): Promise<void>;
+    getContextByTopics(indexState: Index, topics: string[]): Promise<Context[]>;
+    saveSession(meta: SessionMeta): Promise<void>;
+    updateSessionMeta(sessionId: UUID, patch: DeepPartial<SessionMeta>): Promise<void>;
+    deleteSession(sessionId: UUID): Promise<void>;
+    registerBlob(data: Uint8Array, mediaType: BlobMediaType, filename?: string): Promise<Result<BlobRef, WorkspaceError>>;
+    retainBlob(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
+    releaseBlob(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
+    purgeBlob(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
+    recordBlobRemoteId(sha256: SHA256, providerId: string, fileId: string): Promise<Result<void, WorkspaceError>>;
+    getBlobRecord(sha256: SHA256): BlobRecord | null;
+    getAllBlobRecords(): Record<SHA256, BlobRecord>;
+    /**
+     * Returns the blob resolver function expected by PromptBuilder.
+     * Closes over the internal BlobStore — no BlobStore reference leaks out.
+     */
+    getBlobResolver(): BlobStore['resolveRefs'];
     recordTurn(sessionId: UUID, turn: Turn): Promise<Result<void, WorkspaceError>>;
     editTurn(sessionId: UUID, turnId: UUID, newBlocks: ContentBlock[], newVersion: number, roleSnapshot?: string): Promise<Result<void, WorkspaceError>>;
     branchTurn(sessionId: UUID, newTurn: Turn): Promise<Result<void, WorkspaceError>>;
     deleteTurnSubtree(sessionId: UUID, turnId: UUID, version: number, newHead: TurnRef | null): Promise<Result<void, WorkspaceError>>;
     copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
-    storeBytes(sha256: SHA256, data: Uint8Array): Promise<void>;
-    loadBytes(sha256: SHA256): Promise<Uint8Array | null>;
-    deleteBytes(sha256: SHA256): Promise<void>;
     resolveSession(workspace: Workspace, sessionId: UUID, transcript?: Turn[]): Promise<Result<EffectiveSession, WorkspaceError>>;
 }
 
@@ -771,6 +1182,12 @@ declare function workspaceReducer({ index: state }: Workspace, command: Command)
 
 declare class WorkspaceManager {
     private readonly contentStore;
+    /**
+     * Called when BlobStore triggers a registry change outside of a dispatch()
+     * call — e.g. eagerEviction deleting a blob on release. The caller should
+     * merge this patch into their Workspace.
+     */
+    onWorkspacePatch?: (patch: DeepPartial<Workspace>) => void;
     constructor(contentStore: ContentStore);
     reduce(workspace: Workspace, command: Command): Result<DeepPartial<Workspace>, WorkspaceError>;
     dispatch(workspace: Workspace, command: Command): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
@@ -902,18 +1319,6 @@ declare function buildTurnNode(turn: Turn, children?: UUID[]): TurnNode;
 interface SessionManagerConfig {
     flush?: Partial<FlushConfig>;
 }
-/**
- * Returned by SessionManager.open().
- *
- * session — the live Session instance. Store this in your component or
- *           module; pass it to every subsequent session.* call.
- *
- * patch   — a DeepPartial<Workspace> that the caller should merge into
- *           their Workspace immediately after open(). Currently empty
- *           (the Workspace index already holds SessionMeta), but present
- *           for forward compatibility — future versions may update head
- *           or flushedTurnCount as part of opening.
- */
 interface OpenResult {
     session: Session;
     patch: DeepPartial<Workspace>;
@@ -928,4 +1333,71 @@ declare class SessionManager {
     get workspace(): WorkspaceManager;
 }
 
-export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTurn, type BaseCommand, type BlobMediaType, type BlobRecord, type BlobRef, type BlobStorage, BlobStore, type BlobStoreConfig, type BranchInfo, type BranchTurn, type CacheConfig, type Command, type ContentBlock, type ContentStorage, ContentStore, type ContentStoreConfig, type Context, type ContextContent, type ContextRelevanceConfig, type ContextSummary, type CreateSession, type CreateWorkspace, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type EditTurn, type EffectiveSession, type FlushConfig, type ForkSession, type ImageBlock, type ImageMediaType, type Index, type IndexedDBConfig, IndexedDBStorage, type OpenResult, type OverrideSessionPreferences, type Preference, type PreferenceConflict, type PreferenceSummary, type Project, type Prompt, PromptBuilder, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type ResolvedBlob, type Result, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, Session, SessionManager, type SessionManagerConfig, type SessionMeta, type Settings, type SummaryBlock, type SwitchRole, type TextBlock, type ThinkingBlock, type Timestamp, type TokenBudget, type ToolResultBlock, type ToolUseBlock, type TopicIndex, type TranscriptWindow, type Turn, type TurnNode, type TurnRef, type TurnRole, TurnTree, type URI, type UUID, type UpdateContext, type UpdatePreference, type UpdateRole, type Workspace, type WorkspaceBundle, type WorkspaceError, WorkspaceManager, buildTurnNode, computeSHA256, del, err, merge, ok, workspaceReducer };
+/**
+ * In-process implementation backed by plain Maps.
+ * Suitable for development, testing, and server-side runtimes without
+ * access to IndexedDB.
+ */
+declare class MemoryBlobStorage implements BlobStorage {
+    private readonly bytes;
+    private readonly records;
+    storeBytes(sha256: SHA256, data: Uint8Array): Promise<void>;
+    loadBytes(sha256: SHA256): Promise<Uint8Array | null>;
+    hasBytes(sha256: SHA256): Promise<boolean>;
+    deleteBytes(sha256: SHA256): Promise<void>;
+    saveRecord(record: BlobRecord): Promise<void>;
+    loadRecord(sha256: SHA256): Promise<BlobRecord | null>;
+    deleteRecord(sha256: SHA256): Promise<void>;
+    listRecords(): Promise<BlobRecord[]>;
+    exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
+    /**
+     * Atomic register for MemoryBlobStorage — sequential ops are atomic
+     * in a single-threaded JS runtime, so this is equivalent to two separate
+     * calls, but we implement it for interface consistency.
+     */
+    registerBlob(record: BlobRecord, data: Uint8Array): Promise<void>;
+}
+
+interface IndexedDBBlobConfig {
+    /** Name of the IndexedDB database. Defaults to 'aiworkspace-blobs'. */
+    dbName?: string;
+}
+/**
+ * IndexedDB-backed blob storage.
+ *
+ * Bytes are stored as raw Uint8Array — IndexedDB handles binary natively,
+ * no base64 encoding at rest. This is important for large files.
+ *
+ * Transaction discipline: never await inside an active transaction.
+ * All multi-step operations chain synchronous IDB request handlers
+ * inside a single Promise.
+ */
+declare class IndexedDBBlobStorage implements BlobStorage {
+    private readonly dbName;
+    private db;
+    constructor(config?: IndexedDBBlobConfig);
+    open(): Promise<void>;
+    private createSchema;
+    close(): void;
+    deleteDatabase(): Promise<void>;
+    private getDB;
+    private readTx;
+    private writeTx;
+    storeBytes(sha256: SHA256, data: Uint8Array): Promise<void>;
+    loadBytes(sha256: SHA256): Promise<Uint8Array | null>;
+    hasBytes(sha256: SHA256): Promise<boolean>;
+    deleteBytes(sha256: SHA256): Promise<void>;
+    saveRecord(record: BlobRecord): Promise<void>;
+    loadRecord(sha256: SHA256): Promise<BlobRecord | null>;
+    deleteRecord(sha256: SHA256): Promise<void>;
+    listRecords(): Promise<BlobRecord[]>;
+    exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
+    /**
+     * Atomically stores bytes and saves a record together.
+     * Preferred over calling storeBytes + saveRecord separately when both
+     * are new — avoids a window where bytes exist without a record.
+     */
+    registerBlob(record: BlobRecord, data: Uint8Array): Promise<void>;
+}
+
+export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTurn, type BaseCommand, type BlobCommand, type BlobMediaType, type BlobRecord, type BlobRef, type BlobStorage, BlobStore, type BlobStoreConfig, type BranchInfo, type BranchTurn, COLLECTIONS, type CacheConfig, type CollectionName, type Command, type ContentBlock, ContentStore, type ContentStoreConfig, type Context, type ContextContent, type ContextRelevanceConfig, type ContextSummary, type CreateSession, type CreateWorkspace, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type EditTurn, type EffectiveSession, type FlushConfig, type ForkSession, type ImageBlock, type ImageMediaType, type Index, type IndexedDBBlobConfig, IndexedDBBlobStorage, MemoryBlobStorage, type OpenResult, type OverrideSessionPreferences, type Preference, type PreferenceConflict, type PreferenceSummary, type Project, type Prompt, PromptBuilder, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type ResolvedBlob, type Result, type RetainBlob, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, Session, SessionManager, type SessionManagerConfig, type SessionMeta, type Settings, type SummaryBlock, type SwitchRole, type TextBlock, type ThinkingBlock, type Timestamp, type TokenBudget, type ToolResultBlock, type ToolUseBlock, type TopicIndex, type TranscriptWindow, type Turn, type TurnNode, type TurnRef, type TurnRole, TurnTree, type URI, type UUID, type UpdateContext, type UpdatePreference, type UpdateRole, type Workspace, type WorkspaceBundle, type WorkspaceDatabase, type WorkspaceError, WorkspaceManager, buildTurnNode, computeSHA256, createSimpleWorkspace, createWorkspaceDatabase, del, err, extractBlobRecord, extractBlobRef, merge, ok, omitNullUndefined, workspaceReducer };