@semiont/sdk 0.5.3 → 0.5.4

package/dist/index.d.ts

@@ -1,1759 +1,61 @@
-import * as rxjs from 'rxjs';
-import { Observable, BehaviorSubject, Subject } from 'rxjs';
-export { firstValueFrom, lastValueFrom } from 'rxjs';
-import * as _semiont_core from '@semiont/core';
-import { ResourceId, components, UserDID, paths, BackendDownload, ProgressEvent, AnnotationId, BodyOperation, EventMap, ResourceDescriptor, Annotation, TagSchema, GraphConnection, Motivation, GatheredContext, JobId, ITransport, EventBus, IContentTransport, IBackendOperations, BaseUrl, AccessToken, SemiontError, ConnectionState, Selector } from '@semiont/core';
-export { AccessToken, Annotation, AnnotationId, BaseUrl, BodyItem, BodyOperation, ConnectionState, EntityType, EventMap, GatheredContext, IContentTransport, ITransport, Logger, Motivation, RefreshToken, ResourceDescriptor, ResourceId, SemiontError, TagCategory, TagSchema, UserId, accessToken, annotationId, baseUrl, entityType, refreshToken, resourceId, userId } from '@semiont/core';
-export { APIError, HttpContentTransport, HttpTransport, HttpTransportConfig, TokenRefresher } from '@semiont/api-client';
-
-/**
- * Thenable Observable subclasses.
- *
- * Two thin Observable subclasses that also implement `PromiseLike<T>`. Used as
- * the public return type of namespace methods that emit streams (job
- * lifecycle, generation progress) and cache reads (Browse live queries).
- *
- * The point: scripts can `await` the call directly without `lastValueFrom` /
- * `firstValueFrom` wrappers; reactive consumers keep using `.subscribe(...)`
- * and `.pipe(...)` exactly as before.
- *
- * The asymmetric `.then()` semantics — last-value-on-completion for streams,
- * first-non-undefined-value for caches — is encoded by the subclass name. The
- * docstring on the namespace method tells the consumer which one applies.
- *
- * `.pipe(...)` returns a plain `Observable<T>` (RxJS doesn't propagate
- * subclasses through `pipe`). Once you compose, you've explicitly entered
- * RxJS land; `lastValueFrom` from `rxjs` is the right bridge there.
- */
-
-/**
- * Bounded Observable stream — emits zero-or-more progress values, then a
- * final value on completion. Used by job-lifecycle methods like
- * `mark.assist`, `gather.annotation`, `match.search`, `yield.fromAnnotation`.
- *
- * Awaiting resolves to the **last** emitted value (via `lastValueFrom`).
- * Subscribing yields every emission, ending in `complete`.
- */
-declare class StreamObservable<T> extends Observable<T> implements PromiseLike<T> {
-    then<R1 = T, R2 = never>(onfulfilled?: ((v: T) => R1 | PromiseLike<R1>) | null, onrejected?: ((e: unknown) => R2 | PromiseLike<R2>) | null): PromiseLike<R1 | R2>;
-    /** Wrap an existing Observable's subscribe behavior in a StreamObservable. */
-    static from<T>(source: Observable<T>): StreamObservable<T>;
-}
-/**
- * Multicast cache observable — emits `undefined` while the underlying value
- * is loading, then the value, then re-emits when bus events invalidate the
- * cache entry. Used by Browse live-query methods (`browse.resource`,
- * `browse.annotations`, etc.).
- *
- * Awaiting resolves to the **first non-undefined** value (waits past the
- * loading state). Subscribing yields the full sequence including the
- * initial `undefined`, so reactive consumers can render a loading state.
- *
- * The class is parameterized as `CacheObservable<T>` even though the
- * stream's element type is `T | undefined` — `T` is what the consumer
- * gets from `await`, and that's the contract we want to advertise. The
- * `Observable<T | undefined>` shape leaks through `.subscribe` and
- * `.pipe` in the natural way.
- */
-declare class CacheObservable<T> extends Observable<T | undefined> implements PromiseLike<T> {
-    then<R1 = T, R2 = never>(onfulfilled?: ((v: T) => R1 | PromiseLike<R1>) | null, onrejected?: ((e: unknown) => R2 | PromiseLike<R2>) | null): PromiseLike<R1 | R2>;
-    /**
-     * Wrap an existing Observable's subscribe behavior in a `CacheObservable`.
-     *
-     * Memoizes on source identity: passing the same `source` returns the same
-     * wrapper instance. The Browse cache primitive already returns a stable
-     * Observable per key (its B4 contract), so this preserves that contract
-     * through the awaitable wrapping. Without the memo, every public-method
-     * call would produce a fresh wrapper and break referential-equality
-     * guarantees that hook-style reactive consumers depend on.
-     *
-     * Backed by a `WeakMap`, so wrappers are GC'd when their source is.
-     */
-    static from<T>(source: Observable<T | undefined>): CacheObservable<T>;
-}
-/**
- * Discriminated phases of an upload's lifecycle.
- *
- * - `started` — emitted immediately on `yield.resource(...)` invocation, before any bytes flow.
- * - `progress` — emitted as bytes flow over the wire. Wired by `HttpContentTransport`'s XHR path when a caller passes `onProgress` (or, transitively, when `yield.resource` is the caller — it always wires the hook so subscribers see byte counts). `bytesUploaded` and `totalBytes` carry the running counts; `totalBytes` may be 0 when the transport can't determine the total (rare, e.g. chunked encoding) — UI consumers should render an indeterminate state in that case.
- * - `finished` — emitted on backend acknowledgement, carries the assigned `resourceId`.
- *
- * Failures surface as `Observable.error(...)` (typically an `APIError` from the transport's `errors$` Subject), not as a `phase: 'failed'` event — `subscribe`'s error callback handles them. Cancellation is honored: unsubscribing before `finished` aborts the in-flight HTTP request on the XHR path.
- */
-type UploadProgress = {
-    phase: 'started';
-    totalBytes: number;
-} | {
-    phase: 'progress';
-    bytesUploaded: number;
-    totalBytes: number;
-} | {
-    phase: 'finished';
-    resourceId: ResourceId;
-};
-/**
- * Specialized `StreamObservable` for `yield.resource`. Subscribers see the
- * full `UploadProgress` event sequence (started → optional progress → finished).
- * Awaiting resolves specifically to `{ resourceId }` extracted from the
- * `'finished'` event — preserving the pre-Phase-18 awaited shape so existing
- * `await client.yield.resource(...)` callers don't need to narrow the union.
- */
-declare class UploadObservable extends Observable<UploadProgress> implements PromiseLike<{
-    resourceId: ResourceId;
-}> {
-    then<R1 = {
-        resourceId: ResourceId;
-    }, R2 = never>(onfulfilled?: ((v: {
-        resourceId: ResourceId;
-    }) => R1 | PromiseLike<R1>) | null, onrejected?: ((e: unknown) => R2 | PromiseLike<R2>) | null): PromiseLike<R1 | R2>;
-}
-
-/**
- * Verb Namespace Interfaces
- *
- * These interfaces define the public API of `@semiont/sdk`, organized by
- * the 7 domain flows (Browse, Mark, Bind, Gather, Match, Yield, Beckon)
- * plus infrastructure namespaces (Job, Auth, Admin).
- *
- * Each namespace maps 1:1 to a flow. Each flow maps to a clear actor on
- * the backend. The frontend calls `client.mark.annotation()` and the
- * client handles HTTP, auth, SSE, and caching internally.
- *
- * Return type conventions:
- * - Browse live queries → `CacheObservable<T>` (bus-driven, cached;
- *   subscribe yields `T | undefined`, await yields `T` after first load)
- * - Browse one-shot reads → `Promise<T>` (fetch once, no cache)
- * - Commands (mark, bind, yield.resource) → `Promise<T>` (atomic ops)
- * - Long-running ops (gather, match, yield.fromAnnotation, mark.assist)
- *   → `StreamObservable<T>` (progress + result; subscribe yields every
- *   emit, await yields the last one)
- * - Ephemeral signals (beckon) → `void`
- *
- * `StreamObservable` and `CacheObservable` are `Observable` subclasses
- * that also implement `PromiseLike<T>` — `await client.X.Y(...)` works
- * directly without `lastValueFrom`/`firstValueFrom` wrappers.
- * `.pipe(...)` returns a plain `Observable<T>` (the thenable subclass
- * does not propagate through pipe — by design).
- */
-
-type StoredEventResponse$1 = components['schemas']['StoredEventResponse'];
-type GatherProgress = components['schemas']['GatherProgress'];
-type MatchSearchResult = components['schemas']['MatchSearchResult'];
-type JobProgress$2 = components['schemas']['JobProgress'];
-type GatherAnnotationComplete = components['schemas']['GatherAnnotationComplete'];
-type JobStatusResponse$1 = components['schemas']['JobStatusResponse'];
-type AuthResponse$1 = components['schemas']['AuthResponse'];
-type TokenRefreshResponse$1 = components['schemas']['TokenRefreshResponse'];
-type OAuthConfigResponse$1 = components['schemas']['OAuthConfigResponse'];
-type AdminUserStatsResponse$1 = components['schemas']['AdminUserStatsResponse'];
-type ResponseContent<T> = T extends {
-    responses: {
-        200: {
-            content: {
-                'application/json': infer R;
-            };
-        };
-    };
-} ? R : T extends {
-    responses: {
-        201: {
-            content: {
-                'application/json': infer R;
-            };
-        };
-    };
-} ? R : T extends {
-    responses: {
-        202: {
-            content: {
-                'application/json': infer R;
-            };
-        };
-    };
-} ? R : never;
-type RequestContent<T> = T extends {
-    requestBody?: {
-        content: {
-            'application/json': infer R;
-        };
-    };
-} ? R : never;
-/** Input for creating an annotation via mark.annotation() */
-type CreateAnnotationInput = components['schemas']['CreateAnnotationRequest'];
-/** Input for creating a resource via yield.resource() */
-interface CreateResourceInput {
-    name: string;
-    file: File | Buffer;
-    format: string;
-    entityTypes?: string[];
-    language?: string;
-    creationMethod?: string;
-    sourceAnnotationId?: string;
-    sourceResourceId?: string;
-    storageUri: string;
-    /** Prompt that drove AI generation (for AI-generated resources). */
-    generationPrompt?: string;
-    /** Agent(s) that generated the content (for AI-generated resources). */
-    generator?: components['schemas']['Agent'] | components['schemas']['Agent'][];
-    isDraft?: boolean;
-}
-/** Options for yield.fromAnnotation() */
-interface GenerationOptions {
-    title: string;
-    storageUri: string;
-    context: GatheredContext;
-    prompt?: string;
-    /** Entity-type tags to stamp on the synthesized resource. Used both as a prompt bias for the generation worker and as the `entityTypes` set on the resulting resource (so `browse.resources({ entityType: ... })` queries can find it). */
-    entityTypes?: string[];
-    /** Annotation/resource body locale — language the generated resource is written in (typically the user's UI locale). */
-    language?: string;
-    /** Source-resource locale — language of the resource the annotation lives on, used in the prompt so the LLM understands embedded source-context snippets. BCP-47. */
-    sourceLanguage?: string;
-    temperature?: number;
-    maxTokens?: number;
-}
-/** Options for mark.assist() */
-interface MarkAssistOptions {
-    entityTypes?: string[];
-    includeDescriptiveReferences?: boolean;
-    instructions?: string;
-    density?: number;
-    tone?: string;
-    /** Annotation body locale — language the LLM should write generated body text in (comment text, assessment text, tag/reference body language stamp). BCP-47. */
-    language?: string;
-    /** Source-resource locale — language of the content being analyzed, used in the prompt so the LLM analyzes non-English source correctly. BCP-47. */
-    sourceLanguage?: string;
-    schemaId?: string;
-    categories?: string[];
-}
-/** Options for yield.createFromToken() */
-type CreateFromTokenOptions = {
-    token: string;
-    name: string;
-    content: string;
-    archiveOriginal?: boolean;
-};
-/** Referenced-by entry from browse.referencedBy() */
-type ReferencedByEntry = components['schemas']['GetReferencedByResponse']['referencedBy'][number];
-/** Annotation history from browse.annotationHistory() */
-type AnnotationHistoryResponse = components['schemas']['GetAnnotationHistoryResponse'];
-/** User object from auth/admin responses */
-type User = AuthResponse$1['user'];
-/**
- * Progress emitted by gather.annotation() Observable.
- * Emits GatherProgress during assembly, then GatherAnnotationComplete on finish.
- */
-type GatherAnnotationProgress = GatherProgress | GatherAnnotationComplete;
-/**
- * Progress emitted by match.search() Observable.
- * Emits the final MatchSearchResult (no intermediate progress events currently).
- */
-type MatchSearchProgress = MatchSearchResult;
-/**
- * Progress payload emitted by mark.assist() and yield.fromAnnotation()
- * Observables. Each progress emission carries a JobProgress snapshot
- * (unified job lifecycle).
- */
-type MarkAssistProgress = JobProgress$2;
-/**
- * Discriminated event yielded by the `mark.assist()` Observable. Progress
- * events stream while the worker runs; the final value before the
- * Observable completes is a `complete` event carrying the `JobCompleteCommand`
- * payload (with `result`, `jobId`, `jobType`, etc.). The Observable errors
- * on `job:fail`.
- */
-type MarkAssistEvent = {
-    kind: 'progress';
-    data: MarkAssistProgress;
-} | {
-    kind: 'complete';
-    data: components['schemas']['JobCompleteCommand'];
-};
-/**
- * Discriminated event yielded by the `yield.fromAnnotation()` Observable.
- * Same shape and semantics as `MarkAssistEvent`.
- */
-type YieldGenerationEvent = {
-    kind: 'progress';
-    data: JobProgress$2;
-} | {
-    kind: 'complete';
-    data: components['schemas']['JobCompleteCommand'];
-};
-/**
- * Browse — reads from materialized views
- *
- * Live queries return Observables that emit initial state and re-emit
- * on bus gateway updates. One-shot reads return Promises.
- *
- * Backend actor: Browser (context classes)
- * Event prefix: browse:*
- */
-interface BrowseNamespace$1 {
-    resource(resourceId: ResourceId): CacheObservable<ResourceDescriptor>;
-    resources(filters?: {
-        limit?: number;
-        archived?: boolean;
-        search?: string;
-    }): CacheObservable<ResourceDescriptor[]>;
-    annotations(resourceId: ResourceId): CacheObservable<Annotation[]>;
-    annotation(resourceId: ResourceId, annotationId: AnnotationId): CacheObservable<Annotation>;
-    entityTypes(): CacheObservable<string[]>;
-    tagSchemas(): CacheObservable<TagSchema[]>;
-    referencedBy(resourceId: ResourceId): CacheObservable<ReferencedByEntry[]>;
-    events(resourceId: ResourceId): CacheObservable<StoredEventResponse$1[]>;
-    resourceContent(resourceId: ResourceId): Promise<string>;
-    resourceRepresentation(resourceId: ResourceId, options?: {
-        accept?: string;
-    }): Promise<{
-        data: ArrayBuffer;
-        contentType: string;
-    }>;
-    resourceRepresentationStream(resourceId: ResourceId, options?: {
-        accept?: string;
-    }): Promise<{
-        stream: ReadableStream<Uint8Array>;
-        contentType: string;
-    }>;
-    resourceEvents(resourceId: ResourceId): Promise<StoredEventResponse$1[]>;
-    annotationHistory(resourceId: ResourceId, annotationId: AnnotationId): Promise<AnnotationHistoryResponse>;
-    connections(resourceId: ResourceId): Promise<GraphConnection[]>;
-    backlinks(resourceId: ResourceId): Promise<Annotation[]>;
-    resourcesByName(query: string, limit?: number): Promise<ResourceDescriptor[]>;
-    files(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount'): Promise<components['schemas']['BrowseFilesResponse']>;
-    click(annotationId: AnnotationId, motivation: Motivation): void;
-    navigateReference(resourceId: ResourceId): void;
-}
-/**
- * Frame — schema-layer flow (the eighth flow).
- *
- * Frame operates on the KB's conceptual vocabulary — what *kinds* of
- * things exist (entity types) and, in the future, what taxonomies are
- * recognized (tag schemas), what relations are typed (predicate types),
- * and how schemas are imported (ontology I/O). The other seven flows
- * (yield, mark, match, bind, gather, browse, beckon) operate on
- * content; Frame operates on the schema layer that content is expressed
- * in.
- *
- * MVP scope is small: entity-type vocabulary writes only. Live reads of
- * the entity-type vocabulary stay on Browse (`browse.entityTypes()` is
- * a `CacheObservable<string[]>` consumed by 8+ call sites). Frame owns
- * writes; Browse owns reads — the same asymmetry that already holds for
- * resources and annotations.
- *
- * Backend actor: Stower
- * Event prefix: frame:*
- */
-interface FrameNamespace$1 {
-    /** Add a single entity type to the KB's vocabulary. Idempotent — adding an existing type is a no-op. */
-    addEntityType(type: string): Promise<void>;
-    /** Add multiple entity types in one call. Convenience over a loop of `addEntityType`. */
-    addEntityTypes(types: string[]): Promise<void>;
-    /**
-     * Register a tag schema with the KB's runtime registry.
-     *
-     * Most-recent registration of a given `schema.id` wins; identical
-     * re-registrations are silent, differing content overwrites the
-     * existing entry and logs a warning. KBs typically call this at
-     * session/skill startup so the schema is available for `mark.assist`
-     * with motivation `tagging` and surfaces in `browse.tagSchemas()`.
-     */
-    addTagSchema(schema: TagSchema): Promise<void>;
-}
-/**
- * Mark — annotation CRUD, AI assist, resource lifecycle
- *
- * Commands return Promises that resolve on HTTP acceptance (202).
- * Results appear on browse Observables via bus gateway.
- * assist() returns an Observable for long-running progress.
- *
- * Backend actor: Stower
- * Event prefix: mark:*
- */
-interface MarkNamespace$1 {
-    annotation(input: CreateAnnotationInput): Promise<{
-        annotationId: AnnotationId;
-    }>;
-    delete(resourceId: ResourceId, annotationId: AnnotationId): Promise<void>;
-    archive(resourceId: ResourceId): Promise<void>;
-    unarchive(resourceId: ResourceId): Promise<void>;
-    assist(resourceId: ResourceId, motivation: Motivation, options: MarkAssistOptions): StreamObservable<MarkAssistEvent>;
-    request(selector: components['schemas']['MarkRequestedEvent']['selector'], motivation: Motivation): void;
-    /** Fire-and-forget variant of `assist` — mark-state-unit orchestrates the call and its progress Observable. */
-    requestAssist(motivation: Motivation, options: MarkAssistOptions, correlationId?: string): void;
-    /** Submit the currently pending annotation with its selector and optional body. */
-    submit(input: components['schemas']['MarkSubmitEvent']): void;
-    /** Cancel the currently pending annotation (if any). */
-    cancelPending(): void;
-    /** Dismiss the in-progress AI-assist widget. */
-    dismissProgress(): void;
-    changeSelection(motivation: Motivation | null): void;
-    changeClick(action: string): void;
-    changeShape(shape: string): void;
-    toggleMode(): void;
-}
-/**
- * Bind — reference linking
- *
- * The simplest namespace. One method. The result (updated annotation
- * with resolved reference) arrives on browse.annotations() via the
- * enriched mark:body-updated event.
- *
- * Backend actor: Stower (via mark:update-body)
- * Event prefix: mark:body-updated (shares mark event pipeline)
- */
-interface BindNamespace$1 {
-    body(resourceId: ResourceId, annotationId: AnnotationId, operations: BodyOperation[]): Promise<void>;
-    /** UI signal: a reference-binding flow is requested for an annotation. */
-    initiate(input: EventMap['bind:initiate']): void;
-}
-/**
- * Gather — context assembly
- *
- * Long-running (LLM calls + graph traversal). Returns Observables
- * that emit progress then the gathered context.
- *
- * Backend actor: Gatherer
- * Event prefix: gather:*
- */
-interface GatherNamespace$1 {
-    annotation(resourceId: ResourceId, annotationId: AnnotationId, options?: {
-        contextWindow?: number;
-    }): StreamObservable<GatherAnnotationProgress>;
-    resource(resourceId: ResourceId, options?: {
-        contextWindow?: number;
-    }): StreamObservable<GatherAnnotationProgress>;
-}
-/**
- * Match — search and ranking
- *
- * Long-running (semantic search, optional LLM scoring). Returns
- * Observable with progress then results.
- *
- * Backend actor: Matcher
- * Event prefix: match:*
- */
-interface MatchNamespace$1 {
-    search(resourceId: ResourceId, referenceId: AnnotationId, context: GatheredContext, options?: {
-        limit?: number;
-        useSemanticScoring?: boolean;
-    }): StreamObservable<MatchSearchProgress>;
-    /** Fire-and-forget variant: match-state-unit orchestrates the call and its result Observable. */
-    requestSearch(input: components['schemas']['MatchSearchRequest']): void;
-}
-/**
- * Yield — resource creation
- *
- * resource() is synchronous file upload (Promise).
- * fromAnnotation() is long-running LLM generation (Observable).
- *
- * Backend actor: Stower + generation worker
- * Event prefix: yield:*
- */
-interface YieldNamespace$1 {
-    resource(data: CreateResourceInput): UploadObservable;
-    fromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options: GenerationOptions): StreamObservable<YieldGenerationEvent>;
-    cloneToken(resourceId: ResourceId): Promise<{
-        token: string;
-        expiresAt: string;
-    }>;
-    fromToken(token: string): Promise<ResourceDescriptor>;
-    createFromToken(options: CreateFromTokenOptions): Promise<{
-        resourceId: ResourceId;
-    }>;
-    /** UI signal: user invoked the clone action from the resource-info panel. */
-    clone(): void;
-}
-/**
- * Beckon — attention coordination
- *
- * Fire-and-forget. Ephemeral presence signal delivered via the
- * attention-stream to other participants.
- *
- * Backend actor: (frontend relay via attention-stream)
- * Event prefix: beckon:*
- */
-interface BeckonNamespace$1 {
-    attention(resourceId: ResourceId, annotationId: AnnotationId): void;
-    hover(annotationId: AnnotationId | null): void;
-    sparkle(annotationId: AnnotationId): void;
-}
-/**
- * Job — worker lifecycle
- */
-interface JobNamespace$1 {
-    /** Live stream of `job:queued` events from the bus. */
-    readonly queued$: Observable<EventMap['job:queued']>;
-    /** Live stream of `job:report-progress` events from the bus. */
-    readonly progress$: Observable<EventMap['job:report-progress']>;
-    /** Live stream of `job:complete` events from the bus. */
-    readonly complete$: Observable<EventMap['job:complete']>;
-    /** Live stream of `job:fail` events from the bus. */
-    readonly fail$: Observable<EventMap['job:fail']>;
-    status(jobId: JobId): Promise<JobStatusResponse$1>;
-    pollUntilComplete(jobId: JobId, options?: {
-        interval?: number;
-        timeout?: number;
-        onProgress?: (status: JobStatusResponse$1) => void;
-    }): Promise<JobStatusResponse$1>;
-    cancelByType(jobType: 'annotation' | 'generation'): Promise<void>;
-    /** UI signal: cancel all active jobs of a given type (e.g. "annotation"). */
-    cancelRequest(jobType: 'annotation' | 'generation'): void;
-}
-/**
- * Auth — authentication
- */
-interface AuthNamespace$1 {
-    password(email: string, password: string): Promise<AuthResponse$1>;
-    google(credential: string): Promise<AuthResponse$1>;
-    refresh(token: string): Promise<TokenRefreshResponse$1>;
-    logout(): Promise<void>;
-    me(): Promise<User>;
-    acceptTerms(): Promise<void>;
-    mcpToken(): Promise<{
-        token: string;
-    }>;
-    mediaToken(resourceId: ResourceId): Promise<{
-        token: string;
-    }>;
-}
-/**
- * Admin — administration
- */
-interface AdminNamespace$1 {
-    users(): Promise<User[]>;
-    userStats(): Promise<AdminUserStatsResponse$1>;
-    updateUser(userId: UserDID, data: RequestContent<paths['/api/admin/users/{id}']['patch']>): Promise<User>;
-    oauthConfig(): Promise<OAuthConfigResponse$1>;
-    healthCheck(): Promise<ResponseContent<paths['/api/health']['get']>>;
-    status(): Promise<ResponseContent<paths['/api/status']['get']>>;
-    backup(): Promise<BackendDownload>;
-    /**
-     * Restore from a backup archive. Returns a `StreamObservable` that
-     * emits each `ProgressEvent` as the operation runs (`'started'`,
-     * `'parsing'`, `'importing'`, ..., `'complete'`). Subscribers see
-     * every step; awaiters get the final event via the PromiseLike sugar.
-     */
-    restore(file: File): StreamObservable<ProgressEvent>;
-    exportKnowledgeBase(params?: {
-        includeArchived?: boolean;
-    }): Promise<BackendDownload>;
-    importKnowledgeBase(file: File): StreamObservable<ProgressEvent>;
-}
-
-type StoredEventResponse = components['schemas']['StoredEventResponse'];
-type ResourceListFilters = {
-    limit?: number;
-    archived?: boolean;
-    search?: string;
-};
-declare class BrowseNamespace implements BrowseNamespace$1 {
-    private readonly transport;
-    private readonly bus;
-    private readonly content;
-    private readonly resourceCache;
-    private readonly resourceListCache;
-    private readonly annotationListCache;
-    /**
-     * Annotation-detail cache keyed by `annotationId` only — the resourceId
-     * is a routing hint for the backend fetch, not an identity component.
-     * We track the most recent resourceId per annotationId in a side-map
-     * so `mark:delete-ok` (which carries only `annotationId`) can reach
-     * the right cache entry. Aligns with the pre-refactor semantics.
-     */
-    private readonly annotationDetailCache;
-    private readonly annotationResources;
-    private readonly entityTypesCache;
-    private readonly tagSchemasCache;
-    private readonly referencedByCache;
-    private readonly resourceEventsCache;
-    /** Filter-blob memory so `invalidateResourceLists` can replay per-key. */
-    private readonly resourceListFilters;
-    /**
-     * Per-key memo for `annotations()` observables. The cache stores the
-     * full `AnnotationsListResponse`; the public shape is just the inner
-     * `Annotation[]`. Without this memo, every call to `annotations(rId)`
-     * would produce a fresh `.pipe(map(...))` observable, violating B4
-     * (per-key observable stability). Consumers that compare observable
-     * identity — React hooks depending on the observable reference,
-     * `distinctUntilChanged` at a higher level — would misbehave.
-     */
-    private readonly annotationListObs;
-    constructor(transport: ITransport, bus: EventBus, content: IContentTransport);
-    resource(resourceId: ResourceId): CacheObservable<ResourceDescriptor>;
-    resources(filters?: ResourceListFilters): CacheObservable<ResourceDescriptor[]>;
-    annotations(resourceId: ResourceId): CacheObservable<Annotation[]>;
-    annotation(resourceId: ResourceId, annotationId: AnnotationId): CacheObservable<Annotation>;
-    entityTypes(): CacheObservable<string[]>;
-    tagSchemas(): CacheObservable<TagSchema[]>;
-    referencedBy(resourceId: ResourceId): CacheObservable<ReferencedByEntry[]>;
-    events(resourceId: ResourceId): CacheObservable<StoredEventResponse[]>;
-    resourceContent(resourceId: ResourceId): Promise<string>;
-    resourceRepresentation(resourceId: ResourceId, options?: {
-        accept?: string;
-    }): Promise<{
-        data: ArrayBuffer;
-        contentType: string;
-    }>;
-    resourceRepresentationStream(resourceId: ResourceId, options?: {
-        accept?: string;
-    }): Promise<{
-        stream: ReadableStream<Uint8Array>;
-        contentType: string;
-    }>;
-    resourceEvents(resourceId: ResourceId): Promise<StoredEventResponse[]>;
-    annotationHistory(resourceId: ResourceId, annotationId: AnnotationId): Promise<AnnotationHistoryResponse>;
-    connections(_resourceId: ResourceId): Promise<GraphConnection[]>;
-    backlinks(_resourceId: ResourceId): Promise<Annotation[]>;
-    resourcesByName(_query: string, _limit?: number): Promise<ResourceDescriptor[]>;
-    files(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount'): Promise<components['schemas']['BrowseFilesResponse']>;
-    click(annotationId: AnnotationId, motivation: Motivation): void;
-    navigateReference(resourceId: ResourceId): void;
-    invalidateAnnotationList(resourceId: ResourceId): void;
-    removeAnnotationDetail(annotationId: AnnotationId): void;
-    invalidateResourceDetail(id: ResourceId): void;
-    invalidateResourceLists(): void;
-    invalidateEntityTypes(): void;
-    invalidateTagSchemas(): void;
-    invalidateReferencedBy(resourceId: ResourceId): void;
-    invalidateResourceEvents(resourceId: ResourceId): void;
-    updateAnnotationInPlace(resourceId: ResourceId, annotation: Annotation): void;
-    /**
-     * Typed shorthand for `eventBus.get(channel).subscribe(handler)`.
-     * Preserves per-channel payload typing so handlers read
-     * `EventMap[K]` without any casts.
-     */
-    private on;
-    /**
-     * Handler shared by `mark:entity-tag-added` and `mark:entity-tag-removed`.
-     * Both events carry the same effect: the annotation list, the
-     * resource descriptor, and the event log for that resource all may
-     * now reflect different entity tagging, so invalidate all three.
-     */
-    private onEntityTagChanged;
-    /**
-     * Handler shared by `mark:archived` and `mark:unarchived`. Both
-     * change a resource's archived flag, which is stored on the resource
-     * descriptor and affects the resource-list filter.
-     */
-    private onArchiveToggled;
-    /**
-     * Handler shared by `yield:create-ok` and `yield:update-ok`. Both
-     * report a resource mutation with the resourceId as a string (not
-     * yet branded), so we brand and apply the same effect as
-     * `onArchiveToggled`.
-     */
-    private onYieldResourceMutated;
-    private subscribeToEvents;
-}
-
-declare class MarkNamespace implements MarkNamespace$1 {
-    private readonly transport;
-    private readonly bus;
-    constructor(transport: ITransport, bus: EventBus);
-    annotation(input: CreateAnnotationInput): Promise<{
-        annotationId: AnnotationId;
-    }>;
-    delete(resourceId: ResourceId, annotationId: AnnotationId): Promise<void>;
-    archive(resourceId: ResourceId): Promise<void>;
-    unarchive(resourceId: ResourceId): Promise<void>;
-    assist(resourceId: ResourceId, motivation: Motivation, options: MarkAssistOptions): StreamObservable<MarkAssistEvent>;
-    request(selector: components['schemas']['MarkRequestedEvent']['selector'], motivation: Motivation): void;
-    requestAssist(motivation: Motivation, options: MarkAssistOptions, correlationId?: string): void;
-    submit(input: components['schemas']['MarkSubmitEvent']): void;
-    cancelPending(): void;
-    dismissProgress(): void;
-    changeSelection(motivation: Motivation | null): void;
-    changeClick(action: string): void;
-    changeShape(shape: string): void;
-    toggleMode(): void;
-    private dispatchAssist;
-}
-
-declare class BindNamespace implements BindNamespace$1 {
-    private readonly transport;
-    private readonly bus;
-    constructor(transport: ITransport, bus: EventBus);
-    body(resourceId: ResourceId, annotationId: AnnotationId, operations: BodyOperation[]): Promise<void>;
-    initiate(input: EventMap['bind:initiate']): void;
-}
-
-declare class GatherNamespace implements GatherNamespace$1 {
-    private readonly transport;
-    private readonly bus;
-    constructor(transport: ITransport, bus: EventBus);
-    annotation(resourceId: ResourceId, annotationId: AnnotationId, options?: {
-        contextWindow?: number;
-    }): StreamObservable<GatherAnnotationProgress>;
-    resource(_resourceId: ResourceId, _options?: {
-        contextWindow?: number;
-    }): StreamObservable<GatherAnnotationProgress>;
-}
-
-declare class MatchNamespace implements MatchNamespace$1 {
-    private readonly transport;
-    private readonly bus;
-    constructor(transport: ITransport, bus: EventBus);
-    requestSearch(input: components['schemas']['MatchSearchRequest']): void;
-    search(resourceId: ResourceId, referenceId: AnnotationId, context: GatheredContext, options?: {
-        limit?: number;
-        useSemanticScoring?: boolean;
-    }): StreamObservable<MatchSearchProgress>;
-}
-
-declare class YieldNamespace implements YieldNamespace$1 {
-    private readonly transport;
-    private readonly bus;
-    private readonly content;
-    constructor(transport: ITransport, bus: EventBus, content: IContentTransport);
-    resource(data: CreateResourceInput): UploadObservable;
-    fromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options: GenerationOptions): StreamObservable<YieldGenerationEvent>;
-    cloneToken(resourceId: ResourceId): Promise<{
-        token: string;
-        expiresAt: string;
-    }>;
-    fromToken(token: string): Promise<ResourceDescriptor>;
-    createFromToken(options: CreateFromTokenOptions): Promise<{
-        resourceId: ResourceId;
-    }>;
-    clone(): void;
-}
-
-declare class BeckonNamespace implements BeckonNamespace$1 {
-    private readonly transport;
-    private readonly bus;
-    constructor(transport: ITransport, bus: EventBus);
-    attention(resourceId: ResourceId, annotationId: AnnotationId): void;
-    hover(annotationId: AnnotationId | null): void;
-    sparkle(annotationId: AnnotationId): void;
-}
-
-/**
- * FrameNamespace — the eighth flow's surface.
- *
- * Frame operates on the KB's **schema layer** — the conceptual vocabulary
- * the other seven flows are expressed in. Where yield/mark/match/bind/
- * gather/browse/beckon act on content (resources, annotations, references,
- * attention), Frame acts on what *kinds* of things exist: entity types,
- * eventually tag schemas, relation/predicate types, ontology imports.
- *
- * The MVP owns a single primitive — entity-type vocabulary writes on the
- * `frame:add-entity-type` channel. See `docs/protocol/flows/FRAME.md`
- * for the per-flow contract.
- *
- * Live reads of the entity-type vocabulary stay on Browse
- * (`browse.entityTypes()` is a `CacheObservable<string[]>`). Frame owns
- * writes; Browse owns reads. The asymmetry is intentional — re-implementing
- * Browse's cache primitives on Frame for a single read would duplicate
- * machinery without benefit.
- */
-
-declare class FrameNamespace implements FrameNamespace$1 {
-    private readonly transport;
-    constructor(transport: ITransport);
-    addEntityType(type: string): Promise<void>;
-    addEntityTypes(types: string[]): Promise<void>;
-    addTagSchema(schema: TagSchema): Promise<void>;
-}
-
-type JobStatusResponse = components['schemas']['JobStatusResponse'];
-declare class JobNamespace implements JobNamespace$1 {
-    private readonly transport;
-    private readonly bus;
-    constructor(transport: ITransport, bus: EventBus);
-    /**
-     * Live stream of `job:queued` events. Surfaces a typed view onto the
-     * underlying bus channel for consumers (CLIs, MCP handlers, widgets)
-     * that orchestrate jobs and need to react to lifecycle transitions.
-     */
-    get queued$(): Observable<EventMap['job:queued']>;
-    /** Live stream of `job:report-progress` events. */
-    get progress$(): Observable<EventMap['job:report-progress']>;
-    /** Live stream of `job:complete` events. */
-    get complete$(): Observable<EventMap['job:complete']>;
-    /** Live stream of `job:fail` events. */
-    get fail$(): Observable<EventMap['job:fail']>;
-    status(jobId: JobId): Promise<JobStatusResponse>;
-    pollUntilComplete(jobId: JobId, options?: {
-        interval?: number;
-        timeout?: number;
-        onProgress?: (status: JobStatusResponse) => void;
-    }): Promise<JobStatusResponse>;
-    cancelByType(jobType: 'annotation' | 'generation'): Promise<void>;
-    cancelRequest(jobType: 'annotation' | 'generation'): void;
-}
-
-/**
- * AuthNamespace — authentication. Backend ops only; no bus.
- */
-
-type AuthResponse = components['schemas']['AuthResponse'];
-type TokenRefreshResponse = components['schemas']['TokenRefreshResponse'];
-declare class AuthNamespace implements AuthNamespace$1 {
-    private readonly backend;
-    constructor(backend: IBackendOperations);
-    password(emailStr: string, passwordStr: string): Promise<AuthResponse>;
-    google(credential: string): Promise<AuthResponse>;
-    refresh(token: string): Promise<TokenRefreshResponse>;
-    logout(): Promise<void>;
-    me(): Promise<User>;
-    acceptTerms(): Promise<void>;
-    mcpToken(): Promise<{
-        token: string;
-    }>;
-    mediaToken(resourceId: ResourceId): Promise<{
-        token: string;
-    }>;
-}
-
 /**
- * AdminNamespace — administration. Backend ops only; no bus.
- */
-
-type AdminUserStatsResponse = components['schemas']['AdminUserStatsResponse'];
-type OAuthConfigResponse = components['schemas']['OAuthConfigResponse'];
-declare class AdminNamespace implements AdminNamespace$1 {
-    private readonly backend;
-    constructor(backend: IBackendOperations);
-    users(): Promise<User[]>;
-    userStats(): Promise<AdminUserStatsResponse>;
-    updateUser(userId: UserDID, data: RequestContent<paths['/api/admin/users/{id}']['patch']>): Promise<User>;
-    oauthConfig(): Promise<OAuthConfigResponse>;
-    healthCheck(): Promise<ResponseContent<paths['/api/health']['get']>>;
-    status(): Promise<ResponseContent<paths['/api/status']['get']>>;
-    backup(): Promise<BackendDownload>;
-    restore(file: File): StreamObservable<ProgressEvent>;
-    exportKnowledgeBase(params?: {
-        includeArchived?: boolean;
-    }): Promise<BackendDownload>;
-    importKnowledgeBase(file: File): StreamObservable<ProgressEvent>;
-}
-
-declare class SemiontClient {
-    /**
-     * The wire-facing transport. Owns bus actor, HTTP, auth, admin, exchange,
-     * system. Exposed for advanced consumers (workers, custom job adapters)
-     * that need raw `transport.emit(channel, payload, scope)` access. Ordinary
-     * consumers go through typed namespace methods.
-     */
-    readonly transport: ITransport;
-    /** Binary I/O transport. */
-    private readonly content;
-    /**
-     * Per-client local EventBus. Wire events flow in via the transport
-     * bridge. Read-only public so `SemiontSession.subscribe(channel, …)`
-     * can wire arbitrary-channel subscriptions; everything else uses
-     * typed namespace methods.
-     */
-    readonly bus: EventBus;
-    readonly baseUrl: BaseUrl;
-    readonly frame: FrameNamespace;
-    readonly browse: BrowseNamespace;
-    readonly mark: MarkNamespace;
-    readonly bind: BindNamespace;
-    readonly gather: GatherNamespace;
-    readonly match: MatchNamespace;
-    readonly yield: YieldNamespace;
-    readonly beckon: BeckonNamespace;
-    readonly job: JobNamespace;
-    readonly auth: AuthNamespace | undefined;
-    readonly admin: AdminNamespace | undefined;
-    /**
-     * The client *owns* its bus. The constructor creates a fresh `EventBus`
-     * and hands it to the transport via `transport.bridgeInto(this.bus)`.
-     * The reference flows client → transport, never the other way:
-     * the transport stores the reference and publishes the events it
-     * receives onto that bus. `HttpTransport` does so for every channel
-     * delivered on its SSE wire; in-process transports adapt their
-     * internal source.
-     *
-     * Callers do not pass a bus in. If they need to interact with the bus
-     * (e.g. for tests or to subscribe to arbitrary channels), they read it
-     * back via `client.bus`.
-     *
-     * `backend` is optional. When provided, the `auth` and `admin`
-     * namespaces are constructed against it; when omitted, they're
-     * `undefined`. For HTTP setups this is conventionally the same
-     * `HttpTransport` instance that's also passed as `transport` (HTTP
-     * implements both `ITransport` and `IBackendOperations`).
-     */
-    constructor(transport: ITransport, content: IContentTransport, backend?: IBackendOperations);
-    /** Transport-level connection state. HTTP reflects SSE health; local is always 'connected'. */
-    get state$(): rxjs.Observable<_semiont_core.ConnectionState>;
-    subscribeToResource(resourceId: ResourceId): () => void;
-    dispose(): void;
-    /**
-     * Convenience factory for the default HTTP setup. Constructs a
-     * `BehaviorSubject<AccessToken | null>` internally, plus an
-     * `HttpTransport` and `HttpContentTransport`, and returns the wired
-     * `SemiontClient`.
-     *
-     * Use this for one-shot scripts, CLI commands, or any consumer that
-     * doesn't need to drive the token from outside (no manual refresh,
-     * no cross-tab sync). For long-running scripts that need refresh,
-     * use `SemiontSession.fromHttp(...)` (with a token already on hand)
-     * or `SemiontSession.signInHttp(...)` (credentials-first) instead —
-     * either owns the same transport/client wiring plus the
-     * proactive-refresh + storage machinery.
-     *
-     * Strings are accepted for `baseUrl` and `token`; they are branded
-     * via `baseUrl()` / `accessToken()` from `@semiont/core` automatically.
-     * Pass the already-branded values if you have them.
-     *
-     * Omit `token` for unauthenticated usage (public endpoints only).
-     */
-    static fromHttp(opts: {
-        baseUrl: BaseUrl | string;
-        token?: AccessToken | string | null;
-    }): SemiontClient;
-    /**
-     * Async factory for the credentials-first script case. Builds a
-     * transient HTTP transport, calls `auth.password(email, password)`
-     * to acquire an access token, and returns the wired client with
-     * the token populated.
-     *
-     * This is the right entry point for skills, CLI scripts, and any
-     * consumer that starts with email + password rather than a JWT
-     * already on hand. For consumers that already hold a token (CLI
-     * cached-token path, env-var token, embedded auth flow), use
-     * `fromHttp({ baseUrl, token })` instead.
-     *
-     * For long-running scripts that need refresh, use
-     * `SemiontSession.signInHttp(...)` — same credentials shape, plus
-     * the session machinery for proactive refresh and persistence.
-     *
-     * Named `signInHttp` because email+password authentication is
-     * inherently an HTTP-shaped operation in the current backend; an
-     * in-process `LocalTransport` doesn't have a credentials login
-     * path. Non-HTTP transports construct the client directly from
-     * their package's transport instance.
-     *
-     * Throws if authentication fails. The transient client is disposed
-     * before the throw, so no resources leak on failure.
-     */
-    static signInHttp(opts: {
-        baseUrl: BaseUrl | string;
-        email: string;
-        password: string;
-    }): Promise<SemiontClient>;
-}
-
-type BusRequestErrorCode = 'bus.timeout' | 'bus.rejected' | 'bus.bad-payload' | 'bus.unauthorized' | 'bus.forbidden' | 'bus.not-found';
-declare class BusRequestError extends SemiontError {
-    code: BusRequestErrorCode;
-    constructor(message: string, code: BusRequestErrorCode, details?: Record<string, unknown>);
-}
-/**
- * Subset of ITransport that `busRequest` needs: a way to send a command and
- * a way to observe channels. Generic enough that an in-process transport
- * can satisfy it without round-tripping through HTTP.
- */
-interface BusRequestPrimitive {
-    emit<K extends keyof EventMap>(channel: K, payload: EventMap[K]): Promise<void>;
-    stream<K extends keyof EventMap>(channel: K): Observable<EventMap[K]>;
-}
-declare function busRequest<TResult>(bus: BusRequestPrimitive, emitChannel: string, payload: Record<string, unknown>, resultChannel: string, failureChannel: string, timeoutMs?: number): Promise<TResult>;
-
-/**
- * KnowledgeBase — a connection to a Semiont knowledge system.
- *
- * The KB type itself is uniform. The transport-shape variation lives in
- * the nested `endpoint` field, which is a discriminated union:
+ * @semiont/sdk
  *
- *  - `endpoint.kind === 'http'`  — a remote backend reached over HTTP+SSE.
- *                                  Carries `host`/`port`/`protocol`.
- *  - `endpoint.kind === 'local'` — an in-process knowledge system reached
- *                                  via `LocalTransport` from
- *                                  `@semiont/make-meaning`. Carries an
- *                                  opaque `kbId` identifying the local
- *                                  instance to the host process.
+ * The Semiont SDK — `SemiontClient`, the verb-oriented namespaces, the
+ * per-tab session layer, the flow state machines and worker adapters,
+ * and the supporting helpers (`bus-request`, `cache`).
  *
- * Code that doesn't know how to make a transport (`SemiontSession`,
- * `SemiontBrowser`, the frontend KB list UI) treats `KnowledgeBase` as
- * uniform and never inspects `endpoint`. Code that *does* construct
- * transports (the transport-factory passed to `SemiontBrowser`,
- * `kbBackendUrl` for HTTP URL construction) inspects `endpoint.kind`
- * and dispatches.
+ * Transport-agnostic: `SemiontClient` consumes the `ITransport` /
+ * `IContentTransport` contracts from `@semiont/core`. The HTTP adapters
+ * (`HttpTransport`, `HttpContentTransport`) are re-exported here for
+ * convenience so the common case is a single import; non-HTTP transports
+ * (e.g. `LocalTransport` from `@semiont/make-meaning`) are constructed
+ * by the caller from their own package.
  *
- * Each KB has its own session, its own credentials (where applicable),
- * and its own JWT (HTTP only). The user is "authenticated against KB X" —
- * never globally authenticated.
- */
-/** Fields shared by every KB regardless of endpoint kind. */
-interface KnowledgeBase {
-    id: string;
-    label: string;
-    email: string;
-    gitBranch?: string;
-    endpoint: KbEndpoint;
-}
-type KbEndpoint = HttpEndpoint | LocalEndpoint;
-interface HttpEndpoint {
-    kind: 'http';
-    host: string;
-    port: number;
-    protocol: 'http' | 'https';
-}
-interface LocalEndpoint {
-    kind: 'local';
-    /** Opaque identifier for the in-process KB instance the host has loaded. */
-    kbId: string;
-}
-/**
- * Input shape for adding a new KB. The id is generated by the provider.
- */
-type NewKnowledgeBase = Omit<KnowledgeBase, 'id'>;
-/**
- * Status of the locally-stored credential for a KB. Derived from the
- * presence and validity of the JWT in session storage.
- */
-type KbSessionStatus = 'authenticated' | 'expired' | 'signed-out' | 'unreachable';
-/**
- * Construct a `KnowledgeBase` for an HTTP-backed Semiont backend without
- * spelling out the nested `endpoint` literal. Convenience for tests,
- * worker bootstraps, and one-off scripts.
+ * Transport-specific error classes (`APIError` from `@semiont/api-client`)
+ * are NOT re-exported. Catch on `SemiontError` (exported below) and route
+ * on `err.code`; reach for the transport-specific class only when you're
+ * already in HTTP-aware code and import it from `@semiont/api-client`
+ * directly.
  *
  * ```ts
- * const kb = httpKb({
- *   id: 'my-watcher',
- *   label: 'My Watcher',
- *   email: 'me@example.com',
- *   host: 'localhost',
- *   port: 4000,
- *   protocol: 'http',
- * });
- * ```
- *
- * Equivalent to:
+ * import { SemiontClient, HttpTransport, HttpContentTransport } from '@semiont/sdk';
+ * import { baseUrl } from '@semiont/core';
  *
- * ```ts
- * const kb: KnowledgeBase = {
- *   id, label, email,
- *   endpoint: { kind: 'http', host, port, protocol },
- * };
+ * const transport = new HttpTransport({ baseUrl: baseUrl('https://kb.example/') });
+ * // HttpTransport implements both ITransport and IBackendOperations;
+ * // passing it as the third arg wires `client.auth` and `client.admin`.
+ * const client = new SemiontClient(transport, new HttpContentTransport(transport), transport);
  * ```
- *
- * UI hosts that have a structured form (host / port / protocol pickers)
- * already construct the literal directly — they don't need this helper.
- * Local-endpoint KBs construct the literal directly too; the local
- * endpoint shape (`{ kind: 'local', kbId }`) is one line and doesn't
- * earn a helper.
- */
-declare function httpKb(opts: {
-    id: string;
-    label: string;
-    email: string;
-    host: string;
-    port: number;
-    protocol: 'http' | 'https';
-    gitBranch?: string;
-}): KnowledgeBase;
-
-/**
- * Session-level error surface. Emitted on `SemiontBrowser.error$` for
- * failures that make the session itself unusable (auth failed, actor
- * couldn't start, token refresh terminally exhausted). Per-request
- * errors stay with the caller as normal Promise rejections.
- *
- * `SemiontSessionError` extends `SemiontError` (the unified Semiont base)
- * so consumers can catch with `instanceof SemiontError` for any error
- * surfaced through the SDK.
- */
-
-type SemiontSessionErrorCode = 'session.construct-failed' | 'session.auth-failed' | 'session.refresh-exhausted' | 'browser.sign-in-failed';
-declare class SemiontSessionError extends SemiontError {
-    code: SemiontSessionErrorCode;
-    readonly kbId: string | null;
-    constructor(code: SemiontSessionErrorCode, message: string, kbId?: string | null);
-}
-
-/**
- * SessionStorage — environment-agnostic persistence adapter for the
- * Semiont session layer. Decouples `SemiontSession` / `SemiontBrowser`
- * from `localStorage` / `window` so the same classes can run in a
- * browser, a CLI process, or tests without environment guards.
- *
- * Implementations shipped here:
- *  - `InMemorySessionStorage` — map-backed, for tests.
- *
- * Browser-backed (`WebBrowserStorage`) lives in `@semiont/react-ui`
- * because it touches browser-only globals.
- */
-/** String key/value store with optional cross-context change subscription. */
-interface SessionStorage {
-    /** Read a string value; null if absent. */
-    get(key: string): string | null;
-    /** Write a string value. */
-    set(key: string, value: string): void;
-    /** Remove a key. No-op if absent. */
-    delete(key: string): void;
-    /**
-     * Optional: subscribe to external changes (cross-tab, cross-process).
-     * Browser implements via the `storage` event; filesystem would use
-     * fs.watch; in-memory omits this method. Returns an unsubscribe
-     * callback. If omitted, cross-context sync simply isn't available
-     * in that environment — the session still works correctly within a
-     * single process.
-     */
-    subscribe?(handler: (key: string, newValue: string | null) => void): () => void;
-}
-/**
- * Map-backed `SessionStorage`. Cross-context sync is not implemented;
- * tests that need it can drive it manually.
- */
-declare class InMemorySessionStorage implements SessionStorage {
-    private readonly map;
-    get(key: string): string | null;
-    set(key: string, value: string): void;
-    delete(key: string): void;
-}
-
-/**
- * SemiontSession — per-backend session lifetime object. Owns the
- * SemiontClient, the access token BehaviorSubject, and optionally
- * an authenticated user. One SemiontSession exists per active backend
- * connection; lifetime is decoupled from React mount lifetime.
- *
- * Headless by design. Runs in browsers, CLIs, workers, and tests.
- * UI-specific state (session-expired/permission-denied modals) lives
- * in `SessionSignals`, which wraps a session — the session
- * itself has no modal observables, no user-facing notifications.
- *
- * Auth is parameterized via callbacks passed at construction:
- *
- *   - `refresh()` — invoked on 401 / proactive re-auth. Returns the
- *     new access token, or null on failure. The frontend passes a
- *     closure that runs the refresh-token flow; the worker passes
- *     one that exchanges the shared secret.
- *
- *   - `validate(token)` — optional. If provided, the session calls
- *     it once at startup with the stored token to confirm it's
- *     still good and populate `user$`. Frontend passes `getMe`;
- *     worker omits this (service principals have no user record).
- *
- *   - `onAuthFailed(message)` — optional. Invoked when refresh
- *     terminally fails (expired token, no recovery possible). UI hosts
- *     typically wire this to `SessionSignals.notifySessionExpired` so a
- *     modal surfaces; headless consumers typically just log.
- *
- * Persistence goes through a `SessionStorage` adapter provided at
- * construction — the session never touches `localStorage` or `window`
- * directly.
- */
-
-type UserInfo = components['schemas']['UserResponse'];
-interface SemiontSessionConfig {
-    kb: KnowledgeBase;
-    /** Persistence adapter. Reads/writes tokens via this. */
-    storage: SessionStorage;
-    /**
-     * Pre-built api client. The session does not construct it — caller
-     * builds the transport stack and passes the client in. This is the
-     * seam where consumers swap one `ITransport` implementation for
-     * another (HTTP, in-process, etc.).
-     */
-    client: SemiontClient;
-    /**
-     * Token observable shared with the transport. Caller must pass the
-     * SAME instance to both the transport (via `HttpTransport` config)
-     * and the session. The session writes refreshed tokens here; the
-     * transport reads from here.
-     */
-    token$: BehaviorSubject<AccessToken | null>;
-    /**
-     * Re-authenticate after expiry / 401. Returns a new access token
-     * (no "Bearer " prefix) on success, or null if recovery is
-     * impossible. Omit for transports where tokens don't apply.
-     */
-    refresh?: () => Promise<string | null>;
-    /**
-     * Validate the stored token at startup and populate `user$`. Omit
-     * for service-principal sessions (worker, CLI tools) where there
-     * is no user record to fetch.
-     */
-    validate?: (token: AccessToken) => Promise<UserInfo | null>;
-    /**
-     * Invoked when refresh terminally fails. Frontend consumers wire
-     * this to a UI signal that surfaces the session-expired modal.
-     */
-    onAuthFailed?: (message: string | null) => void;
-    /** Called for session-level failures (auth, refresh exhaustion). */
-    onError?: (err: SemiontSessionError) => void;
-}
-declare class SemiontSession {
-    readonly kb: KnowledgeBase;
-    readonly client: SemiontClient;
-    readonly token$: BehaviorSubject<AccessToken | null>;
-    readonly user$: BehaviorSubject<UserInfo | null>;
-    readonly streamState$: Observable<ConnectionState>;
-    /**
-     * Stream of `SemiontError` instances surfaced by the underlying transport
-     * just before they're thrown to the caller. For `HttpTransport` this is
-     * an `APIError` (status-coded); other transports emit their own subclass.
-     * Surfaced here so a host layer (e.g. `SemiontBrowser`) can route by
-     * `err.code` to global notifications without every call site handling
-     * errors itself. Headless consumers can subscribe for logging.
-     *
-     * Re-published from `client.transport.errors$` per the `ITransport`
-     * contract — the session is purely a passthrough.
-     */
-    readonly errors$: Observable<SemiontError>;
-    /** Resolves after the initial validation round-trip completes (success or failure). */
-    readonly ready: Promise<void>;
-    private readonly storage;
-    private readonly doRefresh?;
-    private readonly doValidate?;
-    private readonly onAuthFailed;
-    private readonly onError;
-    private refreshTimer;
-    private unsubscribeStorage;
-    private disposed;
-    constructor(config: SemiontSessionConfig);
-    /**
-     * Run the initial mount-time validation. If a stored access token is
-     * present and unexpired, call the configured `validate` with it to
-     * confirm it still works and populate `user$`. If expired, try
-     * refresh first. On 401 from validate, try refresh once. Surfaces
-     * auth-failed on terminal failure.
-     *
-     * When no `validate` callback is provided (service principals), this
-     * still runs through the refresh-if-expired step so the stored
-     * token is current — it just skips the user-validation round trip.
-     */
-    private validate;
-    /**
-     * Refresh the access token via the configured `refresh` callback.
-     * On success, pushes the new token into `token$` and schedules the
-     * next proactive refresh. On failure, clears persisted state and
-     * fires `onAuthFailed` — the frontend's wiring of that callback is
-     * what surfaces the session-expired modal.
-     */
-    refresh(): Promise<AccessToken | null>;
-    private scheduleProactiveRefresh;
-    private clearRefreshTimer;
-    /**
-     * Cross-context sync: another tab/process refreshed or signed out this
-     * KB. Mirror the change into our in-memory state.
-     */
-    private handleStorageChange;
-    get expiresAt(): Date | null;
-    /**
-     * Subscribe to a session-bus channel. The single sanctioned escape hatch
-     * for generic-channel subscription (the case `useEventSubscription` needs
-     * — channel name is a hook parameter, not known statically). All other
-     * consumers must call typed namespace methods (e.g. `session.client.mark.archive(...)`).
-     *
-     * @returns disposer that unsubscribes the handler.
-     */
-    subscribe<K extends keyof EventMap>(channel: K, handler: (payload: EventMap[K]) => void): () => void;
-    dispose(): Promise<void>;
-    /**
-     * Convenience factory for the default HTTP setup. Constructs the
-     * shared `BehaviorSubject<AccessToken | null>`, an `HttpTransport`,
-     * an `HttpContentTransport`, and a `SemiontClient`, then wires
-     * the session over them. Removes the load-bearing
-     * "same-token$-instance" invariant from the caller's hands.
-     *
-     * Strings are accepted for `baseUrl` and `token`; they are branded
-     * via `baseUrl()` / `accessToken()` from `@semiont/core` automatically.
-     *
-     * The remaining options (`refresh`, `validate`, `onAuthFailed`,
-     * `onError`) match `SemiontSessionConfig` exactly.
-     */
-    static fromHttp(opts: {
-        kb: KnowledgeBase;
-        storage: SessionStorage;
-        baseUrl: BaseUrl | string;
-        token?: AccessToken | string | null;
-        refresh?: () => Promise<string | null>;
-        validate?: (token: AccessToken) => Promise<UserInfo | null>;
-        onAuthFailed?: (message: string | null) => void;
-        onError?: (err: SemiontSessionError) => void;
-    }): SemiontSession;
-    /**
-     * Async factory for the credentials-first long-running script case.
-     * Builds the HTTP transport stack, calls `auth.password(email,
-     * password)` to acquire access + refresh tokens, persists them via
-     * the storage adapter, wires a default `refresh` callback that
-     * exchanges the refresh token via `auth.refresh(...)`, and returns
-     * the ready session.
-     *
-     * The consumer-supplied `refresh` callback becomes optional — only
-     * needed for non-standard refresh flows (worker-pool shared secret,
-     * OAuth refresh-token grant, interactive re-prompt). The default
-     * uses the refresh token returned by `auth.password`.
-     *
-     * `kb` is required and must be a full `KnowledgeBase`. The `id` field
-     * is the storage key for this session — distinct scripts sharing the
-     * same `SessionStorage` instance must use distinct ids to avoid
-     * trampling each other's tokens. The factory does not synthesize a
-     * default; the consumer makes the choice.
-     *
-     * Named `signInHttp` because email+password authentication is
-     * inherently an HTTP-shaped operation in the current backend; an
-     * in-process `LocalTransport` doesn't have a credentials login
-     * path. Non-HTTP transports construct the session directly from
-     * their package's transport instance.
-     *
-     * Throws on auth failure with no resources leaked. On success, the
-     * returned session's `ready` promise has already resolved.
-     */
-    static signInHttp(opts: {
-        kb: KnowledgeBase;
-        storage: SessionStorage;
-        baseUrl: BaseUrl | string;
-        email: string;
-        password: string;
-        validate?: (token: AccessToken) => Promise<UserInfo | null>;
-        onAuthFailed?: (message: string | null) => void;
-        onError?: (err: SemiontSessionError) => void;
-    }): Promise<SemiontSession>;
-}
-
-/**
- * OpenResource — a single entry in the open-resources list (tabs).
- *
- * The list itself lives on `SemiontBrowser.openResources$`. The CRUD
- * methods (`addOpenResource`, `removeOpenResource`, `updateOpenResourceName`,
- * `reorderOpenResources`) live on `SemiontBrowser` too.
- */
-interface OpenResource {
-    /** Unique identifier for the resource */
-    id: string;
-    /** Display name of the resource */
-    name: string;
-    /** Timestamp when the resource was opened */
-    openedAt: number;
-    /** Order/position for manual sorting (optional for backward compatibility) */
-    order?: number;
-    /** Media type for icon display (e.g., 'application/pdf', 'text/plain') */
-    mediaType?: string;
-    /** Working-tree URI (e.g. "file://docs/overview.md") — used as tooltip in navigation */
-    storageUri?: string;
-}
-
-/**
- * SessionSignals — UI-facing notification state that belongs to the host
- * surface, not to the session itself.
- *
- * `SemiontSession` is a headless per-backend client + token + user
- * holder. It can run in any process: browser, worker, CLI, test. But
- * the session-expired / permission-denied *notifications* are inherently
- * a UI-host concern. Keeping those observables on `SemiontSession` meant
- * workers and CLIs carried four dead BehaviorSubjects that nothing would
- * ever fire.
- *
- * `SessionSignals` owns the notification state and has no hard reference
- * to a session. A UI host (e.g. `SemiontBrowser`) constructs one alongside
- * every active session and wires:
- *
- *   - `session.onAuthFailed` → `signals.notifySessionExpired` so
- *     proactive-refresh failures surface as a notification
- *
- * UI consumers that need to render modal/banner state subscribe here;
- * consumers that need bus/HTTP access continue to subscribe to the session.
- *
- * Session auth-state cleanup (clearing token, clearing storage) is
- * the session's own responsibility inside `refresh()` — by the time
- * `notifySessionExpired` runs, the session has already torn down.
- * Signals only surfaces the notification.
  */
