@asaidimu/utils-workspace 4.0.3 → 5.0.0

package/index.d.ts

@@ -1,2060 +1,2278 @@
-import { QueryFilter, PaginationOptions } from '@asaidimu/query';
 import { IndexDefinition, SchemaDefinition, SchemaChange, DataTransform } from '@asaidimu/anansi';
-import { EventBus } from '@asaidimu/events';
-import * as _google_genai from '@google/genai';
-import { GenerateContentParameters, GenerateContentResponse, GoogleGenAI } from '@google/genai';
+import { QueryFilter, PaginationOptions } from '@asaidimu/query';
 
 /**
- * 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.
+ * 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.
  */
-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 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;
+}
 /**
- * core/types.ts
- * * This file contains the primary domain models, data structures, and command types
- * for the AI Workspace. It acts as the "Source of Truth" for all modules.
+ * 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.
  */
-
-/** RFC 4122 compliant Universally Unique Identifier. */
-type UUID = string;
-/** ISO-8601 formatted UTC timestamp string. */
-type Timestamp = string;
-/** Uniform Resource Identifier string. */
-type URI = string;
-/** Hexadecimal representation of a SHA-256 hash. */
-type SHA256 = string;
-/** Special marker used to denote a role with no specific instructions or identity. */
-declare const EMPTY_SYSTEM_ROLE = "__system__";
+type CursorCallback<T> = (value: T, key: string | number, cursor: any) => Promise<CursorCallbackResult<T>>;
 /**
- * A functional wrapper for operations that can fail.
- * Encourages explicit error handling over try/catch blocks.
+ * A generic representation of a key range, replacing the browser-specific IDBKeyRange.
  */
-type Result<T, E = WorkspaceError> = {
-    ok: true;
-    value: T;
-} | {
-    ok: false;
-    error: E;
-};
-/** Occurs when attempting to create a resource with a key that already exists. */
-type DuplicateKeyError = {
-    code: 'DUPLICATE_KEY';
-    resource: string;
-    key: string;
-};
-/** Occurs when a requested resource cannot be found by its unique identifier. */
-type NotFoundError = {
-    code: 'NOT_FOUND';
-    resource: string;
-    id: string;
-};
-/** Triggered when a command payload fails validation or is logically inconsistent. */
-type InvalidCommandError = {
-    code: 'INVALID_COMMAND';
-    reason: string;
-};
-/** Generic wrapper for unexpected infrastructure or downstream service failures. */
-type BackendError = {
-    code: 'BACKEND_ERROR';
-    reason: string;
-};
-/** Specific errors related to blob storage, retrieval, or corruption. */
-type BlobError = {
-    code: 'BLOB_ERROR';
-    reason: string;
-};
-/** Triggered when the current actor lacks sufficient privileges for a command. */
-type PermissionDeniedError = {
-    code: 'PERMISSION_DENIED';
-    command: Command;
-    reason: string;
-};
-/** Union of all possible error types within the Workspace domain. */
-type WorkspaceError = DuplicateKeyError | NotFoundError | InvalidCommandError | BackendError | PermissionDeniedError | BlobError;
-/** Global user preferences and defaults for the workspace. */
-interface Settings {
-    /** Default language code (e.g., 'en-US'). */
-    language: string;
-    /** The name of the role used when starting a new session. */
-    defaultRole?: string;
-    /** Global instructions appended to all system prompts. */
-    prompt?: string;
+interface StoreKeyRange {
+    lower?: any;
+    upper?: any;
+    lowerOpen?: boolean;
+    upperOpen?: boolean;
 }
-/** * Represents the project-level metadata.
- * Allows for extensible metadata fields via the generic Metadata type.
- */
-type Project<Metadata extends Record<string, any> = Record<string, any>> = Metadata & {
-    id: UUID;
-    name: string;
-};
-/** Supported mime-types for image assets. */
-type ImageMediaType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
-/** Supported mime-types for text-based or structured documents. */
-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';
-/** Union of all media types handled by the blob system. */
-type BlobMediaType = ImageMediaType | DocumentMediaType;
-/**
- * A lightweight reference to a blob.
- * Used in content blocks to avoid passing heavy metadata or binary data.
- */
-type BlobRef = Pick<BlobRecord, 'sha256' | 'mediaType' | 'sizeBytes' | 'filename' | 'previewUrl'>;
 /**
- * Represents a blob that has been fetched into memory.
- * Can be 'inline' (binary data present) or 'remote' (stored in an external provider).
+ * 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 ResolvedBlob = {
-    kind: 'inline';
-    sha256: SHA256;
-    mediaType: BlobMediaType;
-    data: Uint8Array;
+type BufferedOperation<T> = {
+    type: "add" | "put";
+    data: T | T[];
 } | {
-    kind: 'remote';
-    sha256: SHA256;
-    mediaType: BlobMediaType;
-    fileId: string;
-    providerId: string;
-    timestamp: Timestamp;
+    type: "delete";
+    data: string | number | (string | number)[];
 };
 /**
- * The authoritative registry entry for a file in the system.
- * Includes reference counting for garbage collection and remote mappings.
+ * 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 BlobRecord {
-    sha256: SHA256;
-    mediaType: BlobMediaType;
-    sizeBytes: number;
-    filename?: string;
-    previewUrl?: string;
-    /** Number of content blocks currently referencing this blob. */
-    refCount: number;
-    /** Map of provider IDs to their specific external file identifiers. */
-    remoteIds: Record<string, {
-        id: string;
-        timestamp: Timestamp;
-    }>;
-    createdAt: Timestamp;
-    lastUsedAt: Timestamp;
-}
-/** Standard text content within a turn. */
-interface TextBlock {
-    id: UUID;
-    type: 'text';
-    text: string;
-}
-/** An image asset within a turn, optionally containing the resolved binary data. */
-interface ImageBlock {
-    id: UUID;
-    type: 'image';
-    ref?: BlobRef;
-    blob?: ResolvedBlob;
-    altText?: string;
-}
-/** A document asset within a turn. */
-interface DocumentBlock {
-    id: UUID;
-    type: 'document';
-    ref?: BlobRef;
-    blob?: ResolvedBlob;
-    title?: string;
-}
-/** Represents a structured proposal to create or modify a task. */
-interface TaskProposalBlock {
-    id?: UUID;
-    ref?: string;
-    type: 'task:proposal';
-    title: string;
-    steps: {
-        ref?: string;
-        text: string;
-        status: 'todo' | 'done';
-    }[];
-    action: 'create' | 'update' | 'complete';
-}
-/** Captured request from the AI to execute a specific tool. */
-interface ToolUseBlock {
-    id: UUID;
-    type: 'tool:use';
-    name: string;
-    input: Record<string, unknown>;
-}
-/** The resulting output (or error) from a tool execution. */
-interface ToolResultBlock {
-    id: UUID;
-    type: 'tool:result';
-    /** References the ToolUseBlock ID that generated this result. */
-    useId: UUID;
-    content: string | Record<string, unknown>;
-    isError?: boolean;
-}
-/** Internal "Chain of Thought" or reasoning generated by the model. */
-interface ThinkingBlock {
-    id: UUID;
-    type: 'thinking';
-    thinking: string;
-}
-/** A condensed summary of previous conversation history. */
-interface SummaryBlock {
-    id: UUID;
-    type: 'summary';
-    text: string;
-}
-/** Notates that the session has switched from one Role persona to another. */
-interface RoleTransitionBlock {
-    id: UUID;
-    type: 'role:transition';
-    previousRole: string | null;
-    newRole: string;
-}
-/** Union of all possible content types that can exist within a conversation Turn. */
-type ContentBlock = TextBlock | ImageBlock | DocumentBlock | ToolUseBlock | ToolResultBlock | SummaryBlock | RoleTransitionBlock | ThinkingBlock | TaskProposalBlock;
-/** Definition of a tool available to the AI. */
-interface ToolSummary {
-    name: string;
-    description: string;
-    /** JSON Schema defining the required input arguments. */
-    parameters: {
-        type: 'object';
-        properties: Record<string, any>;
-        required: string[];
-    };
-    /** Semantic tags used to help the model find relevant tools. */
-    topics: string[];
-}
-/** An instance of a tool being called with specific arguments. */
-interface ToolCall {
-    id: UUID;
-    tool: UUID;
-    arguments: Record<string, any>;
+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>;
 }
-/** A request for authorization before executing a command or tool. */
-type AuthRequest = {
-    type: 'command';
-    payload: Command;
-} | {
-    type: 'tool';
-    payload: ToolCall;
-};
-/** Identifies whether a turn originated from the user, the AI, a tool, or the system. */
-type TurnActor = 'user' | 'assistant' | 'tool' | 'system';
-/** * The flat storage format for a conversation turn.
- * Supports versioning and parent-pointers for branching conversation trees (DAG).
- */
-interface Turn {
-    id: UUID;
-    /** Incrementing number for edits to the same turn ID. */
-    version: number;
-    actor: TurnActor;
-    blocks: ContentBlock[];
-    timestamp: Timestamp;
-    /** Name of the role active at the time of this turn. */
-    role?: string;
-    /** Link to the preceding turn in the conversation tree. */
-    parent: {
-        id: UUID;
-        version: number;
-    } | null;
-    /** Used for fast filtering within a specific chat session. */
-    sessionId?: UUID;
+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>>;
+    /**
+     * Updates all documents matching the query with the provided partial data.
+     * Returns the number of documents updated.
+     */
+    update: (query: QueryFilter<T>, data: Partial<T>, tx?: TransactionContext) => Promise<number>;
+    /**
+     * Deletes all documents matching the query.
+     * Returns the number of documents deleted.
+     */
+    delete: (query: QueryFilter<T>, tx?: TransactionContext) => Promise<number>;
+    /**
+     * 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;
 }
 /**
- * An in-memory representation of a turn, including all its versions and children.
- * This is used for rendering threaded/branching conversations.
+ * Event payload for Collection events.
  */
-interface TurnNode {
-    id: UUID;
-    /** Map of version numbers to the Turn data. */
-    versions: Record<number, Turn>;
-    activeVersion: number;
-    role: TurnActor;
-    blocks: ContentBlock[];
-    timestamp: Timestamp;
-    roleSnapshot?: string;
-    parent: {
-        id: UUID;
-        version: number;
-    } | null;
-    /** Map of version numbers to an array of child turn IDs. */
-    children: Record<number, UUID[]>;
-}
-/** UI helper for navigating between different versions of a turn (e.g. "2 of 5"). */
-interface BranchInfo {
-    versions: number[];
-    currentIndex: number;
-    total: number;
-    hasPrev: boolean;
-    hasNext: boolean;
-}
-/** A system persona containing specific instructions and associated preferences. */
-interface Role {
-    /** Unique identifier name (e.g. "software-architect"). */
-    name: string;
-    /** Human-readable display label. */
-    label: string;
-    description?: string;
-    /** The core instructions (system prompt) for this persona. */
-    persona: string;
-    /** Array of Preference IDs associated with this role. */
-    preferences: UUID[];
-}
-/** A specific user preference or "memory" that informs model behavior. */
-interface Preference {
-    id: UUID;
-    content: string;
-    /** Topics used for retrieval-augmented generation (RAG). */
-    topics: string[];
-    timestamp: Timestamp;
-}
-/** Discriminated union of types that can be injected into the AI context. */
-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;
+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;
 };
-/** A contextual item (file, snippet, or data) attached to a session or prompt. */
-interface Context {
-    /** Unique lookup key. */
-    key: string;
-    topics: string[];
-    content: ContextContent;
-    timestamp: Timestamp;
-    metadata?: Record<string, any>;
+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>;
 }
-/** Metadata for a conversation session, stored in the persistent collection. */
-interface SessionMeta {
-    id: UUID;
-    label: string;
-    /** The active Role name for this session. */
-    role: string;
-    topics: string[];
-    preferences: UUID[];
+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 DocumentMetadata = {
+    $id?: string;
+    $created?: string | Date;
+    $updated?: string | Date;
+    $version?: number;
+};
+type Document<T> = {
+    readonly [K in keyof T]: T[K];
+} & DocumentMetadata & {
+    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;
+    $metadata(): DocumentMetadata;
+};
+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: {
-        created?: Timestamp;
-        updated?: Timestamp;
+        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;
     };
-    /** Tracks how many turns have been persisted to the database. */
-    flushedTurnCount: number;
-    /** The current leaf-node of the conversation. */
-    head: {
-        id: UUID;
-        version: number;
-    } | null;
-    /** Optional link to a specific Task being worked on. */
-    task: UUID | null;
-}
-type TaskStatus = 'todo' | 'active' | 'done' | 'blocked' | 'defered';
-/** A single item within a Task's checklist. */
-interface TaskStep {
-    ref: string;
-    text: string;
-    completed?: Timestamp;
-}
-/** A high-level objective with nested steps, used for tracking AI progress. */
-interface Task {
-    id: UUID;
-    ref?: string;
-    title: string;
-    description?: string;
-    status: TaskStatus;
-    steps: TaskStep[];
-    topics: string[];
-    metadata?: Record<string, any>;
-    created: Timestamp;
-    updated: Timestamp;
-}
-interface RoleSummary {
-    name: string;
-    label: string;
-    description?: string;
-    preferences: number;
+};
+
+/**
+ * Interface defining the shape of the EventBus.
+ * @template TEventMap - A record mapping event names to their respective payload types.
+ */
+interface EventBus<TEventMap extends Record<string, any>> {
+    /**
+     * Subscribes to a specific event by name.
+     * @param eventName - The name of the event to subscribe to.
+     * @param callback - The function to call when the event is emitted.
+     * @returns A function to unsubscribe from the event.
+     */
+    subscribe: <TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void) => () => void;
+    /**
+     * Subscribes to an event and automatically unsubscribes after it fires once.
+     * @param eventName - The name of the event to subscribe to.
+     * @param callback - The function to call when the event is emitted.
+     * @returns A function to cancel the one-shot subscription before it fires.
+     */
+    once: <TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void) => () => void;
+    /**
+     * Emits an event with a payload to all subscribed listeners.
+     * @param event - An object containing the event name and payload.
+     */
+    emit: <TEventName extends keyof TEventMap>(event: {
+        name: TEventName;
+        payload: TEventMap[TEventName];
+    }) => void;
+    /**
+     * Retrieves metrics about event bus usage.
+     * @returns An object containing various metrics.
+     */
+    metrics: () => EventMetrics;
+    /**
+     * Clears all subscriptions and resets metrics.
+     * After calling clear(), the bus is fully reset and can be reused —
+     * cross-tab communication is re-established if it was previously enabled.
+     */
+    clear: () => void;
 }
