@asaidimu/utils-workspace 1.0.0 → 2.0.0

package/index.d.ts

@@ -9,8 +9,6 @@ type Result<T, E = WorkspaceError> = {
     ok: false;
     error: E;
 };
-declare function ok<T>(value: T): Result<T, never>;
-declare function err<E = WorkspaceError>(error: E): Result<never, E>;
 type WorkspaceError = {
     code: 'DUPLICATE_KEY';
     resource: string;
@@ -43,13 +41,12 @@ interface Project {
 type ImageMediaType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
 type DocumentMediaType = 'application/pdf' | 'application/json' | 'text/plain' | 'text/html' | 'text/markdown' | 'text/csv' | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
 type BlobMediaType = ImageMediaType | DocumentMediaType;
-interface BlobRef {
-    sha256: SHA256;
-    mediaType: BlobMediaType;
-    sizeBytes: number;
-    filename?: string;
-    previewUrl?: string;
-}
+/**
+ * Lightweight pointer to a blob — the subset of BlobRecord that content
+ * blocks and context entries carry. Use this at call sites that only need
+ * to reference a blob, not inspect its registry metadata.
+ */
+type BlobRef = Pick<BlobRecord, 'sha256' | 'mediaType' | 'sizeBytes' | 'filename' | 'previewUrl'>;
 type ResolvedBlob = {
     kind: 'inline';
     sha256: SHA256;
@@ -62,37 +59,36 @@ type ResolvedBlob = {
     fileId: string;
     providerId: string;
 };
+/**
+ * Full registry entry for a blob. BlobRef is a Pick of this type, so
+ * a BlobRecord is always assignable to BlobRef. BlobSummary has been
+ * removed — callers that previously used BlobSummary use BlobRecord directly.
+ */
 interface BlobRecord {
     sha256: SHA256;
     mediaType: BlobMediaType;
     sizeBytes: number;
     filename?: string;
+    previewUrl?: string;
     refCount: number;
     remoteIds: Record<string, string>;
     createdAt: Timestamp;
     lastUsedAt: Timestamp;
 }
-interface BlobSummary {
-    sha256: SHA256;
-    mediaType: BlobMediaType;
-    sizeBytes: number;
-    filename?: string;
-    refCount: number;
-    createdAt: Timestamp;
-    lastUsedAt: Timestamp;
-}
 interface TextBlock {
     type: 'text';
     text: string;
 }
 interface ImageBlock {
     type: 'image';
-    blob: ResolvedBlob;
+    ref?: BlobRef;
+    blob?: ResolvedBlob;
     altText?: string;
 }
 interface DocumentBlock {
     type: 'document';
-    blob: ResolvedBlob;
+    ref?: BlobRef;
+    blob?: ResolvedBlob;
     title?: string;
 }
 interface ToolUseBlock {
@@ -111,7 +107,16 @@ interface ThinkingBlock {
     type: 'thinking';
     thinking: string;
 }
-type ContentBlock = TextBlock | ImageBlock | DocumentBlock | ToolUseBlock | ToolResultBlock | ThinkingBlock;
+interface SummaryBlock {
+    type: 'summary';
+    text: string;
+}
+interface RoleTransitionBlock {
+    type: 'role_transition';
+    previousRole: string | null;
+    newRole: string;
+}
+type ContentBlock = TextBlock | ImageBlock | DocumentBlock | ToolUseBlock | ToolResultBlock | SummaryBlock | RoleTransitionBlock | ThinkingBlock;
 type TurnRole = 'user' | 'assistant' | 'tool';
 interface Turn {
     id: UUID;
@@ -125,14 +130,31 @@ interface Turn {
         version: number;
     } | null;
 }
-interface SessionSummary {
+interface TurnNode {
     id: UUID;
-    label: string;
-    role: string;
-    topics: string[];
-    created: Timestamp;
-    updated: Timestamp;
-    turns: number;
+    versions: Record<number, Turn>;
+    activeVersion: number;
+    role: TurnRole;
+    blocks: ContentBlock[];
+    timestamp: Timestamp;
+    roleSnapshot?: string;
+    parent: {
+        id: UUID;
+        version: number;
+    } | null;
+    children: Record<number, UUID[]>;
+}
+interface 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 {
     name: string;
@@ -166,27 +188,19 @@ interface TopicIndex {
         entries?: number;
     };
 }
-interface Indexes {
-    sessions: Record<UUID, SessionSummary>;
-    roles: Record<string, RoleSummary>;
-    preferences: Record<UUID, PreferenceSummary>;
-    context: Record<string, ContextSummary>;
-    topics: Record<string, TopicIndex>;
-}
 interface Workspace {
     id: UUID;
     settings: Settings;
     project: Project;
-    indexes: Indexes;
+    index: Index;
 }
-interface IndexState {
+interface Index {
     format: string;
-    workspace: Workspace;
     roles: Record<string, RoleSummary>;
     preferences: Record<UUID, PreferenceSummary>;
     context: Record<string, ContextSummary>;
     sessions: Record<UUID, SessionMeta>;
-    blobs: Record<SHA256, BlobSummary>;
+    topics: Record<string, TopicIndex>;
 }
 interface SessionMeta {
     id: UUID;
@@ -220,13 +234,27 @@ interface Preference {
 }
 interface Context {
     key: string;
-    content: string | object | URI;
+    content: ContextContent;
     topics: string[];
     timestamp: Timestamp;
     metadata?: Record<string, any>;
-    attachments?: BlobRef[];
+    remoteIds?: Record<string, string>;
+    refCount?: number;
 }
-interface Session {
+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;
@@ -244,7 +272,7 @@ interface WorkspaceBundle {
     roles: Record<string, Role>;
     preferences: Record<UUID, Preference>;
     context: Record<string, Context>;
-    sessions: Record<UUID, Session>;
+    sessions: Record<UUID, Session$1>;
     blobs: Record<SHA256, BlobRecord>;
 }
 interface TranscriptWindow {
@@ -259,12 +287,12 @@ interface EffectiveSession {
     preferences: Preference[];
     context: Context[];
     transcript: Turn[];
-    systemPrompt?: string;
+    instructions?: string;
 }
 interface CacheConfig {
     roles?: number;
     preferences?: number;
-    contextEntries?: number;
+    context?: number;
     transcriptWindows?: number;
 }
 interface FlushConfig {
@@ -385,13 +413,6 @@ interface DeleteTurn extends BaseCommand {
         } | null;
     };
 }
-interface AddInteraction extends BaseCommand {
-    type: 'turn:add';
-    payload: {
-        sessionId: UUID;
-        turn: Turn;
-    };
-}
 interface SwitchRole extends BaseCommand {
     type: 'session:role:switch';
     payload: {
@@ -464,21 +485,35 @@ interface ContextRelevanceConfig {
     minScore?: number;
     freshnessHalfLifeDays?: number;
 }
-interface BuiltTurn {
-    role: TurnRole;
-    blocks: ContentBlock[];
-}
+/**
+ * BuiltTurn has been removed. Prompt.transcript.turns is now Turn[].
+ * Synthetic turns produced by PromptAssembler (summary blocks, truncation
+ * notices, referential attachments) carry generated UUIDs and version 0,
+ * with parent: null. They are ephemeral — never stored, never patched.
+ */
 interface Prompt {
-    system: string | null;
-    turns: BuiltTurn[];
-    blobs: BlobRef[];
+    system: {
+        instructions?: string;
+        persona: string;
+        preferences: Preference[];
+        context: Context[];
+    };
+    context: Context[];
+    transcript: {
+        turns: Turn[];
+    };
+    budget: {
+        total: number;
+        used: number;
+        breakdown: Record<string, number>;
+    };
     truncated: {
         preferences: number;
         interactions: number;
-        contextEntries: number;
+        context: number;
     };
-    conflicts: PreferenceConflict[];
     warnings: string[];
+    conflicts: PreferenceConflict[];
 }
 
 interface ContentStorage {
@@ -490,10 +525,12 @@ interface ContentStorage {
     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, limit?: number): Promise<Turn[]>;
+    loadAllTurns(sessionId: UUID): Promise<Turn[]>;
+    deleteTurn(sessionId: UUID, turnId: UUID, version: number): Promise<void>;
     setSessionHead(sessionId: UUID, head: {
         id: UUID;
         version: number;
@@ -502,45 +539,10 @@ interface ContentStorage {
         id: UUID;
         version: number;
     } | null>;
-    deleteTurnSubtree(sessionId: UUID, turnId: UUID, version: number): Promise<void>;
-    getActiveChain(sessionId: UUID): Promise<Turn[]>;
-    countChainedTurns(sessionId: UUID): Promise<number>;
-    copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
-}
-declare class MemoryStorage implements ContentStorage {
-    private readonly roles;
-    private readonly preferences;
-    private readonly contexts;
-    private readonly turnVersions;
-    private readonly sessionHeads;
-    saveRole(role: Role): Promise<void>;
-    loadRole(name: string): Promise<Role | null>;
-    deleteRole(name: string): Promise<void>;
-    savePreference(preference: Preference): Promise<void>;
-    loadPreference(id: UUID): Promise<Preference | null>;
-    deletePreference(id: UUID): Promise<void>;
-    saveContext(context: Context): Promise<void>;
-    loadContext(key: string): Promise<Context | null>;
-    deleteContext(key: string): Promise<void>;
-    saveTurn(sessionId: UUID, turn: Turn): Promise<void>;
-    loadTurn(sessionId: UUID, turnId: UUID, version: number): Promise<Turn | null>;
-    loadAllTurns(sessionId: UUID, limit?: number): Promise<Turn[]>;
-    setSessionHead(sessionId: UUID, head: {
-        id: UUID;
-        version: number;
-    } | null): Promise<void>;
-    getSessionHead(sessionId: UUID): Promise<{
-        id: UUID;
-        version: number;
-    } | null>;
-    getActiveChain(sessionId: UUID): Promise<Turn[]>;
-    deleteTurnSubtree(sessionId: UUID, turnId: UUID, version: number): Promise<void>;
-    countChainedTurns(sessionId: UUID): Promise<number>;
-    copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
-    static fromBundle(bundle: WorkspaceBundle): {
-        backend: MemoryStorage;
-        indexState: IndexState;
-    };
+    storeBytes(sha256: SHA256, data: Uint8Array): Promise<void>;
+    loadBytes(sha256: SHA256): Promise<Uint8Array | null>;
+    deleteBytes(sha256: SHA256): Promise<void>;
+    exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
 }
 
 /**
@@ -556,6 +558,8 @@ type DeepPartial<T> = T extends object ? T extends readonly (infer U)[] ? readon
 
 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;
@@ -579,11 +583,12 @@ declare class IndexedDBStorage implements ContentStorage {
     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>;
-    loadAllTurns(sessionId: UUID, limit?: number): Promise<Turn[]>;
-    countChainedTurns(sessionId: UUID): Promise<number>;
     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;
@@ -592,24 +597,25 @@ declare class IndexedDBStorage implements ContentStorage {
         id: UUID;
         version: number;
     } | null>;
-    getActiveChain(sessionId: UUID): Promise<Turn[]>;
-    deleteTurnSubtree(sessionId: UUID, turnId: UUID, version: number): Promise<void>;
-    copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
-    saveIndexState(state: IndexState): Promise<void>;
-    loadIndexState(): Promise<IndexState | null>;
+    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[]>;
-        indexState: IndexState | null;
+        workspace: Workspace | null;
     }>;
     importBundle(data: {
         roles: Record<string, Role>;
         preferences: Record<UUID, Preference>;
         context: Record<string, Context>;
         transcripts: Record<UUID, Turn[]>;
-        indexState?: IndexState;
+        workspace?: Workspace;
     }): Promise<void>;
     private getAllFromStore;
 }
@@ -652,65 +658,33 @@ interface BlobStorage {
      * Used for workspace export / migration.
      */
     exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
-}
-/**
- * In-process implementation backed by plain Maps.
- * Suitable for development, testing, and server-side runtimes without
- * access to IndexedDB.
- */
-declare class MemoryBlobStorage implements BlobStorage {
-    private readonly bytes;
-    private readonly records;
-    storeBytes(sha256: SHA256, data: Uint8Array): Promise<void>;
-    loadBytes(sha256: SHA256): Promise<Uint8Array | null>;
-    hasBytes(sha256: SHA256): Promise<boolean>;
-    deleteBytes(sha256: SHA256): Promise<void>;
-    saveRecord(record: BlobRecord): Promise<void>;
-    loadRecord(sha256: SHA256): Promise<BlobRecord | null>;
-    deleteRecord(sha256: SHA256): Promise<void>;
-    listRecords(): Promise<BlobRecord[]>;
-    exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
-}
-interface IndexedDBBlobConfig {
-    /** Name of the IndexedDB database. Defaults to 'aiworkspace-blobs'. */
-    dbName?: string;
-}
-/**
- * IndexedDB-backed blob storage.
- *
- * Bytes are stored as raw Uint8Array — IndexedDB handles binary natively,
- * no base64 encoding at rest. This is important for large files.
- *
- * Transaction discipline matches IndexedDBBlobStorage: never await inside an
- * active transaction. All multi-step operations chain synchronous IDB
- * request handlers inside a single Promise.
- */
-declare class IndexedDBBlobStorage implements BlobStorage {
-    private readonly dbName;
-    private db;
-    constructor(config?: IndexedDBBlobConfig);
-    open(): Promise<void>;
-    private createSchema;
-    close(): void;
-    deleteDatabase(): Promise<void>;
-    private getDB;
-    private readTx;
-    private writeTx;
-    storeBytes(sha256: SHA256, data: Uint8Array): Promise<void>;
-    loadBytes(sha256: SHA256): Promise<Uint8Array | null>;
-    hasBytes(sha256: SHA256): Promise<boolean>;
-    deleteBytes(sha256: SHA256): Promise<void>;
-    saveRecord(record: BlobRecord): Promise<void>;
-    loadRecord(sha256: SHA256): Promise<BlobRecord | null>;
-    deleteRecord(sha256: SHA256): Promise<void>;
-    listRecords(): Promise<BlobRecord[]>;
-    exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
     /**
-     * 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.
+     * Optional atomic operation: store bytes and save record in a single
+     * transaction. Backends that support this (e.g. IndexedDB) should
+     * implement it to avoid a window where bytes exist without a record.
+     * BlobStore will prefer this over calling storeBytes + saveRecord separately.
      */
-    registerBlob(record: BlobRecord, data: Uint8Array): Promise<void>;
+    registerBlob?(record: BlobRecord, data: Uint8Array): Promise<void>;
+}
+
+interface TurnRef {
+    id: UUID;
+    version: number;
+}
+declare class TurnTree {
+    private readonly storage;
+    constructor(storage: ContentStorage);
+    append(sessionId: UUID, turn: Turn): Promise<Turn>;
+    appendBatch(sessionId: UUID, turns: Turn[]): Promise<void>;
+    replaceVersion(sessionId: UUID, newTurn: Turn): Promise<void>;
+    branch(sessionId: UUID, newTurn: Turn): Promise<void>;
+    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>;
@@ -718,13 +692,12 @@ interface BlobStoreConfig {
     /**
      * When true, blobs with refCount === 0 are deleted from the backend
      * immediately on release. When false (default), they are retained until
-     * an explicit GC sweep via gc(). Lazy GC is safer for offline-first apps
-     * that may need blobs for re-upload after a crash.
+     * an explicit GC sweep via gc(). Lazy GC is safer for offline-first apps.
      */
     eagerEviction?: boolean;
 }
 declare class BlobStore {
-    private readonly backend;
+    private readonly storage;
     private readonly config;
     /**
      * In-memory cache of BlobRecords. Kept consistent with the backend on
@@ -733,61 +706,22 @@ declare class BlobStore {
     private readonly recordCache;
     /**
      * Called after any operation that changes the blob registry.
-     * The integration layer wires this to an IndexState patch that updates
-     * IndexState.blobs with the new BlobSummary.
+     * Passes the full BlobRecord (or null on deletion). The integration
+     * layer wires this to an Index patch that updates the blob index.
+     *
+     * BlobRecord is a superset of the former BlobSummary — callers
+     * that only need summary fields (sha256, mediaType, sizeBytes, etc.)
+     * can read them directly from BlobRecord without a separate type.
      */
-    onRegistryChanged?: (sha256: SHA256, summary: BlobSummary | null) => void;
+    onRegistryChanged?: (sha256: SHA256, record: BlobRecord | null) => void;
     constructor(backend: BlobStorage, config?: BlobStoreConfig);
     init(): Promise<void>;
-    /**
-     * Register a binary blob and return a BlobRef.
-     *
-     * If the same bytes have been registered before (same SHA-256), only the
-     * ref count is incremented — bytes are not written again.
-     *
-     * @param data      Raw binary content.
-     * @param mediaType MIME type of the content.
-     * @param filename  Optional original filename for UI display.
-     */
     register(data: Uint8Array, mediaType: BlobMediaType, filename?: string): Promise<Result<BlobRef, WorkspaceError>>;
-    /**
-     * Increment the ref count for a blob that is being referenced by a new
-     * turn or context entry. Safe to call multiple times for the same sha256.
-     */
     retain(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
-    /**
-     * Decrement the ref count. When it reaches 0, the blob is eligible for
-     * eviction. With eagerEviction=true, bytes are deleted immediately.
-     * With eagerEviction=false, bytes are retained until gc() is called.
-     */
     release(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
-    /**
-     * Record that a blob has been uploaded to a provider and assigned a file ID.
-     * Idempotent — calling with the same providerId + fileId has no effect.
-     */
     recordRemoteId(sha256: SHA256, providerId: string, fileId: string): Promise<Result<void, WorkspaceError>>;
-    /**
-     * Get the remote file ID for a blob on a specific provider, if known.
-     */
     getRemoteId(sha256: SHA256, providerId: string): string | null;
-    /**
-     * Resolve a BlobRef to a ResolvedBlob.
-     *
-     * If a remote file ID is known for the given providerId, returns
-     * { kind: 'remote' } — no bytes transferred to the model call.
-     * Otherwise loads bytes from the backend and returns { kind: 'inline' }.
-     *
-     * @param ref        The BlobRef to resolve.
-     * @param providerId The provider the resolved blob will be sent to
-     *                   (e.g. 'anthropic', 'openai'). Used to look up
-     *                   known remote file IDs. Pass null for local-only use.
-     */
     resolveRef(ref: BlobRef, providerId: string | null): Promise<Result<ResolvedBlob, WorkspaceError>>;
-    /**
-     * Resolve multiple BlobRefs, collecting all results.
-     * Returns a map of sha256 → ResolvedBlob for successes and a list of
-     * errors for failures, so partial failures don't block the whole build.
-     */
     resolveRefs(refs: BlobRef[], providerId: string | null): Promise<{
         resolved: Map<SHA256, ResolvedBlob>;
         errors: Array<{
@@ -795,74 +729,52 @@ declare class BlobStore {
             error: WorkspaceError;
         }>;
     }>;
-    /**
-     * Delete bytes for all blobs with refCount === 0.
-     * Records are kept so re-registration is cheap (no re-hash needed).
-     * Call this periodically or on app startup to reclaim storage.
-     *
-     * Returns the number of blobs whose bytes were evicted.
-     */
     gc(): Promise<number>;
-    /**
-     * Fully purge a blob — delete both bytes and record regardless of refCount.
-     * Only use this for explicit user-initiated deletion or during workspace
-     * destruction. In normal operation, use release() and let GC handle it.
-     */
+    gcFull(): Promise<number>;
     purge(sha256: SHA256): Promise<Result<void, WorkspaceError>>;
     getRecord(sha256: SHA256): BlobRecord | null;
-    getSummary(sha256: SHA256): BlobSummary | null;
-    /** All summaries — used to seed IndexState.blobs on init. */
-    getAllSummaries(): Record<SHA256, BlobSummary>;
+    /**
+     * All records — used to seed Index.blobs on init.
+     * Returns BlobRecord directly (BlobSummary has been removed).
+     */
+    getAllRecords(): Record<SHA256, BlobRecord>;
 }
 
 declare class ContentStore {
     private readonly storage;
+    private readonly tree;
     private readonly cache;
-    private readonly config;
-    private activeSession;
-    private pinnedPreferenceIds;
-    onFlushed?: (sessionId: UUID, flushedCount: number) => void;
-    onSessionInvalidated?: (sessionId: UUID) => void;
-    constructor(backend: ContentStorage, config?: ContentStoreConfig);
-    getActiveSessionId(): UUID | null;
+    constructor(storage: ContentStorage, config?: ContentStoreConfig);
+    getTurnTree(): TurnTree;
     getRole(name: string): Promise<Result<Role, WorkspaceError>>;
     getPreference(id: UUID): Promise<Result<Preference, WorkspaceError>>;
     getContext(key: string): Promise<Result<Context, WorkspaceError>>;
-    getContextByTopics(indexState: IndexState, topics: string[]): Promise<Context[]>;
-    getTranscriptWindow(sessionId: UUID, windowSize?: number): Promise<TranscriptWindow>;
+    getContextByTopics(indexState: Index, topics: string[]): Promise<Context[]>;
     saveRole(role: Role): Promise<void>;
     savePreference(preference: Preference): Promise<void>;
     saveContext(context: Context): Promise<void>;
-    copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
     deleteRole(name: string): Promise<void>;
     deletePreference(id: UUID): Promise<void>;
     deleteContext(key: string): Promise<void>;
     recordTurn(sessionId: UUID, turn: Turn): Promise<Result<void, WorkspaceError>>;
     editTurn(sessionId: UUID, turnId: UUID, newBlocks: ContentBlock[], newVersion: number, roleSnapshot?: string): Promise<Result<void, WorkspaceError>>;
     branchTurn(sessionId: UUID, newTurn: Turn): Promise<Result<void, WorkspaceError>>;
-    deleteTurnSubtree(sessionId: UUID, turnId: UUID, version: number, newHead: {
-        id: UUID;
-        version: number;
-    } | null): Promise<Result<void, WorkspaceError>>;
-    activateSession(meta: SessionMeta): Promise<Result<void, WorkspaceError>>;
-    deactivateSession(meta?: SessionMeta): Promise<void>;
-    resolveSession(indexState: IndexState, sessionId: UUID): Promise<Result<EffectiveSession, WorkspaceError>>;
-    flush(): Promise<void>;
-    dispose(): Promise<void>;
+    deleteTurnSubtree(sessionId: UUID, turnId: UUID, version: number, newHead: TurnRef | null): Promise<Result<void, WorkspaceError>>;
+    copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
+    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>>;
 }
 
-declare function workspaceReducer(state: IndexState, command: Command): Result<DeepPartial<IndexState>, WorkspaceError>;
+declare function workspaceReducer({ index: state }: Workspace, command: Command): Result<DeepPartial<Workspace>, WorkspaceError>;
 
 declare class WorkspaceManager {
     private readonly contentStore;
     constructor(contentStore: ContentStore);
-    reduce(indexState: IndexState, command: Command): Result<DeepPartial<IndexState>, WorkspaceError>;
-    dispatch(indexState: IndexState, command: Command): Promise<Result<DeepPartial<IndexState>, WorkspaceError>>;
-    resolveSession(indexState: IndexState, sessionId: UUID): Promise<Result<EffectiveSession, WorkspaceError>>;
-    activateSession(indexState: IndexState, sessionId: UUID): Promise<Result<void, WorkspaceError>>;
-    deactivateSession(indexState?: IndexState): Promise<void>;
-    flush(): Promise<void>;
-    dispose(): Promise<void>;
+    reduce(workspace: Workspace, command: Command): Result<DeepPartial<Workspace>, WorkspaceError>;
+    dispatch(workspace: Workspace, command: Command): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    resolveSession(workspace: Workspace, sessionId: UUID): Promise<Result<EffectiveSession, WorkspaceError>>;
     private handleContentSideEffects;
 }
 
@@ -873,27 +785,147 @@ interface Summarizer {
     }>;
 }
 
+interface ContextRankingInput {
+    entries: Context[];
+    recentMessages: string[];
+    config: ContextRelevanceConfig;
+}
+interface ContextRetriever {
+    rank(input: ContextRankingInput): Context[];
+}
+interface PlanningInput {
+    systemInstructions?: string;
+    persona: string;
+    preferences: Preference[];
+    context: Context[];
+    transcript: Turn[];
+    budget?: TokenBudget;
+}
+interface PlanningOutput {
+    preferences: Preference[];
+    context: Context[];
+    transcript: Turn[];
+    truncated: {
+        preferences: number;
+        interactions: number;
+        context: number;
+    };
+    breakdown: Record<string, number>;
+    totalUsed: number;
+    lastRoleBeforeTruncation: string | null;
+}
+interface TokenPlanner {
+    plan(input: PlanningInput): PlanningOutput;
+}
+interface AssemblyInput {
+    session: EffectiveSession;
+    plan: PlanningOutput;
+    resolvedBlobs: Map<SHA256, ResolvedBlob>;
+    summaryBlockText: string | null;
+    warnings: string[];
+    conflicts: PreferenceConflict[];
+    budgetTotal: number;
+}
+declare class PromptAssembler {
+    assemble(input: AssemblyInput): Prompt;
+    private buildReferentialBlock;
+    private resolveTurnBlocks;
+}
 declare class PromptBuilder {
-    private readonly summarizer?;
-    constructor(summarizer?: Summarizer);
-    /**
-     * Build a provider-agnostic BuildResult from an EffectiveSession.
-     *
-     * IMPORTANT: blobs in the session's turns must be pre-resolved before
-     * calling build(). Pass the resolved map via options.resolvedBlobs.
-     * Any blob whose SHA-256 is not in resolvedBlobs will be omitted from
-     * the output with a warning.
-     *
-     * @param effectiveSession  The resolved session (from ContentStore.resolveSession).
-     * @param options.resolvedBlobs  Map of sha256 → ResolvedBlob from BlobStore.resolveRefs().
-     * @param options.tokenBudget    Optional token budget for truncation.
-     * @param options.relevanceConfig Optional context ranking config.
-     */
-    build(effectiveSession: EffectiveSession, options?: {
-        resolvedBlobs?: Map<SHA256, ResolvedBlob>;
+    private retriever;
+    private planner;
+    private assembler;
+    private summarizer?;
+    private blobResolver;
+    constructor(dependencies: {
+        blobResolver: BlobStore['resolveRefs'];
+        retriever?: ContextRetriever;
+        planner?: TokenPlanner;
+        assembler?: PromptAssembler;
+        summarizer?: Summarizer;
+    });
+    build(session: EffectiveSession, options?: {
         tokenBudget?: TokenBudget;
         relevanceConfig?: ContextRelevanceConfig;
+        providerId?: string;
     }): Promise<Prompt>;
+    private collectUsedBlobRefs;
+    private deduplicateBlobRefs;
+    private extractRecentUserQueries;
+    private resolvePreferenceConflicts;
+}
+
+declare class Session {
+    /** The session ID this object manages. */
+    readonly sessionId: UUID;
+    /**
+     * The turn DAG. Keys are turn IDs. Mutated in-place on every write.
+     * Callers read this directly for rendering — no copy is made.
+     */
+    readonly nodes: Record<UUID, TurnNode>;
+    /**
+     * Current head of the active branch. Mirrors what is in
+     * workspace.index.sessions[sessionId].head after each patch is applied.
+     * Session keeps its own copy so reads don't require workspace.
+     */
+    private head;
+    /** Turns not yet flushed to storage. */
+    private readonly dirtyBuffer;
+    private flushTimer;
+    private flushChain;
+    private readonly flushConfig;
+    private readonly tree;
+    private readonly contentStore;
+    constructor(sessionId: UUID, nodes: Record<UUID, TurnNode>, head: TurnRef | null, tree: TurnTree, contentStore: ContentStore, flushConfig?: FlushConfig);
+    activeChain(): TurnNode[];
+    siblings(turnId: UUID): TurnNode[];
+    branchInfo(turnId: UUID): BranchInfo;
+    addTurn(workspace: Workspace, turn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    editTurn(workspace: Workspace, turnId: UUID, newBlocks: ContentBlock[], roleSnapshot?: string): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    branchFrom(workspace: Workspace, newTurn: Turn): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    deleteTurn(workspace: Workspace, turnId: UUID, version: number, newHead: TurnRef | null): Promise<Result<DeepPartial<Workspace>, WorkspaceError>>;
+    switchVersionLeft(_: Workspace, turnId: UUID): Result<DeepPartial<Workspace>, WorkspaceError>;
+    switchVersionRight(_: Workspace, turnId: UUID): Result<DeepPartial<Workspace>, WorkspaceError>;
+    private switchVersion;
+    resolve(workspace: Workspace): Promise<Result<EffectiveSession, WorkspaceError>>;
+    flush(): Promise<void>;
+    dispose(): Promise<void>;
+    private findSubtreeTipForVersion;
+    private collectSubtreeIds;
+    private upsertNode;
+    private scheduleFlush;
+    private cancelFlushTimer;
+    private doFlush;
+}
+declare function buildTurnNode(turn: Turn, children?: UUID[]): TurnNode;
+
+interface SessionManagerConfig {
+    flush?: Partial<FlushConfig>;
+}
+/**
+ * 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>;
+}
+declare class SessionManager {
+    private readonly workspaceManager;
+    private readonly contentStore;
+    private readonly flushConfig;
+    constructor(workspaceManager: WorkspaceManager, contentStore: ContentStore, config?: SessionManagerConfig);
+    open(workspace: Workspace, sessionId: UUID): Promise<Result<OpenResult, WorkspaceError>>;
+    close(session: Session): Promise<void>;
+    get workspace(): WorkspaceManager;
 }
 
-export { type AddContext, type AddInteraction, type AddPreference, type AddRole, type AddSessionTopics, type AddTurn, type BaseCommand, type BlobMediaType, type BlobRecord, type BlobRef, type BlobStorage, BlobStore, type BlobStoreConfig, type BlobSummary, type BranchTurn, type BuiltTurn, type CacheConfig, type Command, type ContentBlock, type ContentStorage, ContentStore, type ContentStoreConfig, type Context, type ContextRelevanceConfig, type ContextSummary, type CreateSession, type CreateWorkspace, type DeleteContext, type DeletePreference, type DeleteRole, type DeleteSession, type DeleteTurn, type DocumentBlock, type DocumentMediaType, type EditTurn, type EffectiveSession, type FlushConfig, type ForkSession, type ImageBlock, type ImageMediaType, type IndexState, type IndexedDBBlobConfig, IndexedDBBlobStorage, type IndexedDBConfig, IndexedDBStorage, type Indexes, MemoryBlobStorage, MemoryStorage, type OverrideSessionPreferences, type Preference, type PreferenceConflict, type PreferenceSummary, type Project, type Prompt, PromptBuilder, type RecordBlobRemoteId, type RegisterBlob, type ReleaseBlob, type ResolvedBlob, type Result, type Role, type RoleSummary, type SHA256, type Session, type SessionMeta, type SessionSummary, type Settings, type SwitchRole, type TextBlock, type ThinkingBlock, type Timestamp, type TokenBudget, type ToolResultBlock, type ToolUseBlock, type TopicIndex, type TranscriptWindow, type Turn, type TurnRole, type URI, type UUID, type UpdateContext, type UpdatePreference, type UpdateRole, type Workspace, type WorkspaceBundle, type WorkspaceError, WorkspaceManager, computeSHA256, del, err, merge, ok, workspaceReducer };
+export { type AddContext, type AddPreference, type AddRole, type AddSessionTopics, type AddTurn, type BaseCommand, type 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 };