@asaidimu/utils-workspace 2.0.0 → 2.1.0

package/index.d.ts

@@ -1,3 +1,6 @@
+import { QueryFilter, PaginationOptions } from '@asaidimu/query';
+import { SchemaDefinition, SchemaChange, DataTransform } from '@asaidimu/anansi';
+
 type UUID = string;
 type Timestamp = string;
 type URI = string;
@@ -29,7 +32,7 @@ type WorkspaceError = {
 };
 interface Settings {
     language: string;
-    defaultRole: string;
+    defaultRole?: string;
     prompt?: string;
 }
 interface Project {
@@ -61,8 +64,7 @@ type ResolvedBlob = {
 };
 /**
  * Full registry entry for a blob. BlobRef is a Pick of this type, so
- * a BlobRecord is always assignable to BlobRef. BlobSummary has been
- * removed — callers that previously used BlobSummary use BlobRecord directly.
+ * a BlobRecord is always assignable to BlobRef.
  */
 interface BlobRecord {
     sha256: SHA256;
@@ -124,11 +126,26 @@ interface Turn {
     role: TurnRole;
     blocks: ContentBlock[];
     timestamp: Timestamp;
+    /**
+     * The name of the role active when this turn was recorded.
+     * Snapshot so history is stable even if the role is later renamed.
+     */
     roleSnapshot?: string;
+    /**
+     * Parent pointer. Null for root turns.
+     * This is plain data stored on the document — the DAG is reconstructed
+     * in memory by TurnTree.buildNodeGraph() at session open time.
+     */
     parent: {
         id: UUID;
         version: number;
     } | null;
+    /**
+     * Partition key. Stored on the Turn document so Collection.filter
+     * can retrieve all turns for a session in a single query.
+     * Not present on Turn objects used purely in memory (e.g. dirty buffer).
+     */
+    sessionId?: UUID;
 }
 interface TurnNode {
     id: UUID;
@@ -145,63 +162,53 @@ interface TurnNode {
     children: Record<number, UUID[]>;
 }
 interface BranchInfo {
-    /** All sibling versions at this level, in insertion order. */
     versions: number[];
-    /** Index of this turn within siblings (0-based). */
     currentIndex: number;
-    /** Convenience: number of siblings (siblings.length). */
     total: number;
-    /** True when there is a branch to the left. */
     hasPrev: boolean;
-    /** True when there is a branch to the right. */
     hasNext: boolean;
 }
-interface RoleSummary {
+interface Role {
     name: string;
     label: string;
     description?: string;
-    preferences: number;
+    persona: string;
+    preferences: UUID[];
 }
-interface PreferenceSummary {
+interface Preference {
     id: UUID;
+    content: string;
     topics: string[];
     timestamp: Timestamp;
-    snippet?: string;
 }
-interface ContextSummary {
+type ContextContent = {
+    kind: 'text';
+    value: string;
+} | {
+    kind: 'json';
+    value: unknown;
+} | {
+    kind: 'blob';
+    sha256: SHA256;
+    mediaType: BlobMediaType;
+    sizeBytes: number;
+    filename?: string;
+} | {
+    kind: 'remote';
+    uri: URI;
+    mediaType?: BlobMediaType;
+};
+interface Context {
     key: string;
     topics: string[];
+    content: ContextContent;
     timestamp: Timestamp;
-    mime?: string;
-    size?: number;
-    preview?: string;
-    source?: string;
     metadata?: Record<string, any>;
 }
-interface TopicIndex {
-    topic: string;
-    contextKeys: string[];
-    preferences: UUID[];
-    metadata?: {
-        created?: Timestamp;
-        updated?: Timestamp;
-        entries?: number;
-    };
-}
-interface Workspace {
-    id: UUID;
-    settings: Settings;
-    project: Project;
-    index: Index;
-}
-interface Index {
-    format: string;
-    roles: Record<string, RoleSummary>;
-    preferences: Record<UUID, PreferenceSummary>;
-    context: Record<string, ContextSummary>;
-    sessions: Record<UUID, SessionMeta>;
-    topics: Record<string, TopicIndex>;
-}
+/**
+ * SessionMeta is stored as a document in the 'session' collection.
+ * The head pointer lives here — no separate session_heads store needed.
+ */
 interface SessionMeta {
     id: UUID;
     label: string;
@@ -218,69 +225,64 @@ interface SessionMeta {
         version: number;
     } | null;
 }
-interface Role {
-    id: UUID;
+interface RoleSummary {
     name: string;
     label: string;
-    persona: string;
     description?: string;
-    preferences: UUID[];
+    /** Number of preference IDs listed on the role. */
+    preferences: number;
 }
-interface Preference {
+interface PreferenceSummary {
     id: UUID;
-    content: string;
     topics: string[];
     timestamp: Timestamp;
+    snippet?: string;
 }
-interface Context {
+interface ContextSummary {
     key: string;
-    content: ContextContent;
     topics: string[];
     timestamp: Timestamp;
+    mime?: string;
+    size?: number;
+    preview?: string;
+    source?: string;
     metadata?: Record<string, any>;
-    remoteIds?: Record<string, string>;
-    refCount?: number;
 }
-type ContextContent = {
-    kind: 'text';
-    value: string;
-} | {
-    kind: 'json';
-    value: object;
-} | {
-    kind: 'blob';
-} & BlobRef | {
-    kind: 'remote';
-    uri: URI;
-    mediaType: BlobMediaType;
-};
-interface Session$1 {
-    id: UUID;
-    label: string;
-    role: string;
-    topics: string[];
+interface TopicIndex {
+    topic: string;
+    contextKeys: string[];
     preferences: UUID[];
-    turns: Turn[];
-    metadata: {
+    metadata?: {
         created?: Timestamp;
         updated?: Timestamp;
+        entries?: number;
     };
 }
+interface Index {
+    roles: Record<string, RoleSummary>;
+    preferences: Record<UUID, PreferenceSummary>;
+    context: Record<string, ContextSummary>;
+    sessions: Record<UUID, SessionMeta>;
+    topics: Record<string, TopicIndex>;
+    blobs: Record<SHA256, BlobRecord>;
+}
+interface Workspace {
+    id: UUID;
+    settings: Settings;
+    project: Project;
+    index: Index;
+}
 interface WorkspaceBundle {
     format: 'aiworkspace/4.0';
     workspace: Workspace;
     roles: Record<string, Role>;
     preferences: Record<UUID, Preference>;
     context: Record<string, Context>;
-    sessions: Record<UUID, Session$1>;
+    sessions: Record<UUID, SessionMeta & {
+        turns: Turn[];
+    }>;
     blobs: Record<SHA256, BlobRecord>;
 }
-interface TranscriptWindow {
-    sessionId: UUID;
-    turns: Turn[];
-    flushedCount: number;
-    hasMore: boolean;
-}
 interface EffectiveSession {
     session: SessionMeta;
     role: Role;
@@ -293,7 +295,6 @@ interface CacheConfig {
     roles?: number;
     preferences?: number;
     context?: number;
-    transcriptWindows?: number;
 }
 interface FlushConfig {
     maxBufferSize: number;
@@ -302,7 +303,6 @@ interface FlushConfig {
 interface ContentStoreConfig {
     cache?: CacheConfig;
     flush?: FlushConfig;
-    transcriptWindowSize?: number;
 }
 interface BaseCommand {
     type: string;
@@ -452,14 +452,16 @@ interface DeleteSession extends BaseCommand {
 }
 interface RegisterBlob extends BaseCommand {
     type: 'blob:register';
-    payload: BlobRecord;
+    payload: {
+        data: Uint8Array;
+        mediaType: BlobMediaType;
+        filename?: string;
+    };
 }
-interface RecordBlobRemoteId extends BaseCommand {
-    type: 'blob:remote_id';
+interface RetainBlob extends BaseCommand {
+    type: 'blob:retain';
     payload: {
         sha256: SHA256;
-        providerId: string;
-        fileId: string;
     };
 }
 interface ReleaseBlob extends BaseCommand {
@@ -468,7 +470,22 @@ interface ReleaseBlob extends BaseCommand {
         sha256: SHA256;
     };
 }
-type Command = CreateWorkspace | AddRole | UpdateRole | DeleteRole | AddPreference | UpdatePreference | DeletePreference | CreateSession | AddContext | UpdateContext | DeleteContext | AddTurn | EditTurn | BranchTurn | DeleteTurn | SwitchRole | AddSessionTopics | OverrideSessionPreferences | ForkSession | DeleteSession | RegisterBlob | RecordBlobRemoteId | ReleaseBlob;
+interface PurgeBlob extends BaseCommand {
+    type: 'blob:purge';
+    payload: {
+        sha256: SHA256;
+    };
+}
+interface RecordBlobRemoteId extends BaseCommand {
+    type: 'blob:record_remote_id';
+    payload: {
+        sha256: SHA256;
+        providerId: string;
+        fileId: string;
+    };
+}
+type BlobCommand = RegisterBlob | RetainBlob | ReleaseBlob | PurgeBlob | RecordBlobRemoteId;
+type Command = CreateWorkspace | AddRole | UpdateRole | DeleteRole | AddPreference | UpdatePreference | DeletePreference | CreateSession | AddContext | UpdateContext | DeleteContext | AddTurn | EditTurn | BranchTurn | DeleteTurn | SwitchRole | AddSessionTopics | OverrideSessionPreferences | ForkSession | DeleteSession | BlobCommand;
 interface TokenBudget {
     total: number;
     estimator?: (text: string) => number;
@@ -486,7 +503,7 @@ interface ContextRelevanceConfig {
     freshnessHalfLifeDays?: number;
 }
 /**
- * BuiltTurn has been removed. Prompt.transcript.turns is now Turn[].
+ * Prompt.transcript.turns is Turn[].
  * Synthetic turns produced by PromptAssembler (summary blocks, truncation
  * notices, referential attachments) carry generated UUIDs and version 0,
  * with parent: null. They are ephemeral — never stored, never patched.
@@ -515,35 +532,455 @@ interface Prompt {
     warnings: string[];
     conflicts: PreferenceConflict[];
 }
+interface TranscriptWindow {
+    sessionId: UUID;
+    turns: Turn[];
+    flushedCount: number;
+    hasMore: boolean;
+}
 
-interface ContentStorage {
-    saveRole(role: Role): Promise<void>;
-    loadRole(name: string): Promise<Role | null>;
-    deleteRole(name: string): Promise<void>;
-    savePreference(preference: Preference): Promise<void>;
-    loadPreference(id: UUID): Promise<Preference | null>;
-    deletePreference(id: UUID): Promise<void>;
-    saveContext(context: Context): Promise<void>;
-    loadContext(key: string): Promise<Context | null>;
-    loadContextBatch(keys: string[]): Promise<Map<string, Context>>;
-    deleteContext(key: string): Promise<void>;
-    saveTurn(sessionId: UUID, turn: Turn): Promise<void>;
-    loadTurn(sessionId: UUID, turnId: UUID, version: number): Promise<Turn | null>;
-    loadAllTurns(sessionId: UUID): Promise<Turn[]>;
-    deleteTurn(sessionId: UUID, turnId: UUID, version: number): Promise<void>;
-    setSessionHead(sessionId: UUID, head: {
-        id: UUID;
-        version: number;
-    } | null): Promise<void>;
-    getSessionHead(sessionId: UUID): Promise<{
-        id: UUID;
-        version: number;
-    } | null>;
-    storeBytes(sha256: SHA256, data: Uint8Array): Promise<void>;
-    loadBytes(sha256: SHA256): Promise<Uint8Array | null>;
-    deleteBytes(sha256: SHA256): Promise<void>;
-    exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
+declare class TransactionContext {
+    readonly id: string;
+    private buffer;
+    private committed;
+    constructor();
+    addOp(store: Store<any>, type: "put" | "delete", data: any): void;
+    commit(): Promise<void>;
+    rollback(): void;
+}
+
+interface CursorCallbackResult<T> {
+    value: T | null;
+    done: boolean;
+    offset?: number;
+}
+/**
+ * Callback function for cursor iteration over store records.
+ *
+ * @template T - The type of records stored.
+ * @param value - The current record value (cloned, not a live reference).
+ * @param key - The key (ID) of the current record.
+ * @param cursor - The underlying cursor object (implementation‑specific; may be `null` in memory adapters).
+ * @returns A promise that resolves to an object indicating whether iteration should stop, and an optional offset to advance.
+ */
+type 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;
+}
+/**
+ * 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.
+ *
+ * @template T - The type of objects stored in this store. Must include the key path property.
+ */
+interface Store<T = any> {
+    /**
+     * Adds one or more records to the store.
+     *
+     * If a record does not have a value for the store's key path, an automatic
+     * key (e.g., auto‑incremented number) may be assigned. The store's key path
+     * property is then updated on the added record(s).
+     *
+     * @param data - A single record or an array of records to add.
+     * @returns A promise that resolves to:
+     *   - the key(s) of the added record(s) – a single key if `data` was a single record,
+     *     or an array of keys if `data` was an array.
+     * @throws {Error} If any record lacks the key path property and auto‑keying is not supported,
+     *                 or if a record with the same key already exists.
+     */
+    add(data: T | T[]): Promise<string | number | (string | number)[]>;
+    /**
+     * Removes all records from the store.
+     *
+     * @returns A promise that resolves when the store is cleared.
+     * @throws {Error} If the operation fails (e.g., store is closed).
+     */
+    clear(): Promise<void>;
+    /**
+     * Returns the total number of records in the store.
+     *
+     * @returns A promise that resolves to the record count.
+     * @throws {Error} If the operation fails.
+     */
+    count(): Promise<number>;
+    /**
+     * Deletes one or more records by their keys.
+     *
+     * @param id - A single key or an array of keys to delete.
+     * @returns A promise that resolves when the records are deleted.
+     * @throws {Error} If any key is `undefined` or the operation fails.
+     */
+    delete(id: string | number | (string | number)[]): Promise<void>;
+    /**
+     * Retrieves a single record by its primary key.
+     *
+     * @param id - The key of the record to retrieve.
+     * @returns A promise that resolves to the record (cloned) if found, otherwise `undefined`.
+     * @throws {Error} If the key is `undefined` or the operation fails.
+     */
+    getById(id: string | number): Promise<T | undefined>;
+    /**
+     * Retrieves a single record by an index and index key.
+     *
+     * @param index - The name of the index to query.
+     * @param key - The exact key value to look up in the index.
+     * @returns A promise that resolves to the first matching record (cloned), or `undefined` if none.
+     * @throws {Error} If the index does not exist, the key is `undefined`, or the operation fails.
+     */
+    getByIndex(index: string, key: any): Promise<T | undefined>;
+    /**
+     * Retrieves multiple records from an index, optionally within a key range.
+     *
+     * @param index - The name of the index to query.
+     * @param keyRange - Optional `StoreKeyRange` to filter results. If omitted, all records are returned.
+     * @returns A promise that resolves to an array of matching records (each cloned).
+     * @throws {Error} If the index does not exist or the operation fails.
+     */
+    getByKeyRange(index: string, keyRange?: StoreKeyRange): Promise<T[]>;
+    /**
+     * Retrieves all records from the store.
+     *
+     * @returns A promise that resolves to an array of all records (each cloned).
+     * @throws {Error} If the operation fails.
+     */
+    getAll(): Promise<T[]>;
+    /**
+     * Inserts or replaces a record.
+     *
+     * If a record with the same key already exists, it is replaced.
+     * The record must contain the store's key path property.
+     *
+     * @param data - The record to store.
+     * @returns A promise that resolves to the key of the stored record.
+     * @throws {Error} If the record lacks the key path property or the operation fails.
+     */
+    put(data: T): Promise<string | number>;
+    /**
+     * Iterates over records using a cursor, allowing early termination and skipping.
+     *
+     * The callback is invoked for each record in iteration order. The callback
+     * can control the iteration by returning `{ done: true }` to stop, or
+     * `{ offset: n }` to skip ahead `n` records.
+     *
+     * @param callback - Function called for each record.
+     * @param direction - Iteration direction: `"forward"` (ascending keys) or `"backward"` (descending keys).
+     * @param keyRange - An optional StoreKeyRange to start from specific points.
+     * @returns A promise that resolves to the last record processed (or `null` if none).
+     * @throws {Error} If the callback throws or the operation fails.
+     */
+    cursor(callback: CursorCallback<T>, direction?: "forward" | "backward", keyRange?: StoreKeyRange): Promise<T | null>;
+    /**
+     * Executes a batch of write operations atomically.
+     *
+     * All operations in the batch succeed or fail together. This is useful for
+     * maintaining consistency when multiple writes are required.
+     *
+     * @param operations - An array of operations. Each operation can be:
+     *   - `{ type: "add" | "put", data: T | T[] }`
+     *   - `{ type: "delete", data: string | number | (string | number)[] }`
+     * @returns A promise that resolves when the batch is committed.
+     * @throws {Error} If any operation fails or the batch cannot be completed.
+     */
+    batch(operations: Array<{
+        type: "add" | "put";
+        data: T | T[];
+    } | {
+        type: "delete";
+        data: string | number | (string | number)[];
+    }>): Promise<void>;
+    open(): Promise<void>;
+}
+interface Collection<T> {
+    /**
+     * Finds a single document matching the query.
+     * @param query - The query to execute.
+     * @returns A promise resolving to the matching document or `null` if not found.
+     */
+    find: (query: QueryFilter<T>) => Promise<Document<T> | null>;
+    /**
+     * Lists documents based on the provided query.
+     * @param query - The query to list documents (supports pagination and sorting).
+     * @returns A promise resolving to an array of documents.
+     */
+    list: (query: PaginationOptions) => Promise<AsyncIterator<Document<T>[]>>;
+    /**
+     * Filters documents based on the provided query.
+     * @param query - The query to filter documents.
+     * @returns A promise resolving to an array of matching documents.
+     */
+    filter: (query: QueryFilter<T>) => Promise<Document<T>[]>;
+    /**
+     * Creates a new document in the schema.
+     * @param initial - The initial data for the document.
+     * @returns A promise resolving to the created document.
+     */
+    create: (initial: T) => Promise<Document<T>>;
+    /**
+     * Subscribes to schema-level events (e.g., "create", "update", "delete", "access").
+     * @param event - The event type to subscribe to.
+     * @param callback - The function to call when the event occurs.
+     * @returns A promise resolving to an unsubscribe function.
+     */
+    subscribe: (event: CollectionEventType | TelemetryEventType, callback: (event: CollectionEvent<T> | TelemetryEvent) => void) => Promise<() => void>;
+    /**
+     * Validate data
+     * @param data - The data to validate
+     * @returns An object containing validation results
+     */
+    validate(data: Record<string, any>): Promise<{
+        value?: any;
+        issues: Array<{
+            message: string;
+            path: Array<string>;
+        }>;
+    }>;
 }
+/**
+ * Event payload for DocumentCursor events.
+ */
+type CollectionEventType = "document:create" | "collection:read" | "migration:start" | "migration:end";
+type CollectionEvent<T> = {
+    type: CollectionEventType;
+    document?: T;
+    model?: string;
+    method?: keyof Collection<T>;
+    metadata?: Record<string, unknown>;
+    timestamp: number;
+};
+interface Database {
+    /**
+     * Accesses a schema model by name.
+     * @param schemaName - The name of the schema to access.
+     * @returns A promise resolving to the schema's DocumentCursor.
+     * @throws DatabaseError
+     */
+    collection: <T>(schemaName: string) => Promise<Collection<T>>;
+    /**
+     * Creates a new schema model.
+     * @param schema - The schema definition.
+     * @returns A promise resolving to the created schema's DocumentCursor.
+     * @throws DatabaseError
+     */
+    createCollection: <T>(schema: SchemaDefinition) => Promise<Collection<T>>;
+    /**
+     * Deletes a schema by name.
+     * @param schemaName - The name of the schema to delete.
+     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+     * @throws DatabaseError
+     */
+    deleteCollection: (schemaName: string) => Promise<boolean>;
+    /**
+     * Updates an existing schema.
+     * @param schema - The updated schema definition.
+     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+     * @throws DatabaseError
+     */
+    updateCollection: (schema: SchemaDefinition) => Promise<boolean>;
+    /**
+     * Migrates an existing collection's data and updates its schema definition metadata.
+     * This function processes data in a streaming fashion to prevent loading
+     * the entire collection into memory.
+     *
+     * It will:
+     * 1. Verify the target collection exists.
+     * 2. Retrieve the collection's current schema definition from a metadata store ($index).
+     * 3. Initialize a `MigrationEngine` with this schema.
+     * 4. Allow a callback to define specific data transformations using the `MigrationEngine`.
+     * 5. **Crucially, it uses `migrationEngine.dryRun()` to get the `newSchema` that results**
+     * **from the transformations defined in the callback.**
+     * 6. Execute these transformations by streaming data from the collection,
+     * through the `MigrationEngine`, and back into the same collection.
+     * 7. Finally, update the schema definition for the collection in the `$index` metadata store
+     * to reflect this `newSchema`.
+     * All these steps for data and metadata updates happen within a single atomic IndexedDB transaction.
+     *
+     * Note: This function focuses solely on *data transformation* and *metadata updates*.
+     * It does NOT handle structural IndexedDB changes like adding/removing physical indexes or object stores,
+     * which still require an `onupgradeneeded` event (i.e., a database version upgrade).
+     *
+     * @param name - The name of the collection (IndexedDB object store) to migrate.
+     * @param {Object} opts - Options for the new migration
+     * @param {SchemaChange<any>[]} opts.changes - Array of schema changes
+     * @param {string} opts.description - Description of the migration
+     * @param {SchemaChange<any>[]} [opts.rollback] - Optional rollback changes
+     * @param {DataTransform<any, any>} [opts.transform] - Optional data transform
+     * @returns A Promise resolving to `true` if the migration completes successfully,
+     * @throws {DatabaseError} If the collection does not exist, its schema metadata is missing,
+     * or any IndexedDB operation/streaming fails critically.
+     */
+    migrateCollection: (name: string, opts: CollectionMigrationOptions, batchSize?: number) => Promise<boolean>;
+    /**
+     * Subscribes to database-level events (e.g., "schemaAdded", "schemaDeleted", "schemaAccessed", "migrate").
+     * @param event - The event type to subscribe to.
+     * @param callback - The function to call when the event occurs.
+     * @returns A promise resolving to an unsubscribe function.
+     */
+    subscribe: (event: DatabaseEventType | "telemetry", callback: (event: DatabaseEvent | TelemetryEvent) => void) => Promise<() => void>;
+    /**
+     * Closes the connection to the database
+     */
+    close: () => void;
+    /**
+      * Ensures a collection exists; creates it if it doesn't.
+      * Idempotent – safe to call multiple times.
+      * @param schema - The schema definition for the collection.
+      * @returns A promise that resolves when the collection exists.
+      * @throws {DatabaseError} If validation fails or an unexpected error occurs.
+      */
+    ensureCollection: (schema: SchemaDefinition) => Promise<void>;
+    /**
+     * Ensures multiple collections exist; creates any that don't.
+     * Idempotent – safe to call multiple times.
+     * @param schemas - An array of schema definitions.
+     * @returns A promise that resolves when all collections exist.
+     * @throws {DatabaseError} If any schema validation fails or an unexpected error occurs.
+     */
+    setupCollections: (schemas: SchemaDefinition[]) => Promise<void>;
+}
+type CollectionMigrationOptions = {
+    changes: SchemaChange<any>[];
+    description: string;
+    rollback?: SchemaChange<any>[];
+    transform?: string | DataTransform<any, any>;
+};
+/**
+ * Event payload for Database events.
+ */
+type DatabaseEventType = "collection:create" | "collection:delete" | "collection:update" | "collection:read" | "migrate";
+type DatabaseEvent = {
+    type: DatabaseEventType;
+    schema?: SchemaDefinition | Partial<SchemaDefinition>;
+    timestamp: number;
+};
+type Document<T> = {
+    readonly [K in keyof T]: T[K];
+} & {
+    /**
+     * Unique identifier for the document (assigned automatically if not provided).
+     */
+    $id?: string;
+    /**
+     * Timestamp of document creation (ISO string or Date).
+     */
+    $created?: string | Date;
+    /**
+     * Timestamp of last document update (ISO string or Date).
+     */
+    $updated?: string | Date;
+    /**
+     * Version number incremented on each change (used for optimistic concurrency control).
+     */
+    $version?: number;
+    /**
+     * Fetches the latest data from the database and updates the document instance.
+     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+     */
+    read: () => Promise<boolean>;
+    /**
+    * Saves the current document state to the database.
+    * Normally called automatically by `update()` or `delete()`, but can be used manually.
+    * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+    */
+    save: (tx?: TransactionContext) => Promise<boolean>;
+    /**
+     * Updates the document with the provided properties.
+     * @param props - Partial object containing the fields to update.
+     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+     */
+    update: (props: Partial<T>) => Promise<boolean>;
+    /**
+     * Deletes the document from the database.
+     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
+     */
+    delete: () => Promise<boolean>;
+    /**
+     * Subscribes to document events (e.g., "update", "delete", "access").
+     * @param event - The event type to subscribe to.
+     * @param callback - The function to call when the event occurs.
+     * @returns An unsubscribe function.
+     */
+    subscribe: (event: DocumentEventType | TelemetryEventType, callback: (event: DocumentEvent<T> | TelemetryEvent) => void) => () => void;
+    /**
+     * Returns a plain object containing only the user-defined data (without system fields like $id, $version, etc.).
+     * @returns The current user data.
+     */
+    state(): T;
+};
+/**
+ * Event payload for DocumentModel events.
+ */
+type DocumentEventType = "document:create" | "document:write" | "document:update" | "document:delete" | "document:read";
+type DocumentEvent<T> = {
+    type: DocumentEventType;
+    data?: Partial<T>;
+    timestamp: number;
+};
+type TelemetryEventType = "telemetry";
+type TelemetryEvent = {
+    type: TelemetryEventType;
+    method: string;
+    timestamp: number;
+    source: any;
+    metadata: {
+        args: any[];
+        performance: {
+            durationMs: number;
+        };
+        source: {
+            level: "database" | "collection" | "document";
+            collection?: string;
+            document?: string;
+        };
+        result?: {
+            type: 'array' | string;
+            size?: number;
+        };
+        error: {
+            message: string;
+            name: string;
+            stack?: string;
+        } | null;
+    };
+};
+
+interface WorkspaceDatabase {
+    /**
+     * Open the database. Registers core schemas followed by any extension
+     * schemas supplied by the caller (domain plugins).
+     *
+     * Idempotent — safe to call multiple times; subsequent calls are no-ops
+     * if the database is already open.
+     */
+    open(extensionSchemas?: SchemaDefinition[]): Promise<void>;
+    /**
+     * Access a collection by schema name.
+     * Throws if the schema has not been registered.
+     */
+    collection<T>(schemaName: string): Promise<Collection<T>>;
+    /**
+     * Close the database connection.
+     */
+    close(): void;
+}
+declare function createWorkspaceDatabase(db: Database): WorkspaceDatabase;
+declare const COLLECTIONS: {
+    readonly ROLE: "role";
+    readonly PREFERENCE: "preference";
+    readonly CONTEXT: "context";
+    readonly SESSION: "session";
+    readonly TURN: "turn";
+};
+type CollectionName = typeof COLLECTIONS[keyof typeof COLLECTIONS];
 
 /**
  * Utility type for representing partial updates to the state, allowing deep nesting.
@@ -560,65 +997,14 @@ declare function del<T>(): T;
 declare const merge: <T extends object>(original: T, changes: DeepPartial<T> | symbol) => T;
 declare function ok<T>(value: T): Result<T, never>;
 declare function err<E = WorkspaceError>(error: E): Result<never, E>;
-
-interface IndexedDBConfig {
-    dbName?: string;
-}
-declare class IndexedDBStorage implements ContentStorage {
-    private readonly dbName;
-    private db;
-    constructor(config?: IndexedDBConfig);
-    open(): Promise<void>;
-    private createSchema;
-    close(): void;
-    deleteDatabase(): Promise<void>;
-    private getDB;
-    private readTx;
-    private writeTx;
-    saveRole(role: Role): Promise<void>;
-    loadRole(name: string): Promise<Role | null>;
-    deleteRole(name: string): Promise<void>;
-    savePreference(preference: Preference): Promise<void>;
-    loadPreference(id: UUID): Promise<Preference | null>;
-    deletePreference(id: UUID): Promise<void>;
-    saveContext(context: Context): Promise<void>;
-    loadContext(key: string): Promise<Context | null>;
-    loadContextBatch(keys: string[]): Promise<Map<string, Context>>;
-    deleteContext(key: string): Promise<void>;
-    saveTurn(sessionId: UUID, turn: Turn): Promise<void>;
-    loadTurn(sessionId: UUID, turnId: UUID, version: number): Promise<Turn | null>;
-    loadAllTurns(sessionId: UUID): Promise<Turn[]>;
-    deleteTurn(sessionId: UUID, turnId: UUID, version: number): Promise<void>;
-    setSessionHead(sessionId: UUID, head: {
-        id: UUID;
-        version: number;
-    } | null): Promise<void>;
-    getSessionHead(sessionId: UUID): Promise<{
-        id: UUID;
-        version: number;
-    } | null>;
-    storeBytes(sha256: SHA256, data: Uint8Array): Promise<void>;
-    loadBytes(sha256: SHA256): Promise<Uint8Array | null>;
-    deleteBytes(sha256: SHA256): Promise<void>;
-    exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
-    saveWorkspace(state: Workspace): Promise<void>;
-    loadWorkspace(): Promise<Workspace | null>;
-    exportBundle(): Promise<{
-        roles: Record<string, Role>;
-        preferences: Record<UUID, Preference>;
-        context: Record<string, Context>;
-        transcripts: Record<UUID, Turn[]>;
-        workspace: Workspace | null;
-    }>;
-    importBundle(data: {
-        roles: Record<string, Role>;
-        preferences: Record<UUID, Preference>;
-        context: Record<string, Context>;
-        transcripts: Record<UUID, Turn[]>;
-        workspace?: Workspace;
-    }): Promise<void>;
-    private getAllFromStore;
-}
+declare function omitNullUndefined<T extends Record<string, any>>(obj: T): Partial<T>;
+declare function createSimpleWorkspace({ name, owner, language }: {
+    name: string;
+    language: string;
+    owner: string;
+}): Workspace;
+declare function extractBlobRecord(patch: DeepPartial<Workspace>): BlobRecord | null;
+declare function extractBlobRef(record: BlobRecord): BlobRef;
 
 /**
  * Persistence contract for binary blob content and blob registry records.
@@ -672,19 +1058,26 @@ interface TurnRef {
     version: number;
 }
 declare class TurnTree {
-    private readonly storage;
-    constructor(storage: ContentStorage);
+    private readonly db;
+    constructor(db: WorkspaceDatabase);
+    private turns;
+    private sessions;
+    /**
+     * Compound filter for a specific (sessionId, id, version) tuple.
+     * Uses only declared schema fields — never $id.
+     */
+    private turnFilter;
+    getHead(sessionId: UUID): Promise<TurnRef | null>;
+    setHead(sessionId: UUID, head: TurnRef | null): Promise<void>;
     append(sessionId: UUID, turn: Turn): Promise<Turn>;
-    appendBatch(sessionId: UUID, turns: Turn[]): Promise<void>;
+    appendBatch(sessionId: UUID, turns: Turn[], finalHead: TurnRef | null): Promise<void>;
     replaceVersion(sessionId: UUID, newTurn: Turn): Promise<void>;
     branch(sessionId: UUID, newTurn: Turn): Promise<void>;
+    loadAllTurns(sessionId: UUID): Promise<Turn[]>;
     getActiveChain(sessionId: UUID, dirtyBuffer?: readonly Turn[]): Promise<Turn[]>;
-    countChained(sessionId: UUID, dirtyBuffer?: readonly Turn[]): Promise<number>;
     buildNodeGraph(sessionId: UUID, dirtyBuffer?: readonly Turn[]): Promise<Record<UUID, TurnNode>>;
     deleteSubtree(sessionId: UUID, turnId: UUID, version: number, newHead: TurnRef | null): Promise<void>;
     copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
-    getHead(sessionId: UUID): Promise<TurnRef | null>;
-    setHead(sessionId: UUID, head: TurnRef | null): Promise<void>;
 }
 
 declare function computeSHA256(data: Uint8Array): Promise<SHA256>;
@@ -741,29 +1134,55 @@ declare class BlobStore {
 }
 
 declare class ContentStore {
-    private readonly storage;
-    private readonly tree;
-    private readonly cache;
-    constructor(storage: ContentStorage, config?: ContentStoreConfig);
+    private readonly db;
+    readonly tree: TurnTree;
+    readonly blobs: BlobStore;
+    private readonly roleCache;
+    private readonly preferenceCache;
+    private readonly contextCache;
+    /**
+     * Called after any blob registry change with the sha256 and updated
+     * BlobRecord (null on deletion). Wire this to your state manager to
+     * keep Index.blobs current.
+     *
+     * ContentStore sets this on BlobStore.onRegistryChanged internally.
+     * Consumers set this property to receive the forwarded notifications.
+     */
+    onBlobRegistryChanged?: (sha256: SHA256, record: BlobRecord | null) => void;
+    private constructor();
+    static create(db: WorkspaceDatabase, blobStorage: BlobStorage, config?: ContentStoreConfig): Promise<ContentStore>;
+    private init;
     getTurnTree(): TurnTree;
     getRole(name: string): Promise<Result<Role, WorkspaceError>>;
-    getPreference(id: UUID): Promise<Result<Preference, WorkspaceError>>;
-    getContext(key: string): Promise<Result<Context, WorkspaceError>>;
-    getContextByTopics(indexState: Index, topics: string[]): Promise<Context[]>;
     saveRole(role: Role): Promise<void>;
-    savePreference(preference: Preference): Promise<void>;
-    saveContext(context: Context): Promise<void>;
     deleteRole(name: string): Promise<void>;
+    getPreference(id: UUID): Promise<Result<Preference, WorkspaceError>>;
+    savePreference(preference: Preference): Promise<void>;
     deletePreference(id: UUID): Promise<void>;
+    getContext(key: string): Promise<Result<Context, WorkspaceError>>;
+    saveContext(context: Context): Promise<void>;
     deleteContext(key: string): Promise<void>;
+    getContextByTopics(indexState: Index, topics: string[]): Promise<Context[]>;
+    saveSession(meta: SessionMeta): Promise<void>;
+    updateSessionMeta(sessionId: UUID, patch: DeepPartial<SessionMeta>): Promise<void>;
+    deleteSession(sessionId: UUID): Promise<void>;
+    registerBlob(data: Uint8Array, mediaType: BlobMediaType, filename?: string): Promise<Result<BlobRef, WorkspaceError>>;
+    retainBlob(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
+    releaseBlob(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
+    purgeBlob(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
+    recordBlobRemoteId(sha256: SHA256, providerId: string, fileId: string): Promise<Result<void, WorkspaceError>>;
+    getBlobRecord(sha256: SHA256): BlobRecord | null;
+    getAllBlobRecords(): Record<SHA256, BlobRecord>;
+    /**
+     * Returns the blob resolver function expected by PromptBuilder.
+     * Closes over the internal BlobStore — no BlobStore reference leaks out.
+     */
+    getBlobResolver(): BlobStore['resolveRefs'];
     recordTurn(sessionId: UUID, turn: Turn): Promise<Result<void, WorkspaceError>>;
     editTurn(sessionId: UUID, turnId: UUID, newBlocks: ContentBlock[], newVersion: number, roleSnapshot?: string): Promise<Result<void, WorkspaceError>>;
     branchTurn(sessionId: UUID, newTurn: Turn): Promise<Result<void, WorkspaceError>>;
     deleteTurnSubtree(sessionId: UUID, turnId: UUID, version: number, newHead: TurnRef | null): Promise<Result<void, WorkspaceError>>;
     copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
-    storeBytes(sha256: SHA256, data: Uint8Array): Promise<void>;
-    loadBytes(sha256: SHA256): Promise<Uint8Array | null>;
-    deleteBytes(sha256: SHA256): Promise<void>;
     resolveSession(workspace: Workspace, sessionId: UUID, transcript?: Turn[]): Promise<Result<EffectiveSession, WorkspaceError>>;
 }
 
@@ -771,6 +1190,12 @@ declare function workspaceReducer({ index: state }: Workspace, command: Command)
 
 declare class WorkspaceManager {
     private readonly contentStore;
+    /**
+     * Called when BlobStore triggers a registry change outside of a dispatch()
+     * call — e.g. eagerEviction deleting a blob on release. The caller should
+     * merge this patch into their Workspace.
+     */
+    onWorkspacePatch?: (patch: DeepPartial<Workspace>) => void;
     constructor(contentStore: ContentStore);
     reduce(workspace: Workspace, command: Command): Result<DeepPartial<Workspace>, WorkspaceError>;
     dispatch(workspace: Workspace, command: Command): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
@@ -902,18 +1327,6 @@ declare function buildTurnNode(turn: Turn, children?: UUID[]): TurnNode;
 interface SessionManagerConfig {
     flush?: Partial<FlushConfig>;
 }
-/**
- * Returned by SessionManager.open().
- *
- * session — the live Session instance. Store this in your component or
- *           module; pass it to every subsequent session.* call.
- *
- * patch   — a DeepPartial<Workspace> that the caller should merge into
- *           their Workspace immediately after open(). Currently empty
- *           (the Workspace index already holds SessionMeta), but present
- *           for forward compatibility — future versions may update head
- *           or flushedTurnCount as part of opening.
- */
 interface OpenResult {
     session: Session;
     patch: DeepPartial<Workspace>;
@@ -928,4 +1341,71 @@ declare class SessionManager {
     get workspace(): WorkspaceManager;
 }
 
-export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTurn, type BaseCommand, type BlobMediaType, type BlobRecord, type BlobRef, type BlobStorage, BlobStore, type BlobStoreConfig, type BranchInfo, type BranchTurn, type CacheConfig, type Command, type ContentBlock, type ContentStorage, ContentStore, type ContentStoreConfig, type Context, type ContextContent, type ContextRelevanceConfig, type ContextSummary, type CreateSession, type CreateWorkspace, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type EditTurn, type EffectiveSession, type FlushConfig, type ForkSession, type ImageBlock, type ImageMediaType, type Index, type IndexedDBConfig, IndexedDBStorage, type OpenResult, type OverrideSessionPreferences, type Preference, type PreferenceConflict, type PreferenceSummary, type Project, type Prompt, PromptBuilder, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type ResolvedBlob, type Result, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, Session, SessionManager, type SessionManagerConfig, type SessionMeta, type Settings, type SummaryBlock, type SwitchRole, type TextBlock, type ThinkingBlock, type Timestamp, type TokenBudget, type ToolResultBlock, type ToolUseBlock, type TopicIndex, type TranscriptWindow, type Turn, type TurnNode, type TurnRef, type TurnRole, TurnTree, type URI, type UUID, type UpdateContext, type UpdatePreference, type UpdateRole, type Workspace, type WorkspaceBundle, type WorkspaceError, WorkspaceManager, buildTurnNode, computeSHA256, del, err, merge, ok, workspaceReducer };
+/**
+ * In-process implementation backed by plain Maps.
+ * Suitable for development, testing, and server-side runtimes without
+ * access to IndexedDB.
+ */
+declare class MemoryBlobStorage implements BlobStorage {
+    private readonly bytes;
+    private readonly records;
+    storeBytes(sha256: SHA256, data: Uint8Array): Promise<void>;
+    loadBytes(sha256: SHA256): Promise<Uint8Array | null>;
+    hasBytes(sha256: SHA256): Promise<boolean>;
+    deleteBytes(sha256: SHA256): Promise<void>;
+    saveRecord(record: BlobRecord): Promise<void>;
+    loadRecord(sha256: SHA256): Promise<BlobRecord | null>;
+    deleteRecord(sha256: SHA256): Promise<void>;
+    listRecords(): Promise<BlobRecord[]>;
+    exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
+    /**
+     * Atomic register for MemoryBlobStorage — sequential ops are atomic
+     * in a single-threaded JS runtime, so this is equivalent to two separate
+     * calls, but we implement it for interface consistency.
+     */
+    registerBlob(record: BlobRecord, data: Uint8Array): Promise<void>;
+}
+
+interface IndexedDBBlobConfig {
+    /** Name of the IndexedDB database. Defaults to 'aiworkspace-blobs'. */
+    dbName?: string;
+}
+/**
+ * IndexedDB-backed blob storage.
+ *
+ * Bytes are stored as raw Uint8Array — IndexedDB handles binary natively,
+ * no base64 encoding at rest. This is important for large files.
+ *
+ * Transaction discipline: never await inside an active transaction.
+ * All multi-step operations chain synchronous IDB request handlers
+ * inside a single Promise.
+ */
+declare class IndexedDBBlobStorage implements BlobStorage {
+    private readonly dbName;
+    private db;
+    constructor(config?: IndexedDBBlobConfig);
+    open(): Promise<void>;
+    private createSchema;
+    close(): void;
+    deleteDatabase(): Promise<void>;
+    private getDB;
+    private readTx;
+    private writeTx;
+    storeBytes(sha256: SHA256, data: Uint8Array): Promise<void>;
+    loadBytes(sha256: SHA256): Promise<Uint8Array | null>;
+    hasBytes(sha256: SHA256): Promise<boolean>;
+    deleteBytes(sha256: SHA256): Promise<void>;
+    saveRecord(record: BlobRecord): Promise<void>;
+    loadRecord(sha256: SHA256): Promise<BlobRecord | null>;
+    deleteRecord(sha256: SHA256): Promise<void>;
+    listRecords(): Promise<BlobRecord[]>;
+    exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
+    /**
+     * Atomically stores bytes and saves a record together.
+     * Preferred over calling storeBytes + saveRecord separately when both
+     * are new — avoids a window where bytes exist without a record.
+     */
+    registerBlob(record: BlobRecord, data: Uint8Array): Promise<void>;
+}
+
+export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTurn, type BaseCommand, type BlobCommand, type BlobMediaType, type BlobRecord, type BlobRef, type BlobStorage, BlobStore, type BlobStoreConfig, type BranchInfo, type BranchTurn, COLLECTIONS, type CacheConfig, type CollectionName, type Command, type ContentBlock, ContentStore, type ContentStoreConfig, type Context, type ContextContent, type ContextRelevanceConfig, type ContextSummary, type CreateSession, type CreateWorkspace, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type EditTurn, type EffectiveSession, type FlushConfig, type ForkSession, type ImageBlock, type ImageMediaType, type Index, type IndexedDBBlobConfig, IndexedDBBlobStorage, MemoryBlobStorage, type OpenResult, type OverrideSessionPreferences, type Preference, type PreferenceConflict, type PreferenceSummary, type Project, type Prompt, PromptBuilder, type PurgeBlob, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type ResolvedBlob, type Result, type RetainBlob, type Role, type RoleSummary, type RoleTransitionBlock, type SHA256, Session, SessionManager, type SessionManagerConfig, type SessionMeta, type Settings, type SummaryBlock, type SwitchRole, type TextBlock, type ThinkingBlock, type Timestamp, type TokenBudget, type ToolResultBlock, type ToolUseBlock, type TopicIndex, type TranscriptWindow, type Turn, type TurnNode, type TurnRef, type TurnRole, TurnTree, type URI, type UUID, type UpdateContext, type UpdatePreference, type UpdateRole, type Workspace, type WorkspaceBundle, type WorkspaceDatabase, type WorkspaceError, WorkspaceManager, buildTurnNode, computeSHA256, createSimpleWorkspace, createWorkspaceDatabase, del, err, extractBlobRecord, extractBlobRef, merge, ok, omitNullUndefined, workspaceReducer };