@semiont/api-client 0.4.14 → 0.4.15

package/dist/index.d.ts

@@ -1,20 +1,21 @@
 import * as _semiont_core from '@semiont/core';
-import { EntityType, BaseUrl, Logger, ResourceId, AccessToken, AnnotationId, components, EventBus, paths, Email, RefreshToken, GoogleCredential, ContentFormat, SearchQuery, CloneToken, Motivation, UserDID, JobId, UserId } from '@semiont/core';
+import { BaseUrl, Logger, ResourceId, AccessToken, components, UserDID, paths, AnnotationId, GraphConnection, UpdateResourceInput, Motivation, MarkProgress, BodyOperation, GatheredContext, YieldProgress as YieldProgress$1, JobId, EventBus, Email, RefreshToken, GoogleCredential, ContentFormat, SearchQuery, CloneToken, EntityType } from '@semiont/core';
 export { Logger, Selector, getFragmentSelector, getSvgSelector, getTextPositionSelector, validateSvgMarkup } from '@semiont/core';
-import { Subscription, Observable } from 'rxjs';
+import { Observable } 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';
 
 /**
- * TypeScript types for Server-Sent Events (SSE) streaming
+ * TypeScript types for SSE event payloads.
  *
- * These types match the event payloads sent by backend SSE endpoints.
- * They are not validated (per SSE-VALIDATION-CONSIDERATIONS.md) but provide
- * type safety for client code consuming the streams.
+ * Progress and result types for events delivered via the long-lived
+ * events-stream. These match the payloads emitted by job workers on
+ * the resource-scoped EventBus. Used by the MCP server for type-safe
+ * event handling.
  */
 /**
  * Progress event for reference/linking detection stream
  *
- * Sent by POST /resources/:id/annotate-references-stream
+ * Sent by POST /resources/:id/annotate-references
  *
  * @example
  * ```typescript
@@ -45,7 +46,7 @@ interface ReferenceDetectionProgress {
 /**
  * Progress event for resource generation stream
  *
- * Sent by POST /resources/:resourceId/annotations/:annotationId/yield-resource-stream
+ * Sent by POST /resources/:resourceId/annotations/:annotationId/yield-resource
  *
  * @example
  * ```typescript
@@ -110,7 +111,7 @@ interface YieldProgress {
  * eventBus.get('detection:failed').subscribe(({ error }) => console.error(error));
  *
  * // Start stream - eventBus is required (TypeScript enforced)
- * const stream = client.sse.detectReferences(resourceId, request, { auth, eventBus });
+ * const stream = client.sse.markReferences(resourceId, request, { auth, eventBus });
  *
  * // Cleanup when done
  * stream.close();
@@ -127,7 +128,7 @@ interface SSEStream {
      * ```typescript
      * // React cleanup
      * useEffect(() => {
-     *   const stream = client.sse.detectReferences(..., { auth, eventBus });
+     *   const stream = client.sse.markReferences(..., { auth, eventBus });
      *   return () => stream.close();
      * }, []);
      * ```
@@ -141,72 +142,6 @@ interface SSEStream {
  */
 declare const SSE_STREAM_CONNECTED: "stream-connected";
 type SSEStreamConnected = typeof SSE_STREAM_CONNECTED;
-/**
- * Request body for reference annotation stream
- */
-interface AnnotateReferencesStreamRequest {
-    entityTypes: EntityType[];
-    includeDescriptiveReferences?: boolean;
-}
-/**
- * Request body for generation stream
- * Uses generated type from OpenAPI schema
- */
-type YieldResourceStreamRequest = components['schemas']['YieldResourceStreamRequest'];
-/**
- * Request body for highlight annotation stream
- */
-interface AnnotateHighlightsStreamRequest {
-    instructions?: string;
-    /** Desired number of highlights per 2000 words (1-15) */
-    density?: number;
-}
-/**
- * Request body for assessment annotation stream
- */
-interface AnnotateAssessmentsStreamRequest {
-    instructions?: string;
-    tone?: 'analytical' | 'critical' | 'balanced' | 'constructive';
-    /** Desired number of assessments per 2000 words (1-10) */
-    density?: number;
-    /** BCP 47 language tag for generated text (e.g. 'en', 'fr') */
-    language?: string;
-}
-/**
- * Request body for comment annotation stream
- */
-interface AnnotateCommentsStreamRequest {
-    instructions?: string;
-    tone?: 'scholarly' | 'explanatory' | 'conversational' | 'technical';
-    /** Desired number of comments per 2000 words (2-12) */
-    density?: number;
-    /** BCP 47 language tag for generated text (e.g. 'en', 'fr') */
-    language?: string;
-}
-/**
- * Request body for tag annotation stream
- */
-interface AnnotateTagsStreamRequest {
-    schemaId: string;
-    categories: string[];
-}
-/**
- * Request body for resource gather stream
- */
-type GatherResourceStreamRequest = components['schemas']['GatherResourceStreamRequest'];
-/**
- * Request body for annotation gather stream
- */
-type GatherAnnotationStreamRequest = components['schemas']['GatherAnnotationStreamRequest'];
-/**
- * Request body for bind annotation stream
- * Uses generated type from OpenAPI schema
- */
-type BindAnnotationStreamRequest = components['schemas']['BindAnnotationStreamRequest'];
-/**
- * Request body for match search stream
- */
-type MatchSearchStreamRequest = components['schemas']['MatchSearchStreamRequest'];
 /**
  * SSE Client configuration
  */
