@semiont/core 0.4.2 → 0.4.4

package/dist/index.d.ts

@@ -1722,92 +1722,183 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/resources/{id}/llm-context": {
+    "/resources/{id}/gather-resource-stream": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
+        get?: never;
+        put?: never;
         /**
-         * Get Resource LLM Context
-         * @description Get resource with full context for LLM processing
+         * Gather Resource LLM Context (SSE Stream)
+         * @description Stream real-time resource LLM context gathering progress via Server-Sent Events
          */
-        get: {
+        post: {
             parameters: {
-                query?: {
-                    depth?: number;
-                    maxResources?: number;
-                    includeContent?: "true" | "false" | boolean;
-                    includeSummary?: "true" | "false" | boolean;
-                };
+                query?: never;
                 header?: never;
                 path: {
                     id: string;
                 };
                 cookie?: never;
             };
-            requestBody?: never;
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["GatherResourceStreamRequest"];
+                };
+            };
             responses: {
-                /** @description LLM context */
+                /** @description SSE stream opened successfully */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["ResourceLLMContextResponse"];
+                        "text/event-stream": components["schemas"]["EventStreamResponse"];
                     };
                 };
+                /** @description Authentication required */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Resource not found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
             };
         };
-        put?: never;
-        post?: never;
         delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    "/resources/{resourceId}/annotations/{annotationId}/llm-context": {
+    "/resources/{resourceId}/annotations/{annotationId}/gather-annotation-stream": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
+        get?: never;
+        put?: never;
         /**
-         * Get Annotation LLM Context
-         * @description Get annotation with full context for LLM processing
+         * Gather Annotation LLM Context (SSE Stream)
+         * @description Stream real-time annotation LLM context gathering progress via Server-Sent Events
          */
-        get: {
+        post: {
             parameters: {
-                query?: {
-                    includeSourceContext?: "true" | "false" | boolean;
-                    includeTargetContext?: "true" | "false" | boolean;
-                    contextWindow?: number;
-                };
+                query?: never;
                 header?: never;
                 path: {
+                    /** @description Resource ID */
                     resourceId: string;
+                    /** @description Annotation ID */
                     annotationId: string;
                 };
                 cookie?: never;
             };
-            requestBody?: never;
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["GatherAnnotationStreamRequest"];
+                };
+            };
             responses: {
-                /** @description Annotation LLM context */
+                /** @description SSE stream opened successfully */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["AnnotationLLMContextResponse"];
+                        "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;
-        post?: 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: {
+                    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;
@@ -2588,6 +2679,153 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/participants/{id}/attention": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Beckon Participant
+         * @description Direct a participant's attention to a resource or annotation. Produces no persistent annotations — attention signal only. The participant may be a human username or an agent identifier.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Participant username or agent identifier */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": components["schemas"]["BeckonRequest"];
+                };
+            };
+            responses: {
+                /** @description Attention signal accepted */
+                202: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["BeckonResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/participants/me/attention-stream": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Participant Attention Stream
+         * @description Open a persistent SSE connection to receive beckon signals directed at the authenticated participant. Signals are ephemeral — delivered if connected, dropped if not. No queue, no replay.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description SSE stream of beckon:focus events */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "text/event-stream": string;
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/browse/files": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Browse project directory
+         * @description List files and directories in a project directory, merged with Knowledge Base metadata for tracked resources.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Directory path relative to project root. Empty string or omit for project root. */
+                    path?: string;
+                    /** @description Sort order for directory entries. */
+                    sort?: "name" | "mtime" | "annotationCount";
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Directory listing with KB metadata merged */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["BrowseFilesResponse"];
+                    };
+                };
+                /** @description Invalid path (e.g. path escapes project root) */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Directory not found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 interface components {
     schemas: {
@@ -2752,6 +2990,50 @@ interface components {
             token: string;
             isNewUser: boolean;
         };
+        BrowseFilesResponse: {
+            /** @description The directory path that was listed, relative to project root */
+            path: string;
+            entries: components["schemas"]["DirectoryEntry"][];
+        };
+        DirectoryEntry: components["schemas"]["FileEntry"] | components["schemas"]["DirEntry"];
+        FileEntry: {
+            /** @enum {string} */
+            type: "file";
+            /** @description Entry name (basename) */
+            name: string;
+            /** @description Path relative to project root */
+            path: string;
+            /** @description File size in bytes */
+            size: number;
+            /**
+             * Format: date-time
+             * @description Last modified time (ISO 8601)
+             */
+            mtime: string;
+            /** @description True if this file is a tracked resource in the Knowledge Base */
+            tracked: boolean;
+            /** @description Resource ID (only when tracked is true) */
+            resourceId?: string;
+            /** @description Entity types assigned to this resource (only when tracked is true) */
+            entityTypes?: string[];
+            /** @description Number of annotations on this resource (only when tracked is true) */
+            annotationCount?: number;
+            /** @description DID of the user who created the resource (only when tracked is true) */
+            creator?: string;
+        };
+        DirEntry: {
+            /** @enum {string} */
+            type: "dir";
+            /** @description Entry name (basename) */
+            name: string;
+            /** @description Path relative to project root */
+            path: string;
+            /**
+             * Format: date-time
+             * @description Last modified time (ISO 8601)
+             */
+            mtime: string;
+        };
         BodyOperationAdd: {
             /** @enum {string} */
             op: "add";
@@ -2773,6 +3055,22 @@ interface components {
          * @enum {string}
          */
         BodyType: "TextualBody" | "SpecificResource";
+        BeckonRequest: {
+            /** @description Resource to direct attention at */
+            resourceId: string;
+            /** @description Specific annotation within the resource (optional) */
+            annotationId?: string;
+            /** @description Human-readable context for the participant (max 500 chars) */
+            message?: string;
+        };
+        BeckonResponse: {
+            /** @description Username or agent identifier that was beckoned */
+            participant: string;
+            /** @description Resource the attention was directed at */
+            resourceId: string;
+            /** @description Annotation the attention was directed at (if provided) */
+            annotationId?: string;
+        };
         BulkAddEntityTypesRequest: {
             tags: string[];
         };
@@ -2901,6 +3199,26 @@ interface components {
             /** @description Include anaphoric/cataphoric references (e.g., 'the CEO', 'the tech giant') in addition to direct mentions */
             includeDescriptiveReferences?: boolean;
         };
+        GatherResourceStreamRequest: {
+            /** @description Graph traversal depth (default: 2) */
+            depth?: number;
+            /** @description Maximum related resources to include (default: 10) */
+            maxResources?: number;
+            /** @description Include full resource content (default: true) */
+            includeContent?: boolean;
+            /** @description Include AI-generated summary (default: false) */
+            includeSummary?: boolean;
+        };
+        GatherAnnotationStreamRequest: {
+            /** @description Characters of surrounding text context (default: 1000) */
+            contextWindow?: number;
+        };
+        BindAnnotationStreamRequest: {
+            /** @description Resource ID containing the annotation (required for O(1) Layer 3 lookup) */
+            resourceId: string;
+            /** @description Array of body modification operations to apply */
+            operations: (components["schemas"]["BodyOperationAdd"] | components["schemas"]["BodyOperationRemove"] | components["schemas"]["BodyOperationReplace"])[];
+        };
         AnnotateHighlightsStreamRequest: {
             /** @description Optional instructions to guide AI highlight annotation */
             instructions?: string;
@@ -2917,6 +3235,8 @@ interface components {
             tone?: "analytical" | "critical" | "balanced" | "constructive";
             /** @description Optional density: desired number of assessments per 2000 words of text (1-10) */
             density?: number;
+            /** @description BCP 47 language tag for the generated assessment text (e.g. "en", "fr", "de") */
+            language?: string;
         };
         AnnotateCommentsStreamRequest: {
             /** @description Optional instructions to guide AI comment annotation */
@@ -2928,6 +3248,8 @@ interface components {
             tone?: "scholarly" | "explanatory" | "conversational" | "technical";
             /** @description Optional density: desired number of comments per 2000 words of text (2-12) */
             density?: number;
+            /** @description BCP 47 language tag for the generated comment text (e.g. 'en', 'fr', 'de') */
+            language?: string;
         };
         AnnotateTagsStreamRequest: {
             /** @description Tag schema ID (e.g., 'legal-irac', 'scientific-imrad', 'argument-toulmin') */
@@ -3155,10 +3477,10 @@ interface components {
             refresh_token: string;
         };
         /**
-         * @description W3C Web Annotation motivation vocabulary - https://www.w3.org/TR/annotation-vocab/#motivation
+         * @description Semiont-supported W3C Web Annotation motivations - https://www.w3.org/TR/annotation-vocab/#motivation
          * @enum {string}
          */
-        Motivation: "assessing" | "bookmarking" | "classifying" | "commenting" | "describing" | "editing" | "highlighting" | "identifying" | "linking" | "moderating" | "questioning" | "replying" | "tagging";
+        Motivation: "assessing" | "commenting" | "highlighting" | "linking" | "tagging";
         OAuthConfigResponse: {
             providers: {
                 name: string;
@@ -3258,6 +3580,8 @@ interface components {
             wasDerivedFrom?: string | string[];
             /** @description W3C PROV - agents responsible for this resource */
             wasAttributedTo?: components["schemas"]["Agent"] | components["schemas"]["Agent"][];
+            /** @description Software agent that produced or processed this resource (W3C Web Annotation model) */
+            generator?: components["schemas"]["Agent"] | components["schemas"]["Agent"][];
             /** @description Profile/shape URI this resource description conforms to. */
             conformsTo?: string | string[];
             /** @description Convenience set summarizing media types across representations. */
@@ -3328,7 +3652,7 @@ interface components {
             /** @description IRI of the target resource */
             source: string;
             /** @description Why this body is included */
-            purpose?: components["schemas"]["Motivation"];
+            purpose?: components["schemas"]["BodyPurpose"];
         };
         StatusResponse: {
             status: string;
@@ -3362,7 +3686,7 @@ interface components {
             /** @description The text content (e.g., entity type name) */
             value: string;
             /** @description Why this body is included */
-            purpose?: components["schemas"]["Motivation"];
+            purpose?: components["schemas"]["BodyPurpose"];
             /** @description MIME type (defaults to text/plain) */
             format?: string;
             /** @description BCP 47 language tag */
@@ -3443,6 +3767,11 @@ interface components {
              */
             conformsTo?: string;
         };
+        /**
+         * @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";
         /** @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: {
             /** @description The annotation this context was gathered for */
@@ -3686,8 +4015,12 @@ interface ResourceCreatedEvent extends BaseEvent {
         storageUri?: string;
         language?: string;
         isDraft?: boolean;
-        generatedFrom?: string;
+        generatedFrom?: {
+            resourceId: string;
+            annotationId: string;
+        };
         generationPrompt?: string;
+        generator?: components['schemas']['Agent'] | components['schemas']['Agent'][];
     };
 }
 interface ResourceClonedEvent extends BaseEvent {
@@ -4009,13 +4342,14 @@ interface MarkProgress {
 /**
  * Unified event map for all application events
  *
- * Organized by workflow ("flows"):
+ * 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. Gather Flow - LLM context fetching from annotations
- * 5. Browse Flow - Panel, sidebar, and application routing
- * 6. Beckon Flow - Annotation hover/focus/sparkle coordination
+ * 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
  *
  * Plus infrastructure events (domain events, SSE, resource operations, settings)
  */
@@ -4056,8 +4390,12 @@ type EventMap = {
         entityTypes?: string[];
         creationMethod?: CreationMethod;
         isDraft?: boolean;
-        generatedFrom?: string;
+        generatedFrom?: {
+            resourceId: string;
+            annotationId: string;
+        };
         generationPrompt?: string;
+        generator?: components['schemas']['Agent'] | components['schemas']['Agent'][];
         noGit?: boolean;
     };
     'yield:created': {
@@ -4189,6 +4527,7 @@ type EventMap = {
             instructions?: string;
             tone?: 'scholarly' | 'explanatory' | 'conversational' | 'technical' | 'analytical' | 'critical' | 'balanced' | 'constructive';
             density?: number;
+            language?: string;
             entityTypes?: string[];
             includeDescriptiveReferences?: boolean;
             schemaId?: string;
@@ -4247,17 +4586,6 @@ type EventMap = {
     'mark:entity-type-add-failed': {
         error: Error;
     };
-    'mark:entity-types-requested': {
-        correlationId: string;
-    };
-    'mark:entity-types-result': {
-        correlationId: string;
-        response: components['schemas']['GetEntityTypesResponse'];
-    };
-    'mark:entity-types-failed': {
-        correlationId: string;
-        error: Error;
-    };
     'mark:archive': void | {
         userId: UserId;
         resourceId?: ResourceId;
@@ -4282,13 +4610,6 @@ type EventMap = {
         defaultTitle: string;
         entityTypes: string[];
     };
-    'bind:search-requested': {
-        correlationId?: string;
-        referenceId: string;
-        context: GatheredContext;
-        limit?: number;
-        useSemanticScoring?: boolean;
-    };
     'bind:update-body': {
         annotationId: AnnotationId;
         resourceId: ResourceId;
@@ -4306,7 +4627,20 @@ type EventMap = {
     'bind:body-update-failed': {
         error: Error;
     };
-    'bind:search-results': {
+    'bind:finished': {
+        annotationId: AnnotationId;
+    };
+    'bind:failed': {
+        error: Error;
+    };
+    'match:search-requested': {
+        correlationId?: string;
+        referenceId: string;
+        context: GatheredContext;
+        limit?: number;
+        useSemanticScoring?: boolean;
+    };
+    'match:search-results': {
         referenceId: string;
         results: Array<components['schemas']['ResourceDescriptor'] & {
             score?: number;
@@ -4314,24 +4648,11 @@ type EventMap = {
         }>;
         correlationId?: string;
     };
-    'bind:search-failed': {
+    'match:search-failed': {
         referenceId: string;
         error: Error;
         correlationId?: string;
     };
-    'bind:referenced-by-requested': {
-        correlationId: string;
-        resourceId: ResourceId;
-        motivation?: string;
-    };
-    'bind:referenced-by-result': {
-        correlationId: string;
-        response: components['schemas']['GetReferencedByResponse'];
-    };
-    'bind:referenced-by-failed': {
-        correlationId: string;
-        error: Error;
-    };
     'gather:requested': {
         correlationId?: string;
         annotationId: AnnotationId;
@@ -4352,6 +4673,15 @@ type EventMap = {
         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;
@@ -4372,6 +4702,15 @@ type EventMap = {
         resourceId: ResourceId;
         error: Error;
     };
+    'gather:progress': {
+        message?: string;
+        percentage?: number;
+    };
+    'gather:finished': {
+        correlationId?: string;
+        resourceId: ResourceId;
+        context: components['schemas']['ResourceLLMContextResponse'];
+    };
     'browse:click': {
         annotationId: string;
         motivation: Motivation;
@@ -4407,7 +4746,7 @@ type EventMap = {
         cancelFallback: () => void;
     };
     'browse:reference-navigate': {
-        documentId: string;
+        resourceId: string;
     };
     'browse:entity-type-clicked': {
         entityType: string;
@@ -4493,11 +4832,53 @@ type EventMap = {
         correlationId: string;
         error: Error;
     };
+    'browse:referenced-by-requested': {
+        correlationId: string;
+        resourceId: ResourceId;
+        motivation?: string;
+    };
+    'browse:referenced-by-result': {
+        correlationId: string;
+        response: components['schemas']['GetReferencedByResponse'];
+    };
+    'browse:referenced-by-failed': {
+        correlationId: string;
+        error: Error;
+    };
+    'browse:entity-types-requested': {
+        correlationId: string;
+    };
+    'browse:entity-types-result': {
+        correlationId: string;
+        response: components['schemas']['GetEntityTypesResponse'];
+    };
+    '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'][];
+        };
+    };
+    'browse:directory-failed': {
+        correlationId: string;
+        path: string;
+        error: Error;
+    };
     'beckon:hover': {
         annotationId: string | null;
     };
     'beckon:focus': {
-        annotationId: string | null;
+        annotationId?: string;
+        resourceId?: string;
     };
     'beckon:sparkle': {
         annotationId: string;
@@ -5008,16 +5389,17 @@ type Agent = components['schemas']['Agent'];
 /**
  * Convert a user object to a DID:WEB identifier
  *
- * Format: did:web:domain.com:users:userId
- * Example: did:web:example.com:users:abc123
+ * Format: did:web:domain.com:users:email%40domain.com
+ * Example: did:web:example.com:users:alice%40example.com
  *
+ * Email is used as the stable, human-readable identifier (URI-encoded).
  * This is used for W3C Web Annotation compliance and federation readiness.
  *
- * @param user - User object with id and domain
+ * @param user - User object with email and domain
  * @returns DID:WEB identifier string
  */
 declare function userToDid(user: {
-    id: string;
+    email: string;
     domain: string;
 }): string;
 /**