@semiont/core 0.2.45 → 0.3.0

package/dist/index.d.ts

@@ -84,14 +84,12 @@ interface paths {
                 };
             };
             responses: {
-                /** @description Resource updated successfully */
-                200: {
+                /** @description Update accepted */
+                202: {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content: {
-                        "application/json": components["schemas"]["GetResourceResponse"];
-                    };
+                    content?: never;
                 };
                 /** @description Resource not found */
                 404: {
@@ -1063,6 +1061,275 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/admin/exchange/backup": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Backup Knowledge Base
+         * @description Create a lossless backup of the knowledge base as a streaming tar.gz archive
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Streaming backup archive */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/gzip": string;
+                    };
+                };
+                /** @description Unauthorized */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Forbidden - Admin access required */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/admin/exchange/restore": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Restore Knowledge Base
+         * @description Restore knowledge base from a backup archive. Returns SSE progress events.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "multipart/form-data": {
+                        /**
+                         * Format: binary
+                         * @description Backup archive (.tar.gz)
+                         */
+                        file: string;
+                    };
+                };
+            };
+            responses: {
+                /** @description SSE stream of restore progress events */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "text/event-stream": string;
+                    };
+                };
+                /** @description Invalid file format */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Unauthorized */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Forbidden - Admin access required */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/admin/exchange/export": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Export Knowledge Base as JSON-LD
+         * @description Export the knowledge base as a JSON-LD Linked Data tar.gz archive
+         */
+        post: {
+            parameters: {
+                query?: {
+                    /** @description Include archived resources in export */
+                    includeArchived?: boolean;
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Streaming JSON-LD archive */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/gzip": string;
+                    };
+                };
+                /** @description Unauthorized */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Forbidden - Admin access required */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/admin/exchange/import": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Import Knowledge Base from JSON-LD
+         * @description Import resources from a JSON-LD Linked Data archive. Returns SSE progress events.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "multipart/form-data": {
+                        /**
+                         * Format: binary
+                         * @description JSON-LD archive (.tar.gz)
+                         */
+                        file: string;
+                    };
+                };
+            };
+            responses: {
+                /** @description SSE stream of import progress events */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "text/event-stream": string;
+                    };
+                };
+                /** @description Invalid file format */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Unauthorized */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Forbidden - Admin access required */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/resources": {
         parameters: {
             query?: never;
@@ -1140,13 +1407,15 @@ interface paths {
                 };
             };
             responses: {
-                /** @description Resource created successfully */
-                201: {
+                /** @description Resource creation accepted */
+                202: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["CreateResourceResponse"];
+                        "application/json": {
+                            resourceId: string;
+                        };
                     };
                 };
             };
@@ -1655,13 +1924,15 @@ interface paths {
                 };
             };
             responses: {
-                /** @description Resource created successfully */
-                201: {
+                /** @description Resource creation accepted */
+                202: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["CreateResourceResponse"];
+                        "application/json": {
+                            resourceId: string;
+                        };
                     };
                 };
             };
@@ -1767,13 +2038,15 @@ interface paths {
                 };
             };
             responses: {
-                /** @description Annotation created successfully */
-                201: {
+                /** @description Annotation creation accepted */
+                202: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["CreateAnnotationResponse"];
+                        "application/json": {
+                            annotationId: string;
+                        };
                     };
                 };
             };
