@semiont/core 0.5.22 → 0.5.24

package/dist/index.d.ts

@@ -1265,32 +1265,28 @@ interface paths {
             path?: never;
             cookie?: never;
         };
+        get?: never;
+        put?: never;
         /**
          * Subscribe to the Semiont event bus (SSE)
-         * @description Opens a long-lived Server-Sent Events stream over which the bus delivers events matching the requested channels and scopes.
+         * @description Opens a long-lived Server-Sent Events stream over which the bus delivers events matching the requested subscription matrix. The JSON body names unscoped `global` channels plus any number of `scoped` entries — one per resource scope — so a single connection can hold live subscriptions to many resources at once (MULTI-RESOURCE-SCOPE).
          *
-         *     Each SSE frame has `event: bus-event`, a JSON-encoded `data` of the form `{ channel, payload, scope? }`, and an `id` (either a persisted event id, `scope:seq`, for domain events; or an ephemeral id for job-lifecycle / result channels).
+         *     Each SSE frame has `event: bus-event`, a JSON-encoded `data` of the form `{ channel, payload, scope? }` (scoped events carry their originating scope), and an `id` (a persisted event id `p-<scope>-<seq>` for domain events; an ephemeral `e-*` id for job-lifecycle / correlated-reply channels).
          *
-         *     Pass the last-received id as `Last-Event-ID` to resume — the server replays missed persisted events and emits a `bus:resume-gap` synthetic event when the gap exceeds the replay window.
+         *     Resumption is per scope: pass each scope's last-received persisted id as `lastEventId` on its scoped entry — the server replays that scope's missed persisted events and emits a scoped `bus:resume-gap` synthetic event when the gap cannot be covered.
          */
