@asaidimu/utils-workspace 1.0.1 → 2.1.0

package/index.d.ts

@@ -1,3 +1,6 @@
+import { QueryFilter, PaginationOptions } from '@asaidimu/query';
+import { SchemaDefinition, SchemaChange, DataTransform } from '@asaidimu/anansi';
+
 type UUID = string;
 type Timestamp = string;
 type URI = string;
@@ -9,8 +12,6 @@ type Result<T, E = WorkspaceError> = {
     ok: false;
     error: E;
 };
-declare function ok<T>(value: T): Result<T, never>;
-declare function err<E = WorkspaceError>(error: E): Result<never, E>;
 type WorkspaceError = {
     code: 'DUPLICATE_KEY';
     resource: string;
@@ -31,7 +32,7 @@ type WorkspaceError = {
 };
 interface Settings {
     language: string;
-    defaultRole: string;
+    defaultRole?: string;
     prompt?: string;
 }
 interface Project {
@@ -43,13 +44,12 @@ interface Project {
 type ImageMediaType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
 type DocumentMediaType = 'application/pdf' | 'application/json' | 'text/plain' | 'text/html' | 'text/markdown' | 'text/csv' | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
 type BlobMediaType = ImageMediaType | DocumentMediaType;
-interface BlobRef {
-    sha256: SHA256;
-    mediaType: BlobMediaType;
-    sizeBytes: number;
-    filename?: string;
-    previewUrl?: string;
-}
+/**
+ * Lightweight pointer to a blob — the subset of BlobRecord that content
+ * blocks and context entries carry. Use this at call sites that only need
+ * to reference a blob, not inspect its registry metadata.
+ */
+type BlobRef = Pick<BlobRecord, 'sha256' | 'mediaType' | 'sizeBytes' | 'filename' | 'previewUrl'>;
 type ResolvedBlob = {
     kind: 'inline';
     sha256: SHA256;
@@ -62,37 +62,35 @@ type ResolvedBlob = {
     fileId: string;
     providerId: string;
 };
+/**
+ * Full registry entry for a blob. BlobRef is a Pick of this type, so
+ * a BlobRecord is always assignable to BlobRef.
+ */
 interface BlobRecord {
     sha256: SHA256;
     mediaType: BlobMediaType;
     sizeBytes: number;
     filename?: string;
+    previewUrl?: string;
     refCount: number;
     remoteIds: Record<string, string>;
     createdAt: Timestamp;
     lastUsedAt: Timestamp;
 }
-interface BlobSummary {
-    sha256: SHA256;
-    mediaType: BlobMediaType;
-    sizeBytes: number;
-    filename?: string;
-    refCount: number;
-    createdAt: Timestamp;
-    lastUsedAt: Timestamp;
-}
 interface TextBlock {
     type: 'text';
     text: string;
 }
 interface ImageBlock {
     type: 'image';
-    blob: ResolvedBlob;
+    ref?: BlobRef;
+    blob?: ResolvedBlob;
     altText?: string;
 }
 interface DocumentBlock {
     type: 'document';
-    blob: ResolvedBlob;
+    ref?: BlobRef;
+    blob?: ResolvedBlob;
     title?: string;
 }
 interface ToolUseBlock {
@@ -111,7 +109,16 @@ interface ThinkingBlock {
     type: 'thinking';
     thinking: string;
 }
-type ContentBlock = TextBlock | ImageBlock | DocumentBlock | ToolUseBlock | ToolResultBlock | ThinkingBlock;
+interface SummaryBlock {
+    type: 'summary';
+    text: string;
+}
+interface RoleTransitionBlock {
+    type: 'role_transition';
+    previousRole: string | null;
+    newRole: string;
+}
+type ContentBlock = TextBlock | ImageBlock | DocumentBlock | ToolUseBlock | ToolResultBlock | SummaryBlock | RoleTransitionBlock | ThinkingBlock;
 type TurnRole = 'user' | 'assistant' | 'tool';
 interface Turn {
     id: UUID;
@@ -119,75 +126,89 @@ 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 SessionSummary {
+interface TurnNode {
     id: UUID;
-    label: string;
-    role: string;
-    topics: string[];
-    created: Timestamp;
-    updated: Timestamp;
-    turns: number;
+    versions: Record<number, Turn>;
+    activeVersion: number;
+    role: TurnRole;
+    blocks: ContentBlock[];
+    timestamp: Timestamp;
+    roleSnapshot?: string;
+    parent: {
+        id: UUID;
+        version: number;
+    } | null;
+    children: Record<number, UUID[]>;
 }
-interface RoleSummary {
+interface BranchInfo {
+    versions: number[];
+    currentIndex: number;
+    total: number;
+    hasPrev: boolean;
+    hasNext: boolean;
+}
+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 Indexes {
-    sessions: Record<UUID, SessionSummary>;
-    roles: Record<string, RoleSummary>;
-    preferences: Record<UUID, PreferenceSummary>;
-    context: Record<string, ContextSummary>;
-    topics: Record<string, TopicIndex>;
-}
-interface Workspace {
-    id: UUID;
-    settings: Settings;
-    project: Project;
-    indexes: Indexes;
-}
-interface IndexState {
-    format: string;
-    workspace: Workspace;
-    roles: Record<string, RoleSummary>;
-    preferences: Record<UUID, PreferenceSummary>;
-    context: Record<string, ContextSummary>;
-    sessions: Record<UUID, SessionMeta>;
-    blobs: Record<SHA256, BlobSummary>;
-}
+/**
+ * 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;
@@ -204,68 +225,76 @@ 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: string | object | URI;
     topics: string[];
     timestamp: Timestamp;
+    mime?: string;
+    size?: number;
+    preview?: string;
+    source?: string;
     metadata?: Record<string, any>;
-    attachments?: BlobRef[];
 }
-interface Session {
-    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>;
+    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;
     preferences: Preference[];
     context: Context[];
     transcript: Turn[];
-    systemPrompt?: string;
+    instructions?: string;
 }
 interface CacheConfig {
     roles?: number;
     preferences?: number;
-    contextEntries?: number;
-    transcriptWindows?: number;
+    context?: number;
 }
 interface FlushConfig {
     maxBufferSize: number;
@@ -274,7 +303,6 @@ interface FlushConfig {
 interface ContentStoreConfig {
     cache?: CacheConfig;
     flush?: FlushConfig;
-    transcriptWindowSize?: number;
 }
 interface BaseCommand {
     type: string;
@@ -385,13 +413,6 @@ interface DeleteTurn extends BaseCommand {
         } | null;
     };
 }
-interface AddInteraction extends BaseCommand {
-    type: 'turn:add';
-    payload: {
-        sessionId: UUID;
-        turn: Turn;
-    };
-}
 interface SwitchRole extends BaseCommand {
     type: 'session:role:switch';
     payload: {
@@ -431,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 {
@@ -447,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;
@@ -464,170 +502,524 @@ interface ContextRelevanceConfig {
     minScore?: number;
     freshnessHalfLifeDays?: number;
 }
-interface BuiltTurn {
-    role: TurnRole;
-    blocks: ContentBlock[];
-}
+/**
+ * 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.
+ */
 interface Prompt {
-    system: string | null;
-    turns: BuiltTurn[];
-    blobs: BlobRef[];
+    system: {
+        instructions?: string;
+        persona: string;
+        preferences: Preference[];
+        context: Context[];
+    };
+    context: Context[];
+    transcript: {
+        turns: Turn[];
+    };
+    budget: {
+        total: number;
+        used: number;
+        breakdown: Record<string, number>;
+    };
     truncated: {
         preferences: number;
         interactions: number;
-        contextEntries: number;
+        context: number;
     };
-    conflicts: PreferenceConflict[];
     warnings: string[];
+    conflicts: PreferenceConflict[];
 }
-
-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>;
-    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, limit?: number): Promise<Turn[]>;
-    setSessionHead(sessionId: UUID, head: {
-        id: UUID;
-        version: number;
-    } | null): Promise<void>;
-    getSessionHead(sessionId: UUID): Promise<{
-        id: UUID;
-        version: number;
-    } | null>;
-    deleteTurnSubtree(sessionId: UUID, turnId: UUID, version: number): Promise<void>;
-    getActiveChain(sessionId: UUID): Promise<Turn[]>;
-    countChainedTurns(sessionId: UUID): Promise<number>;
-    copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
+interface TranscriptWindow {
+    sessionId: UUID;
+    turns: Turn[];
+    flushedCount: number;
+    hasMore: boolean;
 }
-declare class MemoryStorage implements ContentStorage {
-    private readonly roles;
-    private readonly preferences;
-    private readonly contexts;
-    private readonly turnVersions;
-    private readonly sessionHeads;
-    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>;
-    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, limit?: number): Promise<Turn[]>;
-    setSessionHead(sessionId: UUID, head: {
-        id: UUID;
-        version: number;
-    } | null): Promise<void>;
-    getSessionHead(sessionId: UUID): Promise<{
-        id: UUID;
-        version: number;
-    } | null>;
-    getActiveChain(sessionId: UUID): Promise<Turn[]>;
-    deleteTurnSubtree(sessionId: UUID, turnId: UUID, version: number): Promise<void>;
-    countChainedTurns(sessionId: UUID): Promise<number>;
-    copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
-    static fromBundle(bundle: WorkspaceBundle): {
-        backend: MemoryStorage;
-        indexState: IndexState;
-    };
+
+declare class TransactionContext {
+    readonly id: string;
+    private buffer;
+    private committed;
+    constructor();
+    addOp(store: Store<any>, type: "put" | "delete", data: any): void;
+    commit(): Promise<void>;
+    rollback(): void;
 }
 
+interface CursorCallbackResult<T> {
+    value: T | null;
+    done: boolean;
+    offset?: number;
+}
 /**
- * Utility type for representing partial updates to the state, allowing deep nesting.
- * It makes all properties optional and applies the same transformation recursively
- * to nested objects and array elements, allowing for selective updates while
- * preserving the original structure. It also includes the original type T and
- * undefined as possibilities for the top level and nested values.
+ * 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 that resolves to an object indicating whether iteration should stop, and an optional offset to advance.
  */
-type DeepPartial<T> = T extends object ? T extends readonly (infer U)[] ? readonly (DeepPartial<U> | undefined)[] | undefined | T : T extends (infer U)[] ? (DeepPartial<U> | undefined)[] | undefined | T : {
-    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> | undefined : T[K] | undefined;
-} | undefined | T : T | undefined;
-
-declare function del<T>(): T;
-declare const merge: <T extends object>(original: T, changes: DeepPartial<T> | symbol) => T;
-
-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>;
-    deleteContext(key: string): Promise<void>;
-    saveTurn(sessionId: UUID, turn: Turn): Promise<void>;
-    loadAllTurns(sessionId: UUID, limit?: number): Promise<Turn[]>;
-    countChainedTurns(sessionId: UUID): Promise<number>;
-    loadTurn(sessionId: UUID, turnId: UUID, version: number): Promise<Turn | null>;
-    setSessionHead(sessionId: UUID, head: {
-        id: UUID;
-        version: number;
-    } | null): Promise<void>;
-    getSessionHead(sessionId: UUID): Promise<{
-        id: UUID;
-        version: number;
-    } | null>;
-    getActiveChain(sessionId: UUID): Promise<Turn[]>;
-    deleteTurnSubtree(sessionId: UUID, turnId: UUID, version: number): Promise<void>;
-    copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
-    saveIndexState(state: IndexState): Promise<void>;
-    loadIndexState(): Promise<IndexState | null>;
-    exportBundle(): Promise<{
-        roles: Record<string, Role>;
-        preferences: Record<UUID, Preference>;
-        context: Record<string, Context>;
-        transcripts: Record<UUID, Turn[]>;
-        indexState: IndexState | null;
-    }>;
-    importBundle(data: {
-        roles: Record<string, Role>;
-        preferences: Record<UUID, Preference>;
-        context: Record<string, Context>;
-        transcripts: Record<UUID, Turn[]>;
-        indexState?: IndexState;
-    }): Promise<void>;
-    private getAllFromStore;
+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;
 }
-
 /**
- * Persistence contract for binary blob content and blob registry records.
+ * Storage adapter interface for a single object store (collection).
  *
- * Two concerns live here together deliberately:
- *   1. Raw bytes — stored and retrieved by SHA-256.
- *   2. BlobRecord — the registry entry that tracks ref counts and remote IDs.
+ * This interface abstracts all low‑level persistence operations, allowing
+ * different backends (IndexedDB, memory, remote, etc.) to be used interchangeably.
+ * All methods return promises and operate on clones of data to prevent
+ * unintended mutations.
  *
- * Keeping them in the same backend ensures atomicity: registering a blob and
- * storing its bytes happen in the same transaction boundary.
+ * @template T - The type of objects stored in this store. Must include the key path property.
  */
-interface BlobStorage {
+interface Store<T = any> {
     /**
-     * Store raw bytes for a blob. Idempotent — if the SHA-256 already exists
-     * the bytes are not re-written (content-addressed, so they are identical).
+     * 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 (e.g., auto‑incremented number) may be assigned. The store's key path
+     * property is then updated on the added record(s).
+     *
+     * @param data - A single record or an array of records to add.
+     * @returns A promise that resolves to:
+     *   - the key(s) of the added record(s) – a single key if `data` was a single record,
+     *     or an array of keys if `data` was an array.
+     * @throws {Error} If any record lacks the key path property and auto‑keying is not supported,
+     *                 or if a record with the same key already exists.
+     */
+    add(data: T | T[]): Promise<string | number | (string | number)[]>;
+    /**
+     * Removes all records from the store.
+     *
+     * @returns A promise that resolves when the store is cleared.
+     * @throws {Error} If the operation fails (e.g., store is closed).
+     */
+    clear(): Promise<void>;
+    /**
+     * Returns the total number of records in the store.
+     *
+     * @returns A promise that resolves to the record count.
+     * @throws {Error} If the operation fails.
+     */
+    count(): Promise<number>;
+    /**
+     * Deletes one or more records by their keys.
+     *
+     * @param id - A single key or an array of keys to delete.
+     * @returns A promise that resolves when the records are deleted.
+     * @throws {Error} If any key is `undefined` or the operation fails.
+     */
+    delete(id: string | number | (string | number)[]): Promise<void>;
+    /**
+     * Retrieves a single record by its primary key.
+     *
+     * @param id - The key of the record to retrieve.
+     * @returns A promise that resolves to the record (cloned) if found, otherwise `undefined`.
+     * @throws {Error} If the key is `undefined` or the operation fails.
+     */
+    getById(id: string | number): Promise<T | undefined>;
+    /**
+     * Retrieves a single record by an index and index key.
+     *
+     * @param index - The name of the index to query.
+     * @param key - The exact key value to look up in the index.
+     * @returns A promise that resolves to the first matching record (cloned), or `undefined` if none.
+     * @throws {Error} If the index does not exist, the key is `undefined`, or the operation fails.
+     */
+    getByIndex(index: string, key: any): Promise<T | undefined>;
+    /**
+     * Retrieves multiple records from an index, optionally within a key range.
+     *
+     * @param index - The name of the index to query.
+     * @param keyRange - Optional `StoreKeyRange` to filter results. If omitted, all records are returned.
+     * @returns A promise that resolves to an array of matching records (each cloned).
+     * @throws {Error} If the index does not exist or the operation fails.
+     */
+    getByKeyRange(index: string, keyRange?: StoreKeyRange): Promise<T[]>;
+    /**
+     * Retrieves all records from the store.
+     *
+     * @returns A promise that resolves to an array of all records (each cloned).
+     * @throws {Error} If the operation fails.
+     */
+    getAll(): Promise<T[]>;
+    /**
+     * Inserts or replaces a record.
+     *
+     * If a record with the same key already exists, it is replaced.
+     * The record must contain the store's key path property.
+     *
+     * @param data - The record to store.
+     * @returns A promise that resolves to the key of the stored record.
+     * @throws {Error} If the record lacks the key path property or the operation fails.
+     */
+    put(data: T): Promise<string | number>;
+    /**
+     * Iterates over records using a cursor, allowing early termination and skipping.
+     *
+     * The callback is invoked for each record in iteration order. The callback
+     * can control the iteration by returning `{ done: true }` to stop, or
+     * `{ offset: n }` to skip ahead `n` records.
+     *
+     * @param callback - Function called for each record.
+     * @param direction - Iteration direction: `"forward"` (ascending keys) or `"backward"` (descending keys).
+     * @param keyRange - An optional StoreKeyRange to start from specific points.
+     * @returns A promise that resolves to the last record processed (or `null` if none).
+     * @throws {Error} If the callback throws or the operation fails.
+     */
+    cursor(callback: CursorCallback<T>, direction?: "forward" | "backward", keyRange?: StoreKeyRange): Promise<T | null>;
+    /**
+     * Executes a batch of write operations atomically.
+     *
+     * All operations in the batch succeed or fail together. This is useful for
+     * maintaining consistency when multiple writes are required.
+     *
+     * @param operations - An array of operations. Each operation can be:
+     *   - `{ type: "add" | "put", data: T | T[] }`
+     *   - `{ type: "delete", data: string | number | (string | number)[] }`
+     * @returns A promise that resolves when the batch is committed.
+     * @throws {Error} If any operation fails or the batch cannot be completed.
+     */
+    batch(operations: Array<{
+        type: "add" | "put";
+        data: T | T[];
+    } | {
+        type: "delete";
+        data: string | number | (string | number)[];
+    }>): Promise<void>;
+    open(): Promise<void>;
+}
+interface Collection<T> {
+    /**
+     * Finds a single document matching the query.
+     * @param query - The query to execute.
+     * @returns A promise resolving to the matching document or `null` if not found.
+     */
+    find: (query: QueryFilter<T>) => Promise<Document<T> | null>;
+    /**
+     * Lists documents based on the provided query.
+     * @param query - The query to list documents (supports pagination and sorting).
+     * @returns A promise resolving to an array of documents.
+     */
+    list: (query: PaginationOptions) => Promise<AsyncIterator<Document<T>[]>>;
+    /**
+     * Filters documents based on the provided query.
+     * @param query - The query to filter documents.
+     * @returns A promise resolving to an array of matching documents.
+     */
+    filter: (query: QueryFilter<T>) => Promise<Document<T>[]>;
+    /**
+     * Creates a new document in the schema.
+     * @param initial - The initial data for the document.
+     * @returns A promise resolving to the created document.
+     */
+    create: (initial: T) => Promise<Document<T>>;
+    /**
+     * Subscribes to schema-level events (e.g., "create", "update", "delete", "access").
+     * @param event - The event type to subscribe to.
+     * @param callback - The function to call when the event occurs.
+     * @returns A promise resolving to an unsubscribe function.
+     */
+    subscribe: (event: CollectionEventType | TelemetryEventType, callback: (event: CollectionEvent<T> | TelemetryEvent) => void) => Promise<() => void>;
+    /**
+     * Validate data
+     * @param data - The data to validate
+     * @returns An object containing validation results
+     */
+    validate(data: Record<string, any>): Promise<{
+        value?: any;
+        issues: Array<{
+            message: string;
+            path: Array<string>;
+        }>;
+    }>;
+}
+/**
+ * Event payload for DocumentCursor 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 {
+    /**
+     * Accesses a schema model by name.
+     * @param schemaName - The name of the schema to access.
+     * @returns A promise resolving to the schema's DocumentCursor.
+     * @throws DatabaseError
+     */
+    collection: <T>(schemaName: string) => Promise<Collection<T>>;
+    /**
+     * Creates a new schema model.
+     * @param schema - The schema definition.
+     * @returns A promise resolving to the created schema's DocumentCursor.
+     * @throws DatabaseError
+     */
+    createCollection: <T>(schema: SchemaDefinition) => Promise<Collection<T>>;
+    /**
+     * Deletes a schema by name.
+     * @param schemaName - The name of the schema to delete.
+     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+     * @throws DatabaseError
+     */
+    deleteCollection: (schemaName: string) => Promise<boolean>;
+    /**
+     * Updates an existing schema.
+     * @param schema - The updated schema definition.
+     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+     * @throws DatabaseError
+     */
+    updateCollection: (schema: SchemaDefinition) => Promise<boolean>;
+    /**
+     * Migrates an existing collection's data and updates its schema definition metadata.
+     * This function processes data in a streaming fashion to prevent loading
+     * the entire collection into memory.
+     *
+     * It will:
+     * 1. Verify the target collection exists.
+     * 2. Retrieve the collection's current schema definition from a metadata store ($index).
+     * 3. Initialize a `MigrationEngine` with this schema.
+     * 4. Allow a callback to define specific data transformations using the `MigrationEngine`.
+     * 5. **Crucially, it uses `migrationEngine.dryRun()` to get the `newSchema` that results**
+     * **from the transformations defined in the callback.**
+     * 6. Execute these transformations by streaming data from the collection,
+     * through the `MigrationEngine`, and back into the same collection.
+     * 7. Finally, update the schema definition for the collection in the `$index` metadata store
+     * to reflect this `newSchema`.
+     * All these steps for data and metadata updates happen within a single atomic IndexedDB transaction.
+     *
+     * Note: This function focuses solely on *data transformation* and *metadata updates*.
+     * It does NOT handle structural IndexedDB changes like adding/removing physical indexes or object stores,
+     * which still require an `onupgradeneeded` event (i.e., a database version upgrade).
+     *
+     * @param name - The name of the collection (IndexedDB object store) to migrate.
+     * @param {Object} opts - Options for the new migration
+     * @param {SchemaChange<any>[]} opts.changes - Array of schema changes
+     * @param {string} opts.description - Description of the migration
+     * @param {SchemaChange<any>[]} [opts.rollback] - Optional rollback changes
+     * @param {DataTransform<any, any>} [opts.transform] - Optional data transform
+     * @returns A Promise resolving to `true` if the migration completes successfully,
+     * @throws {DatabaseError} If the collection does not exist, its schema metadata is missing,
+     * or any IndexedDB operation/streaming fails critically.
+     */
+    migrateCollection: (name: string, opts: CollectionMigrationOptions, batchSize?: number) => Promise<boolean>;
+    /**
+     * Subscribes to database-level events (e.g., "schemaAdded", "schemaDeleted", "schemaAccessed", "migrate").
+     * @param event - The event type to subscribe to.
+     * @param callback - The function to call when the event occurs.
+     * @returns A promise resolving to an unsubscribe function.
+     */
+    subscribe: (event: DatabaseEventType | "telemetry", callback: (event: DatabaseEvent | TelemetryEvent) => void) => Promise<() => void>;
+    /**
+     * Closes the connection to the database
+     */
+    close: () => void;
+    /**
+      * Ensures a collection exists; creates it if it doesn't.
+      * Idempotent – safe to call multiple times.
+      * @param schema - The schema definition for the collection.
+      * @returns A promise that resolves when the collection exists.
+      * @throws {DatabaseError} If validation fails or an unexpected error occurs.
+      */
+    ensureCollection: (schema: SchemaDefinition) => Promise<void>;
+    /**
+     * Ensures multiple collections exist; creates any that don't.
+     * Idempotent – safe to call multiple times.
+     * @param schemas - An array of schema definitions.
+     * @returns A promise that resolves when all collections exist.
+     * @throws {DatabaseError} If any schema validation fails or an unexpected error occurs.
+     */
+    setupCollections: (schemas: SchemaDefinition[]) => Promise<void>;
+}
+type CollectionMigrationOptions = {
+    changes: SchemaChange<any>[];
+    description: string;
+    rollback?: SchemaChange<any>[];
+    transform?: string | DataTransform<any, any>;
+};
+/**
+ * Event payload for Database events.
+ */
+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];
+} & {
+    /**
+     * Unique identifier for the document (assigned automatically if not provided).
+     */
+    $id?: string;
+    /**
+     * Timestamp of document creation (ISO string or Date).
+     */
+    $created?: string | Date;
+    /**
+     * Timestamp of last document update (ISO string or Date).
+     */
+    $updated?: string | Date;
+    /**
+     * Version number incremented on each change (used for optimistic concurrency control).
+     */
+    $version?: number;
+    /**
+     * Fetches the latest data from the database and updates the document instance.
+     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+     */
+    read: () => Promise<boolean>;
+    /**
+    * Saves the current document state to the database.
+    * Normally called automatically by `update()` or `delete()`, but can be used manually.
+    * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+    */
+    save: (tx?: TransactionContext) => Promise<boolean>;
+    /**
+     * Updates the document with the provided properties.
+     * @param props - Partial object containing the fields to update.
+     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+     */
+    update: (props: Partial<T>) => Promise<boolean>;
+    /**
+     * Deletes the document from the database.
+     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+     */
+    delete: () => Promise<boolean>;
+    /**
+     * Subscribes to document events (e.g., "update", "delete", "access").
+     * @param event - The event type to subscribe to.
+     * @param callback - The function to call when the event occurs.
+     * @returns An unsubscribe function.
+     */
+    subscribe: (event: DocumentEventType | TelemetryEventType, callback: (event: DocumentEvent<T> | TelemetryEvent) => void) => () => void;
+    /**
+     * Returns a plain object containing only the user-defined data (without system fields like $id, $version, etc.).
+     * @returns The current user data.
+     */
+    state(): T;
+};
+/**
+ * Event payload for DocumentModel events.
+ */
+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
+ * to nested objects and array elements, allowing for selective updates while
+ * preserving the original structure. It also includes the original type T and
+ * undefined as possibilities for the top level and nested values.
+ */
+type DeepPartial<T> = T extends object ? T extends readonly (infer U)[] ? readonly (DeepPartial<U> | undefined)[] | undefined | T : T extends (infer U)[] ? (DeepPartial<U> | undefined)[] | undefined | T : {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> | undefined : T[K] | undefined;
+} | undefined | T : T | undefined;
+
+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>;
+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.
+ *
+ * Two concerns live here together deliberately:
+ *   1. Raw bytes — stored and retrieved by SHA-256.
+ *   2. BlobRecord — the registry entry that tracks ref counts and remote IDs.
+ *
+ * Keeping them in the same backend ensures atomicity: registering a blob and
+ * storing its bytes happen in the same transaction boundary.
+ */
+interface BlobStorage {
+    /**
+     * Store raw bytes for a blob. Idempotent — if the SHA-256 already exists
+     * the bytes are not re-written (content-addressed, so they are identical).
      */
     storeBytes(sha256: SHA256, data: Uint8Array): Promise<void>;
     /** Load raw bytes. Returns null if the blob is not stored locally. */
@@ -652,65 +1044,40 @@ interface BlobStorage {
      * Used for workspace export / migration.
      */
     exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
+    /**
+     * Optional atomic operation: store bytes and save record in a single
+     * transaction. Backends that support this (e.g. IndexedDB) should
+     * implement it to avoid a window where bytes exist without a record.
+     * BlobStore will prefer this over calling storeBytes + saveRecord separately.
+     */
+    registerBlob?(record: BlobRecord, data: Uint8Array): Promise<void>;
 }
-/**
- * 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]>>;
-}
-interface IndexedDBBlobConfig {
-    /** Name of the IndexedDB database. Defaults to 'aiworkspace-blobs'. */
-    dbName?: string;
+
+interface TurnRef {
+    id: UUID;
+    version: number;
 }
-/**
- * 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 matches IndexedDBBlobStorage: 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]>>;
+declare class TurnTree {
+    private readonly db;
+    constructor(db: WorkspaceDatabase);
+    private turns;
+    private sessions;
     /**
-     * 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.
+     * Compound filter for a specific (sessionId, id, version) tuple.
+     * Uses only declared schema fields — never $id.
      */
-    registerBlob(record: BlobRecord, data: Uint8Array): Promise<void>;
+    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[], 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[]>;
+    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>;
 }
 
 declare function computeSHA256(data: Uint8Array): Promise<SHA256>;
@@ -718,13 +1085,12 @@ interface BlobStoreConfig {
     /**
      * When true, blobs with refCount === 0 are deleted from the backend
      * immediately on release. When false (default), they are retained until
-     * an explicit GC sweep via gc(). Lazy GC is safer for offline-first apps
-     * that may need blobs for re-upload after a crash.
+     * an explicit GC sweep via gc(). Lazy GC is safer for offline-first apps.
      */
     eagerEviction?: boolean;
 }
 declare class BlobStore {
-    private readonly backend;
+    private readonly storage;
     private readonly config;
     /**
      * In-memory cache of BlobRecords. Kept consistent with the backend on
@@ -733,61 +1099,22 @@ declare class BlobStore {
     private readonly recordCache;
     /**
      * Called after any operation that changes the blob registry.
-     * The integration layer wires this to an IndexState patch that updates
-     * IndexState.blobs with the new BlobSummary.
+     * Passes the full BlobRecord (or null on deletion). The integration
+     * layer wires this to an Index patch that updates the blob index.
+     *
+     * BlobRecord is a superset of the former BlobSummary — callers
+     * that only need summary fields (sha256, mediaType, sizeBytes, etc.)
+     * can read them directly from BlobRecord without a separate type.
      */
-    onRegistryChanged?: (sha256: SHA256, summary: BlobSummary | null) => void;
+    onRegistryChanged?: (sha256: SHA256, record: BlobRecord | null) => void;
     constructor(backend: BlobStorage, config?: BlobStoreConfig);
     init(): Promise<void>;
-    /**
-     * Register a binary blob and return a BlobRef.
-     *
-     * If the same bytes have been registered before (same SHA-256), only the
-     * ref count is incremented — bytes are not written again.
-     *
-     * @param data      Raw binary content.
-     * @param mediaType MIME type of the content.
-     * @param filename  Optional original filename for UI display.
-     */
     register(data: Uint8Array, mediaType: BlobMediaType, filename?: string): Promise<Result<BlobRef, WorkspaceError>>;
-    /**
-     * Increment the ref count for a blob that is being referenced by a new
-     * turn or context entry. Safe to call multiple times for the same sha256.
-     */
     retain(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
-    /**
-     * Decrement the ref count. When it reaches 0, the blob is eligible for
-     * eviction. With eagerEviction=true, bytes are deleted immediately.
-     * With eagerEviction=false, bytes are retained until gc() is called.
-     */
     release(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
-    /**
-     * Record that a blob has been uploaded to a provider and assigned a file ID.
-     * Idempotent — calling with the same providerId + fileId has no effect.
-     */
     recordRemoteId(sha256: SHA256, providerId: string, fileId: string): Promise<Result<void, WorkspaceError>>;
-    /**
-     * Get the remote file ID for a blob on a specific provider, if known.
-     */
     getRemoteId(sha256: SHA256, providerId: string): string | null;
-    /**
-     * Resolve a BlobRef to a ResolvedBlob.
-     *
-     * If a remote file ID is known for the given providerId, returns
-     * { kind: 'remote' } — no bytes transferred to the model call.
-     * Otherwise loads bytes from the backend and returns { kind: 'inline' }.
-     *
-     * @param ref        The BlobRef to resolve.
-     * @param providerId The provider the resolved blob will be sent to
-     *                   (e.g. 'anthropic', 'openai'). Used to look up
-     *                   known remote file IDs. Pass null for local-only use.
-     */
     resolveRef(ref: BlobRef, providerId: string | null): Promise<Result<ResolvedBlob, WorkspaceError>>;
-    /**
-     * Resolve multiple BlobRefs, collecting all results.
-     * Returns a map of sha256 → ResolvedBlob for successes and a list of
-     * errors for failures, so partial failures don't block the whole build.
-     */
     resolveRefs(refs: BlobRef[], providerId: string | null): Promise<{
         resolved: Map<SHA256, ResolvedBlob>;
         errors: Array<{
@@ -795,74 +1122,84 @@ declare class BlobStore {
             error: WorkspaceError;
         }>;
     }>;
-    /**
-     * Delete bytes for all blobs with refCount === 0.
-     * Records are kept so re-registration is cheap (no re-hash needed).
-     * Call this periodically or on app startup to reclaim storage.
-     *
-     * Returns the number of blobs whose bytes were evicted.
-     */
     gc(): Promise<number>;
-    /**
-     * Fully purge a blob — delete both bytes and record regardless of refCount.
-     * Only use this for explicit user-initiated deletion or during workspace
-     * destruction. In normal operation, use release() and let GC handle it.
-     */
+    gcFull(): Promise<number>;
     purge(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
     getRecord(sha256: SHA256): BlobRecord | null;
-    getSummary(sha256: SHA256): BlobSummary | null;
-    /** All summaries — used to seed IndexState.blobs on init. */
-    getAllSummaries(): Record<SHA256, BlobSummary>;
+    /**
+     * All records — used to seed Index.blobs on init.
+     * Returns BlobRecord directly (BlobSummary has been removed).
+     */
+    getAllRecords(): Record<SHA256, BlobRecord>;
 }
 
 declare class ContentStore {
-    private readonly storage;
-    private readonly cache;
-    private readonly config;
-    private activeSession;
-    private pinnedPreferenceIds;
-    onFlushed?: (sessionId: UUID, flushedCount: number) => void;
-    onSessionInvalidated?: (sessionId: UUID) => void;
-    constructor(backend: ContentStorage, config?: ContentStoreConfig);
-    getActiveSessionId(): UUID | null;
+    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: IndexState, topics: string[]): Promise<Context[]>;
-    getTranscriptWindow(sessionId: UUID, windowSize?: number): Promise<TranscriptWindow>;
     saveRole(role: Role): Promise<void>;
-    savePreference(preference: Preference): Promise<void>;
-    saveContext(context: Context): Promise<void>;
-    copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): 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: {
-        id: UUID;
-        version: number;
-    } | null): Promise<Result<void, WorkspaceError>>;
-    activateSession(meta: SessionMeta): Promise<Result<void, WorkspaceError>>;
-    deactivateSession(meta?: SessionMeta): Promise<void>;
-    resolveSession(indexState: IndexState, sessionId: UUID): Promise<Result<EffectiveSession, WorkspaceError>>;
-    flush(): Promise<void>;
-    dispose(): Promise<void>;
+    deleteTurnSubtree(sessionId: UUID, turnId: UUID, version: number, newHead: TurnRef | null): Promise<Result<void, WorkspaceError>>;
+    copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
+    resolveSession(workspace: Workspace, sessionId: UUID, transcript?: Turn[]): Promise<Result<EffectiveSession, WorkspaceError>>;
 }
 
-declare function workspaceReducer(state: IndexState, command: Command): Result<DeepPartial<IndexState>, WorkspaceError>;
+declare function workspaceReducer({ index: state }: Workspace, command: Command): Result<DeepPartial<Workspace>, WorkspaceError>;
 
 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(indexState: IndexState, command: Command): Result<DeepPartial<IndexState>, WorkspaceError>;
-    dispatch(indexState: IndexState, command: Command): Promise<Result<DeepPartial<IndexState>, WorkspaceError>>;
-    resolveSession(indexState: IndexState, sessionId: UUID): Promise<Result<EffectiveSession, WorkspaceError>>;
-    activateSession(indexState: IndexState, sessionId: UUID): Promise<Result<void, WorkspaceError>>;
-    deactivateSession(indexState?: IndexState): Promise<void>;
-    flush(): Promise<void>;
-    dispose(): Promise<void>;
+    reduce(workspace: Workspace, command: Command): Result<DeepPartial<Workspace>, WorkspaceError>;
+    dispatch(workspace: Workspace, command: Command): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    resolveSession(workspace: Workspace, sessionId: UUID): Promise<Result<EffectiveSession, WorkspaceError>>;
     private handleContentSideEffects;
 }
 
@@ -873,27 +1210,202 @@ interface Summarizer {
     }>;
 }
 
+interface ContextRankingInput {
+    entries: Context[];
+    recentMessages: string[];
+    config: ContextRelevanceConfig;
+}
+interface ContextRetriever {
+    rank(input: ContextRankingInput): Context[];
+}
+interface PlanningInput {
+    systemInstructions?: string;
+    persona: string;
+    preferences: Preference[];
+    context: Context[];
+    transcript: Turn[];
+    budget?: TokenBudget;
+}
+interface PlanningOutput {
+    preferences: Preference[];
+    context: Context[];
+    transcript: Turn[];
+    truncated: {
+        preferences: number;
+        interactions: number;
+        context: number;
+    };
+    breakdown: Record<string, number>;
+    totalUsed: number;
+    lastRoleBeforeTruncation: string | null;
+}
+interface TokenPlanner {
+    plan(input: PlanningInput): PlanningOutput;
+}
+interface AssemblyInput {
+    session: EffectiveSession;
+    plan: PlanningOutput;
+    resolvedBlobs: Map<SHA256, ResolvedBlob>;
+    summaryBlockText: string | null;
+    warnings: string[];
+    conflicts: PreferenceConflict[];
+    budgetTotal: number;
+}
+declare class PromptAssembler {
+    assemble(input: AssemblyInput): Prompt;
+    private buildReferentialBlock;
+    private resolveTurnBlocks;
+}
 declare class PromptBuilder {
-    private readonly summarizer?;
-    constructor(summarizer?: Summarizer);
-    /**
-     * Build a provider-agnostic BuildResult from an EffectiveSession.
-     *
-     * IMPORTANT: blobs in the session's turns must be pre-resolved before
-     * calling build(). Pass the resolved map via options.resolvedBlobs.
-     * Any blob whose SHA-256 is not in resolvedBlobs will be omitted from
-     * the output with a warning.
-     *
-     * @param effectiveSession  The resolved session (from ContentStore.resolveSession).
-     * @param options.resolvedBlobs  Map of sha256 → ResolvedBlob from BlobStore.resolveRefs().
-     * @param options.tokenBudget    Optional token budget for truncation.
-     * @param options.relevanceConfig Optional context ranking config.
-     */
-    build(effectiveSession: EffectiveSession, options?: {
-        resolvedBlobs?: Map<SHA256, ResolvedBlob>;
+    private retriever;
+    private planner;
+    private assembler;
+    private summarizer?;
+    private blobResolver;
+    constructor(dependencies: {
+        blobResolver: BlobStore['resolveRefs'];
+        retriever?: ContextRetriever;
+        planner?: TokenPlanner;
+        assembler?: PromptAssembler;
+        summarizer?: Summarizer;
+    });
+    build(session: EffectiveSession, options?: {
         tokenBudget?: TokenBudget;
         relevanceConfig?: ContextRelevanceConfig;
+        providerId?: string;
     }): Promise<Prompt>;
+    private collectUsedBlobRefs;
+    private deduplicateBlobRefs;
+    private extractRecentUserQueries;
+    private resolvePreferenceConflicts;
+}
+
+declare class Session {
+    /** The session ID this object manages. */
+    readonly sessionId: UUID;
+    /**
+     * The turn DAG. Keys are turn IDs. Mutated in-place on every write.
+     * Callers read this directly for rendering — no copy is made.
+     */
+    readonly nodes: Record<UUID, TurnNode>;
+    /**
+     * Current head of the active branch. Mirrors what is in
+     * workspace.index.sessions[sessionId].head after each patch is applied.
+     * Session keeps its own copy so reads don't require workspace.
+     */
+    private head;
+    /** Turns not yet flushed to storage. */
+    private readonly dirtyBuffer;
+    private flushTimer;
+    private flushChain;
+    private readonly flushConfig;
+    private readonly tree;
+    private readonly contentStore;
+    constructor(sessionId: UUID, nodes: Record<UUID, TurnNode>, head: TurnRef | null, tree: TurnTree, contentStore: ContentStore, flushConfig?: FlushConfig);
+    activeChain(): TurnNode[];
+    siblings(turnId: UUID): TurnNode[];
+    branchInfo(turnId: UUID): BranchInfo;
+    addTurn(workspace: Workspace, turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    editTurn(workspace: Workspace, turnId: UUID, newBlocks: ContentBlock[], roleSnapshot?: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    branchFrom(workspace: Workspace, newTurn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    deleteTurn(workspace: Workspace, turnId: UUID, version: number, newHead: TurnRef | null): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    switchVersionLeft(_: Workspace, turnId: UUID): Result<DeepPartial<Workspace>, WorkspaceError>;
+    switchVersionRight(_: Workspace, turnId: UUID): Result<DeepPartial<Workspace>, WorkspaceError>;
+    private switchVersion;
+    resolve(workspace: Workspace): Promise<Result<EffectiveSession, WorkspaceError>>;
+    flush(): Promise<void>;
+    dispose(): Promise<void>;
+    private findSubtreeTipForVersion;
+    private collectSubtreeIds;
+    private upsertNode;
+    private scheduleFlush;
+    private cancelFlushTimer;
+    private doFlush;
+}
+declare function buildTurnNode(turn: Turn, children?: UUID[]): TurnNode;
+
+interface SessionManagerConfig {
+    flush?: Partial<FlushConfig>;
+}
+interface OpenResult {
+    session: Session;
+    patch: DeepPartial<Workspace>;
+}
+declare class SessionManager {
+    private readonly workspaceManager;
+    private readonly contentStore;
+    private readonly flushConfig;
+    constructor(workspaceManager: WorkspaceManager, contentStore: ContentStore, config?: SessionManagerConfig);
+    open(workspace: Workspace, sessionId: UUID): Promise<Result<OpenResult, WorkspaceError>>;
+    close(session: Session): Promise<void>;
+    get workspace(): WorkspaceManager;
+}
+
+/**
+ * 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 AddInteraction, type AddPreference, type AddRole, type AddSessionTopics, type AddTurn, type BaseCommand, type BlobMediaType, type BlobRecord, type BlobRef, type BlobStorage, BlobStore, type BlobStoreConfig, type BlobSummary, type BranchTurn, type BuiltTurn, type CacheConfig, type Command, type ContentBlock, type ContentStorage, ContentStore, type ContentStoreConfig, type Context, 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 IndexState, type IndexedDBBlobConfig, IndexedDBBlobStorage, type IndexedDBConfig, IndexedDBStorage, type Indexes, MemoryBlobStorage, MemoryStorage, 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 SHA256, type Session, type SessionMeta, type SessionSummary, type Settings, type SwitchRole, type TextBlock, type ThinkingBlock, type Timestamp, type TokenBudget, type ToolResultBlock, type ToolUseBlock, type TopicIndex, type TranscriptWindow, type Turn, type TurnRole, type URI, type UUID, type UpdateContext, type UpdatePreference, type UpdateRole, type Workspace, type WorkspaceBundle, type WorkspaceError, WorkspaceManager, computeSHA256, del, err, merge, ok, workspaceReducer };
+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 };