@@ -1933,15 +2206,8 @@ interface paths {
             };
             requestBody?: never;
             responses: {
-                /** @description Annotation deleted successfully */
-                204: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-                /** @description Annotation not found */
-                404: {
+                /** @description Annotation deletion accepted */
+                202: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -1984,14 +2250,12 @@ interface paths {
                 };
             };
             responses: {
-                /** @description Annotation body updated successfully */
-                200: {
+                /** @description Annotation body update accepted */
+                202: {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content: {
-                        "application/json": components["schemas"]["UpdateAnnotationBodyResponse"];
-                    };
+                    content?: never;
                 };
             };
         };
@@ -2158,18 +2422,66 @@ interface paths {
             };
             requestBody?: {
                 content: {
-                    "application/json": components["schemas"]["AddEntityTypeRequest"];
+                    "application/json": components["schemas"]["AddEntityTypeRequest"];
+                };
+            };
+            responses: {
+                /** @description Entity type addition accepted */
+                202: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Forbidden - Moderator or Admin access required */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/entity-types/bulk": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Bulk Add Entity Types
+         * @description Add multiple entity types to the collection (append-only, requires moderator/admin)
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["BulkAddEntityTypesRequest"];
                 };
             };
             responses: {
-                /** @description Entity type added successfully */
-                200: {
+                /** @description Entity types addition accepted */
+                202: {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content: {
-                        "application/json": components["schemas"]["AddEntityTypeResponse"];
-                    };
+                    content?: never;
                 };
                 /** @description Forbidden - Moderator or Admin access required */
                 403: {
@@ -2188,52 +2500,39 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/entity-types/bulk": {
+    "/api/events/stream": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get?: never;
-        put?: never;
         /**
-         * Bulk Add Entity Types
-         * @description Add multiple entity types to the collection (append-only, requires moderator/admin)
+         * Subscribe to Global Events (SSE)
+         * @description Open a Server-Sent Events stream to receive real-time system-level events (e.g., entity type changes). Events not scoped to a specific resource are delivered on this channel.
          */
-        post: {
+        get: {
             parameters: {
                 query?: never;
                 header?: never;
                 path?: never;
                 cookie?: never;
             };
-            requestBody?: {
-                content: {
-                    "application/json": components["schemas"]["BulkAddEntityTypesRequest"];
-                };
-            };
+            requestBody?: never;
             responses: {
-                /** @description Entity types added successfully */
+                /** @description SSE stream opened successfully */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["AddEntityTypeResponse"];
-                    };
-                };
-                /** @description Forbidden - Moderator or Admin access required */
-                403: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["ErrorResponse"];
+                        "text/event-stream": components["schemas"]["EventStreamResponse"];
                     };
                 };
             };
         };
+        put?: never;
+        post?: never;
         delete?: never;
         options?: never;
         head?: never;
