@semiont/api-client 0.4.21 → 0.5.0

package/dist/index.d.ts

@@ -1,15 +1,11 @@
-import { components, UserDID, paths, ResourceId, AnnotationId, GraphConnection, UpdateResourceInput, Motivation, BodyOperation, GatheredContext, JobId, EventBus, AccessToken, BaseUrl, Logger, EventMap, Email, RefreshToken, GoogleCredential, ContentFormat, SearchQuery, CloneToken, EntityType, Selector } from '@semiont/core';
-export { Logger, Selector, getFragmentSelector, getSvgSelector, getTextPositionSelector, validateSvgMarkup } from '@semiont/core';
-import { Observable, BehaviorSubject, Subject } from 'rxjs';
-export { BoundingBox, ContentCache, FragmentSelector, JWTTokenSchema, LOCALES, LocaleInfo, MatchQuality, Point, SvgSelector, TextPosition, TextPositionSelector, TextQuoteSelector, ValidatedAnnotation, ValidationFailure, ValidationResult, ValidationSuccess, buildContentCache, createCircleSvg, createPolygonSvg, createRectangleSvg, decodeRepresentation, decodeWithCharset, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findTextWithContext, formatLocaleDisplay, getAllLocaleCodes, getAnnotationExactText, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getNodeEncoding, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getStorageUri, getTargetSelector, getTargetSource, getTextQuoteSelector, hasTargetSelector, isArchived, isAssessment, isBodyResolved, isComment, isDraft, isHighlight, isReference, isResolvedReference, isStubReference, isTag, isValidEmail, normalizeCoordinates, normalizeText, parseSvgSelector, scaleSvgToNative, validateAndCorrectOffsets, validateData, verifyPosition } from './utils/index.js';
+import { KyInstance } from 'ky';
+import { Observable, BehaviorSubject } from 'rxjs';
+import { ConnectionState, ITransport, BaseUrl, AccessToken, Logger, EventMap, ResourceId, EventBus, Email, components, GoogleCredential, RefreshToken, UserResponse, ListUsersResponse, UserDID, UpdateUserRequest, UpdateUserResponse, ProgressCallback, ProgressEvent, HealthCheckResponse, StatusResponse, IContentTransport, PutBinaryRequest, ContentFormat } from '@semiont/core';
 
+/** Minimal ViewModel surface — anything with a `dispose()` method. */
 interface ViewModel {
     dispose(): void;
 }
