@semiont/core 0.5.0 → 0.5.2

package/README.md

@@ -336,4 +336,4 @@ Apache-2.0
 
 - [W3C Web Annotation Model](https://www.w3.org/TR/annotation-model/) - Annotation standard
 - [DID:WEB Specification](https://w3c-ccg.github.io/did-method-web/) - Decentralized identifiers
-- [W3C Selectors](../../specs/docs/W3C-SELECTORS.md) - Selector implementation details
+- [W3C Selectors](../../docs/protocol/W3C-SELECTORS.md) - Selector implementation details

package/dist/index.d.ts

@@ -2223,7 +2223,7 @@ interface components {
             annotationId: string;
             operations: (components["schemas"]["BodyOperationAdd"] | components["schemas"]["BodyOperationRemove"] | components["schemas"]["BodyOperationReplace"])[];
         };
-        /** @description Payload for mark:entity-type-added domain event */
+        /** @description Payload for frame:entity-type-added domain event (system-level, no resourceId — fan-out is global) */
         EntityTypeAddedPayload: {
             entityType: string;
         };
@@ -3198,8 +3198,8 @@ interface components {
                 [key: string]: number;
             };
         };
-        /** @description Bus command to add a new entity type tag. */
-        MarkAddEntityTypeCommand: {
+        /** @description Bus command to add a new entity type to the KB's vocabulary. Carried on the `frame:add-entity-type` channel — Frame is the schema-layer flow that owns vocabulary writes. */
+        FrameAddEntityTypeCommand: {
             tag: string;
             /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
             _userId?: string;
@@ -3356,10 +3356,11 @@ interface components {
         /** @description Bus command to create a cloned resource from a clone token. */
         YieldCloneCreateCommand: {
             correlationId: string;
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
             token: string;
             name: string;
             content: string;
-            userId: string;
             archiveOriginal?: boolean;
         };
         /** @description Success response after creating a cloned resource. */
@@ -3674,14 +3675,14 @@ type PersistedEventCatalog = {
     'mark:unarchived': components['schemas']['ResourceUnarchivedPayload'];
     'mark:entity-tag-added': components['schemas']['EntityTagChangedPayload'];
     'mark:entity-tag-removed': components['schemas']['EntityTagChangedPayload'];
-    'mark:entity-type-added': components['schemas']['EntityTypeAddedPayload'];
+    'frame:entity-type-added': components['schemas']['EntityTypeAddedPayload'];
     'job:started': components['schemas']['JobStartedPayload'];
     'job:progress': components['schemas']['JobProgressPayload'];
     'job:completed': components['schemas']['JobCompletedPayload'];
     'job:failed': components['schemas']['JobFailedPayload'];
 };
 /** System event types — persisted events that have no resourceId. */
-type SystemEventType = 'mark:entity-type-added';
+type SystemEventType = 'frame:entity-type-added';
 /** Extract the concrete persisted event type for a given type string. */
 type EventOfType<K extends keyof PersistedEventCatalog> = K extends SystemEventType ? EventBase & {
     type: K;
@@ -3706,7 +3707,7 @@ type PersistedEventType = PersistedEvent['type'];
  * also adding it here: forgetting fails to typecheck rather than silently
  * dropping the event from the events-stream.
  */
-declare const PERSISTED_EVENT_TYPES: readonly ["yield:created", "yield:cloned", "yield:updated", "yield:moved", "yield:representation-added", "yield:representation-removed", "mark:added", "mark:removed", "mark:body-updated", "mark:archived", "mark:unarchived", "mark:entity-tag-added", "mark:entity-tag-removed", "mark:entity-type-added", "job:started", "job:progress", "job:completed", "job:failed"];
+declare const PERSISTED_EVENT_TYPES: readonly ["yield:created", "yield:cloned", "yield:updated", "yield:moved", "yield:representation-added", "yield:representation-removed", "mark:added", "mark:removed", "mark:body-updated", "mark:archived", "mark:unarchived", "mark:entity-tag-added", "mark:entity-tag-removed", "frame:entity-type-added", "job:started", "job:progress", "job:completed", "job:failed"];
 /** Input type for appendEvent — PersistedEvent without id/timestamp (assigned at persistence time). */
 type EventInput = Omit<PersistedEvent, 'id' | 'timestamp'>;
 
@@ -3867,7 +3868,6 @@ type EventMap = {
     'mark:body-updated': StoredEvent<EventOfType<'mark:body-updated'>>;
     'mark:entity-tag-added': StoredEvent<EventOfType<'mark:entity-tag-added'>>;
     'mark:entity-tag-removed': StoredEvent<EventOfType<'mark:entity-tag-removed'>>;
-    'mark:entity-type-added': StoredEvent<EventOfType<'mark:entity-type-added'>>;
     'mark:archived': StoredEvent<EventOfType<'mark:archived'>>;
     'mark:unarchived': StoredEvent<EventOfType<'mark:unarchived'>>;
     'mark:create-request': components['schemas']['MarkCreateRequest'];
@@ -3877,13 +3877,11 @@ type EventMap = {
     'mark:archive': components['schemas']['MarkArchiveCommand'];
     'mark:unarchive': components['schemas']['MarkUnarchiveCommand'];
     'mark:update-entity-types': components['schemas']['MarkUpdateEntityTypesCommand'];
-    'mark:add-entity-type': components['schemas']['MarkAddEntityTypeCommand'];
     'mark:create-ok': components['schemas']['MarkCreateOk'];
     'mark:create-failed': components['schemas']['CommandError'];
     'mark:delete-ok': components['schemas']['MarkDeleteOk'];
     'mark:delete-failed': components['schemas']['CommandError'];
     'mark:body-update-failed': components['schemas']['CommandError'];
-    'mark:entity-type-add-failed': components['schemas']['CommandError'];
     'mark:select-comment': components['schemas']['SelectionData'];
     'mark:select-tag': components['schemas']['SelectionData'];
     'mark:select-assessment': components['schemas']['SelectionData'];
@@ -3898,6 +3896,9 @@ type EventMap = {
     'mark:selection-changed': components['schemas']['MarkSelectionChangedEvent'];
     'mark:click-changed': components['schemas']['MarkClickChangedEvent'];
     'mark:shape-changed': components['schemas']['MarkShapeChangedEvent'];
+    'frame:entity-type-added': StoredEvent<EventOfType<'frame:entity-type-added'>>;
+    'frame:add-entity-type': components['schemas']['FrameAddEntityTypeCommand'];
+    'frame:entity-type-add-failed': components['schemas']['CommandError'];
     'bind:initiate': BindInitiateCommand;
     'bind:update-body': BindUpdateBodyCommand;
     'bind:body-updated': components['schemas']['BindBodyUpdated'];
@@ -4078,7 +4079,7 @@ type EventName = keyof EventMap;
  *
  * The frontend's `subscribeToResource(id)` wires these channels via
  * `scope=id&scoped=<channel>` so the SSE route delivers them to that
- * participant. WorkerVM uses this list to decide which emitted events to
+ * participant. WorkerStateUnit uses this list to decide which emitted events to
  * scope to their resource.
  */
 /**
@@ -4144,7 +4145,7 @@ declare const CHANNEL_SCHEMAS: {
     readonly 'mark:body-updated': null;
     readonly 'mark:entity-tag-added': null;
     readonly 'mark:entity-tag-removed': null;
-    readonly 'mark:entity-type-added': null;
+    readonly 'frame:entity-type-added': null;
     readonly 'mark:archived': null;
     readonly 'mark:unarchived': null;
     readonly 'mark:create-request': "MarkCreateRequest";
@@ -4154,13 +4155,13 @@ declare const CHANNEL_SCHEMAS: {
     readonly 'mark:archive': "MarkArchiveCommand";
     readonly 'mark:unarchive': "MarkUnarchiveCommand";
     readonly 'mark:update-entity-types': "MarkUpdateEntityTypesCommand";
-    readonly 'mark:add-entity-type': "MarkAddEntityTypeCommand";
+    readonly 'frame:add-entity-type': "FrameAddEntityTypeCommand";
     readonly 'mark:create-ok': "MarkCreateOk";
     readonly 'mark:create-failed': "CommandError";
     readonly 'mark:delete-ok': "MarkDeleteOk";
     readonly 'mark:delete-failed': "CommandError";
     readonly 'mark:body-update-failed': "CommandError";
-    readonly 'mark:entity-type-add-failed': "CommandError";
+    readonly 'frame:entity-type-add-failed': "CommandError";
     readonly 'mark:select-comment': "SelectionData";
     readonly 'mark:select-tag': "SelectionData";
     readonly 'mark:select-assessment': "SelectionData";
@@ -4999,6 +5000,54 @@ declare function getNodeEncoding(charset: string): BufferEncoding;
  */
 declare function decodeRepresentation(buffer: Buffer, mediaType: string): string;
 
+/**
+ * Common error classes — the unified Semiont error hierarchy.
+ *
+ * `SemiontError` is the base every other Semiont error class extends:
+ * `APIError` (api-client), `BusRequestError` and `SemiontSessionError` (sdk),
+ * `ValidationError`, `ScriptError`, `NotFoundError`, `UnauthorizedError`,
+ * `ConflictError` (here), and `AWSError` (cli). Subclasses tighten the
+ * `code` field to a literal-union for discriminated handling.
+ */
+/**
+ * Transport-neutral error vocabulary. Every transport that surfaces
+ * errors over `ITransport.errors$` maps its native failure modes to one
+ * of these codes — HTTP `APIError` maps from status code, in-process
+ * transports map from local failure shape, gRPC would map from status
+ * code, etc. Routing layers (e.g. `SemiontBrowser`'s session-expired /
+ * permission-denied modal routing) match on this vocabulary so they
+ * stay transport-agnostic.
+ *
+ *  - `unauthorized` — auth required / token missing or expired (HTTP 401)
+ *  - `forbidden`    — auth ok but lacks permission (HTTP 403)
+ *  - `not-found`    — resource missing (HTTP 404)
+ *  - `conflict`     — concurrent modification, duplicate, etc. (HTTP 409)
+ *  - `bad-request`  — request malformed (HTTP 400)
+ *  - `unavailable`  — backend unreachable, network error, 5xx
+ *  - `error`        — unclassified fallback
+ */
+type TransportErrorCode = 'unauthorized' | 'forbidden' | 'not-found' | 'conflict' | 'bad-request' | 'unavailable' | 'error';
+declare class SemiontError extends Error {
+    code: string;
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, details?: Record<string, unknown> | undefined);
+}
+declare class ValidationError extends SemiontError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class ScriptError extends SemiontError {
+    constructor(message: string, code?: string, details?: Record<string, unknown>);
+}
+declare class NotFoundError extends SemiontError {
+    constructor(resource: string, id?: string);
+}
+declare class UnauthorizedError extends SemiontError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+declare class ConflictError extends SemiontError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+
 /**
  * Transport interfaces — the shared contract for any wire-or-local
  * communication path consumed by `SemiontClient`. Concrete implementations
@@ -5006,16 +5055,21 @@ declare function decodeRepresentation(buffer: Buffer, mediaType: string): string
  * `@semiont/api-client`, in-process variants in `@semiont/make-meaning`,
  * etc.).
  *
- * Two interfaces:
+ * Three interfaces:
  *
- *   ITransport          — full surface: bus primitives + auth + admin +
- *                         exchange + health/status + connection state.
+ *   ITransport          — bus primitives + lifecycle. Universal: every
+ *                         concrete transport implements this.
+ *   IBackendOperations  — auth, admin, exchange, system endpoints.
+ *                         HTTP-shaped today; an in-process transport may
+ *                         implement none, some, or a different set.
+ *                         Optional on `SemiontClient` — passed only when
+ *                         the host has a backend that supports them.
  *   IContentTransport   — binary I/O (putBinary / getBinary). Narrow by
  *                         design because binary has different backpressure
  *                         and streaming characteristics.
  *
  * The behavioral guarantees every implementation must honor are documented
- * in `packages/core/docs/TRANSPORT-CONTRACT.md`.
+ * in `docs/protocol/TRANSPORT-CONTRACT.md`.
  */
 
 type Agent$1 = components['schemas']['Agent'];
@@ -5083,6 +5137,21 @@ type ProgressEvent = {
     result?: Record<string, unknown>;
 };
 type ProgressCallback = (event: ProgressEvent) => void;
+/**
+ * Stream-shaped return type for backend download operations
+ * (`backupKnowledgeBase`, `exportKnowledgeBase`). Transport-neutral —
+ * any implementation can produce a `ReadableStream<Uint8Array>` without
+ * fabricating a fetch `Response`. HTTP wraps `response.body` and
+ * `response.headers`; in-process implementations return their own stream.
+ *
+ * The same shape `IContentTransport.getBinaryStream` already uses for
+ * binary downloads.
+ */
+interface BackendDownload {
+    stream: ReadableStream<Uint8Array>;
+    contentType: string;
+    filename?: string;
+}
 interface ITransport {
     /**
      * Base URL the transport speaks to. For HTTP this is `https://host[:port]`;
@@ -5117,6 +5186,38 @@ interface ITransport {
      * an in-process transport bridges from the local actor bus.
      */
     bridgeInto(bus: EventBus): void;
+    /**
+     * 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).
+     */
+    readonly state$: Observable<ConnectionState>;
+    /**
+     * Stream of transport-level errors surfaced from typed-wire methods or
+     * other transport-mediated round-trips, just before they're thrown to
+     * the caller. Each emission is a `SemiontError` (or subclass — HTTP
+     * emits `APIError`, in-process transports emit whatever subclass is
+     * appropriate). Consumers can subscribe for global error handling
+     * (e.g. surfacing 401/403 as modals, logging) without wrapping every
+     * call site in try/catch. Distinct from bus-level errors, which are
+     * surfaced via the channel-correlation pattern in `busRequest`.
+     */
+    readonly errors$: Observable<SemiontError>;
+    dispose(): void;
+}
+/**
+ * Auth, admin, exchange, and system endpoints. HTTP-shaped today —
+ * `HttpTransport` implements both this and `ITransport`; the
+ * `SemiontClient` constructor takes a `IBackendOperations` argument
+ * separately from the bus transport so non-HTTP transports
+ * (`LocalTransport`) can implement just the bus surface and the
+ * SemiontClient cleanly omits `client.auth` / `client.admin`.
+ *
+ * Implementations should map their native error codes to
+ * `TransportErrorCode` (see `errors.ts`) so the routing layer
+ * (`SemiontBrowser`) stays transport-neutral.
+ */
+interface IBackendOperations {
     authenticatePassword(email: Email, password: string): Promise<AuthResponse>;
     authenticateGoogle(credential: GoogleCredential): Promise<AuthResponse>;
     refreshAccessToken(token: RefreshToken): Promise<TokenRefreshResponse>;
@@ -5133,21 +5234,24 @@ interface ITransport {
     getUserStats(): Promise<AdminUserStatsResponse>;
     updateUser(id: UserDID, data: UpdateUserRequest): Promise<UpdateUserResponse>;
     getOAuthConfig(): Promise<OAuthConfigResponse>;
-    backupKnowledgeBase(): Promise<Response>;
-    restoreKnowledgeBase(file: File, onProgress?: ProgressCallback): Promise<ProgressEvent>;
+    backupKnowledgeBase(): Promise<BackendDownload>;
+    /**
+     * Stream of `ProgressEvent`s for a restore/import operation. The
+     * Observable emits each progress event in order and completes when
+     * the operation is done; the final event carries `phase: 'complete'`
+     * (or `'error'` / `'failed'` followed by an Observable error).
+     *
+     * The SDK wraps the contract's `Observable<ProgressEvent>` as a
+     * `StreamObservable<ProgressEvent>` so consumers can `await` for the
+     * final event or `.subscribe(...)` to render every step.
+     */
+    restoreKnowledgeBase(file: File): Observable<ProgressEvent>;
     exportKnowledgeBase(params?: {
         includeArchived?: boolean;
-    }): Promise<Response>;
-    importKnowledgeBase(file: File, onProgress?: ProgressCallback): Promise<ProgressEvent>;
+    }): Promise<BackendDownload>;
+    importKnowledgeBase(file: File): Observable<ProgressEvent>;
     healthCheck(): Promise<HealthCheckResponse>;
     getStatus(): Promise<StatusResponse>;
-    /**
-     * 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).
-     */
-    readonly state$: Observable<ConnectionState>;
-    dispose(): void;
 }
 interface PutBinaryRequest {
     name: string;
@@ -5163,10 +5267,36 @@ interface PutBinaryRequest {
     generator?: Agent$1 | Agent$1[];
     isDraft?: boolean;
 }
+/**
+ * Optional byte-progress hook for `putBinary`. Receives raw byte counts;
+ * derived shapes (percentage, ETA) are the caller's responsibility.
+ *
+ * `totalBytes` may be 0 when the underlying transport can't determine it
+ * (chunked encoding, indeterminate streams). Consumers should render an
+ * indeterminate state in that case.
+ */
+type PutBinaryProgress = (event: {
+    bytesUploaded: number;
+    totalBytes: number;
+}) => void;
+interface PutBinaryOptions {
+    auth?: AccessToken;
+    /**
+     * Called as bytes flow over the wire. Honored by transports that can
+     * observe upload progress (HTTP via XHR). Transports that can't
+     * (in-process LocalContentTransport, current `ky`-based fetch path
+     * with no `onProgress`) simply ignore it.
+     */
+    onProgress?: PutBinaryProgress;
+    /**
+     * Signal that aborts the in-flight request. The XHR-based HTTP path
+     * calls `xhr.abort()` when the signal fires; in-process and
+     * non-XHR HTTP paths complete in the background after abort.
+     */
+    signal?: AbortSignal;
+}
 interface IContentTransport {
-    putBinary(request: PutBinaryRequest, options?: {
-        auth?: AccessToken;
-    }): Promise<{
+    putBinary(request: PutBinaryRequest, options?: PutBinaryOptions): Promise<{
         resourceId: ResourceId;
     }>;
     getBinary(resourceId: ResourceId, options?: {
@@ -5201,7 +5331,7 @@ interface IContentTransport {
  * Resource-scoped channels (joined/left via `subscribeToResource`) are
  * tracked separately by transports that care about scope (HTTP).
  */
-declare const BRIDGED_CHANNELS: readonly ["browse:resources-result", "browse:resources-failed", "browse:resource-result", "browse:resource-failed", "browse:annotations-result", "browse:annotations-failed", "browse:annotation-result", "browse:annotation-failed", "browse:annotation-history-result", "browse:annotation-history-failed", "browse:events-result", "browse:events-failed", "browse:referenced-by-result", "browse:referenced-by-failed", "browse:entity-types-result", "browse:entity-types-failed", "browse:directory-result", "browse:directory-failed", "browse:annotation-context-result", "browse:annotation-context-failed", "mark:delete-ok", "mark:delete-failed", "mark:create-ok", "mark:create-failed", "match:search-results", "match:search-failed", "gather:complete", "gather:failed", "gather:annotation-progress", "gather:annotation-finished", "gather:summary-result", "gather:summary-failed", "bind:body-updated", "bind:body-update-failed", "job:report-progress", "job:complete", "job:fail", "job:status-result", "job:status-failed", "job:created", "job:create-failed", "job:claimed", "job:claim-failed", "yield:clone-token-generated", "yield:clone-token-failed", "yield:clone-resource-result", "yield:clone-resource-failed", "yield:clone-created", "yield:clone-create-failed", "mark:entity-type-added", "beckon:focus", "beckon:sparkle", "bus:resume-gap"];
+declare const BRIDGED_CHANNELS: readonly ["browse:resources-result", "browse:resources-failed", "browse:resource-result", "browse:resource-failed", "browse:annotations-result", "browse:annotations-failed", "browse:annotation-result", "browse:annotation-failed", "browse:annotation-history-result", "browse:annotation-history-failed", "browse:events-result", "browse:events-failed", "browse:referenced-by-result", "browse:referenced-by-failed", "browse:entity-types-result", "browse:entity-types-failed", "browse:directory-result", "browse:directory-failed", "browse:annotation-context-result", "browse:annotation-context-failed", "mark:delete-ok", "mark:delete-failed", "mark:create-ok", "mark:create-failed", "match:search-results", "match:search-failed", "gather:complete", "gather:failed", "gather:annotation-progress", "gather:annotation-finished", "gather:summary-result", "gather:summary-failed", "bind:body-updated", "bind:body-update-failed", "job:report-progress", "job:complete", "job:fail", "job:status-result", "job:status-failed", "job:created", "job:create-failed", "job:claimed", "job:claim-failed", "yield:create-ok", "yield:create-failed", "yield:update-ok", "yield:update-failed", "yield:clone-token-generated", "yield:clone-token-failed", "yield:clone-resource-result", "yield:clone-resource-failed", "yield:clone-created", "yield:clone-create-failed", "frame:entity-type-added", "beckon:focus", "beckon:sparkle", "bus:resume-gap"];
 type BridgedChannel = typeof BRIDGED_CHANNELS[number];
 
 /**
@@ -5649,57 +5779,6 @@ declare function isNullish(value: unknown): value is null | undefined;
  */
 declare function isDefined<T>(value: T | null | undefined): value is T;
 
-/**
- * Common error classes
- */
-/**
- * Base error class for Semiont applications
- */
-declare class SemiontError extends Error {
-    code: string;
-    details?: Record<string, any> | undefined;
-    constructor(message: string, code: string, details?: Record<string, any> | undefined);
-}
-/**
- * Error thrown when validation fails
- */
-declare class ValidationError extends SemiontError {
-    constructor(message: string, details?: Record<string, any>);
-}
-/**
- * Error thrown by scripts
- */
-declare class ScriptError extends SemiontError {
-    constructor(message: string, code?: string, details?: Record<string, any>);
-}
-/**
- * Error thrown when a resource is not found
- */
-declare class NotFoundError extends SemiontError {
-    constructor(resource: string, id?: string);
-}
-/**
- * Error thrown when user is not authorized
- */
-declare class UnauthorizedError extends SemiontError {
-    constructor(message?: string, details?: Record<string, any>);
-}
-/**
- * Error thrown when operation would conflict with existing data
- */
-declare class ConflictError extends SemiontError {
-    constructor(message: string, details?: Record<string, any>);
-}
-/**
- * API Error class for handling HTTP errors
- * Used by API clients to represent failed HTTP requests
- */
-declare class APIError extends Error {
-    status: number;
-    data: any;
-    constructor(status: number, data: any, message?: string);
-}
-
 /**
  * DID (Decentralized Identifier) and W3C Agent utilities
  *
@@ -5885,4 +5964,4 @@ declare function getAllPlatformTypes(): PlatformType[];
 declare const CORE_TYPES_VERSION = "0.1.0";
 declare const SDK_VERSION = "0.1.0";
 
-export { APIError, type AccessToken, type Annotation, type AnnotationCategory, type AnnotationId, type AnnotationUri, type AssembledAnnotation, type AuthCode, BRIDGED_CHANNELS, type BaseUrl, type BodyItem, type BodyItemIdentity, type BodyOperation, type BoundingBox, type Brand, type BridgedChannel, type BurstBufferOptions, type BusOp, CHANNEL_SCHEMAS, CORE_TYPES_VERSION, CREATION_METHODS, type CloneToken, ConfigurationError, ConflictError, type ConnectionState, type ContentCache, type ContentFormat, type CreateAnnotationInternal, type CreationMethod, type Email, type EmittableChannel, type EntityType, type EntityTypeStats, type Environment, EnvironmentConfig, type EventBase, EventBus, type EventInput, type EventMap, type EventMetadata, type EventName, type EventOfType, type EventQuery, type EventSignature, type FragmentSelector, type GatheredContext, type GoogleAuthRequest, type GoogleCredential, type GraphConnection, type GraphPath, type HealthCheckResponse, type IContentTransport, type ITransport, JWTTokenSchema, type JobId, LOCALES, type ListUsersResponse, type LocaleInfo, type Logger, type MCPToken, type MatchQuality, type MimeCategory, type Motivation, NotFoundError, PERSISTED_EVENT_TYPES, type PersistedEvent, type PersistedEventType, type PlatformType, type Point, type ProgressCallback, type ProgressEvent, type PutBinaryRequest, RESOURCE_BROADCAST_TYPES, type RefreshToken, type ResourceAnnotationUri, type ResourceAnnotations, type ResourceBroadcastType, type ResourceDescriptor, type ResourceFilter, type ResourceId, type ResourceUri, SDK_VERSION, ScopedEventBus, ScriptError, type SearchQuery, type SelectionData, type Selector, SemiontError, type StatusResponse, type StoredEvent, type StoredEventLike, type SvgSelector, type TextPosition, type TextPositionSelector, type TextQuoteSelector, type ActorInferenceConfig as TomlActorInferenceConfig, type TomlFileReader, type InferenceConfig as TomlInferenceConfig, type WorkerInferenceConfig as TomlWorkerInferenceConfig, UnauthorizedError, type UpdateResourceInput, type UpdateUserRequest, type UpdateUserResponse, type UserDID, type UserId, type UserResponse, type ValidatedAnnotation, ValidationError, type ValidationFailure, type ValidationResult, type ValidationSuccess, accessToken, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseUrl, buildContentCache, burstBuffer, busLog, busLogEnabled, cloneToken, type components, createCircleSvg, createPolygonSvg, createRectangleSvg, createTomlConfigLoader, decodeRepresentation, decodeWithCharset, didToAgent, email, entityType, errField, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findBodyItem, findTextWithContext, formatLocaleDisplay, generateUuid, getAllLocaleCodes, getAllPlatformTypes, getAnnotationExactText, getAnnotationUriFromEvent, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getExtensionForMimeType, getFragmentSelector, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getMimeCategory, getNodeEncoding, 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, isImageMimeType, isNull, isNullish, isNumber, isObject, isPdfMimeType, isReference, isResolvedReference, isResourceId, isStoredEvent, isString, isStubReference, isTag, isTextMimeType, isUndefined, isValidEmail, isValidPlatformType, jobId, loadTomlConfig, mcpToken, normalizeCoordinates, normalizeText, type operations, parseEnvironment, parseSvgSelector, type paths, refreshToken, resourceAnnotationUri, resourceId, resourceUri, scaleSvgToNative, searchQuery, serializePerKey, setBusLogTraceIdProvider, userDID, userId, userToAgent, userToDid, validateAndCorrectOffsets, validateData, validateEnvironment, validateSvgMarkup, verifyPosition };
+export { type AccessToken, type Annotation, type AnnotationCategory, type AnnotationId, type AnnotationUri, type AssembledAnnotation, type AuthCode, BRIDGED_CHANNELS, type BackendDownload, type BaseUrl, type BodyItem, type BodyItemIdentity, type BodyOperation, type BoundingBox, type Brand, type BridgedChannel, type BurstBufferOptions, type BusOp, CHANNEL_SCHEMAS, CORE_TYPES_VERSION, CREATION_METHODS, type CloneToken, ConfigurationError, ConflictError, type ConnectionState, type ContentCache, type ContentFormat, type CreateAnnotationInternal, type CreationMethod, type Email, type EmittableChannel, type EntityType, type EntityTypeStats, type Environment, EnvironmentConfig, type EventBase, EventBus, type EventInput, type EventMap, type EventMetadata, type EventName, type EventOfType, type EventQuery, type EventSignature, type FragmentSelector, type GatheredContext, type GoogleAuthRequest, type GoogleCredential, type GraphConnection, type GraphPath, type HealthCheckResponse, type IBackendOperations, type IContentTransport, type ITransport, JWTTokenSchema, type JobId, LOCALES, type ListUsersResponse, type LocaleInfo, type Logger, type MCPToken, type MatchQuality, type MimeCategory, type Motivation, NotFoundError, PERSISTED_EVENT_TYPES, type PersistedEvent, type PersistedEventType, type PlatformType, type Point, type ProgressCallback, type ProgressEvent, type PutBinaryOptions, type PutBinaryProgress, type PutBinaryRequest, RESOURCE_BROADCAST_TYPES, type RefreshToken, type ResourceAnnotationUri, type ResourceAnnotations, type ResourceBroadcastType, type ResourceDescriptor, type ResourceFilter, type ResourceId, type ResourceUri, SDK_VERSION, ScopedEventBus, ScriptError, type SearchQuery, type SelectionData, type Selector, SemiontError, type StatusResponse, type StoredEvent, type StoredEventLike, type SvgSelector, type TextPosition, type TextPositionSelector, type TextQuoteSelector, type ActorInferenceConfig as TomlActorInferenceConfig, type TomlFileReader, type InferenceConfig as TomlInferenceConfig, type WorkerInferenceConfig as TomlWorkerInferenceConfig, type TransportErrorCode, UnauthorizedError, type UpdateResourceInput, type UpdateUserRequest, type UpdateUserResponse, type UserDID, type UserId, type UserResponse, type ValidatedAnnotation, ValidationError, type ValidationFailure, type ValidationResult, type ValidationSuccess, accessToken, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseUrl, buildContentCache, burstBuffer, busLog, busLogEnabled, cloneToken, type components, createCircleSvg, createPolygonSvg, createRectangleSvg, createTomlConfigLoader, decodeRepresentation, decodeWithCharset, didToAgent, email, entityType, errField, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findBodyItem, findTextWithContext, formatLocaleDisplay, generateUuid, getAllLocaleCodes, getAllPlatformTypes, getAnnotationExactText, getAnnotationUriFromEvent, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getExtensionForMimeType, getFragmentSelector, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getMimeCategory, getNodeEncoding, 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, isImageMimeType, isNull, isNullish, isNumber, isObject, isPdfMimeType, isReference, isResolvedReference, isResourceId, isStoredEvent, isString, isStubReference, isTag, isTextMimeType, isUndefined, isValidEmail, isValidPlatformType, jobId, loadTomlConfig, mcpToken, normalizeCoordinates, normalizeText, type operations, parseEnvironment, parseSvgSelector, type paths, refreshToken, resourceAnnotationUri, resourceId, resourceUri, scaleSvgToNative, searchQuery, serializePerKey, setBusLogTraceIdProvider, userDID, userId, userToAgent, userToDid, validateAndCorrectOffsets, validateData, validateEnvironment, validateSvgMarkup, verifyPosition };

package/dist/index.js

@@ -109,7 +109,7 @@ var PERSISTED_EVENT_TYPES = [
   "mark:unarchived",
   "mark:entity-tag-added",
   "mark:entity-tag-removed",
-  "mark:entity-type-added",
+  "frame:entity-type-added",
   "job:started",
   "job:progress",
   "job:completed",
@@ -169,7 +169,7 @@ var CHANNEL_SCHEMAS = {
   "mark:body-updated": null,
   "mark:entity-tag-added": null,
   "mark:entity-tag-removed": null,
-  "mark:entity-type-added": null,
+  "frame:entity-type-added": null,
   "mark:archived": null,
   "mark:unarchived": null,
   "mark:create-request": "MarkCreateRequest",
@@ -179,13 +179,13 @@ var CHANNEL_SCHEMAS = {
   "mark:archive": "MarkArchiveCommand",
   "mark:unarchive": "MarkUnarchiveCommand",
   "mark:update-entity-types": "MarkUpdateEntityTypesCommand",
-  "mark:add-entity-type": "MarkAddEntityTypeCommand",
+  "frame:add-entity-type": "FrameAddEntityTypeCommand",
   "mark:create-ok": "MarkCreateOk",
   "mark:create-failed": "CommandError",
   "mark:delete-ok": "MarkDeleteOk",
   "mark:delete-failed": "CommandError",
   "mark:body-update-failed": "CommandError",
-  "mark:entity-type-add-failed": "CommandError",
+  "frame:entity-type-add-failed": "CommandError",
   "mark:select-comment": "SelectionData",
   "mark:select-tag": "SelectionData",
   "mark:select-assessment": "SelectionData",
@@ -349,6 +349,34 @@ function isEventRelatedToAnnotation(event, annotationUri2) {
 function isStoredEvent(event) {
   return event && typeof event.id === "string" && typeof event.timestamp === "string" && typeof event.type === "string" && typeof event.metadata === "object" && typeof event.metadata.sequenceNumber === "number";
 }
+
+// src/bus-log.ts
+var NODE_BUS_LOG = typeof process !== "undefined" && !!process.env?.SEMIONT_BUS_LOG;
+function busLogEnabled() {
+  const g = globalThis;
+  if (g.__SEMIONT_BUS_LOG__) return true;
+  return NODE_BUS_LOG;
+}
+var traceIdProvider;
+function setBusLogTraceIdProvider(fn) {
+  traceIdProvider = fn;
+}
+function busLog(op, channel, payload, scope) {
+  if (!busLogEnabled()) return;
+  const cidRaw = payload?.correlationId;
+  const cid = typeof cidRaw === "string" ? cidRaw.slice(0, 8) : void 0;
+  let traceId;
+  if (traceIdProvider) {
+    try {
+      traceId = traceIdProvider();
+    } catch {
+    }
+  }
+  const tag = `[bus ${op}] ${channel}` + (scope ? ` scope=${scope}` : "") + (cid ? ` cid=${cid}` : "") + (traceId ? ` trace=${traceId.slice(0, 8)}` : "");
+  console.debug(tag, payload);
+}
+
+// src/event-bus.ts
 var EventBus = class {
   subjects;
   isDestroyed;
@@ -384,7 +412,15 @@ var EventBus = class {
       throw new Error(`Cannot access event '${String(eventName)}' on destroyed bus`);
     }
     if (!this.subjects.has(eventName)) {
-      this.subjects.set(eventName, new Subject());
+      const subject = new Subject();
+      if (busLogEnabled()) {
+        const originalNext = subject.next.bind(subject);
+        subject.next = (value) => {
+          busLog("EMIT", String(eventName), value);
+          originalNext(value);
+        };
+      }
+      this.subjects.set(eventName, subject);
     }
     return this.subjects.get(eventName);
   }
@@ -592,32 +628,6 @@ function errField(error) {
   return error;
 }
 
-// src/bus-log.ts
-var NODE_BUS_LOG = typeof process !== "undefined" && !!process.env?.SEMIONT_BUS_LOG;
-function busLogEnabled() {
-  const g = globalThis;
-  if (g.__SEMIONT_BUS_LOG__) return true;
-  return NODE_BUS_LOG;
-}
-var traceIdProvider;
-function setBusLogTraceIdProvider(fn) {
-  traceIdProvider = fn;
-}
-function busLog(op, channel, payload, scope) {
-  if (!busLogEnabled()) return;
-  const cidRaw = payload?.correlationId;
-  const cid = typeof cidRaw === "string" ? cidRaw.slice(0, 8) : void 0;
-  let traceId;
-  if (traceIdProvider) {
-    try {
-      traceId = traceIdProvider();
-    } catch {
-    }
-  }
-  const tag = `[bus ${op}] ${channel}` + (scope ? ` scope=${scope}` : "") + (cid ? ` cid=${cid}` : "") + (traceId ? ` trace=${traceId.slice(0, 8)}` : "");
-  console.debug(tag, payload);
-}
-
 // src/annotation-utils.ts
 function findBodyItem(body, identity) {
   if (!Array.isArray(body)) {
@@ -1016,13 +1026,17 @@ var BRIDGED_CHANNELS = [
   "job:create-failed",
   "job:claimed",
   "job:claim-failed",
+  "yield:create-ok",
+  "yield:create-failed",
+  "yield:update-ok",
+  "yield:update-failed",
   "yield:clone-token-generated",
   "yield:clone-token-failed",
   "yield:clone-resource-result",
   "yield:clone-resource-failed",
   "yield:clone-created",
   "yield:clone-create-failed",
-  "mark:entity-type-added",
+  "frame:entity-type-added",
   "beckon:focus",
   "beckon:sparkle",
   "bus:resume-gap"
@@ -1555,15 +1569,6 @@ var ConflictError = class extends SemiontError {
     this.name = "ConflictError";
   }
 };
-var APIError = class extends Error {
-  constructor(status, data, message) {
-    super(message || `API Error: ${status}`);
-    this.status = status;
-    this.data = data;
-    this.name = "APIError";
-    Error.captureStackTrace(this, this.constructor);
-  }
-};
 
 // src/did-utils.ts
 function userToDid(user) {
@@ -1929,6 +1934,6 @@ function getAllPlatformTypes() {
 var CORE_TYPES_VERSION = "0.1.0";
 var SDK_VERSION = "0.1.0";
 
-export { APIError, BRIDGED_CHANNELS, CHANNEL_SCHEMAS, CORE_TYPES_VERSION, CREATION_METHODS, ConfigurationError, ConflictError, EventBus, JWTTokenSchema, LOCALES, NotFoundError, PERSISTED_EVENT_TYPES, RESOURCE_BROADCAST_TYPES, SDK_VERSION, ScopedEventBus, ScriptError, SemiontError, UnauthorizedError, ValidationError, accessToken, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseUrl, buildContentCache, burstBuffer, busLog, busLogEnabled, cloneToken, createCircleSvg, createPolygonSvg, createRectangleSvg, createTomlConfigLoader, decodeRepresentation, decodeWithCharset, didToAgent, email, entityType, errField, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findBodyItem, findTextWithContext, formatLocaleDisplay, generateUuid, getAllLocaleCodes, getAllPlatformTypes, getAnnotationExactText, getAnnotationUriFromEvent, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getExtensionForMimeType, getFragmentSelector, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getMimeCategory, getNodeEncoding, 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, isImageMimeType, isNull, isNullish, isNumber, isObject, isPdfMimeType, isReference, isResolvedReference, isResourceId, isStoredEvent, isString, isStubReference, isTag, isTextMimeType, isUndefined, isValidEmail, isValidPlatformType, jobId, loadTomlConfig, mcpToken, normalizeCoordinates, normalizeText, parseEnvironment, parseSvgSelector, refreshToken, resourceAnnotationUri, resourceId, resourceUri, scaleSvgToNative, searchQuery, serializePerKey, setBusLogTraceIdProvider, userDID, userId, userToAgent, userToDid, validateAndCorrectOffsets, validateData, validateEnvironment, validateSvgMarkup, verifyPosition };
+export { BRIDGED_CHANNELS, CHANNEL_SCHEMAS, CORE_TYPES_VERSION, CREATION_METHODS, ConfigurationError, ConflictError, EventBus, JWTTokenSchema, LOCALES, NotFoundError, PERSISTED_EVENT_TYPES, RESOURCE_BROADCAST_TYPES, SDK_VERSION, ScopedEventBus, ScriptError, SemiontError, UnauthorizedError, ValidationError, accessToken, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseUrl, buildContentCache, burstBuffer, busLog, busLogEnabled, cloneToken, createCircleSvg, createPolygonSvg, createRectangleSvg, createTomlConfigLoader, decodeRepresentation, decodeWithCharset, didToAgent, email, entityType, errField, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findBodyItem, findTextWithContext, formatLocaleDisplay, generateUuid, getAllLocaleCodes, getAllPlatformTypes, getAnnotationExactText, getAnnotationUriFromEvent, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getExtensionForMimeType, getFragmentSelector, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getMimeCategory, getNodeEncoding, 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, isImageMimeType, isNull, isNullish, isNumber, isObject, isPdfMimeType, isReference, isResolvedReference, isResourceId, isStoredEvent, isString, isStubReference, isTag, isTextMimeType, isUndefined, isValidEmail, isValidPlatformType, jobId, loadTomlConfig, mcpToken, normalizeCoordinates, normalizeText, parseEnvironment, parseSvgSelector, refreshToken, resourceAnnotationUri, resourceId, resourceUri, scaleSvgToNative, searchQuery, serializePerKey, setBusLogTraceIdProvider, userDID, userId, userToAgent, userToDid, validateAndCorrectOffsets, validateData, validateEnvironment, validateSvgMarkup, verifyPosition };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map