@@ -2298,10 +2597,6 @@ interface components {
         AddEntityTypeRequest: {
             tag: string;
         };
-        AddEntityTypeResponse: {
-            success: boolean;
-            entityTypes: string[];
-        };
         AdminUpdateUserResponse: {
             success: boolean;
             user: {
@@ -2409,8 +2704,8 @@ interface components {
             annotation: components["schemas"]["Annotation"];
             sourceResource: components["schemas"]["ResourceDescriptor"];
             targetResource?: components["schemas"]["ResourceDescriptor"] | null;
-            /** @description Generation context for this annotation */
-            context?: components["schemas"]["YieldContext"];
+            /** @description Gathered context for this annotation */
+            context?: components["schemas"]["GatheredContext"];
             /** @description DEPRECATED: Use 'context' instead. Legacy source context format. */
             sourceContext?: {
                 before: string;
@@ -2523,9 +2818,6 @@ interface components {
             };
             body: unknown[] | components["schemas"]["AnnotationBody"] | components["schemas"]["AnnotationBody"][];
         };
-        CreateAnnotationResponse: {
-            annotation: components["schemas"]["Annotation"];
-        };
         CreateFromAnnotationRequest: {
             /** @description ID of the resource containing the annotation */
             resourceId: string;
@@ -2577,10 +2869,6 @@ interface components {
             /** @description Whether to archive the original resource */
             archiveOriginal?: boolean;
         };
-        CreateResourceFromTokenResponse: {
-            resource: components["schemas"]["ResourceDescriptor"];
-            annotations: components["schemas"]["Annotation"][];
-        };
         CreateResourceRequest: {
             name: string;
             content: string;
@@ -2688,8 +2976,8 @@ interface components {
             prompt?: string;
             /** @description Language locale for generated content (e.g., "es", "fr", "ja") */
             language?: string;
-            /** @description Generation context including source document excerpts and metadata */
-            context: components["schemas"]["YieldContext"];
+            /** @description Gathered context including source document excerpts, metadata, and graph context */
+            context: components["schemas"]["GatheredContext"];
             /** @description Inference temperature (0.0 = focused, 1.0 = creative) */
             temperature?: number;
             /** @description Maximum tokens to generate */
@@ -2935,10 +3223,7 @@ interface components {
             } | (string | {
                 [key: string]: unknown;
             })[];
-            /**
-             * Format: uri
-             * @description Canonical URI/URN of the resource being described.
-             */
+            /** @description Canonical URI/URN of the resource being described. */
             "@id": string;
             /** @description Type(s) of the resource (IRIs/CURIEs via @context). */
             "@type"?: string | string[];
@@ -2991,6 +3276,11 @@ interface components {
             sourceAnnotationId?: string;
             /** @description Application-specific: ID of source resource for clones/derivatives */
             sourceResourceId?: string;
+            /**
+             * Format: uri
+             * @description Original URI from a source knowledge base when this resource was imported
+             */
+            originatedFrom?: string;
         } & {
             [key: string]: unknown;
         };
@@ -3087,9 +3377,6 @@ interface components {
             /** @description Array of body modification operations to apply */
             operations: (components["schemas"]["BodyOperationAdd"] | components["schemas"]["BodyOperationRemove"] | components["schemas"]["BodyOperationReplace"])[];
         };
-        UpdateAnnotationBodyResponse: {
-            annotation: components["schemas"]["Annotation"];
-        };
         UpdateResourceRequest: {
             entityTypes?: string[];
             archived?: boolean;
@@ -3149,8 +3436,12 @@ interface components {
              */
             conformsTo?: string;
         };
-        /** @description Context information used for AI generation. Includes source document excerpts and metadata. */
-        YieldContext: {
+        /** @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 */
+            annotation: components["schemas"]["Annotation"];
+            /** @description The resource containing the annotation */
+            sourceResource: components["schemas"]["ResourceDescriptor"];
             /** @description Text context from the source document */
             sourceContext: {
                 /** @description Text appearing before the selected passage */
@@ -3160,7 +3451,7 @@ interface components {
                 /** @description Text appearing after the selected passage */
                 after?: string;
             };
-            /** @description Additional context metadata (reserved for future use) */
+            /** @description Context metadata about the annotation and its source */
             metadata?: {
                 /** @description Type of source resource (e.g., 'document', 'image', 'video') */
                 resourceType?: string;
@@ -3169,6 +3460,35 @@ interface components {
                 /** @description Entity types associated with the annotation */
                 entityTypes?: string[];
             };
+            /** @description Graph-derived context from the knowledge base */
+            graphContext?: {
+                /** @description Resources connected to the source resource via annotations */
+                connections?: {
+                    /** @description ID of the connected resource */
+                    resourceId: string;
+                    /** @description Name of the connected resource */
+                    resourceName: string;
+                    /** @description Entity types on the connected resource */
+                    entityTypes?: string[];
+                    /** @description Whether the connection goes both ways */
+                    bidirectional: boolean;
+                }[];
+                /** @description Number of other resources that reference the source resource */
+                citedByCount?: number;
+                /** @description Resources that reference the source resource */
+                citedBy?: {
+                    resourceId: string;
+                    resourceName: string;
+                }[];
+                /** @description Entity types from other annotations on the same resource */
+                siblingEntityTypes?: string[];
+                /** @description Global frequency counts for entity types (for IDF-like weighting) */
+                entityTypeFrequencies?: {
+                    [key: string]: number;
+                };
+                /** @description LLM-generated summary of the annotation's relationships in the knowledge graph */
+                inferredRelationshipSummary?: string;
+            };
         };
     };
     responses: never;
@@ -3292,104 +3612,18 @@ declare function resourceId(id: string): ResourceId;
 declare function annotationId(id: string): AnnotationId;
 declare function userId(id: string): UserId;
 
-/**
- * URI utilities for W3C annotations
- *
- * Converts between short resource/annotation IDs and full URIs.
- * Full URIs are required by W3C Web Annotation Data Model.
- */
-
-/**
- * Convert resource ID to full URI
- *
- * @param id - Short resource ID (e.g., "doc-abc123")
- * @param publicURL - Backend base URL
- * @returns Full URI (e.g., "https://api.semiont.app/resources/doc-abc123")
- *
- * @example
- * resourceIdToURI("doc-abc123", "https://api.semiont.app")
- * // => "https://api.semiont.app/resources/doc-abc123"
- */
-declare function resourceIdToURI(id: ResourceId, publicURL: string): ResourceUri;
-/**
- * Extract resource ID from full URI
- *
- * @param uri - Full resource URI (e.g., "https://api.semiont.app/resources/doc-abc123")
- * @returns Short resource ID (e.g., "doc-abc123")
- * @throws Error if URI format is invalid
- *
- * @example
- * uriToResourceId("https://api.semiont.app/resources/doc-abc123")
- * // => "doc-abc123"
- */
-declare function uriToResourceId(uri: string): ResourceId;
-/**
- * Convert annotation ID to full URI
- *
- * @param id - Short annotation ID (e.g., "anno-xyz789")
- * @param publicURL - Backend base URL
- * @returns Full URI (e.g., "https://api.semiont.app/annotations/anno-xyz789")
- *
- * @example
- * annotationIdToURI("anno-xyz789", "https://api.semiont.app")
- * // => "https://api.semiont.app/annotations/anno-xyz789"
- */
-declare function annotationIdToURI(id: AnnotationId, publicURL: string): AnnotationUri;
-/**
- * Extract annotation ID from full URI
- *
- * @param uri - Full annotation URI (e.g., "https://api.semiont.app/annotations/anno-xyz789")
- * @returns Short annotation ID (e.g., "anno-xyz789")
- * @throws Error if URI format is invalid
- *
- * @example
- * uriToAnnotationId("https://api.semiont.app/annotations/anno-xyz789")
- * // => "anno-xyz789"
- */
-declare function uriToAnnotationId(uri: string): AnnotationId;
-/**
- * Extract annotation ID from URI or pass through if already an ID
- *
- * Defensive version of uriToAnnotationId that handles both:
- * - Full URIs: "https://api.semiont.app/annotations/anno-xyz789" → "anno-xyz789"
- * - Already IDs: "anno-xyz789" → "anno-xyz789"
- *
- * @param uriOrId - Full annotation URI or short ID
- * @returns Short annotation ID
- *
- * @example
- * uriToAnnotationIdOrPassthrough("https://api.semiont.app/annotations/anno-xyz789")
- * // => "anno-xyz789"
- *
- * uriToAnnotationIdOrPassthrough("anno-xyz789")
- * // => "anno-xyz789"
- */
-declare function uriToAnnotationIdOrPassthrough(uriOrId: string): AnnotationId;
-/**
- * Extract resource URI from nested annotation URI
- *
- * @param annotationUri - Nested ResourceAnnotationUri (e.g., "https://api.semiont.app/resources/doc-123/annotations/anno-456")
- * @returns Resource URI (e.g., "https://api.semiont.app/resources/doc-123")
- * @throws Error if URI format is invalid
- *
- * @example
- * extractResourceUriFromAnnotationUri("https://api.semiont.app/resources/doc-123/annotations/anno-456")
- * // => "https://api.semiont.app/resources/doc-123"
- */
-declare function extractResourceUriFromAnnotationUri(annotationUri: ResourceAnnotationUri): ResourceUri;
-
 /**
  * Graph types - Models for graph connections and relationships
  */
 
 type ResourceDescriptor = components['schemas']['ResourceDescriptor'];
-type Annotation$4 = components['schemas']['Annotation'];
+type Annotation$5 = components['schemas']['Annotation'];
 /**
  * Represents a connection between resources through annotations
  */
 interface GraphConnection {
     targetResource: ResourceDescriptor;
-    annotations: Annotation$4[];
+    annotations: Annotation$5[];
     relationshipType?: string;
     bidirectional: boolean;
 }
@@ -3398,7 +3632,7 @@ interface GraphConnection {
  */
 interface GraphPath {
     resources: ResourceDescriptor[];
-    annotations: Annotation$4[];
+    annotations: Annotation$5[];
 }
 /**
  * Statistics about entity types in the graph
@@ -3421,7 +3655,7 @@ interface EntityTypeStats {
  * - Optional signatures for cross-org verification
  */
 
-type Annotation$3 = components['schemas']['Annotation'];
+type Annotation$4 = components['schemas']['Annotation'];
 type ContentFormat = components['schemas']['ContentFormat'];
 type Motivation$1 = components['schemas']['Motivation'];
 interface BaseEvent {
@@ -3499,7 +3733,7 @@ interface RepresentationRemovedEvent extends BaseEvent {
 interface AnnotationAddedEvent extends BaseEvent {
     type: 'annotation.added';
     payload: {
-        annotation: Omit<Annotation$3, 'creator' | 'created'>;
+        annotation: Annotation$4;
     };
 }
 interface AnnotationRemovedEvent extends BaseEvent {
@@ -3651,7 +3885,7 @@ interface EventQuery {
 }
 interface ResourceAnnotations {
     resourceId: ResourceId;
-    annotations: Annotation$3[];
+    annotations: Annotation$4[];
     version: number;
     updatedAt: string;
 }
@@ -3688,8 +3922,8 @@ declare function isResourceEvent(event: any): event is StoredEvent;
  */
 
 type Selector = components['schemas']['TextPositionSelector'] | components['schemas']['TextQuoteSelector'] | components['schemas']['SvgSelector'] | components['schemas']['FragmentSelector'];
-type YieldContext = components['schemas']['YieldContext'];
-type Annotation$2 = components['schemas']['Annotation'];
+type GatheredContext = components['schemas']['GatheredContext'];
+type Annotation$3 = components['schemas']['Annotation'];
 type Motivation = components['schemas']['Motivation'];
 /**
  * Progress state for resource yield workflow
@@ -3760,21 +3994,16 @@ interface MarkProgress {
  */
 type EventMap = {
     'make-meaning:event': ResourceEvent;
-    'yield:modal-open': {
-        annotationUri: string;
-        resourceUri: string;
-        defaultTitle: string;
-    };
     'yield:request': {
-        annotationUri: string;
-        resourceUri: string;
+        annotationId: AnnotationId;
+        resourceId: ResourceId;
         options: {
             title: string;
             prompt?: string;
             language?: string;
             temperature?: number;
             maxTokens?: number;
-            context: YieldContext;
+            context: GatheredContext;
         };
     };
     'yield:progress': YieldProgress;
@@ -3788,7 +4017,68 @@ type EventMap = {
     'yield:representation-removed': Extract<ResourceEvent, {
         type: 'representation.removed';
     }>;
+    'yield:create': {
+        name: string;
+        content: Buffer;
+        format: components['schemas']['ContentFormat'];
+        userId: UserId;
+        language?: string;
+        entityTypes?: string[];
+        creationMethod?: CreationMethod;
+        isDraft?: boolean;
+        generatedFrom?: string;
+        generationPrompt?: string;
+    };
+    'yield:created': {
+        resourceId: ResourceId;
+        resource: components['schemas']['ResourceDescriptor'];
+    };
+    'yield:create-failed': {
+        error: Error;
+    };
     'yield:clone': void;
+    'yield:clone-token-requested': {
+        correlationId: string;
+        resourceId: ResourceId;
+    };
+    '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;
+    };
+    '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;
+        };
+    };
+    'yield:clone-create-failed': {
+        correlationId: string;
+        error: Error;
+    };
     'mark:select-comment': SelectionData;
     'mark:select-tag': SelectionData;
     'mark:select-assessment': SelectionData;
@@ -3798,26 +4088,42 @@ type EventMap = {
         motivation: Motivation;
     };
     'mark:cancel-pending': void;
-    'mark:create': {
+    'mark:submit': {
         motivation: Motivation;
         selector: Selector | Selector[];
         body: components['schemas']['AnnotationBody'][];
     };
+    'mark:create': {
+        annotation: Annotation$3;
+        userId: UserId;
+        resourceId: ResourceId;
+    };
     'mark:created': {
-        annotation: Annotation$2;
+        annotationId: AnnotationId;
     };
     'mark:create-failed': {
         error: Error;
     };
     'mark:delete': {
-        annotationId: string;
+        annotationId: AnnotationId;
+        userId?: UserId;
+        resourceId?: ResourceId;
     };
     'mark:deleted': {
-        annotationId: string;
+        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: {
@@ -3833,7 +4139,7 @@ type EventMap = {
     'mark:progress': MarkProgress;
     'mark:assist-finished': {
         motivation?: Motivation;
-        resourceUri?: ResourceUri;
+        resourceId?: ResourceId;
         progress?: MarkProgress;
     };
     'mark:assist-failed': Extract<ResourceEvent, {
@@ -3866,30 +4172,64 @@ type EventMap = {
     'mark:entity-tag-removed': Extract<ResourceEvent, {
         type: 'entitytag.removed';
     }>;
-    'mark:archive': void;
+    '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: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;
+    };
     'mark:archived': Extract<ResourceEvent, {
         type: 'resource.archived';
     }>;
-    'mark:unarchive': void;
+    'mark:unarchive': void | {
+        userId: UserId;
+        resourceId?: ResourceId;
+    };
     'mark:unarchived': Extract<ResourceEvent, {
         type: 'resource.unarchived';
     }>;
-    'bind:create-manual': {
-        annotationUri: string;
-        title: string;
+    'bind:initiate': {
+        annotationId: AnnotationId;
+        resourceId: ResourceId;
+        defaultTitle: string;
         entityTypes: string[];
     };
-    'bind:link': {
-        annotationUri: string;
-        searchTerm: string;
-    };
     'bind:search-requested': {
+        correlationId?: string;
         referenceId: string;
-        searchTerm: string;
+        context: GatheredContext;
+        limit?: number;
+        useSemanticScoring?: boolean;
     };
     'bind:update-body': {
-        annotationUri: string;
-        resourceId: string;
+        annotationId: AnnotationId;
+        resourceId: ResourceId;
+        userId?: UserId;
         operations: Array<{
             op: 'add' | 'remove' | 'replace';
             item?: components['schemas']['AnnotationBody'];
@@ -3898,21 +4238,75 @@ type EventMap = {
         }>;
     };
     'bind:body-updated': {
-        annotationUri: string;
+        annotationId: AnnotationId;
     };
     'bind:body-update-failed': {
         error: Error;
     };
+    'bind:search-results': {
+        referenceId: string;
+        results: Array<components['schemas']['ResourceDescriptor'] & {
+            score?: number;
+            matchReason?: string;
+        }>;
+        correlationId?: string;
+    };
+    'bind: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': {
-        annotationUri: string;
-        resourceUri: string;
+        correlationId?: string;
+        annotationId: AnnotationId;
+        resourceId: ResourceId;
+        options?: {
+            includeSourceContext?: boolean;
+            includeTargetContext?: boolean;
+            contextWindow?: number;
+        };
     };
     'gather:complete': {
-        annotationUri: string;
-        context: YieldContext;
+        correlationId?: string;
+        annotationId: AnnotationId;
+        response: components['schemas']['AnnotationLLMContextResponse'];
     };
     'gather:failed': {
-        annotationUri: string;
+        correlationId?: string;
+        annotationId: AnnotationId;
+        error: Error;
+    };
+    'gather:resource-requested': {
+        correlationId?: string;
+        resourceId: ResourceId;
+        options: {
+            depth: number;
+            maxResources: number;
+            includeContent: boolean;
+            includeSummary: boolean;
+        };
+    };
+    'gather:resource-complete': {
+        correlationId?: string;
+        resourceId: ResourceId;
+        context: components['schemas']['ResourceLLMContextResponse'];
+    };
+    'gather:resource-failed': {
+        correlationId?: string;
+        resourceId: ResourceId;
         error: Error;
     };
     'browse:click': {
@@ -3955,6 +4349,87 @@ type EventMap = {
     'browse:entity-type-clicked': {
         entityType: string;
     };
+    'browse:resource-requested': {
+        correlationId: string;
+        resourceId: ResourceId;
+    };
+    'browse:resource-result': {
+        correlationId: string;
+        response: components['schemas']['GetResourceResponse'];
+    };
+    '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'];
+    };
+    'browse:resources-failed': {
+        correlationId: string;
+        error: Error;
+    };
+    'browse:annotations-requested': {
+        correlationId: string;
+        resourceId: ResourceId;
+    };
+    'browse:annotations-result': {
+        correlationId: string;
+        response: components['schemas']['GetAnnotationsResponse'];
+    };
+    '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'];
+    };
+    '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'];
+    };
+    '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'];
+    };
+    'browse:annotation-history-failed': {
+        correlationId: string;
+        error: Error;
+    };
     'beckon:hover': {
         annotationId: string | null;
     };
@@ -3964,6 +4439,34 @@ type EventMap = {
     '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';
     }>;
@@ -3984,6 +4487,18 @@ type EventMap = {
     'job:cancel-requested': {
         jobType: 'annotation' | 'generation';
     };
+    'job:status-requested': {
+        correlationId: string;
+        jobId: JobId;
+    };
+    'job:status-result': {
+        correlationId: string;
+        response: components['schemas']['JobStatusResponse'];
+    };
+    'job:status-failed': {
+        correlationId: string;
+        error: Error;
+    };
     'settings:theme-changed': {
         theme: 'light' | 'dark' | 'system';
     };
@@ -4220,12 +4735,64 @@ interface Logger {
  * Backend-specific annotation utility functions
  */
 
-type Annotation$1 = components['schemas']['Annotation'];
+type Annotation$2 = components['schemas']['Annotation'];
 /**
  * Find a body item in an array
  * Returns the index of the first matching item, or -1 if not found
  */
-declare function findBodyItem(body: Annotation$1['body'], targetItem: BodyItem): number;
+declare function findBodyItem(body: Annotation$2['body'], targetItem: BodyItem): number;
+
+/**
+ * Annotation Assembly
+ *
+ * Pure functions for building W3C Annotations and applying body operations.
+ * No EventBus, no persistence — just data transformation.
+ */
+
+type Agent$1 = components['schemas']['Agent'];
+type Annotation$1 = components['schemas']['Annotation'];
+type AnnotationBody = components['schemas']['AnnotationBody'];
+type CreateAnnotationRequest = components['schemas']['CreateAnnotationRequest'];
+type UpdateAnnotationBodyRequest = components['schemas']['UpdateAnnotationBodyRequest'];
+type TextPositionSelector = components['schemas']['TextPositionSelector'];
+type SvgSelector = components['schemas']['SvgSelector'];
+type FragmentSelector = components['schemas']['FragmentSelector'];
+interface AssembledAnnotation {
+    annotation: Annotation$1;
+    bodyArray: AnnotationBody[];
+}
+/**
+ * Get TextPositionSelector from a selector (single or array)
+ */
+declare function getTextPositionSelector(selector: Selector | Selector[] | undefined): TextPositionSelector | null;
+/**
+ * Get SvgSelector from a selector (single or array)
+ */
+declare function getSvgSelector(selector: Selector | Selector[] | undefined): SvgSelector | null;
+/**
+ * Get FragmentSelector from a selector (single or array)
+ */
+declare function getFragmentSelector(selector: Selector | Selector[] | undefined): FragmentSelector | null;
+/**
+ * Validate SVG markup for W3C compliance
+ *
+ * @returns null if valid, error message if invalid
+ */
+declare function validateSvgMarkup(svg: string): string | null;
+/**
+ * Build a complete W3C Annotation from a CreateAnnotationRequest.
+ *
+ * Generates a bare annotation ID (no URL prefix). URIs are constructed
+ * at the API boundary when returning responses to clients.
+ *
+ * Throws on invalid input (missing selector, missing motivation, invalid SVG).
+ */
+declare function assembleAnnotation(request: CreateAnnotationRequest, creator: Agent$1): AssembledAnnotation;
+/**
+ * Apply body operations (add/remove/replace) to an annotation's body array.
+ * Returns a new array — does not mutate the input.
+ */
+declare function applyBodyOperations(body: Annotation$1['body'], operations: UpdateAnnotationBodyRequest['operations']): AnnotationBody[];
 
 /**
  * Resource input/output types
@@ -4264,6 +4831,14 @@ interface GoogleAuthRequest {
     termsAccepted: boolean;
 }
 
+/**
+ * ID generation utilities
+ */
+/**
+ * Generate a UUID v4-like ID (without dashes)
+ */
+declare function generateUuid(): string;
+
 /**
  * Common type guard utilities
  */
@@ -5258,4 +5833,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, type BurstBufferOptions, 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 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 MarkProgress, 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, type YieldContext, type YieldProgress, accessToken, annotationId, annotationIdToURI, annotationUri, authCode, baseUrl, burstBuffer, 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 AnnotationRemovedEvent, type AnnotationUri, type AppConfig, type AssembledAnnotation, type AuthCode, type BackendServiceConfig, type BaseEvent, type BaseUrl, type BodyItem, type BodyOperation, type BurstBufferOptions, 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 GatheredContext, 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 MarkProgress, 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, type YieldProgress, accessToken, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseUrl, burstBuffer, cloneToken, type components, createConfigLoader, deepMerge, didToAgent, displayConfiguration, email, entityType, findBodyItem, formatErrors, generateUuid, getAllPlatformTypes, getAnnotationUriFromEvent, getEventType, getFragmentSelector, getNodeEnvForEnvironment, getSvgSelector, getTextPositionSelector, 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, resourceUri, searchQuery, userDID, userId, userToAgent, userToDid, validateEnvironment, validateEnvironmentConfig, validateSemiontConfig, validateSiteConfig, validateSvgMarkup };