@asaidimu/utils-workspace 1.0.0

package/index.d.mts

@@ -0,0 +1,899 @@
+type UUID = string;
+type Timestamp = string;
+type URI = string;
+type SHA256 = string;
+type Result<T, E = WorkspaceError> = {
+    ok: true;
+    value: T;
+} | {
+    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;
+    key: string;
+} | {
+    code: 'NOT_FOUND';
+    resource: string;
+    id: string;
+} | {
+    code: 'INVALID_COMMAND';
+    reason: string;
+} | {
+    code: 'BACKEND_ERROR';
+    reason: string;
+} | {
+    code: 'BLOB_ERROR';
+    reason: string;
+};
+interface Settings {
+    language: string;
+    defaultRole: string;
+    prompt?: string;
+}
+interface Project {
+    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;
+interface BlobRef {
+    sha256: SHA256;
+    mediaType: BlobMediaType;
+    sizeBytes: number;
+    filename?: string;
+    previewUrl?: string;
+}
+type ResolvedBlob = {
+    kind: 'inline';
+    sha256: SHA256;
+    mediaType: BlobMediaType;
+    data: Uint8Array;
+} | {
+    kind: 'remote';
+    sha256: SHA256;
+    mediaType: BlobMediaType;
+    fileId: string;
+    providerId: string;
+};
+interface BlobRecord {
+    sha256: SHA256;
+    mediaType: BlobMediaType;
+    sizeBytes: number;
+    filename?: 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;
+    altText?: string;
+}
+interface DocumentBlock {
+    type: 'document';
+    blob: ResolvedBlob;
+    title?: string;
+}
+interface ToolUseBlock {
+    type: 'tool_use';
+    toolUseId: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface ToolResultBlock {
+    type: 'tool_result';
+    toolUseId: string;
+    content: string | Record<string, unknown>;
+    isError?: boolean;
+}
+interface ThinkingBlock {
+    type: 'thinking';
+    thinking: string;
+}
+type ContentBlock = TextBlock | ImageBlock | DocumentBlock | ToolUseBlock | ToolResultBlock | ThinkingBlock;
+type TurnRole = 'user' | 'assistant' | 'tool';
+interface Turn {
+    id: UUID;
+    version: number;
+    role: TurnRole;
+    blocks: ContentBlock[];
+    timestamp: Timestamp;
+    roleSnapshot?: string;
+    parent: {
+        id: UUID;
+        version: number;
+    } | null;
+}
+interface SessionSummary {
+    id: UUID;
+    label: string;
+    role: string;
+    topics: string[];
+    created: Timestamp;
+    updated: Timestamp;
+    turns: number;
+}
+interface RoleSummary {
+    name: string;
+    label: string;
+    description?: string;
+    preferences: number;
+}
+interface PreferenceSummary {
+    id: UUID;
+    topics: string[];
+    timestamp: Timestamp;
+    snippet?: string;
+}
+interface ContextSummary {
+    key: string;
+    topics: string[];
+    timestamp: Timestamp;
+    mime?: string;
+    size?: number;
+    preview?: string;
+    source?: string;
+    metadata?: Record<string, any>;
+}
+interface TopicIndex {
+    topic: string;
+    contextKeys: string[];
+    preferences: UUID[];
+    metadata?: {
+        created?: Timestamp;
+        updated?: Timestamp;
+        entries?: number;
+    };
+}
+interface Indexes {
+    sessions: Record<UUID, SessionSummary>;
+    roles: Record<string, RoleSummary>;
+    preferences: Record<UUID, PreferenceSummary>;
+    context: Record<string, ContextSummary>;
+    topics: Record<string, TopicIndex>;
+}
+interface Workspace {
+    id: UUID;
+    settings: Settings;
+    project: Project;
+    indexes: Indexes;
+}
+interface IndexState {
+    format: string;
+    workspace: Workspace;
+    roles: Record<string, RoleSummary>;
+    preferences: Record<UUID, PreferenceSummary>;
+    context: Record<string, ContextSummary>;
+    sessions: Record<UUID, SessionMeta>;
+    blobs: Record<SHA256, BlobSummary>;
+}
+interface SessionMeta {
+    id: UUID;
+    label: string;
+    role: string;
+    topics: string[];
+    preferences: UUID[];
+    metadata: {
+        created?: Timestamp;
+        updated?: Timestamp;
+    };
+    flushedTurnCount: number;
+    head: {
+        id: UUID;
+        version: number;
+    } | null;
+}
+interface Role {
+    id: UUID;
+    name: string;
+    label: string;
+    persona: string;
+    description?: string;
+    preferences: UUID[];
+}
+interface Preference {
+    id: UUID;
+    content: string;
+    topics: string[];
+    timestamp: Timestamp;
+}
+interface Context {
+    key: string;
+    content: string | object | URI;
+    topics: string[];
+    timestamp: Timestamp;
+    metadata?: Record<string, any>;
+    attachments?: BlobRef[];
+}
+interface Session {
+    id: UUID;
+    label: string;
+    role: string;
+    topics: string[];
+    preferences: UUID[];
+    turns: Turn[];
+    metadata: {
+        created?: Timestamp;
+        updated?: Timestamp;
+    };
+}
+interface WorkspaceBundle {
+    format: 'aiworkspace/4.0';
+    workspace: Workspace;
+    roles: Record<string, Role>;
+    preferences: Record<UUID, Preference>;
+    context: Record<string, Context>;
+    sessions: Record<UUID, Session>;
+    blobs: Record<SHA256, BlobRecord>;
+}
+interface TranscriptWindow {
+    sessionId: UUID;
+    turns: Turn[];
+    flushedCount: number;
+    hasMore: boolean;
+}
+interface EffectiveSession {
+    session: SessionMeta;
+    role: Role;
+    preferences: Preference[];
+    context: Context[];
+    transcript: Turn[];
+    systemPrompt?: string;
+}
+interface CacheConfig {
+    roles?: number;
+    preferences?: number;
+    contextEntries?: number;
+    transcriptWindows?: number;
+}
+interface FlushConfig {
+    maxBufferSize: number;
+    flushIntervalMs: number;
+}
+interface ContentStoreConfig {
+    cache?: CacheConfig;
+    flush?: FlushConfig;
+    transcriptWindowSize?: number;
+}
+interface BaseCommand {
+    type: string;
+    timestamp: Timestamp;
+    actor?: string;
+}
+interface CreateWorkspace extends BaseCommand {
+    type: 'workspace:create';
+    payload: {
+        id: UUID;
+        settings: Settings;
+        project: Project;
+    };
+}
+interface AddRole extends BaseCommand {
+    type: 'role:add';
+    payload: Role;
+}
+interface UpdateRole extends BaseCommand {
+    type: 'role:update';
+    payload: Partial<Role> & {
+        name: string;
+    };
+}
+interface DeleteRole extends BaseCommand {
+    type: 'role:delete';
+    payload: {
+        name: string;
+    };
+}
+interface AddPreference extends BaseCommand {
+    type: 'preference:add';
+    payload: Preference;
+}
+interface UpdatePreference extends BaseCommand {
+    type: 'preference:update';
+    payload: Partial<Preference> & {
+        id: UUID;
+    };
+}
+interface DeletePreference extends BaseCommand {
+    type: 'preference:delete';
+    payload: {
+        id: UUID;
+    };
+}
+interface CreateSession extends BaseCommand {
+    type: 'session:create';
+    payload: {
+        id: UUID;
+        label: string;
+        role: string;
+        topics: string[];
+        preferences?: UUID[];
+    };
+}
+interface AddContext extends BaseCommand {
+    type: 'context:add';
+    payload: Context;
+}
+interface UpdateContext extends BaseCommand {
+    type: 'context:update';
+    payload: Partial<Context> & {
+        key: string;
+    };
+}
+interface DeleteContext extends BaseCommand {
+    type: 'context:delete';
+    payload: {
+        key: string;
+    };
+}
+interface AddTurn extends BaseCommand {
+    type: 'turn:add';
+    payload: {
+        sessionId: UUID;
+        turn: Turn;
+    };
+}
+interface EditTurn extends BaseCommand {
+    type: 'turn:edit';
+    payload: {
+        sessionId: UUID;
+        turnId: UUID;
+        newBlocks: ContentBlock[];
+        newVersion: number;
+        roleSnapshot?: string;
+    };
+}
+interface BranchTurn extends BaseCommand {
+    type: 'turn:branch';
+    payload: {
+        sessionId: UUID;
+        parentTurnId: UUID;
+        parentVersion: number;
+        newTurn: Turn;
+    };
+}
+interface DeleteTurn extends BaseCommand {
+    type: 'turn:delete';
+    payload: {
+        sessionId: UUID;
+        turnId: UUID;
+        version: number;
+        newHead: {
+            id: UUID;
+            version: number;
+        } | null;
+    };
+}
+interface AddInteraction extends BaseCommand {
+    type: 'turn:add';
+    payload: {
+        sessionId: UUID;
+        turn: Turn;
+    };
+}
+interface SwitchRole extends BaseCommand {
+    type: 'session:role:switch';
+    payload: {
+        sessionId: UUID;
+        role: string;
+    };
+}
+interface AddSessionTopics extends BaseCommand {
+    type: 'session:topics:add';
+    payload: {
+        sessionId: UUID;
+        topics: string[];
+    };
+}
+interface OverrideSessionPreferences extends BaseCommand {
+    type: 'session:preferences:override';
+    payload: {
+        sessionId: UUID;
+        preferences: UUID[];
+    };
+}
+interface ForkSession extends BaseCommand {
+    type: 'session:fork';
+    payload: {
+        sourceSessionId: UUID;
+        newSessionId: UUID;
+        label: string;
+        role?: string;
+        topics?: string[];
+    };
+}
+interface DeleteSession extends BaseCommand {
+    type: 'session:delete';
+    payload: {
+        sessionId: UUID;
+    };
+}
+interface RegisterBlob extends BaseCommand {
+    type: 'blob:register';
+    payload: BlobRecord;
+}
+interface RecordBlobRemoteId extends BaseCommand {
+    type: 'blob:remote_id';
+    payload: {
+        sha256: SHA256;
+        providerId: string;
+        fileId: string;
+    };
+}
+interface ReleaseBlob extends BaseCommand {
+    type: 'blob:release';
+    payload: {
+        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 TokenBudget {
+    total: number;
+    estimator?: (text: string) => number;
+    blobTokensPerKB?: number;
+}
+interface PreferenceConflict {
+    topic: string;
+    kept: UUID;
+    dropped: UUID;
+    reason: 'superseded_by_newer';
+}
+interface ContextRelevanceConfig {
+    recentMessageWindow?: number;
+    minScore?: number;
+    freshnessHalfLifeDays?: number;
+}
+interface BuiltTurn {
+    role: TurnRole;
+    blocks: ContentBlock[];
+}
+interface Prompt {
+    system: string | null;
+    turns: BuiltTurn[];
+    blobs: BlobRef[];
+    truncated: {
+        preferences: number;
+        interactions: number;
+        contextEntries: number;
+    };
+    conflicts: PreferenceConflict[];
+    warnings: string[];
+}
+
+interface ContentStorage {
+    saveRole(role: Role): Promise<void>;
+    loadRole(name: string): Promise<Role | null>;
+    deleteRole(name: string): Promise<void>;
+    savePreference(preference: Preference): Promise<void>;
+    loadPreference(id: UUID): Promise<Preference | null>;
+    deletePreference(id: UUID): Promise<void>;
+    saveContext(context: Context): Promise<void>;
+    loadContext(key: string): Promise<Context | null>;
+    deleteContext(key: string): Promise<void>;
+    saveTurn(sessionId: UUID, turn: Turn): Promise<void>;
+    loadTurn(sessionId: UUID, turnId: UUID, version: number): Promise<Turn | null>;
+    loadAllTurns(sessionId: UUID, limit?: number): Promise<Turn[]>;
+    setSessionHead(sessionId: UUID, head: {
+        id: UUID;
+        version: number;
+    } | null): Promise<void>;
+    getSessionHead(sessionId: UUID): Promise<{
+        id: UUID;
+        version: number;
+    } | null>;
+    deleteTurnSubtree(sessionId: UUID, turnId: UUID, version: number): Promise<void>;
+    getActiveChain(sessionId: UUID): Promise<Turn[]>;
+    countChainedTurns(sessionId: UUID): Promise<number>;
+    copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
+}
+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;
+    };
+}
+
+/**
+ * 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;
+
+interface IndexedDBConfig {
+    dbName?: string;
+}
+declare class IndexedDBStorage implements ContentStorage {
+    private readonly dbName;
+    private db;
+    constructor(config?: IndexedDBConfig);
+    open(): Promise<void>;
+    private createSchema;
+    close(): void;
+    deleteDatabase(): Promise<void>;
+    private getDB;
+    private readTx;
+    private writeTx;
+    saveRole(role: Role): Promise<void>;
+    loadRole(name: string): Promise<Role | null>;
+    deleteRole(name: string): Promise<void>;
+    savePreference(preference: Preference): Promise<void>;
+    loadPreference(id: UUID): Promise<Preference | null>;
+    deletePreference(id: UUID): Promise<void>;
+    saveContext(context: Context): Promise<void>;
+    loadContext(key: string): Promise<Context | null>;
+    deleteContext(key: string): Promise<void>;
+    saveTurn(sessionId: UUID, turn: Turn): Promise<void>;
+    loadAllTurns(sessionId: UUID, limit?: number): Promise<Turn[]>;
+    countChainedTurns(sessionId: UUID): Promise<number>;
+    loadTurn(sessionId: UUID, turnId: UUID, version: number): Promise<Turn | null>;
+    setSessionHead(sessionId: UUID, head: {
+        id: UUID;
+        version: number;
+    } | null): Promise<void>;
+    getSessionHead(sessionId: UUID): Promise<{
+        id: UUID;
+        version: number;
+    } | null>;
+    getActiveChain(sessionId: UUID): Promise<Turn[]>;
+    deleteTurnSubtree(sessionId: UUID, turnId: UUID, version: number): Promise<void>;
+    copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
+    saveIndexState(state: IndexState): Promise<void>;
+    loadIndexState(): Promise<IndexState | null>;
+    exportBundle(): Promise<{
+        roles: Record<string, Role>;
+        preferences: Record<UUID, Preference>;
+        context: Record<string, Context>;
+        transcripts: Record<UUID, Turn[]>;
+        indexState: IndexState | null;
+    }>;
+    importBundle(data: {
+        roles: Record<string, Role>;
+        preferences: Record<UUID, Preference>;
+        context: Record<string, Context>;
+        transcripts: Record<UUID, Turn[]>;
+        indexState?: IndexState;
+    }): Promise<void>;
+    private getAllFromStore;
+}
+
+/**
+ * Persistence contract for binary blob content and blob registry records.
+ *
+ * Two concerns live here together deliberately:
+ *   1. Raw bytes — stored and retrieved by SHA-256.
+ *   2. BlobRecord — the registry entry that tracks ref counts and remote IDs.
+ *
+ * Keeping them in the same backend ensures atomicity: registering a blob and
+ * storing its bytes happen in the same transaction boundary.
+ */
+interface BlobStorage {
+    /**
+     * Store raw bytes for a blob. Idempotent — if the SHA-256 already exists
+     * the bytes are not re-written (content-addressed, so they are identical).
+     */
+    storeBytes(sha256: SHA256, data: Uint8Array): Promise<void>;
+    /** Load raw bytes. Returns null if the blob is not stored locally. */
+    loadBytes(sha256: SHA256): Promise<Uint8Array | null>;
+    /** Returns true if bytes are stored locally for this SHA-256. */
+    hasBytes(sha256: SHA256): Promise<boolean>;
+    /**
+     * Delete raw bytes. Called by BlobStore when refCount reaches 0 and
+     * the blob has been evicted from the local store.
+     */
+    deleteBytes(sha256: SHA256): Promise<void>;
+    /** Persist a BlobRecord (registry metadata, not bytes). */
+    saveRecord(record: BlobRecord): Promise<void>;
+    /** Load a BlobRecord by SHA-256. Returns null if not found. */
+    loadRecord(sha256: SHA256): Promise<BlobRecord | null>;
+    /** Delete a BlobRecord. Called when a blob is fully evicted. */
+    deleteRecord(sha256: SHA256): Promise<void>;
+    /** Return all stored BlobRecords. Used for bundle export and GC sweeps. */
+    listRecords(): Promise<BlobRecord[]>;
+    /**
+     * Export all bytes as an iterable of [sha256, Uint8Array] pairs.
+     * Used for workspace export / migration.
+     */
+    exportAllBytes(): Promise<Array<[SHA256, Uint8Array]>>;
+}
+/**
+ * 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.
+     */
+    registerBlob(record: BlobRecord, data: Uint8Array): Promise<void>;
+}
+
+declare function computeSHA256(data: Uint8Array): Promise<SHA256>;
+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.
+     */
+    eagerEviction?: boolean;
+}
+declare class BlobStore {
+    private readonly backend;
+    private readonly config;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    onRegistryChanged?: (sha256: SHA256, summary: BlobSummary | 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<{
+            ref: BlobRef;
+            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.
+     */
+    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>;
+}
+
+declare class ContentStore {
+    private readonly storage;
+    private readonly cache;
+    private readonly config;
+    private activeSession;
+    private pinnedPreferenceIds;
+    onFlushed?: (sessionId: UUID, flushedCount: number) => void;
+    onSessionInvalidated?: (sessionId: UUID) => void;
+    constructor(backend: ContentStorage, config?: ContentStoreConfig);
+    getActiveSessionId(): UUID | null;
+    getRole(name: string): Promise<Result<Role, WorkspaceError>>;
+    getPreference(id: UUID): Promise<Result<Preference, WorkspaceError>>;
+    getContext(key: string): Promise<Result<Context, WorkspaceError>>;
+    getContextByTopics(indexState: IndexState, topics: string[]): Promise<Context[]>;
+    getTranscriptWindow(sessionId: UUID, windowSize?: number): Promise<TranscriptWindow>;
+    saveRole(role: Role): Promise<void>;
+    savePreference(preference: Preference): Promise<void>;
+    saveContext(context: Context): Promise<void>;
+    copyTranscript(sourceSessionId: UUID, targetSessionId: UUID): Promise<void>;
+    deleteRole(name: string): Promise<void>;
+    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>;
+}
+
+declare function workspaceReducer(state: IndexState, command: Command): Result<DeepPartial<IndexState>, 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>;
+    private handleContentSideEffects;
+}
+
+interface Summarizer {
+    summarize(transcript: Turn[], tokenBudget: number): Promise<{
+        summary: string;
+        remaining: Turn[];
+    }>;
+}
+
+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>;
+        tokenBudget?: TokenBudget;
+        relevanceConfig?: ContextRelevanceConfig;
+    }): Promise<Prompt>;
+}
+
+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 };