@semiont/sdk 0.5.4 → 0.5.6

package/dist/index.d.ts

@@ -1,61 +1,1801 @@
+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';
+
 /**
- * @semiont/sdk
+ * Thenable Observable subclasses.
  *
- * 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`).
+ * 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).
  *
- * 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.
+ * The point: scripts can `await` the call directly without `lastValueFrom` /
+ * `firstValueFrom` wrappers; reactive consumers keep using `.subscribe(...)`
+ * and `.pipe(...)` exactly as before.
  *
- * 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.
+ * 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 (the one-shot path) fetches a **fresh** value via the optional
+ * `fetchFresh` action and rejects on failure — a re-read reflects writes
+ * (#847). Subscribing yields the SWR sequence: the initial `undefined`, the
+ * loaded value, and re-emits on invalidation. (Without a `fetchFresh` action
+ * — e.g. a non-cache wrapper — the await falls back to the first
+ * non-undefined emission.)
+ *
+ * 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> {
+    /**
+     * Optional one-shot fresh-fetch action. When present, `then()` (the await
+     * path) resolves to a freshly fetched value and rejects on fetch failure —
+     * so a re-read reflects writes (#847). `.subscribe(...)` never uses it: it
+     * keeps the stale-while-revalidate cached view over `source`.
+     */
+    private fetchFresh?;
+    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`.
+     *
+     * `fetchFresh`, when supplied, backs the await path: `await` resolves to a
+     * freshly fetched value (rejecting on failure), so a one-shot read reflects
+     * writes without a scoped subscription (#847). `.subscribe(...)` consumers
+     * keep the SWR view over `source`.
+     *
+     * 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>, fetchFresh?: () => Promise<T>): 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;
+    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;
+        entityType?: 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;
+    entityType?: 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;
+    /**
+     * Per-source memo for the scope-acquiring wrapper (#847 Phase 4), keyed by
+     * the underlying (stable, per-key) cache observable so the wrapped
+     * observable is itself stable per key — preserving B4/B11 referential
+     * identity through to `CacheObservable.from`'s own memo.
+     */
+    private readonly scopedSources;
+    constructor(transport: ITransport, bus: EventBus, content: IContentTransport);
+    /**
+     * Wrap a resource-scoped live query's source so that *subscribing* acquires
+     * the resource's scope (via the transport's ref-counted
+     * `subscribeToResource`) and the last unsubscribe releases it (#847 Phase 4).
+     * Freshness follows observation: a `.subscribe()` keeps `rId`'s scoped
+     * events flowing — so `mark:*` / entity-tag invalidations reach this cache —
+     * with no separate `subscribeToResource` call from the consumer.
+     *
+     * The one-shot `await` path does NOT go through here (it resolves via the
+     * cache's `fetch` — see `CacheObservable.from`'s `fetchFresh`), so a
+     * one-shot read acquires no scope.
+     *
+     * Memoized per source so the wrapped observable is stable per key (B4/B11).
+     * Each subscription calls `subscribeToResource(rId)`; the transport
+     * ref-counts concurrent subscriptions for the same resource onto a single
+     * SSE scope. Single-scope model unchanged — multi-scope is deferred (see
+     * `.plans/MULTI-RESOURCE-SCOPE.md`).
+     */
+    private withScope;
+    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 (global; filter by `jobId`). */
+    get complete$(): Observable<EventMap['job:complete']>;
+    /** Live stream of `job:fail` events (global; filter by `jobId`). */
+    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>;
+    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:
+ *
+ *  - `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.
+ *
+ * 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.
+ *
+ * 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.
  *
  * ```ts
- * import { SemiontClient, HttpTransport, HttpContentTransport } from '@semiont/sdk';
- * import { baseUrl } from '@semiont/core';
+ * const kb = httpKb({
+ *   id: 'my-watcher',
+ *   label: 'My Watcher',
+ *   email: 'me@example.com',
+ *   host: 'localhost',
+ *   port: 4000,
+ *   protocol: 'http',
+ * });
+ * ```
+ *
+ * Equivalent to:
  *
- * 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);
+ * ```ts
+ * const kb: KnowledgeBase = {
+ *   id, label, email,
+ *   endpoint: { kind: 'http', host, port, protocol },
+ * };
  * ```
+ *
+ * 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.
  */
-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
+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, AuthNamespace, BeckonNamespace, BindNamespace, BrowseNamespace, BusRequestError, CacheObservable, FrameNamespace, GatherNamespace, HOVER_DELAY_MS, InMemorySessionStorage, JobNamespace, MarkNamespace, MatchNamespace, SemiontBrowser, SemiontClient, SemiontSession, SemiontSessionError, SessionSignals, StreamObservable, UploadObservable, YieldNamespace, busRequest, createBeckonStateUnit, createDisposer, createGatherStateUnit, createHoverHandlers, createHttpSessionFactory, createMarkStateUnit, createMatchStateUnit, createSearchPipeline, createYieldStateUnit, defaultProtocol, getBrowser, httpKb, isValidHostname, kbBackendUrl, setStoredSession };
+export type { AnnotationHistoryResponse, BeckonStateUnit, BusRequestErrorCode, BusRequestPrimitive, CreateAnnotationInput, CreateFromTokenOptions, CreateResourceInput, GatherAnnotationProgress, GatherStateUnit, GenerateDocumentOptions, GenerationOptions, GetBrowserOptions, HoverHandlers, HttpEndpoint, KbEndpoint, KbSessionStatus, KnowledgeBase, LocalEndpoint, MarkAssistEvent, MarkAssistOptions, MarkAssistProgress, MarkStateUnit, MatchSearchProgress, MatchStateUnit, NewKnowledgeBase, OpenResource, PendingAnnotation, ReferencedByEntry, RequestContent, ResponseContent, SearchPipeline, SearchPipelineOptions, SearchState, SemiontBrowserConfig, SemiontSessionConfig, SemiontSessionErrorCode, SessionFactory, SessionFactoryOptions, SessionStorage, StateUnit, StoredSession, UploadProgress, User, UserInfo, WorkerBus, YieldGenerationEvent, YieldStateUnit };