@semiont/core 0.4.19 → 0.4.21

package/dist/index.d.ts

@@ -7,304 +7,6 @@ export { A as AnthropicProviderConfig, a as AppConfig, B as BackendServiceConfig
  * Do not make direct changes to the file.
  */
 interface paths {
-    "/resources/{id}": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /**
-         * Get Resource by URI (W3C Content Negotiation)
-         * @description W3C-compliant globally resolvable resource URI with content negotiation. Returns JSON-LD metadata (Accept: application/ld+json), raw representation (Accept: text/plain, text/markdown, etc.), or redirects to frontend (?view=semiont). Requires authentication.
-         */
-        get: {
-            parameters: {
-                query?: {
-                    /** @description Optional view parameter. If set to 'semiont', redirects to frontend viewer. */
-                    view?: "semiont";
-                };
-                header?: never;
-                path: {
-                    /** @description Resource ID */
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Resource metadata (JSON-LD) or raw representation */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/ld+json": components["schemas"]["GetResourceResponse"];
-                        "text/plain": string;
-                        "text/markdown": string;
-                    };
-                };
-                /** @description Redirect to frontend viewer (when ?view=semiont) */
-                302: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-                /** @description Resource not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        /**
-         * Update Resource
-         * @description Update resource metadata (append-only operations - name and content are immutable)
-         */
-        patch: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    /** @description Resource ID */
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: {
-                content: {
-                    "application/json": components["schemas"]["UpdateResourceRequest"];
-                };
-            };
-            responses: {
-                /** @description Update accepted */
-                202: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-                /** @description Resource not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        trace?: never;
-    };
-    "/annotations/{id}": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /**
-         * Get Annotation by URI (W3C Content Negotiation)
-         * @description W3C-compliant globally resolvable annotation URI with content negotiation. Returns JSON-LD for API clients (Accept: application/ld+json or application/json). Redirects to frontend for browsers (Accept: text/html or browser User-Agent). Requires authentication and resourceId query parameter.
-         */
-        get: {
-            parameters: {
-                query: {
-                    /** @description Resource ID or URI containing the annotation */
-                    resourceId: string;
-                };
-                header?: never;
-                path: {
-                    /** @description Annotation ID */
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Annotation representation (JSON-LD) */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/ld+json": components["schemas"]["GetAnnotationResponse"];
-                    };
-                };
-                /** @description Redirect to frontend (for browsers) */
-                302: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-                /** @description Missing resourceId parameter */
-                400: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-                /** @description Annotation not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/api/annotations/{id}/context": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /**
-         * Get Annotation Context
-         * @description Get the text context around an annotation with configurable before/after window
-         */
-        get: {
-            parameters: {
-                query: {
-                    /** @description Resource ID containing the annotation */
-                    resourceId: string;
-                    /** @description Number of characters before the selection */
-                    contextBefore?: number;
-                    /** @description Number of characters after the selection */
-                    contextAfter?: number;
-                };
-                header?: never;
-                path: {
-                    /** @description Annotation ID */
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Annotation context */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["AnnotationContextResponse"];
-                    };
-                };
-                /** @description Invalid query parameters */
-                400: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-                /** @description Authentication required */
-                401: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-                /** @description Annotation not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/api/annotations/{id}/summary": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /**
-         * Get Annotation Summary
-         * @description Get an AI-generated summary of the annotation in context
-         */
-        get: {
-            parameters: {
-                query: {
-                    /** @description Resource ID containing the annotation */
-                    resourceId: string;
-                };
-                header?: never;
-                path: {
-                    /** @description Annotation ID */
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description AI-generated annotation summary */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["ContextualSummaryResponse"];
-                    };
-                };
-                /** @description Missing resourceId parameter */
-                400: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-                /** @description Authentication required */
-                401: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-                /** @description Annotation not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     "/api/health": {
         parameters: {
             query?: never;
@@ -618,6 +320,73 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/tokens/worker": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Worker Token Exchange
+         * @description Exchange a shared secret for a bearer JWT. Used by workers and actors connecting to the EventBus.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /** @description The shared worker secret (SEMIONT_WORKER_SECRET) */
+                        secret: string;
+                    };
+                };
+            };
+            responses: {
+                /** @description Token issued */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @description Bearer JWT for subsequent authenticated requests */
+                            token: string;
+                        };
+                    };
+                };
+                /** @description Invalid worker secret */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Worker authentication not configured */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/users/me": {
         parameters: {
             query?: never;
@@ -1247,7 +1016,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/admin/exchange/export": {
+    "/api/moderate/exchange/export": {
         parameters: {
             query?: never;
             header?: never;
@@ -1290,7 +1059,7 @@ interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description Forbidden - Admin access required */
+                /** @description Forbidden - moderator or admin role required */
                 403: {
                     headers: {
                         [name: string]: unknown;
@@ -1307,7 +1076,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/admin/exchange/import": {
+    "/api/moderate/exchange/import": {
         parameters: {
             query?: never;
             header?: never;
@@ -1366,7 +1135,7 @@ interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description Forbidden - Admin access required */
+                /** @description Forbidden - moderator or admin role required */
                 403: {
                     headers: {
                         [name: string]: unknown;
@@ -1383,7 +1152,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/resources": {
+    "/api/cookies/consent": {
         parameters: {
             query?: never;
             header?: never;
@@ -1391,129 +1160,25 @@ interface paths {
             cookie?: never;
         };
         /**
-         * List Resources
-         * @description List all resources with optional filters
+         * Get cookie consent preferences
+         * @description Returns the current user's cookie consent preferences.
          */
         get: {
-            parameters: {
-                query?: {
-                    offset?: number | null;
-                    limit?: number | null;
-                    entityType?: string;
-                    archived?: "true" | "false" | boolean;
-                    search?: string;
-                    /** @description Search query */
-                    q?: string;
-                };
-                header?: never;
-                path?: never;
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Resources listed successfully */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["ListResourcesResponse"];
-                    };
-                };
-            };
-        };
-        put?: never;
-        /**
-         * Create Resource
-         * @description Create a new resource
-         */
-        post: {
             parameters: {
                 query?: never;
                 header?: never;
                 path?: never;
                 cookie?: never;
             };
-            requestBody: {
-                content: {
-                    "multipart/form-data": {
-                        /** @description Resource name */
-                        name: string;
-                        /**
-                         * Format: binary
-                         * @description Binary content of the resource
-                         */
-                        file: string;
-                        /** @description MIME type (e.g., text/markdown, image/png) */
-                        format: string;
-                        /** @description JSON-encoded array of entity types */
-                        entityTypes?: string;
-                        /** @description ISO 639-1 language code */
-                        language?: string;
-                        /** @description How the resource was created */
-                        creationMethod?: string;
-                        /** @description Source annotation ID (for generated resources) */
-                        sourceAnnotationId?: string;
-                        /** @description Source resource ID (for cloned resources) */
-                        sourceResourceId?: string;
-                    };
-                };
-            };
-            responses: {
-                /** @description Resource creation accepted */
-                202: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            resourceId: string;
-                        };
-                    };
-                };
-            };
-        };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/resources/{id}/annotate-references": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * Annotate References with Progress (SSE)
-         * @description Stream real-time reference annotation progress via Server-Sent Events
-         */
-        post: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: {
-                content: {
-                    "application/json": components["schemas"]["AnnotateReferencesStreamRequest"];
-                };
-            };
+            requestBody?: never;
             responses: {
-                /** @description SSE stream opened successfully */
+                /** @description Current consent preferences */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "text/event-stream": components["schemas"]["EventStreamResponse"];
+                        "application/json": components["schemas"]["CookieConsentResponse"];
                     };
                 };
                 /** @description Authentication required */
@@ -1521,117 +1186,46 @@ interface paths {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
-                };
-                /** @description Resource not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
-                    content?: never;
                 };
             };
         };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/resources/{id}/annotate-highlights": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
         put?: never;
         /**
-         * Annotate Highlights with Progress (SSE)
-         * @description Stream real-time highlight annotation progress via Server-Sent Events
+         * Update cookie consent preferences
+         * @description Update the current user's cookie consent preferences. The `necessary` flag must be true — necessary cookies cannot be disabled.
          */
         post: {
             parameters: {
                 query?: never;
                 header?: never;
-                path: {
-                    id: string;
-                };
+                path?: never;
                 cookie?: never;
             };
-            requestBody?: {
+            requestBody: {
                 content: {
-                    "application/json": components["schemas"]["AnnotateHighlightsStreamRequest"];
+                    "application/json": components["schemas"]["CookieConsentRequest"];
                 };
             };
             responses: {
-                /** @description SSE stream opened successfully */
+                /** @description Consent updated */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "text/event-stream": components["schemas"]["EventStreamResponse"];
-                    };
-                };
-                /** @description Authentication required */
-                401: {
-                    headers: {
-                        [name: string]: unknown;
+                        "application/json": components["schemas"]["CookieConsentResponse"];
                     };
-                    content?: never;
-                };
-                /** @description Resource not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/resources/{id}/annotate-assessments": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * Annotate Assessments with Progress (SSE)
-         * @description Stream real-time assessment annotation progress via Server-Sent Events
-         */
-        post: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: {
-                content: {
-                    "application/json": components["schemas"]["AnnotateAssessmentsStreamRequest"];
                 };
-            };
-            responses: {
-                /** @description SSE stream opened successfully */
-                200: {
+                /** @description Invalid consent data (non-boolean fields, missing fields, or necessary=false) */
+                400: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "text/event-stream": components["schemas"]["EventStreamResponse"];
+                        "application/json": components["schemas"]["CookieConsentResponse"];
                     };
                 };
                 /** @description Authentication required */
@@ -1639,14 +1233,9 @@ interface paths {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
-                };
-                /** @description Resource not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
-                    content?: never;
                 };
             };
         };
@@ -1656,41 +1245,33 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/resources/{id}/annotate-comments": {
+    "/api/cookies/export": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get?: never;
-        put?: never;
         /**
-         * Annotate Comments with Progress (SSE)
-         * @description Stream real-time comment annotation progress via Server-Sent Events
+         * Export cookie data (GDPR)
+         * @description Export the current user's cookie-related data as a downloadable JSON file. Response sets `Content-Disposition: attachment; filename="cookie-data-export-<timestamp>.json"`.
          */
-        post: {
+        get: {
             parameters: {
                 query?: never;
                 header?: never;
-                path: {
-                    id: string;
-                };
+                path?: never;
                 cookie?: never;
             };
-            requestBody?: {
-                content: {
-                    "application/json": components["schemas"]["AnnotateCommentsStreamRequest"];
-                };
-            };
+            requestBody?: never;
             responses: {
-                /** @description SSE stream opened successfully */
+                /** @description User cookie data as attachment */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "text/event-stream": components["schemas"]["EventStreamResponse"];
+                        "application/json": components["schemas"]["CookieExportResponse"];
                     };
                 };
                 /** @description Authentication required */
@@ -1698,786 +1279,21 @@ interface paths {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
-                };
-                /** @description Resource not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
-                    content?: never;
-                };
-            };
-        };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/resources/{id}/annotate-tags": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * Annotate Tags with Progress (SSE)
-         * @description Stream real-time tag annotation progress via Server-Sent Events. Identifies passages serving specific structural roles (IRAC, IMRAD, Toulmin frameworks).
-         */
-        post: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: {
-                content: {
-                    "application/json": components["schemas"]["AnnotateTagsStreamRequest"];
-                };
-            };
-            responses: {
-                /** @description SSE stream opened successfully */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "text/event-stream": components["schemas"]["EventStreamResponse"];
-                    };
-                };
-                /** @description Authentication required */
-                401: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-                /** @description Resource not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/resources/{id}/gather-resource-stream": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * Gather Resource LLM Context (SSE Stream)
-         * @description Stream real-time resource LLM context gathering progress via Server-Sent Events
-         */
-        post: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: {
-                content: {
-                    "application/json": components["schemas"]["GatherResourceStreamRequest"];
-                };
-            };
-            responses: {
-                /** @description SSE stream opened successfully */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "text/event-stream": components["schemas"]["EventStreamResponse"];
-                    };
-                };
-                /** @description Authentication required */
-                401: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-                /** @description Resource not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/resources/{id}/match-search": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * Match Search
-         * @description Submit a match-search command for binding candidates. Returns {correlationId} immediately. Results are delivered asynchronously via the long-lived events-stream as match:search-results or match:search-failed events.
-         */
-        post: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    /** @description Resource ID */
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody: {
-                content: {
-                    "application/json": components["schemas"]["MatchSearchRequest"];
-                };
-            };
-            responses: {
-                /** @description Search command accepted. Results delivered via events-stream. */
-                202: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            correlationId: string;
-                        };
-                    };
-                };
-                /** @description Authentication required */
-                401: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-                /** @description Resource not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/resources/{resourceId}/annotations/{annotationId}/gather": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * Gather Annotation Context
-         * @description Submit a gather-context command for an annotation. Returns {correlationId} immediately. The Gatherer assembles passage + graph context (long-running, involves LLM calls) and delivers results via the events-stream as gather:complete, gather:failed, or gather:annotation-progress events.
-         */
-        post: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    /** @description Resource ID */
-                    resourceId: string;
-                    /** @description Annotation ID */
-                    annotationId: string;
-                };
-                cookie?: never;
-            };
-            requestBody: {
-                content: {
-                    "application/json": components["schemas"]["GatherAnnotationStreamRequest"];
-                };
-            };
-            responses: {
-                /** @description Gather command accepted. Results delivered via events-stream. */
-                202: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            correlationId: string;
-                        };
-                    };
-                };
-                /** @description Authentication required */
-                401: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/resources/{id}/referenced-by": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /**
-         * Get Referenced By
-         * @description Get resources that reference this resource
-         */
-        get: {
-            parameters: {
-                query?: {
-                    /** @description Filter incoming references by W3C motivation type (e.g., 'linking', 'commenting', 'highlighting') */
-                    motivation?: components["schemas"]["Motivation"];
-                };
-                header?: never;
-                path: {
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Resources that reference this resource */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["GetReferencedByResponse"];
-                    };
-                };
-            };
-        };
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/api/clone-tokens/{token}": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /**
-         * Get Resource by Clone Token
-         * @description Retrieve a resource using a clone token
-         */
-        get: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    token: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Resource retrieved successfully */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["GetResourceByTokenResponse"];
-                    };
-                };
-            };
-        };
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/api/clone-tokens/create-resource": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * Create Resource from Clone Token
-         * @description Create a new resource using a clone token
-         */
-        post: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path?: never;
-                cookie?: never;
-            };
-            requestBody?: {
-                content: {
-                    "application/json": components["schemas"]["CreateResourceFromTokenRequest"];
-                };
-            };
-            responses: {
-                /** @description Resource creation accepted */
-                202: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            resourceId: string;
-                        };
-                    };
-                };
-            };
-        };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/resources/{id}/clone-with-token": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * Clone Resource with Token
-         * @description Generate a temporary token for cloning a resource
-         */
-        post: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Clone token generated successfully */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["CloneResourceWithTokenResponse"];
-                    };
-                };
-            };
-        };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/resources/{id}/annotations": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /**
-         * Get Resource Annotations
-         * @description Get all annotations (both highlights and references) in a resource
-         */
-        get: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Resource annotations */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["CreateResourceResponse"];
-                    };
-                };
-            };
-        };
-        put?: never;
-        /**
-         * Create Annotation
-         * @description Create a new annotation/reference in a resource
-         */
-        post: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    /** @description Resource ID */
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: {
-                content: {
-                    "application/json": components["schemas"]["CreateAnnotationRequest"];
-                };
-            };
-            responses: {
-                /** @description Annotation creation accepted */
-                202: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            annotationId: string;
-                        };
-                    };
-                };
-            };
-        };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/resources/{id}/events": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /**
-         * Get Resource Event History
-         * @description Get full event history for a resource with optional filtering
-         */
-        get: {
-            parameters: {
-                query?: {
-                    type?: "resource.created" | "resource.cloned" | "resource.updated" | "resource.moved" | "resource.archived" | "resource.unarchived" | "annotation.added" | "annotation.removed" | "annotation.body.updated" | "entitytag.added" | "entitytag.removed" | "entitytype.added";
-                    userId?: string;
-                    limit?: number;
-                };
-                header?: never;
-                path: {
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Events retrieved successfully */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["GetEventsResponse"];
-                    };
-                };
-            };
-        };
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/resources/{id}/events/stream": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /**
-         * Subscribe to Resource Events (SSE)
-         * @description Open a Server-Sent Events stream to receive real-time resource events
-         */
-        get: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description SSE stream opened successfully */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "text/event-stream": components["schemas"]["EventStreamResponse"];
-                    };
-                };
-            };
-        };
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/resources/{resourceId}/annotations/{annotationId}": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /**
-         * Get Annotation
-         * @description Get a specific annotation from a resource using nested path
-         */
-        get: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    /** @description Resource ID */
-                    resourceId: string;
-                    /** @description Annotation ID */
-                    annotationId: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Annotation retrieved successfully */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["GetAnnotationResponse"];
-                    };
-                };
-                /** @description Annotation not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
                 };
             };
         };
         put?: never;
         post?: never;
-        /**
-         * Delete Annotation
-         * @description Delete an annotation from a resource
-         */
-        delete: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    /** @description Resource ID */
-                    resourceId: string;
-                    /** @description Annotation ID */
-                    annotationId: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Annotation deletion accepted */
-                202: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/resources/{resourceId}/annotations/{annotationId}/body": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        /**
-         * Update Annotation Body
-         * @description Apply fine-grained operations to modify annotation body items (add, remove, or replace TextualBody and SpecificResource items)
-         */
-        put: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    /** @description Resource ID */
-                    resourceId: string;
-                    /** @description Annotation ID */
-                    annotationId: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: {
-                content: {
-                    "application/json": components["schemas"]["UpdateAnnotationBodyRequest"];
-                };
-            };
-            responses: {
-                /** @description Annotation body update accepted */
-                202: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/resources/{resourceId}/annotations/{annotationId}/yield-resource": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * Generate Resource from Annotation
-         * @description Submit a resource generation command. Returns {correlationId, jobId} immediately. The generation worker processes the job asynchronously and delivers progress (yield:progress) and completion (yield:finished) or failure (yield:failed) via the events-stream to all connected clients.
-         */
-        post: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    /** @description Source resource ID */
-                    resourceId: string;
-                    /** @description Reference annotation ID */
-                    annotationId: string;
-                };
-                cookie?: never;
-            };
-            requestBody: {
-                content: {
-                    "application/json": components["schemas"]["YieldResourceStreamRequest"];
-                };
-            };
-            responses: {
-                /** @description Generation command accepted. Progress and results delivered via events-stream. */
-                202: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            correlationId: string;
-                            jobId: string;
-                        };
-                    };
-                };
-                /** @description Context is required for generation */
-                400: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-                /** @description Authentication required */
-                401: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-                /** @description Annotation not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
         delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    "/resources/{resourceId}/annotations/{annotationId}/history": {
+    "/api/tokens/mcp-setup": {
         parameters: {
             query?: never;
             header?: never;
@@ -2485,36 +1301,56 @@ interface paths {
             cookie?: never;
         };
         /**
-         * Get Annotation History
-         * @description Get full event history for a specific annotation (highlight or reference)
+         * MCP Setup (browser-driven CLI handoff)
+         * @description Browser flow that generates a long-lived (30 day) MCP refresh token for the authenticated user and redirects to a localhost callback URL with the token as a query parameter. Used by CLI tooling (similar to Google's OAuth CLI flow).
+         *
+         *     The callback URL must match one of the localhost patterns (`http://localhost:<port>/...`, `http://127.0.0.1:<port>/...`, or `http://[::1]:<port>/...`).
          */
         get: {
             parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    resourceId: string;
-                    annotationId: string;
+                query: {
+                    /** @description Localhost URL to redirect to with `?token=<refresh-token>` on success. */
+                    callback: string;
                 };
+                header?: never;
+                path?: never;
                 cookie?: never;
             };
             requestBody?: never;
             responses: {
-                /** @description Annotation history retrieved successfully */
-                200: {
+                /** @description Redirect to the callback URL with the newly-issued refresh token appended as a `?token=` query parameter. */
+                302: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Missing or non-localhost callback URL */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Authentication required */
+                401: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["GetAnnotationHistoryResponse"];
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description Annotation not found */
-                404: {
+                /** @description Failed to generate refresh token */
+                500: {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
             };
         };
@@ -2526,7 +1362,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/entity-types": {
+    "/bus/subscribe": {
         parameters: {
             query?: never;
             header?: never;
@@ -2534,56 +1370,52 @@ interface paths {
             cookie?: never;
         };
         /**
-         * Get Entity Types
-         * @description Get list of available entity types for references
+         * Subscribe to the Semiont event bus (SSE)
+         * @description Opens a long-lived Server-Sent Events stream over which the bus delivers events matching the requested channels and scopes.
+         *
+         *     Each SSE frame has `event: bus-event`, a JSON-encoded `data` of the form `{ channel, payload, scope? }`, and an `id` (either a persisted event id, `scope:seq`, for domain events; or an ephemeral id for job-lifecycle / result channels).
+         *
+         *     Pass the last-received id as `Last-Event-ID` to resume — the server replays missed persisted events and emits a `bus:resume-gap` synthetic event when the gap exceeds the replay window.
          */
         get: {
             parameters: {
-                query?: never;
-                header?: never;
+                query?: {
+                    /** @description Unscoped channels to subscribe to. Repeat the parameter for multiple channels. At least one of `channel` or `scoped` is required. */
+                    channel?: string[];
+                    /** @description Resource-scoped channels to subscribe to (requires `scope`). Repeat for multiple. */
+                    scoped?: string[];
+                    /** @description Resource scope for scoped channels (typically a resourceId). */
+                    scope?: string;
+                };
+                header?: {
+                    /** @description Id of the last event the client received. On reconnect, the server replays persisted events after this id and emits `bus:resume-gap` if the gap exceeds the replay cap. */
+                    "Last-Event-ID"?: string;
+                };
                 path?: never;
                 cookie?: never;
             };
             requestBody?: never;
             responses: {
-                /** @description Entity types retrieved successfully */
+                /** @description SSE stream opened */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["GetEntityTypesResponse"];
+                        "text/event-stream": components["schemas"]["EventStreamResponse"];
                     };
                 };
-            };
-        };
-        put?: never;
-        /**
-         * Add Entity Type
-         * @description Add a new entity type to the collection (append-only, requires moderator/admin)
-         */
-        post: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path?: never;
-                cookie?: never;
-            };
-            requestBody?: {
-                content: {
-                    "application/json": components["schemas"]["AddEntityTypeRequest"];
-                };
-            };
-            responses: {
-                /** @description Entity type addition accepted */
-                202: {
+                /** @description No channels requested (at least one `channel` or `scoped` parameter required) */
+                400: {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
-                /** @description Forbidden - Moderator or Admin access required */
-                403: {
+                /** @description Authentication required */
+                401: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -2593,13 +1425,15 @@ interface paths {
                 };
             };
         };
+        put?: never;
+        post?: never;
         delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    "/api/entity-types/bulk": {
+    "/bus/emit": {
         parameters: {
             query?: never;
             header?: never;
@@ -2609,8 +1443,12 @@ interface paths {
         get?: never;
         put?: never;
         /**
-         * Bulk Add Entity Types
-         * @description Add multiple entity types to the collection (append-only, requires moderator/admin)
+         * Emit an event on the Semiont bus
+         * @description Publishes an event to the bus. The channel name must be registered in `bus-protocol.ts` (`EventMap`); the payload is validated against the channel's schema in `CHANNEL_SCHEMAS` when one is registered.
+         *
+         *     When `scope` is set, the event publishes on `eventBus.scope(scope)` rather than the global bus, routing it to per-resource SSE subscribers only. The authenticated user's DID is attached to the payload as `_userId` automatically.
+         *
+         *     Returns 202 Accepted — the event is delivered to in-memory subscribers synchronously, but downstream persistence (Stower) and materialization happen asynchronously.
          */
         post: {
             parameters: {
@@ -2619,21 +1457,30 @@ interface paths {
                 path?: never;
                 cookie?: never;
             };
-            requestBody?: {
+            requestBody: {
                 content: {
-                    "application/json": components["schemas"]["BulkAddEntityTypesRequest"];
+                    "application/json": components["schemas"]["BusEmitRequest"];
                 };
             };
             responses: {
-                /** @description Entity types addition accepted */
+                /** @description Event accepted and published to subscribers */
                 202: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content?: never;
                 };
-                /** @description Forbidden - Moderator or Admin access required */
-                403: {
+                /** @description Missing/invalid channel, payload, or scope; or payload failed schema validation for the channel */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Authentication required */
+                401: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -2649,46 +1496,98 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/events/stream": {
+    "/resources": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
+        get?: never;
+        put?: never;
         /**
-         * Subscribe to Global Events (SSE)
-         * @description Open a Server-Sent Events stream to receive real-time system-level events (e.g., entity type changes). Events not scoped to a specific resource are delivered on this channel.
+         * Create a resource
+         * @description Upload binary content + metadata as multipart/form-data. The backend writes content to disk, then emits yield:create on the bus; Stower persists it and returns a 202 with the new resourceId. Full reconciliation happens via SSE domain events (yield:created).
+         *
+         *     Generation workers and the /know/compose page both hit this route — bytes always travel on the HTTP wire, never on the bus.
          */
-        get: {
+        post: {
             parameters: {
                 query?: never;
                 header?: never;
                 path?: never;
                 cookie?: never;
             };
-            requestBody?: never;
+            requestBody: {
+                content: {
+                    "multipart/form-data": {
+                        /** @description Human-readable resource name */
+                        name: string;
+                        /**
+                         * Format: binary
+                         * @description Binary content
+                         */
+                        file: string;
+                        /** @description Media type of the content (e.g. text/plain, text/markdown, image/png) */
+                        format: string;
+                        /** @description Where the content has been / should be placed (file://... for local). If omitted, derived from name + format. */
+                        storageUri?: string;
+                        /** @description ISO 639-1 language code */
+                        language?: string;
+                        /** @description JSON-stringified array of entity type names */
+                        entityTypes?: string;
+                        /** @description How this resource was created (api, ui, upload, reference, cli, clone, generated) */
+                        creationMethod?: string;
+                        /** @description For AI-generated resources: the annotation that triggered generation. Nested into generatedFrom.annotationId on the persisted event. */
+                        sourceAnnotationId?: string;
+                        /** @description For AI-generated resources: the source resource the generating annotation lives on. Nested into generatedFrom.resourceId on the persisted event. */
+                        sourceResourceId?: string;
+                        /** @description For AI-generated resources: the prompt that drove generation */
+                        generationPrompt?: string;
+                        /** @description For AI-generated resources: JSON-stringified Agent (single object or array), capturing which model/worker produced the content */
+                        generator?: string;
+                        /** @description 'true' or 'false' — whether the resource is a draft */
+                        isDraft?: string;
+                    };
+                };
+            };
             responses: {
-                /** @description SSE stream opened successfully */
-                200: {
+                /** @description Resource accepted for creation */
+                202: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "text/event-stream": components["schemas"]["EventStreamResponse"];
+                        "application/json": components["schemas"]["CreateResourceResponse"];
+                    };
+                };
+                /** @description Missing required fields (name, file, or format) */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Authentication required */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
             };
         };
-        put?: never;
-        post?: never;
         delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    "/api/jobs/{id}": {
+    "/resources/{id}": {
         parameters: {
             query?: never;
             header?: never;
@@ -2696,13 +1595,20 @@ interface paths {
             cookie?: never;
         };
         /**
-         * Get Job Status
-         * @description Get the current status and progress of an async job
+         * Get a resource (content-negotiated)
+         * @description Content negotiation via the Accept header:
+         *     - application/ld+json (default) — returns JSON-LD metadata including all annotations + inbound entity references
+         *     - text/* or image/* or application/pdf — returns the raw representation bytes
+         *
+         *     Binary payloads flow directly from the content store; metadata payloads go through the bus gateway.
          */
         get: {
             parameters: {
                 query?: never;
-                header?: never;
+                header?: {
+                    /** @description application/ld+json for metadata, or a text/image/pdf media type for raw content */
+                    Accept?: string;
+                };
                 path: {
                     id: string;
                 };
@@ -2710,21 +1616,46 @@ interface paths {
             };
             requestBody?: never;
             responses: {
-                /** @description Job status retrieved successfully */
+                /** @description Resource content or metadata, depending on Accept */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["JobStatusResponse"];
+                        "application/ld+json": components["schemas"]["GetResourceResponse"];
+                        "text/plain": string;
+                        "text/markdown": string;
+                        "text/html": string;
+                        "image/*": string;
+                        "application/pdf": string;
                     };
                 };
-                /** @description Job not found */
+                /** @description Resource not found */
                 404: {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Failed to retrieve resource */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Request timed out (bus gateway) */
+                504: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
             };
         };
@@ -2733,95 +1664,55 @@ interface paths {
         delete?: never;
         options?: never;
         head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/api/participants/{id}/attention": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
         /**
-         * Beckon Participant
-         * @description Direct a participant's attention to a resource or annotation. Produces no persistent annotations — attention signal only. The participant may be a human username or an agent identifier.
+         * Update resource metadata
+         * @description Archive/unarchive or update entity types. Emits mark:archive / mark:unarchive / mark:update-entity-types on the bus; returns 202 immediately. Frontend reconciles state via SSE domain events.
          */
-        post: {
+        patch: {
             parameters: {
                 query?: never;
                 header?: never;
                 path: {
-                    /** @description Participant username or agent identifier */
                     id: string;
                 };
                 cookie?: never;
             };
             requestBody: {
                 content: {
-                    "application/json": components["schemas"]["BeckonRequest"];
+                    "application/json": components["schemas"]["UpdateResourceRequest"];
                 };
             };
             responses: {
-                /** @description Attention signal accepted */
+                /** @description Update accepted */
                 202: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Authentication required */
+                401: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["BeckonResponse"];
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-            };
-        };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/api/participants/me/attention-stream": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /**
-         * Participant Attention Stream
-         * @description Open a persistent SSE connection to receive beckon signals directed at the authenticated participant. Signals are ephemeral — delivered if connected, dropped if not. No queue, no replay.
-         */
-        get: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path?: never;
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description SSE stream of beckon:focus events */
-                200: {
+                /** @description Resource not found */
+                404: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "text/event-stream": string;
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
             };
         };
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
         trace?: never;
     };
-    "/api/browse/files": {
+    "/api/resources/{id}": {
         parameters: {
             query?: never;
             header?: never;
@@ -2829,34 +1720,37 @@ interface paths {
             cookie?: never;
         };
         /**
-         * Browse project directory
-         * @description List files and directories in a project directory, merged with Knowledge Base metadata for tracked resources.
+         * Get raw resource content (browser-friendly alias)
+         * @description Browser-friendly alternative to GET /resources/{id} that always returns the raw representation, never JSON-LD. Used by `<img>` / PDF.js / `<video>` tags and anywhere an httpOnly cookie is the only feasible auth vector. Behaves like GET /resources/{id} with JSON-LD stripped from the Accept header before content negotiation.
+         *
+         *     Sets long-lived immutable Cache-Control (content is addressed by checksum upstream, so bytes never change for a given resource id).
          */
         get: {
             parameters: {
-                query?: {
-                    /** @description Directory path relative to project root. Empty string or omit for project root. */
-                    path?: string;
-                    /** @description Sort order for directory entries. */
-                    sort?: "name" | "mtime" | "annotationCount";
-                };
+                query?: never;
                 header?: never;
-                path?: never;
+                path: {
+                    id: string;
+                };
                 cookie?: never;
             };
             requestBody?: never;
             responses: {
-                /** @description Directory listing with KB metadata merged */
+                /** @description Raw representation bytes with appropriate Content-Type */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["BrowseFilesResponse"];
+                        "text/plain": string;
+                        "text/markdown": string;
+                        "text/html": string;
+                        "image/*": string;
+                        "application/pdf": string;
                     };
                 };
-                /** @description Invalid path (e.g. path escapes project root) */
-                400: {
+                /** @description Resource or representation not found */
+                404: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -2864,8 +1758,8 @@ interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description Directory not found */
-                404: {
+                /** @description Failed to retrieve resource */
+                500: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -2890,9 +1784,6 @@ interface components {
             success: boolean;
             message: string;
         };
-        AddEntityTypeRequest: {
-            tag: string;
-        };
         AdminUpdateUserResponse: {
             success: boolean;
             user: {
@@ -2978,8 +1869,8 @@ interface components {
             motivation: components["schemas"]["Motivation"];
             /** @description W3C Web Annotation target - can be a simple IRI string (entire resource) or an object with source and optional selector (fragment) */
             target: string | components["schemas"]["AnnotationTarget"];
-            /** @description W3C Web Annotation body - can be empty array, single body, or array of bodies */
-            body: components["schemas"]["AnnotationBody"][] | components["schemas"]["AnnotationBody"] | components["schemas"]["AnnotationBody"][];
+            /** @description W3C Web Annotation body. Optional per the W3C spec — annotations whose motivation alone is meaningful (highlighting) legitimately omit it. Present values are either a single body or a non-empty array of bodies; the prior empty-array 'stub' branch has been removed (it was a naming lie shared between highlights and never-actually-emitted stub references, and the source of the #651 reference-annotation validator bug). */
+            body?: components["schemas"]["AnnotationBody"] | components["schemas"]["AnnotationBody"][];
             creator?: components["schemas"]["Agent"];
             created?: string;
             modified?: string;
@@ -3026,14 +1917,6 @@ interface components {
             /** @description Optional selector to identify a specific segment of the source resource */
             selector?: components["schemas"]["TextPositionSelector"] | components["schemas"]["TextQuoteSelector"] | components["schemas"]["SvgSelector"] | components["schemas"]["FragmentSelector"] | (components["schemas"]["TextPositionSelector"] | components["schemas"]["TextQuoteSelector"] | components["schemas"]["SvgSelector"] | components["schemas"]["FragmentSelector"])[];
         };
-        AsyncJobResponse: {
-            jobId: string;
-            /** @enum {string} */
-            status: "pending" | "running" | "complete" | "failed" | "cancelled";
-            /** @enum {string} */
-            type: "reference-annotation" | "generation";
-            created: string;
-        };
         AuthResponse: {
             success: boolean;
             user: {
@@ -3055,6 +1938,53 @@ interface components {
             path: string;
             entries: components["schemas"]["DirectoryEntry"][];
         };
+        /** @description Emit an event on the Semiont bus. Channel names come from bus-protocol.ts; payload shape is validated against the channel's registered schema (CHANNEL_SCHEMAS). An optional scope routes resource-scoped broadcasts (e.g. mark:added, job:complete) to per-resource subscribers via eventBus.scope(scope); leave it unset for unscoped/global events. */
+        BusEmitRequest: {
+            /** @description Channel name from bus-protocol.ts EventMap */
+            channel: string;
+            /** @description Channel-specific payload, validated against CHANNEL_SCHEMAS */
+            payload: {
+                [key: string]: unknown;
+            };
+            /** @description Optional resource scope for broadcast channels (e.g. resourceId). Publishers only — frontends must never set this. */
+            scope?: string;
+        };
+        /** @description User's cookie consent preferences. `necessary` is always true — necessary cookies cannot be disabled. Timestamps and version are stamped server-side. */
+        CookieConsent: {
+            /** @enum {boolean} */
+            necessary: true;
+            analytics: boolean;
+            marketing: boolean;
+            preferences: boolean;
+            /** Format: date-time */
+            timestamp: string;
+            version: string;
+        };
+        /** @description Request body for POST /api/cookies/consent. All four preference fields must be booleans; `necessary` must be true. */
+        CookieConsentRequest: {
+            /** @enum {boolean} */
+            necessary: true;
+            analytics: boolean;
+            marketing: boolean;
+            preferences: boolean;
+        };
+        /** @description Standard envelope for cookie consent endpoints. On success `success: true` and `consent` carries the current preferences; on error `success: false` and `error` carries a human-readable message. */
+        CookieConsentResponse: {
+            success: boolean;
+            consent?: components["schemas"]["CookieConsent"];
+            error?: string;
+        };
+        /** @description GDPR data export of a user's cookie-related data. The response is returned as a file download (Content-Disposition: attachment). */
+        CookieExportResponse: {
+            user: {
+                id: string;
+                email: string;
+            };
+            consent: components["schemas"]["CookieConsent"];
+            /** Format: date-time */
+            exportDate: string;
+            dataRetentionPolicy: string;
+        };
         DirectoryEntry: components["schemas"]["FileEntry"] | components["schemas"]["DirEntry"];
         FileEntry: {
             /** @enum {string} */
@@ -3106,22 +2036,9 @@ interface components {
         };
         BodyOperationReplace: {
             /** @enum {string} */
-            op: "replace";
-            oldItem: components["schemas"]["TextualBody"] | components["schemas"]["SpecificResource"];
-            newItem: components["schemas"]["TextualBody"] | components["schemas"]["SpecificResource"];
-        };
-        /**
-         * @description Annotation body type - TextualBody for textual content, SpecificResource for resource links
-         * @enum {string}
-         */
-        BodyType: "TextualBody" | "SpecificResource";
-        BeckonRequest: {
-            /** @description Resource to direct attention at */
-            resourceId: string;
-            /** @description Specific annotation within the resource (optional) */
-            annotationId?: string;
-            /** @description Human-readable context for the participant (max 500 chars) */
-            message?: string;
+            op: "replace";
+            oldItem: components["schemas"]["TextualBody"] | components["schemas"]["SpecificResource"];
+            newItem: components["schemas"]["TextualBody"] | components["schemas"]["SpecificResource"];
         };
         BeckonResponse: {
             /** @description Username or agent identifier that was beckoned */
@@ -3131,9 +2048,6 @@ interface components {
             /** @description Annotation the attention was directed at (if provided) */
             annotationId?: string;
         };
-        BulkAddEntityTypesRequest: {
-            tags: string[];
-        };
         CloneResourceWithTokenResponse: {
             /** @description Generated clone token */
             token: string;
@@ -3143,6 +2057,8 @@ interface components {
         };
         /** @description Error response for failed bus commands. Replaces native Error objects on the EventBus so payloads are serializable and OpenAPI-typed. */
         CommandError: {
+            /** @description Optional correlation id echoed from the originating command. When present, the failure event can be matched back to the specific command that failed. */
+            correlationId?: string;
             /** @description Human-readable error message */
             message: string;
             /** @description Optional additional context (stack trace, field name, etc.) */
@@ -3182,114 +2098,18 @@ interface components {
                     suffix?: string;
                 } | components["schemas"]["SvgSelector"] | components["schemas"]["FragmentSelector"])[];
             };
-            body: unknown[] | components["schemas"]["AnnotationBody"] | components["schemas"]["AnnotationBody"][];
-        };
-        CreateFromAnnotationRequest: {
-            /** @description ID of the resource containing the annotation */
-            resourceId: string;
-            name: string;
-            content: string;
-            format: components["schemas"]["ContentFormat"];
-        };
-        CreateFromAnnotationResponse: {
-            resource: components["schemas"]["ResourceDescriptor"];
-            annotations: components["schemas"]["Annotation"][];
-        };
-        CreateJobResponse: {
-            jobId: string;
-            /** @enum {string} */
-            type: "reference-annotation" | "generation";
-            /** @enum {string} */
-            status: "pending" | "running" | "complete" | "failed" | "cancelled";
-            created: string;
-            resourceId?: string;
-        };
-        CreateResourceFromAnnotationResponse: {
-            resource: components["schemas"]["ResourceDescriptor"];
-            annotation: components["schemas"]["Annotation"];
-        };
-        CreateResourceFromSelectionRequest: {
-            /** @description ID of the resource containing the annotation */
-            resourceId: string;
-            content: string;
-            name: string;
-            format: components["schemas"]["ContentFormat"];
-            entityTypes?: string[];
-            metadata?: {
-                [key: string]: unknown;
-            };
-            prompt?: string;
-            language?: string;
-        };
-        CreateResourceFromSelectionResponse: {
-            resource: components["schemas"]["ResourceDescriptor"];
-            annotation: components["schemas"]["Annotation"];
-        };
-        CreateResourceFromTokenRequest: {
-            /** @description Clone token */
-            token: string;
-            /** @description Name for the new resource */
-            name: string;
-            /** @description Content for the new resource */
-            content: string;
-            /** @description Whether to archive the original resource */
-            archiveOriginal?: boolean;
-        };
-        CreateResourceRequest: {
-            name: string;
-            content: string;
-            format: components["schemas"]["ContentFormat"];
-            entityTypes: string[];
-            language?: string;
-            creationMethod?: string;
-            sourceAnnotationId?: string;
-            sourceResourceId?: string;
+            /** @description Optional body. Omit for annotations whose motivation alone is meaningful (highlighting) or whose user-supplied content is empty. Shape matches Annotation.body. */
+            body?: components["schemas"]["AnnotationBody"] | components["schemas"]["AnnotationBody"][];
         };
+        /** @description Response body for POST /resources (202 Accepted). Resource creation is asynchronous — the backend writes content to disk, emits yield:create on the bus, and returns the newly-minted resourceId immediately. Consumers watch SSE domain events (yield:created) to observe the fully-persisted state. */
         CreateResourceResponse: {
-            resource: components["schemas"]["ResourceDescriptor"];
-            annotations: components["schemas"]["Annotation"][];
-        };
-        DeleteAnnotationRequest: {
-            /**
-             * Format: uri
-             * @description Resource URI containing the annotation (required for O(1) Layer 3 lookup)
-             */
+            /** @description The id of the newly-created resource. Assigned by Stower when it persists yield:create. */
             resourceId: string;
         };
         DeleteUserResponse: {
             success: boolean;
             message: string;
         };
-        AnnotateReferencesStreamRequest: {
-            /** @description Entity types to annotate (e.g., 'Person', 'Organization', 'Location') */
-            entityTypes: string[];
-            /** @description Include anaphoric/cataphoric references (e.g., 'the CEO', 'the tech giant') in addition to direct mentions */
-            includeDescriptiveReferences?: boolean;
-        };
-        GatherResourceStreamRequest: {
-            /** @description Client-generated correlation ID to thread the response back to the originating request */
-            correlationId?: string;
-            /** @description Graph traversal depth (default: 2) */
-            depth?: number;
-            /** @description Maximum related resources to include (default: 10) */
-            maxResources?: number;
-            /** @description Include full resource content (default: true) */
-            includeContent?: boolean;
-            /** @description Include AI-generated summary (default: false) */
-            includeSummary?: boolean;
-        };
-        GatherAnnotationStreamRequest: {
-            /** @description Client-generated correlation ID to thread the response back to the originating request */
-            correlationId?: string;
-            /** @description Characters of surrounding text context (default: 1000) */
-            contextWindow?: number;
-        };
-        BindAnnotationStreamRequest: {
-            /** @description Resource ID containing the annotation (required for O(1) Layer 3 lookup) */
-            resourceId: string;
-            /** @description Array of body modification operations to apply */
-            operations: (components["schemas"]["BodyOperationAdd"] | components["schemas"]["BodyOperationRemove"] | components["schemas"]["BodyOperationReplace"])[];
-        };
         /** @description Progress payload emitted on gather:annotation-progress and gather:progress SSE channels during LLM context gathering. */
         GatherProgress: {
             message?: string;
@@ -3307,63 +2127,6 @@ interface components {
             resourceId: string;
             response: components["schemas"]["ResourceLLMContextResponse"];
         };
-        /** @description Progress state for mark (annotation) workflows. Supports both entity-type-step and percentage-based progress strategies. Emitted on mark:progress SSE channel. */
-        MarkProgress: {
-            /** @description Echoes the correlationId from the originating mark:assist-request command, if any. Lets clients match progress events back to the operation that initiated them. */
-            correlationId?: string;
-            /** @description Current status of the annotation workflow */
-            status: string;
-            /** @description Human-readable status message */
-            message?: string;
-            /** @description Resource being annotated */
-            resourceId?: string;
-            /** @description Reference annotation: currently scanning entity type */
-            currentEntityType?: string;
-            /** @description Reference annotation: completed entity types with counts */
-            completedEntityTypes?: {
-                entityType: string;
-                foundCount: number;
-            }[];
-            /** @description Percentage-based motivations (highlight, assessment, comment, tag) */
-            percentage?: number;
-            /** @description Category-based motivations (tag): current category */
-            currentCategory?: string;
-            /** @description Category-based motivations (tag): number processed */
-            processedCategories?: number;
-            /** @description Category-based motivations (tag): total categories */
-            totalCategories?: number;
-            /** @description Request parameters for display in progress UI */
-            requestParams?: {
-                label: string;
-                value: string;
-            }[];
-        };
-        /** @description Completion payload emitted on mark:assist-finished SSE channel when AI-assisted annotation completes. */
-        MarkAssistFinished: {
-            /** @description Echoes the correlationId from the originating mark:assist-request command, if any. */
-            correlationId?: string;
-            motivation?: components["schemas"]["Motivation"];
-            resourceId?: string;
-            status?: string;
-            percentage?: number;
-            /** @description Number of annotations found/created */
-            foundCount?: number;
-            /** @description Number of annotations actually created */
-            createdCount?: number;
-            /** @description Counts by category (for tag annotations) */
-            byCategory?: {
-                [key: string]: number;
-            };
-            message?: string;
-            progress?: components["schemas"]["MarkProgress"];
-        };
-        /** @description Error payload emitted on mark:assist-failed SSE channel when AI-assisted annotation fails. */
-        MarkAssistFailed: {
-            /** @description Echoes the correlationId from the originating mark:assist-request command, if any. */
-            correlationId?: string;
-            resourceId?: string;
-            message?: string;
-        };
         /** @description Search results payload emitted on match:search-results SSE channel. */
         MatchSearchResult: {
             correlationId: string;
@@ -3381,36 +2144,6 @@ interface components {
             referenceId: string;
             error: string;
         };
-        /** @description Progress state for resource yield (generation) workflow. Emitted as SSE events on yield:progress and yield:finished channels. */
-        YieldProgress: {
-            /** @description Echoes the correlationId from the originating yield:request command, if any. Lets clients match progress events back to the operation that initiated them. */
-            correlationId?: string;
-            /** @enum {string} */
-            status: "started" | "fetching" | "generating" | "creating" | "complete" | "error";
-            /** @description ID of the reference annotation that triggered generation */
-            referenceId: string;
-            /** @description Name of the resource being generated */
-            resourceName?: string;
-            /** @description ID of the generated resource (available after creation) */
-            resourceId?: string;
-            /** @description ID of the source resource containing the reference */
-            sourceResourceId?: string;
-            /** @description Progress percentage (0-100) */
-            percentage: number;
-            /** @description Human-readable status message */
-            message?: string;
-        };
-        /** @description Error payload emitted on yield:failed SSE channel when resource generation fails. */
-        YieldStreamError: {
-            /** @description Echoes the correlationId from the originating yield:request command, if any. */
-            correlationId?: string;
-            /** @description Error message */
-            error?: string;
-            status?: string;
-            referenceId?: string;
-            percentage?: number;
-            message?: string;
-        };
         /** @description Metadata added at persistence time. Part of every StoredEvent. Integrity is provided by git at the commit level (when gitSync is enabled), not by in-event metadata fields. */
         EventMetadata: {
             /** @description Monotonic position in the event log (ordering authority) */
@@ -3560,6 +2293,8 @@ interface components {
         JobStartedPayload: {
             jobId: string;
             jobType: components["schemas"]["JobType"];
+            /** @description Annotation this job is attached to, when applicable */
+            annotationId?: string;
             totalSteps?: number;
         };
         /** @description Payload for job:progress domain event */
@@ -3583,6 +2318,8 @@ interface components {
         JobCompletedPayload: {
             jobId: string;
             jobType: components["schemas"]["JobType"];
+            /** @description Annotation this job was attached to, when applicable */
+            annotationId?: string;
             totalSteps?: number;
             /** @description For detection: total entities found */
             foundCount?: number;
@@ -3600,47 +2337,11 @@ interface components {
         JobFailedPayload: {
             jobId: string;
             jobType: components["schemas"]["JobType"];
+            /** @description Annotation this job was attached to, when applicable */
+            annotationId?: string;
             error: string;
             details?: string;
         };
-        AnnotateHighlightsStreamRequest: {
-            /** @description Optional instructions to guide AI highlight annotation */
-            instructions?: string;
-            /** @description Optional density: desired number of highlights per 2000 words of text (1-15) */
-            density?: number;
-        };
-        AnnotateAssessmentsStreamRequest: {
-            /** @description Optional instructions to guide AI assessment annotation */
-            instructions?: string;
-            /**
-             * @description Optional tone/style for generated assessments
-             * @enum {string}
-             */
-            tone?: "analytical" | "critical" | "balanced" | "constructive";
-            /** @description Optional density: desired number of assessments per 2000 words of text (1-10) */
-            density?: number;
-            /** @description BCP 47 language tag for the generated assessment text (e.g. "en", "fr", "de") */
-            language?: string;
-        };
-        AnnotateCommentsStreamRequest: {
-            /** @description Optional instructions to guide AI comment annotation */
-            instructions?: string;
-            /**
-             * @description Optional tone/style for generated comments
-             * @enum {string}
-             */
-            tone?: "scholarly" | "explanatory" | "conversational" | "technical";
-            /** @description Optional density: desired number of comments per 2000 words of text (2-12) */
-            density?: number;
-            /** @description BCP 47 language tag for the generated comment text (e.g. 'en', 'fr', 'de') */
-            language?: string;
-        };
-        AnnotateTagsStreamRequest: {
-            /** @description Tag schema ID (e.g., 'legal-irac', 'scientific-imrad', 'argument-toulmin') */
-            schemaId: string;
-            /** @description Categories to annotate from the selected schema (e.g., ['Issue', 'Rule', 'Application', 'Conclusion']) */
-            categories: string[];
-        };
         ErrorResponse: {
             error: string;
             code?: string;
@@ -3651,47 +2352,6 @@ interface components {
             data: string;
             id?: string;
         };
-        YieldResourceFromAnnotationRequest: {
-            /** @description Optional name for the generated resource */
-            name?: string;
-            /** @description Entity types for the generated resource */
-            entityTypes?: string[];
-            /** @description Optional AI prompt for generation */
-            prompt?: string;
-            /** @description Language code (e.g., 'en', 'es') */
-            language?: string;
-        };
-        YieldResourceFromAnnotationResponse: {
-            resource: components["schemas"]["ResourceDescriptor"];
-            annotation: components["schemas"]["Annotation"];
-            generated: boolean;
-        };
-        YieldResourceRequest: {
-            /** @description Resource ID containing the annotation */
-            resourceId: string;
-            /** @description Custom title for generated resource */
-            title?: string;
-            /** @description Custom prompt for content generation */
-            prompt?: string;
-            /** @description Language locale (e.g., "es", "fr", "ja") */
-            language?: string;
-        };
-        YieldResourceStreamRequest: {
-            /** @description Custom title for generated resource */
-            title?: string;
-            /** @description Custom prompt for content generation */
-            prompt?: string;
-            /** @description Language locale for generated content (e.g., "es", "fr", "ja") */
-            language?: string;
-            /** @description Gathered context including source document excerpts, metadata, and graph context */
-            context: components["schemas"]["GatheredContext"];
-            /** @description Inference temperature (0.0 = focused, 1.0 = creative) */
-            temperature?: number;
-            /** @description Maximum tokens to generate */
-            maxTokens?: number;
-            /** @description file://-relative URI where the generated resource will be saved (e.g. file://generated/overview.md) */
-            storageUri: string;
-        };
         GetAnnotationHistoryResponse: {
             events: components["schemas"]["StoredEventResponse"][];
             total: number;
@@ -3772,12 +2432,6 @@ interface components {
             progress?: unknown;
             result?: unknown;
         };
-        ListAnnotationsResponse: {
-            annotations: components["schemas"]["Annotation"][];
-            total: number;
-            offset: number;
-            limit: number;
-        };
         ListResourcesResponse: {
             resources: components["schemas"]["ResourceDescriptor"][];
             total: number;
@@ -3852,14 +2506,6 @@ interface components {
         } & {
             [key: string]: unknown;
         };
-        BindAnnotationRequest: {
-            /** @description Target resource ID to resolve reference to */
-            resourceId: string;
-        };
-        BindAnnotationResponse: {
-            annotation: components["schemas"]["Annotation"];
-            targetResource?: components["schemas"]["ResourceDescriptor"] | null;
-        };
         /** @description Metadata about a resource (1:1 with its URI). JSON-LD subject is @id. Link to concrete bytes via representations. */
         ResourceDescriptor: {
             /** @description JSON-LD context; URI, object, or array of these. */
@@ -4098,8 +2744,10 @@ interface components {
         BeckonSparkleEvent: {
             annotationId: string;
         };
-        /** @description Event payload emitted on the bind:body-updated bus channel after annotation bodies are modified. */
+        /** @description Success result emitted on the bind:body-updated bus channel after bind:update-body has been applied. */
         BindBodyUpdated: {
+            /** @description Correlation ID echoed from the originating bind:update-body command */
+            correlationId: string;
             /** @description Branded AnnotationId of the annotation whose body was updated */
             annotationId: string;
         };
@@ -4166,6 +2814,14 @@ interface components {
             correlationId: string;
             response: components["schemas"]["GetAnnotationResponse"];
         };
+        /** @description Request to get contextual text around an annotation */
+        BrowseAnnotationContextRequest: {
+            correlationId: string;
+            annotationId: string;
+            resourceId: string;
+            contextBefore?: number;
+            contextAfter?: number;
+        };
         /** @description Request to browse annotations for a resource */
         BrowseAnnotationsRequest: {
             correlationId: string;
@@ -4319,7 +2975,7 @@ interface components {
             /** @description The gathered annotation context */
             response: components["schemas"]["AnnotationLLMContextResponse"];
         };
-        /** @description Request payload sent on the gather:annotation-request bus channel to gather context for an annotation. */
+        /** @description Request payload sent on the gather:requested bus channel to gather context for an annotation. */
         GatherAnnotationRequest: {
             /** @description Client-generated correlation ID to thread the response back to the originating request */
             correlationId: string;
@@ -4407,7 +3063,7 @@ interface components {
             /** @description The gathered resource context */
             response: components["schemas"]["ResourceLLMContextResponse"];
         };
-        /** @description Request payload sent on the gather:resource-request bus channel to gather context for a resource. */
+        /** @description Request payload sent on the gather:resource-requested bus channel to gather context for a resource. */
         GatherResourceRequest: {
             /** @description Client-generated correlation ID to thread the response back to the originating request */
             correlationId: string;
@@ -4425,6 +3081,12 @@ interface components {
                 includeSummary: boolean;
             };
         };
+        /** @description Request to generate an AI summary of an annotation */
+        GatherSummaryRequest: {
+            correlationId: string;
+            annotationId: string;
+            resourceId: string;
+        };
         /** @description Result of a completed assessment-annotation job. */
         JobAssessmentAnnotationResult: {
             assessmentsFound: number;
@@ -4435,6 +3097,28 @@ interface components {
             /** @enum {string} */
             jobType: "annotation" | "generation";
         };
+        /** @description Command to claim a pending job (atomic CAS: pending → running) */
+        JobClaimCommand: {
+            correlationId: string;
+            jobId: string;
+        };
+        /** @description Command to create a new job via the event bus */
+        JobCreateCommand: {
+            correlationId: string;
+            /** @enum {string} */
+            jobType: "reference-annotation" | "highlight-annotation" | "assessment-annotation" | "comment-annotation" | "tag-annotation" | "generation";
+            resourceId: string;
+            params: {
+                [key: string]: unknown;
+            };
+        };
+        /** @description Result of a job:create command */
+        JobCreatedResult: {
+            correlationId: string;
+            response: {
+                jobId: string;
+            };
+        };
         /** @description Result of a completed comment-annotation job. */
         JobCommentAnnotationResult: {
             commentsFound: number;
@@ -4446,6 +3130,8 @@ interface components {
             userId: string;
             jobId: string;
             jobType: components["schemas"]["JobType"];
+            /** @description Annotation this job is attached to, when applicable. Lets the UI route completion feedback (toast, resolve state) to a specific annotation. */
+            annotationId?: string;
             result?: components["schemas"]["JobResult"];
         };
         /** @description Command to mark a job as failed */
@@ -4454,12 +3140,14 @@ interface components {
             userId: string;
             jobId: string;
             jobType: components["schemas"]["JobType"];
+            /** @description Annotation this job is attached to, when applicable. Lets the UI route failure feedback (error toast, revert state) to a specific annotation. */
+            annotationId?: string;
             error: string;
         };
-        /** @description Result of a completed generation job. */
+        /** @description Result of a completed generation job. resourceId is assigned by Stower when yield:create is processed; the worker emits job:complete with only resourceName, and Stower populates resourceId on the persisted payload. */
         JobGenerationResult: {
-            /** @description ID of the generated resource */
-            resourceId: string;
+            /** @description ID of the generated resource (populated by Stower, not by the worker) */
+            resourceId?: string;
             /** @description Name of the generated resource */
             resourceName: string;
         };
@@ -4468,14 +3156,16 @@ interface components {
             highlightsFound: number;
             highlightsCreated: number;
         };
-        /** @description Progress report from a running job. Common fields are stage/percentage/message; job-type-specific fields may also be present. */
+        /** @description Progress report from a running job. Common fields are stage/percentage/message; job-type-specific fields may also be present. This is the single progress shape for every job type — annotation workers and generation alike. */
         JobProgress: {
-            /** @description Current processing stage */
+            /** @description Current processing stage (e.g. 'analyzing', 'creating', 'complete', 'error') */
             stage: string;
             /** @description Completion percentage (0-100) */
             percentage: number;
             /** @description Human-readable progress message */
             message: string;
+            /** @description Annotation this job is attached to, when applicable. Echoed inside JobProgress (in addition to the outer command envelope) so consumers that only see the inner progress object (e.g. client.yield.fromAnnotation's Observable) can still route visual feedback to a specific annotation. */
+            annotationId?: string;
             /** @description Total entity types to process (reference-annotation) */
             totalEntityTypes?: number;
             /** @description Entity types processed so far (reference-annotation) */
@@ -4486,12 +3176,22 @@ interface components {
             entitiesEmitted?: number;
             /** @description Entity type currently being processed */
             currentEntityType?: string;
+            /** @description Reference annotation: completed entity types with per-type counts, for UI progress display */
+            completedEntityTypes?: {
+                entityType: string;
+                foundCount: number;
+            }[];
             /** @description Categories processed (tag-annotation) */
             processedCategories?: number;
             /** @description Total categories (tag-annotation) */
             totalCategories?: number;
             /** @description Category currently being processed (tag-annotation) */
             currentCategory?: string;
+            /** @description Echoed job parameters for display in the progress UI (e.g. entity types or categories the user asked to detect) */
+            requestParams?: {
+                label: string;
+                value: string;
+            }[];
         };
         /** @description Event indicating a job has been queued */
         JobQueuedEvent: {
@@ -4514,6 +3214,8 @@ interface components {
             userId: string;
             jobId: string;
             jobType: components["schemas"]["JobType"];
+            /** @description Annotation this job is attached to, when applicable. Lets the UI attach progress visuals to a specific annotation (e.g. a reference whose generation is running). */
+            annotationId?: string;
             percentage: number;
             progress?: components["schemas"]["JobProgress"];
         };
@@ -4525,6 +3227,8 @@ interface components {
             userId: string;
             jobId: string;
             jobType: components["schemas"]["JobType"];
+            /** @description Annotation this job is attached to, when applicable. Set for annotation-scoped jobs like generation (from a specific reference). Unset for resource-scoped jobs like bulk reference/tag/highlight detection. */
+            annotationId?: string;
         };
         /** @description Request to check the status of a job */
         JobStatusRequest: {
@@ -4581,6 +3285,8 @@ interface components {
         };
         /** @description Bus command to create an annotation on a resource. */
         MarkCreateCommand: {
+            /** @description Optional correlation id threaded from the originating mark:create-request. Propagated into event metadata by Stower so annotation-assembly can emit mark:create-ok after persistence completes. */
+            correlationId?: string;
             annotation: components["schemas"]["Annotation"];
             userId: string;
             resourceId: string;
@@ -4589,6 +3295,12 @@ interface components {
         MarkCreateOk: {
             annotationId: string;
         };
+        /** @description Raw annotation creation intent — bus handler assembles the W3C annotation */
+        MarkCreateRequest: {
+            correlationId: string;
+            resourceId: string;
+            request: components["schemas"]["CreateAnnotationRequest"];
+        };
         /** @description Bus command to delete an annotation. */
         MarkDeleteCommand: {
             annotationId: string;
@@ -4618,7 +3330,8 @@ interface components {
             motivation: components["schemas"]["Motivation"];
             /** @description One or more W3C selectors */
             selector: components["schemas"]["TextPositionSelector"] | components["schemas"]["TextQuoteSelector"] | components["schemas"]["SvgSelector"] | components["schemas"]["FragmentSelector"] | (components["schemas"]["TextPositionSelector"] | components["schemas"]["TextQuoteSelector"] | components["schemas"]["SvgSelector"] | components["schemas"]["FragmentSelector"])[];
-            body: components["schemas"]["AnnotationBody"][];
+            /** @description Optional body. Omit for annotations whose motivation alone is meaningful (e.g. highlighting) or whose user-supplied content is empty (e.g. an assessing annotation saved without comment text). Shape matches Annotation.body. */
+            body?: components["schemas"]["AnnotationBody"] | components["schemas"]["AnnotationBody"][];
         };
         /** @description Bus command to unarchive a previously archived resource. */
         MarkUnarchiveCommand: {
@@ -5076,11 +3789,6 @@ interface ResourceAnnotations {
  * Organized by flow (verb), then by category within each flow.
  */
 
-type Selector = components['schemas']['TextPositionSelector'] | components['schemas']['TextQuoteSelector'] | components['schemas']['SvgSelector'] | components['schemas']['FragmentSelector'];
-type GatheredContext = components['schemas']['GatheredContext'];
-type YieldProgress = components['schemas']['YieldProgress'];
-type MarkProgress = components['schemas']['MarkProgress'];
-type SelectionData = components['schemas']['SelectionData'];
 /**
  * The unified EventMap — every channel on the EventBus.
  *
@@ -5096,9 +3804,6 @@ type EventMap = {
     'yield:moved': StoredEvent<EventOfType<'yield:moved'>>;
     'yield:representation-added': StoredEvent<EventOfType<'yield:representation-added'>>;
     'yield:representation-removed': StoredEvent<EventOfType<'yield:representation-removed'>>;
-    'yield:progress': components['schemas']['YieldProgress'];
-    'yield:finished': components['schemas']['YieldProgress'];
-    'yield:failed': components['schemas']['YieldStreamError'];
     'yield:request': components['schemas']['YieldRequestCommand'];
     'yield:create': components['schemas']['YieldCreateCommand'];
     'yield:update': components['schemas']['YieldUpdateCommand'];
@@ -5141,9 +3846,7 @@ type EventMap = {
     'mark:entity-type-added': StoredEvent<EventOfType<'mark:entity-type-added'>>;
     'mark:archived': StoredEvent<EventOfType<'mark:archived'>>;
     'mark:unarchived': StoredEvent<EventOfType<'mark:unarchived'>>;
-    'mark:progress': components['schemas']['MarkProgress'];
-    'mark:assist-finished': components['schemas']['MarkAssistFinished'];
-    'mark:assist-failed': components['schemas']['MarkAssistFailed'];
+    'mark:create-request': components['schemas']['MarkCreateRequest'];
     'mark:create': components['schemas']['MarkCreateCommand'];
     'mark:delete': components['schemas']['MarkDeleteCommand'];
     'mark:update-body': components['schemas']['MarkUpdateBodyCommand'];
@@ -5190,6 +3893,14 @@ type EventMap = {
         correlationId: string;
         resourceId: string;
     } & components['schemas']['CommandError'];
+    'gather:summary-requested': components['schemas']['GatherSummaryRequest'];
+    'gather:summary-result': {
+        correlationId: string;
+        response: Record<string, unknown>;
+    };
+    'gather:summary-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
     'gather:annotation-progress': components['schemas']['GatherProgress'];
     'gather:annotation-finished': components['schemas']['GatherAnnotationFinished'];
     'gather:progress': components['schemas']['GatherProgress'];
@@ -5224,6 +3935,14 @@ type EventMap = {
     'browse:annotation-history-failed': {
         correlationId: string;
     } & components['schemas']['CommandError'];
+    'browse:annotation-context-requested': components['schemas']['BrowseAnnotationContextRequest'];
+    'browse:annotation-context-result': {
+        correlationId: string;
+        response: Record<string, unknown>;
+    };
+    'browse:annotation-context-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
     'browse:referenced-by-requested': components['schemas']['BrowseReferencedByRequest'];
     'browse:referenced-by-result': components['schemas']['BrowseReferencedByResult'];
     'browse:referenced-by-failed': {
@@ -5241,19 +3960,19 @@ type EventMap = {
         path: string;
     } & components['schemas']['CommandError'];
     'browse:click': components['schemas']['BrowseClickEvent'];
-    'browse:panel-toggle': components['schemas']['BrowsePanelToggleEvent'];
-    'browse:panel-open': components['schemas']['BrowsePanelOpenEvent'];
-    'browse:panel-close': void;
-    'browse:sidebar-toggle': void;
-    'browse:resource-close': components['schemas']['BrowseResourceCloseEvent'];
-    'browse:resource-reorder': components['schemas']['BrowseResourceReorderEvent'];
-    'browse:link-clicked': components['schemas']['BrowseLinkClickedEvent'];
-    'browse:router-push': components['schemas']['BrowseRouterPushEvent'];
-    'browse:external-navigate': components['schemas']['BrowseExternalNavigateEvent'] & {
-        cancelFallback: () => void;
-    };
     'browse:reference-navigate': components['schemas']['BrowseReferenceNavigateEvent'];
     'browse:entity-type-clicked': components['schemas']['BrowseEntityTypeClickedEvent'];
+    'panel:toggle': components['schemas']['BrowsePanelToggleEvent'];
+    'panel:open': components['schemas']['BrowsePanelOpenEvent'];
+    'panel:close': void;
+    'shell:sidebar-toggle': void;
+    'tabs:close': components['schemas']['BrowseResourceCloseEvent'];
+    'tabs:reorder': components['schemas']['BrowseResourceReorderEvent'];
+    'nav:link-clicked': components['schemas']['BrowseLinkClickedEvent'];
+    'nav:push': components['schemas']['BrowseRouterPushEvent'];
+    'nav:external': components['schemas']['BrowseExternalNavigateEvent'] & {
+        cancelFallback: () => void;
+    };
     'beckon:hover': components['schemas']['BeckonHoverEvent'];
     'beckon:focus': components['schemas']['BeckonFocusEvent'];
     'beckon:sparkle': components['schemas']['BeckonSparkleEvent'];
@@ -5268,10 +3987,23 @@ type EventMap = {
     'job:queued': components['schemas']['JobQueuedEvent'];
     'job:cancel-requested': components['schemas']['JobCancelRequest'];
     'job:status-requested': components['schemas']['JobStatusRequest'];
+    'job:create': components['schemas']['JobCreateCommand'];
+    'job:claim': components['schemas']['JobClaimCommand'];
     'job:status-result': components['schemas']['JobStatusResult'];
     'job:status-failed': {
         correlationId: string;
     } & components['schemas']['CommandError'];
+    'job:created': components['schemas']['JobCreatedResult'];
+    'job:create-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'job:claimed': {
+        correlationId: string;
+        response: Record<string, unknown>;
+    };
+    'job:claim-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
     'settings:theme-changed': components['schemas']['SettingsThemeChangedEvent'];
     'settings:line-numbers-toggled': void;
     'settings:locale-changed': components['schemas']['SettingsLocaleChangedEvent'];
@@ -5284,25 +4016,253 @@ type EventMap = {
         cap: number;
         message: string;
     };
+    /**
+     * Emitted by the `/bus/subscribe` handler when a client reconnected
+     * with `Last-Event-ID: p-<scope>-<seq>` but the server could not
+     * replay all missed persisted events for that scope (retention
+     * window exceeded, scope unknown, or request unparseable). The
+     * client should treat this as a signal to fall back to the pre-
+     * resumption contract: invalidate caches for the affected scope
+     * and re-read from scratch. Analogous to `replay-window-exceeded`
+     * but scoped to the bus gateway rather than the per-resource
+     * events stream.
+     *
+     * `scope` is the scope string the client asked about (omitted for
+     * global-persisted resumption gaps, if that path ever exists).
+     * `reason` is human-readable, for logging.
+     */
+    'bus:resume-gap': {
+        scope?: string;
+        lastSeenId?: string;
+        reason: string;
+    };
 };
 /** Any valid channel name on the EventBus. */
 type EventName = keyof EventMap;
 /**
- * Non-persisted event types that the per-resource events-stream should deliver
- * to all connected clients. These are ephemeral command-result and progress
- * events that don't go through EventStore.appendEvent but still need to reach
- * every participant viewing the resource for real-time collaboration.
+ * Genuine resource-bound broadcast event types.
+ *
+ * Publishers emit these on the scoped EventBus (`eventBus.scope(resourceId)`)
+ * because every participant viewing the resource should receive them — not
+ * just the caller who triggered the originating action. Examples: resource
+ * generation progress, which multiple viewers of a generating resource all
+ * want to see.
+ *
+ * Non-broadcast progress (AI-assist progress for one user, search results
+ * for one caller) does NOT belong here. Those are per-caller correlation-ID
+ * responses and publish globally — the caller filters by `correlationId`.
+ *
+ * The frontend's `subscribeToResource(id)` wires these channels via
+ * `scope=id&scoped=<channel>` so the SSE route delivers them to that
+ * participant. WorkerVM uses this list to decide which emitted events to
+ * scope to their resource.
+ */
+/**
+ * Audit note (SIMPLE-BUS Phase 3 close): `yield:progress` was
+ * considered for inclusion but has only one consumer — the
+ * yield-initiator's Observable in `packages/api-client/src/namespaces/yield.ts`.
+ * No viewer of the resource other than the initiator subscribes to
+ * progress. Scoping therefore serves no fan-out-narrowing purpose for
+ * that channel, so it stays global (as a correlation-ID-shaped
+ * response, filtered by `referenceId`). Only `yield:finished` and
+ * `yield:failed` have a genuine multi-participant consumer (the
+ * ResourceViewerPage toast on the source resource).
+ */
+declare const RESOURCE_BROADCAST_TYPES: readonly ["job:complete", "job:fail"];
+type ResourceBroadcastType = typeof RESOURCE_BROADCAST_TYPES[number];
+/**
+ * Authoritative map from bus channel to OpenAPI schema name.
+ *
+ * Every {@link EventName} must appear. The `satisfies` clause below
+ * enforces completeness at compile time — adding a channel to
+ * {@link EventMap} without adding an entry here is a build error.
+ *
+ * Values:
+ *   - `<SchemaName>`: payload validates against `components['schemas'][SchemaName]`.
+ *   - `null`: no single-schema validation. Used for branded
+ *     `StoredEvent` wrappers, `void` UI signals, and compound inline
+ *     types (e.g. `{ correlationId } & CommandError`). These are not
+ *     validated by `/bus/emit`.
+ *
+ * The `/bus/emit` route reads this map to validate incoming payloads.
+ * Consumers can also use it to do client-side pre-flight validation
+ * before emitting.
+ */
+declare const CHANNEL_SCHEMAS: {
+    readonly 'yield:created': null;
+    readonly 'yield:cloned': null;
+    readonly 'yield:updated': null;
+    readonly 'yield:moved': null;
+    readonly 'yield:representation-added': null;
+    readonly 'yield:representation-removed': null;
+    readonly 'yield:request': "YieldRequestCommand";
+    readonly 'yield:create': "YieldCreateCommand";
+    readonly 'yield:update': "YieldUpdateCommand";
+    readonly 'yield:mv': "YieldMvCommand";
+    readonly 'yield:clone': null;
+    readonly 'yield:clone-token-requested': "YieldCloneTokenRequest";
+    readonly 'yield:clone-resource-requested': "YieldCloneResourceRequest";
+    readonly 'yield:clone-create': "YieldCloneCreateCommand";
+    readonly 'yield:create-ok': "YieldCreateOk";
+    readonly 'yield:create-failed': "CommandError";
+    readonly 'yield:update-ok': "YieldUpdateOk";
+    readonly 'yield:update-failed': null;
+    readonly 'yield:move-ok': "YieldMoveOk";
+    readonly 'yield:move-failed': null;
+    readonly 'yield:clone-token-generated': null;
+    readonly 'yield:clone-token-failed': null;
+    readonly 'yield:clone-resource-result': null;
+    readonly 'yield:clone-resource-failed': null;
+    readonly 'yield:clone-created': "YieldCloneCreated";
+    readonly 'yield:clone-create-failed': null;
+    readonly 'mark:added': null;
+    readonly 'mark:removed': null;
+    readonly 'mark:body-updated': null;
+    readonly 'mark:entity-tag-added': null;
+    readonly 'mark:entity-tag-removed': null;
+    readonly 'mark:entity-type-added': null;
+    readonly 'mark:archived': null;
+    readonly 'mark:unarchived': null;
+    readonly 'mark:create-request': "MarkCreateRequest";
+    readonly 'mark:create': "MarkCreateCommand";
+    readonly 'mark:delete': "MarkDeleteCommand";
+    readonly 'mark:update-body': "MarkUpdateBodyCommand";
+    readonly 'mark:archive': "MarkArchiveCommand";
+    readonly 'mark:unarchive': "MarkUnarchiveCommand";
+    readonly 'mark:update-entity-types': "MarkUpdateEntityTypesCommand";
+    readonly 'mark:add-entity-type': "MarkAddEntityTypeCommand";
+    readonly 'mark:create-ok': "MarkCreateOk";
+    readonly 'mark:create-failed': "CommandError";
+    readonly 'mark:delete-ok': "MarkDeleteOk";
+    readonly 'mark:delete-failed': "CommandError";
+    readonly 'mark:body-update-failed': "CommandError";
+    readonly 'mark:entity-type-add-failed': "CommandError";
+    readonly 'mark:select-comment': "SelectionData";
+    readonly 'mark:select-tag': "SelectionData";
+    readonly 'mark:select-assessment': "SelectionData";
+    readonly 'mark:select-reference': "SelectionData";
+    readonly 'mark:requested': "MarkRequestedEvent";
+    readonly 'mark:cancel-pending': null;
+    readonly 'mark:submit': "MarkSubmitEvent";
+    readonly 'mark:assist-request': "MarkAssistRequestEvent";
+    readonly 'mark:assist-cancelled': null;
+    readonly 'mark:progress-dismiss': null;
+    readonly 'mark:mode-toggled': null;
+    readonly 'mark:selection-changed': "MarkSelectionChangedEvent";
+    readonly 'mark:click-changed': "MarkClickChangedEvent";
+    readonly 'mark:shape-changed': "MarkShapeChangedEvent";
+    readonly 'bind:initiate': "BindInitiateCommand";
+    readonly 'bind:update-body': "BindUpdateBodyCommand";
+    readonly 'bind:body-updated': "BindBodyUpdated";
+    readonly 'bind:body-update-failed': "CommandError";
+    readonly 'match:search-requested': "MatchSearchRequest";
+    readonly 'match:search-results': "MatchSearchResult";
+    readonly 'match:search-failed': "MatchSearchFailed";
+    readonly 'gather:requested': "GatherAnnotationRequest";
+    readonly 'gather:complete': "GatherAnnotationComplete";
+    readonly 'gather:failed': null;
+    readonly 'gather:resource-requested': "GatherResourceRequest";
+    readonly 'gather:resource-complete': "GatherResourceComplete";
+    readonly 'gather:resource-failed': null;
+    readonly 'gather:summary-requested': "GatherSummaryRequest";
+    readonly 'gather:summary-result': null;
+    readonly 'gather:summary-failed': null;
+    readonly 'gather:annotation-progress': "GatherProgress";
+    readonly 'gather:annotation-finished': "GatherAnnotationFinished";
+    readonly 'gather:progress': "GatherProgress";
+    readonly 'gather:finished': "GatherFinished";
+    readonly 'browse:resource-requested': "BrowseResourceRequest";
+    readonly 'browse:resource-result': "BrowseResourceResult";
+    readonly 'browse:resource-failed': null;
+    readonly 'browse:resources-requested': "BrowseResourcesRequest";
+    readonly 'browse:resources-result': "BrowseResourcesResult";
+    readonly 'browse:resources-failed': null;
+    readonly 'browse:annotations-requested': "BrowseAnnotationsRequest";
+    readonly 'browse:annotations-result': "BrowseAnnotationsResult";
+    readonly 'browse:annotations-failed': null;
+    readonly 'browse:annotation-requested': "BrowseAnnotationRequest";
+    readonly 'browse:annotation-result': "BrowseAnnotationResult";
+    readonly 'browse:annotation-failed': null;
+    readonly 'browse:events-requested': "BrowseEventsRequest";
+    readonly 'browse:events-result': "BrowseEventsResult";
+    readonly 'browse:events-failed': null;
+    readonly 'browse:annotation-history-requested': "BrowseAnnotationHistoryRequest";
+    readonly 'browse:annotation-history-result': "BrowseAnnotationHistoryResult";
+    readonly 'browse:annotation-history-failed': null;
+    readonly 'browse:annotation-context-requested': "BrowseAnnotationContextRequest";
+    readonly 'browse:annotation-context-result': null;
+    readonly 'browse:annotation-context-failed': null;
+    readonly 'browse:referenced-by-requested': "BrowseReferencedByRequest";
+    readonly 'browse:referenced-by-result': "BrowseReferencedByResult";
+    readonly 'browse:referenced-by-failed': null;
+    readonly 'browse:entity-types-requested': "BrowseEntityTypesRequest";
+    readonly 'browse:entity-types-result': "BrowseEntityTypesResult";
+    readonly 'browse:entity-types-failed': null;
+    readonly 'browse:directory-requested': "BrowseDirectoryRequest";
+    readonly 'browse:directory-result': "BrowseDirectoryResult";
+    readonly 'browse:directory-failed': null;
+    readonly 'browse:click': "BrowseClickEvent";
+    readonly 'browse:reference-navigate': "BrowseReferenceNavigateEvent";
+    readonly 'browse:entity-type-clicked': "BrowseEntityTypeClickedEvent";
+    readonly 'panel:toggle': "BrowsePanelToggleEvent";
+    readonly 'panel:open': "BrowsePanelOpenEvent";
+    readonly 'panel:close': null;
+    readonly 'shell:sidebar-toggle': null;
+    readonly 'tabs:close': "BrowseResourceCloseEvent";
+    readonly 'tabs:reorder': "BrowseResourceReorderEvent";
+    readonly 'nav:link-clicked': "BrowseLinkClickedEvent";
+    readonly 'nav:push': "BrowseRouterPushEvent";
+    readonly 'nav:external': null;
+    readonly 'beckon:hover': "BeckonHoverEvent";
+    readonly 'beckon:focus': "BeckonFocusEvent";
+    readonly 'beckon:sparkle': "BeckonSparkleEvent";
+    readonly 'job:started': null;
+    readonly 'job:progress': null;
+    readonly 'job:completed': null;
+    readonly 'job:failed': null;
+    readonly 'job:start': "JobStartCommand";
+    readonly 'job:report-progress': "JobReportProgressCommand";
+    readonly 'job:complete': "JobCompleteCommand";
+    readonly 'job:fail': "JobFailCommand";
+    readonly 'job:queued': "JobQueuedEvent";
+    readonly 'job:cancel-requested': "JobCancelRequest";
+    readonly 'job:status-requested': "JobStatusRequest";
+    readonly 'job:create': "JobCreateCommand";
+    readonly 'job:claim': "JobClaimCommand";
+    readonly 'job:status-result': "JobStatusResult";
+    readonly 'job:status-failed': null;
+    readonly 'job:created': "JobCreatedResult";
+    readonly 'job:create-failed': null;
+    readonly 'job:claimed': null;
+    readonly 'job:claim-failed': null;
+    readonly 'settings:theme-changed': "SettingsThemeChangedEvent";
+    readonly 'settings:line-numbers-toggled': null;
+    readonly 'settings:locale-changed': "SettingsLocaleChangedEvent";
+    readonly 'settings:hover-delay-changed': "SettingsHoverDelayChangedEvent";
+    readonly 'stream-connected': null;
+    readonly 'replay-window-exceeded': null;
+    readonly 'bus:resume-gap': null;
+};
+/** Channels where `/bus/emit` validates the payload (non-null schema). */
+type EmittableChannel = {
+    [K in EventName]: typeof CHANNEL_SCHEMAS[K] extends null ? never : K;
+}[EventName];
+
+/**
+ * Payload Type Aliases
  *
- * Actors (Binder, Gatherer, workers) publish these on the scoped EventBus
- * (`eventBus.scope(resourceId)`). The events-stream route subscribes to them
- * alongside the persisted event types.
+ * Convenience aliases for OpenAPI-generated schema types that are
+ * referenced across the codebase. Shorter than
+ * `components['schemas']['<Name>']` and carry intent.
  *
- * Unlike PERSISTED_EVENT_TYPES, there's no compile-time exhaustiveness check
- * here because these event types are a curated subset of EventMap — not every
- * non-persisted event should flow to all participants. Adding a new one is a
- * deliberate choice, not an automatic cascade.
+ * These aliases are not about the bus. They live here so that
+ * bus-protocol.ts can focus on channel-protocol concerns (EventMap,
+ * CHANNEL_SCHEMAS, scope classification).
  */
-declare const STREAM_COMMAND_RESULT_TYPES: readonly ["match:search-results", "match:search-failed", "gather:complete", "gather:failed", "gather:annotation-progress", "mark:progress", "mark:assist-finished", "mark:assist-failed", "yield:progress", "yield:finished", "yield:failed"];
+
+type Selector = components['schemas']['TextPositionSelector'] | components['schemas']['TextQuoteSelector'] | components['schemas']['SvgSelector'] | components['schemas']['FragmentSelector'];
+type GatheredContext = components['schemas']['GatheredContext'];
+type SelectionData = components['schemas']['SelectionData'];
 
 /**
  * Event Type Guards and Extraction Utilities
@@ -5545,6 +4505,57 @@ interface BurstBufferOptions {
  */
 declare function burstBuffer<T>(options: BurstBufferOptions): OperatorFunction<T, T | T[]>;
 
+/**
+ * serializePerKey — run async work serialized per key, parallel across keys.
+ *
+ * Invariant: two calls with the same `key` run strictly in sequence (the
+ * second `work` does not start until the first has settled). Calls with
+ * different keys overlap freely.
+ *
+ * Error isolation: a rejected work function does not poison subsequent
+ * tasks for the same key. The next task starts fresh from whatever state
+ * the failed task left behind. The rejection still propagates to *this*
+ * caller.
+ *
+ * Registry cleanup: the entry for a key is removed as soon as its chain
+ * empties, so the Map stays bounded by the number of keys with work
+ * currently in flight, not by the total number of keys ever seen.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * const chains = new Map<string, Promise<void>>();
+ *
+ * async function write(resourceId: string, event: Event) {
+ *   return serializePerKey(resourceId, chains, async () => {
+ *     // Read-modify-write on a view file. Any two concurrent calls with
+ *     // the same resourceId will be serialized; different resourceIds
+ *     // will proceed in parallel.
+ *     const view = await viewStorage.get(resourceId);
+ *     applyEvent(view, event);
+ *     await viewStorage.save(resourceId, view);
+ *   });
+ * }
+ * ```
+ *
+ * ## When to use this vs RxJS `groupBy + concatMap`
+ *
+ * Use `serializePerKey` when the work arrives as **direct method calls**
+ * that need to block the caller until completion. This is the RPC shape
+ * — think `EventStore.appendEvent` calling `await views.materializeResource(...)`
+ * and needing the view written before any subscriber sees the published
+ * event.
+ *
+ * Use RxJS `groupBy(keyFn) + concatMap(...)` when the work arrives as an
+ * **event stream** that a component subscribes to once at startup. This
+ * is how `Smelter`, `GraphDBConsumer`, and `Gatherer` serialize their own
+ * per-resource work — see their implementations in `packages/make-meaning`.
+ *
+ * Both patterns solve the same logical problem ("serialize work per key").
+ * The choice is dictated by whether the caller is awaiting the result.
+ */
+declare function serializePerKey<K, T>(key: K, chains: Map<K, Promise<void>>, work: () => Promise<T>): Promise<T>;
+
 /**
  * Logger interface for observability
  *
@@ -5570,6 +4581,36 @@ interface Logger {
     error(message: string, meta?: any): void;
     child(meta: Record<string, any>): Logger;
 }
+/**
+ * Serialize an error value into a form that JSON.stringify can handle
+ * meaningfully.
+ *
+ * Winston's default JSON formatter serializes `Error` instances as `{}`
+ * because `message`, `stack`, and `name` are non-enumerable properties on
+ * the Error prototype. That means `logger.error('x', { error })` with a
+ * raw Error argument produces useless log lines like
+ * `{"error":{},"message":"x",...}`, throwing away the information you
+ * actually need to diagnose the failure.
+ *
+ * This helper extracts the parts you want to see in a log — name,
+ * message, stack, and cause — and leaves non-Error values alone (so
+ * strings, numbers, and plain objects pass through unchanged).
+ *
+ * ## Usage
+ *
+ * ```ts
+ * try {
+ *   await doSomething();
+ * } catch (error) {
+ *   logger.error('Something failed', { error: errField(error) });
+ * }
+ * ```
+ *
+ * Use this at every `logger.error` call site that includes an `error`
+ * field derived from a catch block. Raw `{ error }` without this helper
+ * is almost always a bug.
+ */
+declare function errField(error: unknown): unknown;
 
 /**
  * Annotation body utilities
@@ -5690,7 +4731,7 @@ interface CreateAnnotationInternal {
     id: string;
     motivation: Annotation['motivation'];
     target: Annotation['target'];
-    body: Annotation['body'];
+    body?: Annotation['body'];
     creator: components['schemas']['Agent'];
 }
 
@@ -5854,7 +4895,7 @@ declare function userToAgent(user: {
  * @param did - DID:WEB identifier string
  * @returns Minimal W3C Agent object
  */
-declare function didToAgent(did: string): Agent;
+declare function didToAgent(did: string | undefined | null): Agent;
 
 /**
  * TOML Config Loader
@@ -5990,4 +5031,4 @@ declare function getAllPlatformTypes(): PlatformType[];
 declare const CORE_TYPES_VERSION = "0.1.0";
 declare const SDK_VERSION = "0.1.0";
 
-export { APIError, type AccessToken, type AnnotationCategory, type AnnotationId, type AnnotationUri, type AssembledAnnotation, type AuthCode, type BaseUrl, type BodyItem, type BodyItemIdentity, type BodyOperation, type Brand, type BurstBufferOptions, CORE_TYPES_VERSION, CREATION_METHODS, type CloneToken, ConfigurationError, ConflictError, type ContentFormat, type CreateAnnotationInternal, type CreationMethod, type Email, type EntityType, type EntityTypeStats, type Environment, EnvironmentConfig, type EventBase, EventBus, type EventInput, type EventMap, type EventMetadata, type EventName, type EventOfType, type EventQuery, type EventSignature, type GatheredContext, type GoogleAuthRequest, type GoogleCredential, type GraphConnection, type GraphPath, type JobId, type Logger, type MCPToken, type MarkProgress, type Motivation, NotFoundError, PERSISTED_EVENT_TYPES, type PersistedEvent, type PersistedEventType, type PlatformType, type RefreshToken, type ResourceAnnotationUri, type ResourceAnnotations, type ResourceFilter, type ResourceId, type ResourceUri, SDK_VERSION, STREAM_COMMAND_RESULT_TYPES, ScopedEventBus, ScriptError, type SearchQuery, type SelectionData, type Selector, SemiontError, type StoredEvent, type StoredEventLike, type ActorInferenceConfig as TomlActorInferenceConfig, type TomlFileReader, type InferenceConfig as TomlInferenceConfig, type WorkerInferenceConfig as TomlWorkerInferenceConfig, UnauthorizedError, type UpdateResourceInput, type UserDID, type UserId, ValidationError, type YieldProgress, accessToken, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseUrl, burstBuffer, cloneToken, type components, createTomlConfigLoader, didToAgent, email, entityType, findBodyItem, generateUuid, getAllPlatformTypes, getAnnotationUriFromEvent, getFragmentSelector, getSvgSelector, getTextPositionSelector, googleCredential, isAnnotationId, isArray, isBoolean, isDefined, isEventRelatedToAnnotation, isFunction, isNull, isNullish, isNumber, isObject, isResourceId, isStoredEvent, isString, isUndefined, isValidPlatformType, jobId, loadTomlConfig, mcpToken, type operations, parseEnvironment, type paths, refreshToken, resourceAnnotationUri, resourceId, resourceUri, searchQuery, userDID, userId, userToAgent, userToDid, validateEnvironment, validateSvgMarkup };
+export { APIError, type AccessToken, type AnnotationCategory, type AnnotationId, type AnnotationUri, type AssembledAnnotation, type AuthCode, type BaseUrl, type BodyItem, type BodyItemIdentity, type BodyOperation, type Brand, type BurstBufferOptions, CHANNEL_SCHEMAS, CORE_TYPES_VERSION, CREATION_METHODS, type CloneToken, ConfigurationError, ConflictError, type ContentFormat, type CreateAnnotationInternal, type CreationMethod, type Email, type EmittableChannel, type EntityType, type EntityTypeStats, type Environment, EnvironmentConfig, type EventBase, EventBus, type EventInput, type EventMap, type EventMetadata, type EventName, type EventOfType, type EventQuery, type EventSignature, type GatheredContext, type GoogleAuthRequest, type GoogleCredential, type GraphConnection, type GraphPath, type JobId, type Logger, type MCPToken, type Motivation, NotFoundError, PERSISTED_EVENT_TYPES, type PersistedEvent, type PersistedEventType, type PlatformType, RESOURCE_BROADCAST_TYPES, type RefreshToken, type ResourceAnnotationUri, type ResourceAnnotations, type ResourceBroadcastType, type ResourceFilter, type ResourceId, type ResourceUri, SDK_VERSION, ScopedEventBus, ScriptError, type SearchQuery, type SelectionData, type Selector, SemiontError, type StoredEvent, type StoredEventLike, type ActorInferenceConfig as TomlActorInferenceConfig, type TomlFileReader, type InferenceConfig as TomlInferenceConfig, type WorkerInferenceConfig as TomlWorkerInferenceConfig, UnauthorizedError, type UpdateResourceInput, type UserDID, type UserId, ValidationError, accessToken, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseUrl, burstBuffer, cloneToken, type components, createTomlConfigLoader, didToAgent, email, entityType, errField, findBodyItem, generateUuid, getAllPlatformTypes, getAnnotationUriFromEvent, getFragmentSelector, getSvgSelector, getTextPositionSelector, googleCredential, isAnnotationId, isArray, isBoolean, isDefined, isEventRelatedToAnnotation, isFunction, isNull, isNullish, isNumber, isObject, isResourceId, isStoredEvent, isString, isUndefined, isValidPlatformType, jobId, loadTomlConfig, mcpToken, type operations, parseEnvironment, type paths, refreshToken, resourceAnnotationUri, resourceId, resourceUri, searchQuery, serializePerKey, userDID, userId, userToAgent, userToDid, validateEnvironment, validateSvgMarkup };