-declare function createDisposer(): {
-    add(vm: ViewModel | (() => void)): void;
-    dispose(): void;
-};
 
 interface BusEvent {
     channel: string;
@@ -23,23 +19,6 @@ interface ActorVMOptions {
     scope?: string;
     reconnectMs?: number;
 }
-/**
- * Connection state exposed by the SSE bus actor.
- *
- *   initial      ─ before start() has been called
- *   connecting   ─ fetch() in flight, no bytes yet
- *   open         ─ SSE stream live, first byte seen
- *   reconnecting ─ open → dropped, retrying; may be transient
- *   degraded     ─ has been reconnecting for > DEGRADED_THRESHOLD_MS;
- *                  UI banner threshold; distinguishes brief mount-
- *                  churn cycles from sustained disconnection
- *   closed       ─ stop()/dispose() called; terminal
- *
- * Transition rules are enforced by a helper that throws on invalid
- * transitions — catches bugs in the reconnect loop that would
- * otherwise strand the observable in a lying value.
- */
-type ConnectionState = 'initial' | 'connecting' | 'open' | 'reconnecting' | 'degraded' | 'closed';
 /** Time in the `reconnecting` state before transitioning to `degraded`. */
 declare const DEGRADED_THRESHOLD_MS = 3000;
 interface ActorVM extends ViewModel {
@@ -54,672 +33,31 @@ interface ActorVM extends ViewModel {
 declare function createActorVM(options: ActorVMOptions): ActorVM;
 
 /**
- * Verb Namespace Interfaces
- *
- * These interfaces define the public API of the Semiont api-client,
- * 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
- * proxy handles HTTP, auth, SSE, and caching internally.
- *
- * Return type conventions:
- * - Browse live queries → Observable (bus gateway driven, cached)
- * - Browse one-shot reads → Promise (fetch once, no cache)
- * - Commands (mark, bind, yield.resource) → Promise (fire-and-forget)
- * - Long-running ops (gather, match, yield.fromAnnotation, mark.assist) → Observable (progress + result)
- * - Ephemeral signals (beckon) → void
- */
-
-type Annotation$2 = components['schemas']['Annotation'];
-type ResourceDescriptor$5 = components['schemas']['ResourceDescriptor'];
-type StoredEventResponse$2 = components['schemas']['StoredEventResponse'];
-type GatherProgress = components['schemas']['GatherProgress'];
-type MatchSearchResult = components['schemas']['MatchSearchResult'];
-type JobProgress$2 = components['schemas']['JobProgress'];
-type YieldProgress$1 = JobProgress$2;
-type GatherAnnotationComplete = components['schemas']['GatherAnnotationComplete'];
-type JobStatusResponse$1 = components['schemas']['JobStatusResponse'];
-type AuthResponse$1 = components['schemas']['AuthResponse'];
-type OAuthConfigResponse$1 = components['schemas']['OAuthConfigResponse'];
-type AdminUserStatsResponse$1 = components['schemas']['AdminUserStatsResponse'];
-type ResponseContent$1<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$1<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;
-    language?: string;
-    temperature?: number;
-    maxTokens?: number;
-}
-/** Options for mark.assist() */
-interface MarkAssistOptions {
-    entityTypes?: string[];
-    includeDescriptiveReferences?: boolean;
-    instructions?: string;
-    density?: number;
-    tone?: string;
-    language?: 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 emitted by mark.assist() Observable.
- * Each emission is a JobProgress snapshot (unified job lifecycle). The
- * Observable completes on `job:complete`; errors on `job:fail`.
- */
-type MarkAssistProgress = JobProgress$2;
-/**
- * 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): Observable<ResourceDescriptor$5 | undefined>;
-    resources(filters?: {
-        limit?: number;
-        archived?: boolean;
-        search?: string;
-    }): Observable<ResourceDescriptor$5[] | undefined>;
-    annotations(resourceId: ResourceId): Observable<Annotation$2[] | undefined>;
-    annotation(resourceId: ResourceId, annotationId: AnnotationId): Observable<Annotation$2 | undefined>;
-    entityTypes(): Observable<string[] | undefined>;
-    referencedBy(resourceId: ResourceId): Observable<ReferencedByEntry[] | undefined>;
-    events(resourceId: ResourceId): Observable<StoredEventResponse$2[] | undefined>;
-    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$2[]>;
-    annotationHistory(resourceId: ResourceId, annotationId: AnnotationId): Promise<AnnotationHistoryResponse>;
-    connections(resourceId: ResourceId): Promise<GraphConnection[]>;
-    backlinks(resourceId: ResourceId): Promise<Annotation$2[]>;
-    resourcesByName(query: string, limit?: number): Promise<ResourceDescriptor$5[]>;
-    files(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount'): Promise<components['schemas']['BrowseFilesResponse']>;
-}
-/**
- * Mark — annotation CRUD, entity types, AI assist
- *
- * 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(resourceId: ResourceId, input: CreateAnnotationInput): Promise<{
-        annotationId: string;
-    }>;
-    delete(resourceId: ResourceId, annotationId: AnnotationId): Promise<void>;
-    entityType(type: string): Promise<void>;
-    entityTypes(types: string[]): Promise<void>;
-    updateResource(resourceId: ResourceId, data: UpdateResourceInput): Promise<void>;
-    archive(resourceId: ResourceId): Promise<void>;
-    unarchive(resourceId: ResourceId): Promise<void>;
-    assist(resourceId: ResourceId, motivation: Motivation, options: MarkAssistOptions): Observable<MarkAssistProgress>;
-}
-/**
- * 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>;
-}
-/**
- * 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(annotationId: AnnotationId, resourceId: ResourceId, options?: {
-        contextWindow?: number;
-    }): Observable<GatherAnnotationProgress>;
-    resource(resourceId: ResourceId, options?: {
-        contextWindow?: number;
-    }): Observable<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: string, context: GatheredContext, options?: {
-        limit?: number;
-        useSemanticScoring?: boolean;
-    }): Observable<MatchSearchProgress>;
-}
-/**
- * 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): Promise<{
-        resourceId: string;
-    }>;
-    fromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options: GenerationOptions): Observable<YieldProgress$1>;
-    cloneToken(resourceId: ResourceId): Promise<{
-        token: string;
-        expiresAt: string;
-    }>;
-    fromToken(token: string): Promise<ResourceDescriptor$5>;
-    createFromToken(options: CreateFromTokenOptions): Promise<{
-        resourceId: string;
-    }>;
-}
-/**
- * Beckon — attention coordination
+ * HttpTransport — the HTTP/SSE implementation of ITransport.
  *
- * Fire-and-forget. Ephemeral presence signal delivered via the
- * attention-stream to other participants.
+ * Phase 1 of TRANSPORT-ABSTRACTION. Owns everything that crosses the wire
+ * in remote mode: the bus actor (SSE + POST /bus/emit), auth/admin/exchange/
+ * system HTTP endpoints, and connection-state plumbing.
  *
- * Backend actor: (frontend relay via attention-stream)
- * Event prefix: beckon:*
- */
-interface BeckonNamespace$1 {
-    attention(annotationId: AnnotationId, resourceId: ResourceId): void;
-}
-/**
- * Job — worker lifecycle
- */
-interface JobNamespace$1 {
-    status(jobId: JobId): Promise<JobStatusResponse$1>;
-    pollUntilComplete(jobId: JobId, options?: {
-        interval?: number;
-        timeout?: number;
-        onProgress?: (status: JobStatusResponse$1) => void;
-    }): Promise<JobStatusResponse$1>;
-    cancel(jobId: JobId, type: string): Promise<void>;
-}
-/**
- * Auth — authentication
- */
-interface AuthNamespace$1 {
-    password(email: string, password: string): Promise<AuthResponse$1>;
-    google(credential: string): Promise<AuthResponse$1>;
-    refresh(token: string): Promise<AuthResponse$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$1<paths['/api/admin/users/{id}']['patch']>): Promise<User>;
-    oauthConfig(): Promise<OAuthConfigResponse$1>;
-    healthCheck(): Promise<ResponseContent$1<paths['/api/health']['get']>>;
-    status(): Promise<ResponseContent$1<paths['/api/status']['get']>>;
-    backup(): Promise<Response>;
-    restore(file: File, onProgress?: (event: {
-        phase: string;
-        message?: string;
-        result?: Record<string, unknown>;
-    }) => void): Promise<{
-        phase: string;
-        message?: string;
-        result?: Record<string, unknown>;
-    }>;
-    exportKnowledgeBase(params?: {
-        includeArchived?: boolean;
-    }): Promise<Response>;
-    importKnowledgeBase(file: File, onProgress?: (event: {
-        phase: string;
-        message?: string;
-        result?: Record<string, unknown>;
-    }) => void): Promise<{
-        phase: string;
-        message?: string;
-        result?: Record<string, unknown>;
-    }>;
-}
-
-type Annotation$1 = components['schemas']['Annotation'];
-type ResourceDescriptor$4 = components['schemas']['ResourceDescriptor'];
-type StoredEventResponse$1 = components['schemas']['StoredEventResponse'];
-type TokenGetter$4 = () => AccessToken | undefined;
-type ResourceListFilters = {
-    limit?: number;
-    archived?: boolean;
-    search?: string;
-};
-declare class BrowseNamespace implements BrowseNamespace$1 {
-    private readonly http;
-    private readonly eventBus;
-    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 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;
-    private readonly getToken;
-    private readonly actor;
-    constructor(http: SemiontApiClient, eventBus: EventBus, getToken: TokenGetter$4, actor: ActorVM);
-    resource(resourceId: ResourceId): Observable<ResourceDescriptor$4 | undefined>;
-    resources(filters?: ResourceListFilters): Observable<ResourceDescriptor$4[] | undefined>;
-    annotations(resourceId: ResourceId): Observable<Annotation$1[] | undefined>;
-    annotation(resourceId: ResourceId, annotationId: AnnotationId): Observable<Annotation$1 | undefined>;
-    entityTypes(): Observable<string[] | undefined>;
-    referencedBy(resourceId: ResourceId): Observable<ReferencedByEntry[] | undefined>;
-    events(resourceId: ResourceId): Observable<StoredEventResponse$1[] | undefined>;
-    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$1[]>;
-    resourcesByName(_query: string, _limit?: number): Promise<ResourceDescriptor$4[]>;
-    files(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount'): Promise<components['schemas']['BrowseFilesResponse']>;
-    invalidateAnnotationList(resourceId: ResourceId): void;
-    removeAnnotationDetail(annotationId: AnnotationId): void;
-    invalidateResourceDetail(id: ResourceId): void;
-    invalidateResourceLists(): void;
-    invalidateEntityTypes(): void;
-    invalidateReferencedBy(resourceId: ResourceId): void;
-    invalidateResourceEvents(resourceId: ResourceId): void;
-    updateAnnotationInPlace(resourceId: ResourceId, annotation: Annotation$1): 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;
-}
-
-type TokenGetter$3 = () => AccessToken | undefined;
-declare class MarkNamespace implements MarkNamespace$1 {
-    private readonly http;
-    private readonly eventBus;
-    private readonly getToken;
-    private readonly actor;
-    constructor(http: SemiontApiClient, eventBus: EventBus, getToken: TokenGetter$3, actor: ActorVM);
-    annotation(resourceId: ResourceId, input: CreateAnnotationInput): Promise<{
-        annotationId: string;
-    }>;
-    delete(resourceId: ResourceId, annotationId: AnnotationId): Promise<void>;
-    entityType(type: string): Promise<void>;
-    entityTypes(types: string[]): Promise<void>;
-    updateResource(resourceId: ResourceId, data: UpdateResourceInput): Promise<void>;
-    archive(resourceId: ResourceId): Promise<void>;
-    unarchive(resourceId: ResourceId): Promise<void>;
-    assist(resourceId: ResourceId, motivation: Motivation, options: MarkAssistOptions): Observable<MarkAssistProgress>;
-    private dispatchAssist;
-}
-
-declare class BindNamespace implements BindNamespace$1 {
-    private readonly actor;
-    constructor(actor: ActorVM);
-    body(resourceId: ResourceId, annotationId: AnnotationId, operations: BodyOperation[]): Promise<void>;
-}
-
-declare class GatherNamespace implements GatherNamespace$1 {
-    private readonly eventBus;
-    private readonly actor;
-    constructor(eventBus: EventBus, actor: ActorVM);
-    annotation(annotationId: AnnotationId, resourceId: ResourceId, options?: {
-        contextWindow?: number;
-    }): Observable<GatherAnnotationProgress>;
-    resource(_resourceId: ResourceId, _options?: {
-        contextWindow?: number;
-    }): Observable<GatherAnnotationProgress>;
-}
-
-declare class MatchNamespace implements MatchNamespace$1 {
-    private readonly eventBus;
-    private readonly actor;
-    constructor(eventBus: EventBus, actor: ActorVM);
-    search(resourceId: ResourceId, referenceId: string, context: GatheredContext, options?: {
-        limit?: number;
-        useSemanticScoring?: boolean;
-    }): Observable<MatchSearchProgress>;
-}
-
-type YieldProgress = components['schemas']['JobProgress'];
-
-type ResourceDescriptor$3 = components['schemas']['ResourceDescriptor'];
-type TokenGetter$2 = () => AccessToken | undefined;
-declare class YieldNamespace implements YieldNamespace$1 {
-    private readonly http;
-    private readonly eventBus;
-    private readonly getToken;
-    private readonly actor;
-    constructor(http: SemiontApiClient, eventBus: EventBus, getToken: TokenGetter$2, actor: ActorVM);
-    resource(data: CreateResourceInput): Promise<{
-        resourceId: string;
-    }>;
-    fromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options: GenerationOptions): Observable<YieldProgress>;
-    cloneToken(resourceId: ResourceId): Promise<{
-        token: string;
-        expiresAt: string;
-    }>;
-    fromToken(token: string): Promise<ResourceDescriptor$3>;
-    createFromToken(options: CreateFromTokenOptions): Promise<{
-        resourceId: string;
-    }>;
-}
-
-declare class BeckonNamespace implements BeckonNamespace$1 {
-    private readonly actor;
-    constructor(actor: ActorVM);
-    attention(annotationId: AnnotationId, resourceId: ResourceId): void;
-}
-
-type JobStatusResponse = components['schemas']['JobStatusResponse'];
-declare class JobNamespace implements JobNamespace$1 {
-    private readonly actor;
-    constructor(actor: ActorVM);
-    status(jobId: JobId): Promise<JobStatusResponse>;
-    pollUntilComplete(jobId: JobId, options?: {
-        interval?: number;
-        timeout?: number;
-        onProgress?: (status: JobStatusResponse) => void;
-    }): Promise<JobStatusResponse>;
-    cancel(jobId: JobId, type: string): Promise<void>;
-}
-
-/**
- * AuthNamespace — authentication
+ * Does NOT own the local coordination bus — that lives on `SemiontClient`.
+ * `bridgeInto(bus)` wires SSE-received events into the caller-supplied bus
+ * once at construction.
  */
 
 type AuthResponse = components['schemas']['AuthResponse'];
-type TokenGetter$1 = () => AccessToken | undefined;
-declare class AuthNamespace implements AuthNamespace$1 {
-    private readonly http;
-    private readonly getToken;
-    constructor(http: SemiontApiClient, getToken: TokenGetter$1);
-    password(emailStr: string, passwordStr: string): Promise<AuthResponse>;
-    google(credential: string): Promise<AuthResponse>;
-    refresh(token: string): Promise<AuthResponse>;
-    logout(): Promise<void>;
-    me(): Promise<User>;
-    acceptTerms(): Promise<void>;
-    mcpToken(): Promise<{
-        token: string;
-    }>;
-    mediaToken(resourceId: ResourceId): Promise<{
-        token: string;
-    }>;
-}
-
-/**
- * AdminNamespace — administration
- */
-
+type TokenRefreshResponse = components['schemas']['TokenRefreshResponse'];
 type AdminUserStatsResponse = components['schemas']['AdminUserStatsResponse'];
 type OAuthConfigResponse = components['schemas']['OAuthConfigResponse'];
-type TokenGetter = () => AccessToken | undefined;
-declare class AdminNamespace implements AdminNamespace$1 {
-    private readonly http;
-    private readonly getToken;
-    constructor(http: SemiontApiClient, getToken: TokenGetter);
-    users(): Promise<User[]>;
-    userStats(): Promise<AdminUserStatsResponse>;
-    updateUser(userId: UserDID, data: RequestContent$1<paths['/api/admin/users/{id}']['patch']>): Promise<User>;
-    oauthConfig(): Promise<OAuthConfigResponse>;
-    healthCheck(): Promise<ResponseContent$1<paths['/api/health']['get']>>;
-    status(): Promise<ResponseContent$1<paths['/api/status']['get']>>;
-    backup(): Promise<Response>;
-    restore(file: File, onProgress?: (event: {
-        phase: string;
-        message?: string;
-        result?: Record<string, unknown>;
-    }) => void): Promise<{
-        phase: string;
-        message?: string;
-        result?: Record<string, unknown>;
-    }>;
-    exportKnowledgeBase(params?: {
-        includeArchived?: boolean;
-    }): Promise<Response>;
-    importKnowledgeBase(file: File, onProgress?: (event: {
-        phase: string;
-        message?: string;
-        result?: Record<string, unknown>;
-    }) => void): Promise<{
-        phase: string;
-        message?: string;
-        result?: Record<string, unknown>;
-    }>;
-}
-
-/**
- * Common API client for Semiont backend
- *
- * This client can be used by:
- * - MCP server (Node.js)
- * - Demo scripts (Node.js)
- * - Frontend (Next.js/React - can wrap with hooks)
- *
- * Uses ky for HTTP requests with built-in retry, timeout, and error handling.
- */
-
-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;
 declare class APIError extends Error {
     status: number;
     statusText: string;
     details?: unknown | undefined;
     constructor(message: string, status: number, statusText: string, details?: unknown | undefined);
 }
-/**
- * Optional callback invoked when a request fails with HTTP 401. If it
- * resolves to a non-null token, the failed request is retried once with
- * the new Bearer token. If it resolves to null (or throws), the original
- * 401 propagates as an APIError.
- *
- * Implementations must dedupe concurrent calls so that simultaneous 401s
- * don't fire multiple parallel refresh requests. `SemiontSession.refresh()`
- * satisfies this via an in-flight Promise map keyed by KB id.
- */
 type TokenRefresher = () => Promise<string | null>;
-interface SemiontApiClientConfig {
+interface HttpTransportConfig {
     baseUrl: BaseUrl;
-    /**
-     * Observable access token. All auth (HTTP + bus) reads the current value.
-     * Update by calling `.next(newToken)` on the BehaviorSubject. The bus actor
-     * auto-starts when the value transitions from null to a real token.
-     * If omitted, the client operates unauthenticated (public endpoints only).
-     */
+    /** Observable token source; headers read the current value. */
     token$?: BehaviorSubject<AccessToken | null>;
     timeout?: number;
     retry?: number;
@@ -727,1325 +65,109 @@ interface SemiontApiClientConfig {
     /** Optional 401-recovery hook. See {@link TokenRefresher}. */
     tokenRefresher?: TokenRefresher;
 }
-/**
- * Options for individual API requests
- */
-interface RequestOptions {
-    /** Access token for this request */
-    auth?: AccessToken;
-}
-/**
- * Semiont API Client
- *
- * Provides type-safe methods for all Semiont backend API endpoints.
- * This client is fully stateless - authentication must be provided per request.
- */
-declare class SemiontApiClient {
-    private http;
+declare class HttpTransport implements ITransport {
     readonly baseUrl: BaseUrl;
-    /**
-     * Workspace-scoped EventBus — owned by the client, constructed
-     * internally, never accepted from config. Private: all bus access
-     * goes through `client.emit` / `client.on` / `client.stream`.
-     */
-    private readonly eventBus;
-    private logger?;
-    /**
-     * Observable token source. All auth reads from this.
-     */
+    private readonly http;
     private readonly token$;
+    private readonly logger?;
     private _actor;
-    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;
-    readonly admin: AdminNamespace;
-    constructor(config: SemiontApiClientConfig);
     private _actorStarted;
-    get actor(): ActorVM;
+    private disposed;
     private activeResource;
+    /** Buses we've been asked to bridge wire events into. */
+    private readonly bridges;
+    constructor(config: HttpTransportConfig);
+    get actor(): ActorVM;
+    emit<K extends keyof EventMap>(channel: K, payload: EventMap[K], resourceScope?: ResourceId): Promise<void>;
+    on<K extends keyof EventMap>(channel: K, handler: (payload: EventMap[K]) => void): () => void;
+    stream<K extends keyof EventMap>(channel: K): Observable<EventMap[K]>;
     /**
-     * Subscribe the bus actor to the resource-scoped SSE stream for a single
-     * resource and bridge incoming scoped events into the workspace event bus.
-     *
-     * **One distinct scope at a time**: the client supports subscriptions
-     * to a single resource scope concurrently. Multiple calls with the
-     * **same** resourceId are ref-counted — each returns an independent
-     * unsubscribe; the underlying SSE scope is torn down only when the
-     * last unsubscribe fires. Calling with a **different** resourceId
-     * while a subscription is live throws. Widening this to multiple
-     * concurrent scopes is deferred until a product requirement (e.g.
-     * split-pane viewer, headless fleet-watcher) forces the design.
-     *
-     * @returns a disposer that decrements the ref count (and tears down
-     *          the SSE scope + bridges when it reaches zero).
+     * Wire this transport's SSE fan-in into the given bus. Every channel
+     * in `BRIDGED_CHANNELS` (and subsequently per-resource scoped channels
+     * opened by `subscribeToResource`) is published on the bus. Safe to
+     * call multiple times — each bus is added to the fan-out list.
      */
+    bridgeInto(bus: EventBus): void;
     subscribeToResource(resourceId: ResourceId): () => void;
     private makeUnsubscriber;
+    get state$(): Observable<ConnectionState>;
     dispose(): void;
-    /** Emit an event on the internal bus. */
-    emit<K extends keyof EventMap>(channel: K, payload: EventMap[K]): void;
-    /** Subscribe to an event on the internal bus; returns unsubscribe. */
-    on<K extends keyof EventMap>(channel: K, handler: (payload: EventMap[K]) => void): () => void;
-    /** Read-only observable for a bus channel. Consumers `.pipe(...)` over this. */
-    stream<K extends keyof EventMap>(channel: K): Observable<EventMap[K]>;
-    /**
-     * Build the `Authorization: Bearer <token>` header. If the caller passed
-     * an explicit `{ auth }` it wins (used by session-internal throwaway
-     * clients that need to run a validation request with a specific token).
-     * Otherwise the current value of `this.token$` is used, so external
-     * callers never have to plumb the token themselves.
-     */
     private authHeaders;
-    authenticatePassword(email: Email, password: string, options?: RequestOptions): Promise<ResponseContent<paths['/api/tokens/password']['post']>>;
-    refreshToken(token: RefreshToken, options?: RequestOptions): Promise<ResponseContent<paths['/api/tokens/refresh']['post']>>;
-    authenticateGoogle(credential: GoogleCredential, options?: RequestOptions): Promise<ResponseContent<paths['/api/tokens/google']['post']>>;
-    generateMCPToken(options?: RequestOptions): Promise<ResponseContent<paths['/api/tokens/mcp-generate']['post']>>;
-    getMediaToken(resourceId: ResourceId, options?: RequestOptions): Promise<{
+    authenticatePassword(email: Email, password: string): Promise<AuthResponse>;
+    authenticateGoogle(credential: GoogleCredential): Promise<AuthResponse>;
+    refreshAccessToken(token: RefreshToken): Promise<TokenRefreshResponse>;
+    logout(): Promise<void>;
+    acceptTerms(): Promise<void>;
+    getCurrentUser(): Promise<UserResponse>;
+    generateMcpToken(): Promise<{
         token: string;
     }>;
-    getMe(options?: RequestOptions): Promise<ResponseContent<paths['/api/users/me']['get']>>;
-    acceptTerms(options?: RequestOptions): Promise<ResponseContent<paths['/api/users/accept-terms']['post']>>;
-    logout(options?: RequestOptions): Promise<ResponseContent<paths['/api/users/logout']['post']>>;
-    /**
-     * Create a new resource with binary content support
-     *
-     * @param data - Resource creation data
-     * @param data.name - Resource name
-     * @param data.file - File object or Buffer with binary content
-     * @param data.format - MIME type (e.g., 'text/markdown', 'image/png')
-     * @param data.entityTypes - Optional array of entity types
-     * @param data.language - Optional ISO 639-1 language code
-     * @param data.creationMethod - Optional creation method
-     * @param data.sourceAnnotationId - Optional source annotation ID
-     * @param data.sourceResourceId - Optional source resource ID
-     * @param data.generationPrompt - Optional prompt that drove AI generation
-     * @param data.generator - Optional Agent(s) that generated the content
-     * @param options - Request options including auth
-     */
-    yieldResource(data: {
-        name: string;
-        file: File | Buffer;
-        format: string;
-        entityTypes?: string[];
-        language?: string;
-        creationMethod?: string;
-        sourceAnnotationId?: string;
-        sourceResourceId?: string;
-        storageUri: string;
-        generationPrompt?: string;
-        generator?: components['schemas']['Agent'] | components['schemas']['Agent'][];
-        isDraft?: boolean;
-    }, options?: RequestOptions): Promise<ResponseContent<paths['/resources']['post']>>;
-    browseResource(id: ResourceId, _options?: RequestOptions): Promise<components['schemas']['GetResourceResponse']>;
-    /**
-     * Get resource representation using W3C content negotiation
-     * Returns raw binary content (images, PDFs, text, etc.) with content type
-     *
-     * @param resourceUri - Full resource URI
-     * @param options - Options including Accept header for content negotiation and auth
-     * @returns Object with data (ArrayBuffer) and contentType (string)
-     *
-     * @example
-     * ```typescript
-     * // Get markdown representation
-     * const { data, contentType } = await client.getResourceRepresentation(rUri, { accept: 'text/markdown', auth: token });
-     * const markdown = new TextDecoder().decode(data);
-     *
-     * // Get image representation
-     * const { data, contentType } = await client.getResourceRepresentation(rUri, { accept: 'image/png', auth: token });
-     * const blob = new Blob([data], { type: contentType });
-     *
-     * // Get PDF representation
-     * const { data, contentType } = await client.getResourceRepresentation(rUri, { accept: 'application/pdf', auth: token });
-     * ```
-     */
-    getResourceRepresentation(id: ResourceId, options?: {
-        accept?: ContentFormat;
-        auth?: AccessToken;
-    }): Promise<{
-        data: ArrayBuffer;
-        contentType: string;
-    }>;
-    /**
-     * Get resource representation as a stream using W3C content negotiation
-     * Returns streaming binary content (for large files: videos, large PDFs, etc.)
-     *
-     * Use this for large files to avoid loading entire content into memory.
-     * The stream is consumed incrementally and the backend connection stays open
-     * until the stream is fully consumed or closed.
-     *
-     * @param resourceUri - Full resource URI
-     * @param options - Options including Accept header for content negotiation and auth
-     * @returns Object with stream (ReadableStream) and contentType (string)
-     *
-     * @example
-     * ```typescript
-     * // Stream large file
-     * const { stream, contentType } = await client.getResourceRepresentationStream(rUri, {
-     *   accept: 'video/mp4',
-     *   auth: token
-     * });
-     *
-     * // Consume stream chunk by chunk (never loads entire file into memory)
-     * for await (const chunk of stream) {
-     *   // Process chunk
-     *   console.log(`Received ${chunk.length} bytes`);
-     * }
-     *
-     * // Or pipe to a file in Node.js
-     * const fileStream = fs.createWriteStream('output.mp4');
-     * const reader = stream.getReader();
-     * while (true) {
-     *   const { done, value } = await reader.read();
-     *   if (done) break;
-     *   fileStream.write(value);
-     * }
-     * ```
-     */
-    getResourceRepresentationStream(id: ResourceId, options?: {
-        accept?: ContentFormat;
-        auth?: AccessToken;
-    }): Promise<{
-        stream: ReadableStream<Uint8Array>;
-        contentType: string;
-    }>;
-    browseResources(limit?: number, archived?: boolean, query?: SearchQuery, _options?: RequestOptions): Promise<components['schemas']['ListResourcesResponse']>;
-    updateResource(id: ResourceId, data: {
-        archived?: boolean;
-        entityTypes?: string[];
-    }, options?: RequestOptions): Promise<void>;
-    getResourceEvents(id: ResourceId, _options?: RequestOptions): Promise<components['schemas']['GetEventsResponse']>;
-    browseReferences(id: ResourceId, _options?: RequestOptions): Promise<components['schemas']['GetReferencedByResponse']>;
-    generateCloneToken(id: ResourceId, _options?: RequestOptions): Promise<components['schemas']['CloneResourceWithTokenResponse']>;
-    getResourceByToken(token: CloneToken, _options?: RequestOptions): Promise<components['schemas']['GetResourceByTokenResponse']>;
-    createResourceFromToken(data: {
+    getMediaToken(resourceId: ResourceId): Promise<{
         token: string;
-        name: string;
-        content: string;
-        archiveOriginal?: boolean;
-    }, _options?: RequestOptions): Promise<{
-        resourceId: string;
-    }>;
-    markAnnotation(id: ResourceId, data: components['schemas']['CreateAnnotationRequest'], _options?: RequestOptions): Promise<{
-        annotationId: string;
-    }>;
-    getAnnotation(id: AnnotationId, _options?: RequestOptions): Promise<components['schemas']['GetAnnotationResponse']>;
-    browseAnnotation(resourceId: ResourceId, annotationId: AnnotationId, _options?: RequestOptions): Promise<components['schemas']['GetAnnotationResponse']>;
-    browseAnnotations(id: ResourceId, _motivation?: Motivation, _options?: RequestOptions): Promise<components['schemas']['GetAnnotationsResponse']>;
-    deleteAnnotation(resourceId: ResourceId, annotationId: AnnotationId, _options?: RequestOptions): Promise<void>;
-    bindAnnotation(resourceId: ResourceId, annotationId: AnnotationId, data: {
-        operations: BodyOperation[];
-    }, _options?: RequestOptions): Promise<{
-        correlationId: string;
-    }>;
-    getAnnotationHistory(resourceId: ResourceId, annotationId: AnnotationId, _options?: RequestOptions): Promise<components['schemas']['GetAnnotationHistoryResponse']>;
-    annotateReferences(resourceId: ResourceId, data: {
-        entityTypes: string[];
-        includeDescriptiveReferences?: boolean;
-    }, _options?: RequestOptions): Promise<{
-        correlationId: string;
-        jobId: string;
     }>;
-    annotateHighlights(resourceId: ResourceId, data: {
-        instructions?: string;
-        density?: number;
-    }, _options?: RequestOptions): Promise<{
-        correlationId: string;
-        jobId: string;
-    }>;
-    annotateAssessments(resourceId: ResourceId, data: {
-        instructions?: string;
-        tone?: string;
-        density?: number;
-        language?: string;
-    }, _options?: RequestOptions): Promise<{
-        correlationId: string;
-        jobId: string;
-    }>;
-    annotateComments(resourceId: ResourceId, data: {
-        instructions?: string;
-        tone?: string;
-        density?: number;
-        language?: string;
-    }, _options?: RequestOptions): Promise<{
-        correlationId: string;
-        jobId: string;
-    }>;
-    annotateTags(resourceId: ResourceId, data: {
-        schemaId: string;
-        categories: string[];
-    }, _options?: RequestOptions): Promise<{
-        correlationId: string;
-        jobId: string;
-    }>;
-    yieldResourceFromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, data: {
-        title: string;
-        storageUri: string;
-        context: unknown;
-        prompt?: string;
-        language?: string;
-        temperature?: number;
-        maxTokens?: number;
-    }, _options?: RequestOptions): Promise<{
-        correlationId: string;
-        jobId: string;
-    }>;
-    gatherAnnotationContext(resourceId: ResourceId, annotationId: AnnotationId, data: {
-        correlationId: string;
-        contextWindow?: number;
-    }, _options?: RequestOptions): Promise<{
-        correlationId: string;
-    }>;
-    matchSearch(resourceId: ResourceId, data: {
-        correlationId: string;
-        referenceId: string;
-        context: unknown;
-        limit?: number;
-        useSemanticScoring?: boolean;
-    }, _options?: RequestOptions): Promise<{
-        correlationId: string;
-    }>;
-    addEntityType(type: EntityType, _options?: RequestOptions): Promise<void>;
-    addEntityTypesBulk(types: EntityType[], _options?: RequestOptions): Promise<void>;
-    listEntityTypes(_options?: RequestOptions): Promise<components['schemas']['GetEntityTypesResponse']>;
-    beckonAttention(_participantId: string, data: {
-        annotationId?: string;
-        resourceId: string;
-        message?: string;
-    }, _options?: RequestOptions): Promise<components['schemas']['BeckonResponse']>;
-    listUsers(options?: RequestOptions): Promise<ResponseContent<paths['/api/admin/users']['get']>>;
-    getUserStats(options?: RequestOptions): Promise<ResponseContent<paths['/api/admin/users/stats']['get']>>;
-    /**
-     * Update a user by ID
-     * Note: Users use DID identifiers (did:web:domain:users:id), not HTTP URIs.
-     */
-    updateUser(id: UserDID, data: RequestContent<paths['/api/admin/users/{id}']['patch']>, options?: RequestOptions): Promise<ResponseContent<paths['/api/admin/users/{id}']['patch']>>;
-    getOAuthConfig(options?: RequestOptions): Promise<ResponseContent<paths['/api/admin/oauth/config']['get']>>;
-    /**
-     * Create a backup of the knowledge base. Returns raw Response for streaming download.
-     * Caller should use response.blob() to trigger a file download.
-     */
-    backupKnowledgeBase(options?: RequestOptions): Promise<Response>;
-    /**
-     * Restore knowledge base from a backup file. Parses SSE progress events and calls onProgress.
-     * Returns the final SSE event (phase: 'complete' or 'error').
-     */
-    restoreKnowledgeBase(file: File, options?: RequestOptions & {
-        onProgress?: (event: {
-            phase: string;
-            message?: string;
-            result?: Record<string, unknown>;
-        }) => void;
-    }): Promise<{
-        phase: string;
-        message?: string;
-        result?: Record<string, unknown>;
-    }>;
-    /**
-     * Export the knowledge base as a JSON-LD Linked Data archive. Returns raw Response for streaming download.
-     * Caller should use response.blob() to trigger a file download.
-     */
+    listUsers(): Promise<ListUsersResponse>;
+    getUserStats(): Promise<AdminUserStatsResponse>;
+    updateUser(id: UserDID, data: UpdateUserRequest): Promise<UpdateUserResponse>;
+    getOAuthConfig(): Promise<OAuthConfigResponse>;
+    backupKnowledgeBase(): Promise<Response>;
+    restoreKnowledgeBase(file: File, onProgress?: ProgressCallback): Promise<ProgressEvent>;
     exportKnowledgeBase(params?: {
         includeArchived?: boolean;
-    }, options?: RequestOptions): Promise<Response>;
-    /**
-     * Import a JSON-LD Linked Data archive into the knowledge base. Parses SSE progress events and calls onProgress.
-     * Returns the final SSE event (phase: 'complete' or 'error').
-     */
-    importKnowledgeBase(file: File, options?: RequestOptions & {
-        onProgress?: (event: {
-            phase: string;
-            message?: string;
-            result?: Record<string, unknown>;
-        }) => void;
-    }): Promise<{
-        phase: string;
-        message?: string;
-        result?: Record<string, unknown>;
-    }>;
+    }): Promise<Response>;
+    importKnowledgeBase(file: File, onProgress?: ProgressCallback): Promise<ProgressEvent>;
     private parseSSEStream;
-    getJobStatus(id: JobId, _options?: RequestOptions): Promise<components['schemas']['JobStatusResponse']>;
-    /**
-     * Poll a job until it completes or fails
-     * @param id - The job ID to poll
-     * @param options - Polling options
-     * @returns The final job status
-     */
-    pollJobUntilComplete(id: JobId, options?: {
-        interval?: number;
-        timeout?: number;
-        onProgress?: (status: components['schemas']['JobStatusResponse']) => void;
-        auth?: AccessToken;
-    }): Promise<components['schemas']['JobStatusResponse']>;
-    healthCheck(options?: RequestOptions): Promise<ResponseContent<paths['/api/health']['get']>>;
-    getStatus(options?: RequestOptions): Promise<ResponseContent<paths['/api/status']['get']>>;
-    browseFiles(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount', _options?: RequestOptions): Promise<components['schemas']['BrowseFilesResponse']>;
-}
-
-declare class BusRequestError extends Error {
-    constructor(message: string);
-}
-declare function busRequest<TResult>(actor: ActorVM, emitChannel: string, payload: Record<string, unknown>, resultChannel: string, failureChannel: string, timeoutMs?: number): Promise<TResult>;
-
-/**
- * RxJS-native read-through cache primitive.
- *
- * Behavioral contract: packages/api-client/docs/CACHE-SEMANTICS.md (B1–B13).
- *
- * Framework-agnostic: no React, no dependency on any namespace. Used by
- * `BrowseNamespace` to back its per-key stores, but equally usable from
- * CLI, MCP, or worker code.
- *
- * Shape:
- *   - `observe(key)`: returns an Observable<V | undefined> that triggers
- *     a fetch on first subscription for a missing key, dedup-joins any
- *     concurrent fetch, and emits the stored value thereafter.
- *   - `invalidate(key)`: stale-while-revalidate — keeps the current
- *     value visible to observers, clears the in-flight guard, starts a
- *     fresh fetch. If the previous fetch was orphaned (SSE torn down,
- *     response lost), this is how the cache recovers.
- *   - `remove(key)`: drops the cache entry entirely. Used for entity
- *     deletions (B13a). No refetch.
- *   - `set(key, value)`: writes through without a fetch. Used when a
- *     bus event carries the new value inline (B13b).
- *   - `invalidateAll()`: per-key SWR refetch of every currently-cached
- *     entry. Used by gap-detection paths.
- *   - `dispose()`: completes the store so observers unsubscribe.
- *
- * What's deliberately out:
- *   - No subscriber ref-counting / GC of unobserved keys. The per-key
- *     observable memo grows with the set of observed keys for the cache's
- *     lifetime (B11). Acceptable given cache lifetime == client lifetime.
- *   - No TTL / cacheTime. Entries are evicted only by explicit remove.
- *   - No retry / backoff. A failing fetch leaves the cache unchanged
- *     (B6); the caller drives retry via invalidate.
- */
-
-interface Cache<K, V> {
-    /** Observable stream of the value at `key`. Triggers a fetch if not cached. */
-    observe(key: K): Observable<V | undefined>;
-    /** Synchronous snapshot of the current value, without triggering a fetch. */
-    get(key: K): V | undefined;
-    /** Iterator of currently-cached keys. For invalidateAll and diagnostics. */
-    keys(): K[];
-    /**
-     * Mark the entry stale and refetch. Keeps the previous value visible
-     * to observers during the refetch (stale-while-revalidate).
-     */
-    invalidate(key: K): void;
-    /** Drop the entry from the cache. No refetch. */
-    remove(key: K): void;
-    /** Write-through: set the value directly without a fetch. */
-    set(key: K, value: V): void;
-    /** Per-key SWR refetch of every currently-cached entry. */
-    invalidateAll(): void;
-    /** Release the underlying subject. Observers complete. */
-    dispose(): void;
-}
-declare function createCache<K, V>(fetchFn: (key: K) => Promise<V>): Cache<K, V>;
-
-/**
- * KnowledgeBase — a connection to a Semiont backend instance.
- *
- * Each KB has its own JWT, its own API base URL, and its own session.
- * The user is "authenticated against KB X" — never globally authenticated.
- */
-interface KnowledgeBase {
-    id: string;
-    label: string;
-    host: string;
-    port: number;
-    protocol: 'http' | 'https';
-    email: string;
-    gitBranch?: 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';
-
-/**
- * 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.
- */
-type SemiontErrorCode = 'session.construct-failed' | 'session.auth-failed' | 'session.refresh-exhausted' | 'browser.sign-in-failed';
-declare class SemiontError extends Error {
-    readonly code: SemiontErrorCode;
-    readonly kbId: string | null;
-    constructor(code: SemiontErrorCode, 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
- * SemiontApiClient, 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 `FrontendSessionSignals`, 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). The
- *     frontend wires this to `FrontendSessionSignals.notifySessionExpired`
- *     so the 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;
-    /**
-     * Re-authenticate after expiry / 401. Returns a new access token
-     * (no "Bearer " prefix) on success, or null if recovery is
-     * impossible (user needs to sign in again, or the service secret
-     * is missing). Callers must dedupe concurrent invocations if the
-     * underlying auth call isn't itself idempotent.
-     */
-    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: SemiontError) => void;
-}
-declare class SemiontSession {
-    readonly kb: KnowledgeBase;
-    readonly client: SemiontApiClient;
-    readonly token$: BehaviorSubject<AccessToken | null>;
-    readonly user$: BehaviorSubject<UserInfo | null>;
-    readonly streamState$: Observable<ConnectionState>;
-    /** 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;
+    healthCheck(): Promise<HealthCheckResponse>;
+    getStatus(): Promise<StatusResponse>;
     /**
-     * Cross-context sync: another tab/process refreshed or signed out this
-     * KB. Mirror the change into our in-memory state.
+     * Temporary escape hatch for the ongoing transport migration: namespaces
+     * that still need to issue ad-hoc HTTP calls (e.g. legacy browse/mark
+     * HTTP fallbacks) can borrow the configured `ky` instance here. Will be
+     * deleted once all namespaces route through bus channels or through
+     * typed methods on this transport.
      */
-    private handleStorageChange;
-    get expiresAt(): Date | null;
-    dispose(): Promise<void>;
-}
-
-/**
- * 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;
-}
-
-/**
- * FrontendSessionSignals — modal state that belongs to the UI, not
- * 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 *modals* only make sense
- * in a UI context. Keeping those observables on `SemiontSession`
- * meant workers and CLIs carried four dead BehaviorSubjects that
- * nothing would ever fire.
- *
- * `FrontendSessionSignals` owns the modal state and has no hard
- * reference to a session. `SemiontBrowser` constructs one alongside
- * every frontend session and wires:
- *
- *   - `session.onAuthFailed` → `signals.notifySessionExpired` so
- *     proactive-refresh failures surface as modals
- *   - `notify` module handlers → the active signals' methods so
- *     external callers (e.g. React Query's QueryCache.onError) can
- *     trigger the modals without touching the session
- *
- * React consumers that need modal 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 modal.
- */
-
-declare class FrontendSessionSignals {
-    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;
-}
-
-/**
- * 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. Module-scoped singleton — survives every
- * React re-render, remount, and route change. `SemiontProvider` hands
- * the singleton to the React tree; `useSemiont()` returns it.
- *
- * 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;
-}
-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 [FrontendSessionSignals](./frontend-session-signals.ts).
-     */
-    readonly activeSignals$: BehaviorSubject<FrontendSessionSignals | 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<SemiontError>;
-    readonly identityToken$: BehaviorSubject<string | null>;
-    private readonly storage;
-    /**
-     * 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 `SemiontApiClient`, which carries KB-content events
-     * (mark:*, beckon:*, gather:*, match:*, bind:*, yield:*, browse:click).
-     */
-    private readonly eventBus;
-    private unregisterNotify;
-    private unsubscribeStorage;
-    private disposed;
-    private activating;
-    /**
-     * Per-KB in-flight refresh dedup. Simultaneous 401s for the same
-     * KB converge on a single `/api/tokens/refresh` network call.
-     * Was previously module-scoped in `refresh.ts`; moved here when
-     * that file was deleted — SemiontBrowser is a singleton so the
-     * scoping is equivalent.
-     */
-    private readonly inFlightRefreshes;
-    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 (from NextAuth's useSession).
-     * Called at the root layout via a single `useEffect`. No other site
-     * in the codebase should call this.
-     */
-    setIdentityToken(token: string | null): void;
-    addKb(input: NewKnowledgeBase, access: string, refresh: string): KnowledgeBase;
-    removeKb(id: string): void;
-    updateKb(id: string, updates: Partial<KnowledgeBase>): void;
+    get rawHttp(): KyInstance;
     /**
-     * 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.
+     * Current access token (synchronously read from the BehaviorSubject).
+     * Used by content-transport and legacy namespace HTTP fallbacks that
+     * need to pass `auth: token` through some code paths.
      */
-    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;
-    /**
-     * Refresh the active KB's access token. Returns the new token on
-     * success, null on failure. Concurrent calls for the same KB
-     * dedupe through `inFlightRefreshes`, so simultaneous 401s trigger
-     * only one `/api/tokens/refresh` round trip.
-     *
-     * Uses a throwaway `SemiontApiClient` with no `tokenRefresher` —
-     * a refresh call returning 401 would otherwise re-enter this
-     * function infinitely.
-     */
-    private performRefresh;
-    /**
-     * Validate an access token by calling `getMe` on a throwaway
-     * client. The session uses this once at startup to populate
-     * `user$`; 401 triggers a refresh-then-retry inside the session.
-     */
-    private performValidate;
-    dispose(): Promise<void>;
-}
-
-/**
- * Module-scoped singleton for SemiontBrowser. Constructed lazily on first
- * `getBrowser()` call, survives every React re-render, remount, and route
- * change.
- *
- * The caller provides a `SessionStorage` implementation — there is no
- * default here because storage-backend selection is environment-specific
- * (browsers use `WebBrowserStorage`, CLI uses a filesystem adapter,
- * tests use `InMemorySessionStorage`). The first call to `getBrowser`
- * wins; subsequent calls return the cached instance regardless of the
- * storage passed.
- */
-
-interface GetBrowserOptions {
-    /** Persistence adapter used to construct the singleton on first call. */
-    storage: SessionStorage;
+    getToken(): AccessToken | undefined;
 }
-declare function getBrowser(options: GetBrowserOptions): SemiontBrowser;
 
 /**
- * Pure helpers and storage-adapter-driven loaders for the Semiont
- * session layer.
+ * HttpContentTransport — binary I/O over HTTP.
  *
- * 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.
+ * Phase 1 of TRANSPORT-ABSTRACTION. Narrow by design because binary has
+ * different backpressure and streaming characteristics than typed command
+ * payloads. Uses the HttpTransport's underlying ky instance + token, so
+ * retries, logging, and auth behave identically to the rest of the wire.
  */
 
-/** 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;
-declare function kbBackendUrl(kb: KnowledgeBase): string;
-
-declare function notifySessionExpired(message?: string): void;
-declare function notifyPermissionDenied(message?: string): 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 component instance via React's
- * `useState(() => createSearchPipeline(...))` lazy initializer, then consumed
- * via `useObservable(pipeline.state$)`. The pipeline holds no React state and
- * has no React imports — it's pure RxJS, unit-testable without a renderer.
- *
- * 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 via `useObservable`. */
-    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 `useEffect` cleanup. */
-    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>;
-
-interface BeckonVM extends ViewModel {
-    hoveredAnnotationId$: Observable<string | null>;
-    hover(annotationId: string | null): void;
-    focus(annotationId: string): void;
-    sparkle(annotationId: string): void;
-}
-declare function createBeckonVM(client: SemiontApiClient): BeckonVM;
-/** Default milliseconds the mouse must dwell before beckon:hover is emitted. */
-declare const HOVER_DELAY_MS = 150;
-type EmitHover = (annotationId: string | null) => void;
-interface HoverHandlers {
-    handleMouseEnter: (annotationId: string) => void;
-    handleMouseLeave: () => void;
-    cleanup: () => void;
-}
-declare function createHoverHandlers(emit: EmitHover, delayMs: number): HoverHandlers;
-
-/**
- * ShellVM — app-shell state: which toolbar panel is open, tab-bar
- * coordination helpers, scroll-to-annotation signals. Lives on
- * `SemiontBrowser`'s app-scoped bus (not the per-session client bus)
- * because panel toggles and shell chrome must work regardless of
- * whether a KB session is active.
- *
- * Channels: `panel:toggle`, `panel:open`, `panel:close`.
- */
-
-type ToolbarPanelType = 'history' | 'info' | 'annotations' | 'settings' | 'collaboration' | 'user' | 'jsonld' | 'knowledge-base';
-declare const COMMON_PANELS: readonly ToolbarPanelType[];
-declare const RESOURCE_PANELS: readonly ToolbarPanelType[];
-interface ShellVM extends ViewModel {
-    activePanel$: Observable<ToolbarPanelType | null>;
-    scrollToAnnotationId$: Observable<string | null>;
-    panelInitialTab$: Observable<{
-        tab: string;
-        generation: number;
-    } | null>;
-    openPanel(panel: string): void;
-    closePanel(): void;
-    togglePanel(panel: string): void;
-    onScrollCompleted(): void;
-}
-interface ShellVMOptions {
-    initialPanel?: ToolbarPanelType | null;
-    onPanelChange?: (panel: ToolbarPanelType | null) => void;
-}
-declare function createShellVM(browser: SemiontBrowser, options?: ShellVMOptions): ShellVM;
-
-interface GatherVM extends ViewModel {
-    context$: Observable<GatheredContext | null>;
-    loading$: Observable<boolean>;
-    error$: Observable<Error | null>;
-    annotationId$: Observable<AnnotationId | null>;
-}
-declare function createGatherVM(client: SemiontApiClient, resourceId: ResourceId): GatherVM;
-
-interface MatchVM extends ViewModel {
-}
-declare function createMatchVM(client: SemiontApiClient, _resourceId: ResourceId): MatchVM;
-
-type JobProgress$1 = components['schemas']['JobProgress'];
-interface GenerateDocumentOptions {
-    title: string;
-    storageUri: string;
-    prompt?: string;
-    language?: string;
-    temperature?: number;
-    maxTokens?: number;
-    context: GatheredContext;
-}
-interface YieldVM extends ViewModel {
-    isGenerating$: Observable<boolean>;
-    progress$: Observable<JobProgress$1 | null>;
-    generate(referenceId: string, options: GenerateDocumentOptions): void;
-}
-declare function createYieldVM(client: SemiontApiClient, resourceId: ResourceId, locale: string): YieldVM;
-
-type JobProgress = components['schemas']['JobProgress'];
-interface PendingAnnotation {
-    selector: Selector | Selector[];
-    motivation: Motivation;
-}
-interface MarkVM extends ViewModel {
-    pendingAnnotation$: Observable<PendingAnnotation | null>;
-    assistingMotivation$: Observable<Motivation | null>;
-    progress$: Observable<JobProgress | null>;
-}
-declare function createMarkVM(client: SemiontApiClient, resourceId: ResourceId): MarkVM;
-
-type ResourceDescriptor$2 = components['schemas']['ResourceDescriptor'];
-interface DiscoverVM extends ViewModel {
-    browse: ShellVM;
-    search: SearchPipeline<ResourceDescriptor$2>;
-    recentResources$: Observable<ResourceDescriptor$2[]>;
-    entityTypes$: Observable<string[]>;
-    isLoadingRecent$: Observable<boolean>;
-}
-declare function createDiscoverVM(client: SemiontApiClient, browse: ShellVM): DiscoverVM;
-
-interface EntityTagsVM extends ViewModel {
-    browse: ShellVM;
-    entityTypes$: Observable<string[]>;
-    isLoading$: Observable<boolean>;
-    newTag$: Observable<string>;
-    error$: Observable<string>;
-    isAdding$: Observable<boolean>;
-    setNewTag(value: string): void;
-    addTag(): Promise<void>;
-}
-declare function createEntityTagsVM(client: SemiontApiClient, browse: ShellVM): EntityTagsVM;
-
-interface ImportPreview {
-    format: string;
-    version: number;
-    sourceUrl: string;
-    stats: Record<string, number>;
-}
-interface ExchangeVM extends ViewModel {
-    browse: ShellVM;
-    selectedFile$: Observable<File | null>;
-    preview$: Observable<ImportPreview | null>;
-    importPhase$: Observable<string | null>;
-    importMessage$: Observable<string | undefined>;
-    importResult$: Observable<Record<string, unknown> | undefined>;
-    isExporting$: Observable<boolean>;
-    isImporting$: Observable<boolean>;
-    selectFile(file: File): void;
-    cancelImport(): void;
-    doExport(): Promise<{
-        blob: Blob;
-        filename: string;
+declare class HttpContentTransport implements IContentTransport {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    putBinary(request: PutBinaryRequest, options?: {
+        auth?: AccessToken;
+    }): Promise<{
+        resourceId: ResourceId;
     }>;
-    doImport(): Promise<void>;
-}
-declare function createExchangeVM(browse: ShellVM, exportFn: (params?: {
-    includeArchived?: boolean;
-}) => Promise<Response>, importFn: (file: File, options?: {
-    onProgress?: (event: {
-        phase: string;
-        message?: string;
-        result?: Record<string, unknown>;
-    }) => void;
-}) => Promise<{
-    phase: string;
-    message?: string;
-    result?: Record<string, unknown>;
-}>): ExchangeVM;
-
-interface AdminUsersVM extends ViewModel {
-    browse: ShellVM;
-    users$: Observable<unknown[]>;
-    stats$: Observable<unknown | null>;
-    usersLoading$: Observable<boolean>;
-    statsLoading$: Observable<boolean>;
-    updateUser(id: string, data: {
-        isAdmin?: boolean;
-        isActive?: boolean;
-    }): Promise<void>;
-}
-declare function createAdminUsersVM(client: SemiontApiClient, browse: ShellVM): AdminUsersVM;
-
-interface AdminSecurityVM extends ViewModel {
-    browse: ShellVM;
-    providers$: Observable<unknown[]>;
-    allowedDomains$: Observable<string[]>;
-    isLoading$: Observable<boolean>;
-}
-declare function createAdminSecurityVM(client: SemiontApiClient, browse: ShellVM): AdminSecurityVM;
-
-interface WelcomeVM extends ViewModel {
-    userData$: Observable<{
-        termsAcceptedAt?: string;
-    } | null>;
-    isProcessing$: Observable<boolean>;
-    acceptTerms(): Promise<void>;
-}
-declare function createWelcomeVM(client: SemiontApiClient): WelcomeVM;
-
-type ResourceDescriptor$1 = components['schemas']['ResourceDescriptor'];
-interface ResourceLoaderVM extends ViewModel {
-    resource$: Observable<ResourceDescriptor$1 | undefined>;
-    isLoading$: Observable<boolean>;
-    invalidate(): void;
-}
-declare function createResourceLoaderVM(client: SemiontApiClient, resourceId: ResourceId): ResourceLoaderVM;
-
-interface SessionVM extends ViewModel {
-    isLoggingOut$: Observable<boolean>;
-    logout(): Promise<void>;
-}
-declare function createSessionVM(client: SemiontApiClient): SessionVM;
-
-interface SmelterEvent {
-    type: string;
-    resourceId?: string;
-    payload: Record<string, unknown>;
-}
-interface SmelterActorVMOptions {
-    baseUrl: string;
-    token: string;
-    reconnectMs?: number;
-}
-interface SmelterActorVM extends ViewModel {
-    events$: Observable<SmelterEvent>;
-    state$: Observable<ConnectionState>;
-    emit(channel: string, payload: Record<string, unknown>): Promise<void>;
-    start(): void;
-    stop(): void;
-}
-declare function createSmelterActorVM(options: SmelterActorVMOptions): SmelterActorVM;
-
-/**
- * Job Claim Adapter — worker-side job lifecycle glue on top of a
- * shared `ActorVM`.
- *
- * Replaces the old `WorkerVM`, which owned its own actor and
- * duplicated the SSE connection that `SemiontApiClient` already held.
- * Workers now construct a `SemiontSession` normally (one actor, one
- * SSE connection) and use this adapter to attach job-claim behaviour
- * on top of `session.client.actor`.
- *
- * The adapter is intentionally thin: it subscribes to `job:queued`
- * on the actor, claims jobs via the existing request-response
- * protocol (`job:claim` → `job:claimed` / `job:claim-failed`), and
- * exposes observables for job orchestration. It does **not** own
- * the actor, has no HTTP concerns, and has no modal state.
- */
-
-interface JobAssignment {
-    jobId: string;
-    type: string;
-    resourceId: string;
-}
-interface ActiveJob {
-    jobId: string;
-    type: string;
-    resourceId: string;
-    userId: string;
-    params: Record<string, unknown>;
-}
-interface JobClaimAdapterOptions {
-    /** Shared actor (typically `session.client.actor`). */
-    actor: ActorVM;
-    /**
-     * Job types this worker can process. Jobs of other types that
-     * arrive on `job:queued` are ignored. Empty array = accept any.
-     */
-    jobTypes: string[];
-}
-interface JobClaimAdapter {
-    /** Currently-claimed job, or null when idle. */
-    readonly activeJob$: Observable<ActiveJob | null>;
-    /** True while a claim is in flight or a job is being processed. */
-    readonly isProcessing$: Observable<boolean>;
-    /** Monotonically-incrementing count of successfully-completed jobs. */
-    readonly jobsCompleted$: Observable<number>;
-    /** Stream of job failures (including claim-failed and processing errors). */
-    readonly errors$: Observable<{
-        jobId: string;
-        error: string;
+    getBinary(resourceId: ResourceId, options?: {
+        accept?: ContentFormat | string;
+        auth?: AccessToken;
+    }): Promise<{
+        data: ArrayBuffer;
+        contentType: string;
+    }>;
+    getBinaryStream(resourceId: ResourceId, options?: {
+        accept?: ContentFormat | string;
+        auth?: AccessToken;
+    }): Promise<{
+        stream: ReadableStream<Uint8Array>;
+        contentType: string;
     }>;
-    /**
-     * Subscribe to `job:queued` events (adding the channel to the actor
-     * if not already subscribed) and begin claiming matching jobs.
-     * Idempotent — calling `start()` twice is a no-op.
-     */
-    start(): void;
-    /** Stop claiming new jobs. Does not cancel an in-flight job. */
-    stop(): void;
-    /** Signal successful completion of `activeJob$`. */
-    completeJob(): void;
-    /** Signal failure of `activeJob$`. Emits on `errors$`. */
-    failJob(jobId: string, error: string): void;
-    /** Release observables. Does not dispose the shared actor. */
     dispose(): void;
+    /** Auth header + W3C trace propagation for the active span. */
+    private requestHeaders;
 }
-/**
- * Attach job-claim behaviour to a shared `ActorVM`.
- */
-declare function createJobClaimAdapter(options: JobClaimAdapterOptions): JobClaimAdapter;
-
-interface Job {
-    jobId: string;
-    type: string;
-    status: string;
-    resourceId: string;
-    userId: string;
-    created: string;
-    startedAt?: string;
-    completedAt?: string;
-    error?: string;
-    progress?: Record<string, unknown>;
-    result?: Record<string, unknown>;
-}
-interface JobQueueVM extends ViewModel {
-    jobs$: Observable<Job[]>;
-    pendingByType$: Observable<Map<string, number>>;
-    runningJobs$: Observable<Job[]>;
-    jobCreated$: Observable<Job>;
-    jobCompleted$: Observable<Job>;
-    jobFailed$: Observable<Job>;
-}
-declare function createJobQueueVM(client: SemiontApiClient): JobQueueVM;
-
-type Annotation = components['schemas']['Annotation'];
-interface AnnotationGroups {
-    highlights: Annotation[];
-    comments: Annotation[];
-    assessments: Annotation[];
-    references: Annotation[];
-    tags: Annotation[];
-}
-type StoredEventResponse = components['schemas']['StoredEventResponse'];
-interface WizardState {
-    open: boolean;
-    annotationId: string | null;
-    resourceId: string | null;
-    defaultTitle: string;
-    entityTypes: string[];
-}
-interface ResourceViewerPageVM extends ViewModel {
-    beckon: BeckonVM;
-    browse: ShellVM;
-    mark: MarkVM;
-    gather: GatherVM;
-    yield: YieldVM;
-    annotations$: Observable<Annotation[]>;
-    annotationGroups$: Observable<AnnotationGroups>;
-    entityTypes$: Observable<string[]>;
-    events$: Observable<StoredEventResponse[]>;
-    referencedBy$: Observable<ReferencedByEntry[]>;
-    content$: Observable<string>;
-    contentLoading$: Observable<boolean>;
-    mediaToken$: Observable<string | null>;
-    wizard$: Observable<WizardState>;
-    closeWizard(): void;
-}
-declare function createResourceViewerPageVM(client: SemiontApiClient, resourceId: ResourceId, locale: string, browse: ShellVM, options?: {
-    mediaType?: string;
-}): ResourceViewerPageVM;
-
-type ResourceDescriptor = components['schemas']['ResourceDescriptor'];
-type ComposeMode = 'new' | 'clone' | 'reference';
-interface ComposeParams {
-    mode?: string | undefined;
-    token?: string | undefined;
-    annotationUri?: string | undefined;
-    sourceDocumentId?: string | undefined;
-    name?: string | undefined;
-    entityTypes?: string | undefined;
-    storedContext?: string | undefined;
-}
-interface CloneData {
-    sourceResource: ResourceDescriptor;
-    sourceContent: string;
-}
-interface ReferenceData {
-    annotationUri: string;
-    sourceDocumentId: string;
-    name: string;
-    entityTypes: string[];
-}
-interface SaveResourceParams {
-    mode: ComposeMode;
-    name: string;
-    storageUri: string;
-    content?: string;
-    file?: File;
-    format?: string;
-    charset?: string;
-    entityTypes?: string[];
-    language: string;
-    archiveOriginal?: boolean;
-    annotationUri?: string;
-    sourceDocumentId?: string;
-}
-interface ComposePageVM extends ViewModel {
-    browse: ShellVM;
-    mode$: Observable<ComposeMode>;
-    loading$: Observable<boolean>;
-    cloneData$: Observable<CloneData | null>;
-    referenceData$: Observable<ReferenceData | null>;
-    gatheredContext$: Observable<GatheredContext | null>;
-    entityTypes$: Observable<string[]>;
-    save(params: SaveResourceParams): Promise<string>;
-}
-declare function createComposePageVM(client: SemiontApiClient, browse: ShellVM, params: ComposeParams, auth?: AccessToken): ComposePageVM;
-
-/**
- * MIME type utilities for Semiont
- *
- * Initial support for:
- * - text/plain
- * - text/markdown
- * - image/png
- * - image/jpeg
- * - application/pdf
- */
-/**
- * Map MIME type to file extension
- */
-declare function getExtensionForMimeType(mimeType: string): string;
-/**
- * Detect if MIME type is an image (png or jpeg only for now)
- */
-declare function isImageMimeType(mimeType: string): boolean;
-/**
- * Detect if MIME type is text-based (plain or markdown only for now)
- */
-declare function isTextMimeType(mimeType: string): boolean;
-/**
- * Detect if MIME type is PDF
- */
-declare function isPdfMimeType(mimeType: string): boolean;
-/**
- * Get category for MIME type (for routing to appropriate viewer)
- *
- * Categories represent annotation models, not file formats:
- * - 'text': Text-based annotations (TextPositionSelector, TextQuoteSelector)
- * - 'image': Spatial coordinate annotations (SvgSelector, FragmentSelector)
- *
- * PDFs use spatial coordinates for annotations, so they belong to 'image' category.
- */
-type MimeCategory = 'text' | 'image' | 'unsupported';
-declare function getMimeCategory(mimeType: string): MimeCategory;
 
-export { APIError, type ActiveJob, type ActorVM, type ActorVMOptions, AdminNamespace, type AdminSecurityVM, type AdminUsersVM, type AnnotationGroups, type AnnotationHistoryResponse, AuthNamespace, BeckonNamespace, type BeckonVM, BindNamespace, BrowseNamespace, type BusEvent, BusRequestError, COMMON_PANELS, type Cache, type CloneData, type ComposeMode, type ComposePageVM, type ComposeParams, type ConnectionState, type CreateAnnotationInput, type CreateFromTokenOptions, type CreateResourceInput, DEGRADED_THRESHOLD_MS, type DiscoverVM, type EntityTagsVM, type ExchangeVM, FrontendSessionSignals, type GatherAnnotationProgress, GatherNamespace, type GatherVM, type GenerateDocumentOptions, type GenerationOptions, type GetBrowserOptions, HOVER_DELAY_MS, type HoverHandlers, type ImportPreview, InMemorySessionStorage, type Job, type JobAssignment, type JobClaimAdapter, type JobClaimAdapterOptions, JobNamespace, type JobQueueVM, type KbSessionStatus, type KnowledgeBase, type MarkAssistOptions, type MarkAssistProgress, MarkNamespace, type MarkVM, MatchNamespace, type MatchSearchProgress, type MatchVM, type MimeCategory, type NewKnowledgeBase, type OpenResource, type PendingAnnotation, RESOURCE_PANELS, type ReferenceData, type ReferencedByEntry, type RequestContent$1 as RequestContent, type RequestOptions, type ResourceLoaderVM, type ResourceViewerPageVM, type ResponseContent$1 as ResponseContent, type SaveResourceParams, type SearchPipeline, type SearchPipelineOptions, type SearchState, SemiontApiClient, type SemiontApiClientConfig, SemiontBrowser, type SemiontBrowserConfig, SemiontError, type SemiontErrorCode, SemiontSession, type SemiontSessionConfig, type SessionStorage, type SessionVM, type ShellVM, type ShellVMOptions, type SmelterActorVM, type SmelterActorVMOptions, type SmelterEvent, type StoredSession, type TokenRefresher, type ToolbarPanelType, type User, type UserInfo, type ViewModel, type WelcomeVM, type WizardState, YieldNamespace, type YieldVM, busRequest, createActorVM, createAdminSecurityVM, createAdminUsersVM, createBeckonVM, createCache, createComposePageVM, createDiscoverVM, createDisposer, createEntityTagsVM, createExchangeVM, createGatherVM, createHoverHandlers, createJobClaimAdapter, createJobQueueVM, createMarkVM, createMatchVM, createResourceLoaderVM, createResourceViewerPageVM, createSearchPipeline, createSessionVM, createShellVM, createSmelterActorVM, createWelcomeVM, createYieldVM, defaultProtocol, getBrowser, getExtensionForMimeType, getMimeCategory, isImageMimeType, isPdfMimeType, isTextMimeType, isValidHostname, kbBackendUrl, notifyPermissionDenied, notifySessionExpired, setStoredSession };
+export { APIError, type ActorVM, type ActorVMOptions, type BusEvent, DEGRADED_THRESHOLD_MS, HttpContentTransport, HttpTransport, type HttpTransportConfig, type TokenRefresher, createActorVM };