-        get: {
+        post: {
             parameters: {
-                query?: {
-                    /** @description Unscoped channels to subscribe to. Repeat the parameter for multiple channels. At least one of `channel` or `scoped` is required. */
-                    channel?: string[];
-                    /** @description Resource-scoped channels to subscribe to (requires `scope`). Repeat for multiple. */
-                    scoped?: string[];
-                    /** @description Resource scope for scoped channels (typically a resourceId). */
-                    scope?: string;
-                };
-                header?: {
-                    /** @description Id of the last event the client received. On reconnect, the server replays persisted events after this id and emits `bus:resume-gap` if the gap exceeds the replay cap. */
-                    "Last-Event-ID"?: string;
-                };
+                query?: never;
+                header?: never;
                 path?: never;
                 cookie?: never;
             };
-            requestBody?: never;
+            requestBody: {
+                content: {
+                    "application/json": components["schemas"]["BusSubscribeRequest"];
+                };
+            };
             responses: {
                 /** @description SSE stream opened */
                 200: {
@@ -1301,7 +1297,7 @@ interface paths {
                         "text/event-stream": components["schemas"]["EventStreamResponse"];
                     };
                 };
-                /** @description No channels requested (at least one `channel` or `scoped` parameter required) */
+                /** @description Malformed body, no channels requested, duplicate scopes, malformed scoped entry, or scope count above the per-connection cap */
                 400: {
                     headers: {
                         [name: string]: unknown;
@@ -1321,8 +1317,6 @@ interface paths {
                 };
             };
         };
-        put?: never;
-        post?: never;
         delete?: never;
         options?: never;
         head?: never;
@@ -2124,6 +2118,22 @@ interface components {
             /** @description Optional resource scope for broadcast channels (e.g. resourceId). Publishers only — frontends must never set this. */
             scope?: string;
         };
+        /** @description Subscription matrix for the bus SSE stream (MULTI-RESOURCE-SCOPE). `global` channels are delivered unscoped; each `scoped` entry subscribes the connection to one resource scope's channels, optionally resuming replay from that scope's last-seen persisted event id. At least one global channel or one scoped entry is required. */
+        BusSubscribeRequest: {
+            /** @description Unscoped channels to subscribe to. */
+            global?: string[];
+            /** @description Correlation ids of busRequest replies this client still awaits (BUS-RESUMPTION Phase 2). The server replays any matching replies from its bounded retention buffer (TTL 60s) as normal frames with their deterministic `e-<channel>:<cid>` ids, so a reply that ALSO arrived live dedups client-side. At most 256 entries. */
+            pendingReplies?: string[];
+            /** @description Per-resource-scope subscriptions. Scopes must be unique across entries. */
+            scoped?: {
+                /** @description Resource scope (a resourceId). */
+                scope: string;
+                /** @description Channels to subscribe within this scope. */
+                channels: string[];
+                /** @description This scope's last-seen persisted event id (`p-<scope>-<seq>`). The server replays this scope's persisted events after it before joining the live tail, and emits a scoped `bus:resume-gap` when it cannot cover the gap (unparseable or mismatched id, retention exceeded, or query error). */
+                lastEventId?: string;
+            }[];
+        };
         CloneResourceWithTokenResponse: {
             /** @description Generated clone token */
             token: string;
@@ -5389,8 +5399,9 @@ interface ITransport {
      * SDK-internal: this is the scope primitive the SDK's resource-scoped
      * `browse.*` live queries drive on subscribe/teardown (freshness follows
      * observation; #847) — it is not part of the application-facing surface.
-     * Single-scope at a time; multi-scope is deferred
-     * (`.plans/MULTI-RESOURCE-SCOPE.md`).
+     * Distinct resources COMPOSE (`.plans/MULTI-RESOURCE-SCOPE.md`): each
+     * resource's subscriptions are ref-counted independently, and one client
+     * may hold many resource scopes at once on its single connection.
      */
     subscribeToResource(resourceId: ResourceId): () => void;
     /**
@@ -5406,8 +5417,24 @@ interface ITransport {
      * Transport-level connection state. For HTTP, reflects the SSE
      * connection's health; for in-process transports, typically `'open'`
      * from construction onward (no connection to lose).
+     *
+     * Load-bearing beyond UI: `busRequest` gates its emit on this
+     * (`BusRequestPrimitive.state$`, .plans/BUS-ATTACH-GATE.md) — no
+     * correlated emit before the reply path exists. Implementers back it
+     * with a `BehaviorSubject` so the current state arrives synchronously
+     * on subscribe.
      */
     readonly state$: Observable<ConnectionState>;
+    /**
+     * Correlated-reply retention, client side (BUS-RESUMPTION Phase 2 /
+     * SDK-DEBT S1). `busRequest` registers its correlationId here before
+     * emitting and releases on settle; a wire transport includes the
+     * tracked set as `pendingReplies` on each subscribe body so a reply
+     * published while the connection was down replays from the server's
+     * retention buffer. OPTIONAL: in-process transports that cannot lose
+     * replies omit it.
+     */
+    trackReply?(correlationId: string): () => void;
     /**
      * Stream of transport-level errors surfaced from typed-wire methods or
      * other transport-mediated round-trips, just before they're thrown to
@@ -5536,6 +5563,33 @@ interface IContentTransport {
     dispose(): void;
 }
 
+/**
+ * BUS_OPERATIONS — the request/reply operations registry (Tier 1).
+ *
+ * Each entry declares ONE operation as the triple that was previously three
+ * loose, independently-maintained facts spread across call sites:
+ *   - the request channel (the key — an `EmittableChannel`),
+ *   - the `result` channel (success reply),
+ *   - the `failure` channel,
+ *   - and, for a streaming op, an optional `progress` channel.
+ *
+ * `BridgedChannel` / `BRIDGED_CHANNELS` are DERIVED from this map
+ * (bridged-channels.ts): every reply lands in the bridged fan-in set by
+ * construction, so "a reply channel forgotten from BRIDGED_CHANNELS" — the
+ * recurring bug class (gather:resource-complete, frame:*-add-failed) — is no
+ * longer representable. See .plans/BUS-OPERATIONS-REGISTRY.md.
+ *
+ * `Partial<Record<EmittableChannel, …>>` enforces that every key is a real
+ * emittable request. `result`/`failure`/`progress` stay `EventName` rather than
+ * `BridgedChannel` to avoid a circular reference (BridgedChannel derives from
+ * this map); the derivation closes the loop instead.
+ */
+interface BusOperationSpec {
+    result: EventName;
+    failure: EventName;
+    /** Streaming ops only: an intermediate channel that also bridges. */
+    progress?: EventName;
+}
 declare const BUS_OPERATIONS: {
     readonly 'bind:update-body': {
         readonly result: "bind:body-updated";
@@ -5744,6 +5798,26 @@ declare class BusRequestError extends SemiontError {
 interface BusRequestPrimitive {
     emit<K extends keyof EventMap>(channel: K, payload: EventMap[K]): Promise<void>;
     stream<K extends keyof EventMap>(channel: K): Observable<EventMap[K]>;
+    /**
+     * Connection state of the stream that carries replies. Required, not
+     * optional (.plans/BUS-ATTACH-GATE.md D2): `busRequest` gates its emit on
+     * this — no correlated emit before the reply path exists. Implementers back
+     * it with a `BehaviorSubject`, so the current state arrives synchronously
+     * on subscribe; a transport that cannot lose replies (in-process) reports
+     * `'open'` until disposal.
+     */
+    state$: Observable<ConnectionState>;
+    /**
+     * Correlated-reply retention, client side (.plans/BUS-RESUMPTION.md
+     * Phase 2 / SDK-DEBT S1). `busRequest` registers its correlationId here
+     * BEFORE emitting and calls the returned disposer on every settle path;
+     * a wire transport includes the currently-tracked ids as
+     * `pendingReplies` in each subscribe body, so a reply published while
+     * the connection was down is replayed from the server's retention
+     * buffer on reconnect. OPTIONAL: an in-process transport that cannot
+     * lose replies omits the surface and `busRequest` behaves as before.
+     */
+    trackReply?(correlationId: string): () => void;
 }
 /**
  * Request/reply over the bus, keyed by the operation's request channel.
@@ -6422,12 +6496,30 @@ interface GoogleAuthRequest {
 }
 
 /**
- * ID generation utilities
+ * ID generation utilities.
+ *
+ * Built on `crypto.getRandomValues()`, NOT `crypto.randomUUID()`: browsers
+ * expose `randomUUID` only in secure contexts (https, `http://localhost`,
+ * `http://127.0.0.1`), so a page served over plain http from any other host
+ * has no `randomUUID` and calling it throws — which broke the frontend from
+ * the host-gateway IP (.plans/bugs/crypto-randomuuid-insecure-context.md).
+ * `getRandomValues` is cryptographically sound and available in ALL contexts,
+ * Node and browser, secure or not.
  */
 /**
- * Generate a UUID v4 string (without dashes)
+ * Generate a UUID v4 string WITHOUT dashes (32 hex chars).
+ *
+ * The dashless form is data shape: persisted annotation/resource/job ids are
+ * built from it and land in URIs. Do not change the format.
  */
 declare function generateUuid(): string;
+/**
+ * Generate a canonical dashed UUID v4 (36 chars, 8-4-4-4-12) — the format
+ * `crypto.randomUUID()` produces, without its secure-context requirement.
+ *
+ * Use for ephemeral wire ids (`correlationId`s and the like).
+ */
+declare function uuidV4(): string;
 
 /**
  * Marker for the state-unit pattern: a stateful, lifecycled object with an
@@ -7202,7 +7294,7 @@ type TomlFileReader = {
  *
  * @param projectRoot - Path to the project root (contains .semiont/config)
  * @param environment - Environment name (e.g. 'local', 'production'); when
- *   undefined, resolved from SEMIONT_ENV, then `[defaults] environment`
+ *   undefined, resolved from `[defaults] environment`
  * @param globalConfigPath - Path to ~/.semiontconfig (caller resolves ~ expansion)
  * @param reader - File reader abstraction
  * @param env - Environment variables for ${VAR} resolution
@@ -7373,5 +7465,5 @@ declare function retryWithBackoff<T>(fn: () => Promise<T>, isRetryable: (error:
  */
 declare const DISCOVERY_URL_PATH = "/discovery/kbs.json";
 
-export { AUTHORABLE_MEDIA_TYPES, BRIDGED_CHANNELS, BusRequestError, CHANNEL_SCHEMAS, CONTEXT_FULL_WEIGHT, CONTEXT_PARTIAL_WEIGHT, ConfigurationError, ConflictError, DISCOVERY_URL_PATH, EMBEDDABLE_MEDIA_TYPES, EventBus, JWTTokenSchema, LOCALES, MEDIA_TYPES, NotFoundError, PERSISTED_EVENT_TYPES, POSITION_WEIGHT_MAX, POSITION_WINDOW, RESOURCE_BROADCAST_TYPES, STARTUP_FETCH_RETRY, ScopedEventBus, ScriptError, SemiontError, UnauthorizedError, ValidationError, accessToken, agentToDid, anchorAnnotation, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseMediaType, baseUrl, buildContentCache, burstBuffer, busLog, busLogEnabled, busRequest, capabilitiesOf, cloneToken, createCircleSvg, createFragmentSelector, createPolygonSvg, createRectangleSvg, createTomlConfigLoader, decodeRepresentation, decodeWithCharset, deriveViews, didToAgent, email, entityType, errField, extensionForMediaType, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findBodyItem, formatLocaleDisplay, generateUuid, getAllLocaleCodes, getAllPlatformTypes, getAnnotationExactText, getAnnotationUriFromEvent, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getFragmentSelector, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getNodeEncoding, getPageFromFragment, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getStorageUri, getSvgSelector, getTargetSelector, getTargetSource, getTextPositionSelector, getTextQuoteSelector, googleCredential, hasTargetSelector, isAnnotationId, isArchived, isArray, isAssessment, isBodyResolved, isBoolean, isComment, isDefined, isDraft, isEventRelatedToAnnotation, isFunction, isHighlight, isNull, isNullish, isNumber, isObject, isReference, isResolvedReference, isResourceId, isStoredEvent, isString, isStubReference, isSupportedMediaType, isTag, isTransientFetchError, isUndefined, isValidEmail, isValidPlatformType, jobId, kbDid, loadTomlConfig, mcpToken, mediaTypeForExtension, normalizeCoordinates, normalizeText, parseEnvironment, parseFragmentSelector, parseSvgSelector, reconcileSelector, refreshToken, resourceAnnotationUri, resourceId, resourceUri, retryWithBackoff, scaleSvgToNative, searchQuery, serializePerKey, setBusLogTraceIdProvider, softwareToAgent, textExtractionOf, userDID, userId, userToAgent, userToDid, validateData, validateEnvironment, validateSvgMarkup, verifyPosition };
-export type { AccessToken, AnchorConfidence, AnchorMethod, AnchorRect, AnchorSelectors, AnchorStrategy, AnchoringModel, Annotation, AnnotationCategory, AnnotationId, AnnotationUri, AnthropicProviderConfig, AppConfig, AssembledAnnotation, AuthCode, BackendDownload, BackendServiceConfig, BaseUrl, BodyItem, BodyItemIdentity, BodyOperation, BoundingBox, Brand, BridgedChannel, BurstBufferOptions, BusOp, BusRequestErrorCode, BusRequestPrimitive, CloneToken, CollaboratorEntry, ConnectionState, ContentCache, ContentFormat, CreateAnnotationInternal, DatabaseServiceConfig, DiscoveredKB, DiscoveryDocument, Email, EmbeddingServiceConfig, EmittableChannel, EntityType, EntityTypeStats, Environment, EnvironmentConfig, EventBase, EventInput, EventMap, EventMetadata, EventName, EventOfType, EventQuery, EventSignature, FragmentSelector, FrontendServiceConfig, GatheredContext, GoogleAuthRequest, GoogleCredential, GraphConnection, GraphDatabaseType, GraphPath, GraphServiceConfig, GraphViews, HealthCheckResponse, IBackendOperations, IContentTransport, ITransport, InferenceProvidersConfig, JobId, JobType, ListUsersResponse, LlmSelectorInput, LocaleInfo, Logger, MCPToken, MatchQuality, McpServiceConfig, MediaTypeCapabilities, Motivation, OllamaProviderConfig, PdfCoordinate, PersistedEvent, PersistedEventType, PlatformType, Point, ProgressCallback, ProgressEvent, PutBinaryOptions, PutBinaryProgress, PutBinaryRequest, ReconciledSelector, RefreshToken, RenderMode, RenderedAnchor, ResourceAnnotationUri, ResourceAnnotations, ResourceBroadcastType, ResourceDescriptor, ResourceFilter, ResourceId, ResourceUri, RetryAttemptInfo, RetryPolicy, SearchQuery, SelectionData, Selector, SemiontConfig, ServicePlatformConfig, ServicesConfig, SiteConfig, StateUnit, StatusResponse, StoredEvent, StoredEventLike, SupportedMediaType, SvgSelector, TagCategory, TagSchema, TextExtraction, TextPosition, TextPositionSelector, TextQuoteSelector, ActorInferenceConfig as TomlActorInferenceConfig, TomlFileReader, InferenceConfig as TomlInferenceConfig, WorkerInferenceConfig as TomlWorkerInferenceConfig, TransportErrorCode, UpdateResourceInput, UpdateUserRequest, UpdateUserResponse, UserDID, UserId, UserResponse, ValidationFailure, ValidationResult, ValidationSuccess, VectorsServiceConfig, components, operations, paths };
+export { AUTHORABLE_MEDIA_TYPES, BRIDGED_CHANNELS, BUS_OPERATIONS, BusRequestError, CHANNEL_SCHEMAS, CONTEXT_FULL_WEIGHT, CONTEXT_PARTIAL_WEIGHT, ConfigurationError, ConflictError, DISCOVERY_URL_PATH, EMBEDDABLE_MEDIA_TYPES, EventBus, JWTTokenSchema, LOCALES, MEDIA_TYPES, NotFoundError, PERSISTED_EVENT_TYPES, POSITION_WEIGHT_MAX, POSITION_WINDOW, RESOURCE_BROADCAST_TYPES, STARTUP_FETCH_RETRY, ScopedEventBus, ScriptError, SemiontError, UnauthorizedError, ValidationError, accessToken, agentToDid, anchorAnnotation, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseMediaType, baseUrl, buildContentCache, burstBuffer, busLog, busLogEnabled, busRequest, capabilitiesOf, cloneToken, createCircleSvg, createFragmentSelector, createPolygonSvg, createRectangleSvg, createTomlConfigLoader, decodeRepresentation, decodeWithCharset, deriveViews, didToAgent, email, entityType, errField, extensionForMediaType, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findBodyItem, formatLocaleDisplay, generateUuid, getAllLocaleCodes, getAllPlatformTypes, getAnnotationExactText, getAnnotationUriFromEvent, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getFragmentSelector, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getNodeEncoding, getPageFromFragment, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getStorageUri, getSvgSelector, getTargetSelector, getTargetSource, getTextPositionSelector, getTextQuoteSelector, googleCredential, hasTargetSelector, isAnnotationId, isArchived, isArray, isAssessment, isBodyResolved, isBoolean, isComment, isDefined, isDraft, isEventRelatedToAnnotation, isFunction, isHighlight, isNull, isNullish, isNumber, isObject, isReference, isResolvedReference, isResourceId, isStoredEvent, isString, isStubReference, isSupportedMediaType, isTag, isTransientFetchError, isUndefined, isValidEmail, isValidPlatformType, jobId, kbDid, loadTomlConfig, mcpToken, mediaTypeForExtension, normalizeCoordinates, normalizeText, parseEnvironment, parseFragmentSelector, parseSvgSelector, reconcileSelector, refreshToken, resourceAnnotationUri, resourceId, resourceUri, retryWithBackoff, scaleSvgToNative, searchQuery, serializePerKey, setBusLogTraceIdProvider, softwareToAgent, textExtractionOf, userDID, userId, userToAgent, userToDid, uuidV4, validateData, validateEnvironment, validateSvgMarkup, verifyPosition };
+export type { AccessToken, AnchorConfidence, AnchorMethod, AnchorRect, AnchorSelectors, AnchorStrategy, AnchoringModel, Annotation, AnnotationCategory, AnnotationId, AnnotationUri, AnthropicProviderConfig, AppConfig, AssembledAnnotation, AuthCode, BackendDownload, BackendServiceConfig, BaseUrl, BodyItem, BodyItemIdentity, BodyOperation, BoundingBox, Brand, BridgedChannel, BurstBufferOptions, BusOp, BusOperationKey, BusOperationSpec, BusRequestErrorCode, BusRequestPrimitive, CloneToken, CollaboratorEntry, ConnectionState, ContentCache, ContentFormat, CreateAnnotationInternal, DatabaseServiceConfig, DiscoveredKB, DiscoveryDocument, Email, EmbeddingServiceConfig, EmittableChannel, EntityType, EntityTypeStats, Environment, EnvironmentConfig, EventBase, EventInput, EventMap, EventMetadata, EventName, EventOfType, EventQuery, EventSignature, FragmentSelector, FrontendServiceConfig, GatheredContext, GoogleAuthRequest, GoogleCredential, GraphConnection, GraphDatabaseType, GraphPath, GraphServiceConfig, GraphViews, HealthCheckResponse, IBackendOperations, IContentTransport, ITransport, InferenceProvidersConfig, JobId, JobType, ListUsersResponse, LlmSelectorInput, LocaleInfo, Logger, MCPToken, MatchQuality, McpServiceConfig, MediaTypeCapabilities, Motivation, OllamaProviderConfig, PdfCoordinate, PersistedEvent, PersistedEventType, PlatformType, Point, ProgressCallback, ProgressEvent, PutBinaryOptions, PutBinaryProgress, PutBinaryRequest, ReconciledSelector, RefreshToken, RenderMode, RenderedAnchor, ResourceAnnotationUri, ResourceAnnotations, ResourceBroadcastType, ResourceDescriptor, ResourceFilter, ResourceId, ResourceUri, RetryAttemptInfo, RetryPolicy, SearchQuery, SelectionData, Selector, SemiontConfig, ServicePlatformConfig, ServicesConfig, SiteConfig, StateUnit, StatusResponse, StoredEvent, StoredEventLike, SupportedMediaType, SvgSelector, TagCategory, TagSchema, TextExtraction, TextPosition, TextPositionSelector, TextQuoteSelector, ActorInferenceConfig as TomlActorInferenceConfig, TomlFileReader, InferenceConfig as TomlInferenceConfig, WorkerInferenceConfig as TomlWorkerInferenceConfig, TransportErrorCode, UpdateResourceInput, UpdateUserRequest, UpdateUserResponse, UserDID, UserId, UserResponse, ValidationFailure, ValidationResult, ValidationSuccess, VectorsServiceConfig, components, operations, paths };