-interface PreferenceSummary {
-    id: UUID;
-    topics: string[];
-    timestamp: Timestamp;
-    snippet?: string;
+/**
+ * Interface defining the metrics tracked by the EventBus.
+ */
+interface EventMetrics {
+    /** Total number of events emitted (both sync and deferred paths). */
+    totalEvents: number;
+    /** Number of active subscriptions across all event names. */
+    activeSubscriptions: number;
+    /** Map of event names to their emission counts. */
+    eventCounts: Map<string, number>;
+    /** Average duration of event dispatch in milliseconds. */
+    averageEmitDuration: number;
 }
-interface ContextSummary {
+
+/**
+ * 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;
+
+/**
+ * This file contains the primary domain models, data structures, and command types
+ * for the AI Workspace. It acts as the "Source of Truth" for all modules.
+ */
+
+/** RFC 4122 compliant Universally Unique Identifier. */
+type UUID = string;
+/** ISO-8601 formatted UTC timestamp string. */
+type Timestamp = string;
+/** Uniform Resource Identifier string. */
+type URI = string;
+/** Hexadecimal representation of a SHA-256 hash. */
+type SHA256 = string;
+/** Special marker used to denote a role with no specific instructions or identity. */
+declare const EMPTY_SYSTEM_ROLE = "__system__";
+/**
+ * A functional wrapper for operations that can fail.
+ * Encourages explicit error handling over try/catch blocks.
+ * @template T - The type of the value returned on success.
+ * @template E - The type of the error returned on failure.
+ */
+type Result<T, E = WorkspaceError> = {
+    /** Indicates the operation was successful. */
+    ok: true;
+    /** The resulting value of the successful operation. */
+    value: T;
+} | {
+    /** Indicates the operation failed. */
+    ok: false;
+    /** The error details explaining the failure. */
+    error: E;
+};
+/** Occurs when attempting to create a resource with a key that already exists. */
+type DuplicateKeyError = {
+    /** Error discriminator code. */
+    code: "DUPLICATE_KEY";
+    /** The type of resource that caused the collision (e.g., 'role', 'session'). */
+    resource: string;
+    /** The specific key that duplicated an existing entry. */
     key: string;
-    topics: string[];
-    timestamp: Timestamp;
-    mime?: string;
-    size?: number;
-    preview?: string;
-    source?: string;
-    metadata?: Record<string, any>;
+};
+/** Occurs when a requested resource cannot be found by its unique identifier. */
+type NotFoundError = {
+    /** Error discriminator code. */
+    code: "NOT_FOUND";
+    /** The type of resource that was requested. */
+    resource: string;
+    /** The ID that yielded no results. */
+    id: string;
+};
+/** Triggered when a command payload fails validation or is logically inconsistent. */
+type InvalidCommandError = {
+    /** Error discriminator code. */
+    code: "INVALID_COMMAND";
+    /** Detailed explanation of why the command was rejected. */
+    reason: string;
+};
+/** Generic wrapper for unexpected infrastructure or downstream service failures. */
+type BackendError = {
+    /** Error discriminator code. */
+    code: "BACKEND_ERROR";
+    /** Description of the underlying system failure. */
+    reason: string;
+};
+/** Specific errors related to blob storage, retrieval, or corruption. */
+type BlobError = {
+    /** Error discriminator code. */
+    code: "BLOB_ERROR";
+    /** Description of the blob operation failure. */
+    reason: string;
+};
+/** Triggered when the current actor lacks sufficient privileges for a command. */
+type PermissionDeniedError = {
+    /** Error discriminator code. */
+    code: "PERMISSION_DENIED";
+    /** The command that was attempted and subsequently blocked. */
+    command: BaseCommand;
+    /** Explanation of the missing permissions or blocked action. */
+    reason: string;
+};
+/** Union of all possible error types within the Workspace domain. */
+type WorkspaceError = DuplicateKeyError | NotFoundError | InvalidCommandError | BackendError | PermissionDeniedError | BlobError;
+/** Global user preferences and defaults for the workspace. */
+interface Settings {
+    /** Default language code used for generic formatting (e.g., 'en-US'). */
+    language: string;
+    /** The ID or name of the role used when a new session is instantiated without one. */
+    defaultRole?: string;
+    /** Global system instructions appended to the LLM context across all sessions. */
+    prompt?: string;
 }
-interface TaskSummary {
+/**
+ * Represents the project-level metadata container.
+ * Allows for extensible metadata fields via the generic Metadata type.
+ * @template Metadata - Custom schema for additional project fields.
+ */
+type Project<Metadata extends Record<string, any> = Record<string, any>> = Metadata & {
+    /** Unique identifier for the project. */
     id: UUID;
-    ref?: string;
-    description: string;
-    title: string;
-    status: TaskStatus;
-    steps: {
-        completed: number;
-        total: number;
-    };
-    topics: string[];
-}
-/** Maps topics to the various entities that reference them. */
-interface TopicIndex {
-    topic: string;
-    contextKeys: string[];
-    preferences: UUID[];
-    tasks: UUID[];
-    metadata?: {
-        created?: Timestamp;
-        updated?: Timestamp;
-        entries?: number;
-    };
-}
-/** The complete in-memory read-model of the Workspace state. */
-interface Index {
-    roles: Record<string, RoleSummary>;
-    preferences: Record<UUID, PreferenceSummary>;
-    context: Record<string, ContextSummary>;
-    sessions: Record<UUID, SessionMeta>;
-    tasks: Record<UUID, TaskSummary>;
-    topics: Record<string, TopicIndex>;
-    blobs: Record<SHA256, BlobRecord>;
-    tools: Record<string, ToolSummary>;
-}
-/** The root container for a user's workspace. */
-interface Workspace<ProjectMetadata extends Record<string, any> = Record<string, any>> {
-    id: UUID;
-    settings: Settings;
-    project: Project<ProjectMetadata>;
-    index: Index;
-}
-/** * Format used for exporting/importing a complete workspace state,
- * including all historical turns and binary records.
+    /** Human-readable display name for the project. */
+    name: string;
+};
+/** Supported mime-types for image assets. */
+type ImageMediaType = "image/jpeg" | "image/png" | "image/gif" | "image/webp";
+/** Supported mime-types for text-based or structured documents. */
+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";
+/** Union of all media types handled by the blob system. */
+type BlobMediaType = ImageMediaType | DocumentMediaType;
+/**
+ * A lightweight reference to a blob.
+ * Used in content blocks to avoid passing heavy metadata or binary data across boundaries.
  */
-interface WorkspaceBundle {
-    format: 'aiworkspace/4.0';
-    workspace: Workspace;
-    roles: Record<string, Role>;
-    preferences: Record<UUID, Preference>;
-    context: Record<string, Context>;
-    sessions: Record<UUID, SessionMeta & {
-        turns: Turn[];
+type BlobRef = Pick<BlobRecord, "sha256" | "mediaType" | "sizeBytes" | "filename" | "previewUrl">;
+/**
+ * Represents a blob that has been fetched into memory.
+ * Can be 'inline' (binary data present) or 'remote' (stored in an external provider).
+ */
+type ResolvedBlob = {
+    /** Indicates the blob data is available in the local memory space. */
+    kind: "inline";
+    /** The unique content hash of the blob. */
+    sha256: SHA256;
+    /** The registered mime-type of the data. */
+    mediaType: BlobMediaType;
+    /** The raw binary representation of the file. */
+    data: Uint8Array;
+} | {
+    /** Indicates the blob exists on an external provider and must be referenced by ID. */
+    kind: "remote";
+    /** The unique content hash of the blob. */
+    sha256: SHA256;
+    /** The registered mime-type of the data. */
+    mediaType: BlobMediaType;
+    /** The external provider's unique identifier for this file. */
+    fileId: string;
+    /** The identifier of the external provider (e.g., 'openai', 'gemini'). */
+    providerId: string;
+    /** The UTC timestamp when the file was registered with the remote provider. */
+    timestamp: Timestamp;
+};
+/**
+ * The authoritative registry entry for a file in the system.
+ * Includes reference counting for garbage collection and remote mappings.
+ */
+interface BlobRecord {
+    /** The unique SHA-256 hash representing the blob's binary content. */
+    sha256: SHA256;
+    /** The recognized MIME type of the blob data. */
+    mediaType: BlobMediaType;
+    /** The total size of the blob payload in bytes. */
+    sizeBytes: number;
+    /** The original or user-assigned filename, if available. */
+    filename?: string;
+    /** A secure, temporary URL for previewing the blob in a UI context, if applicable. */
+    previewUrl?: string;
+    /** Number of content blocks currently referencing this blob. Prevents premature garbage collection. */
+    refCount: number;
+    /** Map of external provider IDs to their specific remote file identifiers and upload timestamps. */
+    remoteIds: Record<string, {
+        /** The external provider's specific file ID. */
+        id: string;
+        /** The timestamp the mapping was created. */
+        timestamp: Timestamp;
     }>;
-    tasks: Record<UUID, Task>;
-    blobs: Record<SHA256, BlobRecord>;
+    /** The UTC timestamp when this blob was first registered in the workspace. */
+    createdAt: Timestamp;
+    /** The UTC timestamp of the most recent interaction or reference to this blob. */
+    lastUsedAt: Timestamp;
 }
-/** A fully hydrated view of a session, including resolved objects for the prompt builder. */
-interface EffectiveSession {
-    session: SessionMeta;
-    role: Role;
-    preferences: Preference[];
-    context: Context[];
-    transcript: Turn[];
-    task: Task | null;
-    instructions?: string;
+/**
+ * Base interface for all content blocks inside a turn.
+ * @template BlockType - String literal restricting the block type.
+ */
+interface BaseContentBlock<BlockType extends string> {
+    /** Unique identifier for the specific content block instance. */
+    id: UUID;
+    /** Discriminator used to determine the shape and rendering of the block. */
+    type: BlockType;
+    /** Extensible key-value store for block-specific properties. */
+    [key: string]: any;
 }
-interface BaseCommand {
-    /** Discriminator for the command type. */
-    type: string;
-    timestamp: Timestamp;
-    /** The ID of the user or system component that initiated the command. */
-    actor?: string;
-    description?: string;
-    synthetic?: boolean;
+/** Standard text content within a turn. */
+interface TextBlock extends BaseContentBlock<"text"> {
+    /** The raw markdown or plain text content. */
+    text: string;
 }
-interface CreateWorkspace extends BaseCommand {
-    type: 'workspace:create';
-    payload: {
-        id: UUID;
-        settings: Settings;
-        project: Project;
-    };
+/** An image asset within a turn, optionally containing the resolved binary data. */
+interface ImageBlock extends BaseContentBlock<"image"> {
+    /** Lightweight pointer to the blob record. */
+    ref?: BlobRef;
+    /** Fully resolved blob containing actual data or remote pointers. */
+    blob?: ResolvedBlob;
+    /** Accessible description of the image content. */
+    altText?: string;
 }
-interface AddRole extends BaseCommand {
-    type: 'role:add';
-    payload: Role;
+/** A document asset within a turn. */
+interface DocumentBlock extends BaseContentBlock<"document"> {
+    /** Lightweight pointer to the blob record. */
+    ref?: BlobRef;
+    /** Fully resolved blob containing actual document data or remote pointers. */
+    blob?: ResolvedBlob;
+    /** Human-readable title or filename of the document. */
+    title?: string;
 }
-interface UpdateRole extends BaseCommand {
-    type: 'role:update';
-    payload: Partial<Role> & {
-        name: string;
-    };
+/** Captured request from the AI to execute a specific tool. */
+interface ToolUseBlock extends BaseContentBlock<"tool:use"> {
+    /** The exact registered name of the tool to be executed. */
+    name: string;
+    /** The parameter arguments provided by the model for the tool execution. */
+    input: Record<string, unknown>;
 }
-interface DeleteRole extends BaseCommand {
-    type: 'role:delete';
-    payload: {
-        name: string;
-    };
+/** The resulting output (or error) from a tool execution. */
+interface ToolResultBlock extends BaseContentBlock<"tool:result"> {
+    /** The UUID of the original ToolUseBlock that triggered this execution. */
+    useId: UUID;
+    /** The serialized output of the tool, or a structured JSON response. */
+    content: string | Record<string, unknown>;
+    /** Flag indicating whether the tool execution resulted in an error state. */
+    isError?: boolean;
 }
-interface AddPreference extends BaseCommand {
-    type: 'preference:add';
-    payload: Preference;
+/** Internal "Chain of Thought" or reasoning generated by the model. */
+interface ThinkingBlock extends BaseContentBlock<"thinking"> {
+    /** The internal reasoning text produced by the model before the final response. */
+    thinking: string;
 }
-interface UpdatePreference extends BaseCommand {
-    type: 'preference:update';
-    payload: Partial<Preference> & {
-        id: UUID;
+/** A condensed summary of previous conversation history. */
+interface SummaryBlock extends BaseContentBlock<"summary"> {
+    /** The distilled summary text replacing older conversation turns. */
+    text: string;
+}
+/** Notates that the session has switched from one Role persona to another. */
+interface RoleTransitionBlock extends BaseContentBlock<"role:transition"> {
+    /** The name of the role the session is leaving (undefined if it was a system default). */
+    previousRole?: string;
+    /** The name of the new role the session is adopting. */
+    newRole: string;
+}
+/** Union of all possible content types that can exist within a conversation Turn. */
+type ContentBlock = TextBlock | ImageBlock | DocumentBlock | ToolUseBlock | ToolResultBlock | ThinkingBlock | SummaryBlock | RoleTransitionBlock;
+/** Definition of a tool available to the AI. */
+interface ToolSummary {
+    /** The unique, system-level name of the tool (e.g., 'web_search'). */
+    name: string;
+    /** Human-readable explanation of what the tool does, exposed to the AI model. */
+    description: string;
+    /** JSON Schema defining the required input arguments and their types. */
+    parameters: {
+        /** Root type of the parameter schema, usually 'object'. */
+        type: "object";
+        /** Map of property names to their respective sub-schemas. */
+        properties: Record<string, any>;
+        /** Array of property names that must be provided to execute the tool. */
+        required: string[];
     };
+    /** Semantic tags used to help the model dynamically find relevant tools via RAG. */
+    topics: string[];
 }
-interface DeletePreference extends BaseCommand {
-    type: 'preference:delete';
-    payload: {
+/** An instance of a tool being called with specific arguments. */
+interface ToolCall {
+    /** The unique execution identifier for this specific call instance. */
+    id: UUID;
+    /** The UUID or string identifier of the tool being requested. */
+    tool: UUID;
+    /** The fully parsed arguments mapped to the tool's required parameters. */
+    arguments: Record<string, any>;
+}
+/** A request for authorization before executing a command or tool. */
+type AuthRequest = {
+    /** Discriminator indicating a state mutation authorization request. */
+    type: "command";
+    /** The specific command attempting to execute. */
+    payload: BaseCommand;
+} | {
+    /** Discriminator indicating an external tool execution authorization request. */
+    type: "tool";
+    /** The specific tool call payload attempting to execute. */
+    payload: ToolCall;
+};
+/** Identifies whether a turn originated from the user, the AI, a tool, or the system. */
+type SystemActor = "user" | "assistant" | "tool" | "system";
+/**
+ * The flat storage format for a conversation turn.
+ * Supports versioning and parent-pointers for branching conversation trees (DAG).
+ */
+interface Turn {
+    /** The unique identifier for this specific turn instance. */
+    id: UUID;
+    /** The UUID of the chat session this turn belongs to, used for fast filtering. */
+    session: UUID;
+    /** Incrementing number representing edits to the same turn ID. */
+    version: number;
+    /** The entity (user, model, system) that produced this turn's content. */
+    actor: SystemActor;
+    /** An ordered array of content blocks comprising the payload of this turn. */
+    blocks: BaseContentBlock<string>[];
+    /** The UTC timestamp when this turn was originally created or received. */
+    timestamp: Timestamp;
+    /** Name of the role (persona) active at the exact time this turn occurred. */
+    role?: string;
+    /** Link to the preceding turn in the conversation tree, defining the DAG graph. */
+    parent?: {
+        /** The ID of the parent turn. */
         id: UUID;
+        /** The specific version of the parent turn. */
+        version: number;
     };
+    /** Local model constraints applied explicitly at the time of this turn. */
+    constraints?: ModelConstraintMap;
 }
-interface CreateSession extends BaseCommand {
-    type: 'session:create';
-    payload: {
+/** Unique composite key used to lookup a specific turn version. */
+type TurnKey = Pick<Turn, "version" | "id" | "session">;
+/**
+ * An in-memory representation of a turn, including all its versions and children.
+ * This is used for rendering threaded/branching conversations in UI.
+ */
+interface TurnNode {
+    /** The unique root identifier for this turn across all its versions. */
+    id: UUID;
+    /** Map of version numbers to the specific Turn data payloads. */
+    versions: Record<number, Turn>;
+    /** The version integer currently displayed or active in the primary chat view. */
+    activeVersion: number;
+    /** The entity that produced this turn's root concept. */
+    actor: SystemActor;
+    /** The content blocks of the *active* version for quick rendering. */
+    blocks: BaseContentBlock<string>[];
+    /** The UTC timestamp of the original turn creation. */
+    timestamp: Timestamp;
+    /** The role name active when this node was created. */
+    roleSnapshot?: string;
+    /** Reference to the preceding turn in the conversation DAG. */
+    parent?: {
+        /** Parent turn ID. */
         id: UUID;
-        label: string;
-        role: string;
-        topics: string[];
-        preferences?: UUID[];
+        /** Parent turn version. */
+        version: number;
     };
+    /** Map of version numbers to arrays of child turn IDs spawned from that specific version. */
+    children: Record<number, UUID[]>;
 }
-interface AddContext extends BaseCommand {
-    type: 'context:add';
-    payload: Context;
+/** UI helper for navigating between different versions of a turn (e.g. "2 of 5"). */
+interface BranchInfo {
+    /** Array of all available version numbers for a turn. */
+    versions: number[];
+    /** The array index currently being viewed. */
+    currentIndex: number;
+    /** The total count of available versions. */
+    total: number;
+    /** Indicates if an older version exists to navigate back to. */
+    hasPrev: boolean;
+    /** Indicates if a newer version exists to navigate forward to. */
+    hasNext: boolean;
 }
-interface UpdateContext extends BaseCommand {
-    type: 'context:update';
-    payload: Partial<Context> & {
-        key: string;
+/** Unique string identifier for a model (e.g., 'gemini-2.0-flash'). */
+type ModelName = string;
+/** Execution constraints applied to a specific model. */
+interface ModelConstraint {
+    /** Sampling temperature. 0.0 = deterministic, higher = more creative. */
+    temperature?: number;
+    /** Limits and stop boundaries for token generation. */
+    tokens: {
+        /** Maximum output tokens for this request. Overrides adapter defaults. */
+        max?: number;
+        /** Stop sequences — generation halts immediately when any of these are produced. */
+        stops?: string[];
+        /** Thinking/reasoning budget in tokens. (For supported models only). */
+        thought?: number;
     };
 }
-interface DeleteContext extends BaseCommand {
-    type: 'context:delete';
-    payload: {
-        key: string;
-    };
+/** Map of model names to their explicit, active constraints. */
+type ModelConstraintMap = Record<ModelName, ModelConstraint>;
+/** A system persona containing specific instructions and associated preferences. */
+interface Role {
+    /** Unique identifier name used system-wide (e.g. "software-architect"). */
+    name: string;
+    /** Human-readable display label shown in the UI. */
+    label: string;
+    /** Optional human-readable description of what this persona is intended for. */
+    description?: string;
+    /** The core instructions (system prompt base) establishing this persona's behavior. */
+    persona: string;
+    /** Array of Preference UUIDs explicitly bound to this role. */
+    preferences: UUID[];
+    /** Array of semantic Topics associated with this role to guide RAG retrieval. */
+    topics: string[];
+    /** Model constraints natively attached at the role level. */
+    constraints?: ModelConstraintMap;
 }
-type TaskRef = UUID | string;
-interface AddTask extends BaseCommand {
-    type: 'task:add';
-    payload: Task;
+/** A specific user preference or "memory" that informs model behavior. */
+interface Preference {
+    /** Unique identifier for the preference entry. */
+    id: UUID;
+    /** The actual text content representing the instruction or fact to remember. */
+    content: string;
+    /** Topics used for semantic alignment and retrieval-augmented generation (RAG). */
+    topics: string[];
+    /** UTC timestamp of when this preference was established or last updated. */
+    timestamp: Timestamp;
 }
-interface UpdateTask extends BaseCommand {
-    type: 'task:update';
-    payload: Partial<Task> & ({
-        id: UUID;
-    } | {
-        ref: string;
-    });
+/** Discriminated union of types that can be injected into the AI context. */
+type ContextContent = {
+    /** Denotes raw, unstructured text. */
+    kind: "text";
+    /** The text payload to inject. */
+    value: string;
+} | {
+    /** Denotes structured JSON data. */
+    kind: "json";
+    /** The JSON payload. */
+    value: unknown;
+} | {
+    /** Denotes a reference to a registered blob in the workspace store. */
+    kind: "blob";
+    /** The hash linking to the full blob record. */
+    sha256: SHA256;
+    /** The mime-type of the blob. */
+    mediaType: BlobMediaType;
+    /** File size in bytes. */
+    sizeBytes: number;
+    /** Human-readable filename. */
+    filename?: string;
+} | {
+    /** Denotes data living at an external HTTP URI. */
+    kind: "remote";
+    /** The fully qualified URI to the external resource. */
+    uri: URI;
+    /** Optional hint for the expected mime-type at the remote destination. */
+    mediaType?: BlobMediaType;
+};
+/** A contextual item (file, snippet, or data) attached to a session or prompt. */
+interface Context {
+    /** Unique lookup key for this context entry. */
+    key: string;
+    /** Topics linking this context to relevant sessions or roles. */
+    topics: string[];
+    /** The actual payload of the context block. */
+    content: ContextContent;
+    /** UTC timestamp of when the context was added. */
+    timestamp: Timestamp;
+    /** Extensible key-value store for application-specific contextual metadata. */
+    metadata?: Record<string, any>;
 }
-interface DeleteTask extends BaseCommand {
-    type: 'task:delete';
-    payload: {
-        id: UUID;
+/** Metadata for a conversation session, stored in the persistent collection. */
+interface SessionMetadata {
+    /** Unique identifier for the chat session. */
+    id: UUID;
+    /** Human-readable title or label for the session. */
+    label: string;
+    /** The active Role (persona) name guiding this specific session. */
+    role: string;
+    /** Semantic topics governing what context and tools are active for this session. */
+    topics: string[];
+    /** Array of UUIDs pointing to explicitly active preferences for this session. */
+    preferences: UUID[];
+    /** Timestamps detailing the session lifecycle. */
+    metadata: {
+        /** UTC timestamp of session creation. */
+        created?: Timestamp;
+        /** UTC timestamp of the last activity within the session. */
+        updated?: Timestamp;
     };
-}
-/** Updates an existing turn record in storage. */
-interface SaveTurn extends BaseCommand {
-    type: 'turn:save';
-    payload: {
-        sessionId: UUID;
-        turn: Turn;
+    /** The current chronological leaf-node of the conversation DAG. */
+    head?: {
+        /** The ID of the most recent turn. */
+        id: UUID;
+        /** The active version of the most recent turn. */
+        version: number;
     };
+    /** Overriding execution constraints active at the session level. */
+    constraints?: ModelConstraintMap;
 }
-/** Appends a new turn to a session. */
-interface AddTurn extends BaseCommand {
-    type: 'turn:add';
-    payload: {
-        sessionId: UUID;
-        turn: Turn;
-    };
+/** In-memory summary of a Role. */
+interface RoleSummary {
+    /** The unique identifier string for the role. */
+    name: string;
+    /** The UI-friendly label for the role. */
+    label: string;
+    /** A brief summary of the role's purpose. */
+    description?: string;
+    /** Integer count of how many preference records are tied to this role. */
+    preferences: number;
+    /** Topics relevant to this role. */
+    topics?: string[];
+    /** The top-level constraints baked into the role. */
+    constraints?: ModelConstraintMap;
 }
-/** Creates a new version of an existing turn. */
-interface EditTurn extends BaseCommand {
-    type: 'turn:edit';
-    payload: {
-        sessionId: UUID;
-        turnId: UUID;
-        newBlocks: ContentBlock[];
-        newVersion: number;
-        roleSnapshot?: string;
-    };
+/** In-memory summary of a Preference. */
+interface PreferenceSummary {
+    /** Unique identifier for the preference. */
+    id: UUID;
+    /** The topics linking this preference to the rest of the workspace. */
+    topics: string[];
+    /** UTC timestamp of the last update. */
+    timestamp: Timestamp;
+    /** A truncated preview string of the preference content. */
+    snippet?: string;
 }
-/** Creates a new branch in the conversation history from a specific turn. */
-interface BranchTurn extends BaseCommand {
-    type: 'turn:branch';
-    payload: {
-        sessionId: UUID;
-        turn: Turn;
-    };
-}
-interface TurnRef {
-    id: UUID;
-    version: number;
-}
-/** Removes a specific version of a turn and updates the session head if necessary. */
-interface DeleteTurn extends BaseCommand {
-    type: 'turn:delete';
-    payload: {
-        sessionId: UUID;
-        turnId: UUID;
-        version: number;
-        newHead: TurnRef | null;
-    };
-}
-interface SwitchRole extends BaseCommand {
-    type: 'session:role:switch';
-    payload: {
-        sessionId: UUID;
-        role: string;
-    };
-}
-interface AddSessionTopics extends BaseCommand {
-    type: 'session:topics:add';
-    payload: {
-        sessionId: UUID;
-        topics: string[];
-    };
-}
-interface OverrideSessionPreferences extends BaseCommand {
-    type: 'session:preferences:override';
-    payload: {
-        sessionId: UUID;
-        preferences: UUID[];
-    };
-}
-/** Creates a new session starting from the state of an existing one. */
-interface ForkSession extends BaseCommand {
-    type: 'session:fork';
-    payload: {
-        sourceSessionId: UUID;
-        newSessionId: UUID;
-        label: string;
-        role?: string;
-        topics?: string[];
-    };
-}
-interface UpdateSession extends BaseCommand {
-    type: 'session:update';
-    payload: {
-        sessionId: UUID;
-        label?: string;
-        role?: string;
-        topics?: string[];
-        preferences?: UUID[];
-        task?: UUID | null;
-    };
-}
-interface DeleteSession extends BaseCommand {
-    type: 'session:delete';
-    payload: {
-        sessionId: UUID;
-    };
-}
-interface RegisterBlob extends BaseCommand {
-    type: 'blob:register';
-    payload: {
-        data: Uint8Array;
-        mediaType: BlobMediaType;
-        filename?: string;
-    };
-}
-/** Increases reference count to prevent garbage collection. */
-interface RetainBlob extends BaseCommand {
-    type: 'blob:retain';
-    payload: {
-        sha256: SHA256;
-    };
-}
-/** Decreases reference count. */
-interface ReleaseBlob extends BaseCommand {
-    type: 'blob:release';
-    payload: {
-        sha256: SHA256;
-    };
-}
-/** Immediately removes a blob regardless of reference count. */
-interface PurgeBlob extends BaseCommand {
-    type: 'blob:purge';
-    payload: {
-        sha256: SHA256;
-    };
-}
-/** Maps a local blob to an external provider's file ID. */
-interface RecordBlobRemoteId extends BaseCommand {
-    type: 'blob:record_remote_id';
-    payload: {
-        sha256: SHA256;
-        providerId: string;
-        fileId: string;
-        timestamp?: Timestamp;
-    };
-}
-type BlobCommand = RegisterBlob | RetainBlob | ReleaseBlob | PurgeBlob | RecordBlobRemoteId;
-interface CallTool extends BaseCommand {
-    type: 'tool:call';
-    payload: ToolCall;
-}
-/** Union of all possible commands that can be dispatched to the Workspace Manager. */
-type Command = CreateWorkspace | AddRole | UpdateRole | DeleteRole | AddPreference | UpdatePreference | DeletePreference | CreateSession | UpdateSession | AddContext | UpdateContext | DeleteContext | AddTask | UpdateTask | DeleteTask | AddTurn | SaveTurn | EditTurn | BranchTurn | DeleteTurn | SwitchRole | AddSessionTopics | OverrideSessionPreferences | ForkSession | DeleteSession | BlobCommand | CallTool;
-/** Configuration for token counting and management during prompt generation. */
-interface TokenBudget {
-    total: number;
-    estimator?: (text: string) => number;
-    blobTokensPerKB?: number;
+/** In-memory summary of a Context entry. */
+interface ContextSummary {
+    /** The unique key for the context item. */
+    key: string;
+    /** Associated semantic topics. */
+    topics: string[];
+    /** UTC timestamp of addition. */
+    timestamp: Timestamp;
+    /** MIME type, if applicable to the content kind. */
+    mime?: string;
+    /** File size in bytes, if applicable. */
+    size?: number;
+    /** Truncated text preview or URL for visual representation. */
+    preview?: string;
+    /** Origin or source string indicating where the context came from. */
+    source?: string;
+    /** Flattened representation of the context's internal metadata. */
+    metadata?: Record<string, any>;
 }
-/** Details regarding why a specific preference was excluded from a prompt. */
-interface PreferenceConflict {
+/** Maps topics to the various entities that reference them. */
+interface TopicIndex {
+    /** The exact string name of the topic. */
     topic: string;
-    kept: UUID;
-    dropped: UUID;
-    reason: 'superseded_by_newer';
-}
-/**
- * The final structure sent to an LLM provider.
- * Assembled by the PromptAssembler by resolving roles, context, and history.
- */
-interface Prompt {
-    /** Information destined for the System Message. */
-    system: {
-        instructions?: string;
-        persona: string;
-        preferences: Preference[];
-        context: Context[];
-        task: Task | null;
-    };
-    /** Additional context items injected separately. */
-    context: Context[];
-    /** The conversation history. */
-    transcript: {
-        turns: Turn[];
-    };
-    budget: {
-        total: number;
-        used: number;
-        breakdown: Record<string, number>;
-    };
-    /** Statistics on what was removed to fit within the token limit. */
-    truncated: {
-        preferences: number;
-        interactions: number;
-        context: number;
-    };
-    warnings: string[];
-    conflicts: PreferenceConflict[];
-}
-/** Typed events emitted by the Workspace when data changes. */
-interface WorkspaceEvents {
-    /** Emitted when the index or core settings change. */
-    'workspace:changed': DeepPartial<Workspace>;
-    /** Emitted when a blob is registered, updated, or removed. */
-    'blobs:changed': {
-        sha256: SHA256;
-        record: BlobRecord | null;
+    /** Array of context keys that fall under this topic. */
+    contextKeys: string[];
+    /** Array of preference UUIDs that fall under this topic. */
+    preferences: UUID[];
+    /** Aggregated metadata regarding topic usage. */
+    metadata?: {
+        /** When the topic was first registered. */
+        created?: Timestamp;
+        /** When the topic was last updated or applied. */
+        updated?: Timestamp;
+        /** Total number of workspace items referencing this topic. */
+        entries?: number;
     };
 }
-
-/**
- * Handles transcript compression and history management.
- * When a conversation exceeds the model's context window, the Summarizer
- * condenses older turns into a single summary string to reclaim tokens.
- */
-interface Summarizer {
-    /**
-     * Compresses the provided transcript.
-     * * @param transcript - The current list of conversation turns.
-     * @param tokenBudget - The maximum allowed tokens for the history.
-     * @returns A promise resolving to the summary and the remaining uncompressed turns.
-     */
-    summarize(transcript: Turn[], tokenBudget: number): Promise<{
-        summary: string;
-        remaining: Turn[];
-    }>;
-}
-/**
- * Analyzes model outputs for side effects and workspace actions.
- * The TurnProcessor scans the assistant's response (Turn) for specific
- * triggers, such as file edits, UI updates, or state changes.
- */
-interface TurnProcessor {
-    /**
-     * Scans a turn for actionable blocks and returns workspace commands.
-     * @param turn - The assistant turn to be processed.
-     * @param sessionId - The session in which the turn was generated.
-     * @returns An array of Commands to synchronize the Workspace state.
-     */
-    process(turn: Turn, sessionId?: UUID): Command[];
-}
-/**
- * Manages the lifecycle and execution of external tools.
- * Acts as a central hub for discovering available capabilities and
- * routing tool calls to their respective executors.
- */
-interface ToolRegistry {
-    /**
-     * Subscribes to changes in the tool ecosystem.
-     * @param callback - Invoked whenever tools are added, removed, or updated.
-     */
-    onRegistryChanged(callback: (tools: ToolSummary[]) => void): void;
-    /**
-     * Retrieves a list of all currently registered and available tools.
-     * @returns An array of summaries describing tool capabilities and schemas.
-     */
-    list(): ToolSummary[];
-    /**
-     * Executes a tool call in a stateless manner.
-     * * @template T - The expected return type of the tool execution.
-     * @param call - The specific tool call requested by the model.
-     * @returns A promise resolving to a Result wrapper containing the tool output.
-     */
-    execute<T = any>(call: ToolCall): Promise<Result<T>>;
-}
-/**
- * Enforces security and authorization policies.
- * * The PermissionGuard ensures that the current execution context (User/Session)
- * has the necessary privileges to perform a requested action or tool call.
- */
-interface PermissionGuard {
-    /**
-     * Validates if the current context has the right to execute the request.
-     * * @param request - The authentication payload and target action.
-     * @returns A Result containing the authorized payload or an error.
-     */
-    authenticate(request: AuthRequest): Promise<Result<AuthRequest["payload"] | null>>;
-}
-/**
- * Bridge between the internal Workspace types and external LLM APIs.
- * This generic adapter allows the system to remain vendor-agnostic by
- * centralizing the translation logic for different providers (Google, OpenAI, etc.).
- * @template TRequest - The specific request shape expected by the provider SDK.
- * @template TRequestParams - Extra parameters for the request (e.g., model name, temperature).
- * @template TResponse - The raw response shape returned by the provider SDK.
- */
-interface LLMAdapter<TRequest, TRequestParams, TResponse> {
-    /**
-     * Maps the internal `Prompt` to the vendor-specific request format.
-     * * @param params - The prompt and provider-specific configuration.
-     * @returns The formatted request object ready for the SDK.
-     */
-    /**
-     * Prepares the request and identifies necessary side-effects (like uploads).
-     */
-    prepare(params: {
-        prompt: Prompt;
-    } & TRequestParams): Promise<{
-        request: TRequest;
-        effects?: Command[];
-    }>;
-    /**
-     * Maps the vendor-specific response back to an internal `Turn`.
-     * * @param params - The raw response received from the model API.
-     * @returns A Result containing standardized Turn object or an error.
-     */
-    parse(params: {
-        response: TResponse;
-    }): Result<Turn, WorkspaceError>;
-}
-
-/**
- * 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;
+/** The complete in-memory read-model of the Workspace state. */
+interface Index {
+    /** Lookup dictionary of Roles by their string name. */
+    roles: Record<string, RoleSummary>;
+    /** Lookup dictionary of Preferences by their UUID. */
+    preferences: Record<UUID, PreferenceSummary>;
+    /** Lookup dictionary of Context entries by their specific key. */
+    context: Record<string, ContextSummary>;
+    /** Lookup dictionary of active Sessions by their UUID. */
+    sessions: Record<UUID, SessionMetadata>;
+    /** Lookup dictionary of semantic Topics by their string name. */
+    topics: Record<string, TopicIndex>;
+    /** Lookup dictionary of authoritative Blob records by their SHA-256 hash. */
+    blobs: Record<SHA256, BlobRecord>;
+    /** Lookup dictionary of registered Tool capabilities by their string name. */
+    tools: Record<string, ToolSummary>;
+}
+/** The root container for a user's workspace. */
+interface Workspace<ProjectMetadata extends Record<string, any> = Record<string, any>> {
+    /** Unique identifier for the entire workspace environment. */
+    id: UUID;
+    /** Global user and systemic settings. */
+    settings: Settings;
+    /** High-level project metadata. */
+    project: Project<ProjectMetadata>;
+    /** The in-memory read-projection of all underlying stores. */
+    index: Index;
 }
 /**
- * Event payload for Collection events.
+ * Format used for exporting/importing a complete workspace state,
+ * including all historical turns and binary records.
  */
-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>;
+interface WorkspaceBundle {
+    /** Schema version identifier for serialization compatibility. */
+    format: "aiworkspace/4.0";
+    /** The core workspace root data. */
+    workspace: Workspace;
+    /** All exported role definitions. */
+    roles: Record<string, Role>;
+    /** All exported preference objects. */
+    preferences: Record<UUID, Preference>;
+    /** All exported context entries. */
+    context: Record<string, Context>;
+    /** All exported sessions, deeply hydrated with their complete turn history. */
+    sessions: Record<UUID, SessionMetadata & {
+        turns: Turn[];
+    }>;
+    /** All exported blob definitions (may contain base64 binary strings or remote mappings). */
+    blobs: Record<SHA256, BlobRecord>;
 }
-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;
+/** Base structure for all state-mutating commands in the system. */
+interface BaseCommand<T = any> {
+    /** Discriminator for the specific command type. */
+    type: string;
+    /** UTC timestamp of when the command was issued. */
+    timestamp: Timestamp;
+    /** The ID of the user, system component, or tool that initiated the command. */
+    actor?: SystemActor;
+    /** An optional, human-readable reason or annotation for the execution. */
+    description?: string;
+    /** Indicates this command was automatically fired as a side-effect of another command. */
+    synthetic?: boolean;
+    /** Payload */
+    payload: T;
+}
+interface CreateWorkspace extends BaseCommand {
+    type: "workspace:create";
+    /** Payload detailing initial setup values for the environment. */
+    payload: {
+        id: UUID;
+        settings: Settings;
+        project: Project;
+    };
+}
+interface AddRole extends BaseCommand {
+    type: "role:add";
+    /** The complete role object to inject into the workspace. */
+    payload: Role;
+}
+interface UpdateRole extends BaseCommand {
+    type: "role:update";
+    /** Delta properties to merge into the existing role definition. */
+    payload: Partial<Role> & {
+        name: string;
+    };
+}
+interface DeleteRole extends BaseCommand {
+    type: "role:delete";
+    /** Name of the role to destroy. */
+    payload: {
+        name: string;
+    };
+}
+interface AddPreference extends BaseCommand {
+    type: "preference:add";
+    /** The complete preference object to register. */
+    payload: Preference;
+}
+interface UpdatePreference extends BaseCommand {
+    type: "preference:update";
+    /** Delta properties to merge into the existing preference record. */
+    payload: Partial<Preference> & {
+        id: UUID;
+    };
+}
+interface DeletePreference extends BaseCommand {
+    type: "preference:delete";
+    /** UUID of the preference to drop. */
+    payload: {
+        id: UUID;
+    };
+}
+interface CreateSession extends BaseCommand {
+    type: "session:create";
+    /** Initial setup parameters for the new conversation session. */
+    payload: {
+        id: UUID;
+        label: string;
+        role: string;
+        topics: string[];
+        preferences: UUID[];
+        metadata: {
+            created?: Timestamp;
+            updated?: Timestamp;
         };
-        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";
-    readonly TASK: "task";
-};
-type CollectionName = typeof COLLECTIONS[keyof typeof COLLECTIONS];
-
-declare function del<T>(): T;
-declare const merge: <T extends object>(original: T, changes: DeepPartial<T> | symbol) => T;
-declare function success<T>(value: T): Result<T, never>;
-declare function error<E = WorkspaceError>(error: E): Result<never, E>;
-declare function omitNullUndefined<T extends Record<string, any>>(obj: T): Partial<T>;
-declare function createProjectWorkspace<ProjectMetadata extends Record<string, any> = Record<string, any>>({ project, language }: {
-    language: string;
-    project: Omit<Project<ProjectMetadata>, "id">;
-}): Workspace<ProjectMetadata>;
-declare function createSimpleWorkspace({ name, actor, language }: {
+interface AddContext extends BaseCommand {
+    type: "context:add";
+    /** The new context object to write to the store. */
+    payload: Context;
+}
+interface UpdateContext extends BaseCommand {
+    type: "context:update";
+    /** Delta properties to update an existing context record. */
+    payload: Partial<Context> & {
+        key: string;
+    };
+}
+interface DeleteContext extends BaseCommand {
+    type: "context:delete";
+    /** Key of the context entry to destroy. */
+    payload: {
+        key: string;
+    };
+}
+/** Updates an existing turn record in storage. */
+interface UpdateTurn extends BaseCommand {
+    type: "turn:update";
+    /** The session scope and the fully updated turn structure. */
+    payload: {
+        sessionId: UUID;
+        turn: Turn;
+    };
+}
+/** Appends a new turn to a session. */
+interface AddTurn extends BaseCommand {
+    type: "turn:add";
+    /** The session scope and the new turn to mount. */
+    payload: {
+        sessionId: UUID;
+        turn: Turn;
+    };
+}
+/** Creates a new version of an existing turn. */
+interface EditTurn extends BaseCommand {
+    type: "turn:edit";
+    /** Details for incrementing a specific turn's iteration without losing history. */
+    payload: {
+        sessionId: UUID;
+        turnId: UUID;
+        newBlocks: ContentBlock[];
+        newVersion: number;
+        roleSnapshot?: string;
+    };
+}
+/** Creates a new branch in the conversation history from a specific turn. */
+interface BranchTurn extends BaseCommand {
+    type: "turn:branch";
+    /** The turn object that initiates the new divergent history line. */
+    payload: {
+        sessionId: UUID;
+        turn: Turn;
+    };
+}
+/** Reference to a specific iteration of a turn. */
+interface TurnRef {
+    /** The ID of the referenced turn. */
+    id: UUID;
+    /** The exact version number of the referenced turn. */
+    version: number;
+}
+/** Removes a specific version of a turn and updates the session head if necessary. */
+interface DeleteTurn extends BaseCommand {
+    type: "turn:delete";
+    /** Identification payload to target the precise turn version for destruction. */
+    payload: {
+        sessionId: UUID;
+        turnId: UUID;
+        version: number;
+        /** The fallback position if deleting the current head. */
+        newHead?: TurnRef;
+    };
+}
+interface SwitchSessionRole extends BaseCommand {
+    type: "session:role:switch";
+    /** Defines the transition of a session from one persona to another. */
+    payload: {
+        sessionId: UUID;
+        roleName: string;
+    };
+}
+interface AddSessionTopics extends BaseCommand {
+    type: "session:topics:add";
+    /** Appends semantic tags to an existing session for RAG alignment. */
+    payload: {
+        sessionId: UUID;
+        topics: string[];
+    };
+}
+interface OverrideSessionPreferences extends BaseCommand {
+    type: "session:preferences:override";
+    /** Replaces the explicit preference list attached to a session. */
+    payload: {
+        sessionId: UUID;
+        preferences: UUID[];
+    };
+}
+/** Creates a new session starting from the state of an existing one. */
+interface ForkSession extends BaseCommand {
+    type: "session:fork";
+    /** Data defining the divergence point and initial overrides for the new fork. */
+    payload: {
+        sessionId: UUID;
+        newSessionId: UUID;
+        label: string;
+        role?: string;
+        topics?: string[];
+    };
+}
+interface UpdateSession extends BaseCommand {
+    type: "session:update";
+    /** Modifiable metadata fields for an ongoing session. */
+    payload: {
+        sessionId: UUID;
+        label?: string;
+        role?: string;
+        topics?: string[];
+        preferences?: UUID[];
+        metadata?: SessionMetadata["metadata"];
+    };
+}
+interface DeleteSession extends BaseCommand {
+    type: "session:delete";
+    /** Identifier of the session to terminate and purge. */
+    payload: {
+        sessionId: UUID;
+    };
+}
+interface RegisterBlob extends BaseCommand {
+    type: "blob:register";
+    /** Standard payload for intaking new binary data into the blob system. */
+    payload: {
+        data: Uint8Array;
+        mediaType: BlobMediaType;
+        filename?: string;
+    };
+}
+/** Increases reference count to prevent garbage collection. */
+interface RetainBlob extends BaseCommand {
+    type: "blob:retain";
+    /** The hash targeting the specific blob to protect. */
+    payload: {
+        sha256: SHA256;
+    };
+}
+/** Decreases reference count. */
+interface ReleaseBlob extends BaseCommand {
+    type: "blob:release";
+    /** The hash targeting the specific blob to un-protect. */
+    payload: {
+        sha256: SHA256;
+    };
+}
+/** Immediately removes a blob regardless of reference count. */
+interface PurgeBlob extends BaseCommand {
+    type: "blob:purge";
+    /** The hash targeting the specific blob for immediate destruction. */
+    payload: {
+        sha256: SHA256;
+    };
+}
+/** Maps a local blob to an external provider's file ID. */
+interface RecordBlobRemoteId extends BaseCommand {
+    type: "blob:record_remote_id";
+    /** Payload linking local workspace data to an external API's asset registry. */
+    payload: {
+        sha256: SHA256;
+        providerId: string;
+        fileId: string;
+        timestamp?: Timestamp;
+    };
+}
+/** Union of all blob management commands. */
+type BlobCommand = RegisterBlob | RetainBlob | ReleaseBlob | PurgeBlob | RecordBlobRemoteId;
+/** Entity representing a categorization or grouping mechanism. */
+interface Topic {
+    /** Core string identifier (e.g., 'machine-learning'). */
     name: string;
-    language: string;
-    actor: string;
-}): Workspace;
-declare function extractBlobRecord(patch: DeepPartial<Workspace>): BlobRecord | null;
-declare function extractBlobRef(record: BlobRecord): BlobRef;
-declare function computeSHA256(data: Uint8Array): Promise<SHA256>;
-/**
- * Creates a skeleton Role object with empty defaults.
- */
-declare const createEmptyRole: (name: string, label: string) => Role;
-/**
- * Isomorphic Base64 converter (Node.js / browser).
- */
-declare function bufferToBase64(data: ArrayBuffer | Uint8Array | number[]): string;
-
-/**
- * Short, deterministic hash of a string (4 chars in base36).
- * Suitable for AI-friendly reference tokens.
- */
-declare function shortHash(s: string, length?: number): string;
+    /** UI-friendly presentation string. */
+    label?: string;
+    /** Deep description of what the topic encompasses. */
+    description?: string;
+    /** Extensible key-value store for topic-specific attributes. */
+    metadata?: Record<string, any>;
+    /** Timestamp of initial topic creation. */
+    created: Timestamp;
+    /** Timestamp of the most recent modification. */
+    updated: Timestamp;
+}
+interface AddTopic extends BaseCommand {
+    type: "topic:add";
+    /** Fully formed topic object to inject. */
+    payload: Topic;
+}
+interface UpdateTopic extends BaseCommand {
+    type: "topic:update";
+    /** Delta properties for modifying an existing topic. */
+    payload: Partial<Topic> & {
+        name: string;
+    };
+}
+interface DeleteTopic extends BaseCommand {
+    type: "topic:delete";
+    /** Rules for removing a topic, optionally destroying linked resources. */
+    payload: {
+        name: string;
+        cascade?: boolean;
+    };
+}
+interface MergeTopics extends BaseCommand {
+    type: "topic:merge";
+    /** Consolidates two separate topics, migrating all relationships to the target. */
+    payload: {
+        source: string;
+        target: string;
+    };
+}
+/** Executes a tool payload securely. */
+interface ToolCallCommand extends BaseCommand {
+    type: "tool:call";
+    /** Payload detailing the execution request for a registered tool. */
+    payload: ToolCall;
+}
+/** Union of all possible commands that can be dispatched to the Workspace Manager. */
+type Command = CreateWorkspace | AddRole | UpdateRole | DeleteRole | AddPreference | UpdatePreference | DeletePreference | CreateSession | UpdateSession | ForkSession | DeleteSession | SwitchSessionRole | AddSessionTopics | OverrideSessionPreferences | AddContext | UpdateContext | DeleteContext | UpdateTurn | AddTurn | EditTurn | BranchTurn | DeleteTurn | RegisterBlob | RetainBlob | ReleaseBlob | PurgeBlob | RecordBlobRemoteId | AddTopic | UpdateTopic | DeleteTopic | MergeTopics | ToolCallCommand;
 /**
- * Generates a short, memorable reference for a task.
- * - Returns the proposal's own `ref` if provided.
- * - Otherwise returns a 4‑character hash of the proposal's `id` or `title`.
+ * Standard reducer pattern for updating workspace state.
+ * @template T - Custom contextual additions for the reducer parameters.
+ * @template R - The payload type the reducer expects to process.
  */
-declare function generateTaskRef(proposal: TaskProposalBlock): string;
+type WorkspaceReducer<T = any, R = any> = (
+/** Combined system context containing current state and active configurations. */
+ctx: {
+    workspace: Workspace;
+} & T, 
+/** The payload defining the intended mutation. */
+payload: R) => Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
 /**
- * Generates a short step reference.
- * - Returns the step's own `ref` if provided.
- * - Otherwise returns `${taskRef}_${index+1}` (e.g., "a3f9_2").
- *
- * The underscore separator avoids confusion with colons, slashes, or
- * numeric suffixes that could be misinterpreted by LLMs.
+ * Middleware wrapper for observing or intercepting command dispatches.
  */
-declare function generateTaskStepRef(index: number, proposal: TaskProposalBlock): string;
+type WorkspaceMiddleware = (
+/** Comprehensive payload including the state, the executing command, and the intended state delta. */
+ctx: {
+    workspace: Workspace;
+    command: BaseCommand;
+    patch: DeepPartial<Workspace>;
+} & WorkspaceContext) => Promise<DeepPartial<Workspace>>;
+/** A fully hydrated and normalized session structure. */
+interface ResolvedSession {
+    /** The ID of the session. */
+    sessionId: UUID;
+    /** The active, fully resolved persona definition. */
+    role: Role;
+    /** The deduplicated, prioritized array of active preferences. */
+    preferences: Preference[];
+    /** RAG-retrieved context items relevant to the current conversation. */
+    context: Context[];
+    /** The linear conversation sequence flattened from the DAG structure. */
+    transcript: Turn[];
+    /** Dictionary of completely resolved local and remote binary assets. */
+    blobs: Map<SHA256, ResolvedBlob>;
+    /** The global system prompt overlay, if present. */
+    instructions?: string;
+    /** Array of warning strings generated during the resolution process. */
+    warnings: string[];
+}
+/** Typed events emitted by the Workspace when data changes. */
+interface WorkspaceEvents {
+    /** Emitted when the index or core settings change. */
+    "workspace:changed": DeepPartial<Workspace>;
+    /** Emitted when a blob is registered, updated, or removed. */
+    "blobs:changed": {
+        /** Hash of the affected blob. */
+        sha256: SHA256;
+        /** The actual modified record, or undefined if deleted. */
+        record?: BlobRecord;
+    };
+}
+/** Complete snapshot of the session provided to the PromptBuilder. */
+interface SessionSnapshot {
+    /** Session identifier. */
+    id: UUID;
+    /** Top-level session definition fields. */
+    meta: SessionMetadata;
+    /** The active role — persona, instructions, role-level constraints. */
+    role: Role;
+    /** Unfiltered, unranked preferences attached strictly to the role or session. */
+    preferences: Preference[];
+    /** All context entries whose topics overlap with the session's active topics. */
+    context: Context[];
+    /** Full active chain from TurnTree — oldest to newest. Untruncated. */
+    transcript: Turn[];
+    /** The session's active semantic topic set. */
+    topics: string[];
+    /** Global workspace instructions from Settings.prompt, if set. */
+    instructions?: string;
+    /** Model constraints structured by their hierarchical application level. */
+    constraints: {
+        /** Broadest constraints explicitly linked to the active role. */
+        role?: ModelConstraintMap;
+        /** Overriding constraints attached to the active session. */
+        session?: ModelConstraintMap;
+        /** The most explicit constraints captured at the last user turn. */
+        turn?: ModelConstraintMap;
+    };
+}
 
 /**
- * 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.
+ * Output of PromptBuilder.build(). Input to LLMAdapter.resolve().
  *
- * Keeping them in the same backend ensures atomicity: registering a blob and
- * storing its bytes happen in the same transaction boundary.
+ * Contains fully ranked and conflict-resolved preferences, context, and a
+ * catalogue of blob references — but is NOT truncated and does NOT contain
+ * resolved binary blob data. The adapter is responsible for:
+ *   - Deciding what fits within the model's context window.
+ *   - Resolving only the BlobRefs that survive truncation.
+ *   - Uploading inline blobs to the provider where required.
  */
-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. */
-    loadBytes(sha256: SHA256): Promise<Uint8Array | null>;
-    /** Returns true if bytes are stored locally for this SHA-256. */
-    hasBytes(sha256: SHA256): Promise<boolean>;
-    /**
-     * Delete raw bytes. Called by BlobStore when refCount reaches 0 and
-     * the blob has been evicted from the local store.
-     */
-    deleteBytes(sha256: SHA256): Promise<void>;
-    /** Persist a BlobRecord (registry metadata, not bytes). */
-    saveRecord(record: BlobRecord): Promise<void>;
-    /** Load a BlobRecord by SHA-256. Returns null if not found. */
-    loadRecord(sha256: SHA256): Promise<BlobRecord | null>;
-    /** Delete a BlobRecord. Called when a blob is fully evicted. */
-    deleteRecord(sha256: SHA256): Promise<void>;
-    /** Return all stored BlobRecords. Used for bundle export and GC sweeps. */
-    listRecords(): Promise<BlobRecord[]>;
-    /**
-     * Export all bytes as an iterable of [sha256, Uint8Array] pairs.
-     * Used for workspace export / migration.
-     */
-    exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
+interface Prompt {
+    /** Correlates this prompt to its session for logging and evaluation. */
+    session: UUID;
+    /** System-level instructions, context, and preferences. */
+    system: {
+        /** The active role's persona string. */
+        persona: string;
+        /** Global or session-level instructions. */
+        instructions?: string;
+        /** Conflict-resolved, relevance-ordered preferences. */
+        preferences: Preference[];
+        /** Ranked context entries (text and json kinds only). Blob context is
+         *  represented as referential blocks in the transcript instead. */
+        context: Context[];
+    };
+    /** Active conversation chain, oldest to newest. May include synthetic turns.
+     *  Image and document blocks carry a BlobRef only; the adapter resolves them. */
+    transcript: Turn[];
     /**
-     * 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.
+     * Lightweight catalogue of every blob referenced anywhere in this prompt
+     * (system.context or transcript), keyed by SHA256.
+     *
+     * Values are BlobRefs — metadata only, no binary data. The adapter uses
+     * this catalogue to resolve or upload blobs for whichever turns and context
+     * entries survive its truncation pass.
      */
-    registerBlob?(record: BlobRecord, data: Uint8Array): Promise<void>;
-}
-
-declare class TurnTree {
-    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;
-    private loadRaw;
-    getHead(sessionId: UUID): Promise<TurnRef | null>;
-    setHead(sessionId: UUID, head: TurnRef | null): Promise<void>;
-    save(sessionId: UUID, turn: Turn, head?: TurnRef | null): Promise<Turn>;
-    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[]>;
-    loadTurnVersions(sessionId: UUID, turnId: UUID): Promise<Turn[]>;
-    buildNodes(turns: Turn[], head: TurnRef | null, dirtyBuffer?: readonly Turn[]): Record<UUID, TurnNode>;
-    buildNodeGraph(sessionId: UUID, dirtyBuffer?: readonly Turn[]): Promise<Record<UUID, TurnNode>>;
-    getActiveChain(sessionId: UUID, dirtyBuffer?: readonly Turn[]): Promise<Turn[]>;
-    buildActiveChain(sessionId: UUID): Promise<TurnNode[]>;
-    getTurnSiblings(turnId: UUID, sessionId: UUID): Promise<TurnNode[]>;
-    branchInfo(turnId: UUID, sessionId: UUID): Promise<BranchInfo>;
-    deleteSubtree(sessionId: UUID, turnId: UUID, version: number, newHead: TurnRef | null): Promise<void>;
-    copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
-}
-
-interface BlobStoreConfig {
+    blobs: Map<SHA256, BlobRef>;
+    /** The role object — for inspection and adapter use. */
+    role: Role;
+    /** Model constraints to be merged by the adapter (turn > session > role). */
+    constraints: ModelConstraintMap;
     /**
-     * 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.
+     * Non-fatal warnings generated during the build phase.
+     * Adapters and callers should surface or log these.
+     * Examples: summarizer failures, unresolvable blob refs.
      */
-    eagerEviction?: boolean;
+    warnings: string[];
 }
-declare class BlobStore {
-    private readonly storage;
-    private readonly config;
-    private bus;
-    /**
-     * In-memory cache of BlobRecords. Kept consistent with the backend on
-     * every write. Records are small (no bytes), so we cache all of them.
-     */
-    private readonly recordCache;
-    constructor(backend: BlobStorage, bus: EventBus<WorkspaceEvents>, config?: BlobStoreConfig);
-    /**
-     * Called after any operation that changes the blob registry.
-     * 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.
-     */
-    subscribe<TEventName extends keyof WorkspaceEvents>(event: TEventName, callback: (payload: WorkspaceEvents[TEventName]) => void): () => void;
-    init(): Promise<void>;
-    register(data: Uint8Array, mediaType: BlobMediaType, filename?: string): Promise<Result<BlobRef, WorkspaceError>>;
-    retain(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
-    release(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
-    recordRemoteId(sha256: SHA256, providerId: string, fileId: string): Promise<Result<void, WorkspaceError>>;
-    getRemoteId(sha256: SHA256, providerId: string): string | null;
-    getRemoteRecord(sha256: SHA256, providerId: string): {
-        id: string;
-        timestamp: Timestamp;
-    } | null;
-    resolveRef(ref: BlobRef, providerId: string | null): Promise<Result<ResolvedBlob, WorkspaceError>>;
-    resolveRefs(refs: BlobRef[], providerId: string | null): Promise<{
-        resolved: Map<SHA256, ResolvedBlob>;
-        errors: Array<{
-            ref: BlobRef;
-            error: WorkspaceError;
-        }>;
+/**
+ * Reflects the current state of the LLM adapter (limits, headroom, and readiness).
+ */
+interface AdapterStatus {
+    /** Provider name (e.g., "google", "anthropic", "openai"). */
+    provider: string;
+    /** Model identifier (e.g., "claude-sonnet-4-6", "gemini-2.0-flash"). */
+    model: string;
+    /** Whether the adapter is currently able to accept requests. */
+    ready: boolean;
+    /** Token window limits and current usage. */
+    window: {
+        /** Total context window size in tokens. */
+        size: number;
+        /** Maximum output tokens for this model. */
+        out: number;
+        /** Tokens remaining — estimated or as reported by the provider. */
+        free?: number;
+    };
+    /** Capability flags for this model. */
+    feature: {
+        /** Whether the model can process image inputs. */
+        vision: boolean;
+        /** Whether the model supports tool/function calling. */
+        tools: boolean;
+        /** Whether the model supports structured JSON output mode. */
+        json: boolean;
+        /** Whether the provider supports prompt caching. */
+        cache: boolean;
+        /** Whether the adapter supports streaming. */
+        streaming: boolean;
+        /** Whether the model supports extended thinking/reasoning tokens. */
+        thinking: boolean;
+    };
+    /** Pricing tiers for this model. */
+    pricing: Array<{
+        unit: 'token' | 'call';
+        /** Exponent: price is per 10^scale units. */
+        scale: number;
+        /** Price per unit in USD. */
+        cost: {
+            input: number;
+            output: number;
+            cache?: {
+                read: number;
+                write: number;
+            };
+        };
     }>;
-    gc(): Promise<number>;
-    purge(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
-    getRecord(sha256: SHA256): BlobRecord | null;
-    /**
-     * All records — used to seed Index.blobs on init.
-     * Returns BlobRecord directly (BlobSummary has been removed).
-     */
-    getAllRecords(): Record<SHA256, BlobRecord>;
+    /** Current rate limit state. */
+    rate: {
+        /** Current saturation as a fraction of the most constrained limit (0.0 to 1.0). */
+        load: number;
+        /** Milliseconds until the next request is permitted. */
+        timeout?: number;
+        /** The hard limits enforced by the provider. */
+        capacity: Array<{
+            unit: 'token' | 'call';
+            /** Maximum units allowed per period. */
+            max: number;
+            /** Period length in seconds. */
+            period: number;
+        }>;
+    };
+    /** Adapter-level notes, e.g. model deprecation warnings. */
+    notes?: string[];
 }
-
-interface CacheConfig {
-    roles?: number;
-    preferences?: number;
-    context?: number;
-    tasks?: number;
-}
-interface ContentStoreConfig {
-    cache?: CacheConfig;
-}
-declare class ContentStore {
-    private readonly db;
-    readonly tree: TurnTree;
-    readonly blobs: BlobStore;
-    private readonly roleCache;
-    private readonly preferenceCache;
-    private readonly contextCache;
-    private readonly taskCache;
-    private bus;
-    subscribe<TEventName extends keyof WorkspaceEvents>(event: TEventName, callback: (payload: WorkspaceEvents[TEventName]) => void): () => void;
-    private constructor();
-    static create(db: WorkspaceDatabase, blobStorage: BlobStorage, eventBus: EventBus<WorkspaceEvents>, config?: ContentStoreConfig): Promise<ContentStore>;
-    private init;
-    getTurnTree(): TurnTree;
-    getRole(name: string): Promise<Result<Role, WorkspaceError>>;
-    saveRole(role: Role): 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[]>;
-    getTask(id: UUID): Promise<Result<Task, WorkspaceError>>;
-    saveTask(task: Task): Promise<void>;
-    deleteTask(id: UUID): Promise<void>;
-    getTasksByTopics(indexState: Index, topics: string[]): Promise<Task[]>;
-    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>;
-    getBlobResolver(): BlobStore['resolveRefs'];
-    appendTurn(sessionId: UUID, turn: Turn): Promise<Result<Turn, WorkspaceError>>;
-    saveTurn(sessionId: UUID, turn: Turn): Promise<Result<Turn, 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>;
-    resolveSession(workspace: Workspace, sessionId: UUID, transcript?: Turn[]): Promise<Result<EffectiveSession, WorkspaceError>>;
-    gc(): Promise<number>;
+/**
+ * The result of `PreparedPrompt.execute()`. Contains the turn and derived effects.
+ */
+interface ExecuteResult {
+    /** The newly generated assistant turn. */
+    turn: Turn;
+    /** Side-effect commands to dispatch against the workspace. */
+    effects: BaseCommand[];
 }
-
-declare class WorkspaceManager {
-    private readonly contentStore;
-    private readonly permissionGuard?;
-    private readonly toolRegistry?;
-    private readonly processor;
-    private bus;
-    constructor(options: {
-        contentStore: ContentStore;
-        permissionGuard?: PermissionGuard;
-        toolRegistry?: ToolRegistry;
-        eventBus: EventBus<WorkspaceEvents>;
-        turnProcessor?: TurnProcessor;
-    });
-    store(): ContentStore;
-    turnProcessor(): TurnProcessor;
+/**
+ * The complete, final prompt exactly as the model will receive it.
+ * Generic, provider-agnostic, fully inspectable, and executable.
+ */
+interface PreparedPrompt {
+    /** The complete system instruction broken into labelled sections for inspection. */
+    system: Array<{
+        /** Origin label for this section (e.g., "persona", "context:project-brief"). */
+        label: string;
+        /** Text content exactly as it will be sent to the model. */
+        content: string;
+        /** Optional structured metadata for richer UI display. */
+        metadata?: Record<string, any>;
+    }>;
+    /** Final transcript turns that will be sent after adapter-level truncation. */
+    transcript: Turn[];
+    /** Final context entries included after adapter-level truncation. */
+    context: Context[];
+    /** Final preferences included after adapter-level truncation. */
+    preferences: Preference[];
+    /** The resolved model constraints for this request. */
+    constraints: ModelConstraint;
+    /** Token accounting (estimated or exact). */
+    tokens: {
+        /** Breakdown by section. Keys are adapter-defined. */
+        breakdown: Record<string, number>;
+        /** Total input tokens — estimated or exact. */
+        total: number;
+        /** Whether total is an estimate or exact (provider-supplied). */
+        source: 'estimated' | 'exact';
+        /** Maximum output tokens configured for this request. */
+        output?: number;
+        /** Tokens remaining in the context window after this prompt. */
+        remaining?: number;
+    };
     /**
-     * Initializes a Workspace's in-memory Index from environment-static
-     * sources (like ToolRegistry). Call this when opening a Workspace.
+     * Sends this prompt to the model.
+     * @returns The parsed assistant Turn plus any execution side-effects.
      */
-    initTools(_: Workspace): DeepPartial<Workspace>;
+    execute(): Promise<Result<ExecuteResult, WorkspaceError>>;
     /**
-     * Called after any workspace change
+     * Streaming variant of execute(). Yields partial turns as tokens arrive.
+     * Present only if the adapter and model support streaming.
      */
-    subscribe<TEventName extends keyof WorkspaceEvents>(event: TEventName, callback: (payload: WorkspaceEvents[TEventName]) => void): () => 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, transcript?: Turn[]): Promise<Result<EffectiveSession, WorkspaceError>>;
-    private handleContentSideEffects;
-}
-
-interface ContextRelevanceConfig {
-    recentMessageWindow?: number;
-    minScore?: number;
-    freshnessHalfLifeDays?: number;
-}
-interface ContextRankingInput {
-    entries: Context[];
-    recentMessages: string[];
-    config: ContextRelevanceConfig;
-}
-interface ContextRetriever {
-    rank(input: ContextRankingInput): Context[];
-}
-interface PlanningInput {
-    systemInstructions?: string;
-    persona: string;
-    preferences: Preference[];
-    context: Context[];
-    task: Task | null;
-    transcript: Turn[];
-    budget?: TokenBudget;
-}
-interface PlanningOutput {
-    preferences: Preference[];
-    context: Context[];
-    task: Task | null;
-    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 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;
+    executeStream?(): AsyncIterable<Partial<Turn> | ExecuteResult>;
 }
 
 /**
- * A fluent builder for creating Turn objects.
- * This class helps construct a Turn object by adding various content blocks.
+ * A simple LRU (Least Recently Used) cache implementation.
+ * Used for caching frequently accessed entities in memory.
  */
-declare class TurnBuilder {
-    private readonly _actor;
-    private _turn;
-    constructor(_actor: TurnActor, initialTurn?: Turn);
-    addText(text: string): TurnBuilder;
-    addImage(ref?: BlobRef, altText?: string): TurnBuilder;
-    addDocument(ref?: BlobRef, title?: string): TurnBuilder;
-    addToolUse(name: string, input: Record<string, unknown>): TurnBuilder;
-    addToolResult(useId: UUID, content: string | Record<string, unknown>, isError?: boolean): TurnBuilder;
-    addSummary(text: string): TurnBuilder;
-    addRoleTransition(previousRole: string | null, newRole: string): TurnBuilder;
-    addThinking(thinking: string): TurnBuilder;
+declare class LRUCache<K, V> {
+    private cache;
+    private readonly maxSize;
+    constructor(maxSize: number);
+    /**
+     * Retrieves an item from the cache.
+     * Moves the item to the end of the cache (most recently used).
+     */
+    get(key: K): V | undefined;
     /**
-     * Adds a task proposal block.
-     * @param title The task title.
-     * @param steps Array of step objects (each with text and optional id/status). Status defaults to 'todo'.
-     * @param action The action type ('create', 'update', 'complete'). Defaults to 'create'.
-     * @param taskId Optional existing task ID (for update/complete).
-     */
-    addTaskProposal(title: string, steps: {
-        text: string;
-        status?: 'todo' | 'done';
-        ref?: string;
-    }[], action?: 'create' | 'update' | 'complete', id?: string): TurnBuilder;
-    addBlock(block: ContentBlock): TurnBuilder;
-    deleteBlock(blockId: UUID): TurnBuilder;
-    editTextBlock(blockId: UUID, newText: string): TurnBuilder;
-    withId(id: UUID): TurnBuilder;
-    withVersion(version: number): TurnBuilder;
-    withTimestamp(timestamp: Timestamp): TurnBuilder;
-    withParent(parent: TurnRef): TurnBuilder;
-    withRoleSnapshot(roleSnapshot: string): TurnBuilder;
-    build(): Turn;
+     * Adds or updates an item in the cache.
+     * If the cache exceeds maxSize, the least recently used item is removed.
+     */
+    set(key: K, value: V): void;
+    /**
+     * Checks if a key exists in the cache without refreshing it.
+     */
+    has(key: K): boolean;
+    /**
+     * Removes an item from the cache.
+     */
+    delete(key: K): void;
+    /**
+     * Clears all items from the cache.
+     */
+    clear(): void;
 }
 
-declare class DefaultTurnProcessor implements TurnProcessor {
-    private readonly handlers;
-    process(turn: Turn, sessionId?: UUID): Command[];
+/**
+ * Persistence contract for binary blob content and blob registry records.
+ *
+ * This is a hybrid interface because backends (like IndexedDB) need to
+ * ensure atomicity between storing raw bytes and their associated metadata.
+ */
+interface BlobStorage {
+    /** Store raw bytes for a blob. */
+    storeBytes(sha256: SHA256, data: Uint8Array): Promise<void>;
+    /** Load raw bytes. Returns null if not found locally. */
+    loadBytes(sha256: SHA256): Promise<Uint8Array | null>;
+    /** Returns true if bytes are stored locally for this SHA-256. */
+    hasBytes(sha256: SHA256): Promise<boolean>;
+    /** Delete raw bytes. */
+    deleteBytes(sha256: SHA256): Promise<void>;
+    /** Persist a BlobRecord (registry metadata). */
+    saveRecord(record: BlobRecord): Promise<void>;
+    /** Load a BlobRecord by SHA-256. */
+    loadRecord(sha256: SHA256): Promise<BlobRecord | null>;
+    /** Delete a BlobRecord. */
+    deleteRecord(sha256: SHA256): Promise<void>;
+    /** Return all stored BlobRecords. Used for GC and export. */
+    listRecords(): Promise<BlobRecord[]>;
+    /** Export all bytes for migration. */
+    exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
+    /** Optional atomic operation: store bytes and save record in one transaction. */
+    registerBlob?(record: BlobRecord, data: Uint8Array): Promise<void>;
 }
 
-declare class Session {
-    private readonly sessionId;
-    private readonly tree;
-    private readonly manager;
-    constructor(sessionId: UUID, tree: TurnTree, manager: WorkspaceManager);
-    /** Returns the UUID of this session. */
-    id(): UUID;
+/**
+ * Manages the registry of binary blobs.
+ * Uses a hybrid BlobStorage for bytes and records, ensuring atomicity.
+ */
+declare class BlobStore {
+    private readonly storage;
+    private readonly cache;
+    private readonly bus;
+    constructor(storage: BlobStorage, cache: LRUCache<SHA256, BlobRecord>, bus: EventBus<WorkspaceEvents>);
     /**
-     * Retrieves the full metadata record for this session from the workspace index.
+     * Registers a new blob. Uses atomic registerBlob if available.
      */
-    meta(workspace: Workspace): SessionMeta | undefined;
-    /** Returns the human-readable label for the session. */
-    label(workspace: Workspace): string | undefined;
-    /** Returns the name of the role currently assigned to this session. */
-    private roleName;
+    register(data: Uint8Array, mediaType: BlobMediaType, filename?: string): Promise<Result<BlobRef, WorkspaceError>>;
+    retain(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
+    release(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
+    purge(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
+    recordRemoteId(sha256: SHA256, providerId: string, fileId: string, timestamp?: string): Promise<Result<void, WorkspaceError>>;
+    getRecord(sha256: SHA256): Promise<BlobRecord | null>;
     /**
-     * Returns the RoleSummary (label, description, etc.) for the session's active role.
+     * All records — used to seed Index.blobs on init.
      */
-    role(workspace: Workspace): RoleSummary | undefined;
-    /** Returns the list of topics associated with this session. */
-    topics(workspace: Workspace): string[];
-    /** Returns the list of preference IDs overriding defaults for this session. */
-    preferences(workspace: Workspace): UUID[];
+    getAllRecords(): Promise<Record<SHA256, BlobRecord>>;
+    private reference;
     /**
-     * Returns the current "head" pointer (turnId and version) of the conversation DAG.
+     * Resolves a BlobRef to a ResolvedBlob (inline or remote) or null.
+     *
+     * Resolution precedence:
+     * 1. adapter provided and remote mapping exists for that adapter → remote blob (no local fallback)
+     * 2. adapter provided but remote mapping missing → local bytes (if available)
+     * 3. no adapter → local bytes (if available)
+     * 4. otherwise → null (unresolvable)
      */
-    head(workspace: Workspace): TurnRef | null;
+    resolve(ref: BlobRef, adapter?: string): Promise<Result<ResolvedBlob | null, WorkspaceError>>;
     /**
-     * Returns the full Task object if the session is currently linked to a task.
+     * Resolves multiple BlobRefs concurrently.
+     * Uses the same optional adapter for all refs (or none).
      */
-    task(workspace: Workspace): Promise<Task | undefined>;
+    resolveMany(refs: BlobRef[], adapter?: string): Promise<Result<Map<SHA256, ResolvedBlob>, WorkspaceError>>;
+}
+
+declare class ContextStore {
+    private readonly collection;
+    private readonly cache;
+    constructor(collection: Collection<Context>, cache: LRUCache<string, Context>);
+    get(key: string): Promise<Context | null>;
+    add(context: Context): Promise<void>;
+    list(): Promise<Context[]>;
+    update(key: string, updates: Partial<Context>): Promise<Context | null>;
+    delete(key: string): Promise<boolean>;
     /**
-     * Returns the TaskSummary if the session is currently linked to a task.
+     * Retrieves all context items referenced by the given topics using the in-memory index.
      */
-    taskSummary(workspace: Workspace): TaskSummary | undefined;
+    getByTopics(index: Index, topics: string[]): Promise<Context[]>;
+}
+
+declare class PreferenceStore {
+    private readonly collection;
+    private readonly cache;
+    constructor(collection: Collection<Preference>, cache: LRUCache<UUID, Preference>);
+    get(id: UUID): Promise<Preference | null>;
+    add(preference: Preference): Promise<void>;
+    update(id: UUID, updates: Partial<Preference>): Promise<Preference | null>;
+    delete(id: UUID): Promise<boolean>;
+    load(ids: UUID[]): Promise<Preference[]>;
+    list(): Promise<Preference[]>;
+}
+
+/**
+ * Atomic store for Role entities.
+ * Receives a pre-resolved Collection and manages its own LRU cache.
+ */
+declare class RoleStore {
+    private readonly collection;
+    private readonly cache;
+    constructor(collection: Collection<Role>, cache: LRUCache<string, Role>);
     /**
-     * Checks whether the session is linked to any task.
+     * Retrieves a role by its unique name.
      */
-    hasTask(workspace: Workspace): boolean;
+    get(name: string): Promise<Role | null>;
     /**
-     * Builds the active conversation chain (the current linear history) as an array
-     * of TurnNode objects, following the head pointer and parent links.
+     * Adds a new role to the collection.
      */
-    turns(): Promise<TurnNode[]>;
+    add(role: Role): Promise<void>;
     /**
-     * Returns all sibling turns of the given turn (other turns that share the same parent).
+     * Updates an existing role.
      */
-    siblings(turnId: UUID): Promise<TurnNode[]>;
+    update(name: string, updates: Partial<Role>): Promise<Role | null>;
     /**
-     * Returns version‑branching information for a given turn, including available versions,
-     * current index, and navigation capabilities.
+     * Deletes a role by name.
      */
-    branchInfo(turnId: UUID): Promise<BranchInfo>;
+    delete(name: string): Promise<boolean>;
     /**
-     * Retrieves a single turn node by its ID from the session graph.
+     * Lists all roles.
      */
-    getTurn(turnId: UUID): Promise<TurnNode | undefined>;
+    list(): Promise<Role[]>;
+}
+
+declare class SessionStore {
+    private readonly collection;
+    private readonly cache;
+    constructor(collection: Collection<SessionMetadata>, cache: LRUCache<UUID, SessionMetadata>);
+    get(id: UUID): Promise<SessionMetadata | null>;
+    add(session: SessionMetadata): Promise<void>;
+    update(id: UUID, updates: Partial<SessionMetadata>): Promise<SessionMetadata | null>;
+    delete(id: UUID): Promise<boolean>;
+}
+
+declare class TopicStore {
+    private readonly collection;
+    private readonly cache;
+    constructor(collection: Collection<Topic>, cache: LRUCache<string, Topic>);
+    get(name: string): Promise<Topic | null>;
+    add(topic: Topic): Promise<void>;
+    update(name: string, updates: Partial<Topic>): Promise<Topic | null>;
+    delete(name: string): Promise<boolean>;
+    getMany(names: string[]): Promise<Topic[]>;
     /**
-     * Changes the session's display label.
-     * @param workspace Current workspace state.
-     * @param newLabel New human‑readable label.
-     * @returns A patch to merge into the workspace state.
+     * Checks if a topic is referenced by any entity in the workspace index.
      */
-    rename(workspace: Workspace, newLabel: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    referencedBy(name: string, index: Index): boolean;
+}
+
+declare class TurnStore {
+    private readonly collection;
+    private readonly cache;
+    constructor(collection: Collection<Turn>, cache: LRUCache<string, Document<Turn>>);
+    private key;
+    private find;
+    get(key: {
+        id: UUID;
+        session: UUID;
+        version: number;
+    }): Promise<Turn | null>;
+    add(turn: Turn): Promise<void>;
+    update(key: TurnKey, updates: Partial<Turn>): Promise<Turn | null>;
+    listBySession(sessionId: UUID): Promise<Turn[]>;
+    delete(key: TurnKey): Promise<boolean>;
+}
+
+interface WorkspaceDatabase {
     /**
-     * Replaces the session's topic list entirely.
-     * @param workspace Current workspace state.
-     * @param topics New array of topics (overwrites existing).
-     * @returns A patch to merge into the workspace state.
+     * 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.
      */
-    setTopics(workspace: Workspace, topics: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    open(extensionSchemas?: SchemaDefinition[]): Promise<void>;
     /**
-     * Adds topics to the session (union, no duplicates).
-     * @param workspace Current workspace state.
-     * @param topics Topics to add.
-     * @returns A patch to merge into the workspace state.
+     * Access a collection by schema name.
+     * Throws if the schema has not been registered.
      */
-    addTopics(workspace: Workspace, topics: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    collection<T>(schemaName: string): Promise<Collection<T>>;
     /**
-     * Replaces the session's preference override list entirely.
-     * @param workspace Current workspace state.
-     * @param preferenceIds New array of preference IDs.
-     * @returns A patch to merge into the workspace state.
+     * Close the database connection.
      */
-    setPreferences(workspace: Workspace, preferenceIds: UUID[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    close(): void;
+    /** get the underlying database connection. */
+    database(): Database;
+}
+declare function createWorkspaceDatabase(db: Database): WorkspaceDatabase;
+/**
+ * Collection name constants
+ * Defines the names of the collections used in the Workspace database.
+ * Use these instead of raw strings throughout the codebase so a typo is a
+ * compile-time error rather than a silent runtime miss.
+ */
+declare const COLLECTIONS: {
+    readonly ROLE: "role";
+    readonly PREFERENCE: "preference";
+    readonly CONTEXT: "context";
+    readonly SESSION: "session";
+    readonly TURN: "turn";
+    readonly BLOB: "blob";
+    readonly TOPIC: "topic";
+};
+type Collections = typeof COLLECTIONS[keyof typeof COLLECTIONS];
+
+/**
+ * The full set of stores passed to every reducer and middleware call.
+ * Applications extend this with their own stores (e.g., `interface AppContext extends WorkspaceContext`).
+ */
+interface WorkspaceContext {
+    /** Store for managing system personas and roles. */
+    roles: RoleStore;
+    /** Store for managing global and session-level user preferences. */
+    preferences: PreferenceStore;
+    /** Store for managing RAG-retrievable context entries. */
+    context: ContextStore;
+    /** Store for managing active and archived conversation sessions. */
+    sessions: SessionStore;
+    /** Store for managing topic metadata and indexing. */
+    topics: TopicStore;
+    /** Store for managing blob binary data and references. */
+    blobs: BlobStore;
+    /** Store for managing conversation turns and history. */
+    turns: TurnStore;
+    /** Optional registry for managing available tools. */
+    tools?: ToolRegistry;
+    /** The current state of the workspace. */
+    workspace: Workspace;
+    /** The underlying database used by the workspace */
+    db: WorkspaceDatabase;
+}
+/**
+ * Ranks and filters context entries by relevance to the current conversation.
+ * The default implementation uses token overlap and recency weighting, but
+ * applications may substitute embedding-based or hybrid retrieval.
+ */
+interface ContextRetriever {
+    /**
+     * Ranks context entries by relevance to the current conversation.
+     *
+     * @param input - The payload containing entries to rank and context signals.
+     * @param input.entries - All context entries available for this session.
+     * @param input.recentMessages - Recent user message texts used as the query.
+     * @param input.topics - Topics related to this session.
+     * @param input.config - Optional retriever-specific configuration.
+     * @returns Ranked context entries, most relevant first.
+     */
+    rank(input: {
+        entries: Context[];
+        recentMessages: string[];
+        topics: string[];
+        config?: Record<string, any>;
+    }): Context[];
+}
+/**
+ * Configuration options for the PromptBuilder execution.
+ */
+interface PromptBuilderOptions {
     /**
-     * Links the session to a task, or removes the link if taskId is null.
-     * @param workspace Current workspace state.
-     * @param taskId ID of the task to link, or null to unlink.
-     * @returns A patch to merge into the workspace state.
+     * Forwarded to ContextRetriever.rank(). Use to tune retrieval behaviour per-call.
      */
-    setActiveTask(workspace: Workspace, taskId: UUID | null): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    retrieverConfig?: Record<string, any>;
     /**
-     * Removes the link between the session and its current task (if any).
-     * @param workspace Current workspace state.
-     * @returns A patch to merge into the workspace state.
+     * When true, PromptBuilder will call the Summarizer to compress old turns before returning the Prompt.
      */
-    unsetTask(workspace: Workspace): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    summarize?: boolean;
+}
+/**
+ * Transforms a SessionSnapshot into a standardized Prompt.
+ * Extracts messages, ranks context, resolves blob references, and handles preference conflicts.
+ * The produced Prompt contains the full resolved data, delegating token truncation to the LLMAdapter.
+ */
+interface PromptBuilder {
     /**
-     * Creates a new session as a fork (copy) of this one.
-     * @param workspace Current workspace state.
-     * @param newSessionId Unique ID for the new session.
-     * @param label Display label for the new session.
-     * @param role Optional role override (defaults to current role).
-     * @param topics Optional topic override (defaults to current topics).
-     * @returns A patch to merge into the workspace state.
+     * Builds a standardized Prompt from a SessionSnapshot.
+     *
+     * @param snapshot - Raw session data assembled by Session.
+     * @param ctx - WorkspaceContext for blob and context store access.
+     * @param options - Optional retriever and summarizer configuration.
+     * @returns A Result containing the fully resolved Prompt or a WorkspaceError.
      */
-    fork(workspace: Workspace, newSessionId: UUID, label: string, role?: string, topics?: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    build(snapshot: SessionSnapshot, ctx: WorkspaceContext, options?: PromptBuilderOptions): Promise<Result<Prompt, WorkspaceError>>;
+}
+/**
+ * Bridge between a Prompt and a specific LLM provider's SDK.
+ * Owns all model-specific decisions including truncation, token budgeting, formatting, and serialisation.
+ *
+ * @template TRequestParams - Extra params the caller passes to resolve() (e.g. model name, temperature).
+ */
+interface LLMAdapter<TRequestParams extends Record<string, any> = {}> {
     /**
-     * Permanently deletes this session and all its turns from the workspace.
-     * @param workspace Current workspace state.
-     * @returns A patch to merge into the workspace state.
+     * Returns the current state of the adapter. Callable at any time without a prompt.
+     *
+     * @returns The adapter's status, including context windows and rate limits.
      */
-    delete(workspace: Workspace): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
-    dispatch(workspace: Workspace, command: Command): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    status(): Promise<AdapterStatus>;
     /**
-     * Switches the session to a different role.
-     * @param workspace Current workspace state.
-     * @param newRole Name of the target role (must exist in the workspace).
-     * @returns A patch to merge into the workspace state.
+     * Processes a Prompt into a PreparedPrompt — the complete, final representation of what the model will receive.
+     *
+     * @param params - The input prompt and any additional provider-specific parameters.
+     * @returns The prepared, executable prompt bound to the provider's SDK.
      */
-    switchRole(workspace: Workspace, newRole: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    resolve(params: {
+        prompt: Prompt;
+    } & TRequestParams): Promise<PreparedPrompt>;
+}
+/**
+ * Analyzes assistant turn output for workspace side effects.
+ * Implementations scan blocks and emit Commands that the Session dispatches.
+ */
+interface TurnProcessor {
     /**
-     * Returns all available roles in the workspace.
+     * Scans an assistant turn for actionable blocks.
+     *
+     * @param turn - The turn containing blocks to process.
+     * @param sessionId - The UUID of the session the turn belongs to.
+     * @returns Commands to dispatch against the workspace.
      */
-    listRoles(workspace: Workspace): RoleSummary[];
+    process(turn: {
+        blocks: BaseContentBlock<string>[];
+    }, sessionId?: UUID): BaseCommand[];
+}
+/**
+ * Compresses old transcript turns to reclaim token budget.
+ */
+interface Summarizer {
     /**
-     * Returns a specific role by name, or undefined if not found.
+     * Compresses older turns into a summary string.
+     *
+     * @param transcript - The full array of turns to evaluate.
+     * @param tokenBudget - The maximum allowed tokens for the context window.
+     * @returns The generated summary string and the uncompressed remaining turns.
      */
-    getRole(workspace: Workspace, name: string): RoleSummary | undefined;
+    summarize(transcript: Turn[], tokenBudget: number): Promise<{
+        summary: string;
+        remaining: Turn[];
+    }>;
+}
+/**
+ * Manages the registration, tracking, and execution of AI tools.
+ */
+interface ToolRegistry {
     /**
-     * Creates a new role.
-     * @param workspace Current workspace state.
-     * @param name Unique identifier for the role (e.g., "software-architect").
-     * @param label Human-readable display label.
-     * @param persona The system prompt / instructions for this role.
-     * @param description Optional description.
-     * @param preferenceIds Optional array of preference IDs to associate.
-     * @returns A patch to merge into the workspace state.
+     * Subscribes to changes in the tool registry.
+     * @param callback - Triggered with the updated list of tool summaries.
      */
-    createRole(workspace: Workspace, name: string, label: string, persona: string, description?: string, preferenceIds?: UUID[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    onRegistryChanged(callback: (tools: ToolSummary[]) => void): void;
     /**
-     * Updates an existing role.
-     * @param workspace Current workspace state.
-     * @param name Name of the role to update (must exist).
-     * @param updates Partial updates (label, description, persona, preferences).
-     * @returns A patch to merge into the workspace state.
+     * Retrieves all currently registered tools.
+     * @returns An array of ToolSummary definitions.
      */
-    updateRole(workspace: Workspace, name: string, updates: Partial<Pick<Role, 'label' | 'description' | 'persona' | 'preferences'>>): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    list(): ToolSummary[];
     /**
-     * Deletes a role. Fails if the role is still referenced by any session.
-     * @param workspace Current workspace state.
-     * @param name Name of the role to delete.
-     * @returns A patch to merge into the workspace state.
+     * Executes a specific tool call request.
+     * @param call - The tool call payload with arguments.
+     * @returns A Result containing the tool's output.
      */
-    deleteRole(workspace: Workspace, name: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    execute<T = any>(call: ToolCall): Promise<Result<T>>;
+}
+/**
+ * Secures commands and tool executions by authenticating requests.
+ */
+interface PermissionGuard {
     /**
-     * Saves a constructed Turn object to the session. The turn's parent is automatically
-     * set to the current head of the active chain unless overridden in the turn object.
-     * @param workspace Current workspace state.
-     * @param turn The Turn object (can be built with startTurn()).
-     * @returns A patch to merge into the workspace state.
+     * Authenticates a request before execution.
+     * @param request - The authorization request containing a command or tool payload.
+     * @returns A Result with the authenticated payload or undefined if unhandled.
      */
-    addTurn(workspace: Workspace, turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
-    recordUserTurn(workspace: Workspace, turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
-    recordAssistantTurn(workspace: Workspace, turn: Turn, recordDenial?: boolean): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
-    private buildDenialTurn;
-    private describeCommand;
+    authenticate(request: AuthRequest): Promise<Result<null>>;
+}
+type BlobResolver = (ref: BlobRef, provider?: string) => Promise<Result<ResolvedBlob | null, WorkspaceError>>;
+
+declare class WorkspaceManager {
+    private registry;
+    private middlewares;
+    private serializer;
+    private bus;
+    private _getWorkspace;
+    private updateWorkspace;
+    private guard?;
+    private readonly _ctx;
+    constructor(params: {
+        ctx: Omit<WorkspaceContext, "workspace">;
+        getWorkspace: () => Workspace;
+        updateWorkspace: (workspace: DeepPartial<Workspace>) => Promise<void>;
+        guard?: PermissionGuard;
+        bus: EventBus<WorkspaceEvents>;
+    });
     /**
-     * Creates a new version of an existing turn with updated content.
-     * @param workspace Current workspace state.
-     * @param turnId ID of the turn to edit.
-     * @param newBlocks New content blocks for the turn.
-     * @param roleSnapshot Optional role name to record with this version.
-     * @returns A patch to merge into the workspace state.
+     * Registers a reducer for a specific command type.
+     * @param reducer The reducer function to handle the command.
+     * @returns The WorkspaceManager instance for chaining.
      */
-    editTurn(workspace: Workspace, turnId: UUID, newBlocks: ContentBlock[], roleSnapshot?: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    register(type: string, reducer: WorkspaceReducer): this;
     /**
-     * Creates a new branch from a specific turn (the parent must be set on the turn).
-     * @param workspace Current workspace state.
-     * @param turn The new turn that continues from an existing parent.
-     * @returns A patch to merge into the workspace state.
+     * Registers a middleware function.
+     * @param middleware The middleware function to apply.
+     * @returns The WorkspaceManager instance for chaining.
      */
-    branch(workspace: Workspace, turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    use(middleware: WorkspaceMiddleware): this;
     /**
-     * Deletes a specific version of a turn and all its descendants.
-     * @param workspace Current workspace state.
-     * @param turnId ID of the turn to delete.
-     * @param version Version number of the turn to delete.
-     * @param newHead Optional new head pointer after deletion.
-     * @returns A patch to merge into the workspace state.
+     * Retrieves the current state of the workspace.
+     * @returns The current Workspace state.
      */
-    deleteTurn(workspace: Workspace, turnId: UUID, version: number, newHead: TurnRef | null): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    workspace(): Workspace;
     /**
-     * Switch to the previous version of a turn (if available).
-     * This changes the active chain head but does not create new data.
-     * @param workspace Current workspace state.
-     * @param turnId ID of the turn whose version to switch.
-     * @returns A patch to merge into the workspace state.
+     * Dispatches a command to modify the workspace state.
+     * It ensures commands are processed sequentially and applies middleware.
+     * @param command The command to dispatch.
+     * @returns A promise resolving to the DeepPartial<Workspace> representing the applied patch.
      */
-    switchVersionLeft(workspace: Workspace, turnId: UUID): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    dispatch(command: BaseCommand): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     /**
-     * Switch to the next version of a turn (if available).
-     * This changes the active chain head but does not create new data.
-     * @param workspace Current workspace state.
-     * @param turnId ID of the turn whose version to switch.
-     * @returns A patch to merge into the workspace state.
+     * Subscribes to workspace events.
+     * @param event The event name to subscribe to.
+     * @param listener The callback function to execute when the event is emitted.
+     * @returns unsubscribe
      */
-    switchVersionRight(workspace: Workspace, turnId: UUID): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
-    private switchVersion;
-    addPreference(workspace: Workspace, content: string, topics: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
-    listPreferences(workspace: Workspace): Promise<PreferenceSummary[]>;
-    addContext(workspace: Workspace, key: string, content: ContextContent, topics: string[], metadata?: Record<string, any>): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
-    listContextSummaries(workspace: Workspace): Promise<ContextSummary[]>;
-    /**
- * Registers a new blob in the workspace and returns its SHA256 and BlobRef.
- * This dispatches a blob:register command and extracts the resulting SHA256
- * from the returned workspace patch.
- */
-    registerBlob(workspace: Workspace, data: Uint8Array, mediaType: BlobMediaType, filename?: string): Promise<Result<{
+    subscribe<K extends keyof WorkspaceEvents>(event: K, listener: (payload: WorkspaceEvents[K]) => void): () => void;
+    ctx(): {
+        context: ContextStore;
+        roles: RoleStore;
+        preferences: PreferenceStore;
+        sessions: SessionStore;
+        topics: TopicStore;
+        blobs: BlobStore;
+        turns: TurnStore;
+        tools?: ToolRegistry | undefined;
+        db: WorkspaceDatabase;
+        workspace: Workspace<Record<string, any>>;
+    };
+}
+
+declare class WorkspaceApi {
+    private readonly manager;
+    constructor(manager: WorkspaceManager);
+    private get workspace();
+    roles(): Promise<Role[]>;
+    role(name: string): Promise<Role | null>;
+    createRole(name: string, label: string, persona: string, description?: string, preferenceIds?: UUID[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    updateRole(name: string, updates: Partial<Pick<Role, "label" | "description" | "persona" | "preferences">>): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    deleteRole(name: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    addPreference(content: string, topics: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    preferences(): Promise<Preference[]>;
+    addContext(key: string, content: ContextContent, topics: string[], metadata?: Record<string, any>): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    context(): Promise<Context[]>;
+    registerBlob(data: Uint8Array, mediaType: BlobMediaType, filename?: string): Promise<Result<{
         sha256: SHA256;
         ref: BlobRef;
     }, WorkspaceError>>;
+}
+
+declare class Session {
+    private readonly _id;
+    private readonly manager;
+    private readonly processor;
+    private readonly turnRepository;
+    /** Global workspace operations available under session.workspace */
+    readonly workspace: WorkspaceApi;
+    private _role;
+    private _preferences;
+    private tree;
+    private constructor();
+    static create(sessionId: UUID, manager: WorkspaceManager, processor: TurnProcessor): Promise<Session>;
+    private _setRole;
+    private _setPreference;
+    id(): UUID;
+    private ws;
+    meta(): SessionMetadata | undefined;
+    label(): string | undefined;
+    role(): Role | undefined;
+    topics(): string[];
+    preferences(): Preference[];
+    head(): TurnRef | null;
+    turns(): TurnNode[];
+    siblings(turnId: UUID): Promise<TurnNode[]>;
+    branchInfo(turnId: UUID): Promise<BranchInfo>;
+    getTurn(turnId: UUID): Promise<TurnNode | undefined>;
+    rename(newLabel: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    setTopics(topics: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    addTopics(topics: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    setPreferences(preferenceIds: UUID[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    fork(newSessionId: UUID, label: string, role?: string, topics?: string[]): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    dispatch(command: BaseCommand): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    switchRole(newRole: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    addTurn(turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    recordUserTurn(turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    recordAssistantTurn(turn: Turn, recordDenial?: boolean): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    private buildDenialTurn;
+    private describeCommand;
+    editTurn(turnId: UUID, newBlocks: ContentBlock[], roleSnapshot?: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    branch(turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    deleteTurn(turnId: UUID, version: number, newHead: TurnRef | null): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    switchVersionLeft(turnId: UUID): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    switchVersionRight(turnId: UUID): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    private switchVersion;
     /**
-     * Resolves the session into an EffectiveSession object, which bundles the
-     * session metadata, role, preferences, context, transcript, and linked task.
-     * @param workspace Current workspace state.
-     * @returns The resolved effective session or an error.
+     * Assembles a SessionSnapshot from in-memory state for PromptBuilder.
+     *
+     * This is the handoff point between Session (state management) and
+     * PromptBuilder (prompt preparation). Session's responsibility ends here.
+     *
+     * The only async step is loading context entries by topic from the store.
+     * Role and preferences are already in memory from open().
+     *
+     * Returns undefined if the session no longer exists in the workspace index.
      */
-    resolve(workspace: Workspace): Promise<Result<EffectiveSession, WorkspaceError>>;
+    snapshot(): Promise<SessionSnapshot | undefined>;
+    private refreshTurnTree;
     private findSubtreeTip;
 }
 
-interface SessionManagerConfig {
-}
-interface OpenResult {
-    session: Session;
-    patch: DeepPartial<Workspace>;
-}
 declare class SessionManager {
-    private readonly workspaceManager;
-    private readonly contentStore;
-    constructor(workspaceManager: WorkspaceManager, contentStore: ContentStore);
-    /**
-     * Returns an array of all session metadata entries in the workspace.
-     */
-    list(workspace: Workspace): SessionMeta[];
-    /**
-     * Retrieves the metadata for a specific session without hydrating a Session object.
-     */
-    meta(workspace: Workspace, sessionId: UUID): SessionMeta | undefined;
-    /**
-     * Creates a new session and returns a hydrated Session instance.
-     * This method dispatches a 'session:create' command which is validated by the
-     * reducer (checking for unique IDs and valid roles) and persisted
-     * to the content store.
-     */
-    create(workspace: Workspace, params: {
+    private readonly manager;
+    private readonly processor;
+    private openOnce;
+    constructor(manager: WorkspaceManager, processor: TurnProcessor);
+    open(sessionId: UUID): Promise<Session>;
+    close(sessionId: UUID): void;
+    delete(sessionId: UUID): Promise<Result<undefined, WorkspaceError>>;
+    create(params: {
         label: string;
-        role?: string;
-        topics?: string[];
+        role: string;
+        topics: string[];
         preferences?: UUID[];
-    }): Promise<Result<OpenResult, WorkspaceError>>;
-    open(workspace: Workspace, sessionId: UUID): Promise<Result<OpenResult, WorkspaceError>>;
-    get workspace(): WorkspaceManager;
-    close(_: Session): Promise<void>;
+    }): Promise<Session>;
+    list(): SessionMetadata[];
+    metadata(sessionId: UUID): SessionMetadata | undefined;
 }
 
 /**
- * In-process implementation backed by plain Maps.
- * Suitable for development, testing, and server-side runtimes without
- * access to IndexedDB.
+ * A fluent builder for creating Turn objects.
+ * This class helps construct a Turn object by adding various content blocks.
  */
-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>;
+declare class TurnBuilder {
+    private readonly _actor;
+    private _turn;
+    constructor(_actor: SystemActor, session: string, initialTurn?: Turn);
+    addText(text: string): TurnBuilder;
+    addImage(ref?: BlobRef, altText?: string): TurnBuilder;
+    addDocument(ref?: BlobRef, title?: string): TurnBuilder;
+    addToolUse(name: string, input: Record<string, unknown>): TurnBuilder;
+    addToolResult(useId: UUID, content: string | Record<string, unknown>, isError?: boolean): TurnBuilder;
+    addSummary(text: string): TurnBuilder;
+    addRoleTransition(previousRole: string | undefined, newRole: string): TurnBuilder;
+    addThinking(thinking: string): TurnBuilder;
+    addBlock(block: ContentBlock): TurnBuilder;
+    deleteBlock(blockId: UUID): TurnBuilder;
+    editTextBlock(blockId: UUID, newText: string): TurnBuilder;
+    withId(id: UUID): TurnBuilder;
+    withVersion(version: number): TurnBuilder;
+    withTimestamp(timestamp: Timestamp): TurnBuilder;
+    withParent(parent: TurnRef): TurnBuilder;
+    withRoleSnapshot(roleSnapshot: string): TurnBuilder;
+    build(): Turn;
+}
+
+declare class TurnRepository {
+    private readonly turnStore;
+    private readonly sessionStore;
+    constructor(turnStore: TurnStore, sessionStore: SessionStore);
+    loadAllTurns(sessionId: UUID): Promise<Turn[]>;
+    loadHead(sessionId: UUID): Promise<TurnRef | null>;
 }
 
-interface IndexedDBBlobConfig {
-    /** Name of the IndexedDB database. Defaults to 'aiworkspace-blobs'. */
-    dbName?: string;
+declare class TurnTree {
+    private readonly nodes;
+    private readonly _head;
+    private constructor();
+    static build(sessionId: UUID, repository: TurnRepository): Promise<TurnTree>;
+    head(): TurnRef | null;
+    chain(): TurnNode[];
+    getTurnSiblings(turnId: UUID): TurnNode[];
+    branchInfo(turnId: UUID): BranchInfo;
+    graph(): Readonly<Record<UUID, TurnNode>>;
 }
+
+declare function success<T>(value: T): Result<T, never>;
+declare function ok<T>(value: T): Result<T, never>;
+declare function error<E extends WorkspaceError>(err: E): Result<never, E>;
+declare function omitNullUndefined<T extends Record<string, any>>(obj: T): Partial<T>;
+declare function del<T>(): T;
+declare const merge: <T extends object>(original: T, changes: DeepPartial<T> | symbol) => T;
+declare function computeSHA256(data: Uint8Array): Promise<SHA256>;
 /**
- * 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.
+ * Converts a Uint8Array to a Base64 string.
+ * Uses native Buffer in Node.js/Deno, and falls back to a chunked btoa()
+ * implementation for Browsers and Edge environments to avoid stack overflows.
  */
-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>;
-}
+declare function bufferToBase64(buffer: Uint8Array): string;
 
-declare class GoogleGenAIAdapter implements LLMAdapter<{
-    model: string;
-}, GenerateContentParameters, GenerateContentResponse> {
-    private _;
-    constructor(_: GoogleGenAI);
-    /**
-     * Converts a Prompt into a GenerateContentRequest for @google/genai.
-     */
-    prepare({ prompt, model }: {
-        prompt: Prompt;
-        model: string;
-    }): Promise<{
-        request: {
-            model: string;
-            contents: _google_genai.Content[];
-            config: {
-                systemInstruction: _google_genai.Content;
-                thinkingConfig: {
-                    includeThoughts: boolean;
-                };
-                responseMimeType: string;
-                responseSchema: _google_genai.Schema;
-            };
-        };
-    }>;
-    /**
-     * Parses the GenerateContentResponse into a Turn (assistant turn).
-     */
-    parse({ response }: {
-        response: GenerateContentResponse;
-    }): Result<Turn, WorkspaceError>;
+interface CreateWorkspaceParams {
+    db: Database;
+    blobStorage: BlobStorage;
+    eventBus?: EventBus<WorkspaceEvents>;
+    getWorkspace: () => Workspace;
+    setWorkspace: (workspace: DeepPartial<Workspace>) => Promise<void>;
+    processor: TurnProcessor;
+    guard?: PermissionGuard;
+    toolRegistry?: ToolRegistry;
+    extensionSchemas?: SchemaDefinition[];
+    extensionReducers?: Record<string, WorkspaceReducer<any>>;
+    extensionMiddleware?: WorkspaceMiddleware[];
 }
+/**
+ * Boot factory for the Workspace library.
+ * Resolves all collections and initializes entity stores.
+ */
+declare function createWorkspace(params: CreateWorkspaceParams): Promise<{
+    manager: WorkspaceManager;
+    sessions: SessionManager;
+    ctx: Omit<WorkspaceContext, "workspace">;
+}>;
 
-export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTask, type AddTurn, type AuthRequest, type BackendError, type BaseCommand, type BlobCommand, type BlobError, type BlobMediaType, type BlobRecord, type BlobRef, type BlobStorage, BlobStore, type BlobStoreConfig, type BranchInfo, type BranchTurn, COLLECTIONS, type CallTool, type CollectionName, type Command, type ContentBlock, ContentStore, type Context, type ContextContent, type ContextSummary, type CreateSession, type CreateWorkspace, DefaultTurnProcessor, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTask, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type DuplicateKeyError, EMPTY_SYSTEM_ROLE, type EditTurn, type EffectiveSession, type ForkSession, GoogleGenAIAdapter, type ImageBlock, type ImageMediaType, type Index, type IndexedDBBlobConfig, IndexedDBBlobStorage, type InvalidCommandError, type LLMAdapter, MemoryBlobStorage, type NotFoundError, type OpenResult, type OverrideSessionPreferences, type PermissionDeniedError, type PermissionGuard, 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, type SaveTurn, Session, SessionManager, type SessionManagerConfig, type SessionMeta, type Settings, type Summarizer, type SummaryBlock, type SwitchRole, type Task, type TaskProposalBlock, type TaskRef, type TaskStatus, type TaskStep, type TaskSummary, type TextBlock, type ThinkingBlock, type Timestamp, type TokenBudget, type ToolCall, type ToolRegistry, type ToolResultBlock, type ToolSummary, type ToolUseBlock, type TopicIndex, type Turn, type TurnActor, TurnBuilder, type TurnNode, type TurnProcessor, type TurnRef, TurnTree, type URI, type UUID, type UpdateContext, type UpdatePreference, type UpdateRole, type UpdateSession, type UpdateTask, type Workspace, type WorkspaceBundle, type WorkspaceDatabase, type WorkspaceError, type WorkspaceEvents, WorkspaceManager, bufferToBase64, computeSHA256, createEmptyRole, createProjectWorkspace, createSimpleWorkspace, createWorkspaceDatabase, del, error, extractBlobRecord, extractBlobRef, generateTaskRef, generateTaskStepRef, merge, omitNullUndefined, shortHash, success };
+export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTopic, type AddTurn, type AuthRequest, type BackendError, type BaseCommand, type BaseContentBlock, type BlobCommand, type BlobError, type BlobMediaType, type BlobRecord, type BlobRef, type BlobResolver, type BranchInfo, type BranchTurn, COLLECTIONS, type Collections, type Command, type ContentBlock, type Context, type ContextContent, type ContextRetriever, type ContextSummary, type CreateSession, type CreateWorkspace, type CreateWorkspaceParams, type DeepPartial, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTopic, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type DuplicateKeyError, EMPTY_SYSTEM_ROLE, type EditTurn, type ForkSession, type ImageBlock, type ImageMediaType, type Index, type InvalidCommandError, type LLMAdapter, LRUCache, type MergeTopics, type ModelConstraint, type ModelConstraintMap, type ModelName, type NotFoundError, type OverrideSessionPreferences, type PermissionDeniedError, type PermissionGuard, type Preference, type PreferenceSummary, type Project, type PromptBuilder, type PromptBuilderOptions, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type ResolvedBlob, type ResolvedSession, type Result, type RetainBlob, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, Session, SessionManager, type SessionMetadata, type SessionSnapshot, type Settings, type Summarizer, type SummaryBlock, type SwitchSessionRole, type SystemActor, type TextBlock, type ThinkingBlock, type Timestamp, type ToolCall, type ToolCallCommand, type ToolRegistry, type ToolResultBlock, type ToolSummary, type ToolUseBlock, type Topic, type TopicIndex, type Turn, TurnBuilder, type TurnKey, type TurnNode, type TurnProcessor, type TurnRef, TurnTree, type URI, type UUID, type UpdateContext, type UpdatePreference, type UpdateRole, type UpdateSession, type UpdateTopic, type UpdateTurn, type Workspace, type WorkspaceBundle, type WorkspaceContext, type WorkspaceDatabase, type WorkspaceError, type WorkspaceEvents, WorkspaceManager, type WorkspaceMiddleware, type WorkspaceReducer, bufferToBase64, computeSHA256, createWorkspace, createWorkspaceDatabase, del, error, merge, ok, omitNullUndefined, success };