@asaidimu/utils-workspace 2.1.0 → 3.0.0

package/index.d.mts

@@ -1,5 +1,17 @@
 import { QueryFilter, PaginationOptions } from '@asaidimu/query';
-import { SchemaDefinition, SchemaChange, DataTransform } from '@asaidimu/anansi';
+import { IndexDefinition, SchemaDefinition, SchemaChange, DataTransform } from '@asaidimu/anansi';
+import { EventBus } from '@asaidimu/events';
+
+/**
+ * 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;
 
 type UUID = string;
 type Timestamp = string;
@@ -12,35 +24,38 @@ type Result<T, E = WorkspaceError> = {
     ok: false;
     error: E;
 };
-type WorkspaceError = {
+type DuplicateKeyError = {
     code: 'DUPLICATE_KEY';
     resource: string;
     key: string;
-} | {
+};
+type NotFoundError = {
     code: 'NOT_FOUND';
     resource: string;
     id: string;
-} | {
+};
+type InvalidCommandError = {
     code: 'INVALID_COMMAND';
     reason: string;
-} | {
+};
+type BackendError = {
     code: 'BACKEND_ERROR';
     reason: string;
-} | {
+};
+type BlobError = {
     code: 'BLOB_ERROR';
     reason: string;
 };
+type WorkspaceError = DuplicateKeyError | NotFoundError | InvalidCommandError | BackendError | BlobError;
 interface Settings {
     language: string;
     defaultRole?: string;
     prompt?: string;
 }
-interface Project {
+type Project<Metadata extends Record<string, any> = Record<string, any>> = Metadata & {
+    id: UUID;
     name: string;
-    owner: string;
-    repository?: string;
-    metadata?: Record<string, any>;
-}
+};
 type ImageMediaType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
 type DocumentMediaType = 'application/pdf' | 'application/json' | 'text/plain' | 'text/html' | 'text/markdown' | 'text/csv' | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
 type BlobMediaType = ImageMediaType | DocumentMediaType;
@@ -78,59 +93,104 @@ interface BlobRecord {
     lastUsedAt: Timestamp;
 }
 interface TextBlock {
+    id: UUID;
     type: 'text';
     text: string;
 }
 interface ImageBlock {
+    id: UUID;
     type: 'image';
     ref?: BlobRef;
     blob?: ResolvedBlob;
     altText?: string;
 }
 interface DocumentBlock {
+    id: UUID;
     type: 'document';
     ref?: BlobRef;
     blob?: ResolvedBlob;
     title?: string;
 }
+interface TaskProposalBlock {
+    id: UUID;
+    taskId?: UUID;
+    type: 'task:proposal';
+    title: string;
+    steps: {
+        id?: UUID;
+        text: string;
+        status: 'todo' | 'done';
+    }[];
+    action: 'create' | 'update' | 'complete';
+}
 interface ToolUseBlock {
-    type: 'tool_use';
-    toolUseId: string;
+    id: UUID;
+    type: 'tool:use';
     name: string;
     input: Record<string, unknown>;
 }
 interface ToolResultBlock {
-    type: 'tool_result';
-    toolUseId: string;
+    id: UUID;
+    type: 'tool:result';
+    useId: UUID;
     content: string | Record<string, unknown>;
     isError?: boolean;
 }
 interface ThinkingBlock {
+    id: UUID;
     type: 'thinking';
     thinking: string;
 }
 interface SummaryBlock {
+    id: UUID;
     type: 'summary';
     text: string;
 }
 interface RoleTransitionBlock {
-    type: 'role_transition';
+    id: UUID;
+    type: 'role:transition';
     previousRole: string | null;
     newRole: string;
 }
-type ContentBlock = TextBlock | ImageBlock | DocumentBlock | ToolUseBlock | ToolResultBlock | SummaryBlock | RoleTransitionBlock | ThinkingBlock;
+type ContentBlock = TextBlock | ImageBlock | DocumentBlock | ToolUseBlock | ToolResultBlock | SummaryBlock | RoleTransitionBlock | ThinkingBlock | TaskProposalBlock;
+interface ToolSummary {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, any>;
+        required: string[];
+    };
+    /**
+     * The semantic tags for this tool.
+     * Used by the ContextRetriever to filter relevance.
+     */
+    topics: string[];
+}
+interface ToolCall {
+    id: UUID;
+    tool: UUID;
+    arguments: Record<string, any>;
+}
+type AuthRequest = {
+    type: 'command';
+    payload: Command;
+} | {
+    type: 'tool';
+    payload: ToolCall;
+};
 type TurnRole = 'user' | 'assistant' | 'tool';
 interface Turn {
     id: UUID;
     version: number;
-    role: TurnRole;
+    owner: TurnRole;
     blocks: ContentBlock[];
     timestamp: Timestamp;
     /**
      * The name of the role active when this turn was recorded.
      * Snapshot so history is stable even if the role is later renamed.
      */
-    roleSnapshot?: string;
+    role?: string;
     /**
      * Parent pointer. Null for root turns.
      * This is plain data stored on the document — the DAG is reconstructed
@@ -224,6 +284,24 @@ interface SessionMeta {
         id: UUID;
         version: number;
     } | null;
+    task: UUID | null;
+}
+type TaskStatus = 'todo' | 'active' | 'done' | 'blocked' | 'defered';
+interface TaskStep {
+    id: UUID;
+    text: string;
+    completed?: Timestamp;
+}
+interface Task {
+    id: UUID;
+    title: string;
+    description?: string;
+    status: TaskStatus;
+    steps: TaskStep[];
+    topics: string[];
+    metadata?: Record<string, any>;
+    created: Timestamp;
+    updated: Timestamp;
 }
 interface RoleSummary {
     name: string;
@@ -248,10 +326,21 @@ interface ContextSummary {
     source?: string;
     metadata?: Record<string, any>;
 }
+interface TaskSummary {
+    id: UUID;
+    title: string;
+    status: TaskStatus;
+    steps: {
+        completed: number;
+        total: number;
+    };
+    topics: string[];
+}
 interface TopicIndex {
     topic: string;
     contextKeys: string[];
     preferences: UUID[];
+    tasks: UUID[];
     metadata?: {
         created?: Timestamp;
         updated?: Timestamp;
@@ -263,13 +352,15 @@ interface Index {
     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>;
 }
-interface Workspace {
+interface Workspace<ProjectMetadata extends Record<string, any> = Record<string, any>> {
     id: UUID;
     settings: Settings;
-    project: Project;
+    project: Project<ProjectMetadata>;
     index: Index;
 }
 interface WorkspaceBundle {
@@ -281,6 +372,7 @@ interface WorkspaceBundle {
     sessions: Record<UUID, SessionMeta & {
         turns: Turn[];
     }>;
+    tasks: Record<UUID, Task>;
     blobs: Record<SHA256, BlobRecord>;
 }
 interface EffectiveSession {
@@ -289,12 +381,14 @@ interface EffectiveSession {
     preferences: Preference[];
     context: Context[];
     transcript: Turn[];
+    task: Task | null;
     instructions?: string;
 }
 interface CacheConfig {
     roles?: number;
     preferences?: number;
     context?: number;
+    tasks?: number;
 }
 interface FlushConfig {
     maxBufferSize: number;
@@ -375,6 +469,29 @@ interface DeleteContext extends BaseCommand {
         key: string;
     };
 }
+interface AddTask extends BaseCommand {
+    type: 'task:add';
+    payload: Task;
+}
+interface UpdateTask extends BaseCommand {
+    type: 'task:update';
+    payload: Partial<Task> & {
+        id: UUID;
+    };
+}
+interface DeleteTask extends BaseCommand {
+    type: 'task:delete';
+    payload: {
+        id: UUID;
+    };
+}
+interface SaveTurn extends BaseCommand {
+    type: 'turn:save';
+    payload: {
+        sessionId: UUID;
+        turn: Turn;
+    };
+}
 interface AddTurn extends BaseCommand {
     type: 'turn:add';
     payload: {
@@ -396,21 +513,20 @@ interface BranchTurn extends BaseCommand {
     type: 'turn:branch';
     payload: {
         sessionId: UUID;
-        parentTurnId: UUID;
-        parentVersion: number;
-        newTurn: Turn;
+        turn: Turn;
     };
 }
+interface TurnRef {
+    id: UUID;
+    version: number;
+}
 interface DeleteTurn extends BaseCommand {
     type: 'turn:delete';
     payload: {
         sessionId: UUID;
         turnId: UUID;
         version: number;
-        newHead: {
-            id: UUID;
-            version: number;
-        } | null;
+        newHead: TurnRef | null;
     };
 }
 interface SwitchRole extends BaseCommand {
@@ -485,7 +601,11 @@ interface RecordBlobRemoteId extends BaseCommand {
     };
 }
 type BlobCommand = RegisterBlob | RetainBlob | ReleaseBlob | PurgeBlob | RecordBlobRemoteId;
-type Command = CreateWorkspace | AddRole | UpdateRole | DeleteRole | AddPreference | UpdatePreference | DeletePreference | CreateSession | AddContext | UpdateContext | DeleteContext | AddTurn | EditTurn | BranchTurn | DeleteTurn | SwitchRole | AddSessionTopics | OverrideSessionPreferences | ForkSession | DeleteSession | BlobCommand;
+interface CallTool extends BaseCommand {
+    type: 'tool:call';
+    payload: ToolCall;
+}
+type Command = CreateWorkspace | AddRole | UpdateRole | DeleteRole | AddPreference | UpdatePreference | DeletePreference | CreateSession | AddContext | UpdateContext | DeleteContext | AddTask | UpdateTask | DeleteTask | AddTurn | SaveTurn | EditTurn | BranchTurn | DeleteTurn | SwitchRole | AddSessionTopics | OverrideSessionPreferences | ForkSession | DeleteSession | BlobCommand | CallTool;
 interface TokenBudget {
     total: number;
     estimator?: (text: string) => number;
@@ -514,6 +634,7 @@ interface Prompt {
         persona: string;
         preferences: Preference[];
         context: Context[];
+        task: Task | null;
     };
     context: Context[];
     transcript: {
@@ -538,15 +659,86 @@ interface TranscriptWindow {
     flushedCount: number;
     hasMore: boolean;
 }
+interface WorkspaceEvents {
+    'workspace:changed': DeepPartial<Workspace>;
+    'blobs:changed': {
+        sha256: SHA256;
+        record: BlobRecord | null;
+    };
+}
 
+/**
+ * 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;
-    private buffer;
-    private committed;
+    /**
+     * 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();
-    addOp(store: Store<any>, type: "put" | "delete", data: any): void;
+    /**
+     * 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> {
@@ -560,8 +752,9 @@ interface CursorCallbackResult<T> {
  * @template T - The type of records stored.
  * @param value - The current record value (cloned, not a live reference).
  * @param key - The key (ID) of the current record.
- * @param cursor - The underlying cursor object (implementation‑specific; may be `null` in memory adapters).
- * @returns A promise that resolves to an object indicating whether iteration should stop, and an optional offset to advance.
+ * @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>>;
 /**
@@ -573,123 +766,100 @@ interface StoreKeyRange {
     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).
  *
- * This interface abstracts all low‑level persistence operations, allowing
- * different backends (IndexedDB, memory, remote, etc.) to be used interchangeably.
- * All methods return promises and operate on clones of data to prevent
- * unintended mutations.
+ * 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 in this store. Must include the key path property.
+ * @template T - The type of objects stored. Must include the key path property.
  */
-interface Store<T = 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 (e.g., auto‑incremented number) may be assigned. The store's key path
-     * property is then updated on the added record(s).
-     *
-     * @param data - A single record or an array of records to add.
-     * @returns A promise that resolves to:
-     *   - the key(s) of the added record(s) – a single key if `data` was a single record,
-     *     or an array of keys if `data` was an array.
-     * @throws {Error} If any record lacks the key path property and auto‑keying is not supported,
-     *                 or if a record with the same key already exists.
+     * 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.
-     *
-     * @returns A promise that resolves when the store is cleared.
-     * @throws {Error} If the operation fails (e.g., store is closed).
+     * Removes all records from the store without destroying index structures.
      */
     clear(): Promise<void>;
     /**
      * Returns the total number of records in the store.
-     *
-     * @returns A promise that resolves to the record count.
-     * @throws {Error} If the operation fails.
      */
     count(): Promise<number>;
     /**
      * Deletes one or more records by their keys.
-     *
-     * @param id - A single key or an array of keys to delete.
-     * @returns A promise that resolves when the records are deleted.
-     * @throws {Error} If any key is `undefined` or the operation fails.
      */
     delete(id: string | number | (string | number)[]): Promise<void>;
     /**
      * Retrieves a single record by its primary key.
-     *
-     * @param id - The key of the record to retrieve.
-     * @returns A promise that resolves to the record (cloned) if found, otherwise `undefined`.
-     * @throws {Error} If the key is `undefined` or the operation fails.
      */
     getById(id: string | number): Promise<T | undefined>;
     /**
-     * Retrieves a single record by an index and index key.
+     * Retrieves the first record matching an exact index key (point lookup).
+     * Useful for unique indexes — returns the single matching record or undefined.
      *
-     * @param index - The name of the index to query.
-     * @param key - The exact key value to look up in the index.
-     * @returns A promise that resolves to the first matching record (cloned), or `undefined` if none.
-     * @throws {Error} If the index does not exist, the key is `undefined`, or the operation fails.
+     * @param indexName - The name of the index to query.
+     * @param key - The exact key value to look up.
      */
-    getByIndex(index: string, key: any): Promise<T | undefined>;
+    getByIndex(indexName: string, key: any): Promise<T | undefined>;
     /**
-     * Retrieves multiple records from an index, optionally within a key range.
+     * 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 index - The name of the index to query.
-     * @param keyRange - Optional `StoreKeyRange` to filter results. If omitted, all records are returned.
-     * @returns A promise that resolves to an array of matching records (each cloned).
-     * @throws {Error} If the index does not exist or the operation fails.
+     * @param indexName - The name of the index to query.
+     * @param keyRange - Optional range to filter results.
      */
-    getByKeyRange(index: string, keyRange?: StoreKeyRange): Promise<T[]>;
+    getByKeyRange(indexName: string, keyRange?: StoreKeyRange): Promise<T[]>;
     /**
-     * Retrieves all records from the store.
-     *
-     * @returns A promise that resolves to an array of all records (each cloned).
-     * @throws {Error} If the operation fails.
+     * Retrieves all records from the store without index involvement.
      */
     getAll(): Promise<T[]>;
     /**
-     * Inserts or replaces a record.
-     *
-     * If a record with the same key already exists, it is replaced.
-     * The record must contain the store's key path property.
-     *
-     * @param data - The record to store.
-     * @returns A promise that resolves to the key of the stored record.
-     * @throws {Error} If the record lacks the key path property or the operation fails.
+     * 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.
      *
-     * The callback is invoked for each record in iteration order. The callback
-     * can control the iteration by returning `{ done: true }` to stop, or
-     * `{ offset: n }` to skip ahead `n` records.
-     *
-     * @param callback - Function called for each record.
-     * @param direction - Iteration direction: `"forward"` (ascending keys) or `"backward"` (descending keys).
-     * @param keyRange - An optional StoreKeyRange to start from specific points.
-     * @returns A promise that resolves to the last record processed (or `null` if none).
-     * @throws {Error} If the callback throws or the operation fails.
+     * @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.
-     *
-     * All operations in the batch succeed or fail together. This is useful for
-     * maintaining consistency when multiple writes are required.
+     * Executes a batch of write operations atomically within this store.
+     * All operations succeed or fail together.
      *
-     * @param operations - An array of operations. Each operation can be:
-     *   - `{ type: "add" | "put", data: T | T[] }`
-     *   - `{ type: "delete", data: string | number | (string | number)[] }`
-     * @returns A promise that resolves when the batch is committed.
-     * @throws {Error} If any operation fails or the batch cannot be completed.
+     * Used for standalone (single-store) atomic writes. For cross-store atomicity,
+     * use executeInTransaction instead.
      */
     batch(operations: Array<{
         type: "add" | "put";
@@ -698,44 +868,81 @@ interface Store<T = any> {
         type: "delete";
         data: string | number | (string | number)[];
     }>): Promise<void>;
-    open(): 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.
-     * @param query - The query to execute.
-     * @returns A promise resolving to the matching document or `null` if not found.
      */
     find: (query: QueryFilter<T>) => Promise<Document<T> | null>;
     /**
-     * Lists documents based on the provided query.
-     * @param query - The query to list documents (supports pagination and sorting).
-     * @returns A promise resolving to an array of documents.
+     * 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 documents based on the provided query.
-     * @param query - The query to filter documents.
-     * @returns A promise resolving to an array of matching documents.
+     * Filters all documents matching the query.
      */
     filter: (query: QueryFilter<T>) => Promise<Document<T>[]>;
     /**
-     * Creates a new document in the schema.
+     * 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.
-     * @returns A promise resolving to the created document.
+     * @param tx - Optional transaction to buffer the write into.
      */
-    create: (initial: T) => Promise<Document<T>>;
+    create: (initial: T, tx?: TransactionContext) => Promise<Document<T>>;
     /**
-     * Subscribes to schema-level events (e.g., "create", "update", "delete", "access").
-     * @param event - The event type to subscribe to.
-     * @param callback - The function to call when the event occurs.
-     * @returns A promise resolving to an unsubscribe function.
+     * Subscribes to collection-level events.
      */
-    subscribe: (event: CollectionEventType | TelemetryEventType, callback: (event: CollectionEvent<T> | TelemetryEvent) => void) => Promise<() => void>;
+    subscribe: (event: CollectionEventType | TelemetryEventType, callback: (event: CollectionEvent<T> | TelemetryEvent) => void) => () => void;
     /**
-     * Validate data
-     * @param data - The data to validate
-     * @returns An object containing validation results
+     * Validates data against the collection's schema.
      */
     validate(data: Record<string, any>): Promise<{
         value?: any;
@@ -744,9 +951,10 @@ interface Collection<T> {
             path: Array<string>;
         }>;
     }>;
+    invalidate(): void;
 }
 /**
- * Event payload for DocumentCursor events.
+ * Event payload for Collection events.
  */
 type CollectionEventType = "document:create" | "collection:read" | "migration:start" | "migration:end";
 type CollectionEvent<T> = {
@@ -759,91 +967,49 @@ type CollectionEvent<T> = {
 };
 interface Database {
     /**
-     * Accesses a schema model by name.
-     * @param schemaName - The name of the schema to access.
-     * @returns A promise resolving to the schema's DocumentCursor.
-     * @throws DatabaseError
+     * Opens an existing collection by name.
      */
     collection: <T>(schemaName: string) => Promise<Collection<T>>;
     /**
-     * Creates a new schema model.
-     * @param schema - The schema definition.
-     * @returns A promise resolving to the created schema's DocumentCursor.
-     * @throws DatabaseError
+     * Creates a new collection from a schema definition.
      */
     createCollection: <T>(schema: SchemaDefinition) => Promise<Collection<T>>;
     /**
-     * Deletes a schema by name.
-     * @param schemaName - The name of the schema to delete.
-     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
-     * @throws DatabaseError
+     * Deletes a collection and its schema record.
      */
     deleteCollection: (schemaName: string) => Promise<boolean>;
     /**
-     * Updates an existing schema.
-     * @param schema - The updated schema definition.
-     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
-     * @throws DatabaseError
+     * Updates an existing collection's schema record.
      */
     updateCollection: (schema: SchemaDefinition) => Promise<boolean>;
     /**
-     * Migrates an existing collection's data and updates its schema definition metadata.
-     * This function processes data in a streaming fashion to prevent loading
-     * the entire collection into memory.
-     *
-     * It will:
-     * 1. Verify the target collection exists.
-     * 2. Retrieve the collection's current schema definition from a metadata store ($index).
-     * 3. Initialize a `MigrationEngine` with this schema.
-     * 4. Allow a callback to define specific data transformations using the `MigrationEngine`.
-     * 5. **Crucially, it uses `migrationEngine.dryRun()` to get the `newSchema` that results**
-     * **from the transformations defined in the callback.**
-     * 6. Execute these transformations by streaming data from the collection,
-     * through the `MigrationEngine`, and back into the same collection.
-     * 7. Finally, update the schema definition for the collection in the `$index` metadata store
-     * to reflect this `newSchema`.
-     * All these steps for data and metadata updates happen within a single atomic IndexedDB transaction.
-     *
-     * Note: This function focuses solely on *data transformation* and *metadata updates*.
-     * It does NOT handle structural IndexedDB changes like adding/removing physical indexes or object stores,
-     * which still require an `onupgradeneeded` event (i.e., a database version upgrade).
-     *
-     * @param name - The name of the collection (IndexedDB object store) to migrate.
-     * @param {Object} opts - Options for the new migration
-     * @param {SchemaChange<any>[]} opts.changes - Array of schema changes
-     * @param {string} opts.description - Description of the migration
-     * @param {SchemaChange<any>[]} [opts.rollback] - Optional rollback changes
-     * @param {DataTransform<any, any>} [opts.transform] - Optional data transform
-     * @returns A Promise resolving to `true` if the migration completes successfully,
-     * @throws {DatabaseError} If the collection does not exist, its schema metadata is missing,
-     * or any IndexedDB operation/streaming fails critically.
+     * Migrates an existing collection's data and schema definition.
+     * Processes data in a streaming fashion to avoid loading the full collection
+     * into memory.
      */
-    migrateCollection: (name: string, opts: CollectionMigrationOptions, batchSize?: number) => Promise<boolean>;
+    migrateCollection: <T>(name: string, opts: CollectionMigrationOptions, batchSize?: number) => Promise<Collection<T>>;
     /**
-     * Subscribes to database-level events (e.g., "schemaAdded", "schemaDeleted", "schemaAccessed", "migrate").
-     * @param event - The event type to subscribe to.
-     * @param callback - The function to call when the event occurs.
-     * @returns A promise resolving to an unsubscribe function.
+     * 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).
      */
-    subscribe: (event: DatabaseEventType | "telemetry", callback: (event: DatabaseEvent | TelemetryEvent) => void) => Promise<() => void>;
+    transaction: (callback: (tx: TransactionContext) => Promise<void>) => Promise<void>;
     /**
-     * Closes the connection to the database
+     * 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 – safe to call multiple times.
-      * @param schema - The schema definition for the collection.
-      * @returns A promise that resolves when the collection exists.
-      * @throws {DatabaseError} If validation fails or an unexpected error occurs.
-      */
+     * 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 – safe to call multiple times.
-     * @param schemas - An array of schema definitions.
-     * @returns A promise that resolves when all collections exist.
-     * @throws {DatabaseError} If any schema validation fails or an unexpected error occurs.
+     * Ensures multiple collections exist; creates any that don't. Idempotent.
      */
     setupCollections: (schemas: SchemaDefinition[]) => Promise<void>;
 }
@@ -853,9 +1019,6 @@ type CollectionMigrationOptions = {
     rollback?: SchemaChange<any>[];
     transform?: string | DataTransform<any, any>;
 };
-/**
- * Event payload for Database events.
- */
 type DatabaseEventType = "collection:create" | "collection:delete" | "collection:update" | "collection:read" | "migrate";
 type DatabaseEvent = {
     type: DatabaseEventType;
@@ -865,60 +1028,17 @@ type DatabaseEvent = {
 type Document<T> = {
     readonly [K in keyof T]: T[K];
 } & {
-    /**
-     * Unique identifier for the document (assigned automatically if not provided).
-     */
     $id?: string;
-    /**
-     * Timestamp of document creation (ISO string or Date).
-     */
     $created?: string | Date;
-    /**
-     * Timestamp of last document update (ISO string or Date).
-     */
     $updated?: string | Date;
-    /**
-     * Version number incremented on each change (used for optimistic concurrency control).
-     */
     $version?: number;
-    /**
-     * Fetches the latest data from the database and updates the document instance.
-     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
-     */
     read: () => Promise<boolean>;
-    /**
-    * Saves the current document state to the database.
-    * Normally called automatically by `update()` or `delete()`, but can be used manually.
-    * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
-    */
     save: (tx?: TransactionContext) => Promise<boolean>;
-    /**
-     * Updates the document with the provided properties.
-     * @param props - Partial object containing the fields to update.
-     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
-     */
-    update: (props: Partial<T>) => Promise<boolean>;
-    /**
-     * Deletes the document from the database.
-     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
-     */
-    delete: () => Promise<boolean>;
-    /**
-     * Subscribes to document events (e.g., "update", "delete", "access").
-     * @param event - The event type to subscribe to.
-     * @param callback - The function to call when the event occurs.
-     * @returns An unsubscribe function.
-     */
+    update: (props: Partial<T>, tx?: TransactionContext) => Promise<boolean>;
+    delete: (tx?: TransactionContext) => Promise<boolean>;
     subscribe: (event: DocumentEventType | TelemetryEventType, callback: (event: DocumentEvent<T> | TelemetryEvent) => void) => () => void;
-    /**
-     * Returns a plain object containing only the user-defined data (without system fields like $id, $version, etc.).
-     * @returns The current user data.
-     */
     state(): T;
 };
-/**
- * Event payload for DocumentModel events.
- */
 type DocumentEventType = "document:create" | "document:write" | "document:update" | "document:delete" | "document:read";
 type DocumentEvent<T> = {
     type: DocumentEventType;
@@ -942,7 +1062,7 @@ type TelemetryEvent = {
             document?: string;
         };
         result?: {
-            type: 'array' | string;
+            type: "array" | string;
             size?: number;
         };
         error: {
@@ -979,25 +1099,19 @@ declare const COLLECTIONS: {
     readonly CONTEXT: "context";
     readonly SESSION: "session";
     readonly TURN: "turn";
+    readonly TASK: "task";
 };
 type CollectionName = typeof COLLECTIONS[keyof typeof COLLECTIONS];
 
-/**
- * Utility type for representing partial updates to the state, allowing deep nesting.
- * It makes all properties optional and applies the same transformation recursively
- * to nested objects and array elements, allowing for selective updates while
- * preserving the original structure. It also includes the original type T and
- * undefined as possibilities for the top level and nested values.
- */
-type DeepPartial<T> = T extends object ? T extends readonly (infer U)[] ? readonly (DeepPartial<U> | undefined)[] | undefined | T : T extends (infer U)[] ? (DeepPartial<U> | undefined)[] | undefined | T : {
-    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> | undefined : T[K] | undefined;
-} | undefined | T : T | undefined;
-
 declare function del<T>(): T;
 declare const merge: <T extends object>(original: T, changes: DeepPartial<T> | symbol) => T;
 declare function ok<T>(value: T): Result<T, never>;
 declare function err<E = WorkspaceError>(error: E): Result<never, E>;
 declare function omitNullUndefined<T extends Record<string, any>>(obj: T): Partial<T>;
+declare function createProjectWorkspace<ProjectMetadata extends Record<string, any> = Record<string, any>>({ project, language }: {
+    language: string;
+    project: Omit<Project<ProjectMetadata>, "id">;
+}): Workspace<ProjectMetadata>;
 declare function createSimpleWorkspace({ name, owner, language }: {
     name: string;
     language: string;
@@ -1053,10 +1167,6 @@ interface BlobStorage {
     registerBlob?(record: BlobRecord, data: Uint8Array): Promise<void>;
 }
 
-interface TurnRef {
-    id: UUID;
-    version: number;
-}
 declare class TurnTree {
     private readonly db;
     constructor(db: WorkspaceDatabase);
@@ -1067,15 +1177,22 @@ declare class TurnTree {
      * 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[]>;
-    getActiveChain(sessionId: UUID, dirtyBuffer?: readonly Turn[]): 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>;
 }
@@ -1092,11 +1209,13 @@ interface BlobStoreConfig {
 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
@@ -1106,8 +1225,7 @@ declare class BlobStore {
      * that only need summary fields (sha256, mediaType, sizeBytes, etc.)
      * can read them directly from BlobRecord without a separate type.
      */
-    onRegistryChanged?: (sha256: SHA256, record: BlobRecord | null) => void;
-    constructor(backend: BlobStorage, config?: BlobStoreConfig);
+    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>>;
@@ -1123,7 +1241,6 @@ declare class BlobStore {
         }>;
     }>;
     gc(): Promise<number>;
-    gcFull(): Promise<number>;
     purge(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
     getRecord(sha256: SHA256): BlobRecord | null;
     /**
@@ -1140,17 +1257,11 @@ declare class ContentStore {
     private readonly roleCache;
     private readonly preferenceCache;
     private readonly contextCache;
-    /**
-     * Called after any blob registry change with the sha256 and updated
-     * BlobRecord (null on deletion). Wire this to your state manager to
-     * keep Index.blobs current.
-     *
-     * ContentStore sets this on BlobStore.onRegistryChanged internally.
-     * Consumers set this property to receive the forwarded notifications.
-     */
-    onBlobRegistryChanged?: (sha256: SHA256, record: BlobRecord | null) => void;
+    private 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, config?: ContentStoreConfig): Promise<ContentStore>;
+    static create(db: WorkspaceDatabase, blobStorage: BlobStorage, eventBus: EventBus<WorkspaceEvents>, config?: ContentStoreConfig): Promise<ContentStore>;
     private init;
     getTurnTree(): TurnTree;
     getRole(name: string): Promise<Result<Role, WorkspaceError>>;
@@ -1163,6 +1274,10 @@ declare class ContentStore {
     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>;
@@ -1173,43 +1288,75 @@ declare class ContentStore {
     recordBlobRemoteId(sha256: SHA256, providerId: string, fileId: string): Promise<Result<void, WorkspaceError>>;
     getBlobRecord(sha256: SHA256): BlobRecord | null;
     getAllBlobRecords(): Record<SHA256, BlobRecord>;
-    /**
-     * Returns the blob resolver function expected by PromptBuilder.
-     * Closes over the internal BlobStore — no BlobStore reference leaks out.
-     */
     getBlobResolver(): BlobStore['resolveRefs'];
-    recordTurn(sessionId: UUID, turn: Turn): Promise<Result<void, WorkspaceError>>;
+    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>;
 }
 
 declare function workspaceReducer({ index: state }: Workspace, command: Command): Result<DeepPartial<Workspace>, WorkspaceError>;
 
+interface Summarizer {
+    summarize(transcript: Turn[], tokenBudget: number): Promise<{
+        summary: string;
+        remaining: Turn[];
+    }>;
+}
+interface ToolRegistry {
+    /**
+     * Subscribe to tool registry changes.
+     * The callback is executed whenever the set of available tools changes.
+     */
+    onRegistryChanged(callback: (tools: ToolSummary[]) => void): void;
+    /**
+     * Returns all tools currently available in the environment.
+     */
+    list(): ToolSummary[];
+    /**
+     * The stateless executor.
+     * Takes the call, returns the raw result.
+     */
+    execute<T = any>(call: ToolCall): Promise<Result<T>>;
+}
+interface PermissionGuard {
+    /**
+     * An async predicate that determines if the current context
+     * (user, session, project) has the right to execute the request.
+     */
+    authenticate(request: AuthRequest): Promise<Result<null>>;
+}
+
 declare class WorkspaceManager {
     private readonly contentStore;
+    private readonly permissionGuard?;
+    private readonly toolRegistry?;
+    private bus;
     /**
-     * Called when BlobStore triggers a registry change outside of a dispatch()
-     * call — e.g. eagerEviction deleting a blob on release. The caller should
-     * merge this patch into their Workspace.
+     * Called after any workspace change
      */
-    onWorkspacePatch?: (patch: DeepPartial<Workspace>) => void;
-    constructor(contentStore: ContentStore);
+    subscribe<TEventName extends keyof WorkspaceEvents>(event: TEventName, callback: (payload: WorkspaceEvents[TEventName]) => void): () => void;
+    constructor(options: {
+        contentStore: ContentStore;
+        permissionGuard?: PermissionGuard;
+        toolRegistry?: ToolRegistry;
+        eventBus: EventBus<WorkspaceEvents>;
+    });
+    /**
+     * Initializes a Workspace's in-memory Index from environment-static
+     * sources (like ToolRegistry). Call this when opening a Workspace.
+     */
+    init(_: Workspace): DeepPartial<Workspace>;
     reduce(workspace: Workspace, command: Command): Result<DeepPartial<Workspace>, WorkspaceError>;
     dispatch(workspace: Workspace, command: Command): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
-    resolveSession(workspace: Workspace, sessionId: UUID): Promise<Result<EffectiveSession, WorkspaceError>>;
+    resolveSession(workspace: Workspace, sessionId: UUID, transcript?: Turn[]): Promise<Result<EffectiveSession, WorkspaceError>>;
     private handleContentSideEffects;
 }
 
-interface Summarizer {
-    summarize(transcript: Turn[], tokenBudget: number): Promise<{
-        summary: string;
-        remaining: Turn[];
-    }>;
-}
-
 interface ContextRankingInput {
     entries: Context[];
     recentMessages: string[];
@@ -1223,12 +1370,14 @@ interface PlanningInput {
     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;
@@ -1280,49 +1429,87 @@ declare class PromptBuilder {
     private resolvePreferenceConflicts;
 }
 
+/**
+ * A fluent builder for creating Turn objects.
+ * This class helps construct a Turn object by adding various content blocks.
+ */
+declare class TurnBuilder {
+    private readonly _owner;
+    private _turn;
+    constructor(_owner: TurnRole, 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;
+    /**
+     * 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';
+        id?: UUID;
+    }[], action?: 'create' | 'update' | 'complete', taskId?: UUID): 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 Session {
-    /** The session ID this object manages. */
-    readonly sessionId: UUID;
+    private readonly sessionId;
+    private readonly tree;
+    private readonly manager;
+    constructor(sessionId: UUID, tree: TurnTree, manager: WorkspaceManager);
+    turns(): Promise<TurnNode[]>;
+    siblings(turnId: UUID): Promise<TurnNode[]>;
+    branchInfo(turnId: UUID): Promise<BranchInfo>;
+    id(): string;
     /**
-     * The turn DAG. Keys are turn IDs. Mutated in-place on every write.
-     * Callers read this directly for rendering — no copy is made.
+     * Creates a new fluent TurnBuilder for constructing a Turn object.
+     * @param owner The role of the owner of the turn (e.g., 'user', 'assistant', 'tool').
+     * @returns A new TurnBuilder instance.
      */
-    readonly nodes: Record<UUID, TurnNode>;
+    startTurn(owner: TurnRole): TurnBuilder;
     /**
-     * Current head of the active branch. Mirrors what is in
-     * workspace.index.sessions[sessionId].head after each patch is applied.
-     * Session keeps its own copy so reads don't require workspace.
+     * Saves a constructed Turn object to the session. This method handles setting the session ID
+     * and automatically determines the parent turn if not explicitly provided in the Turn object.
+     * @param workspace The current workspace state.
+     * @param turn The Turn object to save. It can be constructed using the TurnBuilder.
+     * @param parentRef Optional TurnRef to explicitly set the parent of the turn. If not provided,
+     *                  the current head of the active chain will be used as the parent.
+     * @returns A promise resolving to a Result containing a DeepPartial<Workspace> on success,
+     *          or a WorkspaceError on failure.
      */
-    private head;
-    /** Turns not yet flushed to storage. */
-    private readonly dirtyBuffer;
-    private flushTimer;
-    private flushChain;
-    private readonly flushConfig;
-    private readonly tree;
-    private readonly contentStore;
-    constructor(sessionId: UUID, nodes: Record<UUID, TurnNode>, head: TurnRef | null, tree: TurnTree, contentStore: ContentStore, flushConfig?: FlushConfig);
-    activeChain(): TurnNode[];
-    siblings(turnId: UUID): TurnNode[];
-    branchInfo(turnId: UUID): BranchInfo;
     addTurn(workspace: Workspace, turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    /**
+     * Updates an existing turn in the session using a fully constructed Turn object.
+     * This method will dispatch a 'turn:edit' command.
+     * @param workspace The current workspace state.
+     * @param updatedTurn The Turn object containing the updated blocks and other properties.
+     * @returns A promise resolving to a Result containing a DeepPartial<Workspace> on success,
+     *          or a WorkspaceError on failure.
+     */
     editTurn(workspace: Workspace, turnId: UUID, newBlocks: ContentBlock[], roleSnapshot?: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
-    branchFrom(workspace: Workspace, newTurn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    branch(workspace: Workspace, turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     deleteTurn(workspace: Workspace, turnId: UUID, version: number, newHead: TurnRef | null): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
-    switchVersionLeft(_: Workspace, turnId: UUID): Result<DeepPartial<Workspace>, WorkspaceError>;
-    switchVersionRight(_: Workspace, turnId: UUID): Result<DeepPartial<Workspace>, WorkspaceError>;
+    switchVersionLeft(workspace: Workspace, turnId: UUID): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    switchVersionRight(workspace: Workspace, turnId: UUID): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
     private switchVersion;
     resolve(workspace: Workspace): Promise<Result<EffectiveSession, WorkspaceError>>;
-    flush(): Promise<void>;
-    dispose(): Promise<void>;
-    private findSubtreeTipForVersion;
-    private collectSubtreeIds;
-    private upsertNode;
-    private scheduleFlush;
-    private cancelFlushTimer;
-    private doFlush;
-}
-declare function buildTurnNode(turn: Turn, children?: UUID[]): TurnNode;
+}
 
 interface SessionManagerConfig {
     flush?: Partial<FlushConfig>;
@@ -1334,11 +1521,10 @@ interface OpenResult {
 declare class SessionManager {
     private readonly workspaceManager;
     private readonly contentStore;
-    private readonly flushConfig;
-    constructor(workspaceManager: WorkspaceManager, contentStore: ContentStore, config?: SessionManagerConfig);
+    constructor(workspaceManager: WorkspaceManager, contentStore: ContentStore);
     open(workspace: Workspace, sessionId: UUID): Promise<Result<OpenResult, WorkspaceError>>;
-    close(session: Session): Promise<void>;
     get workspace(): WorkspaceManager;
+    close(_: Session): Promise<void>;
 }
 
 /**
@@ -1408,4 +1594,4 @@ declare class IndexedDBBlobStorage implements BlobStorage {
     registerBlob(record: BlobRecord, data: Uint8Array): Promise<void>;
 }
 
-export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTurn, type BaseCommand, type BlobCommand, type BlobMediaType, type BlobRecord, type BlobRef, type BlobStorage, BlobStore, type BlobStoreConfig, type BranchInfo, type BranchTurn, COLLECTIONS, type CacheConfig, type CollectionName, type Command, type ContentBlock, ContentStore, type ContentStoreConfig, type Context, type ContextContent, type ContextRelevanceConfig, type ContextSummary, type CreateSession, type CreateWorkspace, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type EditTurn, type EffectiveSession, type FlushConfig, type ForkSession, type ImageBlock, type ImageMediaType, type Index, type IndexedDBBlobConfig, IndexedDBBlobStorage, MemoryBlobStorage, type OpenResult, type OverrideSessionPreferences, type Preference, type PreferenceConflict, type PreferenceSummary, type Project, type Prompt, PromptBuilder, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type ResolvedBlob, type Result, type RetainBlob, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, Session, SessionManager, type SessionManagerConfig, type SessionMeta, type Settings, type SummaryBlock, type SwitchRole, type TextBlock, type ThinkingBlock, type Timestamp, type TokenBudget, type ToolResultBlock, type ToolUseBlock, type TopicIndex, type TranscriptWindow, type Turn, type TurnNode, type TurnRef, type TurnRole, TurnTree, type URI, type UUID, type UpdateContext, type UpdatePreference, type UpdateRole, type Workspace, type WorkspaceBundle, type WorkspaceDatabase, type WorkspaceError, WorkspaceManager, buildTurnNode, computeSHA256, createSimpleWorkspace, createWorkspaceDatabase, del, err, extractBlobRecord, extractBlobRef, merge, ok, omitNullUndefined, workspaceReducer };
+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 CacheConfig, type CallTool, type CollectionName, type Command, type ContentBlock, ContentStore, type ContentStoreConfig, type Context, type ContextContent, type ContextRelevanceConfig, type ContextSummary, type CreateSession, type CreateWorkspace, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTask, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type DuplicateKeyError, type EditTurn, type EffectiveSession, type FlushConfig, type ForkSession, type ImageBlock, type ImageMediaType, type Index, type IndexedDBBlobConfig, IndexedDBBlobStorage, type InvalidCommandError, MemoryBlobStorage, type NotFoundError, type OpenResult, type OverrideSessionPreferences, type Preference, type PreferenceConflict, type PreferenceSummary, type Project, type Prompt, PromptBuilder, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type ResolvedBlob, type Result, type RetainBlob, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, type SaveTurn, Session, SessionManager, type SessionManagerConfig, type SessionMeta, type Settings, type SummaryBlock, type SwitchRole, type Task, type TaskProposalBlock, type TaskStatus, type TaskStep, type TaskSummary, type TextBlock, type ThinkingBlock, type Timestamp, type TokenBudget, type ToolCall, type ToolResultBlock, type ToolSummary, type ToolUseBlock, type TopicIndex, type TranscriptWindow, type Turn, type TurnNode, type TurnRef, type TurnRole, TurnTree, type URI, type UUID, type UpdateContext, type UpdatePreference, type UpdateRole, type UpdateTask, type Workspace, type WorkspaceBundle, type WorkspaceDatabase, type WorkspaceError, type WorkspaceEvents, WorkspaceManager, computeSHA256, createProjectWorkspace, createSimpleWorkspace, createWorkspaceDatabase, del, err, extractBlobRecord, extractBlobRef, merge, ok, omitNullUndefined, workspaceReducer };