@semiont/core 0.4.14 → 0.4.15

package/dist/index.d.ts

@@ -1479,7 +1479,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/resources/{id}/annotate-references-stream": {
+    "/resources/{id}/annotate-references": {
         parameters: {
             query?: never;
             header?: never;
@@ -1538,7 +1538,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/resources/{id}/annotate-highlights-stream": {
+    "/resources/{id}/annotate-highlights": {
         parameters: {
             query?: never;
             header?: never;
@@ -1597,7 +1597,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/resources/{id}/annotate-assessments-stream": {
+    "/resources/{id}/annotate-assessments": {
         parameters: {
             query?: never;
             header?: never;
@@ -1656,7 +1656,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/resources/{id}/annotate-comments-stream": {
+    "/resources/{id}/annotate-comments": {
         parameters: {
             query?: never;
             header?: never;
@@ -1715,7 +1715,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/resources/{id}/annotate-tags-stream": {
+    "/resources/{id}/annotate-tags": {
         parameters: {
             query?: never;
             header?: never;
@@ -1833,7 +1833,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/resources/{id}/match-search-stream": {
+    "/resources/{id}/match-search": {
         parameters: {
             query?: never;
             header?: never;
@@ -1843,8 +1843,8 @@ interface paths {
         get?: never;
         put?: never;
         /**
-         * Match Search (SSE Stream)
-         * @description Search for binding candidates for a reference annotation via Server-Sent Events. Delegates to the Matcher actor on the backend EventBus.
+         * 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: {
@@ -1858,25 +1858,20 @@ interface paths {
             };
             requestBody: {
                 content: {
-                    "application/json": components["schemas"]["MatchSearchStreamRequest"];
+                    "application/json": components["schemas"]["MatchSearchRequest"];
                 };
             };
             responses: {
-                /** @description SSE stream opened successfully */
-                200: {
+                /** @description Search command accepted. Results delivered via events-stream. */
+                202: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "text/event-stream": components["schemas"]["EventStreamResponse"];
-                    };
-                };
-                /** @description referenceId and context are required */
-                400: {
-                    headers: {
-                        [name: string]: unknown;
+                        "application/json": {
+                            correlationId: string;
+                        };
                     };
-                    content?: never;
                 };
                 /** @description Authentication required */
                 401: {
@@ -1900,7 +1895,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/resources/{resourceId}/annotations/{annotationId}/gather-annotation-stream": {
+    "/resources/{resourceId}/annotations/{annotationId}/gather": {
         parameters: {
             query?: never;
             header?: never;
@@ -1910,8 +1905,8 @@ interface paths {
         get?: never;
         put?: never;
         /**
-         * Gather Annotation LLM Context (SSE Stream)
-         * @description Stream real-time annotation LLM context gathering progress via Server-Sent Events
+         * 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: {
@@ -1925,81 +1920,21 @@ interface paths {
                 };
                 cookie?: never;
             };
-            requestBody?: {
+            requestBody: {
                 content: {
                     "application/json": components["schemas"]["GatherAnnotationStreamRequest"];
                 };
             };
             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 Annotation not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/resources/{resourceId}/annotations/{annotationId}/bind-stream": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * Bind Annotation Body (SSE Stream)
-         * @description Apply annotation body operations and stream completion via Server-Sent 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"]["BindAnnotationStreamRequest"];
-                };
-            };
-            responses: {
-                /** @description SSE stream opened successfully */
-                200: {
+                /** @description Gather command accepted. Results delivered via events-stream. */
+                202: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "text/event-stream": components["schemas"]["EventStreamResponse"];
+                        "application/json": {
+                            correlationId: string;
+                        };
                     };
                 };
                 /** @description Authentication required */
@@ -2009,13 +1944,6 @@ interface paths {
                     };
                     content?: never;
                 };
-                /** @description Annotation not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
             };
         };
         delete?: never;
@@ -2477,7 +2405,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/resources/{resourceId}/annotations/{annotationId}/yield-resource-stream": {
+    "/resources/{resourceId}/annotations/{annotationId}/yield-resource": {
         parameters: {
             query?: never;
             header?: never;
@@ -2487,35 +2415,45 @@ interface paths {
         get?: never;
         put?: never;
         /**
-         * Generate Resource (SSE Stream)
-         * @description Stream real-time resource generation progress via Server-Sent Events
+         * 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 Resource ID */
+                    /** @description Source resource ID */
                     resourceId: string;
-                    /** @description Annotation ID */
+                    /** @description Reference annotation ID */
                     annotationId: string;
                 };
                 cookie?: never;
             };
-            requestBody?: {
+            requestBody: {
                 content: {
                     "application/json": components["schemas"]["YieldResourceStreamRequest"];
                 };
             };
             responses: {
-                /** @description SSE stream opened successfully */
-                200: {
+                /** @description Generation command accepted. Progress and results delivered via events-stream. */
+                202: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "text/event-stream": components["schemas"]["EventStreamResponse"];
+                        "application/json": {
+                            correlationId: string;
+                            jobId: string;
+                        };
+                    };
+                };
+                /** @description Context is required for generation */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
                     };
+                    content?: never;
                 };
                 /** @description Authentication required */
                 401: {
@@ -3106,7 +3044,10 @@ interface components {
                 domain: string;
                 isAdmin: boolean;
             };
+            /** @description Short-lived access token (1 hour). Use as Authorization: Bearer header on API calls. */
             token: string;
+            /** @description Long-lived refresh token (30 days). Exchange via POST /api/tokens/refresh for a fresh access token. */
+            refreshToken: string;
             isNewUser: boolean;
         };
         BrowseFilesResponse: {
@@ -3200,6 +3141,13 @@ interface components {
             expiresAt: string;
             resource: components["schemas"]["ResourceDescriptor"];
         };
+        /** @description Error response for failed bus commands. Replaces native Error objects on the EventBus so payloads are serializable and OpenAPI-typed. */
+        CommandError: {
+            /** @description Human-readable error message */
+            message: string;
+            /** @description Optional additional context (stack trace, field name, etc.) */
+            details?: string;
+        };
         /**
          * @description Content format as MIME type, optionally with charset parameter. Values include: text/plain, text/plain; charset=utf-8, text/plain; charset=iso-8859-1, text/markdown, text/markdown; charset=windows-1252, image/png, image/jpeg, application/pdf
          * @example text/plain; charset=utf-8
@@ -3342,6 +3290,336 @@ interface components {
             /** @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;
+            percentage?: number;
+        };
+        /** @description Completion payload emitted on gather:annotation-finished SSE channel. */
+        GatherAnnotationFinished: {
+            correlationId: string;
+            annotationId: string;
+            response: components["schemas"]["AnnotationLLMContextResponse"];
+        };
+        /** @description Completion payload emitted on gather:finished SSE channel for resource-level context gathering. */
+        GatherFinished: {
+            correlationId: string;
+            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;
+            referenceId: string;
+            response: (components["schemas"]["ResourceDescriptor"] & {
+                /** @description Relevance score */
+                score?: number;
+                /** @description Human-readable reason for the match */
+                matchReason?: string;
+            })[];
+        };
+        /** @description Error payload emitted on match:search-failed SSE channel. */
+        MatchSearchFailed: {
+            correlationId: string;
+            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. */
+        EventMetadata: {
+            /** @description Monotonic position in the event log (ordering authority) */
+            sequenceNumber: number;
+            /** @description Byte offset in the JSONL file */
+            streamPosition: number;
+            /** @description SHA-256 of the previous event (hash chain) */
+            prevEventHash?: string;
+            /** @description SHA-256 of this event (integrity verification) */
+            checksum?: string;
+            /** @description Optional correlation id propagated from a command. Lets clients match command-result events back to the POST that initiated them. Set by EventStore.appendEvent's options when a route handler passes one through. */
+            correlationId?: string;
+        };
+        /** @description Selection data for user-initiated annotations. Captures the text range and optional selector information from a user's highlight in the UI. */
+        SelectionData: {
+            /** @description The exact selected text */
+            exact: string;
+            /** @description Start character offset */
+            start: number;
+            /** @description End character offset */
+            end: number;
+            /** @description SVG selector for non-text selections (e.g. PDF regions) */
+            svgSelector?: string;
+            /** @description Fragment selector (e.g. page=2) */
+            fragmentSelector?: string;
+            /** @description Specification the fragment selector conforms to */
+            conformsTo?: string;
+            /** @description Text before the selection (for disambiguation) */
+            prefix?: string;
+            /** @description Text after the selection (for disambiguation) */
+            suffix?: string;
+        };
+        /** @description A persisted domain event with metadata. Flat shape — event fields and metadata are peers. */
+        StoredEventResponse: {
+            /** @description Unique event ID (UUID) */
+            id: string;
+            /** @description Event type (flow verb name, e.g. mark:added) */
+            type: string;
+            /**
+             * Format: date-time
+             * @description When the event occurred
+             */
+            timestamp: string;
+            /** @description DID of the user who triggered the event */
+            userId: string;
+            /** @description Resource this event affects (absent for system events) */
+            resourceId?: string;
+            /** @description Event schema version */
+            version: number;
+            /** @description Event-type-specific payload */
+            payload: {
+                [key: string]: unknown;
+            };
+            metadata: components["schemas"]["EventMetadata"];
+        };
+        /** @description Wire format emitted by GET /resources/:id/events/stream. Extends StoredEventResponse with optional enrichment fields populated from the materialized view at SSE-write time. Subscribers can read the enrichment fields directly to update local caches without an additional fetch. */
+        EnrichedResourceEvent: components["schemas"]["StoredEventResponse"] & {
+            /** @description Populated for events that mutate an annotation (mark:added, mark:body-updated, mark:removed). Carries the post-materialization annotation as it exists in the view, so subscribers can update local caches in-place without refetching. Absent for events that don't touch annotations. */
+            annotation?: components["schemas"]["Annotation"];
+        };
+        /** @description Payload for yield:created domain event */
+        ResourceCreatedPayload: {
+            name: string;
+            format: components["schemas"]["ContentFormat"];
+            /** @description SHA-256 of content */
+            contentChecksum: string;
+            contentByteSize?: number;
+            /** @enum {string} */
+            creationMethod: "api" | "upload" | "ui" | "reference" | "cli" | "clone" | "generated";
+            entityTypes?: string[];
+            /** @description Working-tree URI (e.g. file://docs/overview.md) */
+            storageUri?: string;
+            language?: string;
+            isDraft?: boolean;
+            generatedFrom?: {
+                resourceId: string;
+                annotationId: string;
+            };
+            generationPrompt?: string;
+            generator?: components["schemas"]["Agent"] | components["schemas"]["Agent"][];
+        };
+        /** @description Payload for yield:cloned domain event */
+        ResourceClonedPayload: {
+            name: string;
+            format: components["schemas"]["ContentFormat"];
+            contentChecksum: string;
+            contentByteSize?: number;
+            parentResourceId: string;
+            /** @enum {string} */
+            creationMethod: "api" | "upload" | "ui" | "reference" | "cli" | "clone" | "generated";
+            entityTypes?: string[];
+            language?: string;
+        };
+        /** @description Payload for yield:updated domain event */
+        ResourceUpdatedPayload: {
+            /** @description SHA-256 of new content */
+            contentChecksum: string;
+            contentByteSize?: number;
+        };
+        /** @description Payload for yield:moved domain event */
+        ResourceMovedPayload: {
+            /** @description Previous file:// URI */
+            fromUri: string;
+            /** @description New file:// URI */
+            toUri: string;
+        };
+        /** @description Payload for mark:archived domain event */
+        ResourceArchivedPayload: {
+            reason?: string;
+        };
+        /** @description Payload for mark:unarchived domain event (empty payload) */
+        ResourceUnarchivedPayload: Record<string, never>;
+        /** @description Payload for yield:representation-added domain event */
+        RepresentationAddedPayload: {
+            representation: components["schemas"]["Representation"];
+        };
+        /** @description Payload for yield:representation-removed domain event */
+        RepresentationRemovedPayload: {
+            /** @description Checksum of the representation to remove */
+            checksum: string;
+        };
+        /** @description Payload for mark:added domain event */
+        AnnotationAddedPayload: {
+            annotation: components["schemas"]["Annotation"];
+            /** @description SHA-256 of resource content at annotation time */
+            contentChecksum?: string;
+        };
+        /** @description Payload for mark:removed domain event */
+        AnnotationRemovedPayload: {
+            annotationId: string;
+        };
+        /** @description Payload for mark:body-updated domain event */
+        AnnotationBodyUpdatedPayload: {
+            annotationId: string;
+            operations: (components["schemas"]["BodyOperationAdd"] | components["schemas"]["BodyOperationRemove"] | components["schemas"]["BodyOperationReplace"])[];
+        };
+        /** @description Payload for mark:entity-type-added domain event */
+        EntityTypeAddedPayload: {
+            entityType: string;
+        };
+        /** @description Payload for mark:entity-tag-added and mark:entity-tag-removed domain events */
+        EntityTagChangedPayload: {
+            entityType: string;
+        };
+        /**
+         * @description Type of background job
+         * @enum {string}
+         */
+        JobType: "reference-annotation" | "generation" | "highlight-annotation" | "assessment-annotation" | "comment-annotation" | "tag-annotation";
+        /** @description Payload for job:started domain event */
+        JobStartedPayload: {
+            jobId: string;
+            jobType: components["schemas"]["JobType"];
+            totalSteps?: number;
+        };
+        /** @description Payload for job:progress domain event */
+        JobProgressPayload: {
+            jobId: string;
+            jobType: components["schemas"]["JobType"];
+            percentage: number;
+            /** @description Human-readable current step */
+            currentStep?: string;
+            processedSteps?: number;
+            totalSteps?: number;
+            /** @description For detection: entities found so far */
+            foundCount?: number;
+            message?: string;
+            /** @description Full progress object for extensibility */
+            progress?: {
+                [key: string]: unknown;
+            };
+        };
+        /** @description Payload for job:completed domain event */
+        JobCompletedPayload: {
+            jobId: string;
+            jobType: components["schemas"]["JobType"];
+            totalSteps?: number;
+            /** @description For detection: total entities found */
+            foundCount?: number;
+            /** @description For generation: ID of generated resource */
+            resultResourceId?: string;
+            /** @description For generation: URI of annotation that triggered generation */
+            annotationUri?: string;
+            message?: string;
+            /** @description Full result object for extensibility */
+            result?: {
+                [key: string]: unknown;
+            };
+        };
+        /** @description Payload for job:failed domain event */
+        JobFailedPayload: {
+            jobId: string;
+            jobType: components["schemas"]["JobType"];
+            error: string;
+            details?: string;
+        };
+        /** @description Payload for embedding:computed domain event */
+        EmbeddingComputedPayload: {
+            annotationId?: string;
+            chunkIndex: number;
+            chunkText: string;
+            embedding: number[];
+            model: string;
+            dimensions: number;
+        };
+        /** @description Payload for embedding:deleted domain event */
+        EmbeddingDeletedPayload: {
+            annotationId?: string;
+        };
         AnnotateHighlightsStreamRequest: {
             /** @description Optional instructions to guide AI highlight annotation */
             instructions?: string;
@@ -3432,57 +3710,7 @@ interface components {
             storageUri: string;
         };
         GetAnnotationHistoryResponse: {
-            events: {
-                id: string;
-                type: string;
-                timestamp: string;
-                userId: string;
-                resourceId: string;
-                payload: {
-                    name: string;
-                    format: components["schemas"]["ContentFormat"];
-                    contentChecksum: string;
-                    /** @enum {string} */
-                    creationMethod: "api" | "upload" | "ui" | "reference" | "clone" | "generated";
-                    entityTypes?: string[];
-                    metadata?: {
-                        [key: string]: unknown;
-                    };
-                } | {
-                    name: string;
-                    format: components["schemas"]["ContentFormat"];
-                    contentChecksum: string;
-                    parentResourceId: string;
-                    /** @enum {string} */
-                    creationMethod: "api" | "upload" | "ui" | "reference" | "clone" | "generated";
-                    entityTypes?: string[];
-                    metadata?: {
-                        [key: string]: unknown;
-                    };
-                } | {
-                    reason?: string;
-                } | Record<string, never> | {
-                    /** @description W3C Annotation (creator/created fields are optional in events - they're derived from event userId/timestamp) */
-                    annotation: components["schemas"]["Annotation"];
-                } | {
-                    /** @description Unified annotation ID */
-                    annotationId: string;
-                } | {
-                    /** @description Unified annotation ID */
-                    annotationId: string;
-                    /** @description For linking motivation */
-                    targetResourceId: string;
-                } | {
-                    entityType: string;
-                } | {
-                    entityType: string;
-                };
-                metadata: {
-                    sequenceNumber: number;
-                    prevEventHash?: string;
-                    checksum?: string;
-                };
-            }[];
+            events: components["schemas"]["StoredEventResponse"][];
             total: number;
             annotationId: string;
             resourceId: string;
@@ -3503,21 +3731,7 @@ interface components {
             entityTypes: string[];
         };
         GetEventsResponse: {
-            events: {
-                event: {
-                    id: string;
-                    type: string;
-                    timestamp: string;
-                    userId: string;
-                    resourceId: string;
-                    payload?: unknown;
-                };
-                metadata: {
-                    sequenceNumber: number;
-                    prevEventHash?: string;
-                    checksum?: string;
-                };
-            }[];
+            events: components["schemas"]["StoredEventResponse"][];
             total: number;
             resourceId: string;
         };
@@ -3721,7 +3935,7 @@ interface components {
              * @description Application-specific: How this resource was created
              * @enum {string}
              */
-            creationMethod?: "api" | "upload" | "ui" | "reference" | "clone" | "generated";
+            creationMethod?: "api" | "upload" | "ui" | "reference" | "cli" | "clone" | "generated";
             /** @description Application-specific: ID of annotation that triggered generation */
             sourceAnnotationId?: string;
             /** @description Application-specific: ID of source resource for clones/derivatives */
@@ -3886,39 +4100,272 @@ interface components {
             /** @description The validated JWT token string for the current session */
             token: string;
         };
-        SvgSelector: {
-            /** @enum {string} */
-            type: "SvgSelector";
-            /** @description SVG markup defining the region (must include xmlns attribute) */
-            value: string;
+        /** @description Emitted when an annotation receives focus for beckoning */
+        BeckonFocusEvent: {
+            annotationId?: string;
+            resourceId?: string;
         };
-        /** @description W3C Web Annotation FragmentSelector for media fragment identifiers (RFC 3778 for PDFs) */
-        FragmentSelector: {
-            /** @enum {string} */
-            type: "FragmentSelector";
-            /**
-             * @description Media fragment identifier (e.g., 'page=1&viewrect=100,200,50,30' for PDF)
-             * @example page=1&viewrect=100,200,50,30
-             */
-            value: string;
-            /**
-             * @description URI identifying the fragment syntax specification
-             * @example http://tools.ietf.org/rfc/rfc3778
-             */
-            conformsTo?: string;
+        /** @description Emitted when an annotation is hovered over for beckoning */
+        BeckonHoverEvent: {
+            annotationId: string | null;
         };
-        /**
-         * @description W3C Web Annotation body purpose vocabulary - https://www.w3.org/TR/annotation-vocab/#motivation
+        /** @description Emitted when a sparkle effect is triggered on an annotation */
+        BeckonSparkleEvent: {
+            annotationId: string;
+        };
+        /** @description Event payload emitted on the bind:body-updated bus channel after annotation bodies are modified. */
+        BindBodyUpdated: {
+            /** @description Branded AnnotationId of the annotation whose body was updated */
+            annotationId: string;
+        };
+        /** @description Command payload sent on the bind:initiate bus channel to start a bind flow. */
+        BindInitiateCommand: {
+            /** @description Branded AnnotationId of the annotation being bound */
+            annotationId: string;
+            /** @description Branded ResourceId of the resource being bound to */
+            resourceId: string;
+            /** @description Default title for the bound annotation */
+            defaultTitle: string;
+            /** @description Entity types to associate with the annotation */
+            entityTypes: string[];
+        };
+        /** @description Command payload sent on the bind:update-body bus channel to modify annotation bodies. */
+        BindUpdateBodyCommand: {
+            /** @description Client-supplied id used to match this command to its result event(s) on the events-stream. Generated by the route handler if absent. */
+            correlationId: string;
+            /** @description Branded AnnotationId of the annotation whose body is being updated */
+            annotationId: string;
+            /** @description Branded ResourceId of the resource the annotation belongs to */
+            resourceId: string;
+            /** @description Branded UserId of the user performing the update */
+            userId?: string;
+            /** @description List of body mutation operations to apply */
+            operations: {
+                /**
+                 * @description The type of body operation
+                 * @enum {string}
+                 */
+                op: "add" | "remove" | "replace";
+                /** @description Body item for add operations */
+                item?: components["schemas"]["AnnotationBody"];
+                /** @description Previous body item for replace operations */
+                oldItem?: components["schemas"]["AnnotationBody"];
+                /** @description Replacement body item for replace operations */
+                newItem?: components["schemas"]["AnnotationBody"];
+            }[];
+        };
+        /**
+         * @description W3C Web Annotation body purpose vocabulary - https://www.w3.org/TR/annotation-vocab/#motivation
          * @enum {string}
          */
         BodyPurpose: "assessing" | "bookmarking" | "classifying" | "commenting" | "describing" | "editing" | "highlighting" | "identifying" | "linking" | "moderating" | "questioning" | "replying" | "tagging";
-        MediaTokenRequest: {
-            /** @description The resource ID to generate a media token for */
+        /** @description Request to browse the history of an annotation */
+        BrowseAnnotationHistoryRequest: {
+            correlationId: string;
             resourceId: string;
+            annotationId: string;
         };
-        MediaTokenResponse: {
-            /** @description Short-lived media token for use as ?token= query parameter on resource URLs */
-            token: string;
+        /** @description Result of browsing annotation history */
+        BrowseAnnotationHistoryResult: {
+            correlationId: string;
+            response: components["schemas"]["GetAnnotationHistoryResponse"];
+        };
+        /** @description Request to browse a single annotation */
+        BrowseAnnotationRequest: {
+            correlationId: string;
+            resourceId: string;
+            annotationId: string;
+        };
+        /** @description Result of browsing a single annotation */
+        BrowseAnnotationResult: {
+            correlationId: string;
+            response: components["schemas"]["GetAnnotationResponse"];
+        };
+        /** @description Request to browse annotations for a resource */
+        BrowseAnnotationsRequest: {
+            correlationId: string;
+            resourceId: string;
+        };
+        /** @description Result of browsing annotations for a resource */
+        BrowseAnnotationsResult: {
+            correlationId: string;
+            response: components["schemas"]["GetAnnotationsResponse"];
+        };
+        /** @description Emitted when an annotation is clicked in the browse panel */
+        BrowseClickEvent: {
+            annotationId: string;
+            motivation: components["schemas"]["Motivation"];
+        };
+        /** @description Request to browse a directory listing */
+        BrowseDirectoryRequest: {
+            correlationId: string;
+            path: string;
+            /** @enum {string} */
+            sort?: "name" | "mtime" | "annotationCount";
+        };
+        /** @description Result of browsing a directory listing */
+        BrowseDirectoryResult: {
+            correlationId: string;
+            response: {
+                path: string;
+                entries: components["schemas"]["DirectoryEntry"][];
+            };
+        };
+        /** @description Emitted when an entity type is clicked in the browse panel */
+        BrowseEntityTypeClickedEvent: {
+            entityType: string;
+        };
+        /** @description Request to browse available entity types */
+        BrowseEntityTypesRequest: {
+            correlationId: string;
+        };
+        /** @description Result of browsing entity types */
+        BrowseEntityTypesResult: {
+            correlationId: string;
+            response: components["schemas"]["GetEntityTypesResponse"];
+        };
+        /** @description Request to browse events for a resource */
+        BrowseEventsRequest: {
+            correlationId: string;
+            resourceId: string;
+            type?: string;
+            userId?: string;
+            limit?: number;
+        };
+        /** @description Result of browsing events for a resource */
+        BrowseEventsResult: {
+            correlationId: string;
+            response: components["schemas"]["GetEventsResponse"];
+        };
+        /** @description Emitted when navigation to an external URL is requested */
+        BrowseExternalNavigateEvent: {
+            url: string;
+            resourceId?: string;
+        };
+        /** @description Emitted when a link is clicked in the browse panel */
+        BrowseLinkClickedEvent: {
+            href: string;
+            label?: string;
+        };
+        /** @description Emitted when a browse panel is opened */
+        BrowsePanelOpenEvent: {
+            panel: string;
+            scrollToAnnotationId?: string;
+            motivation?: string;
+        };
+        /** @description Emitted when a browse panel is toggled */
+        BrowsePanelToggleEvent: {
+            panel: string;
+        };
+        /** @description Request to browse annotations that reference a resource */
+        BrowseReferencedByRequest: {
+            correlationId: string;
+            resourceId: string;
+            motivation?: string;
+        };
+        /** @description Result of browsing annotations that reference a resource */
+        BrowseReferencedByResult: {
+            correlationId: string;
+            response: components["schemas"]["GetReferencedByResponse"];
+        };
+        /** @description Emitted when navigation to a reference resource is requested */
+        BrowseReferenceNavigateEvent: {
+            resourceId: string;
+        };
+        /** @description Emitted when a resource is closed in the browse panel */
+        BrowseResourceCloseEvent: {
+            resourceId: string;
+        };
+        /** @description Emitted when resources are reordered in the browse panel */
+        BrowseResourceReorderEvent: {
+            oldIndex: number;
+            newIndex: number;
+        };
+        /** @description Request to browse a single resource */
+        BrowseResourceRequest: {
+            correlationId: string;
+            resourceId: string;
+        };
+        /** @description Result of browsing a single resource */
+        BrowseResourceResult: {
+            correlationId: string;
+            response: components["schemas"]["GetResourceResponse"];
+        };
+        /** @description Request to browse resources with optional filtering and pagination */
+        BrowseResourcesRequest: {
+            correlationId: string;
+            search?: string;
+            archived?: boolean;
+            entityType?: string;
+            offset?: number;
+            limit?: number;
+        };
+        /** @description Result of browsing resources */
+        BrowseResourcesResult: {
+            correlationId: string;
+            response: components["schemas"]["ListResourcesResponse"];
+        };
+        /** @description Emitted when the browse panel requests a router navigation */
+        BrowseRouterPushEvent: {
+            path: string;
+            reason?: string;
+        };
+        /** @description Command to store a computed embedding for a resource chunk */
+        EmbeddingComputeCommand: {
+            resourceId: string;
+            annotationId?: string;
+            chunkIndex: number;
+            chunkText: string;
+            embedding: number[];
+            model: string;
+            dimensions: number;
+        };
+        /** @description Command to delete embeddings for a resource or annotation */
+        EmbeddingDeleteCommand: {
+            resourceId: string;
+            annotationId?: string;
+        };
+        /** @description W3C Web Annotation FragmentSelector for media fragment identifiers (RFC 3778 for PDFs) */
+        FragmentSelector: {
+            /** @enum {string} */
+            type: "FragmentSelector";
+            /**
+             * @description Media fragment identifier (e.g., 'page=1&viewrect=100,200,50,30' for PDF)
+             * @example page=1&viewrect=100,200,50,30
+             */
+            value: string;
+            /**
+             * @description URI identifying the fragment syntax specification
+             * @example http://tools.ietf.org/rfc/rfc3778
+             */
+            conformsTo?: string;
+        };
+        /** @description Completion payload emitted on the gather:annotation-complete bus channel when annotation context gathering finishes. */
+        GatherAnnotationComplete: {
+            /** @description Client-generated correlation ID to thread the response back to the originating request */
+            correlationId: string;
+            /** @description Branded AnnotationId of the annotation whose context was gathered */
+            annotationId: string;
+            /** @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. */
+        GatherAnnotationRequest: {
+            /** @description Client-generated correlation ID to thread the response back to the originating request */
+            correlationId: string;
+            /** @description Branded AnnotationId of the annotation to gather context for */
+            annotationId: string;
+            /** @description Branded ResourceId of the resource the annotation belongs to */
+            resourceId: string;
+            /** @description Optional gathering configuration */
+            options?: {
+                /** @description Whether to include source context in the gathered result */
+                includeSourceContext?: boolean;
+                /** @description Whether to include target context in the gathered result */
+                includeTargetContext?: boolean;
+                /** @description Characters of surrounding text context to include */
+                contextWindow?: number;
+            };
         };
         /** @description Context gathered for an annotation. Includes source document excerpts, metadata, and graph-derived context. Used by both Find (bind) and Generate (yield) flows. */
         GatheredContext: {
@@ -3981,18 +4428,383 @@ interface components {
                 similar: components["schemas"]["SemanticMatch"][];
             };
         };
-        MatchSearchStreamRequest: {
+        /** @description Completion payload emitted on the gather:resource-complete bus channel when resource context gathering finishes. */
+        GatherResourceComplete: {
             /** @description Client-generated correlation ID to thread the response back to the originating request */
+            correlationId: string;
+            /** @description Branded ResourceId of the resource whose context was gathered */
+            resourceId: string;
+            /** @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. */
+        GatherResourceRequest: {
+            /** @description Client-generated correlation ID to thread the response back to the originating request */
+            correlationId: string;
+            /** @description Branded ResourceId of the resource to gather context for */
+            resourceId: string;
+            /** @description Gathering configuration */
+            options: {
+                /** @description Depth of resource graph traversal */
+                depth: number;
+                /** @description Maximum number of related resources to include */
+                maxResources: number;
+                /** @description Whether to include resource content in the gathered result */
+                includeContent: boolean;
+                /** @description Whether to include resource summaries in the gathered result */
+                includeSummary: boolean;
+            };
+        };
+        /** @description Result of a completed assessment-annotation job. */
+        JobAssessmentAnnotationResult: {
+            assessmentsFound: number;
+            assessmentsCreated: number;
+        };
+        /** @description Request to cancel a job */
+        JobCancelRequest: {
+            /** @enum {string} */
+            jobType: "annotation" | "generation";
+        };
+        /** @description Result of a completed comment-annotation job. */
+        JobCommentAnnotationResult: {
+            commentsFound: number;
+            commentsCreated: number;
+        };
+        /** @description Command to mark a job as complete */
+        JobCompleteCommand: {
+            resourceId: string;
+            userId: string;
+            jobId: string;
+            jobType: components["schemas"]["JobType"];
+            result?: components["schemas"]["JobResult"];
+        };
+        /** @description Command to mark a job as failed */
+        JobFailCommand: {
+            resourceId: string;
+            userId: string;
+            jobId: string;
+            jobType: components["schemas"]["JobType"];
+            error: string;
+        };
+        /** @description Result of a completed generation job. */
+        JobGenerationResult: {
+            /** @description ID of the generated resource */
+            resourceId: string;
+            /** @description Name of the generated resource */
+            resourceName: string;
+        };
+        /** @description Result of a completed highlight-annotation job. */
+        JobHighlightAnnotationResult: {
+            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. */
+        JobProgress: {
+            /** @description Current processing stage */
+            stage: string;
+            /** @description Completion percentage (0-100) */
+            percentage: number;
+            /** @description Human-readable progress message */
+            message: string;
+            /** @description Total entity types to process (reference-annotation) */
+            totalEntityTypes?: number;
+            /** @description Entity types processed so far (reference-annotation) */
+            processedEntityTypes?: number;
+            /** @description Entities found so far (reference-annotation) */
+            entitiesFound?: number;
+            /** @description Annotations emitted so far (reference-annotation) */
+            entitiesEmitted?: number;
+            /** @description Entity type currently being processed */
+            currentEntityType?: string;
+            /** @description Categories processed (tag-annotation) */
+            processedCategories?: number;
+            /** @description Total categories (tag-annotation) */
+            totalCategories?: number;
+            /** @description Category currently being processed (tag-annotation) */
+            currentCategory?: string;
+        };
+        /** @description Event indicating a job has been queued */
+        JobQueuedEvent: {
+            jobId: string;
+            jobType: string;
+            resourceId: string;
+        };
+        /** @description Result of a completed reference-annotation job. */
+        JobReferenceAnnotationResult: {
+            /** @description Total entities found */
+            totalFound: number;
+            /** @description Total annotations emitted */
+            totalEmitted: number;
+            /** @description Number of errors encountered */
+            errors: number;
+        };
+        /** @description Command to report progress on a job */
+        JobReportProgressCommand: {
+            resourceId: string;
+            userId: string;
+            jobId: string;
+            jobType: components["schemas"]["JobType"];
+            percentage: number;
+            progress?: components["schemas"]["JobProgress"];
+        };
+        /** @description Discriminated union of all job result types. */
+        JobResult: components["schemas"]["JobGenerationResult"] | components["schemas"]["JobReferenceAnnotationResult"] | components["schemas"]["JobHighlightAnnotationResult"] | components["schemas"]["JobAssessmentAnnotationResult"] | components["schemas"]["JobCommentAnnotationResult"] | components["schemas"]["JobTagAnnotationResult"];
+        /** @description Command to start a job */
+        JobStartCommand: {
+            resourceId: string;
+            userId: string;
+            jobId: string;
+            jobType: components["schemas"]["JobType"];
+        };
+        /** @description Request to check the status of a job */
+        JobStatusRequest: {
+            correlationId: string;
+            jobId: string;
+        };
+        /** @description Result of a job status request */
+        JobStatusResult: {
+            correlationId: string;
+            response: components["schemas"]["JobStatusResponse"];
+        };
+        /** @description Result of a completed tag-annotation job. */
+        JobTagAnnotationResult: {
+            tagsFound: number;
+            tagsCreated: number;
+            /** @description Count of tags created per category */
+            byCategory: {
+                [key: string]: number;
+            };
+        };
+        /** @description Bus command to add a new entity type tag. */
+        MarkAddEntityTypeCommand: {
+            tag: string;
+            userId: string;
+        };
+        /** @description Bus command to archive a resource and optionally remove its file. */
+        MarkArchiveCommand: {
+            userId?: string;
+            resourceId: string;
+            storageUri?: string;
+            keepFile?: boolean;
+            noGit?: boolean;
+        };
+        /** @description Emitted when the user requests AI assistance for a mark */
+        MarkAssistRequestEvent: {
+            /** @description Client-supplied id used to match this command to its result event(s) on the events-stream. Generated by the route handler if absent. */
+            correlationId?: string;
+            motivation: components["schemas"]["Motivation"];
+            options: {
+                instructions?: string;
+                /** @enum {string} */
+                tone?: "scholarly" | "explanatory" | "conversational" | "technical" | "analytical" | "critical" | "balanced" | "constructive";
+                density?: number;
+                language?: string;
+                entityTypes?: string[];
+                includeDescriptiveReferences?: boolean;
+                schemaId?: string;
+                categories?: string[];
+            };
+        };
+        /** @description Emitted when the mark click action changes */
+        MarkClickChangedEvent: {
+            action: string;
+        };
+        /** @description Bus command to create an annotation on a resource. */
+        MarkCreateCommand: {
+            annotation: components["schemas"]["Annotation"];
+            userId: string;
+            resourceId: string;
+        };
+        /** @description Success response after creating an annotation. */
+        MarkCreateOk: {
+            annotationId: string;
+        };
+        /** @description Bus command to delete an annotation. */
+        MarkDeleteCommand: {
+            annotationId: string;
+            userId?: string;
+            resourceId?: string;
+        };
+        /** @description Success response after deleting an annotation. */
+        MarkDeleteOk: {
+            annotationId: string;
+        };
+        /** @description Emitted when the user requests a new mark (annotation) on a resource */
+        MarkRequestedEvent: {
+            /** @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"])[];
+            motivation: components["schemas"]["Motivation"];
+        };
+        /** @description Emitted when the active mark selection changes */
+        MarkSelectionChangedEvent: {
+            motivation: string | null;
+        };
+        /** @description Emitted when the mark shape changes */
+        MarkShapeChangedEvent: {
+            shape: string;
+        };
+        /** @description Emitted when a mark is submitted with its annotation body */
+        MarkSubmitEvent: {
+            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 Bus command to unarchive a previously archived resource. */
+        MarkUnarchiveCommand: {
+            userId?: string;
+            resourceId: string;
+            storageUri?: string;
+        };
+        /** @description Bus command to update an annotation's body with patch operations. */
+        MarkUpdateBodyCommand: {
+            /** @description Correlation id threaded from the originating route through to event metadata. Lets the events-stream deliver matched results to the client that initiated the bind. */
             correlationId?: string;
+            annotationId: string;
+            userId: string;
+            resourceId: string;
+            operations: (components["schemas"]["BodyOperationAdd"] | components["schemas"]["BodyOperationRemove"] | components["schemas"]["BodyOperationReplace"])[];
+        };
+        /** @description Bus command to replace the entity types on a resource. */
+        MarkUpdateEntityTypesCommand: {
+            resourceId: string;
+            userId: string;
+            currentEntityTypes: string[];
+            updatedEntityTypes: string[];
+        };
+        /** @description Request payload sent on the match:search-request bus channel to find candidate matches. */
+        MatchSearchRequest: {
+            /** @description Client-generated correlation ID to thread the response back to the originating request */
+            correlationId: string;
+            /** @description Resource ID the reference annotation belongs to. Used to scope result events on the EventBus so the events-stream delivers them to participants viewing this resource. */
+            resourceId: string;
             /** @description Annotation ID of the reference to search candidates for */
             referenceId: string;
             /** @description Gathered context for the reference annotation */
             context: components["schemas"]["GatheredContext"];
-            /** @description Maximum number of candidate results to return (default: 10) */
+            /** @description Maximum number of candidate results to return */
             limit?: number;
-            /** @description Enable semantic similarity scoring in addition to keyword matching (default: true) */
+            /** @description Enable semantic similarity scoring in addition to keyword matching */
             useSemanticScoring?: boolean;
         };
+        MediaTokenRequest: {
+            /** @description The resource ID to generate a media token for */
+            resourceId: string;
+        };
+        MediaTokenResponse: {
+            /** @description Short-lived media token for use as ?token= query parameter on resource URLs */
+            token: string;
+        };
+        /** @description Emitted when the hover delay setting changes */
+        SettingsHoverDelayChangedEvent: {
+            hoverDelayMs: number;
+        };
+        /** @description Emitted when the UI locale setting changes */
+        SettingsLocaleChangedEvent: {
+            locale: string;
+        };
+        /** @description Emitted when the UI theme setting changes */
+        SettingsThemeChangedEvent: {
+            /** @enum {string} */
+            theme: "light" | "dark" | "system";
+        };
+        SvgSelector: {
+            /** @enum {string} */
+            type: "SvgSelector";
+            /** @description SVG markup defining the region (must include xmlns attribute) */
+            value: string;
+        };
+        /** @description Bus command to create a cloned resource from a clone token. */
+        YieldCloneCreateCommand: {
+            correlationId: string;
+            token: string;
+            name: string;
+            content: string;
+            userId: string;
+            archiveOriginal?: boolean;
+        };
+        /** @description Success response after creating a cloned resource. */
+        YieldCloneCreated: {
+            correlationId: string;
+            response: {
+                resourceId?: string;
+            };
+        };
+        /** @description Bus command to request cloning a resource using a clone token. */
+        YieldCloneResourceRequest: {
+            correlationId: string;
+            token: string;
+        };
+        /** @description Bus command to request a clone token for a resource. */
+        YieldCloneTokenRequest: {
+            correlationId: string;
+            resourceId: string;
+        };
+        /** @description Bus command to create a yielded resource in the knowledge base. */
+        YieldCreateCommand: {
+            name: string;
+            storageUri: string;
+            contentChecksum: string;
+            byteSize: number;
+            format: components["schemas"]["ContentFormat"];
+            userId: string;
+            language?: string;
+            entityTypes?: string[];
+            creationMethod?: string;
+            isDraft?: boolean;
+            generatedFrom?: {
+                resourceId?: string;
+                annotationId?: string;
+            };
+            generationPrompt?: string;
+            generator?: components["schemas"]["Agent"] | components["schemas"]["Agent"][];
+            noGit?: boolean;
+        };
+        /** @description Success response after creating a yielded resource. */
+        YieldCreateOk: {
+            resourceId: string;
+            resource: components["schemas"]["ResourceDescriptor"];
+        };
+        /** @description Success response after moving a yielded resource. */
+        YieldMoveOk: {
+            resourceId: string;
+        };
+        /** @description Bus command to move (rename) a yielded resource. */
+        YieldMvCommand: {
+            fromUri: string;
+            toUri: string;
+            userId: string;
+            noGit?: boolean;
+        };
+        /** @description Bus command to request yield (generation) of a new resource from an annotation. */
+        YieldRequestCommand: {
+            /** @description Client-supplied id used to match this command to its result event(s) on the events-stream. Generated by the route handler if absent. */
+            correlationId?: string;
+            annotationId: string;
+            resourceId: string;
+            options: {
+                title: string;
+                prompt?: string;
+                language?: string;
+                temperature?: number;
+                maxTokens?: number;
+                context?: components["schemas"]["GatheredContext"];
+                storageUri: string;
+            };
+        };
+        /** @description Bus command to update a yielded resource's storage content. */
+        YieldUpdateCommand: {
+            resourceId: string;
+            storageUri: string;
+            contentChecksum: string;
+            byteSize: number;
+            userId: string;
+            noGit?: boolean;
+        };
+        /** @description Success response after updating a yielded resource. */
+        YieldUpdateOk: {
+            resourceId: string;
+        };
     };
     responses: never;
     parameters: never;
@@ -4009,8 +4821,8 @@ type operations = Record<string, never>;
  * different string types at compile time.
  */
 
-type Motivation$2 = components['schemas']['Motivation'];
-type ContentFormat$1 = components['schemas']['ContentFormat'];
+type Motivation = components['schemas']['Motivation'];
+type ContentFormat = components['schemas']['ContentFormat'];
 type Email = string & {
     readonly __brand: 'Email';
 };
@@ -4083,6 +4895,7 @@ declare const CREATION_METHODS: {
     readonly UPLOAD: "upload";
     readonly UI: "ui";
     readonly REFERENCE: "reference";
+    readonly CLI: "cli";
     readonly CLONE: "clone";
     readonly GENERATED: "generated";
 };
@@ -4120,13 +4933,13 @@ declare function userId(id: string): UserId;
  */
 
 type ResourceDescriptor = components['schemas']['ResourceDescriptor'];
-type Annotation$5 = components['schemas']['Annotation'];
+type Annotation$4 = components['schemas']['Annotation'];
 /**
  * Represents a connection between resources through annotations
  */
 interface GraphConnection {
     targetResource: ResourceDescriptor;
-    annotations: Annotation$5[];
+    annotations: Annotation$4[];
     relationshipType?: string;
     bidirectional: boolean;
 }
@@ -4135,7 +4948,7 @@ interface GraphConnection {
  */
 interface GraphPath {
     resources: ResourceDescriptor[];
-    annotations: Annotation$5[];
+    annotations: Annotation$4[];
 }
 /**
  * Statistics about entity types in the graph
@@ -4146,282 +4959,125 @@ interface EntityTypeStats {
 }
 
 /**
- * Resource Event Types
+ * Persisted Events
+ *
+ * The 20 event types that get appended to the JSONL event log.
+ * Each maps a type string to its OpenAPI payload schema.
+ * The PersistedEvent union derives from this catalog.
+ */
+
+/**
+ * Maps each persisted event type string to its OpenAPI payload schema.
+ * Single source of truth for "what events get written to the log."
+ */
+type PersistedEventCatalog = {
+    'yield:created': components['schemas']['ResourceCreatedPayload'];
+    'yield:cloned': components['schemas']['ResourceClonedPayload'];
+    'yield:updated': components['schemas']['ResourceUpdatedPayload'];
+    'yield:moved': components['schemas']['ResourceMovedPayload'];
+    'yield:representation-added': components['schemas']['RepresentationAddedPayload'];
+    'yield:representation-removed': components['schemas']['RepresentationRemovedPayload'];
+    'mark:added': components['schemas']['AnnotationAddedPayload'];
+    'mark:removed': components['schemas']['AnnotationRemovedPayload'];
+    'mark:body-updated': components['schemas']['AnnotationBodyUpdatedPayload'];
+    'mark:archived': components['schemas']['ResourceArchivedPayload'];
+    'mark:unarchived': components['schemas']['ResourceUnarchivedPayload'];
+    'mark:entity-tag-added': components['schemas']['EntityTagChangedPayload'];
+    'mark:entity-tag-removed': components['schemas']['EntityTagChangedPayload'];
+    'mark:entity-type-added': components['schemas']['EntityTypeAddedPayload'];
+    'job:started': components['schemas']['JobStartedPayload'];
+    'job:progress': components['schemas']['JobProgressPayload'];
+    'job:completed': components['schemas']['JobCompletedPayload'];
+    'job:failed': components['schemas']['JobFailedPayload'];
+    'embedding:computed': components['schemas']['EmbeddingComputedPayload'];
+    'embedding:deleted': components['schemas']['EmbeddingDeletedPayload'];
+};
+/** System event types — persisted events that have no resourceId. */
+type SystemEventType = 'mark:entity-type-added';
+/** Extract the concrete persisted event type for a given type string. */
+type EventOfType<K extends keyof PersistedEventCatalog> = K extends SystemEventType ? EventBase & {
+    type: K;
+    payload: PersistedEventCatalog[K];
+} : EventBase & {
+    type: K;
+    resourceId: ResourceId;
+    payload: PersistedEventCatalog[K];
+};
+/** The union of all 20 persisted event types. Discriminated on `type`. */
+type PersistedEvent = {
+    [K in keyof PersistedEventCatalog]: EventOfType<K>;
+}[keyof PersistedEventCatalog];
+type PersistedEventType = PersistedEvent['type'];
+/**
+ * Runtime list of every persisted event type.
+ *
+ * Single source of truth for code that needs to enumerate event types at
+ * runtime — most importantly the per-resource `events-stream` SSE route,
+ * which subscribes to all of them. The exhaustiveness check below makes
+ * it impossible to add a new member to `PersistedEventCatalog` without
+ * also adding it here: forgetting fails to typecheck rather than silently
+ * dropping the event from the events-stream.
+ */
+declare const PERSISTED_EVENT_TYPES: readonly ["yield:created", "yield:cloned", "yield:updated", "yield:moved", "yield:representation-added", "yield:representation-removed", "mark:added", "mark:removed", "mark:body-updated", "mark:archived", "mark:unarchived", "mark:entity-tag-added", "mark:entity-tag-removed", "mark:entity-type-added", "job:started", "job:progress", "job:completed", "job:failed", "embedding:computed", "embedding:deleted"];
+/** Input type for appendEvent — PersistedEvent without id/timestamp (assigned at persistence time). */
+type EventInput = Omit<PersistedEvent, 'id' | 'timestamp'>;
+
+/**
+ * Event Base Types
  *
- * Event-sourced architecture for resource state management
- * Events are stored in an append-only log (JSONL format)
+ * Core shapes for the event-sourced persistence model.
+ * EventBase is the common shape for all domain events.
+ * StoredEvent wraps an event with persistence metadata.
  *
- * Federation-ready design:
- * - resourceId uses content hashes (doc-sha256:...)
- * - userId uses DID format (did:web:org.com:users:alice)
- * - prevEventHash creates tamper-evident chains
- * - Optional signatures for cross-org verification
+ * These types are referenced by event-catalog.ts (domain events)
+ * and bus-protocol.ts (the full EventMap).
  */
 
-type Annotation$4 = components['schemas']['Annotation'];
-type ContentFormat = components['schemas']['ContentFormat'];
-type Motivation$1 = components['schemas']['Motivation'];
-interface BaseEvent {
+/**
+ * Narrow an OpenAPI-generated type by overriding specific fields with branded types.
+ *
+ * OpenAPI schemas use plain `string` for identifiers. TypeScript branded types
+ * (ResourceId, AnnotationId, UserId, JobId) add compile-time safety. Brand<T, B>
+ * takes the OpenAPI type T and replaces the fields listed in B with their branded
+ * counterparts, preserving all other fields from the schema.
+ *
+ * @example
+ * type MyCommand = Brand<components['schemas']['YieldCreateCommand'], { userId: UserId }>;
+ * // Result: YieldCreateCommand with userId narrowed from string to UserId
+ */
+type Brand<T, Overrides> = Omit<T, keyof Overrides> & Overrides;
+/** Fields common to ALL domain events (system and resource-scoped). */
+interface EventBase {
     id: string;
     timestamp: string;
     resourceId?: ResourceId;
     userId: UserId;
     version: number;
 }
-interface ResourceCreatedEvent extends BaseEvent {
-    type: 'resource.created';
-    payload: {
-        name: string;
-        format: ContentFormat;
-        contentChecksum: string;
-        contentByteSize?: number;
-        creationMethod: CreationMethod;
-        entityTypes?: string[];
-        storageUri?: string;
-        language?: string;
-        isDraft?: boolean;
-        generatedFrom?: {
-            resourceId: string;
-            annotationId: string;
-        };
-        generationPrompt?: string;
-        generator?: components['schemas']['Agent'] | components['schemas']['Agent'][];
-    };
-}
-interface ResourceClonedEvent extends BaseEvent {
-    type: 'resource.cloned';
-    payload: {
-        name: string;
-        format: ContentFormat;
-        contentChecksum: string;
-        contentByteSize?: number;
-        parentResourceId: string;
-        creationMethod: CreationMethod;
-        entityTypes?: string[];
-        language?: string;
-    };
-}
-interface ResourceArchivedEvent extends BaseEvent {
-    type: 'resource.archived';
-    payload: {
-        reason?: string;
-    };
-}
-interface ResourceUnarchivedEvent extends BaseEvent {
-    type: 'resource.unarchived';
-    payload: Record<string, never>;
-}
-interface ResourceUpdatedEvent extends BaseEvent {
-    type: 'resource.updated';
-    resourceId: ResourceId;
-    payload: {
-        contentChecksum: string;
-        contentByteSize?: number;
-    };
-}
-interface ResourceMovedEvent extends BaseEvent {
-    type: 'resource.moved';
-    resourceId: ResourceId;
-    payload: {
-        fromUri: string;
-        toUri: string;
-    };
-}
-interface RepresentationAddedEvent extends BaseEvent {
-    type: 'representation.added';
-    resourceId: ResourceId;
-    payload: {
-        representation: {
-            '@id': string;
-            mediaType: string;
-            byteSize: number;
-            checksum: string;
-            created: string;
-            rel?: 'original' | 'thumbnail' | 'preview' | 'optimized' | 'derived' | 'other';
-            storageUri?: string;
-            filename?: string;
-            language?: string;
-            width?: number;
-            height?: number;
-            duration?: number;
-        };
-    };
-}
-interface RepresentationRemovedEvent extends BaseEvent {
-    type: 'representation.removed';
-    resourceId: ResourceId;
-    payload: {
-        checksum: string;
-    };
-}
-interface AnnotationAddedEvent extends BaseEvent {
-    type: 'annotation.added';
-    payload: {
-        annotation: Annotation$4;
-        contentChecksum?: string;
-    };
-}
-interface AnnotationRemovedEvent extends BaseEvent {
-    type: 'annotation.removed';
-    payload: {
-        annotationId: AnnotationId;
-    };
-}
-type BodyItem = {
-    type: 'TextualBody';
-    value: string;
-    purpose?: Motivation$1;
-    format?: string;
-    language?: string;
-} | {
-    type: 'SpecificResource';
-    source: string;
-    purpose?: Motivation$1;
-};
-type BodyOperation = {
-    op: 'add';
-    item: BodyItem;
-} | {
-    op: 'remove';
-    item: BodyItem;
-} | {
-    op: 'replace';
-    oldItem: BodyItem;
-    newItem: BodyItem;
-};
-interface AnnotationBodyUpdatedEvent extends BaseEvent {
-    type: 'annotation.body.updated';
-    payload: {
-        annotationId: AnnotationId;
-        operations: BodyOperation[];
-    };
-}
-interface JobStartedEvent extends BaseEvent {
-    type: 'job.started';
-    resourceId: ResourceId;
-    payload: {
-        jobId: JobId;
-        jobType: 'reference-annotation' | 'generation' | 'highlight-annotation' | 'assessment-annotation' | 'comment-annotation' | 'tag-annotation';
-        totalSteps?: number;
-    };
-}
-interface JobProgressEvent extends BaseEvent {
-    type: 'job.progress';
-    resourceId: ResourceId;
-    payload: {
-        jobId: JobId;
-        jobType: 'reference-annotation' | 'generation' | 'highlight-annotation' | 'assessment-annotation' | 'comment-annotation' | 'tag-annotation';
-        percentage: number;
-        currentStep?: string;
-        processedSteps?: number;
-        totalSteps?: number;
-        foundCount?: number;
-        message?: string;
-        progress?: any;
-    };
-}
-interface JobCompletedEvent extends BaseEvent {
-    type: 'job.completed';
-    resourceId: ResourceId;
-    payload: {
-        jobId: JobId;
-        jobType: 'reference-annotation' | 'generation' | 'highlight-annotation' | 'assessment-annotation' | 'comment-annotation' | 'tag-annotation';
-        totalSteps?: number;
-        foundCount?: number;
-        resultResourceId?: ResourceId;
-        annotationUri?: AnnotationUri;
-        message?: string;
-        result?: any;
-    };
-}
-interface JobFailedEvent extends BaseEvent {
-    type: 'job.failed';
-    resourceId: ResourceId;
-    payload: {
-        jobId: JobId;
-        jobType: 'reference-annotation' | 'generation' | 'highlight-annotation' | 'assessment-annotation' | 'comment-annotation' | 'tag-annotation';
-        error: string;
-        details?: string;
-    };
-}
-interface EntityTagAddedEvent extends BaseEvent {
-    type: 'entitytag.added';
-    resourceId: ResourceId;
-    payload: {
-        entityType: string;
-    };
-}
-interface EntityTagRemovedEvent extends BaseEvent {
-    type: 'entitytag.removed';
-    resourceId: ResourceId;
-    payload: {
-        entityType: string;
-    };
-}
-interface EmbeddingComputedEvent extends BaseEvent {
-    type: 'embedding.computed';
-    resourceId: ResourceId;
-    payload: {
-        annotationId?: AnnotationId;
-        chunkIndex: number;
-        chunkText: string;
-        embedding: number[];
-        model: string;
-        dimensions: number;
-    };
-}
-interface EmbeddingDeletedEvent extends BaseEvent {
-    type: 'embedding.deleted';
-    resourceId: ResourceId;
-    payload: {
-        annotationId?: AnnotationId;
-    };
-}
-interface EntityTypeAddedEvent extends BaseEvent {
-    type: 'entitytype.added';
-    resourceId?: undefined;
-    payload: {
-        entityType: string;
-    };
-}
-type ResourceEvent = ResourceCreatedEvent | ResourceClonedEvent | ResourceUpdatedEvent | ResourceMovedEvent | ResourceArchivedEvent | ResourceUnarchivedEvent | RepresentationAddedEvent | RepresentationRemovedEvent | AnnotationAddedEvent | AnnotationRemovedEvent | AnnotationBodyUpdatedEvent | JobStartedEvent | JobProgressEvent | JobCompletedEvent | JobFailedEvent | EntityTagAddedEvent | EntityTagRemovedEvent | EntityTypeAddedEvent | EmbeddingComputedEvent | EmbeddingDeletedEvent;
-type ResourceEventType = ResourceEvent['type'];
-type SystemEvent = EntityTypeAddedEvent;
-type ResourceScopedEvent = Exclude<ResourceEvent, SystemEvent>;
-declare function isResourceEvent$1(event: any): event is ResourceEvent;
-/**
- * Type guard: Check if event is system-level (no resourceId)
- * System events affect global state, not individual resources
- */
-declare function isSystemEvent(event: ResourceEvent): event is SystemEvent;
-/**
- * Type guard: Check if event is resource-scoped (has resourceId)
- * Resource events affect a specific resource's state
- */
-declare function isResourceScopedEvent(event: ResourceEvent): event is ResourceScopedEvent;
-declare function getEventType<T extends ResourceEvent>(event: ResourceEvent): T['type'];
-interface EventMetadata {
-    sequenceNumber: number;
-    streamPosition: number;
-    timestamp: string;
-    prevEventHash?: string;
-    checksum?: string;
-}
+/** Persistence metadata attached to every stored event. */
+type EventMetadata = components['schemas']['EventMetadata'];
+/** Optional cryptographic signature on a stored event. */
 interface EventSignature {
     algorithm: 'ed25519';
     publicKey: string;
     signature: string;
     keyId?: string;
 }
-interface StoredEvent<T extends ResourceEvent = ResourceEvent> {
-    event: T;
+/**
+ * A domain event with persistence metadata.
+ * Flat intersection — no nesting (event.type, not event.event.type).
+ */
+type StoredEvent<T extends EventBase = PersistedEvent> = T & {
     metadata: EventMetadata;
     signature?: EventSignature;
-}
+};
+type BodyItem = components['schemas']['TextualBody'] | components['schemas']['SpecificResource'];
+type BodyOperation = components['schemas']['BodyOperationAdd'] | components['schemas']['BodyOperationRemove'] | components['schemas']['BodyOperationReplace'];
+type Annotation$3 = components['schemas']['Annotation'];
 interface EventQuery {
     resourceId?: ResourceId;
     userId?: string;
-    eventTypes?: ResourceEvent['type'][];
+    eventTypes?: string[];
     fromTimestamp?: string;
     toTimestamp?: string;
     fromSequence?: number;
@@ -4429,768 +5085,302 @@ interface EventQuery {
 }
 interface ResourceAnnotations {
     resourceId: ResourceId;
-    annotations: Annotation$4[];
+    annotations: Annotation$3[];
     version: number;
     updatedAt: string;
 }
 
 /**
- * Event Type Guards and Extraction Utilities
+ * Bus Protocol
  *
- * Domain logic for working with resource events.
- * No React dependencies - safe to use in any JavaScript environment.
- */
-
-/**
- * Minimal event shape accepted by event utility functions.
- * Compatible with both the internal `StoredEvent` type and the OpenAPI-derived
- * schema type (`GetEventsResponse['events'][number]`), which lacks `version`
- * on the inner event.
- */
-interface StoredEventLike {
-    event: {
-        id: string;
-        type: string;
-        timestamp: string;
-        userId: string;
-        resourceId?: string;
-        payload?: unknown;
-    };
-    metadata: {
-        sequenceNumber: number;
-        prevEventHash?: string;
-        checksum?: string;
-    };
-}
-/**
- * Extract annotation ID from event payload
- * Returns null if event is not annotation-related
+ * The complete EventMap for the RxJS EventBus. Every channel name and
+ * its payload type is defined here — domain events, commands, reads,
+ * results, SSE stream payloads, and frontend UI events.
  *
- * For annotation.added: extracts full URI from payload.annotation.id
- * For annotation.removed/body.updated: constructs full URI from payload.annotationId (UUID) + resourceId
- */
-declare function getAnnotationUriFromEvent(event: StoredEventLike): AnnotationUri | null;
-/**
- * Check if an event is related to a specific annotation
- */
-declare function isEventRelatedToAnnotation(event: StoredEventLike, annotationUri: AnnotationUri): boolean;
-/**
- * Type guard to check if event is a resource event
- */
-declare function isResourceEvent(event: any): event is StoredEvent;
-
-/**
- * Event Protocol Types
+ * Command and result payloads use OpenAPI-generated types (plain strings
+ * for identifiers). Branded type safety (ResourceId, UserId, etc.) is
+ * enforced at function boundaries, not on bus payloads — callers use
+ * factory functions (resourceId(), userId()) at the consume boundary.
  *
- * Type definitions for the application's event-driven architecture.
- * Single source of truth for all EventBus event types.
+ * Domain events (StoredEvent<Interface>) retain branded types as they
+ * are the system of record, not wire-format payloads.
+ *
+ * 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 Annotation$3 = components['schemas']['Annotation'];
-type Motivation = components['schemas']['Motivation'];
-/**
- * Progress state for resource yield workflow
- */
-interface YieldProgress {
-    status: 'started' | 'fetching' | 'generating' | 'creating' | 'complete' | 'error';
-    referenceId: string;
-    resourceName?: string;
-    resourceId?: string;
-    sourceResourceId?: string;
-    percentage: number;
-    message?: string;
-}
-/**
- * Selection data for user-initiated annotations
- */
-interface SelectionData {
-    exact: string;
-    start: number;
-    end: number;
-    svgSelector?: string;
-    fragmentSelector?: string;
-    conformsTo?: string;
-    prefix?: string;
-    suffix?: string;
-}
-/**
- * Progress state for mark workflows (manual and assisted)
- *
- * Unified progress interface supporting different annotation strategies:
- * - Reference annotation: entity-type steps
- * - Other motivations: percentage-based progress
- */
-interface MarkProgress {
-    status: string;
-    message?: string;
-    /** Reference annotation: currently scanning entity type */
-    currentEntityType?: string;
-    /** Reference annotation: completed entity types with counts (frontend-only) */
-    completedEntityTypes?: Array<{
-        entityType: string;
-        foundCount: number;
-    }>;
-    /** Percentage-based motivations (highlight, assessment, comment, tag) */
-    percentage?: number;
-    /** Category-based motivations (tag) */
-    currentCategory?: string;
-    processedCategories?: number;
-    totalCategories?: number;
-    /** Request parameters for display in progress UI (frontend-only, added by annotation-registry) */
-    requestParams?: Array<{
-        label: string;
-        value: string;
-    }>;
-}
+type YieldProgress = components['schemas']['YieldProgress'];
+type MarkProgress = components['schemas']['MarkProgress'];
+type SelectionData = components['schemas']['SelectionData'];
 /**
- * Unified event map for all application events
- *
- * Organized by workflow ("flows") and actor sections:
- * 1. Yield Flow - Resource generation from references
- * 2. Mark Flow - Manual + AI-assisted annotation (all motivations)
- * 3. Bind Flow - Reference linking/resolution (search modal)
- * 4. Matcher Flow - Candidate search for bind/link operations
- * 5. Gather Flow - LLM context fetching from annotations
- * 6. Browse Flow - Panel, sidebar, and application routing
- * 7. Beckon Flow - Annotation hover/focus/sparkle coordination
+ * The unified EventMap — every channel on the EventBus.
  *
- * Plus infrastructure events (domain events, SSE, resource operations, settings)
+ * Convention:
+ * - Domain events (past tense): StoredEvent<Interface> — branded types
+ * - Commands/reads/results/UI: OpenAPI schema refs — plain strings
+ * - void: UI-only signals with no payload
  */
 type EventMap = {
-    'make-meaning:event': ResourceEvent;
-    'yield:request': {
-        annotationId: AnnotationId;
-        resourceId: ResourceId;
-        options: {
-            title: string;
-            prompt?: string;
-            language?: string;
-            temperature?: number;
-            maxTokens?: number;
-            context: GatheredContext;
-            storageUri: string;
-        };
-    };
-    'yield:progress': YieldProgress;
-    'yield:finished': YieldProgress;
-    'yield:failed': {
-        error?: Error | string;
-        status?: string;
-        referenceId?: string;
-        percentage?: number;
-        message?: string;
-    };
-    'yield:representation-added': Extract<ResourceEvent, {
-        type: 'representation.added';
-    }>;
-    'yield:representation-removed': Extract<ResourceEvent, {
-        type: 'representation.removed';
-    }>;
-    'yield:create': {
-        name: string;
-        content?: Buffer;
-        storageUri?: string;
-        contentChecksum?: string;
-        format: components['schemas']['ContentFormat'];
-        userId: UserId;
-        language?: string;
-        entityTypes?: string[];
-        creationMethod?: CreationMethod;
-        isDraft?: boolean;
-        generatedFrom?: {
-            resourceId: string;
-            annotationId: string;
-        };
-        generationPrompt?: string;
-        generator?: components['schemas']['Agent'] | components['schemas']['Agent'][];
-        noGit?: boolean;
-    };
-    'yield:created': {
-        resourceId: ResourceId;
-        resource: components['schemas']['ResourceDescriptor'];
-    };
-    'yield:create-failed': {
-        error: Error;
-    };
-    'yield:update': {
-        resourceId: ResourceId;
-        storageUri: string;
-        content?: Buffer;
-        contentChecksum: string;
-        userId: UserId;
-        noGit?: boolean;
-    };
-    'yield:updated': {
-        resourceId: ResourceId;
-    };
-    'yield:update-failed': {
-        resourceId: ResourceId;
-        error: Error;
-    };
-    'yield:mv': {
-        fromUri: string;
-        toUri: string;
-        userId: UserId;
-        noGit?: boolean;
-    };
-    'yield:moved': {
-        resourceId: ResourceId;
-    };
+    'yield:created': StoredEvent<EventOfType<'yield:created'>>;
+    'yield:cloned': StoredEvent<EventOfType<'yield:cloned'>>;
+    'yield:updated': StoredEvent<EventOfType<'yield:updated'>>;
+    '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'];
+    'yield:mv': components['schemas']['YieldMvCommand'];
+    'yield:clone': void;
+    'yield:clone-token-requested': components['schemas']['YieldCloneTokenRequest'];
+    'yield:clone-resource-requested': components['schemas']['YieldCloneResourceRequest'];
+    'yield:clone-create': components['schemas']['YieldCloneCreateCommand'];
+    'yield:create-ok': components['schemas']['YieldCreateOk'];
+    'yield:create-failed': components['schemas']['CommandError'];
+    'yield:update-ok': components['schemas']['YieldUpdateOk'];
+    'yield:update-failed': components['schemas']['YieldUpdateOk'] & components['schemas']['CommandError'];
+    'yield:move-ok': components['schemas']['YieldMoveOk'];
     'yield:move-failed': {
         fromUri: string;
-        error: Error;
-    };
-    'yield:clone': void;
-    'yield:clone-token-requested': {
-        correlationId: string;
-        resourceId: ResourceId;
-    };
+    } & components['schemas']['CommandError'];
     'yield:clone-token-generated': {
         correlationId: string;
         response: components['schemas']['CloneResourceWithTokenResponse'];
     };
     'yield:clone-token-failed': {
         correlationId: string;
-        error: Error;
-    };
-    'yield:clone-resource-requested': {
-        correlationId: string;
-        token: string;
-    };
+    } & components['schemas']['CommandError'];
     'yield:clone-resource-result': {
         correlationId: string;
         response: components['schemas']['GetResourceByTokenResponse'];
     };
     'yield:clone-resource-failed': {
         correlationId: string;
-        error: Error;
-    };
-    'yield:clone-create': {
-        correlationId: string;
-        token: string;
-        name: string;
-        content: string;
-        userId: UserId;
-        archiveOriginal?: boolean;
-    };
-    'yield:clone-created': {
-        correlationId: string;
-        response: {
-            resourceId: ResourceId;
-        };
-    };
+    } & components['schemas']['CommandError'];
+    'yield:clone-created': components['schemas']['YieldCloneCreated'];
     'yield:clone-create-failed': {
         correlationId: string;
-        error: Error;
-    };
-    'mark:select-comment': SelectionData;
-    'mark:select-tag': SelectionData;
-    'mark:select-assessment': SelectionData;
-    'mark:select-reference': SelectionData;
-    'mark:requested': {
-        selector: Selector | Selector[];
-        motivation: Motivation;
-    };
+    } & components['schemas']['CommandError'];
+    'mark:added': StoredEvent<EventOfType<'mark:added'>>;
+    'mark:removed': StoredEvent<EventOfType<'mark:removed'>>;
+    'mark:body-updated': StoredEvent<EventOfType<'mark:body-updated'>>;
+    'mark:entity-tag-added': StoredEvent<EventOfType<'mark:entity-tag-added'>>;
+    'mark:entity-tag-removed': StoredEvent<EventOfType<'mark:entity-tag-removed'>>;
+    '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': components['schemas']['MarkCreateCommand'];
+    'mark:delete': components['schemas']['MarkDeleteCommand'];
+    'mark:update-body': components['schemas']['MarkUpdateBodyCommand'];
+    'mark:archive': components['schemas']['MarkArchiveCommand'];
+    'mark:unarchive': components['schemas']['MarkUnarchiveCommand'];
+    'mark:update-entity-types': components['schemas']['MarkUpdateEntityTypesCommand'];
+    'mark:add-entity-type': components['schemas']['MarkAddEntityTypeCommand'];
+    'mark:create-ok': components['schemas']['MarkCreateOk'];
+    'mark:create-failed': components['schemas']['CommandError'];
+    'mark:delete-ok': components['schemas']['MarkDeleteOk'];
+    'mark:delete-failed': components['schemas']['CommandError'];
+    'mark:body-update-failed': components['schemas']['CommandError'];
+    'mark:entity-type-add-failed': components['schemas']['CommandError'];
+    'mark:select-comment': components['schemas']['SelectionData'];
+    'mark:select-tag': components['schemas']['SelectionData'];
+    'mark:select-assessment': components['schemas']['SelectionData'];
+    'mark:select-reference': components['schemas']['SelectionData'];
+    'mark:requested': components['schemas']['MarkRequestedEvent'];
     'mark:cancel-pending': void;
-    'mark:submit': {
-        motivation: Motivation;
-        selector: Selector | Selector[];
-        body: components['schemas']['AnnotationBody'][];
-    };
-    'mark:create': {
-        annotation: Annotation$3;
-        userId: UserId;
-        resourceId: ResourceId;
-    };
-    'mark:created': {
-        annotationId: AnnotationId;
-    };
-    'mark:create-failed': {
-        error: Error;
-    };
-    'mark:delete': {
-        annotationId: AnnotationId;
-        userId?: UserId;
-        resourceId?: ResourceId;
-    };
-    'mark:deleted': {
-        annotationId: AnnotationId;
-    };
-    'mark:delete-failed': {
-        error: Error;
-    };
-    'mark:update-body': {
-        annotationId: AnnotationId;
-        userId: UserId;
-        resourceId: ResourceId;
-        operations: BodyOperation[];
-    };
-    'mark:body-update-failed': {
-        error: Error;
-    };
-    'mark:assist-request': {
-        motivation: Motivation;
-        options: {
-            instructions?: string;
-            tone?: 'scholarly' | 'explanatory' | 'conversational' | 'technical' | 'analytical' | 'critical' | 'balanced' | 'constructive';
-            density?: number;
-            language?: string;
-            entityTypes?: string[];
-            includeDescriptiveReferences?: boolean;
-            schemaId?: string;
-            categories?: string[];
-        };
-    };
-    'mark:progress': MarkProgress & {
-        resourceId?: ResourceId;
-    };
-    'mark:assist-finished': {
-        motivation?: Motivation;
-        resourceId?: ResourceId;
-        status?: string;
-        percentage?: number;
-        foundCount?: number;
-        createdCount?: number;
-        byCategory?: Record<string, number>;
-        message?: string;
-        progress?: MarkProgress;
-    };
-    'mark:assist-failed': {
-        resourceId?: ResourceId;
-        message?: string;
-    };
+    'mark:submit': components['schemas']['MarkSubmitEvent'];
+    'mark:assist-request': components['schemas']['MarkAssistRequestEvent'];
     'mark:assist-cancelled': void;
     'mark:progress-dismiss': void;
     'mark:mode-toggled': void;
-    'mark:selection-changed': {
-        motivation: string | null;
-    };
-    'mark:click-changed': {
-        action: string;
-    };
-    'mark:shape-changed': {
-        shape: string;
-    };
-    'mark:added': Extract<ResourceEvent, {
-        type: 'annotation.added';
-    }>;
-    'mark:removed': Extract<ResourceEvent, {
-        type: 'annotation.removed';
-    }>;
-    'mark:body-updated': Extract<ResourceEvent, {
-        type: 'annotation.body.updated';
-    }>;
-    'mark:entity-tag-added': Extract<ResourceEvent, {
-        type: 'entitytag.added';
-    }>;
-    'mark:entity-tag-removed': Extract<ResourceEvent, {
-        type: 'entitytag.removed';
-    }>;
-    'mark:update-entity-types': {
-        resourceId: ResourceId;
-        userId: UserId;
-        currentEntityTypes: string[];
-        updatedEntityTypes: string[];
-    };
-    'mark:add-entity-type': {
-        tag: string;
-        userId: UserId;
-    };
-    'mark:entity-type-added': {
-        tag: string;
-    };
-    'mark:entity-type-add-failed': {
-        error: Error;
-    };
-    'mark:archive': void | {
-        userId: UserId;
-        resourceId?: ResourceId;
-        storageUri?: string;
-        keepFile?: boolean;
-        noGit?: boolean;
-    };
-    'mark:archived': Extract<ResourceEvent, {
-        type: 'resource.archived';
-    }>;
-    'mark:unarchive': void | {
-        userId: UserId;
-        resourceId?: ResourceId;
-        storageUri?: string;
-    };
-    'mark:unarchived': Extract<ResourceEvent, {
-        type: 'resource.unarchived';
-    }>;
-    'bind:initiate': {
-        annotationId: AnnotationId;
-        resourceId: ResourceId;
-        defaultTitle: string;
-        entityTypes: string[];
-    };
-    'bind:update-body': {
-        annotationId: AnnotationId;
-        resourceId: ResourceId;
-        userId?: UserId;
-        operations: Array<{
-            op: 'add' | 'remove' | 'replace';
-            item?: components['schemas']['AnnotationBody'];
-            oldItem?: components['schemas']['AnnotationBody'];
-            newItem?: components['schemas']['AnnotationBody'];
-        }>;
-    };
-    'bind:body-updated': {
-        annotationId: AnnotationId;
-    };
-    'bind:body-update-failed': {
-        error: Error;
-    };
-    'bind:finished': {
-        annotationId: AnnotationId;
-    };
-    'bind:failed': {
-        error: Error;
-    };
-    'match:search-requested': {
-        correlationId: string;
-        referenceId: string;
-        context: GatheredContext;
-        limit?: number;
-        useSemanticScoring?: boolean;
-    };
-    'match:search-results': {
-        correlationId: string;
-        referenceId: string;
-        response: Array<components['schemas']['ResourceDescriptor'] & {
-            score?: number;
-            matchReason?: string;
-        }>;
-    };
-    'match:search-failed': {
-        correlationId: string;
-        referenceId: string;
-        error: string;
-    };
-    'gather:requested': {
-        correlationId: string;
-        annotationId: AnnotationId;
-        resourceId: ResourceId;
-        options?: {
-            includeSourceContext?: boolean;
-            includeTargetContext?: boolean;
-            contextWindow?: number;
-        };
-    };
-    'gather:complete': {
-        correlationId: string;
-        annotationId: AnnotationId;
-        response: components['schemas']['AnnotationLLMContextResponse'];
-    };
+    'mark:selection-changed': components['schemas']['MarkSelectionChangedEvent'];
+    'mark:click-changed': components['schemas']['MarkClickChangedEvent'];
+    'mark:shape-changed': components['schemas']['MarkShapeChangedEvent'];
+    'bind:initiate': components['schemas']['BindInitiateCommand'];
+    'bind:update-body': components['schemas']['BindUpdateBodyCommand'];
+    'bind:body-updated': components['schemas']['BindBodyUpdated'];
+    'bind:body-update-failed': components['schemas']['CommandError'];
+    'match:search-requested': components['schemas']['MatchSearchRequest'];
+    'match:search-results': components['schemas']['MatchSearchResult'];
+    'match:search-failed': components['schemas']['MatchSearchFailed'];
+    'gather:requested': components['schemas']['GatherAnnotationRequest'];
+    'gather:complete': components['schemas']['GatherAnnotationComplete'];
     'gather:failed': {
         correlationId: string;
-        annotationId: AnnotationId;
-        error: Error;
-    };
-    'gather:annotation-progress': {
-        message?: string;
-        percentage?: number;
-    };
-    'gather:annotation-finished': {
-        correlationId: string;
-        annotationId: AnnotationId;
-        response: components['schemas']['AnnotationLLMContextResponse'];
-    };
-    'gather:resource-requested': {
-        correlationId: string;
-        resourceId: ResourceId;
-        options: {
-            depth: number;
-            maxResources: number;
-            includeContent: boolean;
-            includeSummary: boolean;
-        };
-    };
-    'gather:resource-complete': {
-        correlationId: string;
-        resourceId: ResourceId;
-        response: components['schemas']['ResourceLLMContextResponse'];
-    };
+        annotationId: string;
+    } & components['schemas']['CommandError'];
+    'gather:resource-requested': components['schemas']['GatherResourceRequest'];
+    'gather:resource-complete': components['schemas']['GatherResourceComplete'];
     'gather:resource-failed': {
         correlationId: string;
-        resourceId: ResourceId;
-        error: Error;
-    };
-    'gather:progress': {
-        message?: string;
-        percentage?: number;
-    };
-    'gather:finished': {
-        correlationId: string;
-        resourceId: ResourceId;
-        response: components['schemas']['ResourceLLMContextResponse'];
-    };
-    'browse:click': {
-        annotationId: string;
-        motivation: Motivation;
-    };
-    'browse:panel-toggle': {
-        panel: string;
-    };
-    'browse:panel-open': {
-        panel: string;
-        scrollToAnnotationId?: string;
-        motivation?: string;
-    };
-    'browse:panel-close': void;
-    'browse:sidebar-toggle': void;
-    'browse:resource-close': {
-        resourceId: string;
-    };
-    'browse:resource-reorder': {
-        oldIndex: number;
-        newIndex: number;
-    };
-    'browse:link-clicked': {
-        href: string;
-        label?: string;
-    };
-    'browse:router-push': {
-        path: string;
-        reason?: string;
-    };
-    'browse:external-navigate': {
-        url: string;
-        resourceId?: string;
-        cancelFallback: () => void;
-    };
-    'browse:reference-navigate': {
         resourceId: string;
-    };
-    'browse:entity-type-clicked': {
-        entityType: string;
-    };
-    'browse:resource-requested': {
-        correlationId: string;
-        resourceId: ResourceId;
-    };
-    'browse:resource-result': {
-        correlationId: string;
-        response: components['schemas']['GetResourceResponse'];
-    };
+    } & components['schemas']['CommandError'];
+    'gather:annotation-progress': components['schemas']['GatherProgress'];
+    'gather:annotation-finished': components['schemas']['GatherAnnotationFinished'];
+    'gather:progress': components['schemas']['GatherProgress'];
+    'gather:finished': components['schemas']['GatherFinished'];
+    'browse:resource-requested': components['schemas']['BrowseResourceRequest'];
+    'browse:resource-result': components['schemas']['BrowseResourceResult'];
     'browse:resource-failed': {
         correlationId: string;
-        error: Error;
-    };
-    'browse:resources-requested': {
-        correlationId: string;
-        search?: string;
-        archived?: boolean;
-        entityType?: string;
-        offset?: number;
-        limit?: number;
-    };
-    'browse:resources-result': {
-        correlationId: string;
-        response: components['schemas']['ListResourcesResponse'];
-    };
+    } & components['schemas']['CommandError'];
+    'browse:resources-requested': components['schemas']['BrowseResourcesRequest'];
+    'browse:resources-result': components['schemas']['BrowseResourcesResult'];
     'browse:resources-failed': {
         correlationId: string;
-        error: Error;
-    };
-    'browse:annotations-requested': {
-        correlationId: string;
-        resourceId: ResourceId;
-    };
-    'browse:annotations-result': {
-        correlationId: string;
-        response: components['schemas']['GetAnnotationsResponse'];
-    };
+    } & components['schemas']['CommandError'];
+    'browse:annotations-requested': components['schemas']['BrowseAnnotationsRequest'];
+    'browse:annotations-result': components['schemas']['BrowseAnnotationsResult'];
     'browse:annotations-failed': {
         correlationId: string;
-        error: Error;
-    };
-    'browse:annotation-requested': {
-        correlationId: string;
-        resourceId: ResourceId;
-        annotationId: AnnotationId;
-    };
-    'browse:annotation-result': {
-        correlationId: string;
-        response: components['schemas']['GetAnnotationResponse'];
-    };
+    } & components['schemas']['CommandError'];
+    'browse:annotation-requested': components['schemas']['BrowseAnnotationRequest'];
+    'browse:annotation-result': components['schemas']['BrowseAnnotationResult'];
     'browse:annotation-failed': {
         correlationId: string;
-        error: Error;
-    };
-    'browse:events-requested': {
-        correlationId: string;
-        resourceId: ResourceId;
-        type?: string;
-        userId?: string;
-        limit?: number;
-    };
-    'browse:events-result': {
-        correlationId: string;
-        response: components['schemas']['GetEventsResponse'];
-    };
+    } & components['schemas']['CommandError'];
+    'browse:events-requested': components['schemas']['BrowseEventsRequest'];
+    'browse:events-result': components['schemas']['BrowseEventsResult'];
     'browse:events-failed': {
         correlationId: string;
-        error: Error;
-    };
-    'browse:annotation-history-requested': {
-        correlationId: string;
-        resourceId: ResourceId;
-        annotationId: AnnotationId;
-    };
-    'browse:annotation-history-result': {
-        correlationId: string;
-        response: components['schemas']['GetAnnotationHistoryResponse'];
-    };
+    } & components['schemas']['CommandError'];
+    'browse:annotation-history-requested': components['schemas']['BrowseAnnotationHistoryRequest'];
+    'browse:annotation-history-result': components['schemas']['BrowseAnnotationHistoryResult'];
     'browse:annotation-history-failed': {
         correlationId: string;
-        error: Error;
-    };
-    'browse:referenced-by-requested': {
-        correlationId: string;
-        resourceId: ResourceId;
-        motivation?: string;
-    };
-    'browse:referenced-by-result': {
-        correlationId: string;
-        response: components['schemas']['GetReferencedByResponse'];
-    };
+    } & components['schemas']['CommandError'];
+    'browse:referenced-by-requested': components['schemas']['BrowseReferencedByRequest'];
+    'browse:referenced-by-result': components['schemas']['BrowseReferencedByResult'];
     'browse:referenced-by-failed': {
         correlationId: string;
-        error: Error;
-    };
-    'browse:entity-types-requested': {
-        correlationId: string;
-    };
-    'browse:entity-types-result': {
-        correlationId: string;
-        response: components['schemas']['GetEntityTypesResponse'];
-    };
+    } & components['schemas']['CommandError'];
+    'browse:entity-types-requested': components['schemas']['BrowseEntityTypesRequest'];
+    'browse:entity-types-result': components['schemas']['BrowseEntityTypesResult'];
     'browse:entity-types-failed': {
         correlationId: string;
-        error: Error;
-    };
-    'browse:directory-requested': {
-        correlationId: string;
-        path: string;
-        sort?: 'name' | 'mtime' | 'annotationCount';
-    };
-    'browse:directory-result': {
-        correlationId: string;
-        response: {
-            path: string;
-            entries: components['schemas']['DirectoryEntry'][];
-        };
-    };
+    } & components['schemas']['CommandError'];
+    'browse:directory-requested': components['schemas']['BrowseDirectoryRequest'];
+    'browse:directory-result': components['schemas']['BrowseDirectoryResult'];
     'browse:directory-failed': {
         correlationId: string;
         path: string;
-        error: Error;
-    };
-    'beckon:hover': {
-        annotationId: string | null;
-    };
-    'beckon:focus': {
-        annotationId?: string;
-        resourceId?: string;
-    };
-    'beckon:sparkle': {
-        annotationId: string;
-    };
-    'job:start': {
-        resourceId: ResourceId;
-        userId: UserId;
-        jobId: JobId;
-        jobType: 'reference-annotation' | 'generation' | 'highlight-annotation' | 'assessment-annotation' | 'comment-annotation' | 'tag-annotation';
-    };
-    'job:report-progress': {
-        resourceId: ResourceId;
-        userId: UserId;
-        jobId: JobId;
-        jobType: 'reference-annotation' | 'generation' | 'highlight-annotation' | 'assessment-annotation' | 'comment-annotation' | 'tag-annotation';
-        percentage: number;
-        progress?: any;
-    };
-    'job:complete': {
-        resourceId: ResourceId;
-        userId: UserId;
-        jobId: JobId;
-        jobType: 'reference-annotation' | 'generation' | 'highlight-annotation' | 'assessment-annotation' | 'comment-annotation' | 'tag-annotation';
-        result?: any;
-    };
-    'job:fail': {
-        resourceId: ResourceId;
-        userId: UserId;
-        jobId: JobId;
-        jobType: 'reference-annotation' | 'generation' | 'highlight-annotation' | 'assessment-annotation' | 'comment-annotation' | 'tag-annotation';
-        error: string;
-    };
-    'job:started': Extract<ResourceEvent, {
-        type: 'job.started';
-    }>;
-    'job:progress': Extract<ResourceEvent, {
-        type: 'job.progress';
-    }>;
-    'job:completed': Extract<ResourceEvent, {
-        type: 'job.completed';
-    }>;
-    'job:failed': Extract<ResourceEvent, {
-        type: 'job.failed';
-    }>;
-    'job:queued': {
-        jobId: string;
-        jobType: string;
-        resourceId: string;
-    };
-    'job:cancel-requested': {
-        jobType: 'annotation' | 'generation';
-    };
-    'job:status-requested': {
-        correlationId: string;
-        jobId: JobId;
-    };
-    'job:status-result': {
-        correlationId: string;
-        response: components['schemas']['JobStatusResponse'];
+    } & 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'];
+    'beckon:hover': components['schemas']['BeckonHoverEvent'];
+    'beckon:focus': components['schemas']['BeckonFocusEvent'];
+    'beckon:sparkle': components['schemas']['BeckonSparkleEvent'];
+    'job:started': StoredEvent<EventOfType<'job:started'>>;
+    'job:progress': StoredEvent<EventOfType<'job:progress'>>;
+    'job:completed': StoredEvent<EventOfType<'job:completed'>>;
+    'job:failed': StoredEvent<EventOfType<'job:failed'>>;
+    'job:start': components['schemas']['JobStartCommand'];
+    'job:report-progress': components['schemas']['JobReportProgressCommand'];
+    'job:complete': components['schemas']['JobCompleteCommand'];
+    'job:fail': components['schemas']['JobFailCommand'];
+    'job:queued': components['schemas']['JobQueuedEvent'];
+    'job:cancel-requested': components['schemas']['JobCancelRequest'];
+    'job:status-requested': components['schemas']['JobStatusRequest'];
+    'job:status-result': components['schemas']['JobStatusResult'];
     'job:status-failed': {
         correlationId: string;
-        error: Error;
-    };
-    'settings:theme-changed': {
-        theme: 'light' | 'dark' | 'system';
-    };
+    } & components['schemas']['CommandError'];
+    'embedding:compute': components['schemas']['EmbeddingComputeCommand'];
+    'embedding:delete': components['schemas']['EmbeddingDeleteCommand'];
+    'settings:theme-changed': components['schemas']['SettingsThemeChangedEvent'];
     'settings:line-numbers-toggled': void;
-    'settings:locale-changed': {
-        locale: string;
-    };
-    'settings:hover-delay-changed': {
-        hoverDelayMs: number;
-    };
-    'embedding:computed': {
-        resourceId: ResourceId;
-        annotationId?: AnnotationId;
-        chunkIndex: number;
-        chunkText: string;
-        embedding: number[];
-        model: string;
-        dimensions: number;
-    };
-    'embedding:deleted': {
-        resourceId: ResourceId;
-        annotationId?: AnnotationId;
-    };
+    'settings:locale-changed': components['schemas']['SettingsLocaleChangedEvent'];
+    'settings:hover-delay-changed': components['schemas']['SettingsHoverDelayChangedEvent'];
     'stream-connected': Record<string, never>;
+    'replay-window-exceeded': {
+        resourceId?: string;
+        lastEventId: number;
+        missedCount: number;
+        cap: number;
+        message: string;
+    };
 };
+/** Any valid channel name on the EventBus. */
+type EventName = keyof EventMap;
 /**
- * Union type of all valid event names
- * Use this to enforce compile-time checking of event names
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
  */
-type EventName = keyof EventMap;
+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"];
+
+/**
+ * Event Type Guards and Extraction Utilities
+ *
+ * Domain logic for working with resource events.
+ * No React dependencies - safe to use in any JavaScript environment.
+ */
+
+/**
+ * Minimal event shape accepted by event utility functions.
+ * Compatible with both the internal `StoredEvent` type and the OpenAPI-derived
+ * schema type (`GetEventsResponse['events'][number]`), which lacks `version`.
+ *
+ * Flat shape — event fields and metadata are peers (no `event` wrapper).
+ */
+interface StoredEventLike {
+    id: string;
+    type: string;
+    timestamp: string;
+    userId: string;
+    resourceId?: string;
+    payload?: unknown;
+    metadata: {
+        sequenceNumber: number;
+        prevEventHash?: string;
+        checksum?: string;
+    };
+}
+/**
+ * Extract annotation ID from event payload
+ * Returns null if event is not annotation-related
+ *
+ * For mark:added: extracts full URI from payload.annotation.id
+ * For mark:removed/mark:body-updated: constructs full URI from payload.annotationId (UUID) + resourceId
+ */
+declare function getAnnotationUriFromEvent(event: StoredEventLike): AnnotationUri | null;
+/**
+ * Check if an event is related to a specific annotation
+ */
+declare function isEventRelatedToAnnotation(event: StoredEventLike, annotationUri: AnnotationUri): boolean;
+/**
+ * Type guard to check if an object is a StoredEvent (flat shape)
+ */
+declare function isStoredEvent(event: any): event is StoredEvent;
 
 /**
  * RxJS-based Event Bus
@@ -5257,6 +5447,14 @@ declare class EventBus {
      * ```
      */
     get<K extends keyof EventMap>(eventName: K): Subject<EventMap[K]>;
+    /**
+     * Get the RxJS Subject for a domain event type (PersistedEventType).
+     *
+     * Domain event channels carry `StoredEvent`. This method avoids the need
+     * for `as keyof EventMap` casts when subscribing to domain event channels
+     * using runtime `PersistedEventType` strings.
+     */
+    getDomainEvent(eventType: PersistedEventType): Subject<StoredEvent>;
     /**
      * Destroy the event bus and complete all subjects
      *
@@ -5309,6 +5507,8 @@ declare class ScopedEventBus {
      * @returns The RxJS Subject for this scoped event
      */
     get<E extends keyof EventMap>(event: E): Subject<EventMap[E]>;
+    /** Get the RxJS Subject for a domain event type on this scoped bus. */
+    getDomainEvent(eventType: PersistedEventType): Subject<StoredEvent>;
     /**
      * Create a nested scope
      *
@@ -5795,4 +5995,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 AnnotationAddedEvent, type AnnotationBodyUpdatedEvent, type AnnotationCategory, type AnnotationId, type AnnotationRemovedEvent, type AnnotationUri, type AssembledAnnotation, type AuthCode, type BaseEvent, type BaseUrl, type BodyItem, type BodyOperation, type BurstBufferOptions, CORE_TYPES_VERSION, CREATION_METHODS, type CloneToken, ConfigurationError, ConflictError, type ContentFormat$1 as ContentFormat, type CreateAnnotationInternal, type CreationMethod, type Email, type EmbeddingComputedEvent, type EmbeddingDeletedEvent, type EntityTagAddedEvent, type EntityTagRemovedEvent, type EntityType, type EntityTypeStats, type Environment, EnvironmentConfig, EventBus, type EventMap, type EventMetadata, type EventName, type EventQuery, type EventSignature, type GatheredContext, type GoogleAuthRequest, type GoogleCredential, type GraphConnection, type GraphPath, type JobCompletedEvent, type JobFailedEvent, type JobId, type JobProgressEvent, type JobStartedEvent, type Logger, type MCPToken, type MarkProgress, type Motivation$2 as Motivation, NotFoundError, type PlatformType, type RefreshToken, type RepresentationAddedEvent, type RepresentationRemovedEvent, type ResourceAnnotationUri, type ResourceAnnotations, type ResourceArchivedEvent, type ResourceClonedEvent, type ResourceCreatedEvent, type ResourceEvent, type ResourceEventType, type ResourceFilter, type ResourceId, type ResourceScopedEvent, type ResourceUnarchivedEvent, type ResourceUri, SDK_VERSION, ScopedEventBus, ScriptError, type SearchQuery, type SelectionData, type Selector, SemiontError, type StoredEvent, type StoredEventLike, type SystemEvent, 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, getEventType, getFragmentSelector, getSvgSelector, getTextPositionSelector, googleCredential, isAnnotationId, isArray, isBoolean, isDefined, isEventRelatedToAnnotation, isFunction, isNull, isNullish, isNumber, isObject, isResourceEvent$1 as isResourceEvent, isResourceId, isResourceScopedEvent, isResourceEvent as isStoredEvent, isString, isSystemEvent, 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 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 };