@@ -223,28 +158,27 @@ interface SSERequestOptions {
     eventBus: _semiont_core.EventBus;
 }
 /**
- * SSE Client for real-time streaming operations
+ * SSE Client for long-lived streaming connections.
  *
- * Separate from the main HTTP client to clearly mark streaming endpoints.
- * Uses native fetch() instead of ky for SSE support.
+ * This client has three methods — one per long-lived broadcast stream.
+ * Per-operation SSE routes have been replaced by plain HTTP POSTs with
+ * results delivered via the events-stream.
  *
- * This client is stateless - auth tokens are passed per-request via options.
+ * Uses native fetch() instead of ky for SSE support.
+ * Auth tokens are passed per-request via options.
  *
  * @example
  * ```typescript
- * const sseClient = new SSEClient({
- *   baseUrl: 'http://localhost:4000'
- * });
+ * const sseClient = new SSEClient({ baseUrl: 'http://localhost:4000' });
  *
- * const stream = sseClient.markReferences(
- *   'http://localhost:4000/resources/doc-123',
- *   { entityTypes: ['Person', 'Organization'] },
- *   { auth: 'your-token' }
- * );
+ * // Open a long-lived resource events stream (auto-reconnects on disconnect)
+ * const stream = sseClient.resourceEvents(resourceId, { auth, eventBus });
  *
- * stream.onProgress((p) => console.log(p.message));
- * stream.onComplete((r) => console.log(`Found ${r.foundCount} entities`));
- * stream.onError((e) => console.error('Detection failed:', e));
+ * // Events auto-route to EventBus typed channels
+ * eventBus.get('mark:body-updated').subscribe((event) => { ... });
+ *
+ * // Close when done
+ * stream.close();
  * ```
  */
 declare class SSEClient {
@@ -255,280 +189,6 @@ declare class SSEClient {
      * Get common headers for SSE requests
      */
     private getHeaders;
-    /**
-     * Detect annotations in a resource (streaming)
-     *
-     * Streams entity detection progress via Server-Sent Events.
-     *
-     * @param resourceId - Resource URI or ID
-     * @param request - Detection configuration (entity types to detect)
-     * @param options - Request options (auth token)
-     * @returns SSE stream controller with progress/complete/error callbacks
-     *
-     * @example
-     * ```typescript
-     * const stream = sseClient.markReferences(
-     *   'http://localhost:4000/resources/doc-123',
-     *   { entityTypes: ['Person', 'Organization'] },
-     *   { auth: 'your-token' }
-     * );
-     *
-     * stream.onProgress((progress) => {
-     *   console.log(`Scanning: ${progress.currentEntityType}`);
-     *   console.log(`Progress: ${progress.processedEntityTypes}/${progress.totalEntityTypes}`);
-     * });
-     *
-     * stream.onComplete((result) => {
-     *   console.log(`Detection complete! Found ${result.foundCount} entities`);
-     * });
-     *
-     * stream.onError((error) => {
-     *   console.error('Detection failed:', error.message);
-     * });
-     *
-     * // Cleanup when done
-     * stream.close();
-     * ```
-     */
-    markReferences(resourceId: ResourceId, request: AnnotateReferencesStreamRequest, options: SSERequestOptions): SSEStream;
-    /**
-     * Generate resource from annotation (streaming)
-     *
-     * Streams resource generation progress via Server-Sent Events.
-     *
-     * @param resourceId - Source resource URI or ID
-     * @param annotationId - Annotation URI or ID to use as generation source
-     * @param request - Generation options (title, prompt, language)
-     * @param options - Request options (auth token)
-     * @returns SSE stream controller with progress/complete/error callbacks
-     *
-     * @example
-     * ```typescript
-     * const stream = sseClient.yieldResource(
-     *   'http://localhost:4000/resources/doc-123',
-     *   'http://localhost:4000/annotations/ann-456',
-     *   { language: 'es', title: 'Spanish Summary' },
-     *   { auth: 'your-token' }
-     * );
-     *
-     * stream.onProgress((progress) => {
-     *   console.log(`${progress.status}: ${progress.percentage}%`);
-     *   console.log(progress.message);
-     * });
-     *
-     * stream.onComplete((result) => {
-     *   console.log(`Yielded resource: ${result.resourceId}`);
-     * });
-     *
-     * stream.onError((error) => {
-     *   console.error('Yield failed:', error.message);
-     * });
-     *
-     * // Cleanup when done
-     * stream.close();
-     * ```
-     */
-    yieldResource(resourceId: ResourceId, annotationId: AnnotationId, request: YieldResourceStreamRequest, options: SSERequestOptions): SSEStream;
-    /**
-     * Detect highlights in a resource (streaming)
-     *
-     * Streams highlight annotation progress via Server-Sent Events.
-     *
-     * @param resourceId - Resource URI or ID
-     * @param request - Detection configuration (optional instructions)
-     * @param options - Request options (auth token)
-     * @returns SSE stream controller with progress/complete/error callbacks
-     *
-     * @example
-     * ```typescript
-     * const stream = sseClient.markHighlights(
-     *   'http://localhost:4000/resources/doc-123',
-     *   { instructions: 'Focus on key technical points' },
-     *   { auth: 'your-token' }
-     * );
-     *
-     * stream.onProgress((progress) => {
-     *   console.log(`${progress.status}: ${progress.percentage}%`);
-     *   console.log(progress.message);
-     * });
-     *
-     * stream.onComplete((result) => {
-     *   console.log(`Detection complete! Created ${result.createdCount} highlights`);
-     * });
-     *
-     * stream.onError((error) => {
-     *   console.error('Detection failed:', error.message);
-     * });
-     *
-     * // Cleanup when done
-     * stream.close();
-     * ```
-     */
-    markHighlights(resourceId: ResourceId, request: AnnotateHighlightsStreamRequest | undefined, options: SSERequestOptions): SSEStream;
-    /**
-     * Detect assessments in a resource (streaming)
-     *
-     * Streams assessment annotation progress via Server-Sent Events.
-     *
-     * @param resourceId - Resource URI or ID
-     * @param request - Detection configuration (optional instructions)
-     * @param options - Request options (auth token)
-     * @returns SSE stream controller with progress/complete/error callbacks
-     *
-     * @example
-     * ```typescript
-     * const stream = sseClient.markAssessments(
-     *   'http://localhost:4000/resources/doc-123',
-     *   { instructions: 'Evaluate claims for accuracy' },
-     *   { auth: 'your-token' }
-     * );
-     *
-     * stream.onProgress((progress) => {
-     *   console.log(`${progress.status}: ${progress.percentage}%`);
-     *   console.log(progress.message);
-     * });
-     *
-     * stream.onComplete((result) => {
-     *   console.log(`Detection complete! Created ${result.createdCount} assessments`);
-     * });
-     *
-     * stream.onError((error) => {
-     *   console.error('Detection failed:', error.message);
-     * });
-     *
-     * // Cleanup when done
-     * stream.close();
-     * ```
-     */
-    markAssessments(resourceId: ResourceId, request: AnnotateAssessmentsStreamRequest | undefined, options: SSERequestOptions): SSEStream;
-    /**
-     * Detect comments in a resource (streaming)
-     *
-     * Streams comment annotation progress via Server-Sent Events.
-     * Uses AI to identify passages that would benefit from explanatory comments
-     * and creates comment annotations with contextual information.
-     *
-     * @param resourceId - Resource URI or ID
-     * @param request - Detection configuration (optional instructions and tone)
-     * @param options - Request options (auth token)
-     * @returns SSE stream controller with progress/complete/error callbacks
-     *
-     * @example
-     * ```typescript
-     * const stream = sseClient.markComments(
-     *   'http://localhost:4000/resources/doc-123',
-     *   {
-     *     instructions: 'Focus on technical terminology',
-     *     tone: 'scholarly'
-     *   },
-     *   { auth: 'your-token' }
-     * );
-     *
-     * stream.onProgress((progress) => {
-     *   console.log(`${progress.status}: ${progress.percentage}%`);
-     * });
-     *
-     * stream.onComplete((result) => {
-     *   console.log(`Detection complete! Created ${result.createdCount} comments`);
-     * });
-     *
-     * stream.onError((error) => {
-     *   console.error('Detection failed:', error.message);
-     * });
-     *
-     * // Cleanup when done
-     * stream.close();
-     * ```
-     */
-    markComments(resourceId: ResourceId, request: AnnotateCommentsStreamRequest | undefined, options: SSERequestOptions): SSEStream;
-    /**
-     * Detect tags in a resource (streaming)
-     *
-     * Streams tag annotation progress via Server-Sent Events.
-     * Uses AI to identify passages serving specific structural roles
-     * (e.g., IRAC, IMRAD, Toulmin) and creates tag annotations with dual-body structure.
-     *
-     * @param resourceId - Resource URI or ID
-     * @param request - Detection configuration (schema and categories to detect)
-     * @param options - Request options (auth token)
-     * @returns SSE stream controller with progress/complete/error callbacks
-     *
-     * @example
-     * ```typescript
-     * const stream = sseClient.markTags(
-     *   'http://localhost:4000/resources/doc-123',
-     *   {
-     *     schemaId: 'legal-irac',
-     *     categories: ['Issue', 'Rule', 'Application', 'Conclusion']
-     *   },
-     *   { auth: 'your-token' }
-     * );
-     *
-     * stream.onProgress((progress) => {
-     *   console.log(`${progress.status}: ${progress.percentage}%`);
-     *   console.log(`Processing ${progress.currentCategory}...`);
-     * });
-     *
-     * stream.onComplete((result) => {
-     *   console.log(`Detection complete! Created ${result.tagsCreated} tags`);
-     * });
-     *
-     * stream.onError((error) => {
-     *   console.error('Detection failed:', error.message);
-     * });
-     *
-     * // Cleanup when done
-     * stream.close();
-     * ```
-     */
-    markTags(resourceId: ResourceId, request: AnnotateTagsStreamRequest, options: SSERequestOptions): SSEStream;
-    /**
-     * Gather LLM context for a resource (streaming)
-     *
-     * Streams resource LLM context gathering progress via Server-Sent Events.
-     *
-     * @param resourceId - Resource URI or ID
-     * @param request - Gather configuration (depth, maxResources, includeContent, includeSummary)
-     * @param options - Request options (auth token, eventBus)
-     * @returns SSE stream controller with progress/complete/error callbacks
-     */
-    gatherResource(resourceId: ResourceId, request: GatherResourceStreamRequest, options: SSERequestOptions): SSEStream;
-    /**
-     * Gather LLM context for an annotation (streaming)
-     *
-     * Streams annotation LLM context gathering progress via Server-Sent Events.
-     *
-     * @param resourceId - Resource URI or ID
-     * @param annotationId - Annotation URI or ID
-     * @param request - Gather configuration (contextWindow)
-     * @param options - Request options (auth token, eventBus)
-     * @returns SSE stream controller with progress/complete/error callbacks
-     */
-    gatherAnnotation(resourceId: ResourceId, annotationId: AnnotationId, request: GatherAnnotationStreamRequest, options: SSERequestOptions): SSEStream;
-    /**
-     * Bind annotation body (streaming)
-     *
-     * Applies annotation body operations and streams completion via Server-Sent Events.
-     *
-     * @param resourceId - Resource URI or ID
-     * @param annotationId - Annotation URI or ID
-     * @param request - Bind operations (resourceId + operations array)
-     * @param options - Request options (auth token, eventBus)
-     * @returns SSE stream controller with complete/error callbacks
-     */
-    bindAnnotation(resourceId: ResourceId, annotationId: AnnotationId, request: BindAnnotationStreamRequest, options: SSERequestOptions): SSEStream;
-    /**
-     * Search for binding candidates (streaming)
-     *
-     * Bridges match:search-requested to the backend Matcher actor via SSE.
-     * Results emit as match:search-results on the browser EventBus.
-     *
-     * @param resourceId - Resource the annotation belongs to
-     * @param request - Search configuration (referenceId, context, limit)
-     * @param options - Request options (auth token, eventBus)
-     * @returns SSE stream controller
-     */
-    matchSearch(resourceId: ResourceId, request: MatchSearchStreamRequest, options: SSERequestOptions): SSEStream;
     /**
      * Subscribe to resource events (long-lived stream)
      *
@@ -579,11 +239,9 @@ declare class SSEClient {
      * ```typescript
      * const stream = sseClient.globalEvents({ auth: 'your-token', eventBus });
      *
-     * // Events auto-emit to EventBus — subscribe there
-     * eventBus.get('make-meaning:event').subscribe((event) => {
-     *   if (event.type === 'entitytype.added') {
-     *     // Invalidate entity types query
-     *   }
+     * // Events auto-emit to EventBus typed channels — subscribe there
+     * eventBus.get('mark:entity-type-added').subscribe((stored) => {
+     *   // Invalidate entity types query
      * });
      *
      * // Close when no longer needed
@@ -611,205 +269,629 @@ declare class SSEClient {
 }
 
 /**
- * FlowEngine — framework-agnostic flow orchestration
+ * 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 (events-stream 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$1 = components['schemas']['Annotation'];
+type ResourceDescriptor$2 = components['schemas']['ResourceDescriptor'];
+type StoredEventResponse$1 = components['schemas']['StoredEventResponse'];
+type GatherProgress = components['schemas']['GatherProgress'];
+type MatchSearchResult = components['schemas']['MatchSearchResult'];
+type MarkAssistFinished = components['schemas']['MarkAssistFinished'];
+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 : 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 = RequestContent$1<paths['/resources/{id}/annotations']['post']>;
+/** 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;
+}
+/** 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 = RequestContent$1<paths['/api/clone-tokens/create-resource']['post']>;
+/** Referenced-by entry from browse.referencedBy() */
+type ReferencedByEntry = ResponseContent$1<paths['/resources/{id}/referenced-by']['get']>['referencedBy'][number];
+/** Annotation history from browse.annotationHistory() */
+type AnnotationHistoryResponse = ResponseContent$1<paths['/resources/{resourceId}/annotations/{annotationId}/history']['get']>;
+/** 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.
+ * Emits MarkProgress during scanning, then MarkAssistFinished on completion.
+ * On failure, the Observable errors with MarkAssistFailed.
+ */
+type MarkAssistProgress = MarkProgress | MarkAssistFinished;
+/**
+ * Browse — reads from materialized views
+ *
+ * Live queries return Observables that emit initial state and re-emit
+ * on events-stream updates. One-shot reads return Promises.
+ *
+ * Backend actor: Browser (context classes)
+ * Event prefix: browse:*
+ */
+interface BrowseNamespace$1 {
+    resource(resourceId: ResourceId): Observable<ResourceDescriptor$2 | undefined>;
+    resources(filters?: {
+        limit?: number;
+        archived?: boolean;
+    }): Observable<ResourceDescriptor$2[] | 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>;
+    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$2[]>;
+    files(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount'): Promise<ResponseContent$1<paths['/api/browse/files']['get']>>;
+}
+/**
+ * Mark — annotation CRUD, entity types, AI assist
+ *
+ * Commands return Promises that resolve on HTTP acceptance (202).
+ * Results appear on browse Observables via events-stream.
+ * 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$2>;
+    createFromToken(options: CreateFromTokenOptions): Promise<{
+        resourceId: string;
+    }>;
+}
+/**
+ * Beckon — attention coordination
+ *
+ * Fire-and-forget. Ephemeral presence signal delivered via the
+ * attention-stream to other participants.
+ *
+ * Backend actor: (frontend relay via attention-stream)
+ * Event prefix: beckon:*
+ */
+interface BeckonNamespace$1 {
+    attention(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>;
+    }>;
+}
+
+/**
+ * BrowseNamespace — reads from materialized views
  *
- * Owns the subscription/SSE-bridge logic that was previously scattered across
- * React hooks (useBindFlow, useYieldFlow, useMarkFlow, useContextGatherFlow,
- * useResourceEvents, useAttentionStream).
+ * Absorbs AnnotationStore and ResourceStore logic. Live queries return
+ * Observables backed by BehaviorSubjects that update reactively when
+ * EventBus events arrive. One-shot reads are Promise wrappers over HTTP.
  *
- * Each method accepts a `getToken` function called at event-handling time so
- * the token is always fresh (the client is stateless; tokens rotate).
+ * Backend actor: Browser (context classes)
+ * Event prefix: browse:*
+ */
+
+type Annotation = components['schemas']['Annotation'];
+type ResourceDescriptor$1 = components['schemas']['ResourceDescriptor'];
+type StoredEventResponse = components['schemas']['StoredEventResponse'];
+type TokenGetter$9 = () => AccessToken | undefined;
+declare class BrowseNamespace implements BrowseNamespace$1 {
+    private readonly http;
+    private readonly eventBus;
+    private readonly annotationList$;
+    private readonly fetchingAnnotationList;
+    private readonly annotationListObs$;
+    private readonly annotationDetail$;
+    private readonly fetchingAnnotationDetail;
+    private readonly annotationDetailObs$;
+    private readonly resourceDetail$;
+    private readonly fetchingResourceDetail;
+    private readonly resourceDetailObs$;
+    private readonly resourceList$;
+    private readonly fetchingResourceList;
+    private readonly resourceListObs$;
+    private readonly entityTypes$;
+    private fetchingEntityTypes;
+    private readonly referencedBy$;
+    private readonly fetchingReferencedBy;
+    private readonly referencedByObs$;
+    private readonly getToken;
+    constructor(http: SemiontApiClient, eventBus: EventBus, getToken: TokenGetter$9);
+    resource(resourceId: ResourceId): Observable<ResourceDescriptor$1 | undefined>;
+    resources(filters?: {
+        limit?: number;
+        archived?: boolean;
+    }): Observable<ResourceDescriptor$1[] | undefined>;
+    annotations(resourceId: ResourceId): Observable<Annotation[] | undefined>;
+    annotation(resourceId: ResourceId, annotationId: AnnotationId): Observable<Annotation | undefined>;
+    entityTypes(): Observable<string[] | undefined>;
+    referencedBy(resourceId: ResourceId): Observable<ReferencedByEntry[] | 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[]>;
+    annotationHistory(resourceId: ResourceId, annotationId: AnnotationId): Promise<AnnotationHistoryResponse>;
+    connections(_resourceId: ResourceId): Promise<GraphConnection[]>;
+    backlinks(_resourceId: ResourceId): Promise<Annotation[]>;
+    resourcesByName(_query: string, _limit?: number): Promise<ResourceDescriptor$1[]>;
+    files(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount'): Promise<ResponseContent$1<paths['/api/browse/files']['get']>>;
+    invalidateAnnotationList(resourceId: ResourceId): void;
+    invalidateAnnotationDetail(annotationId: AnnotationId): void;
+    invalidateResourceDetail(id: ResourceId): void;
+    invalidateResourceLists(): void;
+    invalidateEntityTypes(): void;
+    invalidateReferencedBy(resourceId: ResourceId): void;
+    updateAnnotationInPlace(resourceId: ResourceId, annotation: Annotation): void;
+    private subscribeToEvents;
+    private fetchAnnotationList;
+    private fetchAnnotationDetail;
+    private fetchResourceDetail;
+    private fetchResourceList;
+    private fetchEntityTypes;
+    private fetchReferencedBy;
+}
+
+/**
+ * MarkNamespace — annotation CRUD, entity types, AI assist
  *
- * Each method returns an RxJS Subscription. The caller is responsible for
- * calling .unsubscribe() when the flow is no longer needed (e.g. in a
- * React useEffect cleanup or on workspace teardown).
+ * Commands return Promises that resolve on HTTP acceptance.
+ * Results appear on browse Observables via events-stream.
+ * assist() returns an Observable for long-running progress.
  *
- * No React imports. No DOM imports. Pure RxJS + EventBus.
+ * Backend actor: Stower
+ * Event prefix: mark:*
  */
 
-type TokenGetter$2 = () => AccessToken | undefined;
-declare class FlowEngine {
+type TokenGetter$8 = () => AccessToken | undefined;
+declare class MarkNamespace implements MarkNamespace$1 {
+    private readonly http;
     private readonly eventBus;
-    private readonly sse;
+    private readonly getToken;
+    constructor(http: SemiontApiClient, eventBus: EventBus, getToken: TokenGetter$8);
+    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;
+}
+
+/**
+ * BindNamespace — 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)
+ */
+
+type TokenGetter$7 = () => AccessToken | undefined;
+declare class BindNamespace implements BindNamespace$1 {
     private readonly http;
-    constructor(eventBus: EventBus, sse: SSEClient, http: SemiontApiClient);
-    /**
-     * Activate the bind flow for a resource.
-     *
-     * @subscribes bind:update-body  — calls SSE bindAnnotation
-     * @subscribes match:search-requested — calls SSE bindSearch
-     * @emits bind:body-updated, bind:body-update-failed
-     */
-    bind(rUri: ResourceId, getToken: TokenGetter$2): Subscription;
-    /**
-     * Activate the yield (generation) flow for a resource.
-     *
-     * @subscribes yield:request — calls SSE yieldResource
-     * @subscribes yield:finished — links generated resource back to the reference annotation via bind:update-body
-     * @subscribes job:cancel-requested (generation) — aborts in-flight stream
-     */
-    yield(_rUri: ResourceId, getToken: TokenGetter$2): Subscription;
-    /**
-     * Activate the mark (annotation CRUD + assist) flow for a resource.
-     *
-     * @subscribes mark:submit — HTTP markAnnotation
-     * @subscribes mark:delete — HTTP deleteAnnotation
-     * @subscribes mark:assist-request — SSE mark* (by motivation)
-     * @subscribes job:cancel-requested (annotation) — aborts in-flight assist
-     * @emits mark:created, mark:create-failed, mark:deleted, mark:delete-failed
-     */
-    mark(rUri: ResourceId, getToken: TokenGetter$2): Subscription;
-    /**
-     * Activate the gather-context flow for a resource.
-     *
-     * @subscribes gather:requested — calls SSE gatherAnnotation, threads correlationId
-     * @emits gather:complete (re-emitted from SSE gather:annotation-finished)
-     */
-    gatherContext(rUri: ResourceId, getToken: TokenGetter$2): Subscription;
-    /**
-     * Open the long-lived resource-events SSE stream.
-     * Returns a Subscription whose teardown closes the stream.
-     */
-    resourceEvents(rUri: ResourceId, getToken: TokenGetter$2): Subscription;
-    /**
-     * Open the long-lived participant attention SSE stream.
-     * Returns a Subscription whose teardown closes the stream.
-     */
-    attentionStream(getToken: TokenGetter$2): Subscription;
+    private readonly getToken;
+    constructor(http: SemiontApiClient, getToken: TokenGetter$7);
+    body(resourceId: ResourceId, annotationId: AnnotationId, operations: BodyOperation[]): Promise<void>;
 }
 
 /**
- * ResourceStore — per-workspace observable resource cache
+ * GatherNamespace — context assembly
+ *
+ * Long-running (LLM calls + graph traversal). Returns Observables
+ * that emit progress then the gathered context.
  *
- * BehaviorSubject-backed store that:
- * - Populates lazily on first subscribe (no up-front fetch)
- * - Updates reactively when EventBus events arrive (no manual invalidation)
- * - Is readable from outside React
+ * Backend actor: Gatherer
+ * Event prefix: gather:*
+ */
+
+type TokenGetter$6 = () => AccessToken | undefined;
+declare class GatherNamespace implements GatherNamespace$1 {
+    private readonly http;
+    private readonly eventBus;
+    private readonly getToken;
+    constructor(http: SemiontApiClient, eventBus: EventBus, getToken: TokenGetter$6);
+    annotation(annotationId: AnnotationId, resourceId: ResourceId, options?: {
+        contextWindow?: number;
+    }): Observable<GatherAnnotationProgress>;
+    resource(_resourceId: ResourceId, _options?: {
+        contextWindow?: number;
+    }): Observable<GatherAnnotationProgress>;
+}
+
+/**
+ * MatchNamespace — search and ranking
  *
- * EventBus events handled:
- * - yield:created       → fetch new resource into map, invalidate lists
- * - mark:archived       → invalidate resource detail + lists
- * - mark:unarchived     → invalidate resource detail + lists
- * - mark:entity-tag-added / mark:entity-tag-removed → invalidate resource detail
+ * Long-running (semantic search, optional LLM scoring). Returns
+ * Observable with results.
  *
- * Token: mutable — call setTokenGetter() from the React layer when auth changes.
+ * Backend actor: Matcher
+ * Event prefix: match:*
  */
 
-type ResponseContent$2<T> = T extends {
-    responses: {
-        200: {
-            content: {
-                'application/json': infer R;
-            };
-        };
-    };
-} ? R : never;
-type ResourceDetail = ResponseContent$2<paths['/resources/{id}']['get']>;
-type ResourceListResponse = ResponseContent$2<paths['/resources']['get']>;
-type TokenGetter$1 = () => AccessToken | undefined;
-declare class ResourceStore {
+type TokenGetter$5 = () => AccessToken | undefined;
+declare class MatchNamespace implements MatchNamespace$1 {
     private readonly http;
-    /** Cache of individual resource details, keyed by ResourceId */
-    private readonly detail$;
-    /** Cache of list responses, keyed by a serialized options string */
-    private readonly list$;
-    /** Track in-flight fetches to avoid duplicate requests */
-    private readonly fetchingDetail;
-    private readonly fetchingList;
-    /** Memoized Observables — same instance returned for the same key */
-    private readonly detailObs$;
-    private readonly listObs$;
-    /** Mutable token getter — updated from the React layer when auth changes */
-    private getToken;
-    /** Update the token getter (called from React when auth token changes) */
-    setTokenGetter(getter: TokenGetter$1): void;
-    constructor(http: SemiontApiClient, eventBus: EventBus);
-    /**
-     * Get a single resource by ID as an Observable.
-     * Triggers a fetch if not cached.
-     */
-    get(id: ResourceId): Observable<ResourceDetail | undefined>;
-    /**
-     * List resources as an Observable.
-     * Triggers a fetch if not cached.
-     */
-    list(options?: {
+    private readonly eventBus;
+    private readonly getToken;
+    constructor(http: SemiontApiClient, eventBus: EventBus, getToken: TokenGetter$5);
+    search(resourceId: ResourceId, referenceId: string, context: GatheredContext, options?: {
         limit?: number;
-        archived?: boolean;
-    }): Observable<ResourceListResponse | undefined>;
-    /** Invalidate and re-fetch a specific resource detail */
-    invalidateDetail(id: ResourceId): void;
-    /** Remove all list caches (triggers re-fetch on next subscribe) */
-    invalidateLists(): void;
-    private fetchDetail;
-    private fetchList;
+        useSemanticScoring?: boolean;
+    }): Observable<MatchSearchProgress>;
 }
 
 /**
- * AnnotationStore — per-workspace observable annotation cache
+ * YieldNamespace — resource creation
  *
- * BehaviorSubject-backed store that:
- * - Populates lazily on first subscribe (no up-front fetch)
- * - Updates reactively when EventBus events arrive (no manual invalidation)
- * - Is readable from outside React
+ * resource() is synchronous file upload (Promise).
+ * fromAnnotation() is long-running LLM generation (Observable).
+ *
+ * Backend actor: Stower + generation worker
+ * Event prefix: yield:*
+ */
+
+type ResourceDescriptor = components['schemas']['ResourceDescriptor'];
+type TokenGetter$4 = () => AccessToken | undefined;
+declare class YieldNamespace implements YieldNamespace$1 {
+    private readonly http;
+    private readonly eventBus;
+    private readonly getToken;
+    constructor(http: SemiontApiClient, eventBus: EventBus, getToken: TokenGetter$4);
+    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>;
+    createFromToken(options: CreateFromTokenOptions): Promise<{
+        resourceId: string;
+    }>;
+}
+
+/**
+ * BeckonNamespace — attention coordination
  *
- * EventBus events handled:
- * - mark:deleted      → remove from detail cache
- * - mark:added        → invalidate annotation list (SSE domain event; resourceId on BaseEvent)
- * - mark:removed      → invalidate annotation list + detail (SSE domain event)
- * - mark:body-updated → invalidate annotation list + detail (SSE domain event)
- * - mark:entity-tag-added / mark:entity-tag-removed → invalidate list for resource
+ * Fire-and-forget. Ephemeral presence signal delivered via the
+ * attention-stream to other participants.
  *
- * Token: mutable — call setTokenGetter() from the React layer when auth changes.
+ * Backend actor: (frontend relay via attention-stream)
+ * Event prefix: beckon:*
  */
 
-type ResponseContent$1<T> = T extends {
-    responses: {
-        200: {
-            content: {
-                'application/json': infer R;
-            };
-        };
-    };
-} ? R : never;
-type AnnotationsListResponse = ResponseContent$1<paths['/resources/{id}/annotations']['get']>;
-type AnnotationDetail = ResponseContent$1<paths['/resources/{resourceId}/annotations/{annotationId}']['get']>;
+type TokenGetter$3 = () => AccessToken | undefined;
+declare class BeckonNamespace implements BeckonNamespace$1 {
+    private readonly http;
+    private readonly getToken;
+    constructor(http: SemiontApiClient, getToken: TokenGetter$3);
+    attention(annotationId: AnnotationId, resourceId: ResourceId): void;
+}
+
+/**
+ * JobNamespace — worker lifecycle
+ */
+
+type JobStatusResponse = components['schemas']['JobStatusResponse'];
+type TokenGetter$2 = () => AccessToken | undefined;
+declare class JobNamespace implements JobNamespace$1 {
+    private readonly http;
+    private readonly getToken;
+    constructor(http: SemiontApiClient, getToken: TokenGetter$2);
+    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
+ */
+
+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 AdminUserStatsResponse = components['schemas']['AdminUserStatsResponse'];
+type OAuthConfigResponse = components['schemas']['OAuthConfigResponse'];
 type TokenGetter = () => AccessToken | undefined;
-declare class AnnotationStore {
+declare class AdminNamespace implements AdminNamespace$1 {
     private readonly http;
-    /** Annotation list responses keyed by ResourceId */
-    private readonly list$;
-    /** Individual annotation details keyed by AnnotationId */
-    private readonly detail$;
-    /** Track in-flight fetches */
-    private readonly fetchingList;
-    private readonly fetchingDetail;
-    /** Memoized Observables — same instance returned for the same key */
-    private readonly listObs$;
-    private readonly detailObs$;
-    /** Mutable token getter — updated from the React layer when auth changes */
-    private getToken;
-    /** Update the token getter (called from React when auth token changes) */
-    setTokenGetter(getter: TokenGetter): void;
-    constructor(http: SemiontApiClient, eventBus: EventBus);
-    /**
-     * Get annotations for a resource as an Observable.
-     * Triggers a fetch if not cached.
-     */
-    listForResource(resourceId: ResourceId): Observable<AnnotationsListResponse | undefined>;
-    /**
-     * Get a single annotation detail as an Observable.
-     * Triggers a fetch if not cached.
-     */
-    get(resourceId: ResourceId, annotationId: AnnotationId): Observable<AnnotationDetail | undefined>;
-    /** Invalidate and re-fetch a resource's annotation list */
-    invalidateList(resourceId: ResourceId): void;
-    /** Invalidate a single annotation detail (re-fetched on next subscribe) */
-    invalidateDetail(annotationId: AnnotationId): void;
-    /** Remove an annotation from the detail cache without re-fetching */
-    private removeFromDetailCache;
-    private fetchList;
-    private fetchDetail;
+    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>;
+    }>;
 }
 
 /**
@@ -853,6 +935,18 @@ declare class APIError extends Error {
     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. The frontend's
+ * KnowledgeBaseSessionProvider provides this via an in-flight Promise map
+ * keyed by KB id.
+ */
+type TokenRefresher = () => Promise<string | null>;
 interface SemiontApiClientConfig {
     baseUrl: BaseUrl;
     /** Per-workspace EventBus. Required — one bus per workspace, constructed externally. */
@@ -860,6 +954,15 @@ interface SemiontApiClientConfig {
     timeout?: number;
     retry?: number;
     logger?: Logger;
+    /** Optional 401-recovery hook. See {@link TokenRefresher}. */
+    tokenRefresher?: TokenRefresher;
+    /**
+     * Token getter for the verb-namespace API (client.browse, client.mark, etc.).
+     * When provided, auth is managed internally — no per-call auth needed.
+     * The getter is called on each request to get the current token.
+     * If not provided, namespace methods use undefined auth (public endpoints only).
+     */
+    getToken?: () => AccessToken | undefined;
 }
 /**
  * Options for individual API requests
@@ -880,6 +983,11 @@ declare class SemiontApiClient {
     /** The workspace-scoped EventBus this client was constructed with. */
     readonly eventBus: EventBus;
     private logger?;
+    /**
+     * Shared mutable token getter. All verb namespaces read from this.
+     * Updated via setTokenGetter() from the React auth layer.
+     */
+    private _getToken;
     /**
      * SSE streaming client for real-time operations
      *
@@ -887,21 +995,23 @@ declare class SemiontApiClient {
      * Uses native fetch() instead of ky for SSE support.
      */
     readonly sse: SSEClient;
+    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);
     /**
-     * Framework-agnostic flow orchestration.
-     * Each method returns a Subscription; call .unsubscribe() to tear down.
-     */
-    readonly flows: FlowEngine;
-    /**
-     * Per-workspace observable stores for entity data.
-     * Call stores.resources.setTokenGetter() / stores.annotations.setTokenGetter()
-     * from the React layer when the auth token changes.
+     * Update the token getter for all verb namespaces.
+     * Called from the React auth layer when the token changes.
+     * All namespaces share this getter via closure — no per-namespace sync needed.
      */
-    readonly stores: {
-        resources: ResourceStore;
-        annotations: AnnotationStore;
-    };
-    constructor(config: SemiontApiClientConfig);
+    setTokenGetter(getter: () => AccessToken | undefined): void;
     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']>>;
@@ -1029,8 +1139,78 @@ declare class SemiontApiClient {
     browseAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{resourceId}/annotations/{annotationId}']['get']>>;
     browseAnnotations(id: ResourceId, motivation?: Motivation, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}/annotations']['get']>>;
     deleteAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options?: RequestOptions): Promise<void>;
-    bindAnnotation(resourceId: ResourceId, annotationId: AnnotationId, data: RequestContent<paths['/resources/{resourceId}/annotations/{annotationId}/body']['put']>, 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<ResponseContent<paths['/resources/{resourceId}/annotations/{annotationId}/history']['get']>>;
+    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<ResponseContent<paths['/api/entity-types']['get']>>;
@@ -1104,77 +1284,6 @@ declare class SemiontApiClient {
     browseFiles(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount', options?: RequestOptions): Promise<ResponseContent<paths['/api/browse/files']['get']>>;
 }
 
-/**
- * EventBus-Only Client
- *
- * Implements the same knowledge-domain operations as SemiontApiClient
- * but communicates directly via EventBus instead of HTTP.
- *
- * This proves the EventBus is a complete interface for all knowledge-domain
- * operations. Binary content transfer and auth/admin stay HTTP-only.
- *
- * Usage:
- * ```typescript
- * import { EventBus } from '@semiont/core';
- * import { EventBusClient } from '@semiont/api-client';
- *
- * const eventBus = new EventBus();
- * const client = new EventBusClient(eventBus);
- *
- * const resources = await client.browseResources({ limit: 10 });
- * const resource = await client.browseResource(resourceId('doc-123'));
- * ```
- */
-
-declare class EventBusClient {
-    private eventBus;
-    private timeoutMs;
-    constructor(eventBus: EventBus, timeoutMs?: number);
-    browseResource(resourceId: ResourceId): Promise<components['schemas']['GetResourceResponse']>;
-    browseResources(options?: {
-        search?: string;
-        archived?: boolean;
-        entityType?: string;
-        offset?: number;
-        limit?: number;
-    }): Promise<components['schemas']['ListResourcesResponse']>;
-    getAnnotations(resourceId: ResourceId): Promise<components['schemas']['GetAnnotationsResponse']>;
-    getAnnotation(resourceId: ResourceId, annotationId: AnnotationId): Promise<components['schemas']['GetAnnotationResponse']>;
-    getEvents(resourceId: ResourceId, options?: {
-        type?: string;
-        userId?: string;
-        limit?: number;
-    }): Promise<components['schemas']['GetEventsResponse']>;
-    getAnnotationHistory(resourceId: ResourceId, annotationId: AnnotationId): Promise<components['schemas']['GetAnnotationHistoryResponse']>;
-    getReferencedBy(resourceId: ResourceId, motivation?: string): Promise<components['schemas']['GetReferencedByResponse']>;
-    listEntityTypes(): Promise<components['schemas']['GetEntityTypesResponse']>;
-    addEntityType(tag: string, userId: UserId): void;
-    generateCloneToken(resourceId: ResourceId): Promise<components['schemas']['CloneResourceWithTokenResponse']>;
-    getResourceByToken(token: string): Promise<components['schemas']['GetResourceByTokenResponse']>;
-    createResourceFromToken(options: {
-        token: string;
-        name: string;
-        content: string;
-        userId: UserId;
-        archiveOriginal?: boolean;
-    }): Promise<{
-        resourceId: ResourceId;
-    }>;
-    getJobStatus(jobId: JobId): Promise<components['schemas']['JobStatusResponse']>;
-    gatherAnnotation(annotationId: AnnotationId, resourceId: ResourceId, options?: {
-        includeSourceContext?: boolean;
-        includeTargetContext?: boolean;
-        contextWindow?: number;
-    }): Promise<components['schemas']['AnnotationLLMContextResponse']>;
-    gatherResource(resourceId: ResourceId, options: {
-        depth: number;
-        maxResources: number;
-        includeContent: boolean;
-        includeSummary: boolean;
-    }): Promise<components['schemas']['ResourceLLMContextResponse']>;
-    searchResources(searchTerm: string): Promise<components['schemas']['ResourceDescriptor'][]>;
-}
-
 /**
  * MIME type utilities for Semiont
  *
@@ -1213,4 +1322,4 @@ declare function isPdfMimeType(mimeType: string): boolean;
 type MimeCategory = 'text' | 'image' | 'unsupported';
 declare function getMimeCategory(mimeType: string): MimeCategory;
 
-export { APIError, type AnnotateReferencesStreamRequest, type AnnotationDetail, AnnotationStore, type AnnotationsListResponse, EventBusClient, FlowEngine, type MatchSearchStreamRequest, type MimeCategory, type ReferenceDetectionProgress, type RequestOptions, type ResourceDetail, type ResourceListResponse, ResourceStore, SSEClient, type SSEClientConfig, type SSEStream, type SSEStreamConnected, SSE_STREAM_CONNECTED, SemiontApiClient, type SemiontApiClientConfig, type YieldProgress, type YieldResourceStreamRequest, getExtensionForMimeType, getMimeCategory, isImageMimeType, isPdfMimeType, isTextMimeType };
+export { APIError, AdminNamespace, type AnnotationHistoryResponse, AuthNamespace, BeckonNamespace, BindNamespace, BrowseNamespace, type CreateAnnotationInput, type CreateFromTokenOptions, type CreateResourceInput, type GatherAnnotationProgress, GatherNamespace, type GenerationOptions, JobNamespace, type MarkAssistOptions, type MarkAssistProgress, MarkNamespace, MatchNamespace, type MatchSearchProgress, type MimeCategory, type ReferenceDetectionProgress, type ReferencedByEntry, type RequestContent$1 as RequestContent, type RequestOptions, type ResponseContent$1 as ResponseContent, SSEClient, type SSEClientConfig, type SSEStream, type SSEStreamConnected, SSE_STREAM_CONNECTED, SemiontApiClient, type SemiontApiClientConfig, type TokenRefresher, type User, YieldNamespace, type YieldProgress, getExtensionForMimeType, getMimeCategory, isImageMimeType, isPdfMimeType, isTextMimeType };