@semiont/core 0.2.34-build.91 → 0.2.34-build.92

package/dist/index.d.ts

@@ -1157,7 +1157,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/resources/{id}/detect-annotations-stream": {
+    "/resources/{id}/annotate-references-stream": {
         parameters: {
             query?: never;
             header?: never;
@@ -1167,8 +1167,8 @@ interface paths {
         get?: never;
         put?: never;
         /**
-         * Detect Annotations with Progress (SSE)
-         * @description Stream real-time entity detection progress via Server-Sent Events
+         * Annotate References with Progress (SSE)
+         * @description Stream real-time reference annotation progress via Server-Sent Events
          */
         post: {
             parameters: {
@@ -1181,7 +1181,7 @@ interface paths {
             };
             requestBody?: {
                 content: {
-                    "application/json": components["schemas"]["DetectReferencesStreamRequest"];
+                    "application/json": components["schemas"]["AnnotateReferencesStreamRequest"];
                 };
             };
             responses: {
@@ -1216,7 +1216,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/resources/{id}/detect-highlights-stream": {
+    "/resources/{id}/annotate-highlights-stream": {
         parameters: {
             query?: never;
             header?: never;
@@ -1226,8 +1226,8 @@ interface paths {
         get?: never;
         put?: never;
         /**
-         * Detect Highlights with Progress (SSE)
-         * @description Stream real-time highlight detection progress via Server-Sent Events
+         * Annotate Highlights with Progress (SSE)
+         * @description Stream real-time highlight annotation progress via Server-Sent Events
          */
         post: {
             parameters: {
@@ -1240,7 +1240,7 @@ interface paths {
             };
             requestBody?: {
                 content: {
-                    "application/json": components["schemas"]["DetectHighlightsStreamRequest"];
+                    "application/json": components["schemas"]["AnnotateHighlightsStreamRequest"];
                 };
             };
             responses: {
@@ -1275,7 +1275,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/resources/{id}/detect-assessments-stream": {
+    "/resources/{id}/annotate-assessments-stream": {
         parameters: {
             query?: never;
             header?: never;
@@ -1285,8 +1285,8 @@ interface paths {
         get?: never;
         put?: never;
         /**
-         * Detect Assessments with Progress (SSE)
-         * @description Stream real-time assessment detection progress via Server-Sent Events
+         * Annotate Assessments with Progress (SSE)
+         * @description Stream real-time assessment annotation progress via Server-Sent Events
          */
         post: {
             parameters: {
@@ -1299,7 +1299,7 @@ interface paths {
             };
             requestBody?: {
                 content: {
-                    "application/json": components["schemas"]["DetectAssessmentsStreamRequest"];
+                    "application/json": components["schemas"]["AnnotateAssessmentsStreamRequest"];
                 };
             };
             responses: {
@@ -1334,7 +1334,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/resources/{id}/detect-comments-stream": {
+    "/resources/{id}/annotate-comments-stream": {
         parameters: {
             query?: never;
             header?: never;
@@ -1344,8 +1344,8 @@ interface paths {
         get?: never;
         put?: never;
         /**
-         * Detect Comments with Progress (SSE)
-         * @description Stream real-time comment detection progress via Server-Sent Events
+         * Annotate Comments with Progress (SSE)
+         * @description Stream real-time comment annotation progress via Server-Sent Events
          */
         post: {
             parameters: {
@@ -1358,7 +1358,7 @@ interface paths {
             };
             requestBody?: {
                 content: {
-                    "application/json": components["schemas"]["DetectCommentsStreamRequest"];
+                    "application/json": components["schemas"]["AnnotateCommentsStreamRequest"];
                 };
             };
             responses: {
@@ -1393,7 +1393,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/resources/{id}/detect-tags-stream": {
+    "/resources/{id}/annotate-tags-stream": {
         parameters: {
             query?: never;
             header?: never;
@@ -1403,8 +1403,8 @@ interface paths {
         get?: never;
         put?: never;
         /**
-         * Detect Tags with Progress (SSE)
-         * @description Stream real-time tag detection progress via Server-Sent Events. Identifies passages serving specific structural roles (IRAC, IMRAD, Toulmin frameworks).
+         * Annotate Tags with Progress (SSE)
+         * @description Stream real-time tag annotation progress via Server-Sent Events. Identifies passages serving specific structural roles (IRAC, IMRAD, Toulmin frameworks).
          */
         post: {
             parameters: {
@@ -1417,7 +1417,7 @@ interface paths {
             };
             requestBody?: {
                 content: {
-                    "application/json": components["schemas"]["DetectTagsStreamRequest"];
+                    "application/json": components["schemas"]["AnnotateTagsStreamRequest"];
                 };
             };
             responses: {
@@ -2440,7 +2440,7 @@ interface components {
             /** @enum {string} */
             status: "pending" | "running" | "complete" | "failed" | "cancelled";
             /** @enum {string} */
-            type: "detection" | "generation";
+            type: "reference-annotation" | "generation";
             created: string;
         };
         AuthResponse: {
@@ -2547,7 +2547,7 @@ interface components {
         CreateJobResponse: {
             jobId: string;
             /** @enum {string} */
-            type: "detection" | "generation";
+            type: "reference-annotation" | "generation";
             /** @enum {string} */
             status: "pending" | "running" | "complete" | "failed" | "cancelled";
             created: string;
@@ -2613,20 +2613,20 @@ interface components {
             success: boolean;
             message: string;
         };
-        DetectReferencesStreamRequest: {
-            /** @description Entity types to detect (e.g., 'Person', 'Organization', 'Location') */
+        AnnotateReferencesStreamRequest: {
+            /** @description Entity types to annotate (e.g., 'Person', 'Organization', 'Location') */
             entityTypes: string[];
             /** @description Include anaphoric/cataphoric references (e.g., 'the CEO', 'the tech giant') in addition to direct mentions */
             includeDescriptiveReferences?: boolean;
         };
-        DetectHighlightsStreamRequest: {
-            /** @description Optional instructions to guide AI highlight detection */
+        AnnotateHighlightsStreamRequest: {
+            /** @description Optional instructions to guide AI highlight annotation */
             instructions?: string;
             /** @description Optional density: desired number of highlights per 2000 words of text (1-15) */
             density?: number;
         };
-        DetectAssessmentsStreamRequest: {
-            /** @description Optional instructions to guide AI assessment detection */
+        AnnotateAssessmentsStreamRequest: {
+            /** @description Optional instructions to guide AI assessment annotation */
             instructions?: string;
             /**
              * @description Optional tone/style for generated assessments
@@ -2636,8 +2636,8 @@ interface components {
             /** @description Optional density: desired number of assessments per 2000 words of text (1-10) */
             density?: number;
         };
-        DetectCommentsStreamRequest: {
-            /** @description Optional instructions to guide AI comment detection */
+        AnnotateCommentsStreamRequest: {
+            /** @description Optional instructions to guide AI comment annotation */
             instructions?: string;
             /**
              * @description Optional tone/style for generated comments
@@ -2647,10 +2647,10 @@ interface components {
             /** @description Optional density: desired number of comments per 2000 words of text (2-12) */
             density?: number;
         };
-        DetectTagsStreamRequest: {
+        AnnotateTagsStreamRequest: {
             /** @description Tag schema ID (e.g., 'legal-irac', 'scientific-imrad', 'argument-toulmin') */
             schemaId: string;
-            /** @description Categories to detect from the selected schema (e.g., ['Issue', 'Rule', 'Application', 'Conclusion']) */
+            /** @description Categories to annotate from the selected schema (e.g., ['Issue', 'Rule', 'Application', 'Conclusion']) */
             categories: string[];
         };
         ErrorResponse: {
@@ -2835,7 +2835,7 @@ interface components {
         JobStatusResponse: {
             jobId: string;
             /** @enum {string} */
-            type: "detection" | "generation" | "highlight-detection" | "assessment-detection" | "comment-detection" | "tag-detection";
+            type: "reference-annotation" | "generation" | "highlight-annotation" | "assessment-annotation" | "comment-annotation" | "tag-annotation";
             /** @enum {string} */
             status: "pending" | "running" | "complete" | "failed" | "cancelled";
             userId: string;
@@ -3550,7 +3550,7 @@ interface JobStartedEvent extends BaseEvent {
     resourceId: ResourceId;
     payload: {
         jobId: JobId;
-        jobType: 'detection' | 'generation' | 'highlight-detection' | 'assessment-detection' | 'comment-detection' | 'tag-detection';
+        jobType: 'reference-annotation' | 'generation' | 'highlight-annotation' | 'assessment-annotation' | 'comment-annotation' | 'tag-annotation';
         totalSteps?: number;
     };
 }
@@ -3559,7 +3559,7 @@ interface JobProgressEvent extends BaseEvent {
     resourceId: ResourceId;
     payload: {
         jobId: JobId;
-        jobType: 'detection' | 'generation' | 'highlight-detection' | 'assessment-detection' | 'comment-detection' | 'tag-detection';
+        jobType: 'reference-annotation' | 'generation' | 'highlight-annotation' | 'assessment-annotation' | 'comment-annotation' | 'tag-annotation';
         percentage: number;
         currentStep?: string;
         processedSteps?: number;
@@ -3574,7 +3574,7 @@ interface JobCompletedEvent extends BaseEvent {
     resourceId: ResourceId;
     payload: {
         jobId: JobId;
-        jobType: 'detection' | 'generation' | 'highlight-detection' | 'assessment-detection' | 'comment-detection' | 'tag-detection';
+        jobType: 'reference-annotation' | 'generation' | 'highlight-annotation' | 'assessment-annotation' | 'comment-annotation' | 'tag-annotation';
         totalSteps?: number;
         foundCount?: number;
         resultResourceId?: ResourceId;
@@ -3588,7 +3588,7 @@ interface JobFailedEvent extends BaseEvent {
     resourceId: ResourceId;
     payload: {
         jobId: JobId;
-        jobType: 'detection' | 'generation' | 'highlight-detection' | 'assessment-detection' | 'comment-detection' | 'tag-detection';
+        jobType: 'reference-annotation' | 'generation' | 'highlight-annotation' | 'assessment-annotation' | 'comment-annotation' | 'tag-annotation';
         error: string;
         details?: string;
     };
@@ -3691,21 +3691,17 @@ declare function isResourceEvent(event: any): event is StoredEvent;
 /**
  * Event Protocol Types
  *
- * Unified event map for all application events.
- * This is the single source of truth for event types across backend, frontend, and CLI.
- *
- * Consolidates events from:
- * - Backend events (SSE streams, job progress, resource operations)
- * - User interaction events (selection, annotation hover/click, panels, toolbar)
- * - Navigation events (sidebar, routing, links)
- * - Settings events (theme, line numbers, locale)
- * - API operation events (CRUD, detection, generation)
+ * Type definitions for the application's event-driven architecture.
+ * Single source of truth for all EventBus event types.
  */
 
 type Selector = components['schemas']['TextPositionSelector'] | components['schemas']['TextQuoteSelector'] | components['schemas']['SvgSelector'] | components['schemas']['FragmentSelector'];
 type GenerationContext = components['schemas']['GenerationContext'];
 type Annotation$2 = components['schemas']['Annotation'];
 type Motivation = components['schemas']['Motivation'];
+/**
+ * Progress state for resource generation workflow
+ */
 interface GenerationProgress {
     status: 'started' | 'fetching' | 'generating' | 'creating' | 'complete' | 'error';
     referenceId: string;
@@ -3729,19 +3725,18 @@ interface SelectionData {
     suffix?: string;
 }
 /**
- * Common detection progress fields shared across all motivation types.
+ * Progress state for annotation workflows (manual and assisted)
  *
- * The five motivations have different SSE progress shapes
- * (ReferenceDetectionProgress uses entity-type steps; the others use percentage).
- * This type captures the subset of fields used by the detection UI
- * (DetectionProgressWidget, useDetectionFlow).
+ * Unified progress interface supporting different annotation strategies:
+ * - Reference annotation: entity-type steps
+ * - Other motivations: percentage-based progress
  */
-interface DetectionProgress {
+interface AnnotationProgress {
     status: string;
     message?: string;
-    /** Reference detection: currently scanning entity type */
+    /** Reference annotation: currently scanning entity type */
     currentEntityType?: string;
-    /** Reference detection: completed entity types with counts (frontend-only) */
+    /** Reference annotation: completed entity types with counts (frontend-only) */
     completedEntityTypes?: Array<{
         entityType: string;
         foundCount: number;
@@ -3762,96 +3757,68 @@ interface DetectionProgress {
  * Unified event map for all application events
  *
  * Organized by workflow ("flows"):
- * 1. AttentionFlow - Annotation hover/focus/sparkle coordination
- * 2. DetectionFlow - Manual + AI annotation detection (all motivations)
- * 3. GenerationFlow - Document generation from references
- * 4. ResolutionFlow - Reference linking/resolution (search modal)
- * 5. ContextRetrievalFlow - LLM context fetching from annotations
+ * 1. Attention Flow - Annotation hover/focus/sparkle coordination
+ * 2. Annotation Flow - Manual + AI-assisted annotation (all motivations)
+ * 3. Context Retrieval Flow - LLM context fetching from annotations
+ * 4. Generation Flow - Resource generation from references
+ * 5. Resolution Flow - Reference linking/resolution (search modal)
  *
  * Plus infrastructure events (domain events, SSE, resource operations, navigation, settings)
  */
 type EventMap = {
-    'annotation.added': Extract<ResourceEvent, {
-        type: 'annotation.added';
-    }>;
-    'annotation.removed': Extract<ResourceEvent, {
-        type: 'annotation.removed';
-    }>;
-    'annotation.body.updated': Extract<ResourceEvent, {
-        type: 'annotation.body.updated';
-    }>;
-    'entitytag.added': Extract<ResourceEvent, {
-        type: 'entitytag.added';
-    }>;
-    'entitytag.removed': Extract<ResourceEvent, {
-        type: 'entitytag.removed';
-    }>;
-    'resource.archived': Extract<ResourceEvent, {
-        type: 'resource.archived';
-    }>;
-    'resource.unarchived': Extract<ResourceEvent, {
-        type: 'resource.unarchived';
-    }>;
-    'job.started': Extract<ResourceEvent, {
-        type: 'job.started';
-    }>;
-    'job.completed': Extract<ResourceEvent, {
-        type: 'job.completed';
-    }>;
-    'job.failed': Extract<ResourceEvent, {
-        type: 'job.failed';
-    }>;
-    'representation.added': Extract<ResourceEvent, {
-        type: 'representation.added';
-    }>;
-    'representation.removed': Extract<ResourceEvent, {
-        type: 'representation.removed';
-    }>;
     'make-meaning:event': ResourceEvent;
-    'stream-connected': void;
-    'annotation:hover': {
+    'attend:hover': {
         annotationId: string | null;
     };
-    'annotation:click': {
+    'attend:click': {
         annotationId: string;
         motivation: Motivation;
     };
-    'annotation:focus': {
+    'attend:focus': {
         annotationId: string | null;
     };
-    'annotation:sparkle': {
+    'attend:sparkle': {
         annotationId: string;
     };
-    'selection:comment-requested': SelectionData;
-    'selection:tag-requested': SelectionData;
-    'selection:assessment-requested': SelectionData;
-    'selection:reference-requested': SelectionData;
-    'annotation:requested': {
+    'attend:panel-toggle': {
+        panel: string;
+    };
+    'attend:panel-open': {
+        panel: string;
+        scrollToAnnotationId?: string;
+        motivation?: string;
+    };
+    'attend:panel-close': void;
+    'annotate:select-comment': SelectionData;
+    'annotate:select-tag': SelectionData;
+    'annotate:select-assessment': SelectionData;
+    'annotate:select-reference': SelectionData;
+    'annotate:requested': {
         selector: Selector | Selector[];
         motivation: Motivation;
     };
-    'annotation:cancel-pending': void;
-    'annotation:create': {
+    'annotate:cancel-pending': void;
+    'annotate:create': {
         motivation: Motivation;
         selector: Selector | Selector[];
         body: components['schemas']['AnnotationBody'][];
     };
-    'annotation:created': {
+    'annotate:created': {
         annotation: Annotation$2;
     };
-    'annotation:create-failed': {
+    'annotate:create-failed': {
         error: Error;
     };
-    'annotation:delete': {
+    'annotate:delete': {
         annotationId: string;
     };
-    'annotation:deleted': {
+    'annotate:deleted': {
         annotationId: string;
     };
-    'annotation:delete-failed': {
+    'annotate:delete-failed': {
         error: Error;
     };
-    'detection:start': {
+    'annotate:assist-request': {
         motivation: Motivation;
         options: {
             instructions?: string;
@@ -3863,68 +3830,56 @@ type EventMap = {
             categories?: string[];
         };
     };
-    'detection:started': Extract<ResourceEvent, {
-        type: 'job.started';
-    }>;
-    'detection:progress': DetectionProgress;
-    'detection:entity-found': Extract<ResourceEvent, {
-        type: 'annotation.added';
-    }>;
-    'detection:complete': {
+    'annotate:progress': AnnotationProgress;
+    'annotate:assist-finished': {
         motivation?: Motivation;
         resourceUri?: ResourceUri;
-        progress?: DetectionProgress;
+        progress?: AnnotationProgress;
     };
-    'detection:completed': Extract<ResourceEvent, {
-        type: 'job.completed';
-    }>;
-    'detection:failed': Extract<ResourceEvent, {
+    'annotate:assist-failed': Extract<ResourceEvent, {
         type: 'job.failed';
     }>;
-    'detection:cancelled': void;
-    'detection:dismiss-progress': void;
-    'generation:modal-open': {
-        annotationUri: string;
-        resourceUri: string;
-        defaultTitle: string;
+    'annotate:assist-cancelled': void;
+    'annotate:progress-dismiss': void;
+    'annotate:mode-toggled': void;
+    'annotate:selection-changed': {
+        motivation: string | null;
     };
-    'generation:start': {
-        annotationUri: string;
-        resourceUri: string;
-        options: {
-            title: string;
-            prompt?: string;
-            language?: string;
-            temperature?: number;
-            maxTokens?: number;
-            context: GenerationContext;
-        };
+    'annotate:click-changed': {
+        action: string;
     };
-    'generation:started': Extract<ResourceEvent, {
-        type: 'job.started';
+    'annotate:shape-changed': {
+        shape: string;
+    };
+    'annotate:added': Extract<ResourceEvent, {
+        type: 'annotation.added';
     }>;
-    'generation:progress': GenerationProgress;
-    'generation:complete': GenerationProgress;
-    'generation:completed': Extract<ResourceEvent, {
-        type: 'job.completed';
+    'annotate:removed': Extract<ResourceEvent, {
+        type: 'annotation.removed';
     }>;
-    'generation:failed': {
-        error: Error;
-    };
-    'reference:create-manual': {
+    'annotate:body-updated': Extract<ResourceEvent, {
+        type: 'annotation.body.updated';
+    }>;
+    'annotate:entity-tag-added': Extract<ResourceEvent, {
+        type: 'entitytag.added';
+    }>;
+    'annotate:entity-tag-removed': Extract<ResourceEvent, {
+        type: 'entitytag.removed';
+    }>;
+    'resolve:create-manual': {
         annotationUri: string;
         title: string;
         entityTypes: string[];
     };
-    'reference:link': {
+    'resolve:link': {
         annotationUri: string;
         searchTerm: string;
     };
-    'resolution:search-requested': {
+    'resolve:search-requested': {
         referenceId: string;
         searchTerm: string;
     };
-    'annotation:update-body': {
+    'resolve:update-body': {
         annotationUri: string;
         resourceId: string;
         operations: Array<{
@@ -3934,74 +3889,77 @@ type EventMap = {
             newItem?: components['schemas']['AnnotationBody'];
         }>;
     };
-    'annotation:body-updated': {
+    'resolve:body-updated': {
         annotationUri: string;
     };
-    'annotation:body-update-failed': {
+    'resolve:body-update-failed': {
         error: Error;
     };
-    'context:retrieval-requested': {
+    'correlate:requested': {
         annotationUri: string;
         resourceUri: string;
     };
-    'context:retrieval-complete': {
+    'correlate:complete': {
         annotationUri: string;
         context: GenerationContext;
     };
-    'context:retrieval-failed': {
+    'correlate:failed': {
         annotationUri: string;
         error: Error;
     };
-    'annotation:added': Extract<ResourceEvent, {
-        type: 'annotation.added';
-    }>;
-    'annotation:removed': Extract<ResourceEvent, {
-        type: 'annotation.removed';
-    }>;
-    'annotation:updated': Extract<ResourceEvent, {
-        type: 'annotation.body.updated';
-    }>;
-    'entity-tag:added': Extract<ResourceEvent, {
-        type: 'entitytag.added';
+    'generate:modal-open': {
+        annotationUri: string;
+        resourceUri: string;
+        defaultTitle: string;
+    };
+    'generate:request': {
+        annotationUri: string;
+        resourceUri: string;
+        options: {
+            title: string;
+            prompt?: string;
+            language?: string;
+            temperature?: number;
+            maxTokens?: number;
+            context: GenerationContext;
+        };
+    };
+    'generate:progress': GenerationProgress;
+    'generate:finished': GenerationProgress;
+    'generate:failed': {
+        error: Error;
+    };
+    'generate:representation-added': Extract<ResourceEvent, {
+        type: 'representation.added';
     }>;
-    'entity-tag:removed': Extract<ResourceEvent, {
-        type: 'entitytag.removed';
+    'generate:representation-removed': Extract<ResourceEvent, {
+        type: 'representation.removed';
     }>;
+    'generate:clone': void;
+    'resource:archive': void;
     'resource:archived': Extract<ResourceEvent, {
         type: 'resource.archived';
     }>;
+    'resource:unarchive': void;
     'resource:unarchived': Extract<ResourceEvent, {
         type: 'resource.unarchived';
     }>;
-    'resource:archive': void;
-    'resource:unarchive': void;
-    'resource:clone': void;
+    'job:started': Extract<ResourceEvent, {
+        type: 'job.started';
+    }>;
+    '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: 'detection' | 'generation';
-    };
-    'panel:toggle': {
-        panel: string;
-    };
-    'panel:open': {
-        panel: string;
-        scrollToAnnotationId?: string;
-        motivation?: string;
-    };
-    'panel:close': void;
-    'view:mode-toggled': void;
-    'toolbar:selection-changed': {
-        motivation: string | null;
-    };
-    'toolbar:click-changed': {
-        action: string;
-    };
-    'toolbar:shape-changed': {
-        shape: string;
+        jobType: 'annotation' | 'generation';
     };
     'navigation:sidebar-toggle': void;
     'navigation:resource-close': {
@@ -4037,6 +3995,9 @@ type EventMap = {
     'settings:locale-changed': {
         locale: string;
     };
+    'settings:hover-delay-changed': {
+        hoverDelayMs: number;
+    };
 };
 /**
  * Union type of all valid event names
@@ -4063,16 +4024,16 @@ type EventName = keyof EventMap;
  * const eventBus = new EventBus();
  *
  * // Emit events
- * eventBus.get('annotation:hover').next({ annotationId: 'ann-1' });
+ * eventBus.get('attend:hover').next({ annotationId: 'ann-1' });
  *
  * // Subscribe to events
- * const subscription = eventBus.get('annotation:hover').subscribe(({ annotationId }) => {
+ * const subscription = eventBus.get('attend:hover').subscribe(({ annotationId }) => {
  *   console.log('Hover:', annotationId);
  * });
  *
  * // Use RxJS operators
  * import { debounceTime } from 'rxjs/operators';
- * eventBus.get('annotation:hover')
+ * eventBus.get('attend:hover')
  *   .pipe(debounceTime(100))
  *   .subscribe(handleHover);
  *
@@ -4097,13 +4058,13 @@ declare class EventBus {
      * @example
      * ```typescript
      * // Emit
-     * eventBus.get('annotation:hover').next({ annotationId: 'ann-1' });
+     * eventBus.get('attend:hover').next({ annotationId: 'ann-1' });
      *
      * // Subscribe
-     * const sub = eventBus.get('annotation:hover').subscribe(handleHover);
+     * const sub = eventBus.get('attend:hover').subscribe(handleHover);
      *
      * // With operators
-     * eventBus.get('annotation:hover')
+     * eventBus.get('attend:hover')
      *   .pipe(debounceTime(100), distinctUntilChanged())
      *   .subscribe(handleHover);
      * ```
@@ -4172,6 +4133,32 @@ declare class ScopedEventBus {
     scope(subScope: string): ScopedEventBus;
 }
 
+/**
+ * Logger interface for observability
+ *
+ * This interface is intentionally framework-agnostic to work with any logger
+ * (winston, pino, bunyan, or simple console).
+ *
+ * Example usage:
+ * ```typescript
+ * import winston from 'winston';
+ *
+ * const logger = winston.createLogger({
+ *   level: 'debug',
+ *   transports: [new winston.transports.Console()]
+ * });
+ *
+ * const service = new MyService(logger);
+ * ```
+ */
+interface Logger {
+    debug(message: string, meta?: any): void;
+    info(message: string, meta?: any): void;
+    warn(message: string, meta?: any): void;
+    error(message: string, meta?: any): void;
+    child(meta: Record<string, any>): Logger;
+}
+
 /**
  * Backend-specific annotation utility functions
  */
@@ -5214,4 +5201,4 @@ declare class ConfigurationError extends Error {
 declare const CORE_TYPES_VERSION = "0.1.0";
 declare const SDK_VERSION = "0.1.0";
 
-export { APIError, type AWSConfig, type AccessToken, type AnnotationAddedEvent, type AnnotationBodyUpdatedEvent, type AnnotationCategory, type AnnotationId, type AnnotationRemovedEvent, type AnnotationUri, type AppConfig, type AuthCode, type BackendServiceConfig, type BaseEvent, type BaseUrl, type BodyItem, type BodyOperation, CORE_TYPES_VERSION, CREATION_METHODS, type CloneToken, type ConfigFileReader, ConfigurationError, ConflictError, type ContentFormat$1 as ContentFormat, type CreateAnnotationInternal, type CreationMethod, type DatabaseServiceConfig, type DetectionProgress, type Email, type EntityTagAddedEvent, type EntityTagRemovedEvent, type EntityType, type EntityTypeStats, type Environment, type EnvironmentConfig, EventBus, type EventMap, type EventMetadata, type EventName, type EventQuery, type EventSignature, type FilesystemServiceConfig, type FrontendServiceConfig, type GenerationContext, type GenerationProgress, type GoogleAuthRequest, type GoogleCredential, type GraphConnection, type GraphDatabaseType, type GraphPath, type GraphServiceConfig, type InferenceServiceConfig, type JobCompletedEvent, type JobFailedEvent, type JobId, type JobProgressEvent, type JobStartedEvent, type MCPToken, type McpServiceConfig, type Motivation$2 as Motivation, NotFoundError, type PlatformType, type ProxyServiceConfig, 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, type SemiontConfig, SemiontError, type ServiceConfig, type ServicePlatformConfig, type ServicesConfig, type SiteConfig, type StoredEvent, type SystemEvent, UnauthorizedError, type UpdateResourceInput, type UserDID, type UserId, ValidationError, type ValidationResult, accessToken, annotationId, annotationIdToURI, annotationUri, authCode, baseUrl, cloneToken, type components, createConfigLoader, deepMerge, didToAgent, displayConfiguration, email, entityType, extractResourceUriFromAnnotationUri, findBodyItem, formatErrors, getAllPlatformTypes, getAnnotationUriFromEvent, getEventType, getNodeEnvForEnvironment, googleCredential, hasAWSConfig, isAnnotationId, isArray, isBoolean, isDefined, isEventRelatedToAnnotation, isFunction, isNull, isNullish, isNumber, isObject, isResourceEvent$1 as isResourceEvent, isResourceId, isResourceScopedEvent, isResourceEvent as isStoredEvent, isString, isSystemEvent, isUndefined, isValidPlatformType, jobId, listEnvironmentNames, mcpToken, type operations, parseAndMergeConfigs, parseEnvironment, type paths, refreshToken, resolveEnvVars, resourceAnnotationUri, resourceId, resourceIdToURI, resourceUri, searchQuery, uriToAnnotationId, uriToAnnotationIdOrPassthrough, uriToResourceId, userDID, userId, userToAgent, userToDid, validateEnvironment, validateEnvironmentConfig, validateSemiontConfig, validateSiteConfig };
+export { APIError, type AWSConfig, type AccessToken, type AnnotationAddedEvent, type AnnotationBodyUpdatedEvent, type AnnotationCategory, type AnnotationId, type AnnotationProgress, type AnnotationRemovedEvent, type AnnotationUri, type AppConfig, type AuthCode, type BackendServiceConfig, type BaseEvent, type BaseUrl, type BodyItem, type BodyOperation, CORE_TYPES_VERSION, CREATION_METHODS, type CloneToken, type ConfigFileReader, ConfigurationError, ConflictError, type ContentFormat$1 as ContentFormat, type CreateAnnotationInternal, type CreationMethod, type DatabaseServiceConfig, type Email, type EntityTagAddedEvent, type EntityTagRemovedEvent, type EntityType, type EntityTypeStats, type Environment, type EnvironmentConfig, EventBus, type EventMap, type EventMetadata, type EventName, type EventQuery, type EventSignature, type FilesystemServiceConfig, type FrontendServiceConfig, type GenerationContext, type GenerationProgress, type GoogleAuthRequest, type GoogleCredential, type GraphConnection, type GraphDatabaseType, type GraphPath, type GraphServiceConfig, type InferenceServiceConfig, type JobCompletedEvent, type JobFailedEvent, type JobId, type JobProgressEvent, type JobStartedEvent, type Logger, type MCPToken, type McpServiceConfig, type Motivation$2 as Motivation, NotFoundError, type PlatformType, type ProxyServiceConfig, 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, type SemiontConfig, SemiontError, type ServiceConfig, type ServicePlatformConfig, type ServicesConfig, type SiteConfig, type StoredEvent, type SystemEvent, UnauthorizedError, type UpdateResourceInput, type UserDID, type UserId, ValidationError, type ValidationResult, accessToken, annotationId, annotationIdToURI, annotationUri, authCode, baseUrl, cloneToken, type components, createConfigLoader, deepMerge, didToAgent, displayConfiguration, email, entityType, extractResourceUriFromAnnotationUri, findBodyItem, formatErrors, getAllPlatformTypes, getAnnotationUriFromEvent, getEventType, getNodeEnvForEnvironment, googleCredential, hasAWSConfig, isAnnotationId, isArray, isBoolean, isDefined, isEventRelatedToAnnotation, isFunction, isNull, isNullish, isNumber, isObject, isResourceEvent$1 as isResourceEvent, isResourceId, isResourceScopedEvent, isResourceEvent as isStoredEvent, isString, isSystemEvent, isUndefined, isValidPlatformType, jobId, listEnvironmentNames, mcpToken, type operations, parseAndMergeConfigs, parseEnvironment, type paths, refreshToken, resolveEnvVars, resourceAnnotationUri, resourceId, resourceIdToURI, resourceUri, searchQuery, uriToAnnotationId, uriToAnnotationIdOrPassthrough, uriToResourceId, userDID, userId, userToAgent, userToDid, validateEnvironment, validateEnvironmentConfig, validateSemiontConfig, validateSiteConfig };