-
-declare class SessionSignals {
-    readonly sessionExpiredAt$: BehaviorSubject<number | null>;
-    readonly sessionExpiredMessage$: BehaviorSubject<string | null>;
-    readonly permissionDeniedAt$: BehaviorSubject<number | null>;
-    readonly permissionDeniedMessage$: BehaviorSubject<string | null>;
-    constructor();
-    notifySessionExpired(message: string | null): void;
-    notifyPermissionDenied(message: string | null): void;
-    acknowledgeSessionExpired(): void;
-    acknowledgePermissionDenied(): void;
-    dispose(): void;
-}
-
-/**
- * SessionFactory — the injection point that lets `SemiontBrowser` stay
- * transport-agnostic.
- *
- * The browser knows how to manage the *lifecycle* of an active session
- * (track it in `activeSession$`, dispose on KB switch, serialize
- * overlapping activations) but does not know how to *construct* one —
- * because that's where transport choice lives. The construction step
- * is parameterized via this factory.
- *
- * The HTTP factory is provided by `createHttpSessionFactory`. A
- * future in-process variant from `@semiont/make-meaning` would expose
- * its own factory.
- */
-
-interface SessionFactoryOptions {
-    /** The KB the session is being constructed for. */
-    kb: KnowledgeBase;
-    /** Persistence adapter — same one the browser uses. */
-    storage: SessionStorage;
-    /** Modal-signal sink for auth-failed / permission-denied notifications. */
-    signals: SessionSignals;
-    /** Receives session-level errors (auth-failed, refresh-exhausted, ...). */
-    onError: (err: SemiontSessionError) => void;
-}
-type SessionFactory = (opts: SessionFactoryOptions) => SemiontSession;
-
-/**
- * SemiontBrowser — top-level app-facing container for non-KB state.
- *
- * Holds the list of configured KBs, the active KB selection, the active
- * SemiontSession, the identity token, the open-resources list, and a
- * session-level error stream. Held as a process-wide instance for the
- * host's lifetime — see `getBrowser()` in `registry.ts` for the canonical
- * accessor.
- *
- * Transport-agnostic: the browser orchestrates session *lifecycle* but
- * delegates session *construction* to a `SessionFactory` injected at
- * construction. HTTP-backed apps pass `createHttpSessionFactory()` from
- * `@semiont/sdk`; in-process apps pass their own factory.
- *
- * Persistence goes through a `SessionStorage` adapter provided at
- * construction — the browser never touches `localStorage` or `window`
- * directly.
- */
-
-interface SemiontBrowserConfig {
-    /** Persistence adapter. The browser reads/writes all persisted state via this. */
-    storage: SessionStorage;
-    /**
-     * Builds a `SemiontSession` for a KB. The browser is transport-
-     * agnostic — every HTTP-vs-local construction concern lives in the
-     * factory. HTTP-backed apps pass `createHttpSessionFactory()` from
-     * `@semiont/sdk`; a future in-process variant from `@semiont/make-meaning`
-     * would expose its own factory.
-     */
-    sessionFactory: SessionFactory;
-}
-declare class SemiontBrowser {
-    readonly kbs$: BehaviorSubject<KnowledgeBase[]>;
-    readonly activeKbId$: BehaviorSubject<string | null>;
-    readonly activeSession$: BehaviorSubject<SemiontSession | null>;
-    /**
-     * Modal signals (session-expired / permission-denied) for the
-     * currently-active session. Parallels `activeSession$` — always
-     * non-null when `activeSession$` is non-null, always null when it
-     * is. Extracted from the session itself so headless sessions
-     * (workers, CLIs, tests) don't carry dead modal observables.
-     * See [SessionSignals](./session-signals.ts).
-     */
-    readonly activeSignals$: BehaviorSubject<SessionSignals | null>;
-    /**
-     * True while a session is actively being constructed (setActiveKb /
-     * signIn in flight, awaiting `session.ready`). Distinguishes the
-     * "session about to arrive" intermediate state from "session
-     * intentionally null" (after signOut, or when the active KB has no
-     * stored credentials). UIs that want a loading spinner should gate
-     * on this; otherwise they get stuck spinning after every signOut.
-     */
-    readonly sessionActivating$: BehaviorSubject<boolean>;
-    readonly openResources$: BehaviorSubject<OpenResource[]>;
-    readonly error$: Subject<SemiontSessionError>;
-    readonly identityToken$: BehaviorSubject<string | null>;
-    private readonly storage;
-    private readonly sessionFactory;
-    /**
-     * App-scoped EventBus. Hosts UI-shell events that must work regardless
-     * of whether a KB session is active: panel toggles, sidebar state,
-     * tab reorders, routing, settings, etc. Disjoint from the per-session
-     * bus inside `SemiontClient`, which carries KB-content events
-     * (mark:*, beckon:*, gather:*, match:*, bind:*, yield:*, browse:click).
-     */
-    private readonly eventBus;
-    private unsubscribeStorage;
-    private disposed;
-    private activating;
-    constructor(config: SemiontBrowserConfig);
-    /** Emit an event on the browser's app-scoped bus. */
-    emit<K extends keyof EventMap>(channel: K, payload: EventMap[K]): void;
-    /** Subscribe to an event; returns unsubscribe. */
-    on<K extends keyof EventMap>(channel: K, handler: (payload: EventMap[K]) => void): () => void;
-    /** Read-only observable for an app-scoped channel. */
-    stream<K extends keyof EventMap>(channel: K): Observable<EventMap[K]>;
-    /**
-     * Set the app-level identity token. Sourced from whatever the host
-     * environment uses for OAuth sessions (e.g. NextAuth in a browser app).
-     * Should be called once from the host's startup-and-on-change site;
-     * no other code should write to this slot.
-     */
-    setIdentityToken(token: string | null): void;
-    addKb(input: NewKnowledgeBase, access: string, refresh: string): KnowledgeBase;
-    removeKb(id: string): void;
-    /**
-     * Patch a KB in the list. Restricted to the common, endpoint-agnostic
-     * fields (`label`, `email`, `gitBranch`) — the `endpoint` shape isn't
-     * editable in place; remove and re-add to change the connection
-     * target.
-     */
-    updateKb(id: string, updates: {
-        label?: string;
-        email?: string;
-        gitBranch?: string;
-    }): void;
-    /**
-     * Read the locally-stored credential status for a KB. Pure / synchronous —
-     * does not subscribe to context changes. Used by KB-list UI to color status
-     * dots without requiring re-renders on every tick.
-     */
-    getKbSessionStatus(kbId: string): KbSessionStatus;
-    /**
-     * Switch the active KB. Follows the D2 disposal contract:
-     *   1. Synchronously announce the new id on `activeKbId$` and null out
-     *      `activeSession$` so views see a safe empty state first.
-     *   2. Serialize overlapping calls — if an activation is in flight, wait
-     *      for it before proceeding.
-     *   3. Dispose whatever session is currently live.
-     *   4. Construct the next session and await `session.ready`.
-     *   5. Before emitting, re-check `activeKbId$` — if a newer call superseded
-     *      us while we waited, dispose our session and skip the emit.
-     *   6. Emit the new session.
-     */
-    setActiveKb(id: string | null): Promise<void>;
-    /**
-     * Sign in to an existing KB: store the tokens and (re)activate the
-     * session. If the KB is already active, the current session is disposed
-     * and replaced so the new tokens take effect.
-     */
-    signIn(id: string, access: string, refresh: string): Promise<void>;
-    /**
-     * Sign out of a KB: clear stored tokens. If the KB is active, dispose
-     * its session + signals and emit null for both.
-     */
-    signOut(id: string): Promise<void>;
-    addOpenResource(id: string, name: string, mediaType?: string, storageUri?: string): void;
-    removeOpenResource(id: string): void;
-    updateOpenResourceName(id: string, name: string): void;
-    reorderOpenResources(oldIndex: number, newIndex: number): void;
-    dispose(): Promise<void>;
-}
-
-/**
- * createHttpSessionFactory — the default `SessionFactory` for HTTP-backed
- * KBs. Owns every HTTP-specific construction concern that used to live in
- * `SemiontBrowser`: building `HttpTransport`/`HttpContentTransport`,
- * wiring the `tokenRefresher` callback, deduplicating concurrent 401
- * refresh round trips, and invoking the auth endpoints for token refresh
- * and user-validate.
- *
- * Returned as a closure so a single `inFlightRefreshes` map is shared
- * across every session this factory builds — the dedup is meaningful
- * across concurrent session reactivations for the same KB id.
- */
-
-declare function createHttpSessionFactory(): SessionFactory;
-
-/**
- * Process-wide accessor for `SemiontBrowser`. Constructed lazily on the
- * first `getBrowser()` call and held for the host's lifetime — a single
- * instance owns the KB list, identity token, and active-session state,
- * so callers throughout the host get the same view of "which KB am I
- * talking to right now" regardless of where they pick it up.
- *
- * The caller provides a `SessionStorage` implementation and a
- * `SessionFactory` — both are environment-specific (browsers use
- * `WebBrowserStorage` + `createHttpSessionFactory()`, CLI/embedded
- * hosts use a filesystem adapter and possibly a local-process
- * factory, tests use `InMemorySessionStorage` and stubs). The first
- * call to `getBrowser` wins; subsequent calls return the cached
- * instance regardless of the options passed.
- */
-
-interface GetBrowserOptions {
-    /** Persistence adapter used to construct the singleton on first call. */
-    storage: SessionStorage;
-    /** Session factory used to build a `SemiontSession` per active KB. */
-    sessionFactory: SessionFactory;
-}
-declare function getBrowser(options: GetBrowserOptions): SemiontBrowser;
-
-/**
- * Pure helpers and storage-adapter-driven loaders for the Semiont
- * session layer.
- *
- * Contains:
- *  - Storage key shape (constants, `sessionKey(kbId)`)
- *  - JWT expiry parsing and "is expired" check
- *  - URL/protocol helpers for KB instances
- *  - Loaders/savers that take a `SessionStorage` and operate over it
- *    (no direct `localStorage` access)
- *
- * No React imports, no module-scoped state, no side effects beyond
- * whatever the passed-in `SessionStorage` does.
- */
-
-/** The shape persisted per KB. */
-interface StoredSession {
-    access: string;
-    refresh: string;
-}
-declare function setStoredSession(storage: SessionStorage, kbId: string, session: StoredSession): void;
-declare function defaultProtocol(host: string): 'http' | 'https';
-declare function isValidHostname(host: string): boolean;
-/**
- * Build the wire URL for an HTTP KB endpoint. HTTP-shaped helper —
- * lives next to the KB list machinery because the frontend Panel needs
- * it for the auth round-trip when adding a KB. Code that holds a
- * uniform `KnowledgeBase` should not call this; it should hand the KB
- * to a transport factory and let the factory inspect `endpoint.kind`.
- */
-declare function kbBackendUrl(endpoint: HttpEndpoint): string;
-
-/**
- * Marker for the state-unit pattern: a stateful, lifecycled object with an
- * RxJS-shaped public surface, constructed by a factory function
- * (`createFooStateUnit`), with internal state held in a closure.
- *
- * The structural contract is `dispose()` — the rest of the pattern
- * (closure-based identity, Observable public surface, internal Subjects
- * exposed as `.asObservable()` views, no leaked subscriptions, composition
- * by parameter rather than ownership) is convention enforced by review,
- * not the type system.
- *
- * See `packages/sdk/docs/STATE-UNITS.md` for the full axioms and rationale.
- */
-interface StateUnit {
-    /**
-     * Idempotent, total teardown. Completes every Subject the unit owns,
-     * unsubscribes every internal subscription, releases timers / abort
-     * controllers / network handles. Safe to call multiple times — the
-     * second call is a no-op.
-     */
-    dispose(): void;
-}
-/**
- * Compose multiple disposers into a single `dispose()` call. Accepts either
- * a `StateUnit` (whose `dispose()` will be invoked) or a plain teardown
- * function. The returned object is itself disposable; call its `dispose()`
- * once to tear down everything that was added.
- */
-declare function createDisposer(): {
-    add(item: StateUnit | (() => void)): void;
-    dispose(): void;
-};
-
-/**
- * createSearchPipeline
- *
- * A debounced-search RxJS pipeline factory. Combines an input Subject with a
- * downstream fetch function and emits typed `{ results, isSearching }` state.
- *
- * Designed to be created once per consumer instance and held for its lifetime
- * (e.g. by a view layer's lazy initializer), then observed via `state$`. The
- * pipeline is pure RxJS — unit-testable without any view-layer dependency.
- *
- * The fetch function is expected to return `Observable<T[] | undefined>`,
- * matching the cache-miss-then-data shape of `BrowseNamespace` Observables:
- * `undefined` means "fetch in flight, no value yet"; an array means "data
- * available (possibly empty)".
- */
-
-interface SearchState<T> {
-    results: T[];
-    isSearching: boolean;
-}
-interface SearchPipeline<T> {
-    /** Latest query string. Bind to a controlled input. */
-    query$: Observable<string>;
-    /** Latest search state — results plus a loading flag. */
-    state$: Observable<SearchState<T>>;
-    /** Push a new query value. Triggers the debounced fetch. */
-    setQuery(value: string): void;
-    /** Tear down the input Subject. Call from the consumer's cleanup hook. */
-    dispose(): void;
-}
-interface SearchPipelineOptions {
-    /** Milliseconds to wait after the last keystroke before fetching. Default 250. */
-    debounceMs?: number;
-    /** Initial query value. Useful for modals that open with a pre-filled term. */
-    initialQuery?: string;
-}
-declare function createSearchPipeline<T>(fetch: (query: string) => Observable<T[] | undefined>, options?: SearchPipelineOptions): SearchPipeline<T>;
-
-/**
- * WorkerBus — minimal channel-bus surface that worker-side adapters
- * (e.g. `JobClaimAdapter` in `@semiont/jobs`, `SmelterActorStateUnit` in
- * `@semiont/make-meaning`) need.
- *
- * Transport-neutral by design. HTTP `ActorStateUnit` (from `@semiont/api-client`)
- * satisfies it directly; an in-process worker can pass a small shim around
- * an `EventBus` with a `() => Promise<void>` `emit` that calls into the
- * actor system.
- *
- * `addChannels` is optional because in-process buses receive every emit
- * implicitly — only HTTP needs to widen its SSE subscription set to
- * include worker-only channels (`job:queued`, `yield:created`, etc.).
- */
-
-interface WorkerBus {
-    on$<T = Record<string, unknown>>(channel: string): Observable<T>;
-    emit(channel: string, payload: Record<string, unknown>): Promise<void>;
-    addChannels?(channels: readonly string[]): void;
-}
-
-interface BeckonStateUnit extends StateUnit {
-    hoveredAnnotationId$: Observable<AnnotationId | null>;
-    hover(annotationId: AnnotationId | null): void;
-    focus(annotationId: AnnotationId): void;
-    sparkle(annotationId: AnnotationId): void;
-}
-declare function createBeckonStateUnit(client: SemiontClient): BeckonStateUnit;
-/** Default milliseconds the mouse must dwell before beckon:hover is emitted. */
-declare const HOVER_DELAY_MS = 150;
-type EmitHover = (annotationId: AnnotationId | null) => void;
-interface HoverHandlers {
-    handleMouseEnter: (annotationId: AnnotationId) => void;
-    handleMouseLeave: () => void;
-    cleanup: () => void;
-}
-declare function createHoverHandlers(emit: EmitHover, delayMs: number): HoverHandlers;
-
-interface GatherStateUnit extends StateUnit {
-    context$: Observable<GatheredContext | null>;
-    loading$: Observable<boolean>;
-    error$: Observable<Error | null>;
-    annotationId$: Observable<AnnotationId | null>;
-}
-declare function createGatherStateUnit(client: SemiontClient, resourceId: ResourceId): GatherStateUnit;
-
-interface MatchStateUnit extends StateUnit {
-}
-declare function createMatchStateUnit(client: SemiontClient, _resourceId: ResourceId): MatchStateUnit;
-
-type JobProgress$1 = components['schemas']['JobProgress'];
-interface GenerateDocumentOptions {
-    title: string;
-    storageUri: string;
-    prompt?: string;
-    /** Body locale — language the generated resource is written in. Falls back to the state unit's UI locale when unset. */
-    language?: string;
-    /** Source-resource locale — language of the resource the annotation lives on. Forwarded to the prompt for context-snippet awareness. BCP-47. */
-    sourceLanguage?: string;
-    temperature?: number;
-    maxTokens?: number;
-    context: GatheredContext;
-}
-interface YieldStateUnit extends StateUnit {
-    isGenerating$: Observable<boolean>;
-    progress$: Observable<JobProgress$1 | null>;
-    generate(referenceId: string, options: GenerateDocumentOptions): void;
-}
-declare function createYieldStateUnit(client: SemiontClient, resourceId: ResourceId, locale: string): YieldStateUnit;
-
-type JobProgress = components['schemas']['JobProgress'];
-interface PendingAnnotation {
-    selector: Selector | Selector[];
-    motivation: Motivation;
-}
-interface MarkStateUnit extends StateUnit {
-    pendingAnnotation$: Observable<PendingAnnotation | null>;
-    assistingMotivation$: Observable<Motivation | null>;
-    progress$: Observable<JobProgress | null>;
-}
-declare function createMarkStateUnit(client: SemiontClient, resourceId: ResourceId): MarkStateUnit;
-
-export { AdminNamespace, type AnnotationHistoryResponse, AuthNamespace, BeckonNamespace, type BeckonStateUnit, BindNamespace, BrowseNamespace, BusRequestError, type BusRequestErrorCode, type BusRequestPrimitive, CacheObservable, type CreateAnnotationInput, type CreateFromTokenOptions, type CreateResourceInput, FrameNamespace, type GatherAnnotationProgress, GatherNamespace, type GatherStateUnit, type GenerateDocumentOptions, type GenerationOptions, type GetBrowserOptions, HOVER_DELAY_MS, type HoverHandlers, type HttpEndpoint, InMemorySessionStorage, JobNamespace, type KbEndpoint, type KbSessionStatus, type KnowledgeBase, type LocalEndpoint, type MarkAssistEvent, type MarkAssistOptions, type MarkAssistProgress, MarkNamespace, type MarkStateUnit, MatchNamespace, type MatchSearchProgress, type MatchStateUnit, type NewKnowledgeBase, type OpenResource, type PendingAnnotation, type ReferencedByEntry, type RequestContent, type ResponseContent, type SearchPipeline, type SearchPipelineOptions, type SearchState, SemiontBrowser, type SemiontBrowserConfig, SemiontClient, SemiontSession, type SemiontSessionConfig, SemiontSessionError, type SemiontSessionErrorCode, type SessionFactory, type SessionFactoryOptions, SessionSignals, type SessionStorage, type StateUnit, type StoredSession, StreamObservable, UploadObservable, type UploadProgress, type User, type UserInfo, type WorkerBus, type YieldGenerationEvent, YieldNamespace, type YieldStateUnit, busRequest, createBeckonStateUnit, createDisposer, createGatherStateUnit, createHoverHandlers, createHttpSessionFactory, createMarkStateUnit, createMatchStateUnit, createSearchPipeline, createYieldStateUnit, defaultProtocol, getBrowser, httpKb, isValidHostname, kbBackendUrl, setStoredSession };
+export * from './client';
+export { StreamObservable, CacheObservable, UploadObservable, type UploadProgress } from './awaitable';
+export { busRequest, BusRequestError, type BusRequestErrorCode, type BusRequestPrimitive, } from './bus-request';
+export { FrameNamespace } from './namespaces/frame';
+export { BrowseNamespace } from './namespaces/browse';
+export { MarkNamespace } from './namespaces/mark';
+export { BindNamespace } from './namespaces/bind';
+export { GatherNamespace } from './namespaces/gather';
+export { MatchNamespace } from './namespaces/match';
+export { YieldNamespace } from './namespaces/yield';
+export { BeckonNamespace } from './namespaces/beckon';
+export { JobNamespace } from './namespaces/job';
+export { AuthNamespace } from './namespaces/auth';
+export { AdminNamespace } from './namespaces/admin';
+export type * from './namespaces/types';
+export type { Logger, AccessToken, AnnotationId, BaseUrl, RefreshToken, ResourceId, UserId, Annotation, BodyItem, BodyOperation, EntityType, EventMap, GatheredContext, Motivation, ResourceDescriptor, TagCategory, TagSchema, ConnectionState, IContentTransport, ITransport, } from '@semiont/core';
+export { accessToken, annotationId, baseUrl, entityType, refreshToken, resourceId, userId, SemiontError, } from '@semiont/core';
+export { SemiontSession, type SemiontSessionConfig, type UserInfo } from './session/semiont-session';
+export { SemiontBrowser, type SemiontBrowserConfig } from './session/semiont-browser';
+export type { SessionFactory, SessionFactoryOptions } from './session/session-factory';
+export { createHttpSessionFactory } from './session/http-session-factory';
+export { SessionSignals } from './session/session-signals';
+export { SemiontSessionError, type SemiontSessionErrorCode } from './session/errors';
+export { getBrowser, type GetBrowserOptions } from './session/registry';
+export { type SessionStorage, InMemorySessionStorage, } from './session/session-storage';
+export { type KnowledgeBase, type KbEndpoint, type HttpEndpoint, type LocalEndpoint, type NewKnowledgeBase, type KbSessionStatus, httpKb, } from './session/knowledge-base';
+export { type OpenResource } from './session/open-resource';
+export { defaultProtocol, isValidHostname, kbBackendUrl, setStoredSession, type StoredSession, } from './session/storage';
+export * from './state';
+export { firstValueFrom, lastValueFrom } from 'rxjs';
+//# sourceMappingURL=index